diff options
author | Ruy Adorno <ruyadorno@hotmail.com> | 2021-04-07 18:03:41 +0300 |
---|---|---|
committer | Ruy Adorno <ruyadorno@hotmail.com> | 2021-04-22 22:06:29 +0300 |
commit | 4c1f16d2c29a7a56c19b97f2820e6305a6075083 (patch) | |
tree | 460fd0dfa65b168d3f35bac5e0ad363b14684a1d /docs | |
parent | 2aecec591df6866e27d0b17dc49cef8f7d738d77 (diff) |
feat: add init workspaces
Add workspaces support to `npm init`
- Fixes `npm exec` respecting `script-shell` option value
- Refactored `lib/exec.js` into `libnpmexec`
- Updates init-package-json@2.0.3
- Added ability to create a new workspace using the -w config
PR-URL: https://github.com/npm/cli/pull/3095
Credit: @ruyadorno
Close: #3095
Reviewed-by: @wraithgar
Diffstat (limited to 'docs')
-rw-r--r-- | docs/content/commands/npm-exec.md | 1 | ||||
-rw-r--r-- | docs/content/commands/npm-init.md | 120 | ||||
-rw-r--r-- | docs/content/commands/npm-run-script.md | 1 | ||||
-rw-r--r-- | docs/content/using-npm/config.md | 3 |
4 files changed, 114 insertions, 11 deletions
diff --git a/docs/content/commands/npm-exec.md b/docs/content/commands/npm-exec.md index 6666d30e8..2364da32c 100644 --- a/docs/content/commands/npm-exec.md +++ b/docs/content/commands/npm-exec.md @@ -291,3 +291,4 @@ project. * [npm restart](/commands/npm-restart) * [npm stop](/commands/npm-stop) * [npm config](/commands/npm-config) +* [npm workspaces](/using-npm/workspaces) diff --git a/docs/content/commands/npm-init.md b/docs/content/commands/npm-init.md index 4b0b8c4c4..8288034a3 100644 --- a/docs/content/commands/npm-init.md +++ b/docs/content/commands/npm-init.md @@ -8,8 +8,9 @@ description: Create a package.json file ```bash npm init [--force|-f|--yes|-y|--scope] -npm init <@scope> (same as `npx <@scope>/create`) -npm init [<@scope>/]<name> (same as `npx [<@scope>/]create-<name>`) +npm init <@scope> (same as `npm exec <@scope>/create`) +npm init [<@scope>/]<name> (same as `npm exec [<@scope>/]create-<name>`) +npm init [-w <dir>] [args...] ``` ### Description @@ -18,19 +19,16 @@ npm init [<@scope>/]<name> (same as `npx [<@scope>/]create-<name>`) package. `initializer` in this case is an npm package named `create-<initializer>`, -which will be installed by [`npx`](https://npm.im/npx), and then have its +which will be installed by [`npm-exec`](/commands/npm-exec), and then have its main bin executed -- presumably creating or updating `package.json` and running any other initialization-related operations. -The init command is transformed to a corresponding `npx` operation as +The init command is transformed to a corresponding `npm exec` operation as follows: -* `npm init foo` -> `npx create-foo` -* `npm init @usr/foo` -> `npx @usr/create-foo` -* `npm init @usr` -> `npx @usr/create` - -Any additional options will be passed directly to the command, so `npm init -foo -- --hello` will map to `npx create-foo --hello`. +* `npm init foo` -> `npm exec create-foo` +* `npm init @usr/foo` -> `npm exec @usr/create-foo` +* `npm init @usr` -> `npm exec @usr/create` If the initializer is omitted (by just calling `npm init`), init will fall back to legacy init behavior. It will ask you a bunch of questions, and @@ -40,6 +38,18 @@ strictly additive, so it will keep any fields and values that were already set. You can also use `-y`/`--yes` to skip the questionnaire altogether. If you pass `--scope`, it will create a scoped package. +#### Forwarding additional options + +Any additional options will be passed directly to the command, so `npm init +foo -- --hello` will map to `npm exec -- create-foo --hello`. + +To better illustrate how options are forwarded, here's a more evolved +example showing options passed to both the **npm cli** and a create package, +both following commands are equivalent: + +- `npm init foo -y --registry=<url> -- --hello -a` +- `npm exec -y --registry=<url> -- create-foo --hello -a` + ### Examples Create a new React-based project using @@ -71,6 +81,68 @@ Generate it without having it ask any questions: $ npm init -y ``` +### Workspaces support + +It's possible to create a new workspace within your project by using the +`workspace` config option. When using `npm init -w <dir>` the cli will +create the folders and boilerplate expected while also adding a reference +to your project `package.json` `"workspaces": []` property in order to make +sure that new generated **workspace** is properly set up as such. + +Given a project with no workspaces, e.g: + +``` +. ++-- package.json +``` + +You may generate a new workspace using the legacy init: + +```bash +$ npm init -w packages/a +``` + +That will generate a new folder and `package.json` file, while also updating +your top-level `package.json` to add the reference to this new workspace: + +``` +. ++-- package.json +`-- packages + `-- a + `-- package.json +``` + +The workspaces init also supports the `npm init <initializer> -w <dir>` +syntax, following the same set of rules explained earlier in the initial +**Description** section of this page. Similar to the previous example of +creating a new React-based project using +[`create-react-app`](https://npm.im/create-react-app), the following syntax +will make sure to create the new react app as a nested **workspace** within your +project and configure your `package.json` to recognize it as such: + +```bash +npm init -w packages/my-react-app react-app . +``` + +This will make sure to generate your react app as expected, one important +consideration to have in mind is that `npm exec` is going to be run in the +context of the newly created folder for that workspace, and that's the reason +why in this example the initializer uses the initializer name followed with a +dot to represent the current directory in that context, e.g: `react-app .`: + +``` +. ++-- package.json +`-- packages + +-- a + | `-- package.json + `-- my-react-app + +-- README + +-- package.json + `-- ... +``` + ### A note on caching The npm cli utilizes its internal package cache when using the package @@ -93,6 +165,33 @@ requested from the server. To force full offline mode, use `offline`. Forces full offline mode. Any packages not locally cached will result in an error. +#### workspace + +* Alias: `-w` +* Type: Array +* Default: `[]` + +Enable running `npm init` in the context of workspaces, creating any missing +folders, generating files and adding/updating the `"workspaces"` property of +the project `package.json`. + +the provided names or paths provided. + +Valid values for the `workspace` config are either: +- Workspace names +- Path to a workspace directory +- Path to a parent workspace directory (will result to selecting all of the +children workspaces) + +#### workspaces + +* Alias: `-ws` +* Type: Boolean +* Default: `false` + +Run `npm init` in the context of all configured workspaces for the +current project. + ### See Also * [init-package-json module](http://npm.im/init-package-json) @@ -100,3 +199,4 @@ an error. * [npm version](/commands/npm-version) * [npm scope](/using-npm/scope) * [npm exec](/commands/npm-exec) +* [npm workspaces](/using-npm/workspaces) diff --git a/docs/content/commands/npm-run-script.md b/docs/content/commands/npm-run-script.md index 028f8eb15..6786312e0 100644 --- a/docs/content/commands/npm-run-script.md +++ b/docs/content/commands/npm-run-script.md @@ -204,3 +204,4 @@ project. * [npm restart](/commands/npm-restart) * [npm stop](/commands/npm-stop) * [npm config](/commands/npm-config) +* [npm workspaces](/using-npm/workspaces) diff --git a/docs/content/using-npm/config.md b/docs/content/using-npm/config.md index b2e8baf01..1a70c29f9 100644 --- a/docs/content/using-npm/config.md +++ b/docs/content/using-npm/config.md @@ -1087,7 +1087,8 @@ installation of packages specified according to the pattern * Default: '/bin/sh' on POSIX systems, 'cmd.exe' on Windows * Type: null or String -The shell to use for scripts run with the `npm run` command. +The shell to use for scripts run with the `npm exec`, `npm run` and +`npm init <pkg>` commands. #### `searchexclude` |