diff --git a/nx-dev/nx-dev/public/documentation/latest/angular/api-angular/generators/application.md b/nx-dev/nx-dev/public/documentation/latest/angular/api-angular/generators/application.md index e2407bbe4b..5c317fad44 100644 --- a/nx-dev/nx-dev/public/documentation/latest/angular/api-angular/generators/application.md +++ b/nx-dev/nx-dev/public/documentation/latest/angular/api-angular/generators/application.md @@ -128,6 +128,14 @@ Type: `boolean` Skip creating spec files. +### standaloneConfig + +Default: `false` + +Type: `boolean` + +Split the project configuration into /project.json rather than including it inside workspace.json + ### strict Default: `true` @@ -142,7 +150,7 @@ Default: `css` Type: `string` -Possible values: `css`, `scss`, `styl`, `less` +Possible values: `css`, `scss`, `less` The file extension to be used for style files. diff --git a/nx-dev/nx-dev/public/documentation/latest/angular/api-angular/generators/downgrade-module.md b/nx-dev/nx-dev/public/documentation/latest/angular/api-angular/generators/downgrade-module.md index bf61edc6e0..0112606aba 100644 --- a/nx-dev/nx-dev/public/documentation/latest/angular/api-angular/generators/downgrade-module.md +++ b/nx-dev/nx-dev/public/documentation/latest/angular/api-angular/generators/downgrade-module.md @@ -1,6 +1,6 @@ # downgrade-module -Setup Downgrade Module +Setup Downgrade Module. ## Usage @@ -40,7 +40,7 @@ The name of the main AngularJS module. Type: `string` -The name of the project +The name of the project. ### skipFormat @@ -48,7 +48,7 @@ Default: `false` Type: `boolean` -Skip formatting files +Skip formatting files. ### skipPackageJson @@ -56,4 +56,4 @@ Default: `false` Type: `boolean` -Do not add @angular/upgrade to package.json (e.g., --skipPackageJson) +Do not add @angular/upgrade to package.json (e.g., --skipPackageJson). diff --git a/nx-dev/nx-dev/public/documentation/latest/angular/api-angular/generators/library.md b/nx-dev/nx-dev/public/documentation/latest/angular/api-angular/generators/library.md index c4987372f8..08495ee7c3 100644 --- a/nx-dev/nx-dev/public/documentation/latest/angular/api-angular/generators/library.md +++ b/nx-dev/nx-dev/public/documentation/latest/angular/api-angular/generators/library.md @@ -150,6 +150,14 @@ Type: `boolean` Do not update tsconfig.json for development experience. +### standaloneConfig + +Default: `false` + +Type: `boolean` + +Split the project configuration into /project.json rather than including it inside workspace.json + ### strict Default: `true` diff --git a/nx-dev/nx-dev/public/documentation/latest/angular/api-angular/generators/ngrx.md b/nx-dev/nx-dev/public/documentation/latest/angular/api-angular/generators/ngrx.md index 2b80efe29e..f4a49fdd4c 100644 --- a/nx-dev/nx-dev/public/documentation/latest/angular/api-angular/generators/ngrx.md +++ b/nx-dev/nx-dev/public/documentation/latest/angular/api-angular/generators/ngrx.md @@ -1,6 +1,6 @@ # ngrx -Add an ngrx config to a project +Add NgRx support to an application or library. ## Usage @@ -66,23 +66,27 @@ The path to NgModule where the feature state will be registered. The host direct Type: `string` -Name of the NgRx feature state, such as "products" or "users"). Recommended to use the plural form of the name. +Name of the NgRx feature state, such as `products` or `users`. Recommended to use the plural form of the name. -### onlyAddFiles +### ~~onlyAddFiles~~ Default: `false` Type: `boolean` -**Deprecated**, use `skipImport`. Only add new NgRx files, without changing the module file (e.g., --onlyAddFiles). +**Deprecated:** Use the `skipImport` option instead. -### onlyEmptyRoot +Only add new NgRx files, without changing the module file (e.g., --onlyAddFiles). + +### ~~onlyEmptyRoot~~ Default: `false` Type: `boolean` -**Deprecated**, use `minimal`. Do not generate any files. Only generate StoreModule.forRoot and EffectsModule.forRoot (e.g., --onlyEmptyRoot). +**Deprecated:** Use the `minimal` option instead. + +Do not generate any files. Only generate StoreModule.forRoot and EffectsModule.forRoot (e.g., --onlyEmptyRoot). ### root diff --git a/nx-dev/nx-dev/public/documentation/latest/angular/api-angular/generators/upgrade-module.md b/nx-dev/nx-dev/public/documentation/latest/angular/api-angular/generators/upgrade-module.md index 5ef0b73705..9bbc95c372 100644 --- a/nx-dev/nx-dev/public/documentation/latest/angular/api-angular/generators/upgrade-module.md +++ b/nx-dev/nx-dev/public/documentation/latest/angular/api-angular/generators/upgrade-module.md @@ -1,6 +1,6 @@ # upgrade-module -Add an upgrade module +Add an upgrade module. ## Usage @@ -28,7 +28,7 @@ nx g upgrade-module ... --dry-run Type: `string` -The selector of an AngularJS component (e.g., --angularJsCmpSelector=myComponent) +The selector of an AngularJS component (e.g., --angularJsCmpSelector=myComponent). ### angularJsImport @@ -46,7 +46,7 @@ The name of the main AngularJS module. Type: `string` -The name of the project +The name of the project. ### router @@ -54,7 +54,7 @@ Default: `false` Type: `boolean` -Sets up router synchronization (e.g., --router) +Sets up router synchronization (e.g., --router). ### skipFormat @@ -62,7 +62,7 @@ Default: `false` Type: `boolean` -Skip formatting files +Skip formatting files. ### skipPackageJson @@ -70,4 +70,4 @@ Default: `false` Type: `boolean` -Do not add @angular/upgrade to package.json (e.g., --skipPackageJson) +Do not add @angular/upgrade to package.json (e.g., --skipPackageJson). diff --git a/nx-dev/nx-dev/public/documentation/latest/angular/api-angular/generators/web-worker.md b/nx-dev/nx-dev/public/documentation/latest/angular/api-angular/generators/web-worker.md new file mode 100644 index 0000000000..bee7e29698 --- /dev/null +++ b/nx-dev/nx-dev/public/documentation/latest/angular/api-angular/generators/web-worker.md @@ -0,0 +1,59 @@ +# web-worker + +Create a Web Worker. + +## Usage + +```bash +nx generate web-worker ... +``` + +By default, Nx will search for `web-worker` in the default collection provisioned in `angular.json`. + +You can specify the collection explicitly as follows: + +```bash +nx g @nrwl/angular:web-worker ... +``` + +Show what will be generated without writing to disk: + +```bash +nx g web-worker ... --dry-run +``` + +## Options + +### name + +Type: `string` + +The name of the worker. + +### path + +Type: `string` + +The path at which to create the worker file, relative to the current workspace. + +### project + +Type: `string` + +The name of the project. + +### skipFormat + +Default: `false` + +Type: `boolean` + +Skip formatting files. + +### snippet + +Default: `true` + +Type: `boolean` + +Add a worker creation snippet in a sibling file of the same name. diff --git a/nx-dev/nx-dev/public/documentation/latest/angular/api-express/generators/application.md b/nx-dev/nx-dev/public/documentation/latest/angular/api-express/generators/application.md index fa4f5a0ae5..8e49680aa1 100644 --- a/nx-dev/nx-dev/public/documentation/latest/angular/api-express/generators/application.md +++ b/nx-dev/nx-dev/public/documentation/latest/angular/api-express/generators/application.md @@ -98,6 +98,14 @@ Type: `boolean` Do not add dependencies to package.json. +### standaloneConfig + +Default: `false` + +Type: `boolean` + +Split the project configuration into /project.json rather than including it inside workspace.json + ### tags Type: `string` diff --git a/nx-dev/nx-dev/public/documentation/latest/angular/api-gatsby/generators/application.md b/nx-dev/nx-dev/public/documentation/latest/angular/api-gatsby/generators/application.md index ed72dbe620..bb5cb750ab 100644 --- a/nx-dev/nx-dev/public/documentation/latest/angular/api-gatsby/generators/application.md +++ b/nx-dev/nx-dev/public/documentation/latest/angular/api-gatsby/generators/application.md @@ -66,6 +66,14 @@ Type: `boolean` Whether or not to configure the ESLint "parserOptions.project" option. We do not do this by default for lint performance reasons. +### standaloneConfig + +Default: `false` + +Type: `boolean` + +Split the project configuration into /project.json rather than including it inside workspace.json + ### style Alias(es): s diff --git a/nx-dev/nx-dev/public/documentation/latest/angular/api-nest/generators/application.md b/nx-dev/nx-dev/public/documentation/latest/angular/api-nest/generators/application.md index a8033843a3..67dedc1057 100644 --- a/nx-dev/nx-dev/public/documentation/latest/angular/api-nest/generators/application.md +++ b/nx-dev/nx-dev/public/documentation/latest/angular/api-nest/generators/application.md @@ -72,6 +72,14 @@ Type: `boolean` Do not add dependencies to package.json. +### standaloneConfig + +Default: `false` + +Type: `boolean` + +Split the project configuration into /project.json rather than including it inside workspace.json + ### tags Type: `string` diff --git a/nx-dev/nx-dev/public/documentation/latest/angular/api-next/generators/application.md b/nx-dev/nx-dev/public/documentation/latest/angular/api-next/generators/application.md index 292a04726d..669219336d 100644 --- a/nx-dev/nx-dev/public/documentation/latest/angular/api-next/generators/application.md +++ b/nx-dev/nx-dev/public/documentation/latest/angular/api-next/generators/application.md @@ -108,6 +108,14 @@ Type: `boolean` Skip updating workspace.json with default options based on values provided to this app (e.g. babel, style) +### standaloneConfig + +Default: `false` + +Type: `boolean` + +Split the project configuration into /project.json rather than including it inside workspace.json + ### style Alias(es): s diff --git a/nx-dev/nx-dev/public/documentation/latest/angular/api-node/generators/application.md b/nx-dev/nx-dev/public/documentation/latest/angular/api-node/generators/application.md index f187df290d..2d4718b74f 100644 --- a/nx-dev/nx-dev/public/documentation/latest/angular/api-node/generators/application.md +++ b/nx-dev/nx-dev/public/documentation/latest/angular/api-node/generators/application.md @@ -106,6 +106,14 @@ Type: `boolean` Do not add dependencies to package.json. +### standaloneConfig + +Default: `false` + +Type: `boolean` + +Split the project configuration into /project.json rather than including it inside workspace.json + ### tags Type: `string` diff --git a/nx-dev/nx-dev/public/documentation/latest/angular/api-node/generators/library.md b/nx-dev/nx-dev/public/documentation/latest/angular/api-node/generators/library.md index bffb37794f..f8b89989f7 100644 --- a/nx-dev/nx-dev/public/documentation/latest/angular/api-node/generators/library.md +++ b/nx-dev/nx-dev/public/documentation/latest/angular/api-node/generators/library.md @@ -138,6 +138,14 @@ Type: `boolean` Do not update tsconfig.base.json for development experience. +### standaloneConfig + +Default: `false` + +Type: `boolean` + +Split the project configuration into /project.json rather than including it inside workspace.json + ### strict Default: `false` diff --git a/nx-dev/nx-dev/public/documentation/latest/angular/api-nx-devkit/index.md b/nx-dev/nx-dev/public/documentation/latest/angular/api-nx-devkit/index.md index 22d4c4c357..9346199a10 100644 --- a/nx-dev/nx-dev/public/documentation/latest/angular/api-nx-devkit/index.md +++ b/nx-dev/nx-dev/public/documentation/latest/angular/api-nx-devkit/index.md @@ -60,9 +60,11 @@ - [applyChangesToString](../../angular/nx-devkit/index#applychangestostring) - [convertNxExecutor](../../angular/nx-devkit/index#convertnxexecutor) - [convertNxGenerator](../../angular/nx-devkit/index#convertnxgenerator) +- [detectPackageManager](../../angular/nx-devkit/index#detectpackagemanager) - [formatFiles](../../angular/nx-devkit/index#formatfiles) - [generateFiles](../../angular/nx-devkit/index#generatefiles) - [getPackageManagerCommand](../../angular/nx-devkit/index#getpackagemanagercommand) +- [getPackageManagerVersion](../../angular/nx-devkit/index#getpackagemanagerversion) - [getProjects](../../angular/nx-devkit/index#getprojects) - [getWorkspaceLayout](../../angular/nx-devkit/index#getworkspacelayout) - [getWorkspacePath](../../angular/nx-devkit/index#getworkspacepath) @@ -473,7 +475,7 @@ Callback to install dependencies only if necessary. undefined is returned if cha ### addProjectConfiguration -▸ **addProjectConfiguration**(`host`: [_Tree_](../../angular/nx-devkit/index#tree), `projectName`: _string_, `projectConfiguration`: [_ProjectConfiguration_](../../angular/nx-devkit/index#projectconfiguration) & [_NxJsonProjectConfiguration_](../../angular/nx-devkit/index#nxjsonprojectconfiguration)): _void_ +▸ **addProjectConfiguration**(`host`: [_Tree_](../../angular/nx-devkit/index#tree), `projectName`: _string_, `projectConfiguration`: [_ProjectConfiguration_](../../angular/nx-devkit/index#projectconfiguration) & [_NxJsonProjectConfiguration_](../../angular/nx-devkit/index#nxjsonprojectconfiguration), `standalone?`: _boolean_): _void_ Adds project configuration to the Nx workspace. @@ -482,11 +484,12 @@ both files. #### Parameters -| Name | Type | Description | -| :--------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------- | -| `host` | [_Tree_](../../angular/nx-devkit/index#tree) | the file system tree | -| `projectName` | _string_ | unique name. Often directories are part of the name (e.g., mydir-mylib) | -| `projectConfiguration` | [_ProjectConfiguration_](../../angular/nx-devkit/index#projectconfiguration) & [_NxJsonProjectConfiguration_](../../angular/nx-devkit/index#nxjsonprojectconfiguration) | project configuration | +| Name | Type | Default value | Description | +| :--------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------ | :----------------------------------------------------------------------------------------- | +| `host` | [_Tree_](../../angular/nx-devkit/index#tree) | - | the file system tree | +| `projectName` | _string_ | - | unique name. Often directories are part of the name (e.g., mydir-mylib) | +| `projectConfiguration` | [_ProjectConfiguration_](../../angular/nx-devkit/index#projectconfiguration) & [_NxJsonProjectConfiguration_](../../angular/nx-devkit/index#nxjsonprojectconfiguration) | - | project configuration | +| `standalone` | _boolean_ | false | should the project use package.json? If false, the project config is inside workspace.json | **Returns:** _void_ @@ -577,6 +580,22 @@ Convert an Nx Generator into an Angular Devkit Schematic --- +### detectPackageManager + +▸ **detectPackageManager**(`dir?`: _string_): [_PackageManager_](../../angular/nx-devkit/index#packagemanager) + +Detects which package manager is used in the workspace based on the lock file. + +#### Parameters + +| Name | Type | Default value | +| :---- | :------- | :------------ | +| `dir` | _string_ | '' | + +**Returns:** [_PackageManager_](../../angular/nx-devkit/index#packagemanager) + +--- + ### formatFiles ▸ **formatFiles**(`host`: [_Tree_](../../angular/nx-devkit/index#tree)): _Promise_ @@ -634,7 +653,7 @@ doesn't get confused about incorrect TypeScript files. ### getPackageManagerCommand -▸ **getPackageManagerCommand**(`packageManager?`: [_PackageManager_](../../angular/nx-devkit/index#packagemanager)): _object_ +▸ **getPackageManagerCommand**(`packageManager?`: [_PackageManager_](../../angular/nx-devkit/index#packagemanager)): PackageManagerCommands Returns commands for the package manager used in the workspace. By default, the package manager is derived based on the lock file, @@ -652,17 +671,25 @@ execSync(`${getPackageManagerCommand().addDev} my-dev-package`); | :--------------- | :--------------------------------------------------------------- | | `packageManager` | [_PackageManager_](../../angular/nx-devkit/index#packagemanager) | -**Returns:** _object_ +**Returns:** PackageManagerCommands -| Name | Type | -| :-------- | :------------------------------------------------- | -| `add` | _string_ | -| `addDev` | _string_ | -| `exec` | _string_ | -| `install` | _string_ | -| `list` | _string_ | -| `rm` | _string_ | -| `run` | (`script`: _string_, `args`: _string_) => _string_ | +--- + +### getPackageManagerVersion + +▸ **getPackageManagerVersion**(`packageManager?`: [_PackageManager_](../../angular/nx-devkit/index#packagemanager)): _string_ + +Returns the version of the package manager used in the workspace. +By default, the package manager is derived based on the lock file, +but it can also be passed in explicitly. + +#### Parameters + +| Name | Type | +| :--------------- | :--------------------------------------------------------------- | +| `packageManager` | [_PackageManager_](../../angular/nx-devkit/index#packagemanager) | + +**Returns:** _string_ --- diff --git a/nx-dev/nx-dev/public/documentation/latest/angular/api-nx-plugin/generators/plugin.md b/nx-dev/nx-dev/public/documentation/latest/angular/api-nx-plugin/generators/plugin.md index 656fff8080..ea1023a339 100644 --- a/nx-dev/nx-dev/public/documentation/latest/angular/api-nx-plugin/generators/plugin.md +++ b/nx-dev/nx-dev/public/documentation/latest/angular/api-nx-plugin/generators/plugin.md @@ -78,6 +78,14 @@ Type: `boolean` Do not update tsconfig.json for development experience. +### standaloneConfig + +Default: `false` + +Type: `boolean` + +Split the project configuration into /project.json rather than including it inside workspace.json + ### tags Alias(es): t diff --git a/nx-dev/nx-dev/public/documentation/latest/angular/api-react/generators/application.md b/nx-dev/nx-dev/public/documentation/latest/angular/api-react/generators/application.md index 9845367f40..53173b4df3 100644 --- a/nx-dev/nx-dev/public/documentation/latest/angular/api-react/generators/application.md +++ b/nx-dev/nx-dev/public/documentation/latest/angular/api-react/generators/application.md @@ -150,6 +150,14 @@ Type: `boolean` Skip updating workspace.json with default options based on values provided to this app (e.g. babel, style). +### standaloneConfig + +Default: `false` + +Type: `boolean` + +Split the project configuration into /project.json rather than including it inside workspace.json + ### strict Default: `true` diff --git a/nx-dev/nx-dev/public/documentation/latest/angular/api-react/generators/library.md b/nx-dev/nx-dev/public/documentation/latest/angular/api-react/generators/library.md index a8ba5c65cb..629dd33712 100644 --- a/nx-dev/nx-dev/public/documentation/latest/angular/api-react/generators/library.md +++ b/nx-dev/nx-dev/public/documentation/latest/angular/api-react/generators/library.md @@ -158,6 +158,14 @@ Type: `boolean` Do not update tsconfig.json for development experience. +### standaloneConfig + +Default: `false` + +Type: `boolean` + +Split the project configuration into /project.json rather than including it inside workspace.json + ### strict Default: `true` diff --git a/nx-dev/nx-dev/public/documentation/latest/angular/api-react/generators/storybook-configuration.md b/nx-dev/nx-dev/public/documentation/latest/angular/api-react/generators/storybook-configuration.md index 0960cd8121..5def48cdd8 100644 --- a/nx-dev/nx-dev/public/documentation/latest/angular/api-react/generators/storybook-configuration.md +++ b/nx-dev/nx-dev/public/documentation/latest/angular/api-react/generators/storybook-configuration.md @@ -77,3 +77,11 @@ The tool to use for running lint checks. Type: `string` Project name + +### standaloneConfig + +Default: `false` + +Type: `boolean` + +Split the project configuration into /project.json rather than including it inside workspace.json diff --git a/nx-dev/nx-dev/public/documentation/latest/angular/api-storybook/generators/configuration.md b/nx-dev/nx-dev/public/documentation/latest/angular/api-storybook/generators/configuration.md index bbfd23285d..0b8b80da6c 100644 --- a/nx-dev/nx-dev/public/documentation/latest/angular/api-storybook/generators/configuration.md +++ b/nx-dev/nx-dev/public/documentation/latest/angular/api-storybook/generators/configuration.md @@ -60,6 +60,14 @@ Type: `string` Library or application name +### standaloneConfig + +Default: `false` + +Type: `boolean` + +Split the project configuration into /project.json rather than including it inside workspace.json + ### uiFramework Type: `string` diff --git a/nx-dev/nx-dev/public/documentation/latest/angular/api-storybook/generators/cypress-project.md b/nx-dev/nx-dev/public/documentation/latest/angular/api-storybook/generators/cypress-project.md index cb0211937b..5e75a55405 100644 --- a/nx-dev/nx-dev/public/documentation/latest/angular/api-storybook/generators/cypress-project.md +++ b/nx-dev/nx-dev/public/documentation/latest/angular/api-storybook/generators/cypress-project.md @@ -53,3 +53,11 @@ The tool to use for running lint checks. Type: `string` Library or application name + +### standaloneConfig + +Default: `false` + +Type: `boolean` + +Split the project configuration into /project.json rather than including it inside workspace.json diff --git a/nx-dev/nx-dev/public/documentation/latest/angular/api-web/generators/application.md b/nx-dev/nx-dev/public/documentation/latest/angular/api-web/generators/application.md index c7954c442c..d20d9fb8c1 100644 --- a/nx-dev/nx-dev/public/documentation/latest/angular/api-web/generators/application.md +++ b/nx-dev/nx-dev/public/documentation/latest/angular/api-web/generators/application.md @@ -76,6 +76,14 @@ Type: `boolean` Skip formatting files +### standaloneConfig + +Default: `false` + +Type: `boolean` + +Split the project configuration into /project.json rather than including it inside workspace.json + ### style Default: `css` diff --git a/nx-dev/nx-dev/public/documentation/latest/angular/api-workspace/generators/convert-to-nx-project.md b/nx-dev/nx-dev/public/documentation/latest/angular/api-workspace/generators/convert-to-nx-project.md new file mode 100644 index 0000000000..2373901192 --- /dev/null +++ b/nx-dev/nx-dev/public/documentation/latest/angular/api-workspace/generators/convert-to-nx-project.md @@ -0,0 +1,51 @@ +# convert-to-nx-project + +Moves a project's configuration outside of workspace.json + +## Usage + +```bash +nx generate convert-to-nx-project ... +``` + +By default, Nx will search for `convert-to-nx-project` in the default collection provisioned in `angular.json`. + +You can specify the collection explicitly as follows: + +```bash +nx g @nrwl/workspace:convert-to-nx-project ... +``` + +Show what will be generated without writing to disk: + +```bash +nx g convert-to-nx-project ... --dry-run +``` + +### Examples + +Convert the my-feature-lib project to use project.json file instead of workspace.json: + +```bash +nx g @nrwl/workspace:convert-to-nx-project --project my-feature-lib +``` + +Convert all projects in workspace.json to separate project.json files.: + +```bash +nx g @nrwl/workspace:convert-to-nx-project --all +``` + +## Options + +### all + +Type: `boolean` + +Should every project be converted? + +### project + +Type: `string` + +Project name diff --git a/nx-dev/nx-dev/public/documentation/latest/angular/api-workspace/generators/library.md b/nx-dev/nx-dev/public/documentation/latest/angular/api-workspace/generators/library.md index ff8fcffd4e..5ef0a69ab5 100644 --- a/nx-dev/nx-dev/public/documentation/latest/angular/api-workspace/generators/library.md +++ b/nx-dev/nx-dev/public/documentation/latest/angular/api-workspace/generators/library.md @@ -130,6 +130,14 @@ Type: `boolean` Do not update tsconfig.json for development experience. +### standaloneConfig + +Default: `false` + +Type: `boolean` + +Split the project configuration into /project.json rather than including it inside workspace.json + ### strict Default: `false` diff --git a/nx-dev/nx-dev/public/documentation/latest/angular/cli/affected-dep-graph.md b/nx-dev/nx-dev/public/documentation/latest/angular/cli/affected-dep-graph.md index 1f5311aa42..e96515443d 100644 --- a/nx-dev/nx-dev/public/documentation/latest/angular/cli/affected-dep-graph.md +++ b/nx-dev/nx-dev/public/documentation/latest/angular/cli/affected-dep-graph.md @@ -131,3 +131,9 @@ Print additional error stack trace on failure ### version Show version number + +### watch + +Default: `false` + +Watch for changes to dep graph and update in-browser diff --git a/nx-dev/nx-dev/public/documentation/latest/angular/cli/dep-graph.md b/nx-dev/nx-dev/public/documentation/latest/angular/cli/dep-graph.md index 7de42387d7..8db615a505 100644 --- a/nx-dev/nx-dev/public/documentation/latest/angular/cli/dep-graph.md +++ b/nx-dev/nx-dev/public/documentation/latest/angular/cli/dep-graph.md @@ -54,6 +54,12 @@ Show the graph where every node is either an ancestor or a descendant of todos-f nx dep-graph --focus=todos-feature-main --exclude=project-one,project-two ``` +Watch for changes to dep graph and update in-browser: + +```bash +nx dep-graph --watch +``` + ## Options ### exclude @@ -87,3 +93,9 @@ Bind the dep graph server to a specific port. ### version Show version number + +### watch + +Default: `false` + +Watch for changes to dep graph and update in-browser diff --git a/nx-dev/nx-dev/public/documentation/latest/angular/generators/composing-generators.md b/nx-dev/nx-dev/public/documentation/latest/angular/generators/composing-generators.md new file mode 100644 index 0000000000..6d289141e6 --- /dev/null +++ b/nx-dev/nx-dev/public/documentation/latest/angular/generators/composing-generators.md @@ -0,0 +1,39 @@ +# Composing Generators + +Generators are useful individually, but reusing and composing generators allows you to build whole workflows out of simpler building blocks. + +## Using Nx Devkit Generators + +Nx Devkit generators can be imported and invoked like any javascript function. They often return a `Promise`, so they can be used with the `await` keyword to mimic synchronous code. Because this is standard javascript, control flow logic can be adjusted with `if` blocks and `for` loops as usual. + +```typescript +import { libraryGenerator } from '@nrwl/workspace'; + +export default async function (tree: Tree, schema: any) { + await libraryGenerator( + tree, // virtual file system tree + { name: schema.name } // options for the generator + ); +} +``` + +## Using Angular Devkit Schematics + +If you need to use a generator written with the Angular devkit (also known as a schematic) inside of an Nx devkit generator, you need to wrap the schematic inside the `wrapAngularDevkitSchematic` function. + +Note: All Nrwl maintained schematics have been migrated over to the Nx Devkit, so this should only be necessary for third party schematics. + +```typescript +import { wrapAngularDevkitSchematic } from '@nrwl/devkit/ngcli-adapter'; + +export default async function (tree: Tree, schema: any) { + const libraryGenerator = wrapAngularDevkitSchematic( + '@nrwl/angular', // plugin name + 'lib' // schematic name + ); + await libraryGenerator( + tree, // virtual file system tree + { name: schema.name } // options for the generator + ); +} +``` diff --git a/nx-dev/nx-dev/public/documentation/latest/angular/generators/using-generators.md b/nx-dev/nx-dev/public/documentation/latest/angular/generators/using-generators.md new file mode 100644 index 0000000000..c842f48632 --- /dev/null +++ b/nx-dev/nx-dev/public/documentation/latest/angular/generators/using-generators.md @@ -0,0 +1,28 @@ +# Using Generators + +## Overview + +Generators provide a way to automate many tasks you regularly perform as part of your development workflow. Whether it is scaffolding out components, features, ensuring libraries are generated and structured in a certain way, or updating your configuration files, generators help you standardize these tasks in a consistent, and predictable manner. + +Generators can be written using `@nrwl/devkit` or `@angular-devkit`. Generators written with the `@angular-devkit` are called schematics. To read more about the concepts of `@angular-devkit` schematics, and building an example schematic, see the [Schematics Authoring Guide](https://angular.io/guide/schematics-authoring). + +The [Workspace Generators](/{{framework}}/generators/workspace-generators) guide shows you how to create, run, and customize workspace generators within your Nx workspace. + +## Types of Generators + +There are three main types of generators: + +1. **Plugin Generators** are available when an Nx plugin has been installed in your workspace. +2. **Workspace Generators** are generators that you can create for your own workspace. [Workspace generators](/{{framework}}/generators/workspace-generators) allow you to codify the processes that are unique to your own organization. +3. **Update Generators** are invoked by Nx plugins when you [update Nx](/{{framework}}/core-concepts/updating-nx) to keep your config files in sync with the latest versions of third party tools. + +## Invoking Plugin Generators + +Generators allow you to create or modify your codebase in a simple and repeatable way. Generators are invoked using the [`nx generate`](/{{framework}}/cli/generate) command. + +```bash +nx generate [plugin]:[generator-name] [options] +nx generate @nrwl/react:component mycmp --project=myapp +``` + +It is important to have a clean git working directory before invoking a generator so that you can easily revert changes and re-invoke the generator with different inputs. diff --git a/nx-dev/nx-dev/public/documentation/latest/angular/generators/workspace-generators.md b/nx-dev/nx-dev/public/documentation/latest/angular/generators/workspace-generators.md new file mode 100644 index 0000000000..0bce4cdbdf --- /dev/null +++ b/nx-dev/nx-dev/public/documentation/latest/angular/generators/workspace-generators.md @@ -0,0 +1,107 @@ +# Workspace Generators + +Workspace generators provide a way to automate many tasks you regularly perform as part of your development workflow. Whether it is scaffolding out components, features, or ensuring libraries are generated and structured in a certain way, generators help you standardize these tasks in a consistent, and predictable manner. Nx provides tooling around creating, and running custom generators from within your workspace. This guide shows you how to create, run, and customize workspace generators within your Nx workspace. + +## Creating a workspace generator + +Use the Nx CLI to generate the initial files needed for your workspace generator. + +```bash +nx generate @nrwl/workspace:workspace-generator my-generator +``` + +After the command is finished, the workspace generator is created under the `tools/generators` folder. + +```treeview +happynrwl/ +├── apps/ +├── libs/ +├── tools/ +│ ├── generators +│ | └── my-generator/ +│ | | ├── index.ts +│ | | └── schema.json +├── nx.json +├── package.json +└── tsconfig.base.json +``` + +The `index.ts` provides an entry point to the generator. The file contains a function that is called to perform manipulations on a tree that represents the file system. +The `schema.json` provides a description of the generator, available options, validation information, and default values. + +The initial generator function creates a library. + +```typescript +import { Tree, formatFiles, installPackagesTask } from '@nrwl/devkit'; +import { libraryGenerator } from '@nrwl/workspace'; + +export default async function (tree: Tree, schema: any) { + await libraryGenerator(tree, { name: schema.name }); + await formatFiles(tree); + return () => { + installPackagesTask(tree); + }; +} +``` + +To invoke other generators, import the entry point function and run it against the tree tree. `async/await` can be used to make code with Promises read like procedural code. The generator function may return a callback function that is executed after changes to the file system have been applied. + +In the schema.json file for your generator, the `name` is provided as a default option. The `cli` property is set to `nx` to signal that this is a generator that uses `@nrwl/devkit` and not `@angular-devkit`. + +```json +{ + "cli": "nx", + "id": "test", + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Library name", + "$default": { + "$source": "argv", + "index": 0 + } + } + }, + "required": ["name"] +} +``` + +The `$default` object is used to read arguments from the command-line that are passed to the generator. The first argument passed to this schematic is used as the `name` property. + +## Running a workspace generator + +To run a generator, invoke the `nx workspace-generator` command with the name of the generator. + +```bash +nx workspace-generator my-generator mylib +``` + +## Running a workspace schematic created with @angular-devkit + +Generators that are created using the `@angular-devkit` are called schematics. Workspace schematics that have been created with the `@angular-devkit` will omit the `"cli": "nx"` property in `schema.json`. Nx will recognize this and correctly run the schematic using the same command as an `@nrwl/devkit` generator. + +```bash +nx workspace-generator my-schematic mylib +``` + +The command is also aliased to the previous `workspace-schematic` command, so this still works: + +```bash +nx workspace-schematic my-schematic mylib +``` + +## Debugging Workspace generators + +### With Visual Studio Code + +1. Open the Command Palette and choose `Debug: Create JavaScript Debug Terminal`. + This will open a terminal with debugging enabled. +2. Set breakpoints in your code +3. Run `nx workspace-generator my-generator` in the debug terminal. + +![](/shared/vscode-schematics-debug.png) + +## Workspace Generator Utilities + +The `@nrwl/devkit` package provides many utility functions that can be used in schematics to help with modifying files, reading and updating configuration files, and working with an Abstract Syntax Tree (AST). diff --git a/nx-dev/nx-dev/public/documentation/latest/angular/getting-started/intro.md b/nx-dev/nx-dev/public/documentation/latest/angular/getting-started/intro.md index 2c470947be..7be0315e67 100644 --- a/nx-dev/nx-dev/public/documentation/latest/angular/getting-started/intro.md +++ b/nx-dev/nx-dev/public/documentation/latest/angular/getting-started/intro.md @@ -17,7 +17,7 @@ Nx works especially well for [monorepos](/{{framework}}/core-concepts/why-monore ## Features - Test (or builds or lints) only the projects [affected](/{{framework}}/cli/affected) by a code change. -- [Cache](/{{framework}}/core-concepts/computation-caching) command output locally so that future runs on the same code happen in seconds. The paid [Nx Cloud](https://nx.app) offering allows this cache to be shared across every developer in your organization. +- [Cache](/{{framework}}/core-extended/computation-caching) command output locally so that future runs on the same code happen in seconds. The paid [Nx Cloud](https://nx.app) offering allows this cache to be shared across every developer in your organization. - Provide a consistent syntax for [executing commands](/{{framework}}/executors/using-builders). `nx build my-app` works no matter what framework `my-app` uses. - Automate code modification tasks with [generators](/{{framework}}/cli/affected). - Access a thriving ecosystem of [plugins](/{{framework}}/generators/using-schematics) from Nrwl and the [community](/community). @@ -32,5 +32,5 @@ Nx works especially well for [monorepos](/{{framework}}/core-concepts/why-monore - [Nx CLI](/{{framework}}/getting-started/nx-cli) - [Configuration Files](/{{framework}}/core-concepts/configuration) -- [Computation Caching](/{{framework}}/core-concepts/computation-caching) -- [Rebuilding What is Affected](/{{framework}}/core-concepts/affected) +- [Computation Caching](/{{framework}}/core-extended/computation-caching) +- [Rebuilding What is Affected](/{{framework}}/core-extended/affected) diff --git a/nx-dev/nx-dev/public/documentation/latest/angular/getting-started/nx-cli.md b/nx-dev/nx-dev/public/documentation/latest/angular/getting-started/nx-cli.md index 765cf5b30c..9922dd0781 100644 --- a/nx-dev/nx-dev/public/documentation/latest/angular/getting-started/nx-cli.md +++ b/nx-dev/nx-dev/public/documentation/latest/angular/getting-started/nx-cli.md @@ -41,15 +41,6 @@ nx workspace-generator my-generator [The first command](/{{framework}}/cli/generate) scaffolds a new customizable workspace generator named `my-generator` and [the second command](/{{framework}}/cli/workspace-generator) invokes it. -**Update plugins:** - -```bash -nx migrate latest -nx migrate --run-migrations=migrations.json -``` - -[The first command](/{{framework}}/cli/migrate) updates the installed Nx plugin versions and creates a list of generators to keep configuration files up to date. [The second command](/{{framework}}/cli/migrate) invokes those generators. - **Run an executor on one project:** ```bash @@ -57,7 +48,15 @@ nx run my-app:build nx build my-app ``` -Both of [these commands](/{{framework}}/cli/run) build the `my-app` application. Custom executors need to use the more verbose `nx run project:target` syntax. See the [workspace.json documentation](/{{framework}}/core-concepts/configuration) for information on configuring executor options. +Both of [these commands](/{{framework}}/cli/run) build the `my-app` application. See the [workspace.json documentation](/{{framework}}/core-concepts/configuration) for information on configuring executor options. + +**Run an executor for many projects:** + +```bash +nx run-many --target=build --projects=app1,app2 +``` + +[This command](/{{framework}}/cli/run-many) builds `app1` and `app2`. **Run an executor for all affected projects:** @@ -71,10 +70,11 @@ nx affected --target=build ```bash nx dep-graph +nx dep-graph --watch nx affected:dep-graph ``` -[The first command](/{{framework}}/cli/dep-graph) launches a web browser with repository's dependency graph rendered visually. [The second command](/{{framework}}/cli/affected-dep-graph) renders the same graph with projects affected by the current code change highlighted. +[The first command](/{{framework}}/cli/dep-graph) launches a web browser with repository's dependency graph rendered visually. You can add the `--watch` flag to watch for changes to the dep grpah and update the view in-browser. [The second command](/{{framework}}/cli/affected-dep-graph) renders the same graph with projects affected by the current code change highlighted. **List installed plugins:** @@ -84,6 +84,20 @@ nx list [This command](/{{framework}}/cli/list) lists the currently installed Nx plugins and shows other plugins that are available. +**Update plugins:** + +```bash +nx migrate latest +nx migrate --run-migrations=migrations.json +``` + +[The first command](/{{framework}}/cli/migrate) updates the installed Nx plugin versions and creates a list of generators to keep configuration files up to date. [The second command](/{{framework}}/cli/migrate) invokes those generators. + +## Common Env Variables + +- Setting **NX_VERBOSE_LOGGING=true** will print debug information useful for troubleshooting. +- Setting **NX_PERF_LOGGING=true** will print debug information useful for profiling executors and Nx itself. + ## Nx and Angular CLI Nx supports Angular Devkit. When you run `nx build myapp`, and the build target for `myapp` is implemented using Angular Devkit, Nx behaves exactly the same as the Angular CLI. When you run `nx g component mycmp`, once again, Nx invokes the same schematic. You can think of Nx wrapping the Angular CLI. The results of running commands produces the same result, except that running `nx` is often a lot faster. diff --git a/nx-dev/nx-dev/public/documentation/latest/angular/guides/configuration.md b/nx-dev/nx-dev/public/documentation/latest/angular/guides/configuration.md index 515cac921a..fa5cf56a96 100644 --- a/nx-dev/nx-dev/public/documentation/latest/angular/guides/configuration.md +++ b/nx-dev/nx-dev/public/documentation/latest/angular/guides/configuration.md @@ -17,6 +17,12 @@ The `angular.json` configuration file contains information about the targets and "build": { "builder": "@nrwl/web:build", "outputs": ["dist/apps/myapp"], + "dependsOn": [ + { + "target": "build", + "projects": "dependencies" + } + ], "options": { "index": "apps/myapp/src/app.html", "main": "apps/myapp/src/main.ts" @@ -88,6 +94,8 @@ For instance, the following configures `mylib`. > Nx uses the architect library built by the Angular team at Google. The naming reflects that. Important to note: it's a general purpose library that **does not** have any dependency on Angular. +> Projects utilizing `project.json` files will not be present in `angular.json`. + ### Targets Let's look at the simple architect target: @@ -106,7 +114,7 @@ Let's look at the simple architect target: **Target Name** -The name of the target `test` means that you can invoke it as follows: `nx test mylib` or `nx run mylib:test`. The name isn't significant in any other way. If you rename it to, for example, `mytest`, you will be able to run as follows: `nx run mylib:mytest`. +The name of the target `test` means that you can invoke it as follows: `nx test mylib` or `nx run mylib:test`. The name isn't significant in any other way. If you rename it to, for example, `mytest`, you will be able to run as follows: `nx mytest mylib` or `nx run mylib:mytest`. **Builder** @@ -172,6 +180,66 @@ require(`@nrwl/jest`).builders['jest']({...options, ...selectedConfiguration, .. The selected configuration adds/overrides the default options, and the provided command line args add/override the configuration options. +**Target Dependencies** + +Targets can depend on other targets. A common scenario is having to build dependencies of a project first before building the project. You can specify this using the `dependsOn`. + +```json +{ + "build": { + "executor": "@nrwl/web:build", + "outputs": ["dist/apps/myapp"], + "options": { + "index": "apps/myapp/src/app.html", + "main": "apps/myapp/src/main.ts" + }, + "dependsOn": [ + { + "target": "build", + "projects": "dependencies" + } + ] + } +} +``` + +In this case, running `nx build myapp` will build all the buildable libraries `myapp` depends on first. In other words, `nx build myapp` will result in multiple tasks executing. The `--parallel`, and `--max-parallel` flags will have the same effect as they would with `run-many` or `affected`. + +It is also possible to define dependencies between the targets of the same project. + +In the following example invoking `nx build myapp` will build all the libraries first, then `nx build-base myapp` will be executed and only then `nx build myapp` will be executed. + +```json +{ + "build-base": { + "executor": "@nrwl/web:build", + "outputs": ["dist/apps/myapp"], + "options": { + "index": "apps/myapp/src/app.html", + "main": "apps/myapp/src/main.ts" + } + }, + "build": { + "executor": "@nrwl/workspace:run-commands", + "dependsOn": [ + { + "target": "build", + "projects": "dependencies" + }, + { + "target": "build-base", + "projects": "self" + } + ], + "options": { + "command": "./copy-readme-and-license.sh" + } + } +} +``` + +Often the same `dependsOn` configuration has to be defined for every project in the repo. You can define it once in `nx.json` (see below). + ### Generators Generators that are created using `@angular-devkit` are called schematics. You can configure default generator options in `angular.json` as well. For instance, the following will tell Nx to always pass `--style=scss` when creating new libraries. @@ -202,6 +270,33 @@ The following command will generate a new library: `nx g @nrwl/angular:lib mylib Your `angular.json` file can be renamed to `workspace.json` and Nx will process it in the same way. The `workspace.json` has one additional top level property `version`. Setting `version` to 1 means the `workspace.json` file syntax is identical to `angular.json` When the `version` of `workspace.json` is set to 2, `targets`, `generators` and `executor` properties are used instead of the version 1 properties `architect`, `schematics` and `builder`. +## project.json + +Project configurations can also be independent files, referenced by `angular.json`. For instance, an `angular.json` may contain projects configured as below. + +```json +{ + "projects": { + "mylib": "libs/mylib" + } +} +``` + +This tells Nx that all configuration for that project is found in the `libs/mylib/project.json` file. This file contains a combination of the project's configuration from both `angular.json` and `nx.json`. + +```json +{ + "mylib": { + "root": "libs/mylib/", + "sourceRoot": "libs/mylib/src", + "projectType": "library", + "targets": {}, + "tags": [], + "implicitDependencies": [] + } +} +``` + ## nx.json The `nx.json` file contains extra configuration options mostly related to the project graph. @@ -229,6 +324,14 @@ The `nx.json` file contains extra configuration options mostly related to the pr "tsconfig.base.json": "*", "nx.json": "*" }, + "targetDependencies": { + "build": [ + { + "target": "build", + "projects": "dependencies" + } + ] + }, "projects": { "myapp": { "tags": [] @@ -244,6 +347,8 @@ The `nx.json` file contains extra configuration options mostly related to the pr } ``` +> Projects utilizing `project.json` files will not be present in `nx.json`. + **NPM Scope** Tells Nx what prefix to use when generating library imports. @@ -352,9 +457,32 @@ You can also add dependencies between projects. For instance, the example below } ``` +### Target Dependencies + +Targets can depend on other targets. A common scenario is having to build dependencies of a project first before building the project. The `dependsOn` property in `workspace.json` can be used to define the list of dependencies of an individual target. + +Often the same `dependsOn` configuration has to be defined for every project in the repo, and that's when defining `targetDependencies` in `nx.json` is helpful. + +```json +{ + "targetDependencies": { + "build": [ + { + "target": "build", + "projects": "dependencies" + } + ] + } +} +``` + +The configuration above is identical to adding `{"dependsOn": [{"target": "build", "projects": "dependencies"]}` to every build target in `workspace.json`. + +The `dependsOn` property in `workspace.json` takes precedence over the `targetDependencies` in `nx.json`. + ## .nxignore -You may optionally add an `.nxignore` file to the root. This file is used to specify files in your workspace that should be completely ignored by nx. +You may optionally add an `.nxignore` file to the root. This file is used to specify files in your workspace that should be completely ignored by Nx. The syntax is the same as a [`.gitignore` file](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository#_ignoring). diff --git a/nx-dev/nx-dev/public/documentation/latest/angular/guides/storybook-plugin.md b/nx-dev/nx-dev/public/documentation/latest/angular/guides/storybook-plugin.md index 025d7f93cb..32892c3c72 100644 --- a/nx-dev/nx-dev/public/documentation/latest/angular/guides/storybook-plugin.md +++ b/nx-dev/nx-dev/public/documentation/latest/angular/guides/storybook-plugin.md @@ -394,13 +394,3 @@ Your folder structure should now look like this: ├── README.md └── etc... ``` - -### Storybook v6 args and controls - -Storybook v6 moves from "knobs" to args and controls when it comes to defining and manipulating your storybook -component properties. Feel free to use the new args way of defining stories. More can be found -[on the official Storybook docs](https://storybook.js.org/docs/angular/writing-stories/args). - -> **Note:** Nx does not yet automatically generate stories that use the args syntax. The main reason is that args don't -> yet support being loaded via the iframe URL which is used in Nx to setup your Storybook based e2e tests. Once support -> is present in Storybook v6, we will provide a way to generate args & controls based stories. More on the progress [here](https://github.com/storybookjs/storybook/issues/12291). diff --git a/nx-dev/nx-dev/public/documentation/latest/angular/guides/update.md b/nx-dev/nx-dev/public/documentation/latest/angular/guides/update.md index e20c638c65..eca39651e6 100644 --- a/nx-dev/nx-dev/public/documentation/latest/angular/guides/update.md +++ b/nx-dev/nx-dev/public/documentation/latest/angular/guides/update.md @@ -1,23 +1,23 @@ # Updating Nx -Nx provides the `migrate` command which help you stay up to date with the latest version of Nx. +The Nx CLI provides the `migrate` command to help you stay up to date with the latest version of Nx. -Not only `nx migrate` updates the version of Nx, but it also updates the versions of dependencies which we install such as jest and cypress. You can also use the `migrate` command to update any Nx plugin or any Angular package. +Not only does `nx migrate` update you to the latest version of Nx, but it also updates the versions of dependencies that we support and test such as Jest and Cypress. You can also use the `migrate` command to update any Nx plugin. -## What About "Ng Update?" +## What about "ng update?" -**TLDR: So if you are using Nx 10, run `nx migrate latest` instead of `ng update`.** +**TLDR: So if you are using Nx 10 or later, run `nx migrate latest` instead of `ng update`.** If you haven't used Nx before and used the Angular CLI, you probably ran `ng update`. What is the difference? `nx migrate` is a much improved version of `ng update`. It runs the same migrations, but allows you to: -- rerun the same migration multiple times -- reorder migrations -- skip migrations -- fix migrations that "almost work" -- commit a partially migrated state -- change versions of packages to match org requirements +- Rerun the same migration multiple times. +- Reorder migrations. +- Skip migrations. +- Fix migrations that "almost work". +- Commit a partially migrated state. +- Change versions of packages to match org requirements. And, in general, it is lot more reliable for non-trivial workspaces. Why? @@ -44,16 +44,16 @@ If you ran `ng update` and saw the error telling you to use `nx migrate`, do the - `npm install` (or `yarn install`) - `nx migrate --run-migrations=migrations.json` -## How to Migrate +## Migrating to the latest Nx version Migration happens in two steps: -- Updating `package.json` (and `node_modules`) -- Updating the source code of the repo to match the new versions of packages in `package.json` +- The installed dependencies are updated including the `package.json` (and `node_modules`). +- The source code in the repo is updated to match the new versions of packages in `package.json`. -### Step 1: Updating package.json and generating migrations.json +### Step 1: Updating dependencies and generating migrations -Run the following: +First, run the `migrate` command: ```bash nx migrate latest # same as nx migrate @nrwl/workspace@latest @@ -65,75 +65,81 @@ You can also specify the name of the package and the version: nx migrate @nrwl/workspace@version # you can also specify version ``` -This will fetch the specified version of `@nrwl/workspace`, analyze the dependencies and fetch all the dependent packages. The process will keep going until the whole tree of dependencies is resolved. This will result in: +This fetches the specified version of the `@nrwl/workspace` package, analyzes the dependencies and fetches all the dependent packages. The process keeps going until all the dependencies are resolved. This results in: -- `package.json` being updated -- `migrations.json` being generated +- The `package.json` being updated +- A `migrations.json` being generated if there are pending migrations. At this point, no packages have been installed, and no other files have been touched. -Now, you can inspect `package.json` to see if the changes make sense. Sometimes the migration can update some package to the version that is either not allowed or conflicts with with another package. Feel free to manually apply the desired adjustments. +Now, you can inspect `package.json` to see if the changes make sense. Sometimes the migration can update some package to the version that is either not allowed or conflicts with another package. Feel free to manually apply the desired adjustments. ### Step 2: Install the packages -After you are satisfied, make sure to actuall install the packages by running `npm install`, `yarn`, or `pnpm install`. +After inspecting the `package.json`, make sure to install the updated package versions by running `npm install`, `yarn`, or `pnpm install`. ### Step 3: Running migrations -Next, we need to update the repo to match the updated `package.json` and `node_modules`. Every Nx plugin comes with a set of migrations that describe how to update the workspace to make it work with the new version of the plugin. During Step 1 Nx looked at all of the packages being updated and collected their migrations into `migrations.json`. It's important to note that because Nx knows the from and to versions of every package, the `migrations.json` file only contains the relevant migrations. +Next, update the repo to match the updated `package.json` and `node_modules`. Every Nx plugin comes with a set of migrations that describe how to update the workspace to make it work with the new version of the plugin. During step one, Nx looked at all of the packages being updated and collected their migrations into `migrations.json`. It's important to note that because Nx knows the from and to versions of every package, the `migrations.json` file only contains the relevant migrations. -Each migration in `migrations.json` updates the source code in the repository. To run all the migrations in order, invoke: +Each migration in `migrations.json` updates the source code in the repository. To run all the migrations in order, run the following command: + +```bash +nx migrate --run-migrations +``` + +To specify a custom migrations file, pass it to the `--run-migrations` option: ```bash nx migrate --run-migrations=migrations.json ``` -For small projects, running all the migrations at once often succeeds without any issues. For large projects, more flexibility is sometimes needed: +For small projects, running all the migrations at once often succeeds without any issues. For large projects, more flexibility is needed: - You may have to skip a migration. - You may want to run one migration at a time to address minor issues. - You may want to reorder migrations. - You may want to run the same migration multiple time if the process takes a long time and you had to rebase. -Since you can run `nx migrate --run-migrations=migrations.json` as many times as you want, you can achieve all of that by commenting out and reordering items in `migrations.json`. The migrate process can take a long time, sometimes a day, so it can be useful to commit the migrations file with the partially-updated repo. +Because you can run `nx migrate --run-migrations` as many times as you want, you can achieve all of that by commenting out and reordering items in `migrations.json`. The migration process can take a long time, depending on the number of migrations, so it is useful to commit the migrations file with the partially-updated repo. ### Step 4: Cleaning up -After you run all the migrations, you can remove `migration.json` and commit the changes. +After you run all the migrations, you can remove `migrations.json` and commit the changes. -## Advanced Capabilities & Recommendations +## Advanced capabilities & recommendations -### One Major Version at a Time, Small Steps +### One major version at a time, small steps -Migrating Jest, Cypress, ESLint, React, Angular, Next etc... is a difficult task. All the tools change at different rates, they can conflict with each other etc.. In addition, every workspace is different. Even though our goal is to let you update any version of Nx to any other version in a single go, sometimes it doesn't work. The following process is better for large workspaces. +Migrating Jest, Cypress, ESLint, React, Angular, Next, and more is a difficult task. All the tools change at different rates, they can conflict with each other. In addition, every workspace is different. Even though our goal is for you to update any version of Nx to a newer version of Nx in a single go, sometimes it doesn't work. The following process is better for large workspaces. Say you want to migrate from Nx 10.1.0 to Nx 11.0.1. The following steps are more likely to work comparing to `nx migrate 11.0.1`. -- Run `nx migrate 10.4.5` to update the latest version in the 10x branch. -- Run `npm install` -- Run `nx migrate --run-migrations=migrations.json` -- Next, run `nx migrate 11.0.1` -- Run `npm install` -- Run `nx migrate --run-migrations=migrations.json` +- Run `nx migrate 10.4.5` to update the latest version in the 10.x branch. +- Run `npm install`. +- Run `nx migrate --run-migrations`. +- Next, run `nx migrate 11.0.1`. +- Run `npm install`. +- Run `nx migrate --run-migrations`. ### Overriding versions -Sometimes, you may want to use a different version of a package than what Nx recommends. You can do it as follows: +Sometimes, you may want to use a different version of a package than what Nx recommends. To do that, specify the package and version: ```bash nx migrate @nrwl/workspace --to="jest@22.0.0,cypress:3.4.0" ``` -By default, Nx uses currently installed packages to calculate what migrations need to run. You can override them like this: +By default, Nx uses currently installed packages to calculate what migrations need to run. To override them, override the version: ```bash -nx migrate @nrwl/workspace --to="@nrwl/jest@8.0.0" +nx migrate @nrwl/workspace --to="@nrwl/jest@12.0.0" ``` ### Reverting a failed update -Updates are best done on a clean git history so that it can be easily reversed if something fails. -We try our best to make sure migrations do not fail but if one does, **please report it** on [Github](https://www.github.com/nrwl/nx/issues/new/). +Updates are best done on a clean git history so that it can be easily reversed if something fails. We try our best to make sure migrations do not fail but if one does, **please report it** on [GitHub](https://www.github.com/nrwl/nx/issues/new/). + If an update fails for any reason, you can revert it as you do any other set of changes: ```bash diff --git a/nx-dev/nx-dev/public/documentation/latest/angular/migration/migration-angular.md b/nx-dev/nx-dev/public/documentation/latest/angular/migration/migration-angular.md index cb5d9b9ecf..5646c3a176 100644 --- a/nx-dev/nx-dev/public/documentation/latest/angular/migration/migration-angular.md +++ b/nx-dev/nx-dev/public/documentation/latest/angular/migration/migration-angular.md @@ -12,7 +12,7 @@ using a monorepo approach. If you are currently using an Angular CLI workspace, To add Nx to an existing Angular CLI workspace to an Nx workspace, with keeping your existing file structure in place, use the `ng add` command with the `--preserveAngularCLILayout` option: -``` +```bash ng add @nrwl/workspace --preserveAngularCLILayout ``` @@ -28,7 +28,7 @@ After the process completes, you continue using the same serve/build/lint/test c To transform a Angular CLI workspace to an Nx workspace, use the `ng add` command: -``` +```bash ng add @nrwl/workspace ``` @@ -86,14 +86,14 @@ Your workspace is now powered by Nx! You can verify out that your application st - To run e2e tests, run `ng e2e`. - To see your dependency graph, run `nx dep-graph`. -> Your dependency graph will grow as you add, and use more applications and libraries. +> Your dependency graph will grow as you add, and use more applications and libraries. You can add the `--watch` flag to `nx dep-graph` to see this changes in-browser as you add them. Learn more about the advantages of Nx in the following guides: - [Using Cypress for e2e tests](/angular/cypress/overview) - [Using Jest for unit tests](/angular/jest/overview) -- [Computation Caching](/angular/core-concepts/computation-caching) -- [Rebuilding and Retesting What is Affected](/angular/core-concepts/affected) +- [Computation Caching](/angular/core-extended/computation-caching) +- [Rebuilding and Retesting What is Affected](/angular/core-extended/affected) ## Transitioning Manually @@ -376,4 +376,4 @@ Learn more about the advantages of Nx in the following guides: [Using Cypress for e2e tests](/angular/cypress/overview) \ [Using Jest for unit tests](/angular/jest/overview) \ -[Rebuilding and Retesting What is Affected](/angular/core-concepts/affected) +[Rebuilding and Retesting What is Affected](/angular/core-extended/affected) diff --git a/nx-dev/nx-dev/public/documentation/latest/angular/tutorial/10-computation-caching.md b/nx-dev/nx-dev/public/documentation/latest/angular/tutorial/10-computation-caching.md index ad97f93597..98223a09a7 100644 --- a/nx-dev/nx-dev/public/documentation/latest/angular/tutorial/10-computation-caching.md +++ b/nx-dev/nx-dev/public/documentation/latest/angular/tutorial/10-computation-caching.md @@ -59,7 +59,7 @@ Based on the state of the source code and the environment, Nx was able to figure Nx read the output from cache instead of running the command for 1 out of 2 projects. ``` -Nx built `api` and retrieved `todos` from its computation cache. Read more about the cache here [here](/{{framework}}/core-concepts/computation-caching). +Nx built `api` and retrieved `todos` from its computation cache. Read more about the cache here [here](/{{framework}}/core-extended/computation-caching). ## --with-deps diff --git a/nx-dev/nx-dev/public/documentation/latest/angular/tutorial/12-summary.md b/nx-dev/nx-dev/public/documentation/latest/angular/tutorial/12-summary.md index 0963e7923a..f00dd1c556 100644 --- a/nx-dev/nx-dev/public/documentation/latest/angular/tutorial/12-summary.md +++ b/nx-dev/nx-dev/public/documentation/latest/angular/tutorial/12-summary.md @@ -14,5 +14,5 @@ In this tutorial you: **Dive Deep:** - [Nx CLI](/{{framework}}/getting-started/nx-cli) -- [Computation Caching](/{{framework}}/core-concepts/computation-caching) -- [Rebuilding What is Affected](/{{framework}}/core-concepts/affected) +- [Computation Caching](/{{framework}}/core-extended/computation-caching) +- [Rebuilding What is Affected](/{{framework}}/core-extended/affected) diff --git a/nx-dev/nx-dev/public/documentation/latest/map.json b/nx-dev/nx-dev/public/documentation/latest/map.json index d78d5a72ef..3ed72f2e02 100644 --- a/nx-dev/nx-dev/public/documentation/latest/map.json +++ b/nx-dev/nx-dev/public/documentation/latest/map.json @@ -86,21 +86,16 @@ "name": "Using Nx", "id": "core-concepts", "itemList": [ - { - "name": "Computation Caching", - "id": "computation-caching", - "file": "shared/computation-caching" - }, - { - "name": "Rebuild Only What is Affected", - "id": "affected", - "file": "shared/affected" - }, { "name": "Monorepos", "id": "why-monorepos", "file": "shared/guides/why-monorepos" }, + { + "name": "Mental Model", + "id": "mental-model", + "file": "shared/mental-model" + }, { "name": "Updating Nx", "id": "updating-nx", @@ -318,6 +313,11 @@ "id": "workspace-generator", "file": "angular/api-workspace/generators/workspace-generator" }, + { + "name": "convert-to-nx-project generator", + "id": "convert-to-nx-project-generator", + "file": "angular/api-workspace/generators/convert-to-nx-project" + }, { "name": "run-commands executor", "id": "run-commands-executor", @@ -387,21 +387,26 @@ "id": "application", "file": "angular/api-angular/generators/application" }, + { + "name": "convert-tslint-to-eslint", + "id": "convert-tslint-to-eslint", + "file": "angular/api-angular/generators/convert-tslint-to-eslint" + }, { "name": "downgrade-module generator", "id": "downgrade-module", "file": "angular/api-angular/generators/downgrade-module" }, - { - "name": "karma-project generator", - "id": "karma-project", - "file": "angular/api-angular/generators/karma-project" - }, { "name": "karma generator", "id": "karma", "file": "angular/api-angular/generators/karma" }, + { + "name": "karma-project generator", + "id": "karma-project", + "file": "angular/api-angular/generators/karma-project" + }, { "name": "library generator", "id": "library", @@ -443,29 +448,29 @@ "file": "angular/api-angular/generators/upgrade-module" }, { - "name": "convert-tslint-to-eslint", - "id": "convert-tslint-to-eslint", - "file": "angular/api-angular/generators/convert-tslint-to-eslint" + "name": "web-worker generator", + "id": "web-worker", + "file": "angular/api-angular/generators/web-worker" }, { - "name": "package executor", - "id": "package", - "file": "angular/api-angular/executors/package" + "name": "delegate-build executor", + "id": "delegate-build", + "file": "angular/api-angular/executors/delegate-build" }, { "name": "ng packagr lite executor", "id": "ng-packagr-lite", "file": "angular/api-angular/executors/ng-packagr-lite" }, + { + "name": "package executor", + "id": "package", + "file": "angular/api-angular/executors/package" + }, { "name": "webpack-browser executor", "id": "webpack-browser", "file": "angular/api-angular/executors/webpack-browser" - }, - { - "name": "delegate-build executor", - "id": "delegate-build", - "file": "angular/api-angular/executors/delegate-build" } ] }, @@ -903,6 +908,22 @@ } ] }, + { + "name": "Core", + "id": "core-extended", + "itemList": [ + { + "name": "Computation Caching", + "id": "computation-caching", + "file": "shared/computation-caching" + }, + { + "name": "Rebuild Only What is Affected", + "id": "affected", + "file": "shared/affected" + } + ] + }, { "name": "Executors / Builders", "id": "executors", @@ -931,12 +952,32 @@ { "name": "Using Generators", "id": "using-schematics", - "file": "shared/using-generators" + "file": "angular/generators/using-generators" }, { "name": "Workspace Generators", "id": "workspace-generators", - "file": "shared/tools-workspace-generators" + "file": "angular/generators/workspace-generators" + }, + { + "name": "Composing Generators", + "id": "composing-generators", + "file": "angular/generators/composing-generators" + }, + { + "name": "Generator Options", + "id": "generator-options", + "file": "shared/generators/generator-options" + }, + { + "name": "Creating Files", + "id": "creating-files", + "file": "shared/generators/creating-files" + }, + { + "name": "Modifying Files", + "id": "modifying-files", + "file": "shared/generators/modifying-files" } ] }, @@ -1185,21 +1226,16 @@ "name": "Using Nx", "id": "core-concepts", "itemList": [ - { - "name": "Computation Caching", - "id": "computation-caching", - "file": "shared/computation-caching" - }, - { - "name": "Rebuild Only What is Affected", - "id": "affected", - "file": "shared/affected" - }, { "name": "Monorepos", "id": "why-monorepos", "file": "shared/guides/why-monorepos" }, + { + "name": "Mental Model", + "id": "mental-model", + "file": "shared/mental-model" + }, { "name": "Updating Nx", "id": "updating-nx", @@ -1413,6 +1449,11 @@ "id": "workspace-generator", "file": "react/api-workspace/generators/workspace-generator" }, + { + "name": "convert-to-nx-project generator", + "id": "convert-to-nx-project-generator", + "file": "react/api-workspace/generators/convert-to-nx-project" + }, { "name": "run-commands executor", "id": "run-commands-executor", @@ -1482,21 +1523,26 @@ "id": "application", "file": "react/api-angular/generators/application" }, + { + "name": "convert-tslint-to-eslint", + "id": "convert-tslint-to-eslint", + "file": "react/api-angular/generators/convert-tslint-to-eslint" + }, { "name": "downgrade-module generator", "id": "downgrade-module", "file": "react/api-angular/generators/downgrade-module" }, - { - "name": "karma-project generator", - "id": "karma-project", - "file": "react/api-angular/generators/karma-project" - }, { "name": "karma generator", "id": "karma", "file": "react/api-angular/generators/karma" }, + { + "name": "karma-project generator", + "id": "karma-project", + "file": "react/api-angular/generators/karma-project" + }, { "name": "library generator", "id": "library", @@ -1512,11 +1558,6 @@ "id": "ngrx", "file": "react/api-angular/generators/ngrx" }, - { - "name": "convert-tslint-to-eslint", - "id": "convert-tslint-to-eslint", - "file": "react/api-angular/generators/convert-tslint-to-eslint" - }, { "name": "stories generator", "id": "stories", @@ -1543,24 +1584,29 @@ "file": "react/api-angular/generators/upgrade-module" }, { - "name": "package executor", - "id": "package", - "file": "react/api-angular/executors/package" + "name": "web-worker generator", + "id": "web-worker", + "file": "react/api-angular/generators/web-worker" + }, + { + "name": "delegate-build executor", + "id": "delegate-build", + "file": "react/api-angular/executors/delegate-build" }, { "name": "ng packagr lite executor", "id": "ng-packagr-lite", "file": "react/api-angular/executors/ng-packagr-lite" }, + { + "name": "package executor", + "id": "package", + "file": "react/api-angular/executors/package" + }, { "name": "webpack-browser executor", "id": "webpack-browser", "file": "react/api-angular/executors/webpack-browser" - }, - { - "name": "delegate-build executor", - "id": "delegate-build", - "file": "react/api-angular/executors/delegate-build" } ] }, @@ -2004,6 +2050,22 @@ } ] }, + { + "name": "Core", + "id": "core-extended", + "itemList": [ + { + "name": "Computation Caching", + "id": "computation-caching", + "file": "shared/computation-caching" + }, + { + "name": "Rebuild Only What is Affected", + "id": "affected", + "file": "shared/affected" + } + ] + }, { "name": "Executors / Builders", "id": "executors", @@ -2032,12 +2094,32 @@ { "name": "Using Generators", "id": "using-schematics", - "file": "shared/using-generators" + "file": "shared/generators/using-generators" }, { "name": "Workspace Generators", "id": "workspace-generators", - "file": "shared/tools-workspace-generators" + "file": "shared/generators/workspace-generators" + }, + { + "name": "Composing Generators", + "id": "composing-generators", + "file": "shared/generators/composing-generators" + }, + { + "name": "Generator Options", + "id": "generator-options", + "file": "shared/generators/generator-options" + }, + { + "name": "Creating Files", + "id": "creating-files", + "file": "shared/generators/creating-files" + }, + { + "name": "Modifying Files", + "id": "modifying-files", + "file": "shared/generators/modifying-files" } ] }, @@ -2248,21 +2330,16 @@ "name": "Using Nx", "id": "core-concepts", "itemList": [ - { - "name": "Computation Caching", - "id": "computation-caching", - "file": "shared/computation-caching" - }, - { - "name": "Rebuild Only What is Affected", - "id": "affected", - "file": "shared/affected" - }, { "name": "Monorepos", "id": "why-monorepos", "file": "shared/guides/why-monorepos" }, + { + "name": "Mental Model", + "id": "mental-model", + "file": "shared/mental-model" + }, { "name": "Updating Nx", "id": "updating-nx", @@ -2472,6 +2549,11 @@ "id": "workspace-generator", "file": "node/api-workspace/generators/workspace-generator" }, + { + "name": "convert-to-nx-project generator", + "id": "convert-to-nx-project-generator", + "file": "node/api-workspace/generators/convert-to-nx-project" + }, { "name": "run-commands executor", "id": "run-commands-executor", @@ -2541,21 +2623,26 @@ "id": "application", "file": "node/api-angular/generators/application" }, + { + "name": "convert-tslint-to-eslint", + "id": "convert-tslint-to-eslint", + "file": "node/api-angular/generators/convert-tslint-to-eslint" + }, { "name": "downgrade-module generator", "id": "downgrade-module", "file": "node/api-angular/generators/downgrade-module" }, - { - "name": "karma-project generator", - "id": "karma-project", - "file": "node/api-angular/generators/karma-project" - }, { "name": "karma generator", "id": "karma", "file": "node/api-angular/generators/karma" }, + { + "name": "karma-project generator", + "id": "karma-project", + "file": "node/api-angular/generators/karma-project" + }, { "name": "library generator", "id": "library", @@ -2597,29 +2684,29 @@ "file": "node/api-angular/generators/upgrade-module" }, { - "name": "convert-tslint-to-eslint", - "id": "convert-tslint-to-eslint", - "file": "node/api-angular/generators/convert-tslint-to-eslint" + "name": "web-worker generator", + "id": "web-worker", + "file": "node/api-angular/generators/web-worker" }, { - "name": "package executor", - "id": "package", - "file": "node/api-angular/executors/package" + "name": "delegate-build executor", + "id": "delegate-build", + "file": "node/api-angular/executors/delegate-build" }, { "name": "ng packagr lite executor", "id": "ng-packagr-lite", "file": "node/api-angular/executors/ng-packagr-lite" }, + { + "name": "package executor", + "id": "package", + "file": "node/api-angular/executors/package" + }, { "name": "webpack-browser executor", "id": "webpack-browser", "file": "node/api-angular/executors/webpack-browser" - }, - { - "name": "delegate-build executor", - "id": "delegate-build", - "file": "node/api-angular/executors/delegate-build" } ] }, @@ -3056,6 +3143,22 @@ } ] }, + { + "name": "Core", + "id": "core-extended", + "itemList": [ + { + "name": "Computation Caching", + "id": "computation-caching", + "file": "shared/computation-caching" + }, + { + "name": "Rebuild Only What is Affected", + "id": "affected", + "file": "shared/affected" + } + ] + }, { "name": "Executors / Builders", "id": "executors", @@ -3084,12 +3187,32 @@ { "name": "Using Generators", "id": "using-schematics", - "file": "shared/using-generators" + "file": "shared/generators/using-generators" }, { "name": "Workspace Generators", "id": "workspace-generators", - "file": "shared/tools-workspace-generators" + "file": "shared/generators/workspace-generators" + }, + { + "name": "Composing Generators", + "id": "composing-generators", + "file": "shared/generators/composing-generators" + }, + { + "name": "Generator Options", + "id": "generator-options", + "file": "shared/generators/generator-options" + }, + { + "name": "Creating Files", + "id": "creating-files", + "file": "shared/generators/creating-files" + }, + { + "name": "Modifying Files", + "id": "modifying-files", + "file": "shared/generators/modifying-files" } ] }, diff --git a/nx-dev/nx-dev/public/documentation/latest/node/api-angular/generators/application.md b/nx-dev/nx-dev/public/documentation/latest/node/api-angular/generators/application.md index 5c11383f44..26b9fa5d6f 100644 --- a/nx-dev/nx-dev/public/documentation/latest/node/api-angular/generators/application.md +++ b/nx-dev/nx-dev/public/documentation/latest/node/api-angular/generators/application.md @@ -128,6 +128,14 @@ Type: `boolean` Skip creating spec files. +### standaloneConfig + +Default: `false` + +Type: `boolean` + +Split the project configuration into /project.json rather than including it inside workspace.json + ### strict Default: `true` @@ -142,7 +150,7 @@ Default: `css` Type: `string` -Possible values: `css`, `scss`, `styl`, `less` +Possible values: `css`, `scss`, `less` The file extension to be used for style files. diff --git a/nx-dev/nx-dev/public/documentation/latest/node/api-angular/generators/downgrade-module.md b/nx-dev/nx-dev/public/documentation/latest/node/api-angular/generators/downgrade-module.md index 83a9b97974..f0fa6fc1e7 100644 --- a/nx-dev/nx-dev/public/documentation/latest/node/api-angular/generators/downgrade-module.md +++ b/nx-dev/nx-dev/public/documentation/latest/node/api-angular/generators/downgrade-module.md @@ -1,6 +1,6 @@ # downgrade-module -Setup Downgrade Module +Setup Downgrade Module. ## Usage @@ -40,7 +40,7 @@ The name of the main AngularJS module. Type: `string` -The name of the project +The name of the project. ### skipFormat @@ -48,7 +48,7 @@ Default: `false` Type: `boolean` -Skip formatting files +Skip formatting files. ### skipPackageJson @@ -56,4 +56,4 @@ Default: `false` Type: `boolean` -Do not add @angular/upgrade to package.json (e.g., --skipPackageJson) +Do not add @angular/upgrade to package.json (e.g., --skipPackageJson). diff --git a/nx-dev/nx-dev/public/documentation/latest/node/api-angular/generators/library.md b/nx-dev/nx-dev/public/documentation/latest/node/api-angular/generators/library.md index 617acfa27e..a2d8fa56f9 100644 --- a/nx-dev/nx-dev/public/documentation/latest/node/api-angular/generators/library.md +++ b/nx-dev/nx-dev/public/documentation/latest/node/api-angular/generators/library.md @@ -150,6 +150,14 @@ Type: `boolean` Do not update tsconfig.json for development experience. +### standaloneConfig + +Default: `false` + +Type: `boolean` + +Split the project configuration into /project.json rather than including it inside workspace.json + ### strict Default: `true` diff --git a/nx-dev/nx-dev/public/documentation/latest/node/api-angular/generators/ngrx.md b/nx-dev/nx-dev/public/documentation/latest/node/api-angular/generators/ngrx.md index 9d4a0f23dc..7995a15629 100644 --- a/nx-dev/nx-dev/public/documentation/latest/node/api-angular/generators/ngrx.md +++ b/nx-dev/nx-dev/public/documentation/latest/node/api-angular/generators/ngrx.md @@ -1,6 +1,6 @@ # ngrx -Add an ngrx config to a project +Add NgRx support to an application or library. ## Usage @@ -66,23 +66,27 @@ The path to NgModule where the feature state will be registered. The host direct Type: `string` -Name of the NgRx feature state, such as "products" or "users"). Recommended to use the plural form of the name. +Name of the NgRx feature state, such as `products` or `users`. Recommended to use the plural form of the name. -### onlyAddFiles +### ~~onlyAddFiles~~ Default: `false` Type: `boolean` -**Deprecated**, use `skipImport`. Only add new NgRx files, without changing the module file (e.g., --onlyAddFiles). +**Deprecated:** Use the `skipImport` option instead. -### onlyEmptyRoot +Only add new NgRx files, without changing the module file (e.g., --onlyAddFiles). + +### ~~onlyEmptyRoot~~ Default: `false` Type: `boolean` -**Deprecated**, use `minimal`. Do not generate any files. Only generate StoreModule.forRoot and EffectsModule.forRoot (e.g., --onlyEmptyRoot). +**Deprecated:** Use the `minimal` option instead. + +Do not generate any files. Only generate StoreModule.forRoot and EffectsModule.forRoot (e.g., --onlyEmptyRoot). ### root diff --git a/nx-dev/nx-dev/public/documentation/latest/node/api-angular/generators/upgrade-module.md b/nx-dev/nx-dev/public/documentation/latest/node/api-angular/generators/upgrade-module.md index 093f05de01..bf85ee63b3 100644 --- a/nx-dev/nx-dev/public/documentation/latest/node/api-angular/generators/upgrade-module.md +++ b/nx-dev/nx-dev/public/documentation/latest/node/api-angular/generators/upgrade-module.md @@ -1,6 +1,6 @@ # upgrade-module -Add an upgrade module +Add an upgrade module. ## Usage @@ -28,7 +28,7 @@ nx g upgrade-module ... --dry-run Type: `string` -The selector of an AngularJS component (e.g., --angularJsCmpSelector=myComponent) +The selector of an AngularJS component (e.g., --angularJsCmpSelector=myComponent). ### angularJsImport @@ -46,7 +46,7 @@ The name of the main AngularJS module. Type: `string` -The name of the project +The name of the project. ### router @@ -54,7 +54,7 @@ Default: `false` Type: `boolean` -Sets up router synchronization (e.g., --router) +Sets up router synchronization (e.g., --router). ### skipFormat @@ -62,7 +62,7 @@ Default: `false` Type: `boolean` -Skip formatting files +Skip formatting files. ### skipPackageJson @@ -70,4 +70,4 @@ Default: `false` Type: `boolean` -Do not add @angular/upgrade to package.json (e.g., --skipPackageJson) +Do not add @angular/upgrade to package.json (e.g., --skipPackageJson). diff --git a/nx-dev/nx-dev/public/documentation/latest/node/api-angular/generators/web-worker.md b/nx-dev/nx-dev/public/documentation/latest/node/api-angular/generators/web-worker.md new file mode 100644 index 0000000000..67031d48f7 --- /dev/null +++ b/nx-dev/nx-dev/public/documentation/latest/node/api-angular/generators/web-worker.md @@ -0,0 +1,59 @@ +# web-worker + +Create a Web Worker. + +## Usage + +```bash +nx generate web-worker ... +``` + +By default, Nx will search for `web-worker` in the default collection provisioned in `workspace.json`. + +You can specify the collection explicitly as follows: + +```bash +nx g @nrwl/angular:web-worker ... +``` + +Show what will be generated without writing to disk: + +```bash +nx g web-worker ... --dry-run +``` + +## Options + +### name + +Type: `string` + +The name of the worker. + +### path + +Type: `string` + +The path at which to create the worker file, relative to the current workspace. + +### project + +Type: `string` + +The name of the project. + +### skipFormat + +Default: `false` + +Type: `boolean` + +Skip formatting files. + +### snippet + +Default: `true` + +Type: `boolean` + +Add a worker creation snippet in a sibling file of the same name. diff --git a/nx-dev/nx-dev/public/documentation/latest/node/api-express/generators/application.md b/nx-dev/nx-dev/public/documentation/latest/node/api-express/generators/application.md index c801960e6a..1f5b44281a 100644 --- a/nx-dev/nx-dev/public/documentation/latest/node/api-express/generators/application.md +++ b/nx-dev/nx-dev/public/documentation/latest/node/api-express/generators/application.md @@ -98,6 +98,14 @@ Type: `boolean` Do not add dependencies to package.json. +### standaloneConfig + +Default: `false` + +Type: `boolean` + +Split the project configuration into /project.json rather than including it inside workspace.json + ### tags Type: `string` diff --git a/nx-dev/nx-dev/public/documentation/latest/node/api-gatsby/generators/application.md b/nx-dev/nx-dev/public/documentation/latest/node/api-gatsby/generators/application.md index 7269ac5bbd..304a5932ed 100644 --- a/nx-dev/nx-dev/public/documentation/latest/node/api-gatsby/generators/application.md +++ b/nx-dev/nx-dev/public/documentation/latest/node/api-gatsby/generators/application.md @@ -66,6 +66,14 @@ Type: `boolean` Whether or not to configure the ESLint "parserOptions.project" option. We do not do this by default for lint performance reasons. +### standaloneConfig + +Default: `false` + +Type: `boolean` + +Split the project configuration into /project.json rather than including it inside workspace.json + ### style Alias(es): s diff --git a/nx-dev/nx-dev/public/documentation/latest/node/api-nest/generators/application.md b/nx-dev/nx-dev/public/documentation/latest/node/api-nest/generators/application.md index cca4d44354..bff9cfa98d 100644 --- a/nx-dev/nx-dev/public/documentation/latest/node/api-nest/generators/application.md +++ b/nx-dev/nx-dev/public/documentation/latest/node/api-nest/generators/application.md @@ -72,6 +72,14 @@ Type: `boolean` Do not add dependencies to package.json. +### standaloneConfig + +Default: `false` + +Type: `boolean` + +Split the project configuration into /project.json rather than including it inside workspace.json + ### tags Type: `string` diff --git a/nx-dev/nx-dev/public/documentation/latest/node/api-next/generators/application.md b/nx-dev/nx-dev/public/documentation/latest/node/api-next/generators/application.md index ebdc892804..7fdb044de5 100644 --- a/nx-dev/nx-dev/public/documentation/latest/node/api-next/generators/application.md +++ b/nx-dev/nx-dev/public/documentation/latest/node/api-next/generators/application.md @@ -108,6 +108,14 @@ Type: `boolean` Skip updating workspace.json with default options based on values provided to this app (e.g. babel, style) +### standaloneConfig + +Default: `false` + +Type: `boolean` + +Split the project configuration into /project.json rather than including it inside workspace.json + ### style Alias(es): s diff --git a/nx-dev/nx-dev/public/documentation/latest/node/api-node/generators/application.md b/nx-dev/nx-dev/public/documentation/latest/node/api-node/generators/application.md index 7978f16169..6da0095e63 100644 --- a/nx-dev/nx-dev/public/documentation/latest/node/api-node/generators/application.md +++ b/nx-dev/nx-dev/public/documentation/latest/node/api-node/generators/application.md @@ -106,6 +106,14 @@ Type: `boolean` Do not add dependencies to package.json. +### standaloneConfig + +Default: `false` + +Type: `boolean` + +Split the project configuration into /project.json rather than including it inside workspace.json + ### tags Type: `string` diff --git a/nx-dev/nx-dev/public/documentation/latest/node/api-node/generators/library.md b/nx-dev/nx-dev/public/documentation/latest/node/api-node/generators/library.md index 3097fb9634..317300e3be 100644 --- a/nx-dev/nx-dev/public/documentation/latest/node/api-node/generators/library.md +++ b/nx-dev/nx-dev/public/documentation/latest/node/api-node/generators/library.md @@ -138,6 +138,14 @@ Type: `boolean` Do not update tsconfig.base.json for development experience. +### standaloneConfig + +Default: `false` + +Type: `boolean` + +Split the project configuration into /project.json rather than including it inside workspace.json + ### strict Default: `false` diff --git a/nx-dev/nx-dev/public/documentation/latest/node/api-nx-devkit/index.md b/nx-dev/nx-dev/public/documentation/latest/node/api-nx-devkit/index.md index 4362e49c99..c05636dfb6 100644 --- a/nx-dev/nx-dev/public/documentation/latest/node/api-nx-devkit/index.md +++ b/nx-dev/nx-dev/public/documentation/latest/node/api-nx-devkit/index.md @@ -60,9 +60,11 @@ - [applyChangesToString](../../node/nx-devkit/index#applychangestostring) - [convertNxExecutor](../../node/nx-devkit/index#convertnxexecutor) - [convertNxGenerator](../../node/nx-devkit/index#convertnxgenerator) +- [detectPackageManager](../../node/nx-devkit/index#detectpackagemanager) - [formatFiles](../../node/nx-devkit/index#formatfiles) - [generateFiles](../../node/nx-devkit/index#generatefiles) - [getPackageManagerCommand](../../node/nx-devkit/index#getpackagemanagercommand) +- [getPackageManagerVersion](../../node/nx-devkit/index#getpackagemanagerversion) - [getProjects](../../node/nx-devkit/index#getprojects) - [getWorkspaceLayout](../../node/nx-devkit/index#getworkspacelayout) - [getWorkspacePath](../../node/nx-devkit/index#getworkspacepath) @@ -473,7 +475,7 @@ Callback to install dependencies only if necessary. undefined is returned if cha ### addProjectConfiguration -▸ **addProjectConfiguration**(`host`: [_Tree_](../../node/nx-devkit/index#tree), `projectName`: _string_, `projectConfiguration`: [_ProjectConfiguration_](../../node/nx-devkit/index#projectconfiguration) & [_NxJsonProjectConfiguration_](../../node/nx-devkit/index#nxjsonprojectconfiguration)): _void_ +▸ **addProjectConfiguration**(`host`: [_Tree_](../../node/nx-devkit/index#tree), `projectName`: _string_, `projectConfiguration`: [_ProjectConfiguration_](../../node/nx-devkit/index#projectconfiguration) & [_NxJsonProjectConfiguration_](../../node/nx-devkit/index#nxjsonprojectconfiguration), `standalone?`: _boolean_): _void_ Adds project configuration to the Nx workspace. @@ -482,11 +484,12 @@ both files. #### Parameters -| Name | Type | Description | -| :--------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------- | -| `host` | [_Tree_](../../node/nx-devkit/index#tree) | the file system tree | -| `projectName` | _string_ | unique name. Often directories are part of the name (e.g., mydir-mylib) | -| `projectConfiguration` | [_ProjectConfiguration_](../../node/nx-devkit/index#projectconfiguration) & [_NxJsonProjectConfiguration_](../../node/nx-devkit/index#nxjsonprojectconfiguration) | project configuration | +| Name | Type | Default value | Description | +| :--------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------ | :----------------------------------------------------------------------------------------- | +| `host` | [_Tree_](../../node/nx-devkit/index#tree) | - | the file system tree | +| `projectName` | _string_ | - | unique name. Often directories are part of the name (e.g., mydir-mylib) | +| `projectConfiguration` | [_ProjectConfiguration_](../../node/nx-devkit/index#projectconfiguration) & [_NxJsonProjectConfiguration_](../../node/nx-devkit/index#nxjsonprojectconfiguration) | - | project configuration | +| `standalone` | _boolean_ | false | should the project use package.json? If false, the project config is inside workspace.json | **Returns:** _void_ @@ -577,6 +580,22 @@ Convert an Nx Generator into an Angular Devkit Schematic --- +### detectPackageManager + +▸ **detectPackageManager**(`dir?`: _string_): [_PackageManager_](../../node/nx-devkit/index#packagemanager) + +Detects which package manager is used in the workspace based on the lock file. + +#### Parameters + +| Name | Type | Default value | +| :---- | :------- | :------------ | +| `dir` | _string_ | '' | + +**Returns:** [_PackageManager_](../../node/nx-devkit/index#packagemanager) + +--- + ### formatFiles ▸ **formatFiles**(`host`: [_Tree_](../../node/nx-devkit/index#tree)): _Promise_ @@ -634,7 +653,7 @@ doesn't get confused about incorrect TypeScript files. ### getPackageManagerCommand -▸ **getPackageManagerCommand**(`packageManager?`: [_PackageManager_](../../node/nx-devkit/index#packagemanager)): _object_ +▸ **getPackageManagerCommand**(`packageManager?`: [_PackageManager_](../../node/nx-devkit/index#packagemanager)): PackageManagerCommands Returns commands for the package manager used in the workspace. By default, the package manager is derived based on the lock file, @@ -652,17 +671,25 @@ execSync(`${getPackageManagerCommand().addDev} my-dev-package`); | :--------------- | :------------------------------------------------------------ | | `packageManager` | [_PackageManager_](../../node/nx-devkit/index#packagemanager) | -**Returns:** _object_ +**Returns:** PackageManagerCommands -| Name | Type | -| :-------- | :------------------------------------------------- | -| `add` | _string_ | -| `addDev` | _string_ | -| `exec` | _string_ | -| `install` | _string_ | -| `list` | _string_ | -| `rm` | _string_ | -| `run` | (`script`: _string_, `args`: _string_) => _string_ | +--- + +### getPackageManagerVersion + +▸ **getPackageManagerVersion**(`packageManager?`: [_PackageManager_](../../node/nx-devkit/index#packagemanager)): _string_ + +Returns the version of the package manager used in the workspace. +By default, the package manager is derived based on the lock file, +but it can also be passed in explicitly. + +#### Parameters + +| Name | Type | +| :--------------- | :------------------------------------------------------------ | +| `packageManager` | [_PackageManager_](../../node/nx-devkit/index#packagemanager) | + +**Returns:** _string_ --- diff --git a/nx-dev/nx-dev/public/documentation/latest/node/api-nx-plugin/generators/plugin.md b/nx-dev/nx-dev/public/documentation/latest/node/api-nx-plugin/generators/plugin.md index f7bce6c1ba..2934ff0176 100644 --- a/nx-dev/nx-dev/public/documentation/latest/node/api-nx-plugin/generators/plugin.md +++ b/nx-dev/nx-dev/public/documentation/latest/node/api-nx-plugin/generators/plugin.md @@ -78,6 +78,14 @@ Type: `boolean` Do not update tsconfig.json for development experience. +### standaloneConfig + +Default: `false` + +Type: `boolean` + +Split the project configuration into /project.json rather than including it inside workspace.json + ### tags Alias(es): t diff --git a/nx-dev/nx-dev/public/documentation/latest/node/api-react/generators/application.md b/nx-dev/nx-dev/public/documentation/latest/node/api-react/generators/application.md index 15bc5d395c..db9e3c7ab8 100644 --- a/nx-dev/nx-dev/public/documentation/latest/node/api-react/generators/application.md +++ b/nx-dev/nx-dev/public/documentation/latest/node/api-react/generators/application.md @@ -150,6 +150,14 @@ Type: `boolean` Skip updating workspace.json with default options based on values provided to this app (e.g. babel, style). +### standaloneConfig + +Default: `false` + +Type: `boolean` + +Split the project configuration into /project.json rather than including it inside workspace.json + ### strict Default: `true` diff --git a/nx-dev/nx-dev/public/documentation/latest/node/api-react/generators/library.md b/nx-dev/nx-dev/public/documentation/latest/node/api-react/generators/library.md index bd622569cf..d605dfc63a 100644 --- a/nx-dev/nx-dev/public/documentation/latest/node/api-react/generators/library.md +++ b/nx-dev/nx-dev/public/documentation/latest/node/api-react/generators/library.md @@ -158,6 +158,14 @@ Type: `boolean` Do not update tsconfig.json for development experience. +### standaloneConfig + +Default: `false` + +Type: `boolean` + +Split the project configuration into /project.json rather than including it inside workspace.json + ### strict Default: `true` diff --git a/nx-dev/nx-dev/public/documentation/latest/node/api-react/generators/storybook-configuration.md b/nx-dev/nx-dev/public/documentation/latest/node/api-react/generators/storybook-configuration.md index c013ff5a7d..06dc9ea29f 100644 --- a/nx-dev/nx-dev/public/documentation/latest/node/api-react/generators/storybook-configuration.md +++ b/nx-dev/nx-dev/public/documentation/latest/node/api-react/generators/storybook-configuration.md @@ -77,3 +77,11 @@ The tool to use for running lint checks. Type: `string` Project name + +### standaloneConfig + +Default: `false` + +Type: `boolean` + +Split the project configuration into /project.json rather than including it inside workspace.json diff --git a/nx-dev/nx-dev/public/documentation/latest/node/api-storybook/generators/configuration.md b/nx-dev/nx-dev/public/documentation/latest/node/api-storybook/generators/configuration.md index dffb1048ab..6e982ee587 100644 --- a/nx-dev/nx-dev/public/documentation/latest/node/api-storybook/generators/configuration.md +++ b/nx-dev/nx-dev/public/documentation/latest/node/api-storybook/generators/configuration.md @@ -60,6 +60,14 @@ Type: `string` Library or application name +### standaloneConfig + +Default: `false` + +Type: `boolean` + +Split the project configuration into /project.json rather than including it inside workspace.json + ### uiFramework Type: `string` diff --git a/nx-dev/nx-dev/public/documentation/latest/node/api-storybook/generators/cypress-project.md b/nx-dev/nx-dev/public/documentation/latest/node/api-storybook/generators/cypress-project.md index 5783c6d340..c3e27b2976 100644 --- a/nx-dev/nx-dev/public/documentation/latest/node/api-storybook/generators/cypress-project.md +++ b/nx-dev/nx-dev/public/documentation/latest/node/api-storybook/generators/cypress-project.md @@ -53,3 +53,11 @@ The tool to use for running lint checks. Type: `string` Library or application name + +### standaloneConfig + +Default: `false` + +Type: `boolean` + +Split the project configuration into /project.json rather than including it inside workspace.json diff --git a/nx-dev/nx-dev/public/documentation/latest/node/api-web/generators/application.md b/nx-dev/nx-dev/public/documentation/latest/node/api-web/generators/application.md index 914d89a1c5..e2595bf10f 100644 --- a/nx-dev/nx-dev/public/documentation/latest/node/api-web/generators/application.md +++ b/nx-dev/nx-dev/public/documentation/latest/node/api-web/generators/application.md @@ -76,6 +76,14 @@ Type: `boolean` Skip formatting files +### standaloneConfig + +Default: `false` + +Type: `boolean` + +Split the project configuration into /project.json rather than including it inside workspace.json + ### style Default: `css` diff --git a/nx-dev/nx-dev/public/documentation/latest/node/api-workspace/generators/convert-to-nx-project.md b/nx-dev/nx-dev/public/documentation/latest/node/api-workspace/generators/convert-to-nx-project.md new file mode 100644 index 0000000000..b86c1820e6 --- /dev/null +++ b/nx-dev/nx-dev/public/documentation/latest/node/api-workspace/generators/convert-to-nx-project.md @@ -0,0 +1,51 @@ +# convert-to-nx-project + +Moves a project's configuration outside of workspace.json + +## Usage + +```bash +nx generate convert-to-nx-project ... +``` + +By default, Nx will search for `convert-to-nx-project` in the default collection provisioned in `workspace.json`. + +You can specify the collection explicitly as follows: + +```bash +nx g @nrwl/workspace:convert-to-nx-project ... +``` + +Show what will be generated without writing to disk: + +```bash +nx g convert-to-nx-project ... --dry-run +``` + +### Examples + +Convert the my-feature-lib project to use project.json file instead of workspace.json: + +```bash +nx g @nrwl/workspace:convert-to-nx-project --project my-feature-lib +``` + +Convert all projects in workspace.json to separate project.json files.: + +```bash +nx g @nrwl/workspace:convert-to-nx-project --all +``` + +## Options + +### all + +Type: `boolean` + +Should every project be converted? + +### project + +Type: `string` + +Project name diff --git a/nx-dev/nx-dev/public/documentation/latest/node/api-workspace/generators/library.md b/nx-dev/nx-dev/public/documentation/latest/node/api-workspace/generators/library.md index 44fd48eafb..1e2dd53851 100644 --- a/nx-dev/nx-dev/public/documentation/latest/node/api-workspace/generators/library.md +++ b/nx-dev/nx-dev/public/documentation/latest/node/api-workspace/generators/library.md @@ -130,6 +130,14 @@ Type: `boolean` Do not update tsconfig.json for development experience. +### standaloneConfig + +Default: `false` + +Type: `boolean` + +Split the project configuration into /project.json rather than including it inside workspace.json + ### strict Default: `false` diff --git a/nx-dev/nx-dev/public/documentation/latest/node/cli/affected-dep-graph.md b/nx-dev/nx-dev/public/documentation/latest/node/cli/affected-dep-graph.md index 1f5311aa42..e96515443d 100644 --- a/nx-dev/nx-dev/public/documentation/latest/node/cli/affected-dep-graph.md +++ b/nx-dev/nx-dev/public/documentation/latest/node/cli/affected-dep-graph.md @@ -131,3 +131,9 @@ Print additional error stack trace on failure ### version Show version number + +### watch + +Default: `false` + +Watch for changes to dep graph and update in-browser diff --git a/nx-dev/nx-dev/public/documentation/latest/node/cli/dep-graph.md b/nx-dev/nx-dev/public/documentation/latest/node/cli/dep-graph.md index 7de42387d7..8db615a505 100644 --- a/nx-dev/nx-dev/public/documentation/latest/node/cli/dep-graph.md +++ b/nx-dev/nx-dev/public/documentation/latest/node/cli/dep-graph.md @@ -54,6 +54,12 @@ Show the graph where every node is either an ancestor or a descendant of todos-f nx dep-graph --focus=todos-feature-main --exclude=project-one,project-two ``` +Watch for changes to dep graph and update in-browser: + +```bash +nx dep-graph --watch +``` + ## Options ### exclude @@ -87,3 +93,9 @@ Bind the dep graph server to a specific port. ### version Show version number + +### watch + +Default: `false` + +Watch for changes to dep graph and update in-browser diff --git a/nx-dev/nx-dev/public/documentation/latest/node/getting-started/intro.md b/nx-dev/nx-dev/public/documentation/latest/node/getting-started/intro.md index 7d0b96c932..186f806b0e 100644 --- a/nx-dev/nx-dev/public/documentation/latest/node/getting-started/intro.md +++ b/nx-dev/nx-dev/public/documentation/latest/node/getting-started/intro.md @@ -17,7 +17,7 @@ Nx works especially well for [monorepos](/{{framework}}/core-concepts/why-monore ## Features - Test (or builds or lints) only the projects [affected](/{{framework}}/cli/affected) by a code change. -- [Cache](/{{framework}}/core-concepts/computation-caching) command output locally so that future runs on the same code happen in seconds. The paid [Nx Cloud](https://nx.app) offering allows this cache to be shared across every developer in your organization. +- [Cache](/{{framework}}/core-extended/computation-caching) command output locally so that future runs on the same code happen in seconds. The paid [Nx Cloud](https://nx.app) offering allows this cache to be shared across every developer in your organization. - Provide a consistent syntax for [executing commands](/{{framework}}/executors/using-builders). `nx build my-app` works no matter what framework `my-app` uses. - Automate code modification tasks with [generators](/{{framework}}/cli/affected). - Access a thriving ecosystem of [plugins](/{{framework}}/generators/using-schematics) from Nrwl and the [community](/community). @@ -31,5 +31,5 @@ Nx works especially well for [monorepos](/{{framework}}/core-concepts/why-monore - [Nx CLI](/{{framework}}/getting-started/nx-cli) - [Configuration Files](/{{framework}}/core-concepts/configuration) -- [Computation Caching](/{{framework}}/core-concepts/computation-caching) -- [Rebuilding What is Affected](/{{framework}}/core-concepts/affected) +- [Computation Caching](/{{framework}}/core-extended/computation-caching) +- [Rebuilding What is Affected](/{{framework}}/core-extended/affected) diff --git a/nx-dev/nx-dev/public/documentation/latest/node/getting-started/nx-cli.md b/nx-dev/nx-dev/public/documentation/latest/node/getting-started/nx-cli.md index b49c55fe12..9b35846133 100644 --- a/nx-dev/nx-dev/public/documentation/latest/node/getting-started/nx-cli.md +++ b/nx-dev/nx-dev/public/documentation/latest/node/getting-started/nx-cli.md @@ -41,15 +41,6 @@ nx workspace-generator my-generator [The first command](/{{framework}}/cli/generate) scaffolds a new customizable workspace generator named `my-generator` and [the second command](/{{framework}}/cli/workspace-generator) invokes it. -**Update plugins:** - -```bash -nx migrate latest -nx migrate --run-migrations=migrations.json -``` - -[The first command](/{{framework}}/cli/migrate) updates the installed Nx plugin versions and creates a list of generators to keep configuration files up to date. [The second command](/{{framework}}/cli/migrate) invokes those generators. - **Run an executor on one project:** ```bash @@ -57,7 +48,15 @@ nx run my-app:build nx build my-app ``` -Both of [these commands](/{{framework}}/cli/run) build the `my-app` application. Custom executors need to use the more verbose `nx run project:target` syntax. See the [workspace.json documentation](/{{framework}}/core-concepts/configuration) for information on configuring executor options. +Both of [these commands](/{{framework}}/cli/run) build the `my-app` application. See the [workspace.json documentation](/{{framework}}/core-concepts/configuration) for information on configuring executor options. + +**Run an executor for many projects:** + +```bash +nx run-many --target=build --projects=app1,app2 +``` + +[This command](/{{framework}}/cli/run-many) builds `app1` and `app2`. **Run an executor for all affected projects:** @@ -71,10 +70,11 @@ nx affected --target=build ```bash nx dep-graph +nx dep-graph --watch nx affected:dep-graph ``` -[The first command](/{{framework}}/cli/dep-graph) launches a web browser with repository's dependency graph rendered visually. [The second command](/{{framework}}/cli/affected-dep-graph) renders the same graph with projects affected by the current code change highlighted. +[The first command](/{{framework}}/cli/dep-graph) launches a web browser with repository's dependency graph rendered visually. You can add the `--watch` flag to watch for changes to the dep grpah and update the view in-browser. [The second command](/{{framework}}/cli/affected-dep-graph) renders the same graph with projects affected by the current code change highlighted. **List installed plugins:** @@ -83,3 +83,17 @@ nx list ``` [This command](/{{framework}}/cli/list) lists the currently installed Nx plugins and shows other plugins that are available. + +**Update plugins:** + +```bash +nx migrate latest +nx migrate --run-migrations=migrations.json +``` + +[The first command](/{{framework}}/cli/migrate) updates the installed Nx plugin versions and creates a list of generators to keep configuration files up to date. [The second command](/{{framework}}/cli/migrate) invokes those generators. + +## Common Env Variables + +- Setting **NX_VERBOSE_LOGGING=true** will print debug information useful for troubleshooting. +- Setting **NX_PERF_LOGGING=true** will print debug information useful for profiling executors and Nx itself. diff --git a/nx-dev/nx-dev/public/documentation/latest/node/guides/configuration.md b/nx-dev/nx-dev/public/documentation/latest/node/guides/configuration.md index 38166a0b99..4e57334292 100644 --- a/nx-dev/nx-dev/public/documentation/latest/node/guides/configuration.md +++ b/nx-dev/nx-dev/public/documentation/latest/node/guides/configuration.md @@ -18,6 +18,12 @@ The `workspace.json` configuration file contains information about the targets a "build": { "executor": "@nrwl/node:build", "outputs": ["dist/apps/myapp"], + "dependsOn": [ + { + "target": "build", + "projects": "dependencies" + } + ], "options": { "outputPath": "dist/packages/myapp", "main": "packages/myapp/src/main.ts", @@ -99,9 +105,11 @@ For instance, the following configures `mylib`. - `root` tells Nx the location of the library including its sources and configuration files. - `sourceRoot` tells Nx the location of the library's source files. -- `projectType` is either 'application' or 'library'. +- `projectType` is either 'application' or 'library'. The project type is used in dep graph viz and in a few aux commands. - `targets` configures all the targets which define what tasks you can run against the library. +> Projects utilizing `project.json` files will not be present in `workspace.json`. + ### Targets Let's look at the simple target: @@ -119,7 +127,7 @@ Let's look at the simple target: **Target Name** -The name of the target `test` means that you can invoke it as follows: `nx test mylib` or `nx run mylib:test`. The name isn't significant in any other way. If you rename it to, for example, `mytest`, you will be able to run as follows: `nx run mylib:mytest`. +The name of the target `test` means that you can invoke it as follows: `nx test mylib` or `nx run mylib:test`. The name isn't significant in any other way. If you rename it to, for example, `mytest`, you will be able to run as follows: `nx mytest mylib` or `nx run mylib:mytest`. **Executor** @@ -188,6 +196,66 @@ require(`@nrwl/jest`).executors['jest']({...options, ...selectedConfiguration, . The selected configuration adds/overrides the default options, and the provided command line args add/override the configuration options. +**Target Dependencies** + +Targets can depend on other targets. A common scenario is having to build dependencies of a project first before building the project. You can specify this using the `dependsOn`. + +```json +{ + "build": { + "executor": "@nrwl/node:build", + "outputs": ["dist/apps/myapp"], + "options": { + "index": "apps/myapp/src/app.html", + "main": "apps/myapp/src/main.ts" + }, + "dependsOn": [ + { + "target": "build", + "projects": "dependencies" + } + ] + } +} +``` + +In this case, running `nx build myapp` will build all the buildable libraries `myapp` depends on first. In other words, `nx build myapp` will result in multiple tasks executing. The `--parallel`, and `--max-parallel` flags will have the same effect as they would with `run-many` or `affected`. + +It is also possible to define dependencies between the targets of the same project. + +In the following example invoking `nx build myapp` will build all the libraries first, then `nx build-base myapp` will be executed and only then `nx build myapp` will be executed. + +```json +{ + "build-base": { + "executor": "@nrwl/node:build", + "outputs": ["dist/apps/myapp"], + "options": { + "index": "apps/myapp/src/app.html", + "main": "apps/myapp/src/main.ts" + } + }, + "build": { + "executor": "@nrwl/workspace:run-commands", + "dependsOn": [ + { + "target": "build", + "projects": "dependencies" + }, + { + "target": "build-base", + "projects": "self" + } + ], + "options": { + "command": "./copy-readme-and-license.sh" + } + } +} +``` + +Often the same `dependsOn` configuration has to be defined for every project in the repo. You can define it once in `nx.json` (see below). + ### Generators You can configure default generator options in `workspace.json` as well. For instance, the following will tell Nx to always pass `--js` when creating new libraries. @@ -236,6 +304,33 @@ The following command will generate a new library: `nx g @nrwl/node:lib mylib`. When the `version` of `workspace.json` is set to 2, `targets`, `generators` and `executor` properties are used instead of the version 1 properties `architect`, `schematics` and `builder`. +## project.json + +Project configurations can also be independent files, referenced by `workspace.json`. For instance, a `workspace.json` may contain projects configured as below. + +```json +{ + "projects": { + "mylib": "libs/mylib" + } +} +``` + +This tells Nx that all configuration for that project is found in the `libs/mylib/project.json` file. This file contains a combination of the project's configuration from both `workspace.json` and `nx.json`. + +```json +{ + "mylib": { + "root": "libs/mylib/", + "sourceRoot": "libs/mylib/src", + "projectType": "library", + "targets": {}, + "tags": [], + "implicitDependencies": [] + } +} +``` + ## nx.json The `nx.json` file contains extra configuration options mostly related to the project graph. @@ -370,3 +465,39 @@ You can also add dependencies between projects. For instance, the example below } } ``` + +> Projects utilizing `project.json` files will not be present in `nx.json`. + +### Target Dependencies + +Targets can depend on other targets. A common scenario is having to build dependencies of a project first before building the project. The `dependsOn` property in `workspace.json` can be used to define the list of dependencies of an individual target. + +Often the same `dependsOn` configuration has to be defined for every project in the repo, and that's when defining `targetDependencies` in `nx.json` is helpful. + +```json +{ + "targetDependencies": { + "build": [ + { + "target": "build", + "projects": "dependencies" + } + ] + } +} +``` + +The configuration above is identical to adding `{"dependsOn": [{"target": "build", "projects": "dependencies"]}` to every build target in `workspace.json`. + +The `dependsOn` property in `workspace.json` takes precedence over the `targetDependencies` in `nx.json`. + +## .nxignore + +You may optionally add an `.nxignore` file to the root. This file is used to specify files in your workspace that should be completely ignored by Nx. + +The syntax is the same as a [`.gitignore` file](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository#_ignoring). + +**When a file is specified in the `.nxignore` file:** + +1. Changes to that file will not be taken into account in the `affected` calculations. +2. Even if the file is outside an app or library, `nx workspace-lint` will not warn about it. diff --git a/nx-dev/nx-dev/public/documentation/latest/node/tutorial/08-summary.md b/nx-dev/nx-dev/public/documentation/latest/node/tutorial/08-summary.md index 7331a421a0..30eb36b758 100644 --- a/nx-dev/nx-dev/public/documentation/latest/node/tutorial/08-summary.md +++ b/nx-dev/nx-dev/public/documentation/latest/node/tutorial/08-summary.md @@ -14,5 +14,5 @@ In this tutorial you: **Dive Deep:** - [Nx CLI](/{{framework}}/getting-started/nx-cli) -- [Computation Caching](/{{framework}}/core-concepts/computation-caching) -- [Rebuilding What is Affected](/{{framework}}/core-concepts/affected) +- [Computation Caching](/{{framework}}/core-extended/computation-caching) +- [Rebuilding What is Affected](/{{framework}}/core-extended/affected) diff --git a/nx-dev/nx-dev/public/documentation/latest/react/api-angular/generators/application.md b/nx-dev/nx-dev/public/documentation/latest/react/api-angular/generators/application.md index 5c11383f44..26b9fa5d6f 100644 --- a/nx-dev/nx-dev/public/documentation/latest/react/api-angular/generators/application.md +++ b/nx-dev/nx-dev/public/documentation/latest/react/api-angular/generators/application.md @@ -128,6 +128,14 @@ Type: `boolean` Skip creating spec files. +### standaloneConfig + +Default: `false` + +Type: `boolean` + +Split the project configuration into /project.json rather than including it inside workspace.json + ### strict Default: `true` @@ -142,7 +150,7 @@ Default: `css` Type: `string` -Possible values: `css`, `scss`, `styl`, `less` +Possible values: `css`, `scss`, `less` The file extension to be used for style files. diff --git a/nx-dev/nx-dev/public/documentation/latest/react/api-angular/generators/downgrade-module.md b/nx-dev/nx-dev/public/documentation/latest/react/api-angular/generators/downgrade-module.md index 83a9b97974..f0fa6fc1e7 100644 --- a/nx-dev/nx-dev/public/documentation/latest/react/api-angular/generators/downgrade-module.md +++ b/nx-dev/nx-dev/public/documentation/latest/react/api-angular/generators/downgrade-module.md @@ -1,6 +1,6 @@ # downgrade-module -Setup Downgrade Module +Setup Downgrade Module. ## Usage @@ -40,7 +40,7 @@ The name of the main AngularJS module. Type: `string` -The name of the project +The name of the project. ### skipFormat @@ -48,7 +48,7 @@ Default: `false` Type: `boolean` -Skip formatting files +Skip formatting files. ### skipPackageJson @@ -56,4 +56,4 @@ Default: `false` Type: `boolean` -Do not add @angular/upgrade to package.json (e.g., --skipPackageJson) +Do not add @angular/upgrade to package.json (e.g., --skipPackageJson). diff --git a/nx-dev/nx-dev/public/documentation/latest/react/api-angular/generators/library.md b/nx-dev/nx-dev/public/documentation/latest/react/api-angular/generators/library.md index 617acfa27e..a2d8fa56f9 100644 --- a/nx-dev/nx-dev/public/documentation/latest/react/api-angular/generators/library.md +++ b/nx-dev/nx-dev/public/documentation/latest/react/api-angular/generators/library.md @@ -150,6 +150,14 @@ Type: `boolean` Do not update tsconfig.json for development experience. +### standaloneConfig + +Default: `false` + +Type: `boolean` + +Split the project configuration into /project.json rather than including it inside workspace.json + ### strict Default: `true` diff --git a/nx-dev/nx-dev/public/documentation/latest/react/api-angular/generators/ngrx.md b/nx-dev/nx-dev/public/documentation/latest/react/api-angular/generators/ngrx.md index 9d4a0f23dc..7995a15629 100644 --- a/nx-dev/nx-dev/public/documentation/latest/react/api-angular/generators/ngrx.md +++ b/nx-dev/nx-dev/public/documentation/latest/react/api-angular/generators/ngrx.md @@ -1,6 +1,6 @@ # ngrx -Add an ngrx config to a project +Add NgRx support to an application or library. ## Usage @@ -66,23 +66,27 @@ The path to NgModule where the feature state will be registered. The host direct Type: `string` -Name of the NgRx feature state, such as "products" or "users"). Recommended to use the plural form of the name. +Name of the NgRx feature state, such as `products` or `users`. Recommended to use the plural form of the name. -### onlyAddFiles +### ~~onlyAddFiles~~ Default: `false` Type: `boolean` -**Deprecated**, use `skipImport`. Only add new NgRx files, without changing the module file (e.g., --onlyAddFiles). +**Deprecated:** Use the `skipImport` option instead. -### onlyEmptyRoot +Only add new NgRx files, without changing the module file (e.g., --onlyAddFiles). + +### ~~onlyEmptyRoot~~ Default: `false` Type: `boolean` -**Deprecated**, use `minimal`. Do not generate any files. Only generate StoreModule.forRoot and EffectsModule.forRoot (e.g., --onlyEmptyRoot). +**Deprecated:** Use the `minimal` option instead. + +Do not generate any files. Only generate StoreModule.forRoot and EffectsModule.forRoot (e.g., --onlyEmptyRoot). ### root diff --git a/nx-dev/nx-dev/public/documentation/latest/react/api-angular/generators/upgrade-module.md b/nx-dev/nx-dev/public/documentation/latest/react/api-angular/generators/upgrade-module.md index 093f05de01..bf85ee63b3 100644 --- a/nx-dev/nx-dev/public/documentation/latest/react/api-angular/generators/upgrade-module.md +++ b/nx-dev/nx-dev/public/documentation/latest/react/api-angular/generators/upgrade-module.md @@ -1,6 +1,6 @@ # upgrade-module -Add an upgrade module +Add an upgrade module. ## Usage @@ -28,7 +28,7 @@ nx g upgrade-module ... --dry-run Type: `string` -The selector of an AngularJS component (e.g., --angularJsCmpSelector=myComponent) +The selector of an AngularJS component (e.g., --angularJsCmpSelector=myComponent). ### angularJsImport @@ -46,7 +46,7 @@ The name of the main AngularJS module. Type: `string` -The name of the project +The name of the project. ### router @@ -54,7 +54,7 @@ Default: `false` Type: `boolean` -Sets up router synchronization (e.g., --router) +Sets up router synchronization (e.g., --router). ### skipFormat @@ -62,7 +62,7 @@ Default: `false` Type: `boolean` -Skip formatting files +Skip formatting files. ### skipPackageJson @@ -70,4 +70,4 @@ Default: `false` Type: `boolean` -Do not add @angular/upgrade to package.json (e.g., --skipPackageJson) +Do not add @angular/upgrade to package.json (e.g., --skipPackageJson). diff --git a/nx-dev/nx-dev/public/documentation/latest/react/api-angular/generators/web-worker.md b/nx-dev/nx-dev/public/documentation/latest/react/api-angular/generators/web-worker.md new file mode 100644 index 0000000000..67031d48f7 --- /dev/null +++ b/nx-dev/nx-dev/public/documentation/latest/react/api-angular/generators/web-worker.md @@ -0,0 +1,59 @@ +# web-worker + +Create a Web Worker. + +## Usage + +```bash +nx generate web-worker ... +``` + +By default, Nx will search for `web-worker` in the default collection provisioned in `workspace.json`. + +You can specify the collection explicitly as follows: + +```bash +nx g @nrwl/angular:web-worker ... +``` + +Show what will be generated without writing to disk: + +```bash +nx g web-worker ... --dry-run +``` + +## Options + +### name + +Type: `string` + +The name of the worker. + +### path + +Type: `string` + +The path at which to create the worker file, relative to the current workspace. + +### project + +Type: `string` + +The name of the project. + +### skipFormat + +Default: `false` + +Type: `boolean` + +Skip formatting files. + +### snippet + +Default: `true` + +Type: `boolean` + +Add a worker creation snippet in a sibling file of the same name. diff --git a/nx-dev/nx-dev/public/documentation/latest/react/api-express/generators/application.md b/nx-dev/nx-dev/public/documentation/latest/react/api-express/generators/application.md index c801960e6a..1f5b44281a 100644 --- a/nx-dev/nx-dev/public/documentation/latest/react/api-express/generators/application.md +++ b/nx-dev/nx-dev/public/documentation/latest/react/api-express/generators/application.md @@ -98,6 +98,14 @@ Type: `boolean` Do not add dependencies to package.json. +### standaloneConfig + +Default: `false` + +Type: `boolean` + +Split the project configuration into /project.json rather than including it inside workspace.json + ### tags Type: `string` diff --git a/nx-dev/nx-dev/public/documentation/latest/react/api-gatsby/generators/application.md b/nx-dev/nx-dev/public/documentation/latest/react/api-gatsby/generators/application.md index 7269ac5bbd..304a5932ed 100644 --- a/nx-dev/nx-dev/public/documentation/latest/react/api-gatsby/generators/application.md +++ b/nx-dev/nx-dev/public/documentation/latest/react/api-gatsby/generators/application.md @@ -66,6 +66,14 @@ Type: `boolean` Whether or not to configure the ESLint "parserOptions.project" option. We do not do this by default for lint performance reasons. +### standaloneConfig + +Default: `false` + +Type: `boolean` + +Split the project configuration into /project.json rather than including it inside workspace.json + ### style Alias(es): s diff --git a/nx-dev/nx-dev/public/documentation/latest/react/api-nest/generators/application.md b/nx-dev/nx-dev/public/documentation/latest/react/api-nest/generators/application.md index cca4d44354..bff9cfa98d 100644 --- a/nx-dev/nx-dev/public/documentation/latest/react/api-nest/generators/application.md +++ b/nx-dev/nx-dev/public/documentation/latest/react/api-nest/generators/application.md @@ -72,6 +72,14 @@ Type: `boolean` Do not add dependencies to package.json. +### standaloneConfig + +Default: `false` + +Type: `boolean` + +Split the project configuration into /project.json rather than including it inside workspace.json + ### tags Type: `string` diff --git a/nx-dev/nx-dev/public/documentation/latest/react/api-next/generators/application.md b/nx-dev/nx-dev/public/documentation/latest/react/api-next/generators/application.md index ebdc892804..7fdb044de5 100644 --- a/nx-dev/nx-dev/public/documentation/latest/react/api-next/generators/application.md +++ b/nx-dev/nx-dev/public/documentation/latest/react/api-next/generators/application.md @@ -108,6 +108,14 @@ Type: `boolean` Skip updating workspace.json with default options based on values provided to this app (e.g. babel, style) +### standaloneConfig + +Default: `false` + +Type: `boolean` + +Split the project configuration into /project.json rather than including it inside workspace.json + ### style Alias(es): s diff --git a/nx-dev/nx-dev/public/documentation/latest/react/api-node/generators/application.md b/nx-dev/nx-dev/public/documentation/latest/react/api-node/generators/application.md index 7978f16169..6da0095e63 100644 --- a/nx-dev/nx-dev/public/documentation/latest/react/api-node/generators/application.md +++ b/nx-dev/nx-dev/public/documentation/latest/react/api-node/generators/application.md @@ -106,6 +106,14 @@ Type: `boolean` Do not add dependencies to package.json. +### standaloneConfig + +Default: `false` + +Type: `boolean` + +Split the project configuration into /project.json rather than including it inside workspace.json + ### tags Type: `string` diff --git a/nx-dev/nx-dev/public/documentation/latest/react/api-node/generators/library.md b/nx-dev/nx-dev/public/documentation/latest/react/api-node/generators/library.md index 3097fb9634..317300e3be 100644 --- a/nx-dev/nx-dev/public/documentation/latest/react/api-node/generators/library.md +++ b/nx-dev/nx-dev/public/documentation/latest/react/api-node/generators/library.md @@ -138,6 +138,14 @@ Type: `boolean` Do not update tsconfig.base.json for development experience. +### standaloneConfig + +Default: `false` + +Type: `boolean` + +Split the project configuration into /project.json rather than including it inside workspace.json + ### strict Default: `false` diff --git a/nx-dev/nx-dev/public/documentation/latest/react/api-nx-devkit/index.md b/nx-dev/nx-dev/public/documentation/latest/react/api-nx-devkit/index.md index 9a38cb6e71..c57d7462ae 100644 --- a/nx-dev/nx-dev/public/documentation/latest/react/api-nx-devkit/index.md +++ b/nx-dev/nx-dev/public/documentation/latest/react/api-nx-devkit/index.md @@ -60,9 +60,11 @@ - [applyChangesToString](../../react/nx-devkit/index#applychangestostring) - [convertNxExecutor](../../react/nx-devkit/index#convertnxexecutor) - [convertNxGenerator](../../react/nx-devkit/index#convertnxgenerator) +- [detectPackageManager](../../react/nx-devkit/index#detectpackagemanager) - [formatFiles](../../react/nx-devkit/index#formatfiles) - [generateFiles](../../react/nx-devkit/index#generatefiles) - [getPackageManagerCommand](../../react/nx-devkit/index#getpackagemanagercommand) +- [getPackageManagerVersion](../../react/nx-devkit/index#getpackagemanagerversion) - [getProjects](../../react/nx-devkit/index#getprojects) - [getWorkspaceLayout](../../react/nx-devkit/index#getworkspacelayout) - [getWorkspacePath](../../react/nx-devkit/index#getworkspacepath) @@ -473,7 +475,7 @@ Callback to install dependencies only if necessary. undefined is returned if cha ### addProjectConfiguration -▸ **addProjectConfiguration**(`host`: [_Tree_](../../react/nx-devkit/index#tree), `projectName`: _string_, `projectConfiguration`: [_ProjectConfiguration_](../../react/nx-devkit/index#projectconfiguration) & [_NxJsonProjectConfiguration_](../../react/nx-devkit/index#nxjsonprojectconfiguration)): _void_ +▸ **addProjectConfiguration**(`host`: [_Tree_](../../react/nx-devkit/index#tree), `projectName`: _string_, `projectConfiguration`: [_ProjectConfiguration_](../../react/nx-devkit/index#projectconfiguration) & [_NxJsonProjectConfiguration_](../../react/nx-devkit/index#nxjsonprojectconfiguration), `standalone?`: _boolean_): _void_ Adds project configuration to the Nx workspace. @@ -482,11 +484,12 @@ both files. #### Parameters -| Name | Type | Description | -| :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------------------------------------------------------------------- | -| `host` | [_Tree_](../../react/nx-devkit/index#tree) | the file system tree | -| `projectName` | _string_ | unique name. Often directories are part of the name (e.g., mydir-mylib) | -| `projectConfiguration` | [_ProjectConfiguration_](../../react/nx-devkit/index#projectconfiguration) & [_NxJsonProjectConfiguration_](../../react/nx-devkit/index#nxjsonprojectconfiguration) | project configuration | +| Name | Type | Default value | Description | +| :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------ | :----------------------------------------------------------------------------------------- | +| `host` | [_Tree_](../../react/nx-devkit/index#tree) | - | the file system tree | +| `projectName` | _string_ | - | unique name. Often directories are part of the name (e.g., mydir-mylib) | +| `projectConfiguration` | [_ProjectConfiguration_](../../react/nx-devkit/index#projectconfiguration) & [_NxJsonProjectConfiguration_](../../react/nx-devkit/index#nxjsonprojectconfiguration) | - | project configuration | +| `standalone` | _boolean_ | false | should the project use package.json? If false, the project config is inside workspace.json | **Returns:** _void_ @@ -577,6 +580,22 @@ Convert an Nx Generator into an Angular Devkit Schematic --- +### detectPackageManager + +▸ **detectPackageManager**(`dir?`: _string_): [_PackageManager_](../../react/nx-devkit/index#packagemanager) + +Detects which package manager is used in the workspace based on the lock file. + +#### Parameters + +| Name | Type | Default value | +| :---- | :------- | :------------ | +| `dir` | _string_ | '' | + +**Returns:** [_PackageManager_](../../react/nx-devkit/index#packagemanager) + +--- + ### formatFiles ▸ **formatFiles**(`host`: [_Tree_](../../react/nx-devkit/index#tree)): _Promise_ @@ -634,7 +653,7 @@ doesn't get confused about incorrect TypeScript files. ### getPackageManagerCommand -▸ **getPackageManagerCommand**(`packageManager?`: [_PackageManager_](../../react/nx-devkit/index#packagemanager)): _object_ +▸ **getPackageManagerCommand**(`packageManager?`: [_PackageManager_](../../react/nx-devkit/index#packagemanager)): PackageManagerCommands Returns commands for the package manager used in the workspace. By default, the package manager is derived based on the lock file, @@ -652,17 +671,25 @@ execSync(`${getPackageManagerCommand().addDev} my-dev-package`); | :--------------- | :------------------------------------------------------------- | | `packageManager` | [_PackageManager_](../../react/nx-devkit/index#packagemanager) | -**Returns:** _object_ +**Returns:** PackageManagerCommands -| Name | Type | -| :-------- | :------------------------------------------------- | -| `add` | _string_ | -| `addDev` | _string_ | -| `exec` | _string_ | -| `install` | _string_ | -| `list` | _string_ | -| `rm` | _string_ | -| `run` | (`script`: _string_, `args`: _string_) => _string_ | +--- + +### getPackageManagerVersion + +▸ **getPackageManagerVersion**(`packageManager?`: [_PackageManager_](../../react/nx-devkit/index#packagemanager)): _string_ + +Returns the version of the package manager used in the workspace. +By default, the package manager is derived based on the lock file, +but it can also be passed in explicitly. + +#### Parameters + +| Name | Type | +| :--------------- | :------------------------------------------------------------- | +| `packageManager` | [_PackageManager_](../../react/nx-devkit/index#packagemanager) | + +**Returns:** _string_ --- diff --git a/nx-dev/nx-dev/public/documentation/latest/react/api-nx-plugin/generators/plugin.md b/nx-dev/nx-dev/public/documentation/latest/react/api-nx-plugin/generators/plugin.md index f7bce6c1ba..2934ff0176 100644 --- a/nx-dev/nx-dev/public/documentation/latest/react/api-nx-plugin/generators/plugin.md +++ b/nx-dev/nx-dev/public/documentation/latest/react/api-nx-plugin/generators/plugin.md @@ -78,6 +78,14 @@ Type: `boolean` Do not update tsconfig.json for development experience. +### standaloneConfig + +Default: `false` + +Type: `boolean` + +Split the project configuration into /project.json rather than including it inside workspace.json + ### tags Alias(es): t diff --git a/nx-dev/nx-dev/public/documentation/latest/react/api-react/generators/application.md b/nx-dev/nx-dev/public/documentation/latest/react/api-react/generators/application.md index 15bc5d395c..db9e3c7ab8 100644 --- a/nx-dev/nx-dev/public/documentation/latest/react/api-react/generators/application.md +++ b/nx-dev/nx-dev/public/documentation/latest/react/api-react/generators/application.md @@ -150,6 +150,14 @@ Type: `boolean` Skip updating workspace.json with default options based on values provided to this app (e.g. babel, style). +### standaloneConfig + +Default: `false` + +Type: `boolean` + +Split the project configuration into /project.json rather than including it inside workspace.json + ### strict Default: `true` diff --git a/nx-dev/nx-dev/public/documentation/latest/react/api-react/generators/library.md b/nx-dev/nx-dev/public/documentation/latest/react/api-react/generators/library.md index bd622569cf..d605dfc63a 100644 --- a/nx-dev/nx-dev/public/documentation/latest/react/api-react/generators/library.md +++ b/nx-dev/nx-dev/public/documentation/latest/react/api-react/generators/library.md @@ -158,6 +158,14 @@ Type: `boolean` Do not update tsconfig.json for development experience. +### standaloneConfig + +Default: `false` + +Type: `boolean` + +Split the project configuration into /project.json rather than including it inside workspace.json + ### strict Default: `true` diff --git a/nx-dev/nx-dev/public/documentation/latest/react/api-react/generators/storybook-configuration.md b/nx-dev/nx-dev/public/documentation/latest/react/api-react/generators/storybook-configuration.md index c013ff5a7d..06dc9ea29f 100644 --- a/nx-dev/nx-dev/public/documentation/latest/react/api-react/generators/storybook-configuration.md +++ b/nx-dev/nx-dev/public/documentation/latest/react/api-react/generators/storybook-configuration.md @@ -77,3 +77,11 @@ The tool to use for running lint checks. Type: `string` Project name + +### standaloneConfig + +Default: `false` + +Type: `boolean` + +Split the project configuration into /project.json rather than including it inside workspace.json diff --git a/nx-dev/nx-dev/public/documentation/latest/react/api-storybook/generators/configuration.md b/nx-dev/nx-dev/public/documentation/latest/react/api-storybook/generators/configuration.md index dffb1048ab..6e982ee587 100644 --- a/nx-dev/nx-dev/public/documentation/latest/react/api-storybook/generators/configuration.md +++ b/nx-dev/nx-dev/public/documentation/latest/react/api-storybook/generators/configuration.md @@ -60,6 +60,14 @@ Type: `string` Library or application name +### standaloneConfig + +Default: `false` + +Type: `boolean` + +Split the project configuration into /project.json rather than including it inside workspace.json + ### uiFramework Type: `string` diff --git a/nx-dev/nx-dev/public/documentation/latest/react/api-storybook/generators/cypress-project.md b/nx-dev/nx-dev/public/documentation/latest/react/api-storybook/generators/cypress-project.md index 5783c6d340..c3e27b2976 100644 --- a/nx-dev/nx-dev/public/documentation/latest/react/api-storybook/generators/cypress-project.md +++ b/nx-dev/nx-dev/public/documentation/latest/react/api-storybook/generators/cypress-project.md @@ -53,3 +53,11 @@ The tool to use for running lint checks. Type: `string` Library or application name + +### standaloneConfig + +Default: `false` + +Type: `boolean` + +Split the project configuration into /project.json rather than including it inside workspace.json diff --git a/nx-dev/nx-dev/public/documentation/latest/react/api-web/generators/application.md b/nx-dev/nx-dev/public/documentation/latest/react/api-web/generators/application.md index 914d89a1c5..e2595bf10f 100644 --- a/nx-dev/nx-dev/public/documentation/latest/react/api-web/generators/application.md +++ b/nx-dev/nx-dev/public/documentation/latest/react/api-web/generators/application.md @@ -76,6 +76,14 @@ Type: `boolean` Skip formatting files +### standaloneConfig + +Default: `false` + +Type: `boolean` + +Split the project configuration into /project.json rather than including it inside workspace.json + ### style Default: `css` diff --git a/nx-dev/nx-dev/public/documentation/latest/react/api-workspace/generators/convert-to-nx-project.md b/nx-dev/nx-dev/public/documentation/latest/react/api-workspace/generators/convert-to-nx-project.md new file mode 100644 index 0000000000..b86c1820e6 --- /dev/null +++ b/nx-dev/nx-dev/public/documentation/latest/react/api-workspace/generators/convert-to-nx-project.md @@ -0,0 +1,51 @@ +# convert-to-nx-project + +Moves a project's configuration outside of workspace.json + +## Usage + +```bash +nx generate convert-to-nx-project ... +``` + +By default, Nx will search for `convert-to-nx-project` in the default collection provisioned in `workspace.json`. + +You can specify the collection explicitly as follows: + +```bash +nx g @nrwl/workspace:convert-to-nx-project ... +``` + +Show what will be generated without writing to disk: + +```bash +nx g convert-to-nx-project ... --dry-run +``` + +### Examples + +Convert the my-feature-lib project to use project.json file instead of workspace.json: + +```bash +nx g @nrwl/workspace:convert-to-nx-project --project my-feature-lib +``` + +Convert all projects in workspace.json to separate project.json files.: + +```bash +nx g @nrwl/workspace:convert-to-nx-project --all +``` + +## Options + +### all + +Type: `boolean` + +Should every project be converted? + +### project + +Type: `string` + +Project name diff --git a/nx-dev/nx-dev/public/documentation/latest/react/api-workspace/generators/library.md b/nx-dev/nx-dev/public/documentation/latest/react/api-workspace/generators/library.md index 44fd48eafb..1e2dd53851 100644 --- a/nx-dev/nx-dev/public/documentation/latest/react/api-workspace/generators/library.md +++ b/nx-dev/nx-dev/public/documentation/latest/react/api-workspace/generators/library.md @@ -130,6 +130,14 @@ Type: `boolean` Do not update tsconfig.json for development experience. +### standaloneConfig + +Default: `false` + +Type: `boolean` + +Split the project configuration into /project.json rather than including it inside workspace.json + ### strict Default: `false` diff --git a/nx-dev/nx-dev/public/documentation/latest/react/cli/affected-dep-graph.md b/nx-dev/nx-dev/public/documentation/latest/react/cli/affected-dep-graph.md index 1f5311aa42..e96515443d 100644 --- a/nx-dev/nx-dev/public/documentation/latest/react/cli/affected-dep-graph.md +++ b/nx-dev/nx-dev/public/documentation/latest/react/cli/affected-dep-graph.md @@ -131,3 +131,9 @@ Print additional error stack trace on failure ### version Show version number + +### watch + +Default: `false` + +Watch for changes to dep graph and update in-browser diff --git a/nx-dev/nx-dev/public/documentation/latest/react/cli/dep-graph.md b/nx-dev/nx-dev/public/documentation/latest/react/cli/dep-graph.md index 7de42387d7..8db615a505 100644 --- a/nx-dev/nx-dev/public/documentation/latest/react/cli/dep-graph.md +++ b/nx-dev/nx-dev/public/documentation/latest/react/cli/dep-graph.md @@ -54,6 +54,12 @@ Show the graph where every node is either an ancestor or a descendant of todos-f nx dep-graph --focus=todos-feature-main --exclude=project-one,project-two ``` +Watch for changes to dep graph and update in-browser: + +```bash +nx dep-graph --watch +``` + ## Options ### exclude @@ -87,3 +93,9 @@ Bind the dep graph server to a specific port. ### version Show version number + +### watch + +Default: `false` + +Watch for changes to dep graph and update in-browser diff --git a/nx-dev/nx-dev/public/documentation/latest/react/getting-started/intro.md b/nx-dev/nx-dev/public/documentation/latest/react/getting-started/intro.md index 492695c2f0..a3b4d5df09 100644 --- a/nx-dev/nx-dev/public/documentation/latest/react/getting-started/intro.md +++ b/nx-dev/nx-dev/public/documentation/latest/react/getting-started/intro.md @@ -17,7 +17,7 @@ Nx works especially well for [monorepos](/{{framework}}/core-concepts/why-monore ## Features - Test (or builds or lints) only the projects [affected](/{{framework}}/cli/affected) by a code change. -- [Cache](/{{framework}}/core-concepts/computation-caching) command output locally so that future runs on the same code happen in seconds. The paid [Nx Cloud](https://nx.app) offering allows this cache to be shared across every developer in your organization. +- [Cache](/{{framework}}/core-extended/computation-caching) command output locally so that future runs on the same code happen in seconds. The paid [Nx Cloud](https://nx.app) offering allows this cache to be shared across every developer in your organization. - Provide a consistent syntax for [executing commands](/{{framework}}/executors/using-builders). `nx build my-app` works no matter what framework `my-app` uses. - Automate code modification tasks with [generators](/{{framework}}/cli/affected). - Access a thriving ecosystem of [plugins](/{{framework}}/generators/using-schematics) from Nrwl and the [community](/community). @@ -32,5 +32,5 @@ Nx works especially well for [monorepos](/{{framework}}/core-concepts/why-monore - [Nx CLI](/{{framework}}/getting-started/nx-cli) - [Configuration Files](/{{framework}}/core-concepts/configuration) -- [Computation Caching](/{{framework}}/core-concepts/computation-caching) -- [Rebuilding What is Affected](/{{framework}}/core-concepts/affected) +- [Computation Caching](/{{framework}}/core-extended/computation-caching) +- [Rebuilding What is Affected](/{{framework}}/core-extended/affected) diff --git a/nx-dev/nx-dev/public/documentation/latest/react/getting-started/nx-cli.md b/nx-dev/nx-dev/public/documentation/latest/react/getting-started/nx-cli.md index 6de49934dc..c48ae96593 100644 --- a/nx-dev/nx-dev/public/documentation/latest/react/getting-started/nx-cli.md +++ b/nx-dev/nx-dev/public/documentation/latest/react/getting-started/nx-cli.md @@ -41,23 +41,22 @@ nx workspace-generator my-generator [The first command](/{{framework}}/cli/generate) scaffolds a new customizable workspace generator named `my-generator` and [the second command](/{{framework}}/cli/workspace-generator) invokes it. -**Update plugins:** - -```bash -nx migrate latest -nx migrate --run-migrations=migrations.json -``` - -[The first command](/{{framework}}/cli/migrate) updates the installed Nx plugin versions and creates a list of generators to keep configuration files up to date. [The second command](/{{framework}}/cli/migrate) invokes those generators. - **Run an executor on one project:** ```bash -nx run my-app:build -nx build my-app +nx run my-react-app:build +nx build my-react-app ``` -Both of [these commands](/{{framework}}/cli/run) build the `my-app` application. Custom executors need to use the more verbose `nx run project:target` syntax. See the [workspace.json documentation](/{{framework}}/core-concepts/configuration) for information on configuring executor options. +Both of [these commands](/{{framework}}/cli/run) build the `my-app` application. See the [workspace.json documentation](/{{framework}}/core-concepts/configuration) for information on configuring executor options. + +**Run an executor for many projects:** + +```bash +nx run-many --target=build --projects=app1,app2 +``` + +[This command](/{{framework}}/cli/run-many) builds `app1` and `app2`. **Run an executor for all affected projects:** @@ -71,10 +70,11 @@ nx affected --target=build ```bash nx dep-graph +nx dep-graph --watch nx affected:dep-graph ``` -[The first command](/{{framework}}/cli/dep-graph) launches a web browser with repository's dependency graph rendered visually. [The second command](/{{framework}}/cli/affected-dep-graph) renders the same graph with projects affected by the current code change highlighted. +[The first command](/{{framework}}/cli/dep-graph) launches a web browser with repository's dependency graph rendered visually. You can add the `--watch` flag to watch for changes to the dep grpah and update the view in-browser. [The second command](/{{framework}}/cli/affected-dep-graph) renders the same graph with projects affected by the current code change highlighted. **List installed plugins:** @@ -83,3 +83,17 @@ nx list ``` [This command](/{{framework}}/cli/list) lists the currently installed Nx plugins and shows other plugins that are available. + +**Update plugins:** + +```bash +nx migrate latest +nx migrate --run-migrations=migrations.json +``` + +[The first command](/{{framework}}/cli/migrate) updates the installed Nx plugin versions and creates a list of generators to keep configuration files up to date. [The second command](/{{framework}}/cli/migrate) invokes those generators. + +## Common Env Variables + +- Setting **NX_VERBOSE_LOGGING=true** will print debug information useful for troubleshooting. +- Setting **NX_PERF_LOGGING=true** will print debug information useful for profiling executors and Nx itself. diff --git a/nx-dev/nx-dev/public/documentation/latest/react/guides/configuration.md b/nx-dev/nx-dev/public/documentation/latest/react/guides/configuration.md index 8404bd7c8c..59ea456d31 100644 --- a/nx-dev/nx-dev/public/documentation/latest/react/guides/configuration.md +++ b/nx-dev/nx-dev/public/documentation/latest/react/guides/configuration.md @@ -18,6 +18,12 @@ The `workspace.json` configuration file contains information about the targets a "build": { "executor": "@nrwl/web:build", "outputs": ["dist/apps/myapp"], + "dependsOn": [ + { + "target": "build", + "projects": "dependencies" + } + ], "options": { "index": "apps/myapp/src/app.html", "main": "apps/myapp/src/main.ts" @@ -89,9 +95,11 @@ For instance, the following configures `mylib`. - `root` tells Nx the location of the library including its sources and configuration files. - `sourceRoot` tells Nx the location of the library's source files. -- `projectType` is either 'application' or 'library'. +- `projectType` is either 'application' or 'library'. The project type is used in dep graph viz and in a few aux commands. - `targets` configures all the targets which define what tasks you can run against the library. +> Projects utilizing `project.json` files will not be present in `workspace.json`. + ### Targets Let's look at the simple target: @@ -110,7 +118,7 @@ Let's look at the simple target: **Target Name** -The name of the target `test` means that you can invoke it as follows: `nx test mylib` or `nx run mylib:test`. The name isn't significant in any other way. If you rename it to, for example, `mytest`, you will be able to run as follows: `nx run mylib:mytest`. +The name of the target `test` means that you can invoke it as follows: `nx test mylib` or `nx run mylib:test`. The name isn't significant in any other way. If you rename it to, for example, `mytest`, you will be able to run as follows: `nx mytest mylib` or `nx run mylib:mytest`. **Executor** @@ -176,6 +184,66 @@ require(`@nrwl/jest`).executors['jest']({...options, ...selectedConfiguration, . The selected configuration adds/overrides the default options, and the provided command line args add/override the configuration options. +**Target Dependencies** + +Targets can depend on other targets. A common scenario is having to build dependencies of a project first before building the project. You can specify this using the `dependsOn`. + +```json +{ + "build": { + "executor": "@nrwl/web:build", + "outputs": ["dist/apps/myapp"], + "options": { + "index": "apps/myapp/src/app.html", + "main": "apps/myapp/src/main.ts" + }, + "dependsOn": [ + { + "target": "build", + "projects": "dependencies" + } + ] + } +} +``` + +In this case, running `nx build myapp` will build all the buildable libraries `myapp` depends on first. In other words, `nx build myapp` will result in multiple tasks executing. The `--parallel`, and `--max-parallel` flags will have the same effect as they would with `run-many` or `affected`. + +It is also possible to define dependencies between the targets of the same project. + +In the following example invoking `nx build myapp` will build all the libraries first, then `nx build-base myapp` will be executed and only then `nx build myapp` will be executed. + +```json +{ + "build-base": { + "executor": "@nrwl/web:build", + "outputs": ["dist/apps/myapp"], + "options": { + "index": "apps/myapp/src/app.html", + "main": "apps/myapp/src/main.ts" + } + }, + "build": { + "executor": "@nrwl/workspace:run-commands", + "dependsOn": [ + { + "target": "build", + "projects": "dependencies" + }, + { + "target": "build-base", + "projects": "self" + } + ], + "options": { + "command": "./copy-readme-and-license.sh" + } + } +} +``` + +Often the same `dependsOn` configuration has to be defined for every project in the repo. You can define it once in `nx.json` (see below). + ### Generators You can configure default generator options in `workspace.json` as well. For instance, the following will tell Nx to always pass `--js` when creating new libraries. @@ -224,6 +292,33 @@ The following command will generate a new library: `nx g @nrwl/react:lib mylib`. When the `version` of `workspace.json` is set to 2, `targets`, `generators` and `executor` properties are used instead of the version 1 properties `architect`, `schematics` and `builder`. +## project.json + +Project configurations can also be independent files, referenced by `workspace.json`. For instance, a `workspace.json` may contain projects configured as below. + +```json +{ + "projects": { + "mylib": "libs/mylib" + } +} +``` + +This tells Nx that all configuration for that project is found in the `libs/mylib/project.json` file. This file contains a combination of the project's configuration from both `workspace.json` and `nx.json`. + +```json +{ + "mylib": { + "root": "libs/mylib/", + "sourceRoot": "libs/mylib/src", + "projectType": "library", + "targets": {}, + "tags": [], + "implicitDependencies": [] + } +} +``` + ## nx.json The `nx.json` file contains extra configuration options mostly related to the project graph. @@ -251,6 +346,14 @@ The `nx.json` file contains extra configuration options mostly related to the pr "tsconfig.base.json": "*", "nx.json": "*" }, + "targetDependencies": { + "build": [ + { + "target": "build", + "projects": "dependencies" + } + ] + }, "projects": { "myapp": { "tags": [] @@ -358,3 +461,39 @@ You can also add dependencies between projects. For instance, the example below } } ``` + +> Projects utilizing `project.json` files will not be present in `nx.json`. + +### Target Dependencies + +Targets can depend on other targets. A common scenario is having to build dependencies of a project first before building the project. The `dependsOn` property in `workspace.json` can be used to define the list of dependencies of an individual target. + +Often the same `dependsOn` configuration has to be defined for every project in the repo, and that's when defining `targetDependencies` in `nx.json` is helpful. + +```json +{ + "targetDependencies": { + "build": [ + { + "target": "build", + "projects": "dependencies" + } + ] + } +} +``` + +The configuration above is identical to adding `{"dependsOn": [{"target": "build", "projects": "dependencies"]}` to every build target in `workspace.json`. + +The `dependsOn` property in `workspace.json` takes precedence over the `targetDependencies` in `nx.json`. + +## .nxignore + +You may optionally add an `.nxignore` file to the root. This file is used to specify files in your workspace that should be completely ignored by Nx. + +The syntax is the same as a [`.gitignore` file](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository#_ignoring). + +**When a file is specified in the `.nxignore` file:** + +1. Changes to that file will not be taken into account in the `affected` calculations. +2. Even if the file is outside an app or library, `nx workspace-lint` will not warn about it. diff --git a/nx-dev/nx-dev/public/documentation/latest/react/guides/environment-variables.md b/nx-dev/nx-dev/public/documentation/latest/react/guides/environment-variables.md index 27044501c1..03943a07f3 100644 --- a/nx-dev/nx-dev/public/documentation/latest/react/guides/environment-variables.md +++ b/nx-dev/nx-dev/public/documentation/latest/react/guides/environment-variables.md @@ -58,7 +58,7 @@ For example: 2. `workspaceRoot/apps/my-app/.env` contains `AUTH_URL=https://prod-url.com/auth` 3. Nx will first load the variables from `apps/my-app/.env.local` into the process. When it tries to load the variables from `apps/my-app/.env`, it will notice that `AUTH_URL` already exists, so it will ignore it. -We recommend nesting your **app** specific `env` files in `apps/your-app`, and creating workspace/root level `env` files for workspace-specific settings (like the [Nx Cloud token](/{{framework}}/core-concepts/computation-caching#nx-cloud-and-distributed-computation-caching)). +We recommend nesting your **app** specific `env` files in `apps/your-app`, and creating workspace/root level `env` files for workspace-specific settings (like the [Nx Cloud token](/{{framework}}/core-extended/computation-caching#nx-cloud-and-distributed-computation-caching)). ### Pointing to custom env files diff --git a/nx-dev/nx-dev/public/documentation/latest/react/guides/nextjs-webpack5.md b/nx-dev/nx-dev/public/documentation/latest/react/guides/nextjs-webpack5.md index eff052ba04..29e8a5d533 100644 --- a/nx-dev/nx-dev/public/documentation/latest/react/guides/nextjs-webpack5.md +++ b/nx-dev/nx-dev/public/documentation/latest/react/guides/nextjs-webpack5.md @@ -8,9 +8,14 @@ Next.js applications within an Nx workspace are generated with a `next.config.js // eslint-disable-next-line @typescript-eslint/no-var-requires const withNx = require('@nrwl/next/plugins/with-nx'); -module.exports = withNx({ +/** + * @type {import('@nrwl/next/plugins/with-nx').WithNxOptions} + **/ +const nextConfig = { future: { webpack5: true, }, -}); +}; + +module.exports = withNx(nextConfig); ``` diff --git a/nx-dev/nx-dev/public/documentation/latest/react/guides/nextjs.md b/nx-dev/nx-dev/public/documentation/latest/react/guides/nextjs.md index e0eb2e2f0e..212b76730c 100644 --- a/nx-dev/nx-dev/public/documentation/latest/react/guides/nextjs.md +++ b/nx-dev/nx-dev/public/documentation/latest/react/guides/nextjs.md @@ -157,7 +157,12 @@ Let's continue to use our `tuskdesk` example from above, and so we need to check // eslint-disable-next-line @typescript-eslint/no-var-requires const withNx = require('@nrwl/next/plugins/with-nx'); -module.exports = withNx({}); +/** + * @type {import('@nrwl/next/plugins/with-nx').WithNxOptions} + **/ +const nextConfig = {}; + +module.exports = withNx(nextConfig); ``` If you have a config which looks like that (leveraging the `withNx()` config plugin) **AND** the version of Nx you are using is `11.1.0` or later, **no further action is needed** in your config. @@ -180,10 +185,15 @@ E.g. // eslint-disable-next-line @typescript-eslint/no-var-requires const withNx = require('@nrwl/next/plugins/with-nx'); -module.exports = withNx({ +/** + * @type {import('@nrwl/next/plugins/with-nx').WithNxOptions} + **/ +const nextConfig = { target: 'experimental-serverless-trace', // ...You can of course have other Next.js config options specified here too, but the "target" is critical for Vercel deployments... -}); +}; + +module.exports = withNx(nextConfig); ``` OR diff --git a/nx-dev/nx-dev/public/documentation/latest/react/guides/storybook-plugin.md b/nx-dev/nx-dev/public/documentation/latest/react/guides/storybook-plugin.md index 1762f9d3fe..4e0900c45c 100644 --- a/nx-dev/nx-dev/public/documentation/latest/react/guides/storybook-plugin.md +++ b/nx-dev/nx-dev/public/documentation/latest/react/guides/storybook-plugin.md @@ -374,13 +374,3 @@ Your folder structure should now look like this: ├── README.md └── etc... ``` - -### Storybook v6 args and controls - -Storybook v6 moves from "knobs" to args and controls when it comes to defining and manipulating your storybook -component properties. Feel free to use the new args way of defining stories. More can be found -[on the official Storybook docs](https://storybook.js.org/docs/react/writing-stories/args). - -> **Note:** Nx does not yet automatically generate stories that use the args syntax. The main reason is that args don't -> yet support being loaded via the iframe URL which is used in Nx to setup your Storybook based e2e tests. Once support -> is present in Storybook v6, we will provide a way to generate args & controls based stories. More on the progress [here](https://github.com/storybookjs/storybook/issues/12291). diff --git a/nx-dev/nx-dev/public/documentation/latest/react/tutorial/10-computation-caching.md b/nx-dev/nx-dev/public/documentation/latest/react/tutorial/10-computation-caching.md index 1e58540d14..6fb8c5c30e 100644 --- a/nx-dev/nx-dev/public/documentation/latest/react/tutorial/10-computation-caching.md +++ b/nx-dev/nx-dev/public/documentation/latest/react/tutorial/10-computation-caching.md @@ -54,7 +54,7 @@ Based on the state of the source code and the environment, Nx was able to figure Nx read the output from cache instead of running the command for 1 out of 2 projects. ``` -Nx built `api` and retrieved `todos` from its computation cache. Read more about the cache [here](/{{framework}}/core-concepts/computation-caching). +Nx built `api` and retrieved `todos` from its computation cache. Read more about the cache [here](/{{framework}}/core-extended/computation-caching). ## --with-deps diff --git a/nx-dev/nx-dev/public/documentation/latest/react/tutorial/12-summary.md b/nx-dev/nx-dev/public/documentation/latest/react/tutorial/12-summary.md index baf2fd890e..4a0cefcc3e 100644 --- a/nx-dev/nx-dev/public/documentation/latest/react/tutorial/12-summary.md +++ b/nx-dev/nx-dev/public/documentation/latest/react/tutorial/12-summary.md @@ -14,5 +14,5 @@ In this tutorial you: **Dive Deep:** - [Nx CLI](/{{framework}}/getting-started/nx-cli) -- [Computation Caching](/{{framework}}/core-concepts/computation-caching) -- [Rebuilding What is Affected](/{{framework}}/core-concepts/affected) +- [Computation Caching](/{{framework}}/core-extended/computation-caching) +- [Rebuilding What is Affected](/{{framework}}/core-extended/affected) diff --git a/nx-dev/nx-dev/public/documentation/latest/shared/computation-caching.md b/nx-dev/nx-dev/public/documentation/latest/shared/computation-caching.md index 55d65ce69f..209ad53b58 100644 --- a/nx-dev/nx-dev/public/documentation/latest/shared/computation-caching.md +++ b/nx-dev/nx-dev/public/documentation/latest/shared/computation-caching.md @@ -4,11 +4,15 @@ It's costly to rebuild and retest the same code over and over again. Nx uses a c **In order not to recompute something twice, we need two things:** -**1. We need to store the results of the computation.** -**2. We need to know when we are about to compute something we already computed before.** +1. We need to store the results of the computation. +2. We need to know when we are about to compute something we already computed before. There are three things that tell Nx if something has been computed before: +- [Source Code Cache Inputs](#source-code-cache-inputs) +- [Runtime Cache Inputs](#runtime-cache-inputs) +- [Args Cache Inputs](#args-cache-inputs) + ## Source Code Cache Inputs The result of building/testing an application or a library depends on the source code of that project and all the source codes of all the libraries it depends on (directly or indirectly). It also depends on the configuration files like `package.json`, `workspace.json`, `nx.json`, `tsconfig.base.json`, and `package-lock.json`. The list of these files isn't arbitrary. Nx can deduce most of them by analyzing our codebase. Few will have to be listed manually in the `implicitDependencies` property of `nx.json`. diff --git a/nx-dev/nx-dev/public/documentation/latest/shared/devkit-and-nx-plugins.md b/nx-dev/nx-dev/public/documentation/latest/shared/devkit-and-nx-plugins.md index ae8fe092cf..e35869a6ea 100644 --- a/nx-dev/nx-dev/public/documentation/latest/shared/devkit-and-nx-plugins.md +++ b/nx-dev/nx-dev/public/documentation/latest/shared/devkit-and-nx-plugins.md @@ -40,7 +40,7 @@ The Nx Devkit is the underlying technology used to customize Nx to support diffe ### Pay as you go -As with most things in Nx, the core of Nx Devkit is very simple. It only uses language primitives and immutable objects (the tree being the only exception). See [Simplest Generator](/{{framework}}/generators/using-schematics#simplest-generator) and [Simplest Executor](/{{framework}}/executors/using-builders#simplest-executor) for examples on creating generators and executors. The [Using Executors](/{{framework}}/executors/using-builders) and [Using Generators](/{{framework}}/generators/using-schematics) guides also have additional information on executors and generators. +As with most things in Nx, the core of Nx Devkit is very simple. It only uses language primitives and immutable objects (the tree being the only exception). See [Simplest Generator](/{{framework}}/generators/creating-files) and [Simplest Executor](/{{framework}}/executors/using-builders#simplest-executor) for examples on creating generators and executors. The [Using Executors](/{{framework}}/executors/using-builders) and [Using Generators](/{{framework}}/generators/using-schematics) guides also have additional information on executors and generators. ## Learn more diff --git a/nx-dev/nx-dev/public/documentation/latest/shared/generators/composing-generators.md b/nx-dev/nx-dev/public/documentation/latest/shared/generators/composing-generators.md new file mode 100644 index 0000000000..04186e0cb6 --- /dev/null +++ b/nx-dev/nx-dev/public/documentation/latest/shared/generators/composing-generators.md @@ -0,0 +1,18 @@ +# Composing Generators + +Generators are useful individually, but reusing and composing generators allows you to build whole workflows out of simpler building blocks. + +## Using Nx Devkit Generators + +Nx Devkit generators can be imported and invoked like any javascript function. They often return a `Promise`, so they can be used with the `await` keyword to mimic synchronous code. Because this is standard javascript, control flow logic can be adjusted with `if` blocks and `for` loops as usual. + +```typescript +import { libraryGenerator } from '@nrwl/workspace'; + +export default async function (tree: Tree, schema: any) { + await libraryGenerator( + tree, // virtual file system tree + { name: schema.name } // options for the generator + ); +} +``` diff --git a/nx-dev/nx-dev/public/documentation/latest/shared/generators/creating-files.md b/nx-dev/nx-dev/public/documentation/latest/shared/generators/creating-files.md new file mode 100644 index 0000000000..01a61879fc --- /dev/null +++ b/nx-dev/nx-dev/public/documentation/latest/shared/generators/creating-files.md @@ -0,0 +1,146 @@ +# Creating files with a generator + +Generators provide an API for managing files within your workspace. You can use generators to do things such as create, update, move, and delete files. Files with static or dynamic content can also be created. + +The generator below shows you how to generate a library, and then scaffold out additional files with the newly created library. + +First, you define a folder to store your static or dynamic templates used to generated files. This is commonly done in a `files` folder. + +```treeview +happynrwl/ +├── apps/ +├── libs/ +├── tools/ +│ ├── generators +│ | └── my-generator/ +│ | | └── files +│ | | └── NOTES.md +│ | | ├── index.ts +│ | | └── schema.json +├── nx.json +├── package.json +└── tsconfig.base.json +``` + +The files can use EJS syntax to substitute variables and logic. See the [EJS Docs](https://ejs.co/) to see more information about how to write these template files. + +Example NOTES.md: + +```markdown +Hello, my name is <%= name %>! +``` + +Next, update the `index.ts` file for the generator, and generate the new files. + +```typescript +import { + Tree, + formatFiles, + installPackagesTask, + generateFiles, + joinPathFragments, + readProjectConfiguration, +} from '@nrwl/devkit'; +import { libraryGenerator } from '@nrwl/workspace'; + +export default async function (tree: Tree, schema: any) { + await libraryGenerator(tree, { name: schema.name }); + const libraryRoot = readProjectConfiguration(tree, schema.name).root; + generateFiles( + tree, // the virtual file system + joinPathFragments(__dirname, './files'), // path to the file templates + libraryRoot, // destination path of the files + schema // config object to replace variable in file templates + ); + await formatFiles(tree); + return () => { + installPackagesTask(tree); + }; +} +``` + +The exported function first creates the library, then creates the additional files in the new library's folder. + +Next, run the generator: + +> Use the `-d` or `--dry-run` flag to see your changes without applying them. + +```bash +nx workspace-generator my-generator mylib +``` + +The following information will be displayed. + +```bash +CREATE libs/mylib/README.md +CREATE libs/mylib/.babelrc +CREATE libs/mylib/src/index.ts +CREATE libs/mylib/src/lib/mylib.spec.ts +CREATE libs/mylib/src/lib/mylib.ts +CREATE libs/mylib/tsconfig.json +CREATE libs/mylib/tsconfig.lib.json +UPDATE tsconfig.base.json +UPDATE workspace.json +UPDATE nx.json +CREATE libs/mylib/.eslintrc.json +CREATE libs/mylib/jest.config.js +CREATE libs/mylib/tsconfig.spec.json +UPDATE jest.config.js +CREATE libs/mylib/NOTES.md +``` + +`libs/mylib/NOTES.md` will contain the content with substituted variables: + +```markdown +Hello, my name is mylib! +``` + +## Dynamic File Names + +If you want the generated file or folder name to contain variable values, use `__variable__`. So `NOTES-for-__name__.md` would be resolved to `NOTES_for_mylib.md` in the above example. + +## EJS Syntax Quickstart + +The EJS syntax can do much more than replace variable names with values. Here are some common techniques. + +1. Pass a function into the template: + +```typescript +// template file +This is my <%= uppercase(name) %> +``` + +```typescript +// typescript file +function uppercase(val) { + val.toUppercase(); +} + +// later + +generateFiles(tree, joinPathFragments(__dirname, './files'), libraryRoot, { + uppercase, + name: schema.name, +}); +``` + +2. Use javascript for control flow in the template: + +```typescript +<% if(shortVersion) { %> +This is the short version. +<% } else { + for(let x=0; x + This text will be repeated <%= numRepetitions %> times. +<% } // end for loop +} // end else block %> +``` + +```typescript +// typescript file +generateFiles(tree, joinPathFragments(__dirname, './files'), libraryRoot, { + shortVerstion: false, + numRepetitions: 3, +}); +``` diff --git a/nx-dev/nx-dev/public/documentation/latest/shared/generators/generator-options.md b/nx-dev/nx-dev/public/documentation/latest/shared/generators/generator-options.md new file mode 100644 index 0000000000..4e3053819b --- /dev/null +++ b/nx-dev/nx-dev/public/documentation/latest/shared/generators/generator-options.md @@ -0,0 +1,103 @@ +# Customizing generator options + +## Adding a TypeScript schema + +To create a TypeScript schema to use in your generator function, define a TypeScript file next to your schema.json named `schema.ts`. Inside the `schema.ts`, define an interface to match the properties in your schema.json file, and whether they are required. + +```typescript +export interface GeneratorOptions { + name: string; + type?: string; +} +``` + +Import the TypeScript schema into your generator file and replace the any in your generator function with the interface. + +```typescript +import { Tree, formatFiles, installPackagesTask } from '@nrwl/devkit'; +import { libraryGenerator } from '@nrwl/workspace'; + +export default async function (tree: Tree, schema: GeneratorOptions) { + await libraryGenerator(tree, { name: `${schema.name}-${schema.type || ''}` }); + await formatFiles(tree); + return () => { + installPackagesTask(tree); + }; +} +``` + +## Adding static options + +Static options for a generator don't prompt the user for input. To add a static option, define a key in the schema.json file with the option name, and define an object with its type, description, and optional default value. + +```json +{ + "$schema": "http://json-schema.org/schema", + "id": "my-generator", + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Library name", + "$default": { + "$source": "argv", + "index": 0 + } + }, + "type": { + "type": "string", + "description": "Provide the library type, such as 'data-access' or 'state'" + } + }, + "required": ["name"] +} +``` + +If you run the generator without providing a value for the type, it is not included in the generated name of the library. + +## Adding dynamic prompts + +Dynamic options can prompt the user to select from a list of options. To define a prompt, add an `x-prompt` property to the option object, set the type to list, and define an items array for the choices. + +```json +{ + "$schema": "http://json-schema.org/schema", + "id": "my-generator", + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Library name", + "$default": { + "$source": "argv", + "index": 0 + } + }, + "type": { + "type": "string", + "description": "Provide the library type", + "x-prompt": { + "message": "Which type of library would you like to generate?", + "type": "list", + "items": [ + { + "value": "data-access", + "label": "Data Access" + }, + { + "value": "feature", + "label": "Feature" + }, + { + "value": "state", + "label": "State Management" + } + ] + } + } + }, + "required": ["name"] +} +``` + +Running the generator without providing a value for the type will prompt the user to make a selection. diff --git a/nx-dev/nx-dev/public/documentation/latest/shared/generators/modifying-files.md b/nx-dev/nx-dev/public/documentation/latest/shared/generators/modifying-files.md new file mode 100644 index 0000000000..8a0af7fb04 --- /dev/null +++ b/nx-dev/nx-dev/public/documentation/latest/shared/generators/modifying-files.md @@ -0,0 +1,132 @@ +# Modifying Files with a Generator + +Modifying existing files is an order of magnitude harder than creating new files, so care should be taken when trying to automate this process. When the situation merits it, automating a process can lead to tremendous benefits across the organization. Here are some approaches listed from simplest to most complex. + +## Compose Existing Generators + +If you can compose together existing generators to modify the files you need, you should take that approach. See [Composing Generators](./composing-generators) for more information. + +## Modify JSON Files + +JSON files are fairly simple to modify, given their predictable structure. + +The following example adds a `package.json` script that issues a friendly greeting. + +```typescript +import { updateJson } from '@nrwl/devkit'; + +export default async function (tree: Tree, schema: any) { + updateJson(tree, 'package.json', (pkgJson) => { + // if scripts is undefined, set it to an empty object + pkgJson.scripts = pkgJson.scripts ?? {}; + // add greet script + pkgJson.scripts.greet = 'echo "Hello!"'; + // return modified JSON object + return pkgJson; + }); +} +``` + +## String Replace + +For files that are not as predictable as JSON files (like `.ts`, `.md` or `.css` files), modifying the contents can get tricky. One approach is to do a find and replace on the string contents of the file. + +Let's say we want to replace any instance of `thomasEdison` with `nikolaTesla` in the `index.ts` file. + +```typescript +export default async function (tree: Tree, schema: any) { + const filePath = `path/to/index.ts`; + const contents = tree.read(filePath); + contents.replace('thomasEdison', 'nikolaTesla'); + tree.write(filePath, contents); +} +``` + +This works, but only replaces the first instance of `thomasEdison`. To replace them all, you need to use regular expressions. (Regular expressions also give you a lot more flexibility in how you search for a string.) + +```typescript +export default async function (tree: Tree, schema: any) { + const filePath = `path/to/index.ts`; + const contents = tree.read(filePath); + contents.replace(/thomasEdison/g, 'nikolaTesla'); + tree.write(filePath, contents); +} +``` + +## AST Manipulation + +ASTs (Abstract Syntax Trees) allow you to understand exactly the code you're modifying. Replacing a string value can accidentally modify text found in a comment rather than changing the name of a variable. + +We'll write a generator that replaces all instances of the type `Array` with `something[]`. To help accomplish this, we'll use the `@phenomnominal/tsquery` npm package and the [AST Explorer](https://astexplorer.net) site. TSQuery allows you to query and modify ASTs with a syntax similar to CSS selectors. The AST Explorer tool allows you to easily examine the AST for a given snippet of code. + +First, go to [AST Explorer](https://astexplorer.net) and paste in a snippet of code that contains the input and desired output of our generator. + +```typescript +// input +const arr: Array = []; + +// desired output +const arr: string[] = []; +``` + +Make sure the parser is set to `typescript`. When you place the cursor on the `Array` text, the right hand panel highlights the corresponding node of the AST. The AST node we're looking for looks like this: + +```typescript +{ // TypeReference + typeName: { // Identifier + escapedText: "Array" + }, + typeArguments: [/* this is where the generic type parameter is specified */] +} +``` + +Second, we need to choose a selector to target this node. Just like with CSS selectors, there is an art to choosing a selector that is specific enough to target the correct nodes, but not overly tied to a certain structure. For our simple example, we can use `TypeReference` to select the parent node and check to see if it has a `typeName` of `Array` before we perform the replacement. We'll then use the `typeArguments` to get the text inside the `<>` characters. + +The finished code looks like this: + +```typescript +import { readProjectConfiguration, Tree } from '@nrwl/devkit'; +import { tsquery } from '@phenomnomnominal/tsquery'; +import { TypeReferenceNode } from 'typescript'; + +/** + * Run the callback on all files inside the specified path + */ +function visitAllFiles( + tree: Tree, + path: string, + callback: (filePath: string) => void +) { + tree.children(path).forEach((fileName) => { + const filePath = `${path}/${fileName}`; + if (!tree.isFile(filePath)) { + visitAllFiles(tree, filePath, callback); + } else { + callback(filePath); + } + }); +} + +export default function (tree: Tree, schema: any) { + const sourceRoot = readProjectConfiguration(tree, schema.name).sourceRoot; + visitAllFiles(tree, sourceRoot, (filePath) => { + const fileEntry = tree.read(filePath); + const contents = fileEntry.toString(); + + // Check each `TypeReference` node to see if we need to replace it + const newContents = tsquery.replace(contents, 'TypeReference', (node) => { + const trNode = node as TypeReferenceNode; + if (trNode.typeName.getText() === 'Array') { + const typeArgument = trNode.typeArguments[0]; + return `${typeArgument.getText()}[]`; + } + // return undefined does not replace anything + }); + + // only write the file if something has changed + if (newContents !== contents) { + tree.write(filePath, newContents); + } + }); +} +``` diff --git a/nx-dev/nx-dev/public/documentation/latest/shared/generators/using-generators.md b/nx-dev/nx-dev/public/documentation/latest/shared/generators/using-generators.md new file mode 100644 index 0000000000..8c765ed11e --- /dev/null +++ b/nx-dev/nx-dev/public/documentation/latest/shared/generators/using-generators.md @@ -0,0 +1,26 @@ +# Using Generators + +## Overview + +Generators provide a way to automate many tasks you regularly perform as part of your development workflow. Whether it is scaffolding out components, features, ensuring libraries are generated and structured in a certain way, or updating your configuration files, generators help you standardize these tasks in a consistent, and predictable manner. + +The [Workspace Generators](/{{framework}}/generators/workspace-generators) guide shows you how to create, run, and customize workspace generators within your Nx workspace. + +## Types of Generators + +There are three main types of generators: + +1. **Plugin Generators** are available when an Nx plugin has been installed in your workspace. +2. **Workspace Generators** are generators that you can create for your own workspace. [Workspace generators](/{{framework}}/generators/workspace-generators) allow you to codify the processes that are unique to your own organization. +3. **Update Generators** are invoked by Nx plugins when you [update Nx](/{{framework}}/core-concepts/updating-nx) to keep your config files in sync with the latest versions of third party tools. + +## Invoking Plugin Generators + +Generators allow you to create or modify your codebase in a simple and repeatable way. Generators are invoked using the [`nx generate`](/{{framework}}/cli/generate) command. + +```bash +nx generate [plugin]:[generator-name] [options] +nx generate @nrwl/react:component mycmp --project=myapp +``` + +It is important to have a clean git working directory before invoking a generator so that you can easily revert changes and re-invoke the generator with different inputs. diff --git a/nx-dev/nx-dev/public/documentation/latest/shared/generators/workspace-generators.md b/nx-dev/nx-dev/public/documentation/latest/shared/generators/workspace-generators.md new file mode 100644 index 0000000000..d20da47d72 --- /dev/null +++ b/nx-dev/nx-dev/public/documentation/latest/shared/generators/workspace-generators.md @@ -0,0 +1,93 @@ +# Workspace Generators + +Workspace generators provide a way to automate many tasks you regularly perform as part of your development workflow. Whether it is scaffolding out components, features, or ensuring libraries are generated and structured in a certain way, generators help you standardize these tasks in a consistent, and predictable manner. Nx provides tooling around creating, and running custom generators from within your workspace. This guide shows you how to create, run, and customize workspace generators within your Nx workspace. + +## Creating a workspace generator + +Use the Nx CLI to generate the initial files needed for your workspace generator. + +```bash +nx generate @nrwl/workspace:workspace-generator my-generator +``` + +After the command is finished, the workspace generator is created under the `tools/generators` folder. + +```treeview +happynrwl/ +├── apps/ +├── libs/ +├── tools/ +│ ├── generators +│ | └── my-generator/ +│ | | ├── index.ts +│ | | └── schema.json +├── nx.json +├── package.json +└── tsconfig.base.json +``` + +The `index.ts` provides an entry point to the generator. The file contains a function that is called to perform manipulations on a tree that represents the file system. +The `schema.json` provides a description of the generator, available options, validation information, and default values. + +The initial generator function creates a library. + +```typescript +import { Tree, formatFiles, installPackagesTask } from '@nrwl/devkit'; +import { libraryGenerator } from '@nrwl/workspace'; + +export default async function (tree: Tree, schema: any) { + await libraryGenerator(tree, { name: schema.name }); + await formatFiles(tree); + return () => { + installPackagesTask(tree); + }; +} +``` + +To invoke other generators, import the entry point function and run it against the tree tree. `async/await` can be used to make code with Promises read like procedural code. The generator function may return a callback function that is executed after changes to the file system have been applied. + +In the schema.json file for your generator, the `name` is provided as a default option. The `cli` property is set to `nx` to signal that this is a generator that uses `@nrwl/devkit` and not `@angular-devkit`. + +```json +{ + "cli": "nx", + "id": "test", + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Library name", + "$default": { + "$source": "argv", + "index": 0 + } + } + }, + "required": ["name"] +} +``` + +The `$default` object is used to read arguments from the command-line that are passed to the generator. The first argument passed to this schematic is used as the `name` property. + +## Running a workspace generator + +To run a generator, invoke the `nx workspace-generator` command with the name of the generator. + +```bash +nx workspace-generator my-generator mylib +``` + +## Debugging Workspace generators + +### With Visual Studio Code + +1. Open the Command Palette and choose `Debug: Create JavaScript Debug Terminal`. + This will open a terminal with debugging enabled. +2. Set breakpoints in your code +3. Run `nx workspace-generator my-generator` in the debug terminal. + +![](/shared/vscode-schematics-debug.png) + +## Workspace Generator Utilities + +The `@nrwl/devkit` package provides many utility functions that can be used in schematics to help with modifying files, reading and updating configuration files, and working with an Abstract Syntax Tree (AST). diff --git a/nx-dev/nx-dev/public/documentation/latest/shared/guides/browser-support.md b/nx-dev/nx-dev/public/documentation/latest/shared/guides/browser-support.md index dd735e4e50..8212f635f4 100644 --- a/nx-dev/nx-dev/public/documentation/latest/shared/guides/browser-support.md +++ b/nx-dev/nx-dev/public/documentation/latest/shared/guides/browser-support.md @@ -6,7 +6,7 @@ In general, the more modern your applications browser support is, the smaller th By default, applications generated from official Nx generators ship an aggressively modern browser support config, in the form of a `.browserlistrc` file in the root of the application with the following contents. -``` +```text last 1 Chrome version last 1 Firefox version last 2 Edge major versions @@ -24,7 +24,7 @@ Adding support for IE or any other browser is as easy as changing the `.browserl To add support for IE 11 simply change the final line in the `.browserlistrc` file to include IE: -``` +```text last 1 Chrome version last 1 Firefox version last 2 Edge major versions diff --git a/nx-dev/nx-dev/public/documentation/latest/shared/mental-model.md b/nx-dev/nx-dev/public/documentation/latest/shared/mental-model.md new file mode 100644 index 0000000000..9dc660683e --- /dev/null +++ b/nx-dev/nx-dev/public/documentation/latest/shared/mental-model.md @@ -0,0 +1,238 @@ +# Mental Model + +Nx is a VSCode of build tools, with a powerful core, driven by metadata, and extensible through plugins. Nx works with a few concepts to drive your monorepo efficiently, and effectively. This guide covers the mental model around how Nx works with project graphs, task graphs, affected commands, computation hashing and caching. + +## The project graph + +A project graph is used to reflect the source code in your repository and all the external dependencies that aren’t authored in your repository, such as Webpack, React, Angular, and so forth. + +![project-graph](/shared/mental-model/project-graph.png) + +With Nx, nodes in the project graph are defined in `workspace.json`. You can manually define dependencies between the nodes, but you don’t have to do it very often. Nx analyzes files’ source code, your installed dependencies, TypeScript files, and others figuring out these dependencies for you. Nx also stores the cached project graph, so it only reanalyzes the files you have changed. + +![project-graph-updated](/shared/mental-model/project-graph-updated.png) + +Nx provides an updated graph after each analysis is done. + +## Metadata-driven + +Everything in Nx comes with metadata to enable toolability. The default values, validations, autocompletion work, and more are all defined in a schema, instead of in code. + +The following sample schema shows inputs, prompts, and validations for adding a new application. + +```json +{ + "$schema": "http://json-schema.org/schema", + "cli": "nx", + "$id": "NxNextApp", + "title": "Create an Application for Nx", + "type": "object", + "properties": { + "name": { + "description": "The name of the application.", + "type": "string", + "$default": { + "$source": "argv", + "index": 0 + }, + "x-prompt": "What name would you like to use for the application?", + "pattern": "^[a-zA-Z].*$" + }, + "directory": { + "description": "The directory of the new application.", + "type": "string", + "alias": "d" + }, + "style": { + "description": "The file extension to be used for style files.", + "type": "string", + "default": "css", + "alias": "s", + "x-prompt": { + "message": "Which stylesheet format would you like to use?", + "type": "list", + "items": [ + { "value": "css", "label": "CSS" }, + { + "value": "scss", + "label": "SASS(.scss) [ http://sass-lang.com ]" + }, + { + "value": "styl", + "label": "Stylus(.styl) [ http://stylus-lang.com ]" + }, + { + "value": "less", + "label": "LESS [ http://lesscss.org ]" + } + ] + } + }, + "linter": { + "description": "The tool to use for running lint checks.", + "type": "string", + "enum": ["eslint", "tslint"], + "default": "eslint" + }, + "skipFormat": { + "description": "Skip formatting files", + "type": "boolean", + "default": false + }, + "skipWorkspaceJson": { + "description": "Skip updating workspace.json with default options based on values provided to this app (e.g. babel, style)", + "type": "boolean", + "default": false + }, + "unitTestRunner": { + "type": "string", + "enum": ["jest", "none"], + "description": "Test runner to use for unit tests", + "default": "jest" + }, + "e2eTestRunner": { + "type": "string", + "enum": ["cypress", "none"], + "description": "Test runner to use for end to end (e2e) tests", + "default": "cypress" + }, + "tags": { + "type": "string", + "description": "Add tags to the application (used for linting)", + "alias": "t" + }, + "js": { + "type": "boolean", + "description": "Generate JavaScript files rather than TypeScript files.", + "default": false + }, + "setParserOptionsProject": { + "type": "boolean", + "description": "Whether or not to configure the ESLint \"parserOptions.project\" option. We do not do this by default for lint performance reasons.", + "default": false + } + }, + "required": [] +} +``` + +This metadata is used by Nx itself, by VSCode and WebStorm integrations, by GitHub integration, and by third-party tools. + +![metadata](/shared/mental-model/metadata.png) + +These tools are able to implement richer experiences with Nx using this metadata. + +## The task graph + +Nx uses the project graph to create a task graph. Any time you run anything, Nx creates a task graph from the project graph and then executes the tasks in that graph. + +For instance `nx test lib` creates a task graph with a single node: + +![task-graph](/shared/mental-model/task-graph.png) + +A task is an invocation of a target. If you invoke the same target twice, you create two tasks. + +Nx uses the [project graph](#the-project-graph), but the task graph and project graph aren’t isomorphic, meaning they aren’t directly connected. In the case above, app1 and app2 depend on lib, but running `nx run-many --target=test --projects=app1,app2,lib`, the created task graph will look like this: + +![task-graph-creation](/shared/mental-model/task-graph-creation.png) + +Even though the apps depend on lib, testing `app1` doesn’t depend on the testing lib. This means that the two tasks can run in parallel. + +Let’s look at the test target relying on its dependencies. + +```json +{ + "test": { + "executor": "@nrwl/jest:jest", + "outputs": ["coverage/apps/app1"], + "dependsOn": [{ "target": "test", "projects": "dependencies" }], + "options": { + "jestConfig": "apps/app1/jest.config.js", + "passWithNoTests": true + } + } +} +``` + +With this, running the same test command creates the following task graph: + +![task-graph-run](/shared/mental-model/task-graph-run.png) + +This often makes more sense for builds, where to build app1, you want to build lib first. You can also define similar relationships between targets of the same project, including a test target that depends on the build. + +A task graph can contain different targets, and those can run in parallel. For instance, as Nx is building `app2`, it can be testing `app1` at the same time. Learn more about configuring targets in the [configuration guide](/{{framework}}/core-concepts/configuration) + +![task-graph-execution](/shared/mental-model/task-graph-execution.png) + +Nx also runs the tasks in the task graph in the right order. Nx executing tasks being executed speeds up your overall execution time. + +## Affected commands + +When you run `nx test app1`, you are telling Nx to run the app1:test task plus all the tasks it depends on. + +When you run `nx run-many --target=test --projects=app1,lib`, you are telling Nx to do the same for two tasks app1:test and lib:test. + +When you run `nx run-many --target=test --all`, you are telling Nx to do this for all the projects. + +As your workspace grows, retesting all projects becomes too slow. To address this Nx implements code change analysis to get the min set of projects that need to be retested. How does it work? + +When you run `nx affected --target=test`, Nx looks at the files you changed in your PR, it will look at the nature of change (what exactly did you update in those files), and it uses this to figure the list of projects in the workspace that can be affected by this change. It then runs the `run-many` command with that list. + +For instance, if my PR changes `lib`, and I then run `nx affected --target=test`, Nx figures out that `app1` and `app2` depend on `lib`, so it will invoke `nx run-many --target=test --projects=app1,app2,lib`. + +![affected](/shared/mental-model/affected.png) + +Nx analyzes the nature of the changes. For example, if you change the version of Next.js in the package.json, Nx knows that `app2` cannot be affected by it, so it only retests `app1`. + +## Computation hashing and caching + +Nx runs the tasks in the task graph in the right order. Before running the task, Nx computes its computation hash. As long as the computation hash is the same, the output of running the task is the same. + +How does Nx do it? + +By default, the computation hash for say `nx test app1` includes: + +- All the source files of `app1` and `lib` +- Relevant global configuration +- Versions of externals dependencies +- Runtime values provisioned by the user such as the version of Node +- Command flags + +![computation-hashing](/shared/mental-model/computation-hashing.png) + +This behavior is customizable. For instance, lint checks may only depend on the source code of the project and global configs. Builds can depend on the dts files of the compiled libs instead of their source. + +After Nx computes the hash for a task, it then checks if it ran this exact computation before. First, it checks locally, and then if it is missing, and if a remote cache is configured, it checks remotely. + +If Nx finds the computation, Nx retrieves it and replay it. Nx places the right files in the right folders and prints the terminal output. So from the user’s point of view, the command ran the same, just a lot faster. + +![cache](/shared/mental-model/cache.png) + +If Nx doesn’t find this computation, Nx runs the task, and after it completes, it takes the outputs and the terminal output and stores it locally (and if configured remotely). All of this happens transparently, so you don’t have to worry about it. + +Although conceptually this is fairly straightforward, Nx optimizes this to make this experience good for you. For instance, Nx: + +- Captures stdout and stderr to make sure the replayed output looks the same, including on Windows. +- Minimizes the IO by remembering what files are replayed where. +- Only shows relevant output when processing a large task graph. +- Provides affordances for troubleshooting cache misses. + And many other optimizations. + +As your workspace grows, the task graph looks more like this: + +![cache](/shared/mental-model/task-graph-big.png) + +All of these optimizations are crucial for making Nx usable for any non-trivial workspace. Only the minimum amount of work happens. The rest is either left as is or restored from the cache. + +In summary: + +- Nx is able to analyze your source code to create a Project Graph. +- Nx can use the project graph and information about projects’ targets to create a Task Graph. +- Nx is able to perform code-change analysis to create the smallest task graph for your PR. +- Nx supports computation caching to never execute the same computation twice. This computation cache is pluggable and can be distributed. + +## Learn more: + +- [Migrating from Lerna to Nx: Better Dev Ergonomics + Much Faster Build Times](https://blog.nrwl.io/migrating-from-lerna-to-nx-better-dev-ergonomics-much-faster-build-times-da76ff14ccbb) +- [Using Generators](/{{framework}}/generators/using-schematics) +- [Using Executors](/{{framework}}/executors/using-builders) diff --git a/nx-dev/nx-dev/public/documentation/latest/shared/mental-model/affected.png b/nx-dev/nx-dev/public/documentation/latest/shared/mental-model/affected.png new file mode 100644 index 0000000000..33bc14b6d2 Binary files /dev/null and b/nx-dev/nx-dev/public/documentation/latest/shared/mental-model/affected.png differ diff --git a/nx-dev/nx-dev/public/documentation/latest/shared/mental-model/cache.png b/nx-dev/nx-dev/public/documentation/latest/shared/mental-model/cache.png new file mode 100644 index 0000000000..09a64576e3 Binary files /dev/null and b/nx-dev/nx-dev/public/documentation/latest/shared/mental-model/cache.png differ diff --git a/nx-dev/nx-dev/public/documentation/latest/shared/mental-model/computation-hashing.png b/nx-dev/nx-dev/public/documentation/latest/shared/mental-model/computation-hashing.png new file mode 100644 index 0000000000..53883b6e0e Binary files /dev/null and b/nx-dev/nx-dev/public/documentation/latest/shared/mental-model/computation-hashing.png differ diff --git a/nx-dev/nx-dev/public/documentation/latest/shared/mental-model/metadata.png b/nx-dev/nx-dev/public/documentation/latest/shared/mental-model/metadata.png new file mode 100644 index 0000000000..b199550618 Binary files /dev/null and b/nx-dev/nx-dev/public/documentation/latest/shared/mental-model/metadata.png differ diff --git a/nx-dev/nx-dev/public/documentation/latest/shared/mental-model/project-graph-import.png b/nx-dev/nx-dev/public/documentation/latest/shared/mental-model/project-graph-import.png new file mode 100644 index 0000000000..9de9d73213 Binary files /dev/null and b/nx-dev/nx-dev/public/documentation/latest/shared/mental-model/project-graph-import.png differ diff --git a/nx-dev/nx-dev/public/documentation/latest/shared/mental-model/project-graph-updated.png b/nx-dev/nx-dev/public/documentation/latest/shared/mental-model/project-graph-updated.png new file mode 100644 index 0000000000..e39968c6d7 Binary files /dev/null and b/nx-dev/nx-dev/public/documentation/latest/shared/mental-model/project-graph-updated.png differ diff --git a/nx-dev/nx-dev/public/documentation/latest/shared/mental-model/project-graph.png b/nx-dev/nx-dev/public/documentation/latest/shared/mental-model/project-graph.png new file mode 100644 index 0000000000..8adccf0f81 Binary files /dev/null and b/nx-dev/nx-dev/public/documentation/latest/shared/mental-model/project-graph.png differ diff --git a/nx-dev/nx-dev/public/documentation/latest/shared/mental-model/task-graph-big.png b/nx-dev/nx-dev/public/documentation/latest/shared/mental-model/task-graph-big.png new file mode 100644 index 0000000000..3faf9ca22b Binary files /dev/null and b/nx-dev/nx-dev/public/documentation/latest/shared/mental-model/task-graph-big.png differ diff --git a/nx-dev/nx-dev/public/documentation/latest/shared/mental-model/task-graph-creation.png b/nx-dev/nx-dev/public/documentation/latest/shared/mental-model/task-graph-creation.png new file mode 100644 index 0000000000..47c344a639 Binary files /dev/null and b/nx-dev/nx-dev/public/documentation/latest/shared/mental-model/task-graph-creation.png differ diff --git a/nx-dev/nx-dev/public/documentation/latest/shared/mental-model/task-graph-execution.png b/nx-dev/nx-dev/public/documentation/latest/shared/mental-model/task-graph-execution.png new file mode 100644 index 0000000000..a2b768558e Binary files /dev/null and b/nx-dev/nx-dev/public/documentation/latest/shared/mental-model/task-graph-execution.png differ diff --git a/nx-dev/nx-dev/public/documentation/latest/shared/mental-model/task-graph-run.png b/nx-dev/nx-dev/public/documentation/latest/shared/mental-model/task-graph-run.png new file mode 100644 index 0000000000..bceb6ba649 Binary files /dev/null and b/nx-dev/nx-dev/public/documentation/latest/shared/mental-model/task-graph-run.png differ diff --git a/nx-dev/nx-dev/public/documentation/latest/shared/mental-model/task-graph.png b/nx-dev/nx-dev/public/documentation/latest/shared/mental-model/task-graph.png new file mode 100644 index 0000000000..a25c5bfc6f Binary files /dev/null and b/nx-dev/nx-dev/public/documentation/latest/shared/mental-model/task-graph.png differ diff --git a/nx-dev/nx-dev/public/documentation/latest/shared/migration/adding-to-monorepo.md b/nx-dev/nx-dev/public/documentation/latest/shared/migration/adding-to-monorepo.md index 43fe7cf50d..0f7b131de8 100644 --- a/nx-dev/nx-dev/public/documentation/latest/shared/migration/adding-to-monorepo.md +++ b/nx-dev/nx-dev/public/documentation/latest/shared/migration/adding-to-monorepo.md @@ -36,7 +36,7 @@ affected than other tools because it looks not just at the changed files but als ### Workspace Visualization Run `npx nx dep-graph` to see a visualization of your workspace. `npx nx affected:dep-graph` will show what is affected -by your commit. +by your commit. `npx nx dep-graph --watch` will watch your workspace for changes and update the the visualization. diff --git a/nx-dev/nx-dev/public/documentation/latest/shared/migration/overview.md b/nx-dev/nx-dev/public/documentation/latest/shared/migration/overview.md index 30270ede8c..020188a50f 100644 --- a/nx-dev/nx-dev/public/documentation/latest/shared/migration/overview.md +++ b/nx-dev/nx-dev/public/documentation/latest/shared/migration/overview.md @@ -173,7 +173,7 @@ Your use-case may also be covered by one of our community plugins. Plugin author [Learn more about the `run-commands` builder](/{{framework}}/workspace/run-commands-executor) -[Learn more about caching](/{{framework}}/core-concepts/computation-caching) +[Learn more about caching](/{{framework}}/core-extended/computation-caching) [Learn more about community plugins](/community) diff --git a/nx-dev/nx-dev/public/documentation/latest/shared/tools-workspace-generators.md b/nx-dev/nx-dev/public/documentation/latest/shared/tools-workspace-generators.md deleted file mode 100644 index c0e5ee1ecd..0000000000 --- a/nx-dev/nx-dev/public/documentation/latest/shared/tools-workspace-generators.md +++ /dev/null @@ -1,308 +0,0 @@ -# Workspace Generators - -Workspace generators provide a way to automate many tasks you regularly perform as part of your development workflow. Whether it is scaffolding out components, features, or ensuring libraries are generated and structured in a certain way, generators help you standardize these tasks in a consistent, and predictable manner. Nx provides tooling around creating, and running custom generators from within your workspace. This guide shows you how to create, run, and customize workspace generators within your Nx workspace. - -## Creating a workspace generator - -Use the Nx CLI to generate the initial files needed for your workspace generator. - -```bash -nx generate @nrwl/workspace:workspace-generator my-generator -``` - -After the command is finished, the workspace generator is created under the `tools/generators` folder. - -```treeview -happynrwl/ -├── apps/ -├── libs/ -├── tools/ -│ ├── generators -│ | └── my-generator/ -│ | | ├── index.ts -│ | | └── schema.json -├── nx.json -├── package.json -└── tsconfig.base.json -``` - -The `index.ts` provides an entry point to the generator. The file contains a function that is called to perform manipulations on a tree that represents the file system. -The `schema.json` provides a description of the generator, available options, validation information, and default values. - -The initial generator function creates a library. - -```typescript -import { Tree, formatFiles, installPackagesTask } from '@nrwl/devkit'; -import { libraryGenerator } from '@nrwl/workspace'; - -export default async function (tree: Tree, schema: any) { - await libraryGenerator(tree, { name: schema.name }); - await formatFiles(tree); - return () => { - installPackagesTask(tree); - }; -} -``` - -To invoke other generators, import the entry point function and run it against the tree tree. `async/await` can be used to make code with Promises read like procedural code. The generator function may return a callback function that is executed after changes to the file system have been applied. - -In the schema.json file for your generator, the `name` is provided as a default option. The `cli` property is set to `nx` to signal that this is a generator that uses `@nrwl/devkit` and not `@angular-devkit`. - -```json -{ - "cli": "nx", - "id": "test", - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Library name", - "$default": { - "$source": "argv", - "index": 0 - } - } - }, - "required": ["name"] -} -``` - -The `$default` object is used to read arguments from the command-line that are passed to the generator. The first argument passed to this schematic is used as the `name` property. - -## Running a workspace generator - -To run a generator, invoke the `nx workspace-generator` command with the name of the generator. - -```bash -nx workspace-generator my-generator mylib -``` - -## Running a workspace schematic created with @angular-devkit - -Generators that are created using the `@angular-devkit` are called schematics. Workspace schematics that have been created with the `@angular-devkit` will omit the `"cli": "nx"` property in `schema.json`. Nx will recognize this and correctly run the schematic using the same command as an `@nrwl/devkit` generator. - -```bash -nx workspace-generator my-schematic mylib -``` - -The command is also aliased to the previous `workspace-schematic` command, so this still works: - -```bash -nx workspace-schematic my-schematic mylib -``` - -## Creating files with a generator - -Generators provide an API for managing files within your workspace. You can use generators to do things such as create, update, move, and delete files. Files with static or dynamic content can also be created. - -The generator below shows you how to generate a library, and then scaffold out additional files with the newly created library. - -First, you define a folder to store your static or dynamic templates used to generated files. This is commonly done in a `files` folder. - -```treeview -happynrwl/ -├── apps/ -├── libs/ -├── tools/ -│ ├── generators -│ | └── my-generator/ -│ | | └── files -│ | | └── NOTES.md -│ | | ├── index.ts -│ | | └── schema.json -├── nx.json -├── package.json -└── tsconfig.base.json -``` - -The files can use EJS syntax to substitute variables and logic. See the [EJS Docs](https://ejs.co/) to see more information about how to write these template files. - -Example NOTES.md: - -```md -Hello, my name is <%= name %>! -``` - -Next, update the `index.ts` file for the generator, and generate the new files. - -```typescript -import { - Tree, - formatFiles, - installPackagesTask, - generateFiles, - joinPathFragments, - readProjectConfiguration, -} from '@nrwl/devkit'; -import { libraryGenerator } from '@nrwl/workspace'; - -export default async function (tree: Tree, schema: any) { - await libraryGenerator(tree, { name: schema.name }); - const libraryRoot = readProjectConfiguration(tree, schema.name).root; - generateFiles( - tree, // the virtual file system - joinPathFragments(__dirname, './files'), // path to the file templates - libraryRoot, // destination path of the files - schema // config object to replace variable in file templates - ); - await formatFiles(tree); - return () => { - installPackagesTask(tree); - }; -} -``` - -The exported function first creates the library, then creates the additional files in the new library's folder. - -Next, run the generator: - -> Use the `-d` or `--dry-run` flag to see your changes without applying them. - -```bash -nx workspace-generator my-generator mylib -``` - -The following information will be displayed. - -```bash -CREATE libs/mylib/README.md -CREATE libs/mylib/.babelrc -CREATE libs/mylib/src/index.ts -CREATE libs/mylib/src/lib/mylib.spec.ts -CREATE libs/mylib/src/lib/mylib.ts -CREATE libs/mylib/tsconfig.json -CREATE libs/mylib/tsconfig.lib.json -UPDATE tsconfig.base.json -UPDATE workspace.json -UPDATE nx.json -CREATE libs/mylib/.eslintrc.json -CREATE libs/mylib/jest.config.js -CREATE libs/mylib/tsconfig.spec.json -UPDATE jest.config.js -CREATE libs/mylib/NOTES.md -``` - -`libs/mylib/NOTES.md` will contain the content with substituted variables: - -```md -Hello, my name is mylib! -``` - -## Customizing generator options - -### Adding a TypeScript schema - -To create a TypeScript schema to use in your generator function, define a TypeScript file next to your schema.json named `schema.ts`. Inside the `schema.ts`, define an interface to match the properties in your schema.json file, and whether they are required. - -```typescript -export interface SchematicOptions { - name: string; - type?: string; -} -``` - -Import the TypeScript schema into your generator file and replace the any in your generator function with the interface. - -```typescript -import { Tree, formatFiles, installPackagesTask } from '@nrwl/devkit'; -import { libraryGenerator } from '@nrwl/workspace'; - -export default async function (tree: Tree, schema: SchematicOptions) { - await libraryGenerator(tree, { name: `${schema.name}-${schema.type || ''}` }); - await formatFiles(tree); - return () => { - installPackagesTask(tree); - }; -} -``` - -### Adding static options - -Static options for a generator don't prompt the user for input. To add a static option, define a key in the schema.json file with the option name, and define an object with its type, description, and optional default value. - -```json -{ - "$schema": "http://json-schema.org/schema", - "id": "my-generator", - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Library name", - "$default": { - "$source": "argv", - "index": 0 - } - }, - "type": { - "type": "string", - "description": "Provide the library type, such as 'data-access' or 'state'" - } - }, - "required": ["name"] -} -``` - -If you run the generator without providing a value for the type, it is not included in the generated name of the library. - -### Adding dynamic prompts - -Dynamic options can prompt the user to select from a list of options. To define a prompt, add an `x-prompt` property to the option object, set the type to list, and define an items array for the choices. - -```json -{ - "$schema": "http://json-schema.org/schema", - "id": "my-generator", - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Library name", - "$default": { - "$source": "argv", - "index": 0 - } - }, - "type": { - "type": "string", - "description": "Provide the library type", - "x-prompt": { - "message": "Which type of library would you like to generate?", - "type": "list", - "items": [ - { - "value": "data-access", - "label": "Data Access" - }, - { - "value": "feature", - "label": "Feature" - }, - { - "value": "state", - "label": "State Management" - } - ] - } - } - }, - "required": ["name"] -} -``` - -Running the generator without providing a value for the type will prompt the user to make a selection. - -## Debugging Workspace generators - -### With Visual Studio Code - -1. Open the Command Palette and choose `Debug: Create JavaScript Debug Terminal`. - This will open a terminal with debugging enabled. -2. Set breakpoints in your code -3. Run `nx workspace-generator my-generator` in the debug terminal. - -![](/shared/vscode-schematics-debug.png) - -## Workspace Generator Utilities - -The `@nrwl/devkit` package provides many utility functions that can be used in schematics to help with modifying files, reading and updating configuration files, and working with an Abstract Syntax Tree (AST). diff --git a/nx-dev/nx-dev/public/documentation/latest/shared/update.md b/nx-dev/nx-dev/public/documentation/latest/shared/update.md index 615c8eae23..16acac33ea 100644 --- a/nx-dev/nx-dev/public/documentation/latest/shared/update.md +++ b/nx-dev/nx-dev/public/documentation/latest/shared/update.md @@ -1,19 +1,19 @@ # Updating Nx -Nx provides the `migrate` command which help you stay up to date with the latest version of Nx. +The Nx CLI provides the `migrate` command to help you stay up to date with the latest version of Nx. -Not only `nx migrate` updates the version of Nx, but it also updates the versions of dependencies which we install such as jest and cypress. You can also use the `migrate` command to update any Nx plugin. +Not only does `nx migrate` update you to the latest version of Nx, but it also updates the versions of dependencies that we support and test such as Jest and Cypress. You can also use the `migrate` command to update any Nx plugin. -## How to Migrate +## Migrating to the latest Nx version Migration happens in two steps: -- Updating `package.json` (and `node_modules`) -- Updating the source code of the repo to match the new versions of packages in `package.json` +- The installed dependencies are updated including the `package.json` (and `node_modules`). +- The source code in the repo is updated to match the new versions of packages in `package.json`. -### Step 1: Updating package.json and generating migrations.json +### Step 1: Updating dependencies and generating migrations -Run the following: +First, run the `migrate` command: ```bash nx migrate latest # same as nx migrate @nrwl/workspace@latest @@ -25,75 +25,81 @@ You can also specify the name of the package and the version: nx migrate @nrwl/workspace@version # you can also specify version ``` -This will fetch the specified version of `@nrwl/workspace`, analyze the dependencies and fetch all the dependent packages. The process will keep going until the whole tree of dependencies is resolved. This will result in: +This fetches the specified version of the `@nrwl/workspace` package, analyzes the dependencies and fetches all the dependent packages. The process keeps going until all the dependencies are resolved. This results in: -- `package.json` being updated -- `migrations.json` being generated +- The `package.json` being updated +- A `migrations.json` being generated if there are pending migrations. At this point, no packages have been installed, and no other files have been touched. -Now, you can inspect `package.json` to see if the changes make sense. Sometimes the migration can update some package to the version that is either not allowed or conflicts with with another package. Feel free to manually apply the desired adjustments. +Now, you can inspect `package.json` to see if the changes make sense. Sometimes the migration can update some package to the version that is either not allowed or conflicts with another package. Feel free to manually apply the desired adjustments. ### Step 2: Install the packages -After you are satisfied, make sure to actuall install the packages by running `npm install`, `yarn`, or `pnpm install`. +After inspecting the `package.json`, make sure to install the updated package versions by running `npm install`, `yarn`, or `pnpm install`. ### Step 3: Running migrations -Next, we need to update the repo to match the updated `package.json` and `node_modules`. Every Nx plugin comes with a set of migrations that describe how to update the workspace to make it work with the new version of the plugin. During Step 1 Nx looked at all of the packages being updated and collected their migrations into `migrations.json`. It's important to note that because Nx knows the from and to versions of every package, the `migrations.json` file only contains the relevant migrations. +Next, update the repo to match the updated `package.json` and `node_modules`. Every Nx plugin comes with a set of migrations that describe how to update the workspace to make it work with the new version of the plugin. During step one, Nx looked at all of the packages being updated and collected their migrations into `migrations.json`. It's important to note that because Nx knows the from and to versions of every package, the `migrations.json` file only contains the relevant migrations. -Each migration in `migrations.json` updates the source code in the repository. To run all the migrations in order, invoke: +Each migration in `migrations.json` updates the source code in the repository. To run all the migrations in order, run the following command: + +```bash +nx migrate --run-migrations +``` + +To specify a custom migrations file, pass it to the `--run-migrations` option: ```bash nx migrate --run-migrations=migrations.json ``` -For small projects, running all the migrations at once often succeeds without any issues. For large projects, more flexibility is sometimes needed: +For small projects, running all the migrations at once often succeeds without any issues. For large projects, more flexibility is needed: - You may have to skip a migration. - You may want to run one migration at a time to address minor issues. - You may want to reorder migrations. - You may want to run the same migration multiple time if the process takes a long time and you had to rebase. -Since you can run `nx migrate --run-migrations=migrations.json` as many times as you want, you can achieve all of that by commenting out and reordering items in `migrations.json`. The migrate process can take a long time, sometimes a day, so it can be useful to commit the migrations file with the partially-updated repo. +Because you can run `nx migrate --run-migrations` as many times as you want, you can achieve all of that by commenting out and reordering items in `migrations.json`. The migration process can take a long time, depending on the number of migrations, so it is useful to commit the migrations file with the partially-updated repo. ### Step 4: Cleaning up -After you run all the migrations, you can remove `migration.json` and commit the changes. +After you run all the migrations, you can remove `migrations.json` and commit the changes. -## Advanced Capabilities & Recommendations +## Advanced capabilities & recommendations -### One Major Version at a Time, Small Steps +### One major version at a time, small steps -Migrating Jest, Cypress, ESLint, React, Angular, Next etc... is a difficult task. All the tools change at different rates, they can conflict with each other etc.. In addition, every workspace is different. Even though our goal is to let you update any version of Nx to any other version in a single go, sometimes it doesn't work. The following process is better for large workspaces. +Migrating Jest, Cypress, ESLint, React, Angular, Next, and more is a difficult task. All the tools change at different rates, they can conflict with each other. In addition, every workspace is different. Even though our goal is for you to update any version of Nx to a newer version of Nx in a single go, sometimes it doesn't work. The following process is better for large workspaces. Say you want to migrate from Nx 10.1.0 to Nx 11.0.1. The following steps are more likely to work comparing to `nx migrate 11.0.1`. -- Run `nx migrate 10.4.5` to update the latest version in the 10x branch. -- Run `npm install` -- Run `nx migrate --run-migrations=migrations.json` -- Next, run `nx migrate 11.0.1` -- Run `npm install` -- Run `nx migrate --run-migrations=migrations.json` +- Run `nx migrate 10.4.5` to update the latest version in the 10.x branch. +- Run `npm install`. +- Run `nx migrate --run-migrations`. +- Next, run `nx migrate 11.0.1`. +- Run `npm install`. +- Run `nx migrate --run-migrations`. ### Overriding versions -Sometimes, you may want to use a different version of a package than what Nx recommends. You can do it as follows: +Sometimes, you may want to use a different version of a package than what Nx recommends. To do that, specify the package and version: ```bash nx migrate @nrwl/workspace --to="jest@22.0.0,cypress:3.4.0" ``` -By default, Nx uses currently installed packages to calculate what migrations need to run. You can override them like this: +By default, Nx uses currently installed packages to calculate what migrations need to run. To override them, override the version: ```bash -nx migrate @nrwl/workspace --to="@nrwl/jest@8.0.0" +nx migrate @nrwl/workspace --to="@nrwl/jest@12.0.0" ``` ### Reverting a failed update -Updates are best done on a clean git history so that it can be easily reversed if something fails. -We try our best to make sure migrations do not fail but if one does, **please report it** on [Github](https://www.github.com/nrwl/nx/issues/new/). +Updates are best done on a clean git history so that it can be easily reversed if something fails. We try our best to make sure migrations do not fail but if one does, **please report it** on [GitHub](https://www.github.com/nrwl/nx/issues/new/). + If an update fails for any reason, you can revert it as you do any other set of changes: ```bash diff --git a/nx-dev/nx-dev/public/documentation/latest/shared/using-generators.md b/nx-dev/nx-dev/public/documentation/latest/shared/using-generators.md deleted file mode 100644 index 2703ea613f..0000000000 --- a/nx-dev/nx-dev/public/documentation/latest/shared/using-generators.md +++ /dev/null @@ -1,301 +0,0 @@ -# Using Generators - -## Overview - -Generators provide a way to automate many tasks you regularly perform as part of your development workflow. Whether it is scaffolding out components, features, ensuring libraries are generated and structured in a certain way, or updating your configuration files, generators help you standardize these tasks in a consistent, and predictable manner. - -Generators can be written using `@nrwl/devkit` or `@angular-devkit`. Generators written with the `@angular-devkit` are called schematics. To read more about the concepts of `@angular-devkit` schematics, and building an example schematic, see the [Schematics Authoring Guide](https://angular.io/guide/schematics-authoring). - -The [Workspace Generators](/{{framework}}/generators/workspace-generators) guide shows you how to create, run, and customize workspace generators within your Nx workspace. - -## Types of generators - -There are three main types of generators: - -1. **Plugin Generators** are available when an Nx plugin has been installed in your workspace. -2. **Workspace Generators** are generators that you can create for your own workspace. [Workspace generators](/{{framework}}/generators/workspace-generators) allow you to codify the processes that are unique to your own organization. -3. **Update Generators** are invoked by Nx plugins when you [update Nx](/{{framework}}/core-concepts/updating-nx) to keep your config files in sync with the latest versions of third party tools. - -## Invoking plugin generators - -Generators allow you to create or modify your codebase in a simple and repeatable way. Generators are invoked using the [`nx generate`](/{{framework}}/cli/generate) command. - -```bash -nx generate [plugin]:[generator-name] [options] -nx generate @nrwl/react:component mycmp --project=myapp -``` - -It is important to have a clean git working directory before invoking a generator so that you can easily revert changes and re-invoke the generator with different inputs. - -### Simplest Generator - -```json -{ - "cli": "nx", - "id": "CustomGenerator", - "description": "Create a custom generator", - "type": "object", - "properties": {}, - "additionalProperties": true -} -``` - -```typescript -export default async function (tree, opts) { - console.log('options', opts); -} -``` - -### Defining a generator schema - -A generator's schema describes the inputs--what you can pass into it. The schema is used to validate inputs, to parse args (e.g., covert strings into numbers), to set defaults, and to power the VSCode plugin. It is written with [JSON Schema](https://json-schema.org/). - -#### Examples - -```json -{ - "cli": "nx", - "id": "CustomGenerator", - "description": "Create a custom generator", - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Generator name", - "x-prompt": "What name would you like to use for the workspace generator?" - }, - "skipFormat": { - "description": "Skip formatting files", - "type": "boolean", - "alias": "sf", - "default": false - } - }, - "required": ["name"] -} -``` - -The schema above defines two fields: `name` and `skipFormat`. The `name` field is a string, `skipFormat` is a boolean. The `x-prompt` property tells Nx to ask for the `name` value if one isn't given. The `skipFormat` field has the default value set to `false`. The schema language is rich and lets you use lists, enums, references, etc.. A few more examples: - -```json -{ - "cli": "nx", - "id": "CustomGenerator", - "description": "Create a custom generator", - "type": "object", - "properties": { - "stringOrBoolean": { - "oneOf": [ - { - "type": "string", - "default": "mystring!" - }, - { - "type": "boolean" - } - ] - }, - "innerObject": { - "type": "object", - "properties": { - "key": { - "type": "boolean" - } - } - }, - "array": { - "type": "array", - "items": { - "type": "number" - } - }, - "complexXPrompt": { - "type": "string", - "default": "css", - "x-prompt": { - "message": "Which stylesheet format would you like to use?", - "type": "list", - "items": [ - { - "value": "css", - "label": "CSS" - }, - { - "value": "scss", - "label": "SASS(.scss)" - }, - { - "value": "styl", - "label": "Stylus(.styl)" - }, - { - "value": "none", - "label": "None" - } - ] - } - }, - "positionalArg": { - "type": "string", - "$default": { - "$source": "argv", - "index": 0 - } - }, - "currentProject": { - "type": "string", - "$default": { - "$source": "projectName" - } - } - } -} -``` - -Sometimes, you may not know the schema or may not care, in this case, you can set the following: - -```json -{ - "cli": "nx", - "id": "CustomGenerator", - "description": "Create a custom generator", - "type": "object", - "properties": { - "name": { - "type": "string" - } - }, - "required": ["name"], - "additionalProperties": true -} -``` - -Because `"additionalProperties"` is `true`, the generator above will accept any extra parameters you pass. They, of course, won't be validated or transformed, but sometimes that's good enough. - -If you want to learn more about the schema language, check out the core plugins at [https://github.com/nrwl/nx](https://github.com/nrwl/nx) for more examples. - -### Implementing a generator - -The implementation is a function that takes two arguments: - -- `tree`: an implementation of the file system - - It allows you to read/write files, list children, etc. - - It's recommended to use the tree instead of directly interacting with the file system. - - This enables the `--dry-run` mode so you can try different sets of options before actually making changes to the files. -- `options` - - This is a combination of the options from `workspace.json`, command-line overrides, and schema defaults. - - All the options are validated and transformed in accordance with the schema. - - You normally don't have to validate anything in the implementation function because it won't be invoked unless the schema validation passes. - -The implementation can return a callback which is invoked _after changes have been made to the file system_. - -#### Examples - -```typescript -import { - Tree, - generateFiles, - formatFiles, - installPackagesTask, -} from '@nrwl/devkit'; - -interface Schema { - name: string; - skipFormat: boolean; -} - -export default async function (tree: Tree, options: Schema) { - generateFiles( - tree, - path.join(__dirname, 'files'), - path.join('tools/generators', options.name), - options - ); - - if (!options.skipFormat) { - await formatFiles(tree); - } - - return () => { - installPackagesTask(tree); - }; -} -``` - -The generator is an async function. You could create new projects and generate new files, but you could also update existing files and refactor things. It's recommended to limit all the side-effects to interacting with the tree and printing to the console. Sometimes generators perform other side-effects such as installing npm packages. Perform them in the function returned from the generator. Nx won't run the returned function in the dry run mode. - -### Devkit helper functions - -Nx provides helpers several functions for writing generators: - -- `readProjectConfiguration` -- Read the project configuration stored in workspace.json and nx.json. -- `addProjectConfiguration` -- Add the project configuration stored in workspace.json and nx.json. -- `removeProjectConfiguration` -- Remove the project configuration stored in workspace.json and nx.json. -- `updateProjectConfiguration` -- Update the project configuration stored in workspace.json and nx.json. -- `readWorkspaceConfiguration` -- Read general workspace configuration such as the default project or cli settings. -- `updateWorkspaceConfiguration` -- Update general workspace configuration such as the default project or cli settings. -- `getProjects` -- Returns the list of projects. -- `generateFiles` -- Generate a folder of files based on provided templates. -- `formatFiles` -- Format all the created or updated files using Prettier. -- `readJson` -- Read a json file. -- `writeJson` -- Write a json file. -- `updateJson` -- Update a json file. -- `addDependenciesToPackageJson` -- Add dependencies and dev dependencies to package.json -- `installPackagesTask` -- Runs `npm install`/`yarn install`/`pnpm install` depending on what is used by the workspaces. -- `names` -- Util function to generate different strings based off the provided name. -- `getWorkspaceLayout` -- Tells where new libs and apps should be generated. -- `offestFromRoot` -- Calculates an offset from the root of the workspace, which is useful for constructing relative URLs. -- `stripIndents` -- Strips indents from a multiline string. -- `normalizePath` -- Coverts an os specific path to a unix style path. -- `joinPathFragments` -- Normalize fragments and joins them with a /. -- `toJS` -- Coverts a TypeScript file to JavaScript. Useful for generators that support both. -- `visitNotIgnoredFiles` -- Utility to act on all files in a tree that are not ignored by git. -- `applyChangesToString`-- Applies a list of changes to a string's original value. This is useful when working with ASTs - -Each of those have detailed API docs. Check the [API Docs](/{{framework}}/nx-devkit/index#functions) for more information. - -It's also important to stress that those are just utility functions. You can use them but you don't have to. You can instead write your own functions that take the tree and do whatever you want to do with it. - -### Composing generators - -Generators are just async functions so they can be easily composed together. For instance, to write a generator that generates two React libraries: - -```typescript -import { - Tree, - generateFiles, - formatFiles, - installPackagesTask, -} from '@nrwl/devkit'; -import { libraryGenerator } from '@nrwl/react'; - -export default async function (tree: Tree, options: Schema) { - const libSideEffects1 = libraryGenerator(tree, { name: options.name1 }); - const libSideEffects2 = libraryGenerator(tree, { name: options.name2 }); - await performOperationsOnTheTree(tree); - return () => { - libSideEffects1(); - libSideEffects2(); - }; -} -``` - -### Testing generators - -The Nx Devkit provides the `createTreeWithEmptyWorkspace` utility to create a tree with an empty workspace that can be used in tests. Other than that, the tests simply invoke the generator and check the changes are made in the tree. - -```typescript -import { readProjectConfiguration } from '@nrwl/devkit'; -import { createTreeWithEmptyWorkspace } from '@nrwl/devkit/testing'; -import createLib from './lib'; - -describe('lib', () => { - it('should create a lib', async () => { - const tree = createTreeWithEmptyWorkspace(); - // update tree before invoking the generator - await createLib(tree, { name: 'lib' }); - - expect(readProjectConfiguration(tree, 'lib')).toBeDefined(); - }); -}); -``` diff --git a/nx-dev/nx-dev/public/documentation/latest/shared/workspace/creating-libraries.md b/nx-dev/nx-dev/public/documentation/latest/shared/workspace/creating-libraries.md index aa5cf178dc..d21fe6541c 100644 --- a/nx-dev/nx-dev/public/documentation/latest/shared/workspace/creating-libraries.md +++ b/nx-dev/nx-dev/public/documentation/latest/shared/workspace/creating-libraries.md @@ -12,7 +12,7 @@ The more granular your libraries are, the more effective `nx affected` and Nx's ### 2. Visualizing Architecture -The `nx dep-graph` command generates a graph of how apps and libraries depend on each other. If most of your code lives in a few giant libraries, this visualization doesn't provide much value. +The `nx dep-graph` command generates a graph of how apps and libraries depend on each other. If most of your code lives in a few giant libraries, this visualization doesn't provide much value. Adding the `--watch` flag to the command will update the visualization in-browser as you make changes. ### 3. Enforcing Constraints diff --git a/nx-dev/nx-dev/public/documentation/versions.json b/nx-dev/nx-dev/public/documentation/versions.json index b8885ac517..2e86143399 100644 --- a/nx-dev/nx-dev/public/documentation/versions.json +++ b/nx-dev/nx-dev/public/documentation/versions.json @@ -1,8 +1,8 @@ [ { - "name": "Latest (v12.4.0)", + "name": "Latest (v12.5.0)", "id": "latest", - "release": "12.4.0", + "release": "12.5.0", "path": "latest", "default": true },