Tutorial
Gatsby CLI Quick Reference
Introduction
When working with Gatsby.js, we constantly make use of its built-in command line interface (CLI.) This essential tool allows us to do things like creating new projects from starters, launching a dev server with hot-reloading, and generating production builds. Here’s a quick reference guide to help you use it.
Installation
If you haven’t already performed a global installation of gatsby-cli
, you will need to do that first:
- npm install -g gatsby-cli
With gatsby-cli
installed globally, you can now run all of Gatsby’s commands from anywhere on your machine. Now let’s cover the available commands!
Create a New Project
The new
command creates a new Gatsby site, installs all of its dependencies, and initializes a new git repository locally with an initial commit.
Running the command with no arguments will prompt for a folder name and optional starter:
- gatsby new
Available Arguments:
-
site directory
: Optional, specifies the installation directory. -
starter
: Optional, this can either be a repo URL or a Github username/repo string. If this is not set, gatsby-starter-default is automatically used.
Here’s an example that installs into a my-site
folder, and uses gatsby-starter-blog as the starter:
- gatsby new my-site gatsbyjs/gatsby-starter-blog
Local Development Server
The develop
command starts up a local development server with hot-reloading.
- gatsby develop
Available Options:
-
-H, --host
: Set host URL/IP. Defaults tolocalhost
. -
-p, --port
: Set application port. Defaults to8000
. -
-o, --open
: Automatically opens the site in your (default) browser. -
-S, --https
: Use HTTPS. (More info on that can be found here.)
Here’s an additional example that runs at http://0.0.0.0:8888
and automatically opens in a browser:
- gatsby develop -H 0.0.0.0 -p 8888 -o
Generate Production Builds
The build
command compiles your site for production-ready deployments.
- gatsby build
Available Options:
-
-prefix-paths
: Builds the site with link paths prefixed. (But only if you’ve setpathPrefix
in your Gatsby config!) -
-no-uglify
: Builds the site without uglifying JavaScript (Useful for debugging.) -
-open-tracing-config-file
: Sets the tracer configuration file for an OpenTracing tool. (More info at Gatsby’s Performance Tracing page.)
Here’s an example that generates a build with prefixed paths and uglify disabled:
- gatsby build -prefix-paths -no-uglify
Serve Production Builds Locally
The serve
command runs production builds locally, which can be helpful for testing and debugging. (You must run the build
command prior to running this, of course.)
- gatsby serve
Available Options:
-
-H, --host
: Set host address. Defaults tolocalhost
. -
-p, --port
: Set application port. Defaults to9000
. -
-o, --open
: Automatically opens the site in your (default) browser. -
-prefix-paths
: Serves the site with prefixed paths, if you set apathPrefix
value in your Gatsby config.
Here’s an an example that serves a production build at http://10.0.0.1:9999
with prefixed paths, and automatically opens in a browser:
- gatsby serve -H 10.0.0.1 -p 9999 -prefix-paths -o
Get Environment Info
The info
command displays environment information about your Gatsby project.
- gatsby info
Available Option:
-
-C, --clipboard
: Automatically copies the info to your clipboard.
Running this command returns an object including your OS, CPU type, Yarn/npm versions, installed languages, browsers, and installed npm packages.
NOTE: This info is required when submitting an official bug report to Gatsby.
Remove Stale Caches/Builds
The clean
command deletes the .cache
and public
directories from your project root.
- gatsby clean
While this command is probably not something you will use too often, it’s still a handy shortcut to know about! Sometimes strange caching issues happen, and this is a fast and safe way to clear it. (It’s easier to type two words vs. typing out two folder deletion commands, and there’s no risk of accidentally deleting the wrong folder.)
REPL Access
The repl
command opens access to Gatsby’s interactive REPL (Read-Eval-Print-Loop) shell.
- gatsby repl
The use of this command is far beyond the scope of a quick reference article, but you can find full usage details in the Gatsby documentation’s REPL page.
Conclusion
Hopefully this short guide will help you navigate the Gatsby CLI with ease. It’s important to be comfortable with it, since you will use it so frequently in your Gatsby projects!
More information is also available, if needed:
- The Gatsby CLI page in the official documentation is great!
- The Github repo for
gatsby-cli
is useful to keep up with updates/changes. - The Gatsby team also created a printable cheat sheet, which includes the most-used CLI commands.