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
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Next Next commit
Adds NPM article.
Update glossary.md, doc-links.yaml with links to new entry.
  • Loading branch information
webinista committed Apr 8, 2020
commit d82be08c7855af4dad34e89f53a06fba1ef9f66e
2 changes: 1 addition & 1 deletion docs/docs/glossary.md
Original file line number Diff line number Diff line change
Expand Up @@ -220,7 +220,7 @@ A way of writing HTML content with plain text, using special characters to denot

## N

### NPM
### [NPM](/docs/glossary/npm)
webinista marked this conversation as resolved.
Show resolved Hide resolved

[Node](#node) [Package](#package) Manager. Allows you to install and update other packages that your project depends on. [Gatsby](#gatsby) and [React](#react) are examples of your project's dependencies. See also: [Yarn](#yarn).
webinista marked this conversation as resolved.
Show resolved Hide resolved

Expand Down
57 changes: 57 additions & 0 deletions docs/docs/glossary/npm.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
---
title: npm or Node Package Manager
webinista marked this conversation as resolved.
Show resolved Hide resolved
disableTableOfContents: true
---

Learn what _npm_ is, how to use it, and how it fits in to the Gatsby ecosystem.

## What is npm?

<abbr>
npm
</abbr>, or Node Package Manager, is the default package manager for the [Node.js](/docs/glossary/node) JavaScript runtime. It lets you install and update libraries and frameworks (dependencies) for Node-based projects, and interact with the npm Registry. You'll use npm to install and upgrade Gatsby and its plugins.
webinista marked this conversation as resolved.
Show resolved Hide resolved

npm is a [command line](/docs/glossary#command-line) tool. You'll need Terminal (Mac, Linux) or Command Prompt (Windows) in order to run its commands. To use one of npm's features, type `npm <command>` . For example, `npm help` displays a list of available features, including `install`, `uninstall`, `update`, and `search`.

npm is installed alongside Node during the default [installation process](/tutorial/part-zero/#install-nodejs-for-your-appropriate-operating-system). You don't need to take any additional steps to add it to your environment.

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

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

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

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

### Using npm to install Gatsby plugins

Gatsby has a robust collection of [plugins](/plugins/) that add functionality or data sourcing to your Gatsby sites. Adding a plugin as a project dependency is similar to installing Gatsby itself. Use `npm install <package-name>` this time with the `--save` flag. To add the [gatsby-source-filesystem](/packages/gatsby-source-filesystem), plugin, for example, you'd use the following command.

```shell
npm install --save gatsby-source-filesystem
```

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

Using the `--save` flag updates 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`.

Choose a reason for hiding this comment

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

To my knowledge, this is no longer necessary unless you specifically want to save something as a dev dependency. See install command docs.


### Learn more about npm

- [npm](https://www.npmjs.com/) official website
- [Node.js](https://nodejs.org/en/) official website
- [An introduction to the npm package manager](https://nodejs.dev/an-introduction-to-the-npm-package-manager) from Nodejs.dev
- [Set Up Your Development Environment](https://www.gatsbyjs.org/tutorial/part-zero/) from the Gatsby docs

Choose a reason for hiding this comment

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

Suggested change
- [Set Up Your Development Environment](https://www.gatsbyjs.org/tutorial/part-zero/) from the Gatsby docs
- [Set Up Your Development Environment](/tutorial/part-zero/) from the Gatsby docs

2 changes: 2 additions & 0 deletions www/src/data/sidebars/doc-links.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -782,6 +782,8 @@
link: /docs/glossary/mdx/
- title: Node.js
link: /docs/glossary/node/
- title: npm
link: /docs/glossary/npm/
- title: React
link: /docs/glossary/react/
- title: Server Side Rendering
Expand Down