Restarting a Gatsby Development Environment

This article preserves a workflow from the Gatsby version of maluk.tech. The current site uses Next.js, but the underlying lesson—make development resets explicit and repeatable—still applies.

The original problem

After changing Gatsby configuration or the shape of Markdown data, the development server needed a restart so GraphQL could rebuild its schema. A previous process sometimes kept port 8000 busy, and Gatsby offered to start on 8001, then 8002, and so on.

That workaround created a new problem: browser and CMS tabs still pointed to the old port. Repeated restarts left several nearly identical tabs and made the active environment unclear.

Diagnose before killing a process

First identify what is listening on the port:

lsof -nP -iTCP:8000 -sTCP:LISTEN

If it is the stale development process you expect, ask it to stop gracefully:

kill <PID>

Use a forced stop only when the process does not respond:

kill -9 <PID>

Do not kill an unknown process simply because it owns the desired port.

Automate the legacy Gatsby reset

The original project used kill-port to reclaim port 8000 and nodemon to restart Gatsby when its configuration changed:

npm install --save-dev nodemon kill-port

The script also cleared Gatsby’s generated cache before starting the server:

{
  "scripts": {
    "dev": "nodemon --exec 'kill-port 8000 && gatsby clean && gatsby develop' --watch gatsby-node.js --watch package.json --watch gatsby-config.js"
  }
}

Then the same command always started the development environment:

npm run dev

What to keep from this solution

The exact Gatsby tooling is historical. The reusable engineering principle is current:

1. diagnose the occupied resource;
2. stop only the process you own;
3. clear generated state only when configuration or schemas require it;
4. encode the recovery sequence in the project scripts;
5. use one predictable command for the team.

Automation is valuable when it makes state visible and repeatable. It is dangerous when it hides a broad kill or cleanup command behind a convenient script, so keep the target narrow and documented.