gatsby-dev-cli

library5.16.0jsnpmunverified

`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.

devops web-framework

npm install gatsby-dev-cli

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GATSBY-DEV-CLI

gatsby-dev-cli

devopsjavascriptv5.16.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

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.

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

gatsby-dev --version

Debug

Known issues

breakingNode.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.

affects: >=5.0.0

gotchaRunning `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).

affects: >=1.0.0

gotchaFor 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`.

affects: >=1.0.0

Errors

Common errors & fixes

error glob@11.0.3: The engine "node" is incompatible with this module. Expected version "20 || >=22". Got "18.6.0"

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.

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.

Upgrade

Version history

5.16.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/gatsbyjs/gatsby ↗

packagehttps://www.npmjs.com/package/gatsby-dev-cli ↗

homepagehttps://www.gatsbyjs.com ↗