The Gatsby command-line interface is the primary means of setting up, developing, and running a Gatsby application, including within a local development server and performing production builds.
First, install the global executable:
$
npm
install
-g
gatsby-cli
Execute gatsby --help
for a full list of available commands and options.
Here’s a quick rundown of the commands you’ll use most often, covered in more detail in “Gatsby CLI Commands”:
gatsby new my-gatsby-site-name
gatsby develop
Start the Gatsby development server, optionally with the following flags:
-H
, --host
Set the host. Defaults to localhost
.
-p
, --port
Set the port. Defaults to 8000
.
-o
, --open
Open the site in the default browser.
-S
, --https
Use HTTPS.
gatsby build
Compile your application and prepare it for deployment, optionally with the following flags:
--prefix-paths
Build the site with link paths prefixed (after setting pathPrefix
in gatsby-config.js).
--no-uglify
Build the site without uglifying JavaScript bundles (for debugging).
--open-tracing-config-file
Enable use of an OpenTracing-compatible configuration file.
gatsby serve
Serve the production build for testing, optionally with the following flags:
-H
, --host
Set host. Defaults to localhost
.
-p
, --port
Set port. Defaults to 9000
.
-o
, --open
Open the site in the default browser.
--prefix-paths
Serve the site with link paths prefixed (if built with pathPrefix
as set in gatsby-config.js).
gatsby info
Get helpful environment information that is useful for reporting issues at https://github.com/gatsbyjs/gatsby/issues. This command takes one optional argument:
-C
, --clipboard
Automatically copy environment information to the clipboard.
gatsby clean
Create a new Gatsby site using the blog starter as follows:
$ gatsby new my-gatsby-blog-name https://github.com/gatsbyjs/gatsby-starter-blog
Change directories into your new site’s directory and start it:
$ cd my-gatsby-blog-name $ gatsby develop
Your site is now running at https://localhost:8000, and you can experiment with querying your data at https://localhost:8000/___graphql . See more information at https://gatsby.dev/tutorial.
See all the Gatsby starters at https://gatsby.dev/starters.
Each of these files should be found at the root of your Gatsby project:
You can find more information at https://gatsby.dev/projects.
Table A-1 provides a quick reference to the most commonly used Gatsby documentation pages.
Documentation page | Shortlink |
---|---|
Gatsby documentation | https://gatsby.dev/docs |
Gatsby on GitHub | https://github.com/gatsbyjs/gatsby |
Gatsby tutorial | https://gatsby.dev/tutorial |
Gatsby Quick Start (for intermediate and advanced developers) | https://gatsby.dev/quick-start |
Gatsby Starter Library | https://gatsby.dev/starters |
Gatsby Plugin Library | https://gatsbyjs.com/plugins |
Gatsby How-to Guides | https://gatsby.dev/recipes |
Importing assets | https://gatsby.dev/image |
Gatsby Node APIs | https://gatsby.dev/api |
GraphQL Concepts | https://gatsby.dev/graphql |
Deploying and Hosting | https://gatsby.dev/deploy |
Gatsby Link API | https://gatsby.dev/link |
Querying Data in Components Using Static Query | https://gatsby.dev/static-query |
How to Contribute | https://gatsby.dev/contribute |
The following is a comprehensive list of the commands available in the Gatsby CLI.
The gatsby new
command without any arguments will run an interactive shell that will ask a series of questions and create a Gatsby site on your behalf:
$ gatsby new What would you like to name the folder where your site will be created? my-gatsby-site Will you be using a CMS? (single choice) No (or I'll add it later) – WordPress Contentful Sanity DatoCMS Shopify Would you like to install a styling system? (single choice) No (or I'll add it later) – CSS Modules/PostCSS styled-components Emotion Sass Theme UI Would you like to install additional features with other plugins? (multiple choice) ◯ Add the Google Analytics tracking script ◯ Add responsive images ◯ Add page meta tags with React Helmet ◯ Add an automatic sitemap ◯ Enable offline functionality ◯ Generate a manifest file ◯ Add Markdown support (without MDX) ◯ Add Markdown and MDX support
Alternatively, you can create a Gatsby site based on a starter by providing one or two arguments, which will not prompt you to configure a custom setup:
$ gatsby new [site-name [starter-url]]
The gatsby new
command accepts two arguments:
site-name
starter-url
gatsby-starter-default
The site-name
argument can only consist of alphanumeric characters. Specifying .
, ./
, or using a space in the name will trigger an error.
After installing a Gatsby site, you can navigate to the root directory of your project and launch a local development server by running:
$
gatsby
develop
The gatsby develop
command accepts the options listed in Table A-2.
Option | Description |
---|---|
-H , --host |
Set host. Defaults to localhost . |
-p , --port |
Set port. Defaults to env.PORT or 8000 . |
-o , --open |
Open the site in the system’s default browser. |
-S , --https |
Use HTTPS. |
--inspect |
Open a port for debugging. |
For more information about how to set up a local HTTPS development server, consult the Gatsby documentation’s guide to using local HTTPS.
You can also use the gatsby develop
command to preview changes on other devices by using the host option to permit access to the development environment on other devices sharing the same network. To do this, execute:
$ gatsby develop -H 0.0.0.0
The terminal will track changes as normal but will also print a URL that you can navigate to on another device (such as a phone or tablet) to see those changes, as long as that client is located on the same network:
You can now view gatsbyjs.com in the browser. ⠀ Local: http://0.0.0.0:8000/ On Your Network: http://192.168.0.212:8000/
In this scenario you can still access the local development server as usual, meaning you can access it through https://localhost:8000 or the URL provided next to “On Your Network.”
To compile your Gatsby application and ready it for deployment, execute the following in the root of your Gatsby project:
$
gatsby
build
The gatsby build
command accepts the options listed in Table A-3.
Option | Description |
---|---|
--prefix-paths |
Build the site with all link paths prefixed (after setting pathPrefix in your Gatsby configuration). |
--no-uglify |
Build the site without uglifying JavaScript bundles (for debugging purposes). |
--profile |
Build the site with React profiling. |
--open-tracing-config-file |
Enable use of an OpenTracing-compatible tracer configuration file. |
--graphql-tracing |
Enable tracing of every graphql resolver (may impact performance). |
--no-color , --no-colors |
Disable color-coded terminal output. |
In addition to the --no-color/--no-colors
option, the Gatsby CLI also respects the configured NO_COLOR
environment variable, if present.
Beyond these build options, you can also provide optional build environment variables that govern how a build runs for more advanced configurations. For instance, providing CI=true
as an environment variable will tailor the build output for dumb terminals.
For more information about build environment variables and dumb terminals, consult the respective guides in the Gatsby documentation.
To serve the production build of your Gatsby site for testing purposes, execute the following in the root of your Gatsby project:
$
gatsby
serve
The gatsby serve
command accepts the options listed in Table A-4.
Option | Description |
---|---|
-H , --host |
Set the host. Defaults to localhost . |
-p , --port |
Set the port. Defaults to 9000 . |
-o , --open |
Open the site in the system’s default browser. |
--prefix-paths |
Serve the site with paths prefixed (if built with pathPrefix configured in Gatsby configuration). |
To receive helpful environment information that is required when reporting an issue in the Gatsby issue queue, execute the following command in your Gatsby project root:
$
gatsby
info
The gatsby info
command accepts the option listed in Table A-5.
Option | Description |
---|---|
-C , --clipboard |
Automatically copy environment information to the system clipboard. |
To delete the Gatsby cache (.cache) and public directories, execute the following in your Gatsby project root:
$
gatsby
clean
The gatsby clean
command is useful when your project appears to have unresolvable issues, such as content not refreshing. Some of the issues this command may resolve include problems with:
Stale data (e.g., a file or resource is not appearing)
GraphQL (e.g., a GraphQL resource that should be present is absent)
Dependencies (e.g., an invalid package version or unresolved console errors)
Plugins (e.g., local plugin updates do not take effect)
To be shown documentation about using and creating Gatsby plugins, execute the following command:
$
gatsby
plugin
docs
To acquire a Node.js REPL (interactive shell) with the context of your Gatsby environment, execute this command:
$
gatsby
repl
Gatsby will prompt you thereafter to type in commands and explore the site data. Once it shows the following output:
gatsby >
you can execute any of the commands listed here:
babelrc
components
dataPaths
getNodes()
nodes
pages
schema
siteConfig
staticQueries
For more information about using the Node.js REPL, consult the Gatsby documentation’s page on the Gatsby REPL.
35.175.174.36