Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Adds NPM article. #22942

Merged
merged 9 commits into from
Apr 9, 2020
Prev Previous commit
Next Next commit
Update docs/docs/glossary/npm.md: Clarify global installation
Remove language about Gatsby "needing" to be installed globally.
Instead call it the recommended way. Explain npx a little more.
Added a clarifying note about plugins, npx and npm install.
  • Loading branch information
webinista committed Apr 8, 2020
commit 7d3bd97b5a8c4931c93de349fcb158f3b369fec6
10 changes: 6 additions & 4 deletions docs/docs/glossary/npm.md
Original file line number Diff line number Diff line change
@@ -17,25 +17,25 @@ npm is installed alongside Node during the default [installation process](/tutor

### Using npm to install Gatsby

To install Gatsby, use the `npm install` command. Since Gatsby needs to be installed globally as a CLI app, you'll need to use the `--global` or `-g` flags.
It's recommended to install Gatsby globally, so that you can use Gatsby as a CLI application. To do so, use `npm install` with the `--global` or `-g` flags.
webinista marked this conversation as resolved.
Show resolved Hide resolved

```shell
npm install -g gatsby-cli
```

This command will install the Gatsby command line interface, or <abbr>CLI</abbr>. Once the installation completes, you can run `gatsby new my-project` to create a new Gatsby project.
Once the installation completes, you can run `gatsby new my-project` to create a new Gatsby project.

### Using npx to install Gatsby

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I started to write a comment about not needing to install globally before seeing this section. The previous section could potentially use a little clarification on that point. Once a reader gets to this section, though, I think things become clearer.

Copy link
Contributor Author

@webinista webinista Apr 8, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So instead of:

Since Gatsby needs to be installed globally as a CLI app ...

Maybe this should be:

It's recommended to install Gatsby globally, as a CLI app. Doing so allows you to use the gatsby command to easily create new and manage new projects.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@webinista I've added another suggestion which feels a bit more active/clear to me. Let me know what you think?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah. That's a better way to phrase it. Thanks!


> **Note:** `npx` requires npm version 5.2 or later. If you've installed the latest versions of Node and NPM, you should also have npx. Otherwise, you should upgrade Node and/or npm.
webinista marked this conversation as resolved.
Show resolved Hide resolved

You can also use the [npx](https://www.npmjs.com/package/npx) command to install Gatsby. npx ships with npm. It allows you to install an npm package and run a command in one step. For example, instead of running `npm install -g gatsby-cli` then `gatsby new my-project`, you could use the following command.
You can also use [npx](https://www.npmjs.com/package/npx) to install Gatsby. npx ships with npm. It allows you to install a package and run a command in one step. For example, instead of running `npm install -g gatsby-cli` then `gatsby new my-project`, you could use the following command.

```shell
npx gatsby new my-project
```

This will download and install the latest version of Gatsby, and create a new Gatsby project in the `my-project` folder. Choosing this method will not make the Gatsby CLI globally available. If you choose this method, you'll need to use `npx gatsby` or `npm run` to execute Gatsby commands, e.g.: `npx gatsby develop` or `npm run develop`.
This will download and install the latest version of Gatsby, then create a new Gatsby project in the `my-project` folder. Choosing this method will not make the Gatsby CLI globally available, however. If you install Gatsby using npx, you'll need to use `npx gatsby` or `npm run` to execute Gatsby commands, e.g.: `npx gatsby develop` or `npm run develop`.

### Using npm to install Gatsby plugins

@@ -45,6 +45,8 @@ Gatsby has a robust collection of [plugins](/plugins/) that add functionality or
npm install gatsby-source-filesystem
```

> **Note:** Use `npm install` to add plugins, even if you installed Gatsby using npx.

> **Note:** You'll still need to update `gatsby-config.js` to add the plugin's functionality to your site.

This will update the dependencies list of `package.json` and `package-lock.json`. Commit both files to your project's repository. Doing so makes it easy to keep your Gatsby project consistent across team members and computers. When another team member clones your repository, they can use `npm install` to install the dependencies included in `package-lock.json`.