{"id":17007,"library":"gatsby-dev-cli","title":"Gatsby Development CLI","description":"`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.","status":"active","version":"5.16.0","language":"javascript","source_language":"en","source_url":"https://github.com/gatsbyjs/gatsby","tags":["javascript","gatsby"],"install":[{"cmd":"npm install gatsby-dev-cli","lang":"bash","label":"npm"},{"cmd":"yarn add gatsby-dev-cli","lang":"bash","label":"yarn"},{"cmd":"pnpm add gatsby-dev-cli","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Primary command-line executable to link and watch Gatsby core changes in a local Gatsby project.","symbol":"gatsby-dev","correct":"gatsby-dev"},{"note":"Used for initial, one-time configuration to specify the absolute path to your local Gatsby monorepo clone.","symbol":"gatsby-dev --set-path-to-repo","correct":"gatsby-dev --set-path-to-repo /path/to/my/cloned/version/gatsby"},{"note":"Allows specifying a subset of Gatsby packages to link, overriding the automatic dependency scanning behavior.","symbol":"gatsby-dev --packages","correct":"gatsby-dev --packages gatsby gatsby-transformer-remark"}],"quickstart":{"code":"npm install -g gatsby-dev-cli\n\n# Configure the path to your cloned Gatsby repository (one-time setup)\ngatsby-dev --set-path-to-repo ~/projects/gatsby-monorepo\n\n# Navigate to your Gatsby project and link it to your local Gatsby core\ncd my-gatsby-project\ngatsby-dev\n\n# (Optional, but recommended in a separate terminal while 'gatsby-dev' is running)\n# Build and watch Gatsby source code in your Gatsby monorepo\n# cd ~/projects/gatsby-monorepo\n# npm run watch\n\n# To revert changes made by gatsby-dev and restore official packages\n# git checkout package.json; npm install --force","lang":"bash","description":"Demonstrates global installation, initial repository configuration, linking a local Gatsby project, and how to revert changes."},"warnings":[{"fix":"Upgrade your Node.js environment to a supported version, such as Node.js 18, 20, 22, or 24.","message":"Node.js 16 is no longer supported. The `gatsby-dev-cli` package, like Gatsby itself, requires Node.js versions >=18.0.0 and <26.","severity":"breaking","affected_versions":">=5.0.0"},{"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).","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"After starting `gatsby-dev` in your project, open a separate terminal, navigate to your cloned Gatsby monorepo, and run `npm run watch`.","message":"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`.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","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.","error":"error glob@11.0.3: The engine \"node\" is incompatible with this module. Expected version \"20 || >=22\". Got \"18.6.0\""},{"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.","cause":"This usually happens because the Gatsby source code itself isn't being watched and rebuilt. `gatsby-dev-cli` only copies *already built* changes.","error":"Gatsby site is not rebuilding or reflecting changes made to the local Gatsby monorepo when `gatsby-dev` is running."}],"ecosystem":"npm","meta_description":null}