Gatsby Development CLI

5.16.0 · active · verified Wed Apr 22

`gatsby-dev-cli` is a command-line interface tool specifically designed to assist contributors in the local development and testing of the Gatsby core framework. Its primary function is to enable developers to link a local clone of the Gatsby monorepo to a Gatsby site, allowing changes made to Gatsby packages to be copied directly into the site's `node_modules` for immediate, real-time testing. After the initial copy, the tool can maintain a watch task to automatically re-copy any changed modules, streamlining the iterative development process. The current stable version is 5.16.0. Gatsby generally follows a continuous release cadence for minor fixes and features within a major version, with major versions released less frequently. This CLI's key differentiation lies in its ability to facilitate rapid iteration on Gatsby core features directly within a consuming project, bypassing the complexities of manual `npm link` or copying. It is an essential utility for anyone contributing to the Gatsby project itself.

Common errors

```
error glob@11.0.3: The engine "node" is incompatible with this module. Expected version "20 || >=22". Got "18.6.0"
```
cause This error indicates a transitive dependency (often `glob` or `devcert` within `gatsby-dev-cli`) has updated its Node.js engine requirements, causing incompatibility with older Node.js 18 releases.

fix Upgrade your Node.js environment. While Node.js 18 is supported, specific older patch versions like 18.6.0 may exhibit this issue. Update to Node.js 18.19.1 (LTS) or higher, or move to Node.js 20, 22, or 24.
```
Gatsby site is not rebuilding or reflecting changes made to the local Gatsby monorepo when `gatsby-dev` is running.
```
cause This usually happens because the Gatsby source code itself isn't being watched and rebuilt. `gatsby-dev-cli` only copies *already built* changes.

fix Ensure you are running `npm run watch` (or `yarn watch`) in a separate terminal within your cloned Gatsby monorepo directory. This command builds the Gatsby source and keeps it updated, allowing `gatsby-dev` to pick up the changes.

Warnings

breaking Node.js 16 is no longer supported. The `gatsby-dev-cli` package, like Gatsby itself, requires Node.js versions >=18.0.0 and <26.
Fix: Upgrade your Node.js environment to a supported version, such as Node.js 18, 20, 22, or 24.
gotcha Running `gatsby-dev` modifies your project's `node_modules` directory and potentially `package.json` to point to local Gatsby packages. These changes are not automatically undone.
Fix: To revert to officially published package versions, you must manually undo the changes. The recommended way is `git checkout package.json; npm install --force` (or `yarn --force` for Yarn users).
gotcha For a complete and reactive development workflow, `gatsby-dev-cli` typically needs to be run in conjunction with `npm run watch` (or `yarn watch`) executed within the Gatsby monorepo itself. This ensures that changes made to Gatsby source code are built and reflected by `gatsby-dev`.
Fix: After starting `gatsby-dev` in your project, open a separate terminal, navigate to your cloned Gatsby monorepo, and run `npm run watch`.

Install

npm install gatsby-dev-cli npm
yarn add gatsby-dev-cli yarn
pnpm add gatsby-dev-cli pnpm

Imports

gatsby-dev
```
gatsby-dev
```
Primary command-line executable to link and watch Gatsby core changes in a local Gatsby project.
gatsby-dev --set-path-to-repo
```
gatsby-dev --set-path-to-repo /path/to/my/cloned/version/gatsby
```
Used for initial, one-time configuration to specify the absolute path to your local Gatsby monorepo clone.
gatsby-dev --packages
```
gatsby-dev --packages gatsby gatsby-transformer-remark
```
Allows specifying a subset of Gatsby packages to link, overriding the automatic dependency scanning behavior.

Quickstart

Demonstrates global installation, initial repository configuration, linking a local Gatsby project, and how to revert changes.

npm install -g gatsby-dev-cli

# Configure the path to your cloned Gatsby repository (one-time setup)
gatsby-dev --set-path-to-repo ~/projects/gatsby-monorepo

# Navigate to your Gatsby project and link it to your local Gatsby core
cd my-gatsby-project
gatsby-dev

# (Optional, but recommended in a separate terminal while 'gatsby-dev' is running)
# Build and watch Gatsby source code in your Gatsby monorepo
# cd ~/projects/gatsby-monorepo
# npm run watch

# To revert changes made by gatsby-dev and restore official packages
# git checkout package.json; npm install --force

view raw JSON →