Appendix A. The Gatsby CLI

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.

Gatsby Cheat Sheet

First, install the global executable:

$ npm install -g gatsby-cli

Execute gatsby --help for a full list of available commands and options.

Common CLI Commands

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
Create a new local Gatsby site using the default starter.
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
Delete Gatsby’s .cache and public directories.

Quick Start Commands

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.

Helpful File Definitions

Each of these files should be found at the root of your Gatsby project:

gatsby-config.js
Configure options for a Gatsby site, with metadata for the project title, description, plugins, etc.
gatsby-node.js
Implement Gatsby’s Node.js APIs to customize and extend default settings influencing the build process.
gatsby-browser.js
Customize and extend default settings influencing the browser, using Gatsby’s Browser APIs.
gatsby-ssr.js
Use Gatsby’s Server-Side Rendering (SSR) APIs to customize default settings influencing server-side rendering.

You can find more information at https://gatsby.dev/projects.

Top Documentation Pages

Table A-1 provides a quick reference to the most commonly used Gatsby documentation pages.

Table A-1. 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

Gatsby CLI Commands

The following is a comprehensive list of the commands available in the Gatsby CLI.

new

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
The Gatsby site name, which will also became the name of the created project directory
starter-url
A Gatsby starter URL or local file path; defaults to gatsby-starter-default
Note

The site-name argument can only consist of alphanumeric characters. Specifying ., ./, or using a space in the name will trigger an error.

develop

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.

Table A-2. gatsby develop options
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.
Note

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/
Note

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

build

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.

Table A-3. gatsby build options
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.
Tip

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.

Note

For more information about build environment variables and dumb terminals, consult the respective guides in the Gatsby documentation.

serve

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.

Table A-4. gatsby serve options
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).

info

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.

Table A-5. gatsby info options
Option Description
-C, --clipboard Automatically copy environment information to the system clipboard.

clean

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)

plugin

To be shown documentation about using and creating Gatsby plugins, execute the following command:

$ gatsby plugin docs

repl

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

Note

For more information about using the Node.js REPL, consult the Gatsby documentation’s page on the Gatsby REPL.

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset
35.175.174.36