From d82be08c7855af4dad34e89f53a06fba1ef9f66e Mon Sep 17 00:00:00 2001 From: Tiffany Brown Date: Mon, 6 Apr 2020 15:48:44 -0700 Subject: [PATCH 1/9] Adds NPM article. Update glossary.md, doc-links.yaml with links to new entry. --- docs/docs/glossary.md | 2 +- docs/docs/glossary/npm.md | 57 ++++++++++++++++++++++++++++ www/src/data/sidebars/doc-links.yaml | 2 + 3 files changed, 60 insertions(+), 1 deletion(-) create mode 100644 docs/docs/glossary/npm.md diff --git a/docs/docs/glossary.md b/docs/docs/glossary.md index 52b1fc0849c10..417fa302bbebf 100644 --- a/docs/docs/glossary.md +++ b/docs/docs/glossary.md @@ -220,7 +220,7 @@ A way of writing HTML content with plain text, using special characters to denot ## N -### NPM +### [NPM](/docs/glossary/npm) [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). diff --git a/docs/docs/glossary/npm.md b/docs/docs/glossary/npm.md new file mode 100644 index 0000000000000..5e5be04b2f74a --- /dev/null +++ b/docs/docs/glossary/npm.md @@ -0,0 +1,57 @@ +--- +title: npm or Node Package Manager +disableTableOfContents: true +--- + +Learn what _npm_ is, how to use it, and how it fits in to the Gatsby ecosystem. + +## What is npm? + + + npm +, 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. + +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 ` . 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 CLI. Once the installation completes, you can run `gatsby new my-project` to create a new Gatsby project. + +### Using npx to install Gatsby + +> **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. + +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 ` 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`. + +### 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 diff --git a/www/src/data/sidebars/doc-links.yaml b/www/src/data/sidebars/doc-links.yaml index 3c3745a2f8382..1808c5da22283 100644 --- a/www/src/data/sidebars/doc-links.yaml +++ b/www/src/data/sidebars/doc-links.yaml @@ -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 From 83973a95bdb59a42a3232ccbfb37671c47db6d99 Mon Sep 17 00:00:00 2001 From: Tiffany Brown Date: Wed, 8 Apr 2020 13:53:08 -0700 Subject: [PATCH 2/9] Update docs/docs/glossary.md Follow capitalization of "Node package manager" from npmjs.com. Co-Authored-By: Aisha Blake --- docs/docs/glossary.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/glossary.md b/docs/docs/glossary.md index 417fa302bbebf..0bf7537dc4d09 100644 --- a/docs/docs/glossary.md +++ b/docs/docs/glossary.md @@ -222,7 +222,7 @@ A way of writing HTML content with plain text, using special characters to denot ### [NPM](/docs/glossary/npm) -[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). +[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). ### Node From 0fdfb266b9c5c92573abf8013c336c4247c6d0d5 Mon Sep 17 00:00:00 2001 From: Tiffany Brown Date: Wed, 8 Apr 2020 13:53:50 -0700 Subject: [PATCH 3/9] Update docs/docs/glossary/npm.md Update document title to use capitalization preferred by npm, Inc. Co-Authored-By: Aisha Blake --- docs/docs/glossary/npm.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/glossary/npm.md b/docs/docs/glossary/npm.md index 5e5be04b2f74a..db81b3644d9de 100644 --- a/docs/docs/glossary/npm.md +++ b/docs/docs/glossary/npm.md @@ -1,5 +1,5 @@ --- -title: npm or Node Package Manager +title: npm or Node package manager disableTableOfContents: true --- From 92c9f319178bea6084c784f727b28fb68f10f3ed Mon Sep 17 00:00:00 2001 From: Tiffany Brown Date: Wed, 8 Apr 2020 13:55:08 -0700 Subject: [PATCH 4/9] Update docs/docs/glossary/npm.md Change capitalization of "Node Package Manager" to "Node package manager" --- docs/docs/glossary/npm.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/glossary/npm.md b/docs/docs/glossary/npm.md index db81b3644d9de..03a8283147971 100644 --- a/docs/docs/glossary/npm.md +++ b/docs/docs/glossary/npm.md @@ -9,7 +9,7 @@ Learn what _npm_ is, how to use it, and how it fits in to the Gatsby ecosystem. npm -, 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. +, 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. 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 ` . For example, `npm help` displays a list of available features, including `install`, `uninstall`, `update`, and `search`. From a830df36eac2aae8c9020ab9762411109496faa9 Mon Sep 17 00:00:00 2001 From: Tiffany Brown Date: Wed, 8 Apr 2020 14:03:40 -0700 Subject: [PATCH 5/9] Update docs/docs/glossary/npm.md Update directions for installing plugins to remove the `--save` flag since npm now does this by default. Change tutorial link to be relative instead of absolute. --- docs/docs/glossary/npm.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/docs/glossary/npm.md b/docs/docs/glossary/npm.md index 03a8283147971..6fde8db2837ff 100644 --- a/docs/docs/glossary/npm.md +++ b/docs/docs/glossary/npm.md @@ -35,23 +35,23 @@ You can also use the [npx](https://www.npmjs.com/package/npx) command to install 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`. +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`. ### 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 ` 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. +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 uses the same process as installing Gatsby itself. Use `npm install `. 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 +npm install 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`. +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`. ### 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 +- [Set Up Your Development Environment](/tutorial/part-zero/) from the Gatsby docs From 7d3bd97b5a8c4931c93de349fcb158f3b369fec6 Mon Sep 17 00:00:00 2001 From: Tiffany Brown Date: Wed, 8 Apr 2020 14:40:05 -0700 Subject: [PATCH 6/9] 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. --- docs/docs/glossary/npm.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/docs/glossary/npm.md b/docs/docs/glossary/npm.md index 6fde8db2837ff..6fdb32bc0c767 100644 --- a/docs/docs/glossary/npm.md +++ b/docs/docs/glossary/npm.md @@ -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. ```shell npm install -g gatsby-cli ``` -This command will install the Gatsby command line interface, or CLI. 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 > **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. -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`. From 70f58ae4a9d6db614cb6a827a8072ceda0e415d4 Mon Sep 17 00:00:00 2001 From: Tiffany Brown Date: Thu, 9 Apr 2020 09:45:45 -0700 Subject: [PATCH 7/9] Update docs/docs/glossary.md Capitalization of npm Co-Authored-By: Aisha Blake --- docs/docs/glossary.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/glossary.md b/docs/docs/glossary.md index 0bf7537dc4d09..d2dbb5c97a0ae 100644 --- a/docs/docs/glossary.md +++ b/docs/docs/glossary.md @@ -220,7 +220,7 @@ A way of writing HTML content with plain text, using special characters to denot ## N -### [NPM](/docs/glossary/npm) +### [npm](/docs/glossary/npm) [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). From bbf15cfd36208b70167ca5d1764eb0734a983c45 Mon Sep 17 00:00:00 2001 From: Tiffany Brown Date: Thu, 9 Apr 2020 09:48:21 -0700 Subject: [PATCH 8/9] Update docs/docs/glossary/npm.md Use active voice re: installing Gatsby globally. Co-Authored-By: Aisha Blake --- docs/docs/glossary/npm.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/glossary/npm.md b/docs/docs/glossary/npm.md index 6fdb32bc0c767..ee966cd1c3603 100644 --- a/docs/docs/glossary/npm.md +++ b/docs/docs/glossary/npm.md @@ -17,7 +17,7 @@ npm is installed alongside Node during the default [installation process](/tutor ### Using npm to install Gatsby -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. +You'll need to install Gatsby globally to use Gatsby CLI commands such as `gatsby new`. To do so, use `npm install` with the `--global` or `-g` flag. ```shell npm install -g gatsby-cli From 89b9dc3eff5553022a53c2cea5bbb3ea8d535ce8 Mon Sep 17 00:00:00 2001 From: Tiffany Brown Date: Thu, 9 Apr 2020 09:49:28 -0700 Subject: [PATCH 9/9] Update docs/docs/glossary/npm.md Change NPM to npm for style, consistency. Co-Authored-By: Aisha Blake --- docs/docs/glossary/npm.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/glossary/npm.md b/docs/docs/glossary/npm.md index ee966cd1c3603..f6caff679440f 100644 --- a/docs/docs/glossary/npm.md +++ b/docs/docs/glossary/npm.md @@ -27,7 +27,7 @@ Once the installation completes, you can run `gatsby new my-project` to create a ### Using npx to install Gatsby -> **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. +> **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. 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.