docs: remove global install instructions and tweak with package scrip…

…ts (#11556) ## Description Changes all docs references to global install of Gatsby CLI to use npx instead. Changes all docs references to using Gatsby CLI commands to either use npx (eg. npx gatsby --help) or npm scripts (eg. npm run develop). First PR so let me know if I should do anything differently! ## Related Issues Fixes #11547
gatsbyjs · Feb 8, 2019 · 45a8f09 · 45a8f09
1 parent d1c5ad9
commit 45a8f09
Show file tree

Hide file tree

Showing 80 changed files with 199 additions and 881 deletions.
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -31,4 +31,4 @@ What happened.
 
 ### Environment
 
-Run `gatsby info --clipboard` in your project directory and paste the output here. Not working? You may need to update your global gatsby-cli - `npm install -g gatsby-cli`
+Run `npx gatsby info --clipboard` in your project directory and paste the output here.
diff --git a/.github/ISSUE_TEMPLATE/question.md b/.github/ISSUE_TEMPLATE/question.md
@@ -27,8 +27,7 @@ about: Usage question or discussion about Gatsby.
 ### Environment (if relevant)
 
 <!--
-  Required. Run `gatsby info --clipboard` in your gatsby project directory and paste its contents here.
-  Not working? You may need to update your global gatsby-cli - `npm install -g gatsby-cli`
+  Required. Run `npx gatsby info --clipboard` in your gatsby project directory and paste its contents here.
 -->
 
 ### File contents (if changed)

diff --git a/README.md b/README.md
@@ -98,11 +98,8 @@ You can get a new Gatsby site up and running on your local dev environment in 5
     Get your Gatsby blog set up in a single command:
 
     ```sh
-    # install the Gatsby CLI globally
-    npm install -g gatsby-cli
-
     # create a new Gatsby site using the default starter
-    gatsby new my-blazing-fast-site
+    npx gatsby new my-blazing-fast-site
     ```
 
 2.  **Start the site in `develop` mode.**

diff --git a/docs/blog/2017-05-31-introduction-to-gatsby/index.md b/docs/blog/2017-05-31-introduction-to-gatsby/index.md
@@ -16,7 +16,7 @@ Having never used an SSG before (although I’ve read about them), and with very
 
 It turns out that getting started with Gatsby is pretty easy. The Gatsby site features a fantastic, step-by-step tutorial that walks you through getting your first site up and running (even down to deploying), and contains a wealth of resources for when you’ve mastered the basics. You don’t need any prior experience with React, although working with Gatsby definitely made me want to learn React to take full advantage of its power.
 
-One thing that prohibits me from publishing side projects is the thought of configuring a whole build setup with Gulp, webpack, etc. just for something small. This is where Gatsby really appeals to me. Gatsby provides an entire out-of-the-box build setup. Yep. Run `gatsby develop` and immediately you can bypass all that configuration and start building cool stuff in the browser (with live reloads). Run `gatsby build` and your production code is optimised (including progressive image loading and code splitting, among many other features) with _absolutely no effort on your part whatsoever_. You could feasibly get a small, performant site built and deployed in just minutes. You can also add a custom webpack config if you need to.
+One thing that prohibits me from publishing side projects is the thought of configuring a whole build setup with Gulp, webpack, etc. just for something small. This is where Gatsby really appeals to me. Gatsby provides an entire out-of-the-box build setup. Yep. Run `npm run develop` and immediately you can bypass all that configuration and start building cool stuff in the browser (with live reloads). Run `npm run build` and your production code is optimised (including progressive image loading and code splitting, among many other features) with _absolutely no effort on your part whatsoever_. You could feasibly get a small, performant site built and deployed in just minutes. You can also add a custom webpack config if you need to.
 
 ### CSS
 

diff --git a/docs/blog/2017-07-19-creating-a-blog-with-gatsby/index.md b/docs/blog/2017-07-19-creating-a-blog-with-gatsby/index.md
@@ -33,25 +33,22 @@ these new features by creating a static blog. Let's get on it!
 
 ## Getting started
 
-### Installing the CLI
-
-`npm install -g gatsby-cli`
+### Using the CLI
 
 Gatsby ships with a great CLI (command line interface) that contains the
 functionality of scaffolding out a working site, as well as commands to help
 develop the site once created.
 
-`gatsby new personal-blog && cd $_`
+`npx gatsby new personal-blog && cd $_`
 
 This command will create the folder `personal-blog` and then change into that
 directory. A working `gatsby` statically generated application can now be
-developed upon. The Gatsby CLI includes many common development features such as
-`gatsby build` (build a production, statically generated version of the
-project), `gatsby develop` (launch a hot-reload enabled web development server),
+developed upon. The CLI generates common development scripts to help you get started.
+For example you can run `npm run build` (build a production, statically generated version of the project) or `npm run develop` (launch a hot-reload enabled web development server),
 etc.
 
 We can now begin the exciting task of _actually_ developing on the site, and
-creating a functional, modern blog. You'll generally want to use `gatsby develop` to launch the local development server to validate functionality as we
+creating a functional, modern blog. You'll generally want to use `npm run develop` to launch the local development server to validate functionality as we
 progress through the steps.
 
 ## Adding necessary plugins

diff --git a/docs/blog/2017-10-01-migrating-my-blog-from-hexo-to-gatsby/index.md b/docs/blog/2017-10-01-migrating-my-blog-from-hexo-to-gatsby/index.md
@@ -82,8 +82,7 @@ are many ways you could do this but I'll go over what I did.
 To get all the Gatsby files you can use the Gatsby CLI.
 
 ```yaml
-npm install -g gatsby-cli   # Install gatsby CLI
-gatsby new temp-gatsby-files # Initialize gatsby in a temp directory
+npx gatsby new temp-gatsby-files # Initialize gatsby in a temp directory
 cp -R temp-gatsby-files/* ./ # Copy all the files into your root directory
 rm -rf temp-gatsby-files     # Remove the temp directory
 ```

diff --git a/docs/blog/2017-12-06-gatsby-plus-contentful-plus-netlify/index.md b/docs/blog/2017-12-06-gatsby-plus-contentful-plus-netlify/index.md
@@ -286,7 +286,7 @@ And back to using it with Gatsby.
 
 After you link your Netlify site to a specific code repository, Netlify’s build
 bots take care of the rest. From that point on, when you push a change to your
-repo, the build bot says, “Hey look! a change! I need to run the `gatsby build`
+repo, the build bot says, “Hey look! a change! I need to run the `npm run build`
 command...”, then it follows the package.json (or yarn file) in the repo and
 downloads the necessary dependencies if they aren’t already cached, and then
 builds out the static site.

diff --git a/docs/blog/2018-01-22-getting-started-gatsby-and-wordpress/index.md b/docs/blog/2018-01-22-getting-started-gatsby-and-wordpress/index.md
@@ -15,7 +15,7 @@ I recently decided to tackle a redo of my blog. I wanted to do something differ
 
 I generated a new site using the [default starter](https://github.com/gatsbyjs/gatsby-starter-default) and read through what it gave me. Assuming you have the [Gatsby CLI](/docs/) installed, run:
 
-`gatsby new gatsby-example-site`
+`npx gatsby new gatsby-example-site`
 
 That gets us a new site directory with a couple (mostly) empty "gatsby"-prefixed files and a src directory with some basic scaffolding. The configuration and lifecycle hooks for Gatsby get put in those "gatsby"-prefixed files, `gatsby-config.js`, `gatsby-node.js` and `gatsby-browser.js`.
 
@@ -132,7 +132,7 @@ If you include the "optional GraphQL query" noted above, the result of that quer
 
 ##Onward
 
-While this isn't a tutorial -- more a guided walkthrough of me familiarizing and stepping through an initial Gatsby setup -- if you're following along with the [demo code](https://github.com/gatsbyjs/gatsby/tree/master/examples/using-wordpress) you're probably close to (or already!) seeing your WordPress data populate your Gatsby dev site if you run `gatsby develop`!
+While this isn't a tutorial -- more a guided walkthrough of me familiarizing and stepping through an initial Gatsby setup -- if you're following along with the [demo code](https://github.com/gatsbyjs/gatsby/tree/master/examples/using-wordpress) you're probably close to (or already!) seeing your WordPress data populate your Gatsby dev site if you run `npm run develop`!
 
 ##Sidenotes
 

diff --git a/docs/blog/2018-04-04-gatsby-contentful-starter-tutorial/index.md b/docs/blog/2018-04-04-gatsby-contentful-starter-tutorial/index.md
@@ -33,7 +33,7 @@ This guide assumes that you have [GatsbyJS installed](/docs/) and, optionally, a
 Start by using this with the Gatsby CLI:
 
 ```bash
-gatsby new contentful-starter https://github.com/contentful-userland/gatsby-contentful-starter
+npx gatsby new contentful-starter https://github.com/contentful-userland/gatsby-contentful-starter
 ```
 
 Alternatively, you can also clone a sample repo from GitHub:

diff --git a/.../blog/2018-06-07-build-a-gatsby-blog-using-the-cosmic-js-source-plugin/index.md b/.../blog/2018-06-07-build-a-gatsby-blog-using-the-cosmic-js-source-plugin/index.md
@@ -39,7 +39,7 @@ npm install --global gatsby-cli
 Create a new site based on the Gatsby Cosmic JS starter:
 
 ```bash
-gatsby new gatsby-blog-cosmicjs
+npx gatsby new gatsby-blog-cosmicjs
 ```
 
 Enter in your project's folder:
@@ -51,7 +51,7 @@ cd gatsby-blog-cosmicjs
 Start the server:
 
 ```bash
-gatsby develop
+npm run develop
 ```
 
 At this point, you can access your Gatsby website by visiting [http://localhost:8000](http://localhost:8000).

diff --git a/docs/blog/2018-06-08-life-after-layouts/index.md b/docs/blog/2018-06-08-life-after-layouts/index.md
@@ -122,7 +122,7 @@ For a full list of what's new, check out our [V2 migration guide](/docs/migratin
 - You can get started using Gatsby V2 right now by installing our V2 default starter:
 
   ```
-  gatsby new my-gatsby-v2-site https://github.com/gatsbyjs/gatsby-starter-default
+  npx gatsby new my-gatsby-v2-site https://github.com/gatsbyjs/gatsby-starter-default
   ```
 
   Huge thanks to [Yuki Takemoto](https://github.com/mottox2) for upgrading the starter to V2!

diff --git a/docs/blog/2018-07-07-graphic-design-class/index.md b/docs/blog/2018-07-07-graphic-design-class/index.md
@@ -69,7 +69,7 @@ Here’s a list of what they love about Gatsby:
 * _Docs:_ While not perfect, the Gatsby tutorial and documentation. was “approachable”
 * _Speed_: They never heard of static site generators or the JAMstack, but the speed immediately impressed them
 * _Built off previous knowledge:_ They were able to use the routing knowledge they gleaned from NextJS
-* _Uses simple commands:_ They work locally and type `$ gatsby develop`. A server opens up and they see and can edit their site in real time. Easy peasy. They want to build for production they use `$ gatsby build && gatsby serve`. Simple!
+* _Uses simple commands:_ They work locally and type `$ npm run develop`. A server opens up and they see and can edit their site in real time. Easy peasy. They want to build for production they use `$ npx gatsby build && npx gatsby serve`. Simple!
 * _Netlify:_ When I showed them Netlify and how they could quickly (and freely) push their site to GitHub and hook it up to Netlify so that it would automatically build it and make their site live! They were blown away.
 * _Fast to build:_ They were able to create their final projects in 3 weeks
 

diff --git a/docs/blog/2018-08-24-gatsby-aws-hosting/index.md b/docs/blog/2018-08-24-gatsby-aws-hosting/index.md
@@ -26,7 +26,7 @@ npm install - global gatsby-cli
 Next, we'll create a new Gatsby site:
 
 ```sh
-gatsby new my-gatsby-site
+npx gatsby new my-gatsby-site
 ```
 
 Finally, change into the new site directory:

diff --git a/docs/blog/2018-1-18-strapi-and-gatsby/index.md b/docs/blog/2018-1-18-strapi-and-gatsby/index.md
@@ -144,7 +144,7 @@ $ npm install --global gatsby-cli
 In the folder `gatsby-strapi-tutorial` that you previously created, generate your brand new blog:
 
 ```bash
-$ gatsby new blog
+$ npx gatsby new blog
 ```
 
 ### Start in development mode
@@ -158,7 +158,7 @@ $ cd blog
 Start the server:
 
 ```bash
-$ gatsby develop
+$ npm run develop
 ```
 
 At this point, you should already be able to get access to your Gatsby website at this address: http://localhost:8000.

diff --git a/docs/blog/2018-10-26-export-a-drupal-site-to-gatsby/index.md b/docs/blog/2018-10-26-export-a-drupal-site-to-gatsby/index.md
@@ -19,7 +19,7 @@ mysqldump --skip-extended-insert --compact DB_name > dump_mysql.sql
 To do this yourself, you'll build a simple blog using the excellent [gatsby-starter-blog](https://github.com/gatsbyjs/gatsby-starter-blog) project. Create a new project and then add a [sqlite library](https://github.com/JoshuaWise/better-sqlite3) as a dev dependency:
 
 ```
-gatsby new gatsby-blog https://github.com/gatsbyjs/gatsby-starter-blog
+npx gatsby new gatsby-blog https://github.com/gatsbyjs/gatsby-starter-blog
 git init # so you can keep track of the changes
 npm i --save-dev better-sqlite3
 ```

diff --git a/docs/blog/2018-11-03-building-an-accessible-lightbox/index.md b/docs/blog/2018-11-03-building-an-accessible-lightbox/index.md
@@ -19,7 +19,7 @@ $ npm install --global gatsby-cli
 Then, still in your Terminal, head over to a folder you'd want to get started in and type in:
 
 ```terminal
-$ gatsby new GatsbyLightbox https://github.com/gatsbyjs/gatsby-starter-default
+$ npx gatsby new GatsbyLightbox https://github.com/gatsbyjs/gatsby-starter-default
 ```
 
 Once it's done scaffolding the starter application, type in:

diff --git a/docs/blog/2018-11-05-deploying-gatsby-to-azure/index.md b/docs/blog/2018-11-05-deploying-gatsby-to-azure/index.md
@@ -45,7 +45,7 @@ Next you will create the blog from the handy [Gatsby Starter Blog](https://githu
 From your terminal run
 
 ```bash
-$ gatsby new azure-blog https://github.com/gatsbyjs/gatsby-starter-blog
+$ npx gatsby new azure-blog https://github.com/gatsbyjs/gatsby-starter-blog
 
 info Creating new site from git: https://github.com/gatsbyjs/gatsby-starter-blog.git
 Cloning into 'azure-blog'...
@@ -63,7 +63,7 @@ You can now view your website by running
 
 ```bash
 $ cd azure-blog
-$ gatsby develop
+$ npm run develop
 ```
 
 You should now see your blog in the flesh!

diff --git a/docs/blog/2018-2-27-why-i-upgraded-my-website-to-gatsbyjs-from-jekyll/index.md b/docs/blog/2018-2-27-why-i-upgraded-my-website-to-gatsbyjs-from-jekyll/index.md
@@ -86,7 +86,7 @@ export const pageQuery = graphql`
 
 When the `<PostTemplate />` component needs to be rendered into a page, the accompanying exported `pageQuery`, a GraphQL query is made, and the results are passed in as props into the component.
 
-The real magic happens when the website is compiled into a production bundle. Running `gatsby build` will tell Gatsby to perform all the GraphQL queries defined and render all the React components into a HTML document, using a technique known as server-side rendering. This means that everything “React” is serialized and compiled to static HTML, ready to be viewed without JavaScript. Visitors to the site will then be able to quickly load and interact with the static version of the page.
+The real magic happens when the website is compiled into a production bundle. Running `npm run build` will tell Gatsby to perform all the GraphQL queries defined and render all the React components into a HTML document, using a technique known as server-side rendering. This means that everything “React” is serialized and compiled to static HTML, ready to be viewed without JavaScript. Visitors to the site will then be able to quickly load and interact with the static version of the page.
 
 Not only that, within the HTML document, there are instructions to load the JavaScript bundle of your application asynchronously. When it has been loaded, the content displayed in the browser will be dynamically replaced by the React application, gaining interactivity. This also happens with the other pages of your site — Gatsby will ensure that they are asynchronously loaded so that when you click on a link, the data is already cached on the browser for React to swap out the DOM elements that need to be changed. Everything is done to give the illusion of speed to the viewer while asynchronously loading everything in the background.
 

diff --git a/docs/blog/2019-01-01-publish-multiple-gatsby-sites/index.md b/docs/blog/2019-01-01-publish-multiple-gatsby-sites/index.md
@@ -267,7 +267,7 @@ package.json- Add the following to the `package.json` file:
     styled-components: "^3.3.3"
   },
   license: "MIT",
-    scripts: {
+  scripts: {
     start: "serve public/",
     build: "gatsby build",
     develop: "gatsby develop"

diff --git a/docs/blog/gatsbygram-case-study/index.md b/docs/blog/gatsbygram-case-study/index.md
@@ -554,7 +554,7 @@ node scrape.js INSTAGRAM_USERNAME
 # Start the Gatsby development server. The initial
 # run will take extra time as it processes
 # images the first time.
-gatsby develop
+npm run develop
 ```
 
 While writing this post I scraped a few accounts and published their resulting

diff --git a/docs/docs/authentication-tutorial.md b/docs/docs/authentication-tutorial.md
@@ -17,7 +17,7 @@ In production, you should use a tested and robust solution to handle the authent
 Start by creating a new Gatsby project using barebones `hello-world` starter:
 
 ```shell
-gatsby new gatsby-auth gatsbyjs/gatsby-starter-hello-world
+npx gatsby new gatsby-auth gatsbyjs/gatsby-starter-hello-world
 cd gatsby-auth
 ```
 

diff --git a/docs/docs/babel-plugin-macros.md b/docs/docs/babel-plugin-macros.md
@@ -47,8 +47,7 @@ import preval from "preval.macro"
 const x = preval`module.exports = 1` // highlight-line
 ```
 
-When building your project with `gatsby develop` or `gatsby build`, this code
-will be transformed into:
+When building your project this code will be transformed into:
 
 ```javascript
 const x = 1

diff --git a/docs/docs/behind-the-scenes.md b/docs/docs/behind-the-scenes.md
@@ -8,7 +8,7 @@ If you're looking for information on how to _use_ Gatsby to write your own site,
 
 These docs aren't supposed to be definitive, or tell you everything there is to know. But as you're exploring the Gatsby codebase, you might find yourself wondering what a concept means, or which part of the codebase implements a particular idea. These docs aim to answer those kinds of questions.
 
-A few more things. These docs are mostly focused on `gatsby build`. Operations specific to `gatsby develop` are mostly ignored. Though this may change in the future. Also, they mostly focus on the happy path, rather than getting bogged down in details of error handling.
+A few more things. These docs are mostly focused on the build lifecycle (`gatsby build`). Operations specific to the develop lifecycle (`gatsby develop`) are mostly ignored. Though this may change in the future. Also, they mostly focus on the happy path, rather than getting bogged down in details of error handling.
 
 The graph below shows roughly how all the sub systems of Gatsby fit together and the input/output artifacts at different parts of the build. To find out how different parts work, click on the nodes in the graph, or use the menu on the left.
 

diff --git a/docs/docs/centralizing-your-sites-navigation.md b/docs/docs/centralizing-your-sites-navigation.md
@@ -15,7 +15,7 @@ What this section will cover:
 
 You will be using `gatsby-config.js` to store the data for your links. `gatsby-config.js` is a file used for configuring Gatsby, located in the root path of every Gatsby project. A plain old JavaScript object is exported from this file; this object contains the `siteMetadata` object which you can query through graphql when generating your static pages.
 
-This guide will use the Gatsby starter project `gatsby-starter-default`, which can be downloaded through the Gatsby command line interface tool using the command `gatsby new [project-name] https://github.com/gatsbyjs/gatsby-starter-default`.
+This guide will use the Gatsby starter project `gatsby-starter-default`, which can be downloaded through the Gatsby command line interface tool using the command `npx gatsby new [project-name] https://github.com/gatsbyjs/gatsby-starter-default`.
 
 ### Creating the link data
 

diff --git a/docs/docs/creating-a-sitemap.md b/docs/docs/creating-a-sitemap.md
@@ -26,7 +26,7 @@ module.exports = {
 }
 ```
 
-Next run a `gatsby build` since the sitemap generation will only happen for production builds. This is all that's required to get a working sitemap with Gatsby! By default, the generated sitemap path is /sitemap.xml and will include all of your site’s pages, but of course the plugin exposes options to configure this default functionality.
+Next run a build (`npm run build`) since the sitemap generation will only happen for production builds. This is all that's required to get a working sitemap with Gatsby! By default, the generated sitemap path is /sitemap.xml and will include all of your site’s pages, but of course the plugin exposes options to configure this default functionality.
 
 ### Additional Modification
Original file line number	Diff line number	Diff line change
Expand Up		@@ -31,4 +31,4 @@ What happened.

		### Environment

		Run `gatsby info --clipboard` in your project directory and paste the output here. Not working? You may need to update your global gatsby-cli - `npm install -g gatsby-cli`
		Run `npx gatsby info --clipboard` in your project directory and paste the output here.
-Original file line number
+Diff line change
@@ Expand Up @@
     It turns out that getting started with Gatsby is pretty easy. The Gatsby site features a fantastic, step-by-step tutorial that walks you through getting your first site up and running (even down to deploying), and contains a wealth of resources for when you’ve mastered the basics. You don’t need any prior experience with React, although working with Gatsby definitely made me want to learn React to take full advantage of its power.
-    One thing that prohibits me from publishing side projects is the thought of configuring a whole build setup with Gulp, webpack, etc. just for something small. This is where Gatsby really appeals to me. Gatsby provides an entire out-of-the-box build setup. Yep. Run `gatsby develop` and immediately you can bypass all that configuration and start building cool stuff in the browser (with live reloads). Run `gatsby build` and your production code is optimised (including progressive image loading and code splitting, among many other features) with _absolutely no effort on your part whatsoever_. You could feasibly get a small, performant site built and deployed in just minutes. You can also add a custom webpack config if you need to.
+    One thing that prohibits me from publishing side projects is the thought of configuring a whole build setup with Gulp, webpack, etc. just for something small. This is where Gatsby really appeals to me. Gatsby provides an entire out-of-the-box build setup. Yep. Run `npm run develop` and immediately you can bypass all that configuration and start building cool stuff in the browser (with live reloads). Run `npm run build` and your production code is optimised (including progressive image loading and code splitting, among many other features) with _absolutely no effort on your part whatsoever_. You could feasibly get a small, performant site built and deployed in just minutes. You can also add a custom webpack config if you need to.
     ### CSS
@@ Expand Down @@