miel.truyen/nx
1
0
Fork 0
Code Issues Pull Requests Actions 5 Packages Projects Releases Wiki Activity

docs(core): inferred targets (#21167)

Browse Source 
Co-authored-by: Katerina Skroumpelou <mandarini@users.noreply.github.com>
Co-authored-by: Colum Ferry <cferry09@gmail.com>
Co-authored-by: Emily Xiong <xiongemi@gmail.com>
Co-authored-by: Nicholas Cunningham <ndcunningham@gmail.com>
Co-authored-by: Jason Jean <jasonjean1993@gmail.com>
Co-authored-by: Victor Savkin <mail@vsavkin.com>
Co-authored-by: Jack Hsu <jack.hsu@gmail.com>
This commit is contained in:
Isaac Mann 2024-02-03 00:14:05 -05:00 committed by GitHub
parent 26a815c7df
commit 61436a64ef
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
221 changed files with 8276 additions and 9127 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/changelog/15_0_0.md
View File

@ -11,7 +11,7 @@ width="100%" /%}
## Breaking Changes
Use [the `nx migrate` command](/core-features/automate-updating-dependencies) to automatically account for these breaking changes.
Use [the `nx migrate` command](/features/automate-updating-dependencies) to automatically account for these breaking changes.
{% cards cols="1" smCols="2" mdCols="3" %}

2
docs/changelog/16_0_0.md
View File

@ -30,7 +30,7 @@ Here are some of our feature highlights:
## Breaking Changes
Use [the `nx migrate` command](/core-features/automate-updating-dependencies) to automatically account for these breaking changes.
Use [the `nx migrate` command](/features/automate-updating-dependencies) to automatically account for these breaking changes.
{% cards cols="2" %}
{% card title="Removed @nrwl/cypress/plugins/preprocessor" type="external" url="https://github.com/nrwl/nx/pull/16170" /%}

2
docs/changelog/17_0_0.md
View File

@ -19,7 +19,7 @@ title="Nx 17.0 Has Landed!!!"
## Breaking Changes
Use [the `nx migrate` command](/core-features/automate-updating-dependencies) to automatically account for these breaking changes.
Use [the `nx migrate` command](/features/automate-updating-dependencies) to automatically account for these breaking changes.
{% cards cols="2" %}
{% card title="Rename @nx/linter to @nx/eslint" type="document" url="/recipes/other/rescope#rename" /%}

205
docs/generated/manifests/ci.json
View File

@ -130,17 +130,6 @@
"mediaImage": "",
"file": "",
"itemList": [
{
"id": "remote-cache",
"name": "Use Remote Caching",
"description": "Learn how to enable remote caching s.t. you don't just benefit locally from it but also in CI.",
"mediaImage": "",
"file": "shared/core-features/remote-cache",
"itemList": [],
"isExternal": false,
"path": "/ci/features/remote-cache",
"tags": ["remote-cache"]
},
{
"id": "affected",
"name": "Run Only Tasks Affected by a PR",
@ -153,15 +142,59 @@
"tags": ["run-tasks"]
},
{
"id": "distribute-task-execution",
"name": "Distribute Task Execution",
"description": "Learn how to efficiently distribute tasks across machines to take full advantage of parallelization. Nx Cloud has a built-in DTE mechanism which makes this a trivial task.",
"id": "remote-cache",
"name": "Use Remote Caching (Nx Replay)",
"description": "Learn how to enable remote caching s.t. you don't just benefit locally from it but also in CI.",
"mediaImage": "",
"file": "shared/core-features/distribute-task-execution",
"file": "shared/features/remote-cache",
"itemList": [],
"isExternal": false,
"path": "/ci/features/remote-cache",
"tags": ["remote-cache"]
},
{
"id": "distribute-task-execution",
"name": "Distribute Task Execution (Nx Agents)",
"description": "Learn how to efficiently distribute tasks across machines to take full advantage of parallelization. Nx Agents make this a trivial task.",
"mediaImage": "",
"file": "shared/features/distribute-task-execution",
"itemList": [],
"isExternal": false,
"path": "/ci/features/distribute-task-execution",
"tags": ["distribute-task-execution"]
"tags": []
},
{
"id": "dynamic-agents",
"name": "Dynamically Allocate Agents",
"description": "",
"mediaImage": "",
"file": "nx-cloud/features/dynamic-agents",
"itemList": [],
"isExternal": false,
"path": "/ci/features/dynamic-agents",
"tags": []
},
{
"id": "split-e2e-tasks",
"name": "Automatically Split E2E Tasks",
"description": "",
"mediaImage": "",
"file": "nx-cloud/features/split-e2e-tasks",
"itemList": [],
"isExternal": false,
"path": "/ci/features/split-e2e-tasks",
"tags": []
},
{
"id": "flaky-tasks",
"name": "Identify and Re-run Flaky Tasks",
"description": "",
"mediaImage": "",
"file": "nx-cloud/features/flaky-tasks",
"itemList": [],
"isExternal": false,
"path": "/ci/features/flaky-tasks",
"tags": []
},
{
"id": "on-premise",
@ -173,34 +206,12 @@
"isExternal": false,
"path": "/ci/features/on-premise",
"tags": ["on-premise"]
},
{
"id": "nx-agents",
"name": "Nx Agents",
"description": "",
"mediaImage": "",
"file": "nx-cloud/intro/nx-agents",
"itemList": [],
"isExternal": false,
"path": "/ci/features/nx-agents",
"tags": []
}
],
"isExternal": false,
"path": "/ci/features",
"tags": []
},
"/ci/features/remote-cache": {
"id": "remote-cache",
"name": "Use Remote Caching",
"description": "Learn how to enable remote caching s.t. you don't just benefit locally from it but also in CI.",
"mediaImage": "",
"file": "shared/core-features/remote-cache",
"itemList": [],
"isExternal": false,
"path": "/ci/features/remote-cache",
"tags": ["remote-cache"]
},
"/ci/features/affected": {
"id": "affected",
"name": "Run Only Tasks Affected by a PR",
@ -212,16 +223,60 @@
"path": "/ci/features/affected",
"tags": ["run-tasks"]
},
"/ci/features/remote-cache": {
"id": "remote-cache",
"name": "Use Remote Caching (Nx Replay)",
"description": "Learn how to enable remote caching s.t. you don't just benefit locally from it but also in CI.",
"mediaImage": "",
"file": "shared/features/remote-cache",
"itemList": [],
"isExternal": false,
"path": "/ci/features/remote-cache",
"tags": ["remote-cache"]
},
"/ci/features/distribute-task-execution": {
"id": "distribute-task-execution",
"name": "Distribute Task Execution",
"description": "Learn how to efficiently distribute tasks across machines to take full advantage of parallelization. Nx Cloud has a built-in DTE mechanism which makes this a trivial task.",
"name": "Distribute Task Execution (Nx Agents)",
"description": "Learn how to efficiently distribute tasks across machines to take full advantage of parallelization. Nx Agents make this a trivial task.",
"mediaImage": "",
"file": "shared/core-features/distribute-task-execution",
"file": "shared/features/distribute-task-execution",
"itemList": [],
"isExternal": false,
"path": "/ci/features/distribute-task-execution",
"tags": ["distribute-task-execution"]
"tags": []
},
"/ci/features/dynamic-agents": {
"id": "dynamic-agents",
"name": "Dynamically Allocate Agents",
"description": "",
"mediaImage": "",
"file": "nx-cloud/features/dynamic-agents",
"itemList": [],
"isExternal": false,
"path": "/ci/features/dynamic-agents",
"tags": []
},
"/ci/features/split-e2e-tasks": {
"id": "split-e2e-tasks",
"name": "Automatically Split E2E Tasks",
"description": "",
"mediaImage": "",
"file": "nx-cloud/features/split-e2e-tasks",
"itemList": [],
"isExternal": false,
"path": "/ci/features/split-e2e-tasks",
"tags": []
},
"/ci/features/flaky-tasks": {
"id": "flaky-tasks",
"name": "Identify and Re-run Flaky Tasks",
"description": "",
"mediaImage": "",
"file": "nx-cloud/features/flaky-tasks",
"itemList": [],
"isExternal": false,
"path": "/ci/features/flaky-tasks",
"tags": []
},
"/ci/features/on-premise": {
"id": "on-premise",
@ -234,17 +289,6 @@
"path": "/ci/features/on-premise",
"tags": ["on-premise"]
},
"/ci/features/nx-agents": {
"id": "nx-agents",
"name": "Nx Agents",
"description": "",
"mediaImage": "",
"file": "nx-cloud/intro/nx-agents",
"itemList": [],
"isExternal": false,
"path": "/ci/features/nx-agents",
"tags": []
},
"/ci/concepts": {
"id": "concepts",
"name": "Concepts",
@ -359,6 +403,17 @@
"mediaImage": "",
"file": "",
"itemList": [
{
"id": "connect-to-cloud",
"name": "Connect Nx Cloud",
"description": "",
"mediaImage": "",
"file": "nx-cloud/recipes/connect-to-cloud",
"itemList": [],
"isExternal": false,
"path": "/ci/recipes/set-up/connect-to-cloud",
"tags": []
},
{
"id": "monorepo-ci-azure",
"name": "Setting up Azure Pipelines",
@ -666,6 +721,17 @@
"mediaImage": "",
"file": "",
"itemList": [
{
"id": "connect-to-cloud",
"name": "Connect Nx Cloud",
"description": "",
"mediaImage": "",
"file": "nx-cloud/recipes/connect-to-cloud",
"itemList": [],
"isExternal": false,
"path": "/ci/recipes/set-up/connect-to-cloud",
"tags": []
},
{
"id": "monorepo-ci-azure",
"name": "Setting up Azure Pipelines",
@ -737,6 +803,17 @@
"path": "/ci/recipes/set-up",
"tags": ["distribute-task-execution"]
},
"/ci/recipes/set-up/connect-to-cloud": {
"id": "connect-to-cloud",
"name": "Connect Nx Cloud",
"description": "",
"mediaImage": "",
"file": "nx-cloud/recipes/connect-to-cloud",
"itemList": [],
"isExternal": false,
"path": "/ci/recipes/set-up/connect-to-cloud",
"tags": []
},
"/ci/recipes/set-up/monorepo-ci-azure": {
"id": "monorepo-ci-azure",
"name": "Setting up Azure Pipelines",
@ -1232,6 +1309,17 @@
"path": "/ci/reference/nx-cloud-cli",
"tags": []
},
{
"id": "launch-templates",
"name": "Launch Templates",
"description": "",
"mediaImage": "",
"file": "nx-cloud/reference/launch-templates",
"itemList": [],
"isExternal": false,
"path": "/ci/reference/launch-templates",
"tags": []
},
{
"id": "env-vars",
"name": "Environment Variables",
@ -1292,6 +1380,17 @@
"path": "/ci/reference/nx-cloud-cli",
"tags": []
},
"/ci/reference/launch-templates": {
"id": "launch-templates",
"name": "Launch Templates",
"description": "",
"mediaImage": "",
"file": "nx-cloud/reference/launch-templates",
"itemList": [],
"isExternal": false,
"path": "/ci/reference/launch-templates",
"tags": []
},
"/ci/reference/env-vars": {
"id": "env-vars",
"name": "Environment Variables",

28
docs/generated/manifests/extending-nx.json
View File

@ -105,7 +105,7 @@
"itemList": [],
"isExternal": false,
"path": "/extending-nx/recipes/local-executors",
"tags": ["use-task-executors"]
"tags": []
},
{
"id": "compose-executors",
@ -116,7 +116,7 @@
"itemList": [],
"isExternal": false,
"path": "/extending-nx/recipes/compose-executors",
"tags": ["use-task-executors"]
"tags": []
},
{
"id": "local-generators",
@ -127,7 +127,7 @@
"itemList": [],
"isExternal": false,
"path": "/extending-nx/recipes/local-generators",
"tags": ["use-code-generators"]
"tags": ["generate-code"]
},
{
"id": "composing-generators",
@ -138,7 +138,7 @@
"itemList": [],
"isExternal": false,
"path": "/extending-nx/recipes/composing-generators",
"tags": ["use-code-generators"]
"tags": ["generate-code"]
},
{
"id": "generator-options",
@ -149,7 +149,7 @@
"itemList": [],
"isExternal": false,
"path": "/extending-nx/recipes/generator-options",
"tags": ["use-code-generators"]
"tags": ["generate-code"]
},
{
"id": "creating-files",
@ -160,7 +160,7 @@
"itemList": [],
"isExternal": false,
"path": "/extending-nx/recipes/creating-files",
"tags": ["use-code-generators"]
"tags": ["generate-code"]
},
{
"id": "modifying-files",
@ -171,7 +171,7 @@
"itemList": [],
"isExternal": false,
"path": "/extending-nx/recipes/modifying-files",
"tags": ["use-code-generators"]
"tags": ["generate-code"]
},
{
"id": "migration-generators",
@ -231,7 +231,7 @@
"itemList": [],
"isExternal": false,
"path": "/extending-nx/recipes/local-executors",
"tags": ["use-task-executors"]
"tags": []
},
"/extending-nx/recipes/compose-executors": {
"id": "compose-executors",
@ -242,7 +242,7 @@
"itemList": [],
"isExternal": false,
"path": "/extending-nx/recipes/compose-executors",
"tags": ["use-task-executors"]
"tags": []
},
"/extending-nx/recipes/local-generators": {
"id": "local-generators",
@ -253,7 +253,7 @@
"itemList": [],
"isExternal": false,
"path": "/extending-nx/recipes/local-generators",
"tags": ["use-code-generators"]
"tags": ["generate-code"]
},
"/extending-nx/recipes/composing-generators": {
"id": "composing-generators",
@ -264,7 +264,7 @@
"itemList": [],
"isExternal": false,
"path": "/extending-nx/recipes/composing-generators",
"tags": ["use-code-generators"]
"tags": ["generate-code"]
},
"/extending-nx/recipes/generator-options": {
"id": "generator-options",
@ -275,7 +275,7 @@
"itemList": [],
"isExternal": false,
"path": "/extending-nx/recipes/generator-options",
"tags": ["use-code-generators"]
"tags": ["generate-code"]
},
"/extending-nx/recipes/creating-files": {
"id": "creating-files",
@ -286,7 +286,7 @@
"itemList": [],
"isExternal": false,
"path": "/extending-nx/recipes/creating-files",
"tags": ["use-code-generators"]
"tags": ["generate-code"]
},
"/extending-nx/recipes/modifying-files": {
"id": "modifying-files",
@ -297,7 +297,7 @@
"itemList": [],
"isExternal": false,
"path": "/extending-nx/recipes/modifying-files",
"tags": ["use-code-generators"]
"tags": ["generate-code"]
},
"/extending-nx/recipes/migration-generators": {
"id": "migration-generators",

816
docs/generated/manifests/menus.json
View File

File diff suppressed because it is too large Load Diff

8
docs/generated/manifests/nx-api.json
View File

@ -1628,7 +1628,7 @@
"itemList": [],
"isExternal": false,
"path": "/nx-api/nx/documents/generate",
"tags": ["use-code-generators"],
"tags": ["generate-code"],
"originalFilePath": "generated/cli/generate"
},
"/nx-api/nx/documents/run": {
@ -1639,7 +1639,7 @@
"itemList": [],
"isExternal": false,
"path": "/nx-api/nx/documents/run",
"tags": ["run-tasks", "use-task-executors"],
"tags": ["run-tasks"],
"originalFilePath": "generated/cli/run"
},
"/nx-api/nx/documents/daemon": {
@ -1672,7 +1672,7 @@
"itemList": [],
"isExternal": false,
"path": "/nx-api/nx/documents/run-many",
"tags": ["run-tasks", "use-task-executors"],
"tags": ["run-tasks"],
"originalFilePath": "generated/cli/run-many"
},
"/nx-api/nx/documents/affected": {
@ -1683,7 +1683,7 @@
"itemList": [],
"isExternal": false,
"path": "/nx-api/nx/documents/affected",
"tags": ["run-tasks", "use-task-executors"],
"tags": ["run-tasks"],
"originalFilePath": "generated/cli/affected"
},
"/nx-api/nx/documents/affected-dep-graph": {

1203
docs/generated/manifests/nx.json
View File

File diff suppressed because it is too large Load Diff

429
docs/generated/manifests/tags.json
View File

@ -2,10 +2,10 @@
"run-tasks": [
{
"description": "Learn about the various ways you can use Nx to run tasks in your workspace.",
"file": "shared/core-features/run-tasks",
"file": "shared/features/run-tasks",
"id": "run-tasks",
"name": "Run Tasks",
"path": "/core-features/run-tasks"
"path": "/features/run-tasks"
},
{
"description": "",
@ -16,23 +16,37 @@
},
{
"description": "",
"file": "shared/recipes/running-tasks/customizing-inputs",
"id": "customizing-inputs",
"name": "Fine-tuning Caching with Inputs",
"path": "/recipes/running-tasks/customizing-inputs"
"file": "shared/recipes/running-tasks/executors-and-configurations",
"id": "executors-and-configurations",
"name": "Executors and Configurations",
"path": "/concepts/executors-and-configurations"
},
{
"description": "",
"file": "shared/recipes/running-tasks/configure-inputs",
"id": "configure-inputs",
"name": "Configure Inputs for Task Caching",
"path": "/recipes/running-tasks/configure-inputs"
},
{
"description": "",
"file": "shared/recipes/running-tasks/configure-outputs",
"id": "configure-outputs",
"name": "Configure Outputs for Task Caching",
"path": "/recipes/running-tasks/configure-outputs"
},
{
"description": "",
"file": "shared/recipes/running-tasks/defining-task-pipeline",
"id": "defining-task-pipeline",
"name": "Defining a Task Pipeline",
"name": "Define a Task Pipeline",
"path": "/recipes/running-tasks/defining-task-pipeline"
},
{
"description": "",
"file": "shared/recipes/running-tasks/running-custom-commands",
"id": "run-commands-executor",
"name": "Running Custom Commands",
"name": "Run Custom Commands",
"path": "/recipes/running-tasks/run-commands-executor"
},
{
@ -88,17 +102,17 @@
"cache-task-results": [
{
"description": "Learn about the various ways you can use Nx to run tasks in your workspace.",
"file": "shared/core-features/run-tasks",
"file": "shared/features/run-tasks",
"id": "run-tasks",
"name": "Run Tasks",
"path": "/core-features/run-tasks"
"path": "/features/run-tasks"
},
{
"description": "Learn how to define cacheable tasks, how to fine-tune with inputs and outputs, where the cache is stored and much more.",
"file": "shared/core-features/cache-task-results",
"file": "shared/features/cache-task-results",
"id": "cache-task-results",
"name": "Cache Task Results",
"path": "/core-features/cache-task-results"
"path": "/features/cache-task-results"
},
{
"description": "",
@ -109,10 +123,17 @@
},
{
"description": "",
"file": "shared/recipes/running-tasks/customizing-inputs",
"id": "customizing-inputs",
"name": "Fine-tuning Caching with Inputs",
"path": "/recipes/running-tasks/customizing-inputs"
"file": "shared/recipes/running-tasks/configure-inputs",
"id": "configure-inputs",
"name": "Configure Inputs for Task Caching",
"path": "/recipes/running-tasks/configure-inputs"
},
{
"description": "",
"file": "shared/recipes/running-tasks/configure-outputs",
"id": "configure-outputs",
"name": "Configure Outputs for Task Caching",
"path": "/recipes/running-tasks/configure-outputs"
},
{
"description": "",
@ -121,6 +142,13 @@
"name": "Troubleshoot Cache Misses",
"path": "/recipes/troubleshooting/troubleshoot-cache-misses"
},
{
"description": "",
"file": "shared/reference/inputs",
"id": "inputs",
"name": "Inputs and Named Inputs",
"path": "/reference/inputs"
},
{
"description": "",
"file": "",
@ -173,11 +201,11 @@
],
"explore-graph": [
{
"description": "Nx uses a graph behind the scenes to optimize your operations. You can also visualize and use the graph to better understand your workspace structure. Learn more in this guide.",
"file": "shared/core-features/explore-graph",
"description": "",
"file": "shared/features/explore-graph",
"id": "explore-graph",
"name": "Explore the Graph",
"path": "/core-features/explore-graph"
"name": "Explore your Workspace",
"path": "/features/explore-graph"
},
{
"description": "",
@ -215,13 +243,85 @@
"path": "/nx-api/nx/documents/dep-graph"
}
],
"generate-code": [
{
"description": "",
"file": "shared/features/generate-code",
"id": "generate-code",
"name": "Generate Code",
"path": "/features/generate-code"
},
{
"description": "",
"file": "shared/concepts/nx-plugins",
"id": "nx-plugins",
"name": "What Are Nx Plugins",
"path": "/concepts/nx-plugins"
},
{
"description": "",
"file": "shared/monorepo-nx-enterprise",
"id": "monorepo-nx-enterprise",
"name": "Using Nx at Enterprises",
"path": "/concepts/more-concepts/monorepo-nx-enterprise"
},
{
"description": "",
"file": "",
"id": "nxjson-generator-defaults",
"name": "nx.json generator defaults",
"path": "/reference/nx-json#generators"
},
{
"description": "",
"file": "shared/recipes/generators/local-generators",
"id": "local-generators",
"name": "Write a Simple Generator",
"path": "/extending-nx/recipes/local-generators"
},
{
"description": "",
"file": "shared/recipes/generators/composing-generators",
"id": "composing-generators",
"name": "Compose Generators",
"path": "/extending-nx/recipes/composing-generators"
},
{
"description": "",
"file": "shared/recipes/generators/generator-options",
"id": "generator-options",
"name": "Provide Options for Generators",
"path": "/extending-nx/recipes/generator-options"
},
{
"description": "",
"file": "shared/recipes/generators/creating-files",
"id": "creating-files",
"name": "Create Files",
"path": "/extending-nx/recipes/creating-files"
},
{
"description": "",
"file": "shared/recipes/generators/modifying-files",
"id": "modifying-files",
"name": "Modify Files",
"path": "/extending-nx/recipes/modifying-files"
},
{
"description": "The core Nx plugin contains the core functionality of Nx like the project graph, nx commands and task orchestration.",
"file": "generated/packages/generated/packages/nx/documents/generate",
"id": "generate",
"name": "generate",
"path": "/nx-api/nx/documents/generate"
}
],
"automate-updating-dependencies": [
{
"description": "Learn how Nx provides automated update scripts to help you keep your workspace, tooling and framework dependencies up to date.",
"file": "shared/core-features/automate-updating-dependencies",
"file": "shared/features/automate-updating-dependencies",
"id": "automate-updating-dependencies",
"name": "Automate Updating Dependencies",
"path": "/core-features/automate-updating-dependencies"
"path": "/features/automate-updating-dependencies"
},
{
"description": "",
@ -248,10 +348,10 @@
"enforce-module-boundaries": [
{
"description": "Learn how to avoid dependency hell and scale a codebase by imposing constraints on your projects using the module boundary lint rule.",
"file": "shared/core-features/enforce-module-boundaries",
"file": "shared/features/enforce-module-boundaries",
"id": "enforce-module-boundaries",
"name": "Enforce Module Boundaries",
"path": "/core-features/enforce-module-boundaries"
"path": "/features/enforce-module-boundaries"
},
{
"description": "",
@ -341,10 +441,10 @@
"integrate-with-editors": [
{
"description": "Learn about Nx Console, an extension for VS Code and WebStorm.",
"file": "shared/core-features/integrate-with-editors",
"file": "shared/features/integrate-with-editors",
"id": "integrate-with-editors",
"name": "Integrate with Editors",
"path": "/core-features/integrate-with-editors"
"path": "/features/integrate-with-editors"
},
{
"description": "",
@ -399,182 +499,10 @@
"manage-releases": [
{
"description": "Learn how Nx provides tools to help you manage releasing your projects.",
"file": "shared/core-features/manage-releases",
"file": "shared/features/manage-releases",
"id": "manage-releases",
"name": "Manage Releases",
"path": "/core-features/manage-releases"
}
],
"use-task-executors": [
{
"description": "",
"file": "shared/plugin-features/use-task-executors",
"id": "use-task-executors",
"name": "Use Task Executors",
"path": "/core-features/plugin-features/use-task-executors"
},
{
"description": "",
"file": "shared/concepts/task-pipeline-configuration",
"id": "task-pipeline-configuration",
"name": "What is a Task Pipeline",
"path": "/concepts/task-pipeline-configuration"
},
{
"description": "",
"file": "shared/guides/module-federation/faster-builds",
"id": "faster-builds-with-module-federation",
"name": "Faster Builds with Module Federation",
"path": "/concepts/module-federation/faster-builds-with-module-federation"
},
{
"description": "",
"file": "shared/incremental-builds",
"id": "incremental-builds",
"name": "Incremental Builds",
"path": "/concepts/more-concepts/incremental-builds"
},
{
"description": "",
"file": "shared/recipes/running-tasks/running-custom-commands",
"id": "run-commands-executor",
"name": "Running Custom Commands",
"path": "/recipes/running-tasks/run-commands-executor"
},
{
"description": "",
"file": "shared/recipes/module-federation-with-ssr",
"id": "module-federation-with-ssr",
"name": "Setup Module Federation with SSR for React",
"path": "/recipes/react/module-federation-with-ssr"
},
{
"description": "",
"file": "shared/recipes/module-federation-with-ssr",
"id": "module-federation-with-ssr",
"name": "Setup Module Federation with SSR for Angular",
"path": "/recipes/angular/module-federation-with-ssr"
},
{
"description": "",
"file": "shared/guides/module-federation/dynamic-mfe-angular",
"id": "dynamic-module-federation-with-angular",
"name": "Advanced Micro Frontends with Angular using Dynamic Federation",
"path": "/recipes/angular/dynamic-module-federation-with-angular"
},
{
"description": "",
"file": "shared/guides/performance-profiling",
"id": "performance-profiling",
"name": "Profiling Build Performance",
"path": "/recipes/troubleshooting/performance-profiling"
},
{
"description": "",
"file": "shared/reference/project-configuration",
"id": "project-configuration",
"name": "Project Configuration",
"path": "/reference/project-configuration"
},
{
"description": "",
"file": "shared/recipes/plugins/local-executors",
"id": "local-executors",
"name": "Write a Simple Executor",
"path": "/extending-nx/recipes/local-executors"
},
{
"description": "",
"file": "shared/recipes/plugins/compose-executors",
"id": "compose-executors",
"name": "Compose Executors",
"path": "/extending-nx/recipes/compose-executors"
},
{
"description": "The core Nx plugin contains the core functionality of Nx like the project graph, nx commands and task orchestration.",
"file": "generated/packages/generated/packages/nx/documents/run",
"id": "run",
"name": "run",
"path": "/nx-api/nx/documents/run"
},
{
"description": "The core Nx plugin contains the core functionality of Nx like the project graph, nx commands and task orchestration.",
"file": "generated/packages/generated/packages/nx/documents/run-many",
"id": "run-many",
"name": "run-many",
"path": "/nx-api/nx/documents/run-many"
},
{
"description": "The core Nx plugin contains the core functionality of Nx like the project graph, nx commands and task orchestration.",
"file": "generated/packages/generated/packages/nx/documents/affected",
"id": "affected",
"name": "affected",
"path": "/nx-api/nx/documents/affected"
}
],
"use-code-generators": [
{
"description": "",
"file": "shared/plugin-features/use-code-generators",
"id": "use-code-generators",
"name": "Use Code Generators",
"path": "/core-features/plugin-features/use-code-generators"
},
{
"description": "",
"file": "shared/monorepo-nx-enterprise",
"id": "monorepo-nx-enterprise",
"name": "Using Nx at Enterprises",
"path": "/concepts/more-concepts/monorepo-nx-enterprise"
},
{
"description": "",
"file": "",
"id": "nxjson-generator-defaults",
"name": "nx.json generator defaults",
"path": "/reference/nx-json#generators"
},
{
"description": "",
"file": "shared/recipes/generators/local-generators",
"id": "local-generators",
"name": "Write a Simple Generator",
"path": "/extending-nx/recipes/local-generators"
},
{
"description": "",
"file": "shared/recipes/generators/composing-generators",
"id": "composing-generators",
"name": "Compose Generators",
"path": "/extending-nx/recipes/composing-generators"
},
{
"description": "",
"file": "shared/recipes/generators/generator-options",
"id": "generator-options",
"name": "Provide Options for Generators",
"path": "/extending-nx/recipes/generator-options"
},
{
"description": "",
"file": "shared/recipes/generators/creating-files",
"id": "creating-files",
"name": "Create Files",
"path": "/extending-nx/recipes/creating-files"
},
{
"description": "",
"file": "shared/recipes/generators/modifying-files",
"id": "modifying-files",
"name": "Modify Files",
"path": "/extending-nx/recipes/modifying-files"
},
{
"description": "The core Nx plugin contains the core functionality of Nx like the project graph, nx commands and task orchestration.",
"file": "generated/packages/generated/packages/nx/documents/generate",
"id": "generate",
"name": "generate",
"path": "/nx-api/nx/documents/generate"
"path": "/features/manage-releases"
}
],
"intro": [
@ -593,6 +521,59 @@
"path": "/concepts/integrated-vs-package-based"
}
],
"create-your-own-plugin": [
{
"description": "",
"file": "shared/concepts/nx-plugins",
"id": "nx-plugins",
"name": "What Are Nx Plugins",
"path": "/concepts/nx-plugins"
},
{
"description": "",
"file": "shared/guides/nx-devkit-angular-devkit",
"id": "nx-devkit-angular-devkit",
"name": "Nx Devkit and Angular Devkit",
"path": "/concepts/more-concepts/nx-devkit-angular-devkit"
},
{
"description": "",
"file": "shared/recipes/plugins/migration-generators",
"id": "migration-generators",
"name": "Write a Migration",
"path": "/extending-nx/recipes/migration-generators"
},
{
"description": "",
"file": "shared/recipes/plugins/create-preset",
"id": "create-preset",
"name": "Create a Preset",
"path": "/extending-nx/recipes/create-preset"
},
{
"description": "",
"file": "shared/recipes/plugins/create-install-package",
"id": "create-install-package",
"name": "Create an Install Package",
"path": "/extending-nx/recipes/create-install-package"
},
{
"description": "",
"file": "shared/recipes/plugins/project-graph-plugins",
"id": "project-graph-plugins",
"name": "Modify the Project Graph",
"path": "/extending-nx/recipes/project-graph-plugins"
}
],
"inferred-tasks": [
{
"description": "",
"file": "shared/concepts/inferred-tasks",
"id": "inferred-tasks",
"name": "Inferred Tasks",
"path": "/concepts/inferred-tasks"
}
],
"repository-types": [
{
"description": "",
@ -728,13 +709,6 @@
"name": "CI Documentation",
"path": "/ci/intro/ci-with-nx"
},
{
"description": "Learn how to efficiently distribute tasks across machines to take full advantage of parallelization. Nx Cloud has a built-in DTE mechanism which makes this a trivial task.",
"file": "shared/core-features/distribute-task-execution",
"id": "distribute-task-execution",
"name": "Distribute Task Execution",
"path": "/ci/features/distribute-task-execution"
},
{
"description": "",
"file": "nx-cloud/concepts/parallelization-distribution",
@ -757,43 +731,6 @@
"path": "/nx-api/nx/documents/connect-to-nx-cloud"
}
],
"create-your-own-plugin": [
{
"description": "",
"file": "shared/guides/nx-devkit-angular-devkit",
"id": "nx-devkit-angular-devkit",
"name": "Nx Devkit and Angular Devkit",
"path": "/concepts/more-concepts/nx-devkit-angular-devkit"
},
{
"description": "",
"file": "shared/recipes/plugins/migration-generators",
"id": "migration-generators",
"name": "Write a Migration",
"path": "/extending-nx/recipes/migration-generators"
},
{
"description": "",
"file": "shared/recipes/plugins/create-preset",
"id": "create-preset",
"name": "Create a Preset",
"path": "/extending-nx/recipes/create-preset"
},
{
"description": "",
"file": "shared/recipes/plugins/create-install-package",
"id": "create-install-package",
"name": "Create an Install Package",
"path": "/extending-nx/recipes/create-install-package"
},
{
"description": "",
"file": "shared/recipes/plugins/project-graph-plugins",
"id": "project-graph-plugins",
"name": "Modify the Project Graph",
"path": "/extending-nx/recipes/project-graph-plugins"
}
],
"workspace-watching": [
{
"description": "",
@ -1189,9 +1126,9 @@
"remote-cache": [
{
"description": "Learn how to enable remote caching s.t. you don't just benefit locally from it but also in CI.",
"file": "shared/core-features/remote-cache",
"file": "shared/features/remote-cache",
"id": "remote-cache",
"name": "Use Remote Caching",
"name": "Use Remote Caching (Nx Replay)",
"path": "/ci/features/remote-cache"
}
],

8
docs/generated/packages-metadata.json
View File

@ -1608,7 +1608,7 @@
"itemList": [],
"isExternal": false,
"path": "nx/documents/generate",
"tags": ["use-code-generators"],
"tags": ["generate-code"],
"originalFilePath": "generated/cli/generate"
},
{
@ -1619,7 +1619,7 @@
"itemList": [],
"isExternal": false,
"path": "nx/documents/run",
"tags": ["run-tasks", "use-task-executors"],
"tags": ["run-tasks"],
"originalFilePath": "generated/cli/run"
},
{
@ -1652,7 +1652,7 @@
"itemList": [],
"isExternal": false,
"path": "nx/documents/run-many",
"tags": ["run-tasks", "use-task-executors"],
"tags": ["run-tasks"],
"originalFilePath": "generated/cli/run-many"
},
{
@ -1663,7 +1663,7 @@
"itemList": [],
"isExternal": false,
"path": "nx/documents/affected",
"tags": ["run-tasks", "use-task-executors"],
"tags": ["run-tasks"],
"originalFilePath": "generated/cli/affected"
},
{

42
docs/generated/packages/angular/documents/overview.md
View File

@ -1,3 +1,8 @@
---
title: Overview of the Nx Angular Plugin
description: The Nx Plugin for Angular contains executors, generators, and utilities for managing Angular applications and libraries within an Nx workspace.
---
The Nx Plugin for Angular contains executors, generators, and utilities for managing Angular applications and libraries
within an Nx workspace. It provides:
@ -15,37 +20,34 @@ You can easily and mostly **automatically migrate from an Angular CLI** project
more [here](/recipes/angular/migration/angular).
{% /callout %}
## Setting up the Angular plugin
## Setting Up @nx/angular
### Installation
{% callout type="note" title="Keep Nx Package Versions In Sync" %}
Make sure to install the `@nx/angular` version that matches the version of `nx` in your repository. If the version
numbers get out of sync, you can encounter some difficult to debug errors. You
can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
Make sure to install the `@nx/angular` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
{% /callout %}
Adding the Angular plugin to an existing Nx workspace can be done with the following:
In any Nx workspace, you can install `@nx/angular` by running the following command:
{% tabs %}
{% tab label="npm" %}
{% tab label="Nx 18+" %}
```shell
nx add @nx/angular
```
This will install the correct version of `@nx/angular`.
{% /tab %}
{% tab label="Nx < 18" %}
Install the `@nx/angular` package with your package manager.
```shell
npm add -D @nx/angular
```
{% /tab %}
{% tab label="yarn" %}
```shell
yarn add -D @nx/angular
```
{% /tab %}
{% tab label="pnpm" %}
```shell
pnpm add -D @nx/angular
```
{% /tab %}
{% /tabs %}

2
docs/generated/packages/angular/generators/cypress-component-configuration.json
View File

@ -37,7 +37,7 @@
}
},
"required": ["project"],
"examplesFile": "{% callout type=\"caution\" title=\"Can I use component testing?\" %}\nAngular component testing with Nx requires **Cypress version 10.7.0** and up.\n\nYou can migrate with to v10 via the [migrate-to-cypress-10 generator](/packages/cypress/generators/migrate-to-cypress-10).\n\nThis generator is for Cypress based component testing.\n\nIf you want to test components via Storybook with Cypress, then check out the [storybook-configuration generator docs](/nx-api/angular/generators/storybook-configuration). However, this functionality is deprecated, and will be removed on Nx version 18.\n{% /callout %}\n\nThis generator is designed to get your Angular project up and running with Cypress Component Testing.\n\n```shell\nnx g @nx/angular:cypress-component-configuration --project=my-cool-angular-project\n```\n\nRunning this generator, adds the required files to the specified project with a preconfigured `cypress.config.ts` designed for Nx workspaces.\n\n```ts {% fileName=\"cypress.config.ts\" %}\nimport { defineConfig } from 'cypress';\nimport { nxComponentTestingPreset } from '@nx/angular/plugins/component-testing';\n\nexport default defineConfig({\n component: nxComponentTestingPreset(__filename),\n});\n```\n\nHere is an example on how to add custom options to the configuration\n\n```ts {% fileName=\"cypress.config.ts\" %}\nimport { defineConfig } from 'cypress';\nimport { nxComponentTestingPreset } from '@nx/angular/plugins/component-testing';\n\nexport default defineConfig({\n component: {\n ...nxComponentTestingPreset(__filename),\n // extra options here\n },\n});\n```\n\n## Specifying a Build Target\n\nComponent testing requires a _build target_ to correctly run the component test dev server. This option can be manually specified with `--build-target=some-angular-app:build`, but Nx will infer this usage from the [project graph](/concepts/mental-model#the-project-graph) if one isn't provided.\n\nFor Angular projects, the build target needs to be using the `@nx/angular:webpack-browser` or\n`@angular-devkit/build-angular:browser` executor.\nThe generator will throw an error if a build target can't be found and suggest passing one in manually.\n\nLetting Nx infer the build target by default\n\n```shell\nnx g @nx/angular:cypress-component-configuration --project=my-cool-angular-project\n```\n\nManually specifying the build target\n\n```shell\nnx g @nx/angular:cypress-component-configuration --project=my-cool-angular-project --build-target:some-angular-app:build --generate-tests\n```\n\n{% callout type=\"note\" title=\"Build Target with Configuration\" %}\nIf you're wanting to use a build target with a specific configuration. i.e. `my-app:build:production`,\nthen manually providing `--build-target=my-app:build:production` is the best way to do that.\n{% /callout %}\n\n## Auto Generating Tests\n\nYou can optionally use the `--generate-tests` flag to generate a test file for each component in your project.\n\n```shell\nnx g @nx/angular:cypress-component-configuration --project=my-cool-angular-project --generate-tests\n```\n\n## Running Component Tests\n\nA new `component-test` target will be added to the specified project to run your component tests.\n\n```shell\nnx g component-test my-cool-angular-project\n```\n\nHere is an example of the project configuration that is generated. The `--build-target` option is added as the `devServerTarget` which can be changed as needed.\n\n```json {% fileName=\"project.json\" %}\n{\n \"targets\" {\n \"component-test\": {\n \"executor\": \"@nx/cypress:cypress\",\n \"options\": {\n \"cypressConfig\": \"<path-to-project-root>/cypress.config.ts\",\n \"testingType\": \"component\",\n \"devServerTarget\": \"some-angular-app:build\",\n \"skipServe\": true\n }\n }\n }\n}\n```\n\n## What is bundled\n\nWhen the project being tested is a dependent of the specified `--build-target`, then **assets, scripts, and styles** are applied to the component being tested. You can determine if the project is dependent by using the [project graph](/core-features/explore-graph). If there is no link between the two projects, then the **assets, scripts, and styles** won't be included in the build; therefore, they will not be applied to the component. To have a link between projects, you can import from the project being tested into the specified `--build-target` project, or set the `--build-target` project to [implicitly depend](/reference/project-configuration#implicitdependencies) on the project being tested.\n\nNx also supports [React component testing](/packages/angular/generators/cypress-component-configuration).\n",
"examplesFile": "{% callout type=\"caution\" title=\"Can I use component testing?\" %}\nAngular component testing with Nx requires **Cypress version 10.7.0** and up.\n\nYou can migrate with to v10 via the [migrate-to-cypress-10 generator](/packages/cypress/generators/migrate-to-cypress-10).\n\nThis generator is for Cypress based component testing.\n\nIf you want to test components via Storybook with Cypress, then check out the [storybook-configuration generator docs](/nx-api/angular/generators/storybook-configuration). However, this functionality is deprecated, and will be removed on Nx version 18.\n{% /callout %}\n\nThis generator is designed to get your Angular project up and running with Cypress Component Testing.\n\n```shell\nnx g @nx/angular:cypress-component-configuration --project=my-cool-angular-project\n```\n\nRunning this generator, adds the required files to the specified project with a preconfigured `cypress.config.ts` designed for Nx workspaces.\n\n```ts {% fileName=\"cypress.config.ts\" %}\nimport { defineConfig } from 'cypress';\nimport { nxComponentTestingPreset } from '@nx/angular/plugins/component-testing';\n\nexport default defineConfig({\n component: nxComponentTestingPreset(__filename),\n});\n```\n\nHere is an example on how to add custom options to the configuration\n\n```ts {% fileName=\"cypress.config.ts\" %}\nimport { defineConfig } from 'cypress';\nimport { nxComponentTestingPreset } from '@nx/angular/plugins/component-testing';\n\nexport default defineConfig({\n component: {\n ...nxComponentTestingPreset(__filename),\n // extra options here\n },\n});\n```\n\n## Specifying a Build Target\n\nComponent testing requires a _build target_ to correctly run the component test dev server. This option can be manually specified with `--build-target=some-angular-app:build`, but Nx will infer this usage from the [project graph](/concepts/mental-model#the-project-graph) if one isn't provided.\n\nFor Angular projects, the build target needs to be using the `@nx/angular:webpack-browser` or\n`@angular-devkit/build-angular:browser` executor.\nThe generator will throw an error if a build target can't be found and suggest passing one in manually.\n\nLetting Nx infer the build target by default\n\n```shell\nnx g @nx/angular:cypress-component-configuration --project=my-cool-angular-project\n```\n\nManually specifying the build target\n\n```shell\nnx g @nx/angular:cypress-component-configuration --project=my-cool-angular-project --build-target:some-angular-app:build --generate-tests\n```\n\n{% callout type=\"note\" title=\"Build Target with Configuration\" %}\nIf you're wanting to use a build target with a specific configuration. i.e. `my-app:build:production`,\nthen manually providing `--build-target=my-app:build:production` is the best way to do that.\n{% /callout %}\n\n## Auto Generating Tests\n\nYou can optionally use the `--generate-tests` flag to generate a test file for each component in your project.\n\n```shell\nnx g @nx/angular:cypress-component-configuration --project=my-cool-angular-project --generate-tests\n```\n\n## Running Component Tests\n\nA new `component-test` target will be added to the specified project to run your component tests.\n\n```shell\nnx g component-test my-cool-angular-project\n```\n\nHere is an example of the project configuration that is generated. The `--build-target` option is added as the `devServerTarget` which can be changed as needed.\n\n```json {% fileName=\"project.json\" %}\n{\n \"targets\" {\n \"component-test\": {\n \"executor\": \"@nx/cypress:cypress\",\n \"options\": {\n \"cypressConfig\": \"<path-to-project-root>/cypress.config.ts\",\n \"testingType\": \"component\",\n \"devServerTarget\": \"some-angular-app:build\",\n \"skipServe\": true\n }\n }\n }\n}\n```\n\n## What is bundled\n\nWhen the project being tested is a dependent of the specified `--build-target`, then **assets, scripts, and styles** are applied to the component being tested. You can determine if the project is dependent by using the [project graph](/features/explore-graph). If there is no link between the two projects, then the **assets, scripts, and styles** won't be included in the build; therefore, they will not be applied to the component. To have a link between projects, you can import from the project being tested into the specified `--build-target` project, or set the `--build-target` project to [implicitly depend](/reference/project-configuration#implicitdependencies) on the project being tested.\n\nNx also supports [React component testing](/packages/angular/generators/cypress-component-configuration).\n",
"presets": []
},
"description": "Setup Cypress component testing for a project.",

84
docs/generated/packages/cypress/documents/overview.md
View File

@ -1,3 +1,8 @@
---
title: Overview of the Nx Cypress Plugin
description: The Nx Plugin for Cypress contains executors and generators that support e2e testing with Cypress. This page also explains how to configure Cypress on your Nx workspace.
---
Cypress is a test runner built for the modern web. It has a lot of great features:
- Time travel
@ -7,35 +12,78 @@ Cypress is a test runner built for the modern web. It has a lot of great feature
- Network traffic control
- Screenshots and videos
## Setting Up Cypress
## Setting Up @nx/cypress
> Info about [Cypress Component Testing can be found here](/recipes/cypress/cypress-component-testing)
>
> Info about [using Cypress and Storybook can be found here](/recipes/storybook/overview-react#cypress-tests-for-storiesbook)
If the `@nx/cypress` package is not installed, install the version that matches your `nx` package version.
### Installation
{% callout type="note" title="Keep Nx Package Versions In Sync" %}
Make sure to install the `@nx/cypress` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
{% /callout %}
In any Nx workspace, you can install `@nx/cypress` by running the following command:
{% tabs %}
{% tab label="npm" %}
{% tab label="Nx 18+" %}
```shell
nx add @nx/cypress
```
This will install the correct version of `@nx/cypress`.
### How @nx/cypress Infers Tasks
The `@nx/cypress` plugin will create a task for any project that has a Cypress configuration file present. Any of the following files will be recognized as a Cypress configuration file:
- `cypress.config.js`
- `cypress.config.ts`
- `cypress.config.mjs`
- `cypress.config.mts`
- `cypress.config.cjs`
- `cypress.config.cts`
### View Inferred Tasks
To view inferred tasks for a project, open the [project details view](/concepts/inferred-tasks) in Nx Console or run `nx show project my-project --web` in the command line.
### @nx/cypress Configuration
The `@nx/cypress/plugin` is configured in the `plugins` array in `nx.json`.
```json {% fileName="nx.json" %}
{
"plugins": [
{
"plugin": "@nx/cypress/plugin",
"options": {
"ciTargetName": "e2e-ci",
"targetName": "e2e",
"componentTestingTargetName": "component-test"
}
}
]
}
```
- The `targetName`, `ciTargetName` and `componentTestingTargetName` options control the namea of the inferred Cypress tasks. The default names are `e2e`, `e2e-ci` and `component-test`.
### Splitting E2E tasks by file
The `@nx/cypress/plugin` will automatically split your e2e tasks by file. You can read more about this feature [here](/ci/features/split-e2e-tasks).
{% /tab %}
{% tab label="Nx < 18" %}
Install the `@nx/cypress` package with your package manager.
```shell
npm add -D @nx/cypress
```
{% /tab %}
{% tab label="yarn" %}
```shell
yarn add -D @nx/cypress
```
{% /tab %}
{% tab label="pnpm" %}
```shell
pnpm add -D @nx/cypress
```
{% /tab %}
{% /tabs %}
@ -67,7 +115,7 @@ Replace `your-app-name` with the app's name as defined in your `tsconfig.base.js
Run `nx e2e frontend-e2e` to execute e2e tests with Cypress.
You can run your e2e test against a production build by using the `production` [configuration](https://nx.dev/plugin-features/use-task-executors#use-executor-configurations)
You can run your e2e test against a production build by using the `production` [configuration](https://nx.dev/concepts/executors-and-configurations#use-task-configurations)
```shell
nx e2e frontend-e2e --configuration=production

2
docs/generated/packages/cypress/executors/cypress.json
View File

@ -156,7 +156,7 @@
},
"additionalProperties": true,
"required": ["cypressConfig"],
"examplesFile": "Depending on your testing type, the Cypress executor is configured in different ways. The following are sample configurations that are created via the [configuration](/packages/cypress/generators/configuration) and [cypress-component-configuration](/packages/cypress/generators/cypress-component-configuration) generators.\n\n{% tabs %}\n{% tab label=\"E2E Testing\" %}\n\n```json\n\"targets\": {\n \"e2e\": {\n \"executor\": \"@nx/cypress:cypress\",\n \"options\": {\n \"cypressConfig\": \"apps/app-e2e/cypres.config.ts\",\n \"devServerTarget\": \"my-react-app:serve\",\n \"testingType\": \"e2e\"\n }\n }\n}\n```\n\n{% callout type=\"note\" title=\"API Testing\" %}\nAPI testing with Cypress is the same setup as e2e testing. Just change which `devServerTarget` is used!\n{% /callout %}\n\n### Providing a Base URL\n\nIf `devServerTarget` is provided, the url returned from started the dev server will be passed to cypress as the `baseUrl` option.\n\nDefining a `baseUrl` in the executor options will override the inferred `baseUrl` from the `devServerTarget`.\n\nThe `baseUrl` defined in the Cypress config file is the last value used if no url is found in the `devServerTarget` or executor options.\n\n### Static Serving\n\nWhen running in CI it doesn't make sense to start up a dev server since there aren't changes to watch for.\n\nYou can use [`@nx/web:file-server`](/packages/web/executors/file-server) to serve the pre-built static files of your frontend project.\n\nIn some _frontend_ application, add a 'static-serve' target.\n\n```json\n\"serve-static\": {\n \"executor\": \"@nx/web:file-server\",\n \"options\":{\n \"buildTarget\": \"frontend:build\"\n }\n}\n```\n\nIn the _e2e_ application add a configuration to change `devServerTarget` to point to the `static-serve` from the _frontend_ application\n\n```json\n\"e2e\": {\n //...\n \"configurations\": {\n \"ci\": {\n \"devServerTarget\": \"frontend:serve-static\"\n }\n }\n}\n```\n\n{% callout type=\"note\" title=\"What about Node projects?\" %}\nThe same can be done for backend node apps with [`@nx/js:node` executor](/packages/js/executors/node)\n{% /callout %}\n\n```bash\nnx e2e my-app-e2e --configuration=ci\n```\n\n{% /tab %}\n{% tab label=\"Component Testing\" %}\n\n{% callout type=\"note\" title=\"Cypress Component Testing\" %}\nWhen adding component testing to a project, it's best to use the framework specific generator, instead `cypress-component-project` directly.\n\n- [React component testing](/packages/react/generators/cypress-component-configuration)\n- [Angular component testing](/packages/angular/generators/cypress-component-configuration)\n\n{% /callout %}\n\n```json\n\"targets\": {\n \"component-test\": {\n \"executor\": \"@nx/cypress:cypress\",\n \"options\": {\n \"cypressConfig\": \"apps/app/cypres.config.ts\",\n \"devServerTarget\": \"my-react-app:build\",\n \"testingType\": \"component\",\n \"skipServe\": true\n }\n }\n}\n```\n\nIt's important `skipServe` is set to true. Nx doesn't need to run the `devServerTarget`, Cypress creates its own dev server for component testing.\nInstead, Nx needs to know what build target to create the correct configuration to pass to Cypress, which is why it's still used in component testing.\n\n{% /tab %}\n{% /tabs %}\n\n### Environment Variables\n\nUsing [executor configurations](recipes/executors/use-executor-configurations#use-executor-configurations) offers flexibility to set environment variables\n\n```json\n\"targets\": {\n \"e2e\": {\n \"executor\": \"@nx/cypress:cypress\",\n \"options\": {\n \"cypressConfig\": \"apps/app-e2e/cypres.config.ts\",\n \"devServerTarget\": \"my-react-app:serve\",\n \"testingType\": \"e2e\"\n },\n \"configurations\": {\n \"qa\": {\n \"env\": {\n \"API_URL\": \"https://api.qa.company.com\"\n }\n },\n \"dev\": {\n \"env\": {\n \"API_URL\": \"http://localhost:3333/api\"\n }\n }\n }\n }\n}\n```\n\nRead more on different ways to use [environment variables for cypress executor](/packages/cypress#environment-variables)\n"
"examplesFile": "Depending on your testing type, the Cypress executor is configured in different ways. The following are sample configurations that are created via the [configuration](/packages/cypress/generators/configuration) and [cypress-component-configuration](/packages/cypress/generators/cypress-component-configuration) generators.\n\n{% tabs %}\n{% tab label=\"E2E Testing\" %}\n\n```json\n\"targets\": {\n \"e2e\": {\n \"executor\": \"@nx/cypress:cypress\",\n \"options\": {\n \"cypressConfig\": \"apps/app-e2e/cypres.config.ts\",\n \"devServerTarget\": \"my-react-app:serve\",\n \"testingType\": \"e2e\"\n }\n }\n}\n```\n\n{% callout type=\"note\" title=\"API Testing\" %}\nAPI testing with Cypress is the same setup as e2e testing. Just change which `devServerTarget` is used!\n{% /callout %}\n\n### Providing a Base URL\n\nIf `devServerTarget` is provided, the url returned from started the dev server will be passed to cypress as the `baseUrl` option.\n\nDefining a `baseUrl` in the executor options will override the inferred `baseUrl` from the `devServerTarget`.\n\nThe `baseUrl` defined in the Cypress config file is the last value used if no url is found in the `devServerTarget` or executor options.\n\n### Static Serving\n\nWhen running in CI it doesn't make sense to start up a dev server since there aren't changes to watch for.\n\nYou can use [`@nx/web:file-server`](/packages/web/executors/file-server) to serve the pre-built static files of your frontend project.\n\nIn some _frontend_ application, add a 'static-serve' target.\n\n```json\n\"serve-static\": {\n \"executor\": \"@nx/web:file-server\",\n \"options\":{\n \"buildTarget\": \"frontend:build\"\n }\n}\n```\n\nIn the _e2e_ application add a configuration to change `devServerTarget` to point to the `static-serve` from the _frontend_ application\n\n```json\n\"e2e\": {\n //...\n \"configurations\": {\n \"ci\": {\n \"devServerTarget\": \"frontend:serve-static\"\n }\n }\n}\n```\n\n{% callout type=\"note\" title=\"What about Node projects?\" %}\nThe same can be done for backend node apps with [`@nx/js:node` executor](/packages/js/executors/node)\n{% /callout %}\n\n```bash\nnx e2e my-app-e2e\n```\n\n{% /tab %}\n{% tab label=\"Component Testing\" %}\n\n{% callout type=\"note\" title=\"Cypress Component Testing\" %}\nWhen adding component testing to a project, it's best to use the framework specific generator, instead `cypress-component-project` directly.\n\n- [React component testing](/packages/react/generators/cypress-component-configuration)\n- [Angular component testing](/packages/angular/generators/cypress-component-configuration)\n\n{% /callout %}\n\n```json\n\"targets\": {\n \"component-test\": {\n \"executor\": \"@nx/cypress:cypress\",\n \"options\": {\n \"cypressConfig\": \"apps/app/cypres.config.ts\",\n \"devServerTarget\": \"my-react-app:build\",\n \"testingType\": \"component\",\n \"skipServe\": true\n }\n }\n}\n```\n\nIt's important `skipServe` is set to true. Nx doesn't need to run the `devServerTarget`, Cypress creates its own dev server for component testing.\nInstead, Nx needs to know what build target to create the correct configuration to pass to Cypress, which is why it's still used in component testing.\n\n{% /tab %}\n{% /tabs %}\n\n### Environment Variables\n\nUsing [executor configurations](recipes/executors/use-executor-configurations#use-executor-configurations) offers flexibility to set environment variables\n\n```json\n\"targets\": {\n \"e2e\": {\n \"executor\": \"@nx/cypress:cypress\",\n \"options\": {\n \"cypressConfig\": \"apps/app-e2e/cypres.config.ts\",\n \"devServerTarget\": \"my-react-app:serve\",\n \"testingType\": \"e2e\"\n },\n \"configurations\": {\n \"qa\": {\n \"env\": {\n \"API_URL\": \"https://api.qa.company.com\"\n }\n },\n \"dev\": {\n \"env\": {\n \"API_URL\": \"http://localhost:3333/api\"\n }\n }\n }\n }\n}\n```\n\nRead more on different ways to use [environment variables for cypress executor](/packages/cypress#environment-variables)\n"
},
"description": "Run Cypress E2E tests.",
"aliases": [],

109
docs/generated/packages/detox/documents/overview.md
View File

@ -8,7 +8,9 @@ Detox is gray box end-to-end testing and automation library for mobile apps. It
## Setting Up Detox
### Install applesimutils (Mac only)
### Setup Environment
#### Install applesimutils (Mac only)
[applesimutils](https://github.com/wix/AppleSimulatorUtils) is a collection of utils for Apple simulators.
@ -17,60 +19,81 @@ brew tap wix/brew
brew install applesimutils
```
### Install Jest Globally
#### Install Jest Globally
```sh
npm install -g jest
```
### Installation
{% callout type="note" title="Keep Nx Package Versions In Sync" %}
Make sure to install the `@nx/detox` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
{% /callout %}
In any Nx workspace, you can install `@nx/detox` by running the following command:
{% tabs %}
{% tab label="Nx 18+" %}
```shell
nx add @nx/detox
```
This will install the correct version of `@nx/detox`.
### How @nx/detox Infers Tasks
The `@nx/detox` plugin will create a task for any project that has an ESLint configuration file present. Any of the following files will be recognized as an ESLint configuration file:
- `.detoxrc.js`
- `.detoxrc.json`
- `detox.config.js`
- `detox.config.json`
### View Inferred Tasks
To view inferred tasks for a project, open the [project details view](/concepts/inferred-tasks) in Nx Console or run `nx show project my-project --web` in the command line.
### @nx/detox Configuration
The `@nx/detox/plugin` is configured in the `plugins` array in `nx.json`.
```json {% fileName="nx.json" %}
{
"plugins": [
{
"plugin": "@nx/detox/plugin",
"options": {
"buildTargetName": "build",
"startTargetName": "start",
"testTargetName": "test"
}
}
]
}
```
Once a Detox configuration file has been identified, the targets are created with the name you specify under `buildTargetName`, `startTargetName` or `testTargetName` in the `nx.json` `plugins` array. The default names for the inferred targets are `build` and `test`.
{% /tab %}
{% tab label="Nx < 18" %}
Install the `@nx/detox` package with your package manager.
```shell
npm add -D @nx/detox
```
### Generating Applications
By default, when creating a mobile application, Nx will use Detox to create the e2e tests project.
```shell
nx g @nx/react-native:app frontend
nx g @nx/react-native:app frontend --e2eTestRunner=deotx
nx g @nx/expo:app frontend --e2eTestRunner=detox
```
### Creating a Detox E2E project for an existing project
You can create a new Detox E2E project for an existing mobile project.
If the `@nx/detox` package is not installed, install the version that matches your `@nx/workspace` version.
{% tabs %}
{% tab label="npm" %}
```shell
npm add -D @nx/detox
```
{% /tab %}
{% tab label="yarn" %}
```shell
yarn add -D @nx/detox
```
{% /tab %}
{% tab label="pnpm" %}
```shell
pnpm add -D @nx/detox
```
{% /tab %}
{% /tabs %}
Next, generate an E2E project based on an existing project.
```sh
nx g @nx/detox:app your-app-name-e2e --project=your-app-name
```
Replace `your-app-name` with the app's name as defined in your `tsconfig.base.json` file or the `name` property of your `package.json`.
In addition, you need to follow [instructions at Detox](https://github.com/wix/Detox/blob/master/docs/Introduction.Android.md) to do manual setup for Android files.
## Using Detox
### Testing Applications

40
docs/generated/packages/esbuild/documents/overview.md
View File

@ -1,3 +1,8 @@
---
title: Overview of the Nx esbuild Plugin
description: The Nx Plugin for esbuild contains executors and generators that support building applications using esbuild. This page also explains how to configure esbuild on your Nx workspace.
---
The Nx Plugin for [esbuild](https://esbuild.github.io/api/), an extremely fast JavaScript bundler.
Why should you use this plugin?
@ -7,40 +12,39 @@ Why should you use this plugin?
- Intelligent `package.json` output.
- Additional [assets](/nx-api/esbuild/executors/esbuild#assets) for the output.
## Setting up esbuild
## Setting Up @nx/esbuild
To create a new workspace, run `npx create-nx-workspace@latest --preset=npm`.
### Installation
{% callout type="note" title="Keep Nx Package Versions In Sync" %}
Make sure to install the `@nx/esbuild` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
{% /callout %}
To add the esbuild plugin to an existing workspace, run the following:
In any Nx workspace, you can install `@nx/esbuild` by running the following command:
{% tabs %}
{% tab label="npm" %}
{% tab label="Nx 18+" %}
```shell
nx add @nx/esbuild
```
This will install the correct version of `@nx/esbuild`.
{% /tab %}
{% tab label="Nx < 18" %}
Install the `@nx/esbuild` package with your package manager.
```shell
npm add -D @nx/esbuild
```
{% /tab %}
{% tab label="yarn" %}
```shell
yarn add -D @nx/esbuild
```
{% /tab %}
{% tab label="pnpm" %}
```shell
pnpm add -D @nx/esbuild
```
{% /tab %}
{% /tabs %}
## Using the @nx/esbuild Plugin
### Creating a new JS library
{% callout type="note" title="Directory Flag Behavior Changes" %}

2
docs/generated/packages/eslint-plugin/documents/enforce-module-boundaries.md
View File

@ -53,7 +53,7 @@ The `depConstraints` is an array of objects representing the constraints defined
Read more about the proper usage of this rule:
- [Enforce Module Boundaries](/core-features/enforce-module-boundaries)
- [Enforce Module Boundaries](/features/enforce-module-boundaries)
- [Ban Dependencies with Certain Tags](/recipes/enforce-module-boundaries/ban-dependencies-with-tags)
- [Tag in Multiple Dimensions](/recipes/enforce-module-boundaries/tag-multiple-dimensions)
- [Ban External Imports](/recipes/enforce-module-boundaries/ban-external-imports)

22
docs/generated/packages/eslint-plugin/documents/overview.md
View File

@ -13,30 +13,10 @@ Make sure to install the `@nx/eslint-plugin` version that matches the version of
In any Nx workspace, you can install `@nx/eslint-plugin` by running the following commands if the package is not already installed:
{% tabs %}
{% tab label="npm" %}
```shell
npm add -D @nx/eslint-plugin
nx add @nx/eslint-plugin
```
{% /tab %}
{% tab label="yarn" %}
```shell
yarn add -D @nx/eslint-plugin
```
{% /tab %}
{% tab label="pnpm" %}
```shell
pnpm add -D @nx/eslint-plugin
```
{% /tab %}
{% /tabs %}
## Included plugins
The plugin contains the following rule configurations divided into sub-plugins.

54
docs/generated/packages/eslint/documents/overview.md
View File

@ -1,6 +1,6 @@
The ESLint plugin contains executors, generator, plugin and utilities used for linting JavaScript/TypeScript projects within an Nx workspace.
The ESLint plugin integrates [ESLint](https://eslint.org/) with Nx. It allows you to run ESLint through Nx with caching enabled. It also includes code generators to help you set up ESLint in your workspace.
## Setting Up ESLint
## Setting Up @nx/eslint
### Installation
@ -11,24 +11,58 @@ Make sure to install the `@nx/eslint` version that matches the version of `nx` i
In any Nx workspace, you can install `@nx/eslint` by running the following command:
{% tabs %}
{%tab label="npm"%}
{% tab label="Nx 18+" %}
```shell
npm i -D @nx/eslint
nx add @nx/eslint
```
{% /tab %}
{%tab label="yarn"%}
This will install the correct version of `@nx/eslint`.
```shell
yarn add -D @nx/eslint
### How @nx/eslint Infers Tasks
The `@nx/eslint` plugin will create a task for any project that has an ESLint configuration file present. Any of the following files will be recognized as an ESLint configuration file:
- `.eslintrc`
- `.eslintrc.js`
- `.eslintrc.cjs`
- `.eslintrc.yaml`
- `.eslintrc.yml`
- `.eslintrc.json`
- `eslint.config.js`
Because ESLint applies configuration files to all subdirectories, the `@nx/eslint` plugin will also infer tasks for projects in subdirectories. So, if there is an ESLint configuration file in the root of the repository, every project will have an inferred ESLint task.
### View Inferred Tasks
To view inferred tasks for a project, open the [project details view](/concepts/inferred-tasks) in Nx Console or run `nx show project my-project --web` in the command line.
### @nx/eslint Configuration
The `@nx/eslint/plugin` is configured in the `plugins` array in `nx.json`.
```json {% fileName="nx.json" %}
{
"plugins": [
{
"plugin": "@nx/eslint/plugin",
"options": {
"targetName": "lint"
}
}
]
}
```
- The `targetName` option controls the name of the inferred ESLint tasks. The default name is `lint`.
{% /tab %}
{%tab label="pnpm"%}
{% tab label="Nx < 18" %}
Install the `@nx/eslint` package with your package manager.
```shell
pnpm add -D @nx/eslint
npm add -D @nx/eslint
```
{% /tab %}

89
docs/generated/packages/expo/documents/overview.md
View File

@ -4,44 +4,87 @@ Expo is a set of tools built on top of React Native. The Nx Plugin for Expo cont
## Setting Up Expo
To create a new workspace with expo, run the following command:
To create a new workspace with Expo, run the following command:
```shell
npx create-nx-workspace --preset=expo
npx create-nx-workspace@latest --preset=expo --appName=your-app-name
```
### Adding Expo to an Existing Project
Install the expo plugin
### Installation
{% callout type="note" title="Keep Nx Package Versions In Sync" %}
Make sure to install the `@nx/expo` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
{% /callout %}
In any Nx workspace, you can install `@nx/expo` by running the following command:
{% tabs %}
{% tab label="npm" %}
{% tab label="Nx 18+" %}
```shell
nx add @nx/expo
```
This will install the correct version of `@nx/expo`.
### How @nx/expo Infers Tasks
The `@nx/expo` plugin will create a task for any project that has an app configuration file present. Any of the following files will be recognized as an app configuration file:
- `app.config.js`
- `app.json`
In the app config file, it needs to have key `expo`:
```json
{
"expo": {
"name": "MyProject",
"slug": "my-project"
}
}
```
### View Inferred Tasks
To view inferred tasks for a project, open the [project details view](/concepts/inferred-tasks) in Nx Console or run `nx show project my-project --web` in the command line.
### @nx/expo Configuration
The `@nx/expo/plugin` is configured in the `plugins` array in `nx.json`.
```json {% fileName="nx.json" %}
{
"plugins": [
{
"plugin": "@nx/expo/plugin",
"options": {
"startTargetName": "start",
"serveTargetName": "serve",
"runIosTargetName": "run-ios",
"runAndroidTargetName": "run-android",
"exportTargetName": "export",
"prebuildTargetName": "prebuild",
"installTargetName": "install",
"buildTargetName": "build",
"submitTargetName": "submit"
}
}
]
}
```
Once a Expo configuration file has been identified, the targets are created with the name you specify under `startTargetName`, `serveTargetName`, `runIosTargetName`, `runAndroidTargetname`, `exportTargetName`, `prebuildTargetName`, `installTargetName`, `buildTargetName` or `submitTargetName` in the `nx.json` `plugins` array. The default names for the inferred targets are `start`, `serve`, `run-ios`, `run-anroid`, `export`, `prebuild`, `install`, `build` and `submit`.
{% /tab %}
{% tab label="Nx < 18" %}
Install the `@nx/expo` package with your package manager.
```shell
npm add -D @nx/expo
```
{% /tab %}
{% tab label="yarn" %}
```shell
yarn add -D @nx/expo
```
{% /tab %}
{% tab label="pnpm" %}
```shell
pnpm add -D @nx/expo
```
{% /tab %}
{% /tabs %}
### Creating Applications
Add a new application to your workspace with the following command:

31
docs/generated/packages/express/documents/overview.md
View File

@ -9,6 +9,37 @@ To create a new workspace with a pre-created Express app, run the following comm
npx create-nx-workspace --preset=express
```
## Setting Up @nx/express
### Installation
{% callout type="note" title="Keep Nx Package Versions In Sync" %}
Make sure to install the `@nx/express` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
{% /callout %}
In any Nx workspace, you can install `@nx/express` by running the following command:
{% tabs %}
{% tab label="Nx 18+" %}
```shell
nx add @nx/express
```
This will install the correct version of `@nx/express`.
{% /tab %}
{% tab label="Nx < 18" %}
Install the `@nx/express` package with your package manager.
```shell
npm add -D @nx/express
```
{% /tab %}
{% /tabs %}
## Recipes
- [Add an Express Application to Your Workspace](/showcase/example-repos/add-express)

112
docs/generated/packages/jest/documents/overview.md
View File

@ -1,10 +1,82 @@
---
title: Overview of the Nx Jest Plugin
description: The Nx Plugin for Jest contains executors and generators that support testing projects using Jest. This page also explains how to configure Jest on your Nx workspace.
---
[Jest](https://jestjs.io/) is an open source test runner created by Facebook. It has a lot of great features:
- Immersive watch mode for providing near instant feedback when developing tests.
- Snapshot testing for validating features.
- Great built-in reporter for printing out test results.
## Setting up Jest
## Setting Up @nx/jest
### Installation
{% callout type="note" title="Keep Nx Package Versions In Sync" %}
Make sure to install the `@nx/jest` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
{% /callout %}
In any Nx workspace, you can install `@nx/jest` by running the following command:
{% tabs %}
{% tab label="Nx 18+" %}
```shell
nx add @nx/jest
```
This will install the correct version of `@nx/jest`.
### How @nx/jest Infers Tasks
The `@nx/jest` plugin will create a task for any project that has an Jest configuration file present. Any of the following files will be recognized as an Jest configuration file:
- `jest.config.js`
- `jest.config.ts`
- `jest.config.mjs`
- `jest.config.mts`
- `jest.config.cjs`
- `jest.config.cts`
### View Inferred Tasks
To view inferred tasks for a project, open the [project details view](/concepts/inferred-tasks) in Nx Console or run `nx show project my-project --web` in the command line.
### @nx/jest Configuration
The `@nx/jest/plugin` is configured in the `plugins` array in `nx.json`.
```json {% fileName="nx.json" %}
{
"plugins": [
{
"plugin": "@nx/jest/plugin",
"options": {
"targetName": "test"
}
}
]
}
```
- The `targetName` option controls the name of the inferred Jest tasks. The default name is `test`.
{% /tab %}
{% tab label="Nx < 18" %}
Install the `@nx/jest` package with your package manager.
```shell
npm add -D @nx/jest
```
{% /tab %}
{% /tabs %}
## Using Jest
### Generate a new project set up with Jest
By default, Nx will use Jest when creating applications and libraries.
@ -12,41 +84,9 @@ By default, Nx will use Jest when creating applications and libraries.
nx g @nx/web:app frontend
```
### Adding Jest to an Existing Project
### Add Jest to a project
Add Jest to a project using the `configuration` generator from `@nx/jest`.
First, install `@nx/jest`, if not already installed using your preferred package manager.
{% callout type="note" title="Keep Nx Package Versions In Sync" %}
Make sure to install the `@nx/jest` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
{% /callout %}
{% tabs %}
{% tab label="npm" %}
```shell
npm add -D @nx/jest
```
{% /tab %}
{% tab label="yarn" %}
```shell
yarn add -D @nx/jest
```
{% /tab %}
{% tab label="pnpm" %}
```shell
pnpm add -D @nx/jest
```
{% /tab %}
{% /tabs %}
Once installed, run the `configuration` generator
Run the `configuration` generator
```shell
nx g @nx/jest:configuration --project=<project-name>
@ -56,8 +96,6 @@ nx g @nx/jest:configuration --project=<project-name>
Replacing `<project-name>` with the name of the project you're wanting to add Jest too.
## Using Jest
### Testing Applications
The recommended way to run/debug Jest tests via an editor

2
docs/generated/packages/jest/executors/jest.json
View File

@ -198,7 +198,7 @@
}
},
"required": ["jestConfig"],
"examplesFile": "Jest can be configured in many ways, but primarily you'll need to at least have the jestConfig options\n\n```json\n\"test\": {\n \"executor\": \"@nx/jest:jest\",\n \"options\": {\n \"jestConfig\": \"libs/my-lib/jest.config.ts\"\n }\n}\n```\n\nIt is also helpful to have `passWithNoTests: true` set so your project doesn't fail testing while tests are still being added.\n\n```json\n\"test\": {\n \"executor\": \"@nx/jest:jest\",\n \"options\": {\n \"jestConfig\": \"libs/my-lib/jest.config.ts\",\n \"passWithNoTests\": true\n }\n}\n```\n\n### Snapshots\n\nUpdate snapshots running with `--update-snapshot` or `-u` for short.\n\n```bash\nnx test my-project -u\n```\n\nOther times you might not want to allow updating snapshots such as in CI.\nAdding a _ci_ configuration is helpful for adding this behavior.\n\n```json\n\"test\": {\n \"executor\": \"@nx/jest:jest\",\n \"options\": {\n \"jestConfig\": \"libs/my-lib/jest.config.ts\",\n \"passWithNoTests\": true\n },\n \"configurations\": {\n \"ci\": {\n \"ci\": true\n }\n }\n}\n```\n\n```bash\nnx affected --target=test --configuration=ci\n```\n\nLearn more [about _affected_](/ci/features/affected)\n"
"examplesFile": "Jest can be configured in many ways, but primarily you'll need to at least have the jestConfig options\n\n```json\n\"test\": {\n \"executor\": \"@nx/jest:jest\",\n \"options\": {\n \"jestConfig\": \"libs/my-lib/jest.config.ts\"\n }\n}\n```\n\nIt is also helpful to have `passWithNoTests: true` set so your project doesn't fail testing while tests are still being added.\n\n```json\n\"test\": {\n \"executor\": \"@nx/jest:jest\",\n \"options\": {\n \"jestConfig\": \"libs/my-lib/jest.config.ts\",\n \"passWithNoTests\": true\n }\n}\n```\n\n### Snapshots\n\nUpdate snapshots running with `--update-snapshot` or `-u` for short.\n\n```bash\nnx test my-project -u\n```\n\nOther times you might not want to allow updating snapshots such as in CI.\nAdding a _ci_ configuration is helpful for adding this behavior.\n\n```json\n\"test\": {\n \"executor\": \"@nx/jest:jest\",\n \"options\": {\n \"jestConfig\": \"libs/my-lib/jest.config.ts\",\n \"passWithNoTests\": true\n },\n \"configurations\": {\n \"ci\": {\n \"ci\": true\n }\n }\n}\n```\n\n```bash\nnx affected --target=test\n```\n\nLearn more [about _affected_](/ci/features/affected)\n"
},
"description": "Run Jest unit tests.",
"aliases": [],

36
docs/generated/packages/js/documents/overview.md
View File

@ -1,6 +1,11 @@
---
title: Overview of the Nx JS Plugin
description: The Nx JS plugin contains executors and generators that are useful for JavaScript/TypeScript projects in an Nx workspace.
---
The JS plugin contains executors and generators that are useful for JavaScript/TypeScript projects in an Nx workspace.
## Setting Up JS
## Setting Up @nx/js
### Installation
@ -8,29 +13,26 @@ The JS plugin contains executors and generators that are useful for JavaScript/T
Make sure to install the `@nx/js` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
{% /callout %}
In any Nx workspace, you can install `@nx/js` by running the following commands if `@nx/js` package is not installed:
In any Nx workspace, you can install `@nx/js` by running the following command:
{% tabs %}
{% tab label="npm" %}
{% tab label="Nx 18+" %}
```shell
nx add @nx/js
```
This will install the correct version of `@nx/js`.
{% /tab %}
{% tab label="Nx < 18" %}
Install the `@nx/js` package with your package manager.
```shell
npm add -D @nx/js
```
{% /tab %}
{% tab label="yarn" %}
```shell
yarn add -D @nx/js
```
{% /tab %}
{% tab label="pnpm" %}
```shell
pnpm add -D @nx/js
```
{% /tab %}
{% /tabs %}

35
docs/generated/packages/nest/documents/overview.md
View File

@ -7,7 +7,9 @@ Nest.js is a framework designed for building scalable server-side applications.
Many conventions and best practices used in Angular applications can be also be used in Nest.
## Setting Up Nest
## Setting Up @nx/nest
### Generating a new workspace
To create a new workspace with Nest, run the following command:
@ -21,33 +23,32 @@ Yarn users can use the following command instead:
yarn create nx-workspace my-workspace --preset=nest
```
### Installation
{% callout type="note" title="Keep Nx Package Versions In Sync" %}
Make sure to install the `@nx/nest` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
{% /callout %}
To add the Nest plugin to an existing workspace, run one the following commands:
In any Nx workspace, you can install `@nx/nest` by running the following command:
{% tabs %}
{% tab label="npm" %}
{% tab label="Nx 18+" %}
```shell
nx add @nx/nest
```
This will install the correct version of `@nx/nest`.
{% /tab %}
{% tab label="Nx < 18" %}
Install the `@nx/nest` package with your package manager.
```shell
npm add -D @nx/nest
```
{% /tab %}
{% tab label="yarn" %}
```shell
yarn add -D @nx/nest
```
{% /tab %}
{% tab label="pnpm" %}
```shell
pnpm add -D @nx/nest
```
{% /tab %}
{% /tabs %}

122
docs/generated/packages/next/documents/overview.md
View File

@ -1,3 +1,8 @@
---
title: Overview of the Nx Next.js Plugin
description: The Nx Next.js plugin contains executors and generators for managing Next.js applications and libraries within an Nx workspace. This page also explains how to configure Next.js on your Nx workspace.
---
When using Next.js in Nx, you get the out-of-the-box support for TypeScript, Cypress, and Jest. No need to configure anything: watch mode, source maps, and typings just work.
The Next.js plugin contains executors and generators for managing Next.js applications and libraries within an Nx workspace. It provides:
@ -6,36 +11,80 @@ The Next.js plugin contains executors and generators for managing Next.js applic
- Integration with building, serving, and exporting a Next.js application.
- Integration with React libraries within the workspace.
## Setting up Next.js
## Setting up @nx/next
To create a new Nx workspace with Next.js, run `npx create-nx-workspace@latest --preset=next`.
To create a new Nx workspace with Next.js, run:
To add Next.js to an existing Nx workspace, install the `@nx/next` package. Make sure to install the version that matches your `nx` version.
```shell
npx create-nx-workspace@latest --preset=next
```
### Installation
{% callout type="note" title="Keep Nx Package Versions In Sync" %}
Make sure to install the `@nx/next` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
{% /callout %}
In any workspace, you can install `@nx/next` by running the following command:
{% tabs %}
{% tab label="npm" %}
{% tab label="Nx 18+" %}
```shell
nx add @nx/next
```
This will install the correct version of `@nx/next`.
### How @nx/next Infers Tasks
The `@nx/next` plugin will create tasks for any project that has a Next.js configuration file preset. Any of the following files will be recognized as a Next.js configuration file:
- `next.config.js`
- `next.config.cjs`
- `next.config.mjs`
### View Inferred Tasks
To view inferred tasks for a project, open the [project details view](/concepts/inferred-tasks) in Nx Console or run `nx show project <project-name> --web` in your command line.
### @nx/next Configuration
The `@nx/next/plugin` is configured in the `plugins` array in `nx.json`.
```json {% fileName="nx.json" %}
{
"plugins": [
{
"plugin": "@nx/next/plugin",
"options": {
"buildTargetName": "build",
"devTargetName": "dev",
"startTargetName": "start"
}
}
]
}
```
- The `buildTargetName` option controls the name of Next.js' compilation task which compiles the application for production deployment. The default name is `build`.
- The `devTargetName` option controls the name of Next.js' development serve task which starts the application in development mode. The default name is `dev`.
- The `startTargetName` option controls the name of Next.js' production serve task which starts the application in production mode. The default name is `start`.
{% /tab %}
{% tab label="Nx < 18" %}
Install the `@nx/next` package with your package manager.
```shell
npm add -D @nx/next
```
{% /tab %}
{% tab label="yarn" %}
```shell
yarn add -D @nx/next
```
{% /tab %}
{% tab label="pnpm" %}
```shell
pnpm add -D @nx/next
```
{% /tab %}
{% /tabs %}
## Using @nx/next
### Creating Applications
You can add a new application with the following:
@ -79,7 +128,28 @@ Nx generates components with tests by default. For pages, you can pass the `--wi
### Serving Next.js Applications
You can run `nx serve my-new-app` to serve a Next.js application called `my-new-app` for development. This will start the dev server at http://localhost:4200.
{% tabs %}
{% tab label="Nx 18+" %}
You can serve a Next.js application `my-new-app` for development:
```shell
nx dev my-new-app
```
To serve a Next.js application for production:
```shell
nx start my-new-app
```
This will start the server at <http://localhost:3000> by default.
{% /tab %}
{% tab label="Nx < 18" %}
You can run `nx serve my-new-app` to serve a Next.js application called `my-new-app` for development. This will start the dev server at <http://localhost:4200>.
To serve a Next.js application for production, add the `--prod` flag to the serve command:
@ -87,6 +157,9 @@ To serve a Next.js application for production, add the `--prod` flag to the serv
nx serve my-new-app --prod
```
{% /tab %}
{% /tabs %}
### Using an Nx Library in your Application
You can import a library called `my-new-lib` in your application as follows.
@ -165,10 +238,15 @@ The library in `dist` is publishable to npm or a private registry.
### Static HTML Export
Next.js applications can be statically exported with:
Next.js applications can be statically exported by changing th eoutput inside your Next.js configuration file.
```shell
nx export my-new-app
```js {% fileName="apps/my-next-app/next.config.js" %}
const nextConfig = {
output: 'export',
nx: {
svgr: false,
},
};
```
### Deploying Next.js Applications

35
docs/generated/packages/node/documents/overview.md
View File

@ -1,37 +1,38 @@
The Node Plugin contains generators and executors to manage Node applications within an Nx workspace. It provides:
## Setting Up Node
## Setting Up @nx/node
### Installation
{% callout type="note" title="Keep Nx Package Versions In Sync" %}
Make sure to install the `@nx/node` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
{% /callout %}
To add the Node plugin to an existing workspace, run one of the following:
In any Nx workspace, you can install `@nx/node` by running the following command:
{% tabs %}
{% tab label="npm" %}
{% tab label="Nx 18+" %}
```shell
nx add @nx/node
```
This will install the correct version of `@nx/node`.
{% /tab %}
{% tab label="Nx < 18" %}
Install the `@nx/node` package with your package manager.
```shell
npm add -D @nx/node
```
{% /tab %}
{% tab label="yarn" %}
```shell
yarn add -D @nx/node
```
{% /tab %}
{% tab label="pnpm" %}
```shell
pnpm add -D @nx/node
```
{% /tab %}
{% /tabs %}
## Using the @nx/node Plugin
### Creating Applications
You can add a new application with the following:

62
docs/generated/packages/nuxt/documents/overview.md
View File

@ -5,7 +5,7 @@ description: The Nx Plugin for Nuxt contains generators for managing Nuxt applic
The Nx plugin for [Nuxt](https://nuxt.com/).
## Setting up a new Nx workspace with Nuxt
## Setting up a new Nx workspace with @nx/nuxt
You can create a new workspace that uses Nuxt with one of the following commands:
@ -15,35 +15,57 @@ You can create a new workspace that uses Nuxt with one of the following commands
npx create-nx-workspace@latest --preset=nuxt
```
## Add Nuxt to an existing workspace
### Installation
There are a number of ways to use Nuxt in your existing workspace.
{% callout type="note" title="Keep Nx Package Versions In Sync" %}
Make sure to install the `@nx/nuxt` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
{% /callout %}
### Install the `@nx/nuxt` plugin
{% tabs %}
{% tab label="npm" %}
In any Nx workspace, you can install `@nx/nuxt` by running the following command:
```shell
npm add -D @nx/nuxt
nx add @nx/nuxt
```
{% /tab %}
{% tab label="yarn" %}
This will install the correct version of `@nx/nuxt`.
```shell
yarn add -D @nx/nuxt
### How @nx/nuxt Infers Tasks
The `@nx/nuxt` plugin will create a task for any project that has an Nuxt configuration file present. Any of the following files will be recognized as an Nuxt configuration file:
- `nuxt.config.js`
- `nuxt.config.ts`
- `nuxt.config.mjs`
- `nuxt.config.mts`
- `nuxt.config.cjs`
- `nuxt.config.cts`
### View Inferred Tasks
To view inferred tasks for a project, open the [project details view](/concepts/inferred-tasks) in Nx Console or run `nx show project my-project --web` in the command line.
### @nx/nuxt Configuration
The `@nx/nuxt/plugin` is configured in the `plugins` array in `nx.json`.
```json {% fileName="nx.json" %}
{
"plugins": [
{
"plugin": "@nx/nuxt/plugin",
"options": {
"buildTargetName": "build",
"testTargetName": "test",
"serveTargetName": "serve"
}
}
]
}
```
{% /tab %}
{% tab label="pnpm" %}
- The `buildTargetName`, `testTargetName` and `serveTargetName` options control the names of the inferred Nuxt tasks. The default names are `build`, `test` and `serve`.
```shell
pnpm add -D @nx/nuxt
```
{% /tab %}
{% /tabs %}
## Using Nuxt
### Generate a new Nuxt app

81
docs/generated/packages/playwright/documents/overview.md
View File

@ -1,3 +1,8 @@
---
title: Overview of the Nx Playwright Plugin
description: The Nx Plugin for Playwright contains executors and generators that support e2e testing with Playwright. This page also explains how to configure Playwright on your Nx workspace.
---
Playwright is a modern web test runner. With included features such as:
- Cross browser support, including mobile browsers
@ -6,31 +11,73 @@ Playwright is a modern web test runner. With included features such as:
- Test generation
- Screenshots and videos
## Setting Up Playwright
## Setting Up @nx/playwright
If the `@nx/playwright` package is not installed, install the version that matches your `nx` package version.
### Installation
{% callout type="note" title="Keep Nx Package Versions In Sync" %}
Make sure to install the `@nx/playwright` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
{% /callout %}
In any Nx workspace, you can install `@nx/playwright` by running the following command:
{% tabs %}
{% tab label="npm" %}
{% tab label="Nx 18+" %}
```shell
nx add @nx/playwright
```
This will install the correct version of `@nx/playwright`.
### How @nx/playwright Infers Tasks
The `@nx/playwright` plugin will create a task for any project that has a Playwright configuration file present. Any of the following files will be recognized as a Playwright configuration file:
- `playwright.config.js`
- `playwright.config.ts`
- `playwright.config.mjs`
- `playwright.config.mts`
- `playwright.config.cjs`
- `playwright.config.cts`
### View Inferred Tasks
To view inferred tasks for a project, open the [project details view](/concepts/inferred-tasks) in Nx Console or run `nx show project my-project --web` in the command line.
### @nx/playwright Configuration
The `@nx/playwright/plugin` is configured in the `plugins` array in `nx.json`.
```json {% fileName="nx.json" %}
{
"plugins": [
{
"plugin": "@nx/playwright/plugin",
"options": {
"ciTargetName": "e2e-ci",
"targetName": "e2e"
}
}
]
}
```
- The `targetName` and `ciTargetName` options control the namea of the inferred Playwright tasks. The default names are `e2e` and `e2e-ci`.
### Splitting E2E tasks by file
The `@nx/playwright/plugin` will automatically split your e2e tasks by file. You can read more about this feature [here](/ci/features/split-e2e-tasks).
{% /tab %}
{% tab label="Nx < 18" %}
Install the `@nx/playwright` package with your package manager.
```shell
npm add -D @nx/playwright
```
{% /tab %}
{% tab label="yarn" %}
```shell
yarn add -D @nx/playwright
```
{% /tab %}
{% tab label="pnpm" %}
```shell
pnpm add -D @nx/playwright
```
{% /tab %}
{% /tabs %}

2
docs/generated/packages/plugin/documents/overview.md
View File

@ -1,4 +1,4 @@
Nx plugins are npm packages that contain [generators](/core-features/plugin-features/use-code-generators) and [executors](/core-features/plugin-features/use-task-executors) to extend a Nx workspace.
Nx plugins are npm packages that contain [generators](/features/generate-code) and [executors](/concepts/executors-and-configurations) to extend a Nx workspace.
This package contains tooling to help plugin authors create and maintain plugins.

82
docs/generated/packages/react-native/documents/overview.md
View File

@ -10,12 +10,10 @@ The Nx Plugin for React Native contains generators for managing React Native app
### Create a New Workspace
The easiest way to create your workspace is via `npx`.
To create a new workspace with React Native, run the following command:
```shell
npx create-nx-workspace your-workspace-name \
--preset=react-native \
--appName=your-app-name
npx create-nx-workspace@latest --preset=react-native --appName=your-app-name
```
{% callout type="note" title="Don't know what you need?" %}
@ -26,38 +24,68 @@ You can also run the command without arguments to go through the interactive pro
npx create-nx-workspace your-workspace-name
```
### Adding React Native to an Existing Workspace
For existing Nx workspaces, install the `@nx/react-native` package to add React Native capabilities to it.
### Installation
{% callout type="note" title="Keep Nx Package Versions In Sync" %}
Make sure to install the `@nx/react-native` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
{% /callout %}
In any Nx workspace, you can install `@nx/react-native` by running the following command:
{% tabs %}
{% tab label="npm" %}
{% tab label="Nx 18+" %}
```shell
nx add @nx/react-native
```
This will install the correct version of `@nx/react-native`.
### How @nx/react-native Infers Tasks
The `@nx/react-native` plugin will create a task for any project that has an app configuration file present. Any of the following files will be recognized as an app configuration file:
- `app.config.js`
- `app.json`
### View Inferred Tasks
To view inferred tasks for a project, open the [project details view](/concepts/inferred-tasks) in Nx Console or run `nx show project my-project --web` in the command line.
### @nx/react-native Configuration
The `@nx/react-native/plugin` is configured in the `plugins` array in `nx.json`.
```json {% fileName="nx.json" %}
{
"plugins": [
{
"plugin": "@nx/react-native/plugin",
"options": {
"startTargetName": "start",
"podInstallTargetName": "pod-install",
"bundleTargetName": "bundle",
"runIosTargetName": "run-ios",
"runAndroidTargetName": "run-android",
"buildIosTargetName": "build-ios",
"buildAndroidTargetName": "build-android"
}
}
]
}
```
Once a React Native configuration file has been identified, the targets are created with the name you specify under `startTargetName`, `podInstallTargetName`, `bundleTargetName`, `runIosTargetName`, `runAndroidTargetname`, `buildIosTargetName` or `buildAndroidTargetName` in the `nx.json` `plugins` array. The default names for the inferred targets are `start`, `pod-install`, `bundle`, `run-ios`, `run-anroid`, `build-ios` and `build-android`.
{% /tab %}
{% tab label="Nx < 18" %}
Install the `@nx/react-native` package with your package manager.
```shell
npm add -D @nx/react-native
```
{% /tab %}
{% tab label="yarn" %}
```shell
yarn add -D @nx/react-native
```
{% /tab %}
{% tab label="pnpm" %}
```shell
pnpm add -D @nx/react-native
```
{% /tab %}
{% /tabs %}
### Generating Applications
To create additional React Native apps run:
@ -86,7 +114,7 @@ Replace `your-lib-name` with the app's name as defined in your `tsconfig.base.js
### Upgrade React Native
The Nx CLI provides the [`migrate` command](/core-features/automate-updating-dependencies) to help you stay up to date with the latest version of Nx.
The Nx CLI provides the [`migrate` command](/features/automate-updating-dependencies) to help you stay up to date with the latest version of Nx.
#### Use upgrade-native Generator
@ -139,7 +167,7 @@ The build artifacts will be located under `<your app folder>/ios/build`.
You can specify the build folder by setting the `buildFolder` option:
```shell
nx build ios <your-app-name> --buildFolder="./build"
nx build-ios <your-app-name> --buildFolder="./build"
```
### Build Android

43
docs/generated/packages/react/documents/overview.md
View File

@ -6,43 +6,46 @@ It provides:
- Library build support for publishing packages to npm or other registries.
- Utilities for automatic workspace refactoring.
## Setting Up React
## Setting Up @nx/react
### Generating a new Workspace
To create a new workspace with React, run `npx create-nx-workspace@latest --preset=react-standalone`.
{% callout type="note" title="React Tutorials" %}
For a full tutorial experience, follow the [React Standalone Tutorial](/getting-started/tutorials/react-standalone-tutorial) or the [React Monorepo Tutorial](/getting-started/tutorials/react-monorepo-tutorial)
{% /callout %}
### Installation
{% callout type="note" title="Keep Nx Package Versions In Sync" %}
Make sure to install the `@nx/react` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
{% /callout %}
To add the React plugin to an existing workspace, run one of the following:
In any Nx workspace, you can install `@nx/react` by running the following command:
{% tabs %}
{% tab label="npm" %}
{% tab label="Nx 18+" %}
```shell
nx add @nx/react
```
This will install the correct version of `@nx/react`.
{% /tab %}
{% tab label="Nx < 18" %}
Install the `@nx/react` package with your package manager.
```shell
npm add -D @nx/react
```
{% /tab %}
{% tab label="yarn" %}
```shell
yarn add -D @nx/react
```
{% /tab %}
{% tab label="pnpm" %}
```shell
pnpm add -D @nx/react
```
{% /tab %}
{% /tabs %}
{% callout type="note" title="React Tutorials" %}
For a full tutorial experience, follow the [React Standalone Tutorial](/getting-started/tutorials/react-standalone-tutorial) or the [React Monorepo Tutorial](/getting-started/tutorials/react-monorepo-tutorial)
{% /callout %}
## Using the @nx/react Plugin
### Creating Applications and Libraries

76
docs/generated/packages/remix/documents/overview.md
View File

@ -1,3 +1,8 @@
---
title: Overview of the Nx Remix Plugin
description: The Nx Plugin for Remix contains executors, generators, and utilities for managing Remix applications and libraries within an Nx workspace.
---
The Nx Plugin for Remix contains executors, generators, and utilities for managing Remix applications and libraries
within an Nx workspace. It provides:
@ -10,37 +15,68 @@ within an Nx workspace. It provides:
- Meta
- Utilities for automatic workspace refactoring.
## Setting up the Remix plugin
## Setting up @nx/remix
### Installation
{% callout type="note" title="Keep Nx Package Versions In Sync" %}
Make sure to install the `@nx/remix` version that matches the version of `nx` in your repository. If the version
numbers get out of sync, you can encounter some difficult to debug errors. You
can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
Make sure to install the `@nx/remix` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
{% /callout %}
Adding the Remix plugin to an existing Nx workspace can be done with the following:
In any Nx workspace, you can install `@nx/remix` by running the following command:
{% tabs %}
{% tab label="npm" %}
{% tab label="Nx 18+" %}
```shell
nx add @nx/remix
```
This will install the correct version of `@nx/remix`.
### How @nx/remix Infers Tasks
The `@nx/remix` plugin will create a task for any project that has a Remix configuration file present. Any of the following files will be recognized as a Remix configuration file:
- `remix.config.js`
- `remix.config.mjs`
- `remix.config.cjs`
### View Inferred Tasks
To view inferred tasks for a project, open the [project details view](/concepts/inferred-tasks) in Nx Console or run `nx show project my-project --web` in the command line.
### @nx/remix Configuration
The `@nx/remix/plugin` is configured in the `plugins` array in `nx.json`.
```json {% fileName="nx.json" %}
{
"plugins": [
{
"plugin": "@nx/remix/plugin",
"options": {
"buildTargetName": "build",
"serveTargetName": "serve",
"startTargetName": "start",
"typecheckTargetName": "typecheck"
}
}
]
}
```
- The `buildTargetName`, `serveTargetName`, `startTargetName` and `typecheckTargetName` options control the names of the inferred Remix tasks. The default names are `build`, `serve`, `start` and `typecheck`.
{% /tab %}
{% tab label="Nx < 18" %}
Install the `@nx/remix` package with your package manager.
```shell
npm add -D @nx/remix
```
{% /tab %}
{% tab label="yarn" %}
```shell
yarn add -D @nx/remix
```
{% /tab %}
{% tab label="pnpm" %}
```shell
pnpm add -D @nx/remix
```
{% /tab %}
{% /tabs %}

68
docs/generated/packages/storybook/documents/overview.md
View File

@ -9,33 +9,69 @@ This guide will briefly walk you through using Storybook within an Nx workspace.
## Setting Up Storybook
### Add the Storybook plugin
### Installation
{% callout type="note" title="Keep Nx Package Versions In Sync" %}
Make sure to install the `@nx/storybook` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
{% /callout %}
In any Nx workspace, you can install `@nx/storybook` by running the following command:
{% tabs %}
{% tab label="npm" %}
{% tab label="Nx 18+" %}
```shell
nx add @nx/storybook
```
This will install the correct version of `@nx/storybook`.
### How @nx/storybook Infers Tasks
The `@nx/storybook` plugin will create a task for any project that has a Storybook configuration file present. Any of the following files will be recognized as a Storybook configuration file:
- `.storybook/main.js`
- `.storybook/main.ts`
- `.storybook/main.cjs`
- `.storybook/main.cts`
- `.storybook/main.mjs`
- `.storybook/main.mts`
### View Inferred Tasks
To view inferred tasks for a project, open the [project details view](/concepts/inferred-tasks) in Nx Console or run `nx show project my-project --web` in the command line.
### @nx/storybook Configuration
The `@nx/storybook/plugin` is configured in the `plugins` array in `nx.json`.
```json {% fileName="nx.json" %}
{
"plugins": [
{
"plugin": "@nx/storybook/plugin",
"options": {
"buildStorybookTargetName": "build-storybook",
"serveStorybookTargetName": "storybook",
"testStorybookTargetName": "test-storybook",
"staticStorybookTargetName": "static-storybook"
}
}
]
}
```
- The `builtStorybookTargetName`, `serveStorybookTargetName`, `testStorybookTargetName` and `staticStorybookTargetName` options control the names of the inferred Storybook tasks. The default names are `build-storybook`, `storybook`, `test-storybook` and `static-storybook`.
{% /tab %}
{% tab label="Nx < 18" %}
Install the `@nx/storybook` package with your package manager.
```shell
npm add -D @nx/storybook
```
{% /tab %}
{% tab label="yarn" %}
```shell
yarn add -D @nx/storybook
```
{% /tab %}
{% tab label="pnpm" %}
```shell
pnpm add -D @nx/storybook
```
{% /tab %}
{% /tabs %}

123
docs/generated/packages/vite/documents/overview.md
View File

@ -16,7 +16,7 @@ Why should you use this plugin?
Read more about Vite and Vitest in the [Vite documentation](https://vitejs.dev/).
## Setting up a new Nx workspace with Vite
## Setting up a new Nx workspace with @nx/vite
Here's an example on how to create a new React app with Vite
@ -24,9 +24,80 @@ Here's an example on how to create a new React app with Vite
npx create-nx-workspace@latest --preset=react-standalone --bundler=vite
```
## Add Vite to an existing workspace
### Installation
There is a number of ways to use Vite in your existing workspace.
{% callout type="note" title="Keep Nx Package Versions In Sync" %}
Make sure to install the `@nx/vite` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
{% /callout %}
In any Nx workspace, you can install `@nx/vite` by running the following command:
{% tabs %}
{% tab label="Nx 18+" %}
```shell
nx add @nx/vite
```
This will install the correct version of `@nx/vite`.
### How @nx/vite Infers Tasks
The `@nx/vite` plugin will create a task for any project that has a Vite configuration file present. Any of the following files will be recognized as a Vite configuration file:
- `vite.config.js`
- `vite.config.ts`
- `vite.config.mjs`
- `vite.config.mts`
- `vite.config.cjs`
- `vite.config.cts`
- `vitest.config.js`
- `vitest.config.ts`
- `vitest.config.mjs`
- `vitest.config.mts`
- `vitest.config.cjs`
- `vitest.config.cts`
### View Inferred Tasks
To view inferred tasks for a project, open the [project details view](/concepts/inferred-tasks) in Nx Console or run `nx show project my-project --web` in the command line.
### @nx/vite Configuration
The `@nx/vite/plugin` is configured in the `plugins` array in `nx.json`.
```json {% fileName="nx.json" %}
{
"plugins": [
{
"plugin": "@nx/vite/plugin",
"options": {
"buildTargetName": "build",
"previewTargetName": "preview",
"testTargetName": "test",
"serveTargetName": "serve",
"serveStaticTargetName": "serve-static"
}
}
]
}
```
- The `buildTargetName`, `previewTargetName`, `testTargetName`, `serveTargetName` and `serveStaticTargetName` options control the names of the inferred Vite tasks. The default names are `build`, `preview`, `test`, `serve` and `serve-static`.
{% /tab %}
{% tab label="Nx < 18" %}
Install the `@nx/vite` package with your package manager.
```shell
npm add -D @nx/vite
```
{% /tab %}
{% /tabs %}
## Using @nx/vite
### Generate a new project using Vite
@ -55,49 +126,3 @@ nx g @nx/web:app my-app --bundler=vite
You can use the `@nx/vite:configuration` generator to change your React or Web project to use Vite.js. This generator will modify your project's configuration to use Vite.js, and it will also install all the necessary dependencies, including the `@nx/vite` plugin..
You can read more about this generator on the [`@nx/vite:configuration`](/nx-api/vite/generators/configuration) generator page.
### Initialize Vite
If you do not want to create any new projects or convert any existing projects yet, you can still use Nx to install all the necessary dependencies for Vite.js. This, for example, could be useful if you want to set up Vite.js manually for a project.
#### Install the `@nx/vite` plugin
{% callout type="note" title="Keep Nx Package Versions In Sync" %}
Make sure to install the `@nx/vite` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
{% /callout %}
{% tabs %}
{% tab label="npm" %}
```shell
npm add -D @nx/vite
```
{% /tab %}
{% tab label="yarn" %}
```shell
yarn add -D @nx/vite
```
{% /tab %}
{% tab label="pnpm" %}
```shell
pnpm add -D @nx/vite
```
{% /tab %}
{% /tabs %}
#### Ask Nx to install the necessary dependencies
After you install the plugin, you can automatically initialize the project with Vite using an Nx generator:
```bash
nx g @nx/vite:init
```
{% callout type="note" title="Choosing a framework" %}
You will notice that the generator will ask you of the framework you are planning to use. This is just to make sure that the right dependencies are installed. You can always install manually any other dependencies you need.
{% /callout %}

47
docs/generated/packages/vue/documents/overview.md
View File

@ -5,50 +5,47 @@ description: The Nx Plugin for Vue contains generators for managing Vue applicat
The Nx plugin for [Vue](https://vuejs.org/).
## Setting up a new Nx workspace with Vue
## Setting Up @nx/vue
You can create a new workspace that uses Vue with one of the following commands:
### Generating a new Workspace
- Generate a new monorepo with a Vue app set up with Vue
```shell
npx create-nx-workspace@latest --preset=vue
```
To create a new workspace with React, run `npx create-nx-workspace@latest --preset=vue`.
{% callout type="note" title="Vue Standalone Tutorial" %}
For a full tutorial experience, follow the [Vue Standalone Tutorial](/getting-started/tutorials/vue-standalone-tutorial)
{% /callout %}
## Add Vue to an existing workspace
### Installation
There are a number of ways to use Vue in your existing workspace.
{% callout type="note" title="Keep Nx Package Versions In Sync" %}
Make sure to install the `@nx/vue` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
{% /callout %}
### Install the `@nx/vue` plugin
In any Nx workspace, you can install `@nx/vue` by running the following command:
{% tabs %}
{% tab label="npm" %}
{% tab label="Nx 18+" %}
```shell
nx add @nx/vue
```
This will install the correct version of `@nx/vue`.
{% /tab %}
{% tab label="Nx < 18" %}
Install the `@nx/vue` package with your package manager.
```shell
npm add -D @nx/vue
```
{% /tab %}
{% tab label="yarn" %}
```shell
yarn add -D @nx/vue
```
{% /tab %}
{% tab label="pnpm" %}
```shell
pnpm add -D @nx/vue
```
{% /tab %}
{% /tabs %}
## Using the @nx/vue Plugin
### Generate a new project using Vue
To generate a Vue application, run the following:

39
docs/generated/packages/web/documents/overview.md
View File

@ -4,40 +4,43 @@ The Nx Plugin for Web Components contains generators for managing Web Component
- Scaffolding for creating buildable libraries that can be published to npm.
- Utilities for automatic workspace refactoring.
## Setting Up Web
## Setting Up @nx/web
To create a new workspace with web, run `npx create-nx-workspace@latest --preset=web-components`.
### Generating a new Workspace
To create a new workspace with React, run `npx create-nx-workspace@latest --preset=web-components`.
### Installation
{% callout type="note" title="Keep Nx Package Versions In Sync" %}
Make sure to install the `@nx/web` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
{% /callout %}
To add the web plugin to an existing workspace, run one of the following:
In any Nx workspace, you can install `@nx/web` by running the following command:
{% tabs %}
{% tab label="npm" %}
{% tab label="Nx 18+" %}
```shell
nx add @nx/web
```
This will install the correct version of `@nx/web`.
{% /tab %}
{% tab label="Nx < 18" %}
Install the `@nx/web` package with your package manager.
```shell
npm add -D @nx/web
```
{% /tab %}
{% tab label="yarn" %}
```shell
yarn add -D @nx/web
```
{% /tab %}
{% tab label="pnpm" %}
```shell
pnpm add -D @nx/web
```
{% /tab %}
{% /tabs %}
## Using the @nx/web Plugin
### Creating Applications
You can add a new application with the following:

66
docs/generated/packages/webpack/documents/overview.md
View File

@ -25,6 +25,72 @@ npx create-nx-workspace@latest --preset=react-standalone --bundler=webpack
npx create-nx-workspace@latest --preset=react-monorepo --bundler=webpack
```
### Installation
{% callout type="note" title="Keep Nx Package Versions In Sync" %}
Make sure to install the `@nx/webpack` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
{% /callout %}
In any Nx workspace, you can install `@nx/webpack` by running the following command:
{% tabs %}
{% tab label="Nx 18+" %}
```shell
nx add @nx/webpack
```
This will install the correct version of `@nx/webpack`.
### How @nx/webpack Infers Tasks
The `@nx/webpack` plugin will create a task for any project that has a Webpack configuration file present. Any of the following files will be recognized as a Webpack configuration file:
- `webpack.config.js`
- `webpack.config.ts`
- `webpack.config.mjs`
- `webpack.config.mts`
- `webpack.config.cjs`
- `webpack.config.cts`
### View Inferred Tasks
To view inferred tasks for a project, open the [project details view](/concepts/inferred-tasks) in Nx Console or run `nx show project my-project --web` in the command line.
### @nx/webpack Configuration
The `@nx/webpack/plugin` is configured in the `plugins` array in `nx.json`.
```json {% fileName="nx.json" %}
{
"plugins": [
{
"plugin": "@nx/webpack/plugin",
"options": {
"buildTargetName": "build",
"previewTargetName": "preview",
"serveTargetName": "serve",
"serveStaticTargetName": "serve-static"
}
}
]
}
```
- The `buildTargetName`, `previewTargetName`, `serveTargetName` and `serveStaticTargetName` options control the names of the inferred Webpack tasks. The default names are `build`, `preview`, `serve` and `serve-static`.
{% /tab %}
{% tab label="Nx < 18" %}
Install the `@nx/webpack` package with your package manager.
```shell
npm add -D @nx/webpack
```
{% /tab %}
{% /tabs %}
## Generate a new project using Webpack
You can generate a [React](/nx-api/react) application or a [Web](/nx-api/web) application that uses Webpack in an existing Nx workspace. The [`@nx/react:app`](/nx-api/react/generators/application), [`@nx/node:app`](/nx-api/node/generators/application) and [`@nx/web:app`](/nx-api/web/generators/application) generators accept the `bundler` option, where you can pass `webpack`. This will generate a new application configured to use Webpack, and it will also install all the necessary dependencies, including the `@nx/webpack` plugin.

348
docs/map.json
View File

@ -67,11 +67,6 @@
"name": "Vue Standalone",
"id": "vue-standalone-tutorial",
"file": "shared/vue-standalone-tutorial/vue-standalone"
},
{
"name": "Node Standalone",
"id": "node-server-tutorial",
"file": "shared/node-server-tutorial/1-code-generation"
}
]
}
@ -115,77 +110,8 @@
]
},
{
"name": "Angular Standalone Tutorial",
"id": "angular-standalone-tutorial",
"description": "Learn to use Nx with this Angular tutorial where you will learn about all its main feature with a real project.",
"itemList": [
{
"name": "1 - Code Generation",
"id": "1-code-generation",
"file": "shared/angular-standalone-tutorial/1-code-generation"
},
{
"name": "2 - Project Graph",
"id": "2-project-graph",
"file": "shared/angular-standalone-tutorial/2-project-graph"
},
{
"name": "3 - Task Running",
"id": "3-task-running",
"file": "shared/angular-standalone-tutorial/3-task-running"
},
{
"name": "4 - Task Pipelines",
"id": "4-task-pipelines",
"file": "shared/angular-standalone-tutorial/4-task-pipelines"
},
{
"name": "5 - Summary",
"id": "5-summary",
"file": "shared/angular-standalone-tutorial/5-summary"
}
]
},
{
"name": "Node Server Tutorial",
"id": "node-server-tutorial",
"description": "Learn to use Nx with this Node Server Tutorial where you will learn about all its main feature with a real project.",
"itemList": [
{
"name": "1 - Code Generation",
"id": "1-code-generation",
"file": "shared/node-server-tutorial/1-code-generation"
},
{
"name": "2 - Project Graph",
"id": "2-project-graph",
"file": "shared/node-server-tutorial/2-project-graph"
},
{
"name": "3 - Task Running",
"id": "3-task-running",
"file": "shared/node-server-tutorial/3-task-running"
},
{
"name": "4 - Task Pipelines",
"id": "4-task-pipelines",
"file": "shared/node-server-tutorial/4-task-pipelines"
},
{
"name": "5 - Docker Target",
"id": "5-docker-target",
"file": "shared/node-server-tutorial/5-docker-target"
},
{
"name": "6 - Summary",
"id": "6-summary",
"file": "shared/node-server-tutorial/6-summary"
}
]
},
{
"name": "Core Features",
"id": "core-features",
"name": "Features",
"id": "features",
"description": "Learn the core features of Nx with in depth guides.",
"itemList": [
{
@ -193,80 +119,111 @@
"description": "Learn about the various ways you can use Nx to run tasks in your workspace.",
"tags": ["run-tasks", "cache-task-results"],
"id": "run-tasks",
"file": "shared/core-features/run-tasks"
"file": "shared/features/run-tasks"
},
{
"name": "Cache Task Results",
"description": "Learn how to define cacheable tasks, how to fine-tune with inputs and outputs, where the cache is stored and much more.",
"id": "cache-task-results",
"tags": ["cache-task-results"],
"file": "shared/core-features/cache-task-results"
"file": "shared/features/cache-task-results"
},
{
"name": "Use Remote Caching",
"id": "remote-cache",
"file": "",
"path": "/ci/features/remote-cache",
"isExternal": true
},
{
"name": "Distribute Task Execution",
"id": "distribute-task-execution",
"file": "",
"path": "/ci/features/distribute-task-execution",
"isExternal": true
},
{
"name": "Explore the Graph",
"name": "Explore your Workspace",
"id": "explore-graph",
"description": "Nx uses a graph behind the scenes to optimize your operations. You can also visualize and use the graph to better understand your workspace structure. Learn more in this guide.",
"tags": ["explore-graph"],
"file": "shared/core-features/explore-graph"
"file": "shared/features/explore-graph"
},
{
"name": "Generate Code",
"id": "generate-code",
"tags": ["generate-code"],
"file": "shared/features/generate-code"
},
{
"name": "Automate Updating Dependencies",
"description": "Learn how Nx provides automated update scripts to help you keep your workspace, tooling and framework dependencies up to date.",
"id": "automate-updating-dependencies",
"tags": ["automate-updating-dependencies"],
"file": "shared/core-features/automate-updating-dependencies"
"file": "shared/features/automate-updating-dependencies"
},
{
"name": "Enforce Module Boundaries",
"description": "Learn how to avoid dependency hell and scale a codebase by imposing constraints on your projects using the module boundary lint rule.",
"id": "enforce-module-boundaries",
"tags": ["enforce-module-boundaries"],
"file": "shared/core-features/enforce-module-boundaries"
"file": "shared/features/enforce-module-boundaries"
},
{
"name": "Integrate with Editors",
"description": "Learn about Nx Console, an extension for VS Code and WebStorm.",
"id": "integrate-with-editors",
"tags": ["integrate-with-editors"],
"file": "shared/core-features/integrate-with-editors"
"file": "shared/features/integrate-with-editors"
},
{
"name": "Manage Releases",
"description": "Learn how Nx provides tools to help you manage releasing your projects.",
"id": "manage-releases",
"tags": ["manage-releases"],
"file": "shared/core-features/manage-releases"
"file": "shared/features/manage-releases"
},
{
"name": "Plugin Features",
"id": "plugin-features",
"description": "Learn what is a plugin, the different type of plugins and how to create one.",
"name": "CI Features",
"id": "ci-features",
"description": "Features of Nx and Nx Cloud that improve CI",
"itemList": [
{
"name": "Use Task Executors",
"id": "use-task-executors",
"tags": ["use-task-executors"],
"file": "shared/plugin-features/use-task-executors"
"name": "Run Only Tasks Affected by a PR",
"id": "affected",
"file": "",
"path": "/ci/features/affected",
"isExternal": true
},
{
"name": "Use Code Generators",
"id": "use-code-generators",
"tags": ["use-code-generators"],
"file": "shared/plugin-features/use-code-generators"
"name": "Use Remote Caching (Nx Replay)",
"description": "Learn how to enable remote caching s.t. you don't just benefit locally from it but also in CI.",
"id": "remote-cache",
"file": "",
"path": "/ci/features/remote-cache",
"isExternal": true
},
{
"name": "Distribute Task Execution (Nx Agents)",
"description": "Learn how to efficiently distribute tasks across machines to take full advantage of parallelization. Nx Agents make this a trivial task.",
"id": "distribute-task-execution",
"file": "",
"path": "/ci/features/distribute-task-execution",
"isExternal": true
},
{
"name": "Dynamically Allocate Agents",
"id": "dynamic-agents",
"file": "",
"path": "/ci/features/dynamic-agents",
"isExternal": true
},
{
"name": "Automatically Split E2E Tasks",
"id": "split-e2e-tasks",
"file": "",
"path": "/ci/features/split-e2e-tasks",
"isExternal": true
},
{
"name": "Identify and Re-run Flaky Tasks",
"id": "flaky-tasks",
"file": "",
"path": "/ci/features/flaky-tasks",
"isExternal": true
},
{
"name": "Set up Nx Cloud On-Premise",
"id": "on-premise",
"description": "Set up Nx Cloud on machines that you control",
"file": "",
"path": "/ci/features/on-premise",
"isExternal": true
}
]
}
@ -289,6 +246,24 @@
"id": "how-caching-works",
"file": "shared/concepts/how-caching-works"
},
{
"name": "What is a Task Pipeline",
"tags": ["run-tasks"],
"id": "task-pipeline-configuration",
"file": "shared/concepts/task-pipeline-configuration"
},
{
"name": "What Are Nx Plugins",
"tags": ["generate-code", "create-your-own-plugin"],
"id": "nx-plugins",
"file": "shared/concepts/nx-plugins"
},
{
"name": "Inferred Tasks",
"tags": ["inferred-tasks"],
"id": "inferred-tasks",
"file": "shared/concepts/inferred-tasks"
},
{
"name": "Types of Configuration",
"tags": [],
@ -296,10 +271,10 @@
"file": "shared/concepts/types-of-configuration"
},
{
"name": "What is a Task Pipeline",
"tags": ["run-tasks", "use-task-executors"],
"id": "task-pipeline-configuration",
"file": "shared/concepts/task-pipeline-configuration"
"name": "Executors and Configurations",
"id": "executors-and-configurations",
"tags": ["run-tasks"],
"file": "shared/recipes/running-tasks/executors-and-configurations"
},
{
"name": "Integrated Repos vs. Package-Based Repos vs. Standalone Apps",
@ -321,12 +296,7 @@
{
"name": "Faster Builds with Module Federation",
"id": "faster-builds-with-module-federation",
"tags": [
"use-task-executors",
"module-federation",
"angular",
"react"
],
"tags": ["module-federation", "angular", "react"],
"file": "shared/guides/module-federation/faster-builds"
},
{
@ -349,7 +319,7 @@
{
"name": "Incremental Builds",
"id": "incremental-builds",
"tags": ["use-task-executors"],
"tags": [],
"file": "shared/incremental-builds"
},
{
@ -382,7 +352,7 @@
{
"name": "Using Nx at Enterprises",
"id": "monorepo-nx-enterprise",
"tags": ["enforce-module-boundaries", "use-code-generators"],
"tags": ["enforce-module-boundaries", "generate-code"],
"file": "shared/monorepo-nx-enterprise"
},
{
@ -456,13 +426,19 @@
"description": "A series of recipes that show how to run tasks efficiently with Nx",
"itemList": [
{
"name": "Fine-tuning Caching with Inputs",
"id": "customizing-inputs",
"name": "Configure Inputs for Task Caching",
"id": "configure-inputs",
"tags": ["run-tasks", "cache-task-results"],
"file": "shared/recipes/running-tasks/customizing-inputs"
"file": "shared/recipes/running-tasks/configure-inputs"
},
{
"name": "Defining a Task Pipeline",
"name": "Configure Outputs for Task Caching",
"id": "configure-outputs",
"tags": ["run-tasks", "cache-task-results"],
"file": "shared/recipes/running-tasks/configure-outputs"
},
{
"name": "Define a Task Pipeline",
"id": "defining-task-pipeline",
"tags": ["run-tasks"],
"file": "shared/recipes/running-tasks/defining-task-pipeline"
@ -473,9 +449,9 @@
"file": "shared/recipes/running-tasks/change-cache-location"
},
{
"name": "Running Custom Commands",
"name": "Run Custom Commands",
"id": "run-commands-executor",
"tags": ["run-tasks", "use-task-executors"],
"tags": ["run-tasks"],
"file": "shared/recipes/running-tasks/running-custom-commands"
},
{
@ -524,11 +500,6 @@
"id": "adding-to-existing-project",
"file": "shared/migration/adding-to-existing-project"
},
{
"name": "Nx and Lerna",
"id": "lerna-and-nx",
"file": "shared/migration/lerna-and-nx"
},
{
"name": "Preserving Git Histories",
"id": "preserving-git-histories",
@ -585,7 +556,7 @@
{
"name": "Setup Module Federation with SSR for React",
"id": "module-federation-with-ssr",
"tags": ["use-task-executors", "module-federation", "react"],
"tags": ["module-federation", "react"],
"file": "shared/recipes/module-federation-with-ssr"
},
{
@ -640,21 +611,13 @@
{
"name": "Setup Module Federation with SSR for Angular",
"id": "module-federation-with-ssr",
"tags": [
"use-task-executors",
"module-federation",
"angular"
],
"tags": ["module-federation", "angular"],
"file": "shared/recipes/module-federation-with-ssr"
},
{
"name": "Advanced Micro Frontends with Angular using Dynamic Federation",
"id": "dynamic-module-federation-with-angular",
"tags": [
"use-task-executors",
"module-federation",
"angular"
],
"tags": ["module-federation", "angular"],
"file": "shared/guides/module-federation/dynamic-mfe-angular"
},
{
@ -882,7 +845,7 @@
"itemList": [
{
"id": "webpack-config-setup",
"name": "How to configure webpack on your Nx workspace",
"name": "How to configure Webpack in your Nx workspace",
"description": "A guide on how to configure webpack on your Nx workspace, and instructions on how to customize your webpack configuration",
"file": "shared/packages/webpack/webpack-config-setup"
},
@ -1109,7 +1072,7 @@
{
"name": "Profiling Build Performance",
"id": "performance-profiling",
"tags": ["use-task-executors", "environment-variables"],
"tags": ["environment-variables"],
"file": "shared/guides/performance-profiling"
}
]
@ -1359,9 +1322,15 @@
{
"name": "Project Configuration",
"id": "project-configuration",
"tags": ["use-task-executors"],
"tags": [],
"file": "shared/reference/project-configuration"
},
{
"name": "Inputs and Named Inputs",
"id": "inputs",
"tags": ["cache-task-results"],
"file": "shared/reference/inputs"
},
{
"name": ".nxignore",
"id": "nxignore",
@ -1422,6 +1391,16 @@
"id": "runtime-cache-inputs",
"file": "shared/deprecated/runtime-cache-inputs"
},
{
"name": "cacheableOperations",
"id": "cacheable-operations",
"file": "shared/deprecated/cacheable-operations"
},
{
"name": "npmScope",
"id": "npm-scope",
"file": "shared/deprecated/npm-scope"
},
{
"name": "globalImplicitDependencies",
"id": "global-implicit-dependencies",
@ -1539,7 +1518,7 @@
"name": "nx.json generator defaults",
"id": "nxjson-generator-defaults",
"file": "",
"tags": ["use-code-generators"],
"tags": ["generate-code"],
"path": "/reference/nx-json#generators",
"isExternal": true
},
@ -1596,43 +1575,43 @@
{
"name": "Write a Simple Executor",
"id": "local-executors",
"tags": ["use-task-executors"],
"tags": [],
"file": "shared/recipes/plugins/local-executors"
},
{
"name": "Compose Executors",
"id": "compose-executors",
"tags": ["use-task-executors"],
"tags": [],
"file": "shared/recipes/plugins/compose-executors"
},
{
"name": "Write a Simple Generator",
"id": "local-generators",
"tags": ["use-code-generators"],
"tags": ["generate-code"],
"file": "shared/recipes/generators/local-generators"
},
{
"name": "Compose Generators",
"id": "composing-generators",
"tags": ["use-code-generators"],
"tags": ["generate-code"],
"file": "shared/recipes/generators/composing-generators"
},
{
"name": "Provide Options for Generators",
"id": "generator-options",
"tags": ["use-code-generators"],
"tags": ["generate-code"],
"file": "shared/recipes/generators/generator-options"
},
{
"name": "Create Files",
"id": "creating-files",
"tags": ["use-code-generators"],
"tags": ["generate-code"],
"file": "shared/recipes/generators/creating-files"
},
{
"name": "Modify Files",
"id": "modifying-files",
"tags": ["use-code-generators"],
"tags": ["generate-code"],
"file": "shared/recipes/generators/modifying-files"
},
{
@ -1702,13 +1681,6 @@
"id": "features",
"description": "Features of Nx and Nx Cloud that improve CI",
"itemList": [
{
"name": "Use Remote Caching",
"description": "Learn how to enable remote caching s.t. you don't just benefit locally from it but also in CI.",
"id": "remote-cache",
"tags": ["remote-cache"],
"file": "shared/core-features/remote-cache"
},
{
"name": "Run Only Tasks Affected by a PR",
"tags": ["run-tasks"],
@ -1716,11 +1688,32 @@
"file": "shared/using-nx/affected"
},
{
"name": "Distribute Task Execution",
"description": "Learn how to efficiently distribute tasks across machines to take full advantage of parallelization. Nx Cloud has a built-in DTE mechanism which makes this a trivial task.",
"name": "Use Remote Caching (Nx Replay)",
"description": "Learn how to enable remote caching s.t. you don't just benefit locally from it but also in CI.",
"id": "remote-cache",
"tags": ["remote-cache"],
"file": "shared/features/remote-cache"
},
{
"name": "Distribute Task Execution (Nx Agents)",
"id": "distribute-task-execution",
"tags": ["distribute-task-execution"],
"file": "shared/core-features/distribute-task-execution"
"description": "Learn how to efficiently distribute tasks across machines to take full advantage of parallelization. Nx Agents make this a trivial task.",
"file": "shared/features/distribute-task-execution"
},
{
"name": "Dynamically Allocate Agents",
"id": "dynamic-agents",
"file": "nx-cloud/features/dynamic-agents"
},
{
"name": "Automatically Split E2E Tasks",
"id": "split-e2e-tasks",
"file": "nx-cloud/features/split-e2e-tasks"
},
{
"name": "Identify and Re-run Flaky Tasks",
"id": "flaky-tasks",
"file": "nx-cloud/features/flaky-tasks"
},
{
"name": "Set up Nx Cloud On-Premise",
@ -1728,11 +1721,6 @@
"id": "on-premise",
"tags": ["on-premise"],
"file": "nx-cloud/private/nx-enterprise-on-prem"
},
{
"name": "Nx Agents",
"id": "nx-agents",
"file": "nx-cloud/intro/nx-agents"
}
]
},
@ -1777,6 +1765,11 @@
"description": "Learn how to set up Nx Cloud for your workspace.",
"tags": ["distribute-task-execution"],
"itemList": [
{
"name": "Connect Nx Cloud",
"id": "connect-to-cloud",
"file": "nx-cloud/recipes/connect-to-cloud"
},
{
"name": "Setting up Azure Pipelines",
"id": "monorepo-ci-azure",
@ -1935,6 +1928,11 @@
"id": "nx-cloud-cli",
"file": "nx-cloud/reference/nx-cloud-cli"
},
{
"name": "Launch Templates",
"id": "launch-templates",
"file": "nx-cloud/reference/launch-templates"
},
{
"name": "Environment Variables",
"id": "env-vars",
@ -1984,12 +1982,12 @@
{
"name": "generate",
"id": "generate",
"tags": ["use-code-generators"],
"tags": ["generate-code"],
"file": "generated/cli/generate"
},
{
"name": "run",
"tags": ["run-tasks", "use-task-executors"],
"tags": ["run-tasks"],
"id": "run",
"file": "generated/cli/run"
},
@ -2006,13 +2004,13 @@
},
{
"name": "run-many",
"tags": ["run-tasks", "use-task-executors"],
"tags": ["run-tasks"],
"id": "run-many",
"file": "generated/cli/run-many"
},
{
"name": "affected",
"tags": ["run-tasks", "use-task-executors"],
"tags": ["run-tasks"],
"id": "affected",
"file": "generated/cli/affected"
},

10
docs/nx-cloud/concepts/building-blocks-fast-ci.md
View File

@ -6,7 +6,7 @@ Nx has many features that make your CI faster. Each of these features speeds up
The purpose of a CI pipeline is to run tasks like `build`, `test`, `lint` and `e2e`. You use different tools to run these tasks (like Webpack or Vite for you `build` task). If the individual tasks in your CI pipeline are slow, then your overall CI pipeline will be slow. Nx has two ways to help with this.
Nx provides plugins for popular tools that make it easy to update to the latest version of that tool and [automatically updates](/core-features/automate-updating-dependencies) your configuration files to take advantage of enhancements in the tool. The tool authors are always looking for ways to improve their product and the best way to get the most out of the tool you're using is to make sure you're on the latest version. Also, the recommended configuration settings for a tool will change over time so even if you're on the latest version of a tool, you may be using a slower version of it because you don't know about a new configuration setting. [`nx migrate`](/core-features/automate-updating-dependencies) will automatically change the default settings of in your tooling config to use the latest recommended settings so that your repo won't be left behind.
Nx provides plugins for popular tools that make it easy to update to the latest version of that tool and [automatically updates](/features/automate-updating-dependencies) your configuration files to take advantage of enhancements in the tool. The tool authors are always looking for ways to improve their product and the best way to get the most out of the tool you're using is to make sure you're on the latest version. Also, the recommended configuration settings for a tool will change over time so even if you're on the latest version of a tool, you may be using a slower version of it because you don't know about a new configuration setting. [`nx migrate`](/features/automate-updating-dependencies) will automatically change the default settings of in your tooling config to use the latest recommended settings so that your repo won't be left behind.
Because Nx plugins have a consistent interface for how they are invoked and how they interact with the codebase, it is easier to try out a different tool to see if it is better than what you're currently using. Newer tools that were created with different technologies or different design decisions can be orders of magnitude faster than your existing tools. Or the new tool might not help your project. Browse through the [list of Nx plugins](/plugin-registry), like [vite](/nx-api/vite) or [rspack](/nx-api/rspack), and try it out on your project with the default settings already configured for you.
@ -25,11 +25,3 @@ Every time you use Nx to run a task, Nx will attempt to run the task and all its
There's a limit to how many tasks can be run in parallel on the same machine, but the logic that Nx uses to assign tasks to parallel processes can also be used by Nx Cloud to efficiently [distribute tasks across multiple agent machines](/ci/features/distribute-task-execution). Once those tasks are run, the [remote cache](/ci/features/remote-cache) is used to replay those task results on the main machine. After the pipeline is finished, it looks like all the tasks were run on a single machine - but much faster than a single machine could do it.
For a detailed analysis of different strategies for running tasks concurrently, read the [Parallelization and Distribution guide](/ci/concepts/parallelization-distribution)
## More CI Performance Features Coming Soon
The Nx team is continuing to push the limits of how fast CI can be.
Soon, you'll be able to use [Nx Agents](/ci/features/nx-agents) to have Nx Cloud spin up agents for you based on how large your PR is. [Nx Agents](/ci/features/nx-agents) will also allow you to automatically identify and re-run flaky tests in their own agent. Later, Nx Workflows will enable you to use Nx Cloud directly as your CI provider, which will open up the possibility for more optimizations.
{% call-to-action title="Sign Up for Early Access" icon="nxcloud" description="Experience Nx Cloud Agents for yourself" url="https://cloud.nx.app/workflows-early-access" /%}

2
docs/nx-cloud/concepts/cache-security.md
View File

@ -36,7 +36,7 @@ When an employee leaves a company, it is standard practice to change all the pas
### Skip the Cache When Creating a Deployment Artifact
In order to guarantee that cache poisoning will never affect your end users, [skip the cache](/core-features/cache-task-results#turn-off-or-skip-the-cache) when creating build artifacts that will actually be deployed. Skipping the cache for this one CI run is a very small performance cost, but it gives you 100% confidence that cache poisoning will not be an issue for the end users.
In order to guarantee that cache poisoning will never affect your end users, [skip the cache](/features/cache-task-results#turn-off-or-skip-the-cache) when creating build artifacts that will actually be deployed. Skipping the cache for this one CI run is a very small performance cost, but it gives you 100% confidence that cache poisoning will not be an issue for the end users.
### Do Not Manually Share Your Local Cache

37
docs/nx-cloud/concepts/parallelization-distribution.md
View File

@ -70,47 +70,34 @@ It is possible in a smaller repository to manually calculate the best order for
| Debuggability | ⛔️ Con | Build artifacts and logs are scattered across agent machines. |
| Speed | 🎉 Pro | Faster than using a single machine |
### Nx Cloud Distributed Task Execution
### Distributed Task Execution Using Nx Agents
When you use Nx Cloud's distributed task execution you gain even more speed than manual distribution while preserving the simple set up and easy debuggability of the single machine scenario.
When you use **Nx Agents** (feature of Nx Cloud) you gain even more speed than manual distribution while preserving the simple set up and easy debuggability of the single machine scenario.
The setup looks like this:
```yaml {% fileName="main-job.yml" %}
# Coordinate the agents to run the tasks and stop agents when the build tasks are done
- npx nx-cloud start-ci-run --stop-agents-after=build
- npx nx-cloud start-ci-run --distribute-on="8 linux-medium-js" --stop-agents-after=build
# Run any commands you want here
- nx affected -t lint,test,build
- nx affected -t lint test build
```
```yaml {% fileName="agent.yml" %}
# Wait for tasks to execute
- npx nx-cloud start-agent
```
The visualization for distributed task execution looks like this:
![CI using DTE](/shared/images/dte/3agents.svg)
The visualization looks like this:
![CI using Agents](/shared/images/dte/3agents.svg)
In the same way that Nx efficiently assigns tasks to parallel processes on a single machine so that pre-requisite tasks are executed first, Nx Cloud's distributed task execution efficiently assigns tasks to agent machines so that the idle time of each agent machine is kept to a minimum. Nx performs these calculations for each PR, so no matter which projects are affected or how your project structure changes, Nx will optimally assign tasks to the agents available.
As your repository grows and CI runs start to slow down, add another agent machine to your pipeline and Nx Cloud will use that extra capacity to handle the larger volume of tasks. If you would like Nx Cloud to automatically provision the agents for you, check out [Nx Agents](/ci/features/nx-agents).
#### Pros and Cons of Using Nx Cloud's Distributed Task Execution:
| Characteristic | Pro/Con | Notes |
| -------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Complexity | 🎉 Pro | The pipeline uses the same commands a developer would use on their local machine, but with one extra line before running tasks and a single line for each agent to execute. |
| Debuggability | 🎉 Pro | Build artifacts and logs are collated to the main machine as if all tasks were executed on that machine |
| Speed | 🎉 Pro | Fastest possible task distribution for each PR |
### Nx Cloud Concurrency Limits
As you scale your usage of Nx Cloud, you may run into concurrency limits. Nx Cloud puts a [limit on the number of CI machines](https://nx.app/pricing) in your workspace that are simultaneously connecting to Nx Cloud. This includes any machine running in CI - both the main CI pipeline machine and any agent machines.
The Free plan offers 30 concurrent connections, the Startup plan offers 50 concurrent connections, the Pro plan offers 70 concurrent connections and the enterprise plan has no limit on concurrent connections. If each pipeline uses 9 agents in addition to the main job, that makes 10 concurrent connections for each PR. This would mean that on a Pro plan, you can have a maximum of 7 PRs running in CI simultaneously. If an eighth PR was submitted while those 7 were still running, your CI pipeline would experience some degradation and eventually failed CI runs. Once your organization's usage goes below the limit, Nx Cloud will resume functioning as normal.
| Characteristic | Pro/Con | Notes |
| -------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------- |
| Complexity | 🎉 Pro | The pipeline uses the same commands a developer would use on their local machine, but with one extra line before running tasks. |
| Debuggability | 🎉 Pro | Build artifacts and logs are collated to the main machine as if all tasks were executed on that machine |
| Speed | 🎉 Pro | Fastest possible task distribution for each PR |
## Conclusion
If your repo is starting to grow large enough that CI times are suffering, or if your parallelization strategy is growing too complex to manage effectively, try [setting up Nx Cloud with Distributed Task Execution](/ci/features/distribute-task-execution). You can [generate a simple workflow](/nx-api/workspace/generators/ci-workflow) for common CI providers with a `nx g ci-workflow` or follow one of the [CI setup recipes](/ci/recipes/set-up).
If your repo is starting to grow large enough that CI times are suffering, or if your parallelization strategy is growing too complex to manage effectively, try [setting up Nx Agents](/ci/features/distribute-task-execution). You can [generate a simple workflow](/nx-api/workspace/generators/ci-workflow) for common CI providers with a `nx g ci-workflow` or follow one of the [CI setup recipes](/ci/recipes/set-up).
Organizations that want extra help setting up Nx Cloud or getting the most out of Nx can [sign up for Nx Enterprise](https://nx.app/enterprise/). This package comes with extra support from the Nx team and the option to host Nx Cloud on your own servers.

36
docs/nx-cloud/features/dynamic-agents.md Normal file
View File

@ -0,0 +1,36 @@
# Dynamically Allocate Agents
The standard way to set up [Nx Agents](/ci/features/distribute-task-execution) is to use this flag:
```
--distribute-on="8 linux-medium-js"
```
...which always runs tasks on the same amount of machines, you can also have Nx Cloud scale the number of agents based on the size of your PR. Specify the number and type of agents to use for small, medium and large changesets by creating a yaml file like this:
```yaml {% fileName=".nx/workflows/dynamic-changesets.yaml" %}
distribute-on:
small-changeset: 1 linux-medium-js
medium-changeset: 6 linux-medium-js
large-changeset: 10 linux-medium-js
```
{% callout type="note" title="How is the size of the PR determined?" %}
To determine the size of the PR, Nx Cloud calculates the relationship between the number of [affected projects](/ci/features/affected) and the total number of projects in the workspace. It then assigns it to one of the three categories: small, medium, or large.
{% /callout %}
You can then reference it in your CI pipeline configuration:
```yaml {% fileName=".github/workflows/main.yaml" %}
...
jobs:
- job: main
displayName: Main Job
...
steps:
- checkout
- run: npx nx-cloud start-ci-run --distribute-on=".nx/workflows/dynamic-changesets.yaml" --stop-agents-after="e2e-ci"
- ...
```
Now PRs that affect a small percentage of the repo will run on 1 agent, mid-size PRs will use 6 agents and large PRs will use 10 agents. This feature helps save costs on the smaller PRs while maintaining the high performance necessary for large PRs.

21
docs/nx-cloud/features/flaky-tasks.md Normal file
View File

@ -0,0 +1,21 @@
# Identify and Re-run Flaky Tasks
Sometimes there are tasks in CI that can fail or succeed without any related code changes. These tasks are called flaky tasks. Because the cause of the flakiness can be difficult to determine, developers will typically re-run CI in the hopes that another run will cause the task to succeed and allow them to merge their PR. Every time a developer has to do this, it is harming their productivity and the productivity of the company as a whole.
Nx is perfectly positioned to detect which tasks are flaky and automatically re-run the flaky task in a different agent so that developers can have confidence that a failed CI pipeline is a real failure.
## Identify Flaky Tasks
Nx creates a hash of all the inputs for a task whenever it is run. If Nx ever encounters a task that fails with a particular set of inputs and then succeeds with those same inputs, Nx knows for a fact that the task is flaky. Nx can't know with certainty when the task has been fixed to no longer be flaky, so if a particular task has no flakiness incidents for 2 weeks, the `flaky` flag is removed for that task.
## Manually Mark a Task as Flaky or Not Flaky
If you need to manually mark a task as flaky or not flaky, you can do so from the run details screen. Flaky tasks will have a button that says `Mark task as no longer flaky` and failed tasks that are not flaky will have a button that says `Mark task as likely flaky`. Using these buttons, you can ensure that Nx Cloud treats tasks in the appropriate way.
![Mark task as no longer flaky button](/nx-cloud/features/mark-task-as-no-longer-flaky.png)
![Mark task as likely flaky button](/nx-cloud/features/mark-task-as-likely-flaky.png)
## Re-run Flaky Tasks
When a flaky task fails in CI with [distributed task execution](/ci/features/distribute-task-execution) enabled, Nx will automatically send that task to a different agent and run it again (up to 2 tries in total). Its important to run the task on a different agent to ensure that the agent itself or the other tasks that were run on that agent are not the reason for the flakiness.

BIN
docs/nx-cloud/features/mark-task-as-likely-flaky.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 19 KiB

BIN
docs/nx-cloud/features/mark-task-as-no-longer-flaky.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 22 KiB

62
docs/nx-cloud/features/split-e2e-tasks.md Normal file
View File

@ -0,0 +1,62 @@
# Automatically Split E2E Tasks by File
In almost every codebase, e2e tests are the largest portion of the CI pipeline. Typically, e2e tests are grouped by application so that whenever an application's code changes, all the e2e tests for that application are run. These large groupings of e2e tests make caching and distribution less effective. Also, because e2e tests deal with a lot of integration code, they are at a much higher risk to be flaky.
You could manually address these problems by splitting your e2e tests into smaller tasks, but this requires developer time to maintain and adds additional configuration overhead to your codebase. Or, you could allow Nx to automatically split your Cypress or Playwright e2e tests by file.
## Set up
To enable automatically split e2e tasks, you need to turn on [inferred tasks](/concepts/inferred-tasks) for the [@nx/cypress](/nx-api/cypress) or [@nx/playwright](/nx-api/playwright) plugins. Run this command to set up inferred tasks:
{% tabs %}
{% tab label="Cypress" %}
```shell
nx add @nx/cypress
```
{% /tab %}
{% tab label="Playwright" %}
```shell
nx add @nx/playwright
```
{% /tab %}
{% /tabs %}
This command will register the appropriate plugin in the `plugins` array of `nx.json`.
## Manual Configuration
If you are already using the `@nx/cypress` or `@nx/playwright` plugin, you need to manually add the appropriate configuration to the `plugins` array of `nx.json`. The configuration settings can be found on the [Cypress](/nx-api/cypress#nxcypress-configuration) or [Playwright](/nx-api/playwright#nxplaywright-configuration) plugin docs.
## Usage
You can view the available tasks in the graph:
```shell
nx graph
```
You'll see that there are tasks named `e2e`, `e2e-ci` and a task for each e2e test file.
Developers can run all e2e tests locally the same way as usual:
```shell
nx e2e my-project-e2e
```
You can update your CI pipeline to run `e2e-ci`, which will automatically run all the inferred tasks for the individual e2e test files. Run it like this:
```shell
nx e2e-ci my-project-e2e
```
## Benefits
Smaller e2e tasks enable the following benefits:
- Nx's cache can be used for all the e2e tasks that succeeded and only the failed tasks need to be re-run
- Distributed Task Execution allows your e2e tests to be run on multiple machines simultaneously, which reduces the total time of the CI pipeline
- Nx Agents can [automatically re-run failed flaky e2e tests](/ci/features/flaky-tasks) on a separate agent without a developer needing to manually re-run the CI pipeline

15
docs/nx-cloud/intro/ci-with-nx.md
View File

@ -20,21 +20,14 @@ npx nx connect
{% cards cols="2" lgCols="4" mdCols="4" smCols="2" %}
{% link-card title="What is Nx Cloud?" type="video" url="https://youtu.be/NZF0ZJpgaJM" icon="nxcloud" /%}
{% link-card title="E2E Test Auto-Splitting and Distribution" type="video" url="https://youtu.be/XLOUFZeqRpM" icon="nxcloud" /%}
{% link-card title="Nx in 10 minutes!" type="video" url="https://youtu.be/-_4WMl-Fn0w" icon="nx" /%}
{% link-card title="More On Youtube" type="video" url="https://www.youtube.com/@nxdevtools" icon="youtube" /%}
{% /cards %}
{% cards cols="2" lgCols="2" mdCols="2" smCols="2" %}
{% link-card title="Circle CI with Nx" type="tutorial" url="/ci/intro/tutorials/circle" icon="circleci" /%}
{% link-card title="GitHub Actions with Nx" type="tutorial" url="/ci/intro/tutorials/github-actions" icon="github" /%}
{% link-card title="E2E Test Auto-Splitting and Distribution" type="video" url="https://youtu.be/XLOUFZeqRpM" icon="nxcloud" /%}
{% link-card title="More On Youtube" type="video" url="https://www.youtube.com/@nxdevtools" icon="youtube" /%}
{% /cards %}
## Ready? Get Started With Your Provider

140
docs/nx-cloud/intro/nx-agents.md
View File

@ -1,140 +0,0 @@
# Nx Agents: The Next Leap in Distributed Task Execution
{% callout type="note" title="Early Preview Doc - Subject to Change" %}
**Early Preview of Nx Agents:** This is a work-in-progress feature, with a public launch anticipated in Feb 2024. Keep an eye on this document for continuous updates. Interested in early access? [Sign up here](https://go.nx.dev/nx-agents-ea).
{% /callout %}
{% youtube
src="https://youtu.be/XLOUFZeqRpM"
title="Nx Agents in action splitting e2e tests at a file level"
/%}
Nx Agents represent the next evolution of [Nx Cloud's Distributed Task Execution (DTE)](/ci/features/distribute-task-execution), bringing a new level of efficiency and simplicity to your CI/CD pipelines. It takes away the complexity of configuring agents and comes with features such as scaling of agents based on the PR, flaky task re-running, and intelligent task splitting and distribution. Keep reading to learn more.
Currently in private beta, Nx Agents are slated for public release in February 2024. Don't miss the opportunity to be among the first to experience this groundbreaking tool. Sign up now for early access.
{% call-to-action title="Sign Up for Early Access" icon="nxcloud" description="Experience Nx Agents for yourself" url="https://go.nx.dev/nx-agents-ea" /%}
## What's the Difference to DTE?
Nx Cloud's [Distributed Task Execution (DTE)](/ci/features/distribute-task-execution) introduced an easy way to intelligently distribute tasks across machines, allowing for a more fine-grained distribution taking historical data as well as the task dependencies into account.
Using DTE you have to configure and instantiate your agents, which might be more or less complex depending on your CI provider. We have some guides on how to do that [here](/ci/recipes/set-up).
![Diagram showing Nx Cloud distributing tasks to multiple agents on your CI provider](/shared/images/dte/distributed-caching-and-task-execution.svg)
Nx Agents take away that complexity by delegating the agent management to Nx Cloud. You can think of them as a managed version of DTE.
![Diagram showing Nx Cloud distributing tasks to multiple Nx Agents](/shared/images/dte/distributed-task-execution-on-workflows.svg)
Keep reading to learn what the configuration and setup looks like.
## Managed Agents, Seamless Configuration
Enabling task distribution with Nx Agents can be done in a single line. Simply add the `--distribute-on` property to the `start-ci-run` line in your CI pipeline configuration:
```yaml
- name: Start CI run
run: 'npx nx-cloud start-ci-run --distribute-on="8 linux-medium-js"'
...
```
This instructs Nx Cloud to distribute tasks across 8 agents of type `linux-medium-js`. `linux-medium-js` is the name of the launch template that will be used to provision the agent. The default launch templates [can be found here](https://github.com/nrwl/nx-cloud-workflows/blob/main/launch-templates/linux.yaml) (there will be more once Nx Agents is publicly available).
You can also define your own "launch templates" (here's an [example from the Nx repo](https://github.com/nrwl/nx/blob/master/.nx/workflows/agents.yaml)):
```yaml
# .nx/workflows/agents.yaml
launch-templates:
linux-medium:
resource-class: 'docker_linux_amd64/medium+'
env:
CI: 'true'
GIT_AUTHOR_EMAIL: test@test.com
...
NX_CLOUD_ACCESS_TOKEN: '{{secrets.NX_CLOUD_ACCESS_TOKEN}}'
init-steps:
...
- name: Install Pnpm
script: |
npm install -g @pnpm/exe@8.7.4
- name: Pnpm Install
script: |
pnpm install --frozen-lockfile
- name: Install Cypress
script: pnpm exec cypress install
- name: Install Rust
- ...
```
Here are the [available resource classes](https://nx.app/pricing#resource-classes).
## Intelligent Dynamic Scaling
Instead of defining
```
--distribute-on="8 linux-medium-js"
```
...which always runs tasks on the same amount of machines, you can also have Nx Cloud scale the number of agents based on the size of your PR.
```yaml {% fileName=".nx/workflows/dynamic-changesets.yaml" %}
distribute-on:
small-changeset: 1 linux-medium-js
medium-changeset: 6 linux-medium-js
large-changeset: 10 linux-medium-js
```
{% callout type="note" title="How is the size of the PR determined?" %}
To determine the size of the PR, Nx Cloud calculates the relationship between the number of [affected projects](/ci/features/affected) and the total number of projects in the workspace. It then assigns it to one of the three categories: small, medium, or large. This calculation is static right now but might be configurable once Nx Agents is publicly available.
{% /callout %}
You can then reference it in your CI pipeline configuration:
```yaml {% fileName=".github/workflows/main.yaml" %}
...
jobs:
- job: main
displayName: Main Job
...
steps:
- checkout
- run: npx nx-cloud start-ci-run --distribute-on=".nx/workflows/dynamic-changesets.yaml" --stop-agents-after="e2e-wrapper"
- ...
```
## Automatic Task Splitting
Imagine you're working on an end-to-end (e2e) project using tools like Cypress or Playwright. Traditionally, to make the most of features like [affected](/ci/features/affected), [caching](/ci/features/remote-cache), and [distribution](/ci/features/distribute-task-execution), you'd need to divide your project into smaller parts. But this approach can often be cumbersome and less efficient for developers.
Nx is on the verge of introducing a game-changing feature that enables dynamic target definitions for projects (more details to come). Paired with Nx Agents, this innovation allows you to distribute e2e tests at the file level across various agents.
This significantly cuts down the time required to run e2e tests. For instance, in the video shown at the beginning of the page, e2e test durations plummeted from 90 minutes to just 10 minutes.
## Flaky Task Re-Running: Enhancing Reliability
Flaky tasks are a common headache, particularly with tests and end-to-end (e2e) tests. Nx Agents offer a solid solution to detect and automatically retry such unreliable tasks.
Nx Cloud keeps track of the targets being executed. A task, like `myapp:e2e`, is labeled as flaky **if it shows different outcomes (status codes) for the same cache hash key**. This key is an ideal task identifier, encompassing the command, environment variables, source files, and more.
Consider this scenario:
- An Nx agent runs `myapp:e2e`.
- Nx calculates the cache hash key for this task.
- **`myapp:e2e` fails**; Nx Cloud notes this failure along with the cache key.
- In a subsequent run, `myapp:e2e` is executed again.
- Nx recalculates the cache hash key, which matches the previous run's key (no existing cache since the initial task failed).
- This time, `myapp:e2e` **succeeds**.
- Nx Cloud identifies the task as flaky and stores this data temporarily.
As a result, if Nx Cloud has marked a task as flaky, it will be automatically retried, ideally on a different Nx Agent to prevent issues from any residues of earlier runs.
---
Sign up now for early access and be one of the first to try Nx Agents.
{% call-to-action title="Sign Up for Early Access" icon="nxcloud" description="Experience Nx Cloud Agents for yourself" url="https://go.nx.dev/nx-agents-ea" /%}

33
docs/nx-cloud/recipes/connect-to-cloud.md Normal file
View File

@ -0,0 +1,33 @@
# Connect to Nx Cloud
Create an account on [nx.app](https://nx.app). There are several ways to connect your repository to Nx Cloud.
#### Connect Directly Through GitHub
If your repository is hosted on GitHub, we recommend you create an Nx Cloud organization based on your GitHub organization.
![Connect Your VCS Account](/nx-cloud/tutorial/connect-vcs-account.png)
After that, connect you repository.
![Connect Your Repository](/nx-cloud/tutorial/connect-repository.png)
This will send a pull request to your repository that will add the `nxCloudAccessToken` property to `nx.json`.
![Nx Cloud Setup PR](/nx-cloud/tutorial/nx-cloud-setup-pr.png)
This wires up all the CI for you and configures access. Folks who can see your repository can see your workspace on nx.app.
## Manually Connect Your Workspace
If your repository is hosted on a different source control provider, you can also connect to Nx Cloud manually. You'll need to add a source control integration later to enable [Nx Agents](/ci/features/distribute-task-execution).
Run the following command in your repository:
```shell
pnpm nx connect
```
Click the link in the terminal to claim your workspace on [nx.app](https://nx.app).
The command generates an `nxCloudAccessToken` property inside of `nx.json`. This is a read-only token that should be committed to the repository.

2
docs/nx-cloud/reference/config.md
View File

@ -30,7 +30,7 @@ The Nx Cloud runner is configured in `nx.json`.
## Cacheable Operations
Targets can be marked as cacheable either in the `targetDefaults` in `nx.json` or in the project configuration by setting `"cache": true`. With this option enabled they can be cached using Nx Cloud and distributed using distributed task execution (DTE).
Targets can be marked as cacheable either in the `targetDefaults` in `nx.json` or in the project configuration by setting `"cache": true`. With this option enabled they can be cached and distributed using Nx Cloud.
## Timeouts

37
docs/nx-cloud/reference/env-vars.md
View File

@ -19,11 +19,6 @@ main jobs (e.g., when running CI on both Linux and Windows or when running the s
of Node.js or Java). In this case you can set the `NX_CI_EXECUTION_ENV` env variable on main jobs and agents. The main
job where the `NX_CI_EXECUTION_ENV` is set to, say, `macos`, will connect to the agents with the same env name.
### NX_RUN_GROUP
Older versions of `nx-cloud` used `NX_RUN_GROUP` instead of `NX_CI_EXECUTION_ID` and `NX_CI_EXECUTION_ENV`. It
served the same purpose.
### NX_CLOUD_ACCESS_TOKEN
You can also configure the access token by setting the `NX_CLOUD_ACCESS_TOKEN` environment
@ -31,22 +26,6 @@ variable. `NX_CLOUD_ACCESS_TOKEN` takes precedence over the `accessToken` proper
token stored in `nx.json` and a read-write token set via `NX_CLOUD_ACCESS_TOKEN` in CI. If you are using this
environment variable with Distributed Task Execution, the value on the main and agent jobs must match.
### NX_CLOUD_DISTRIBUTED_EXECUTION_AGENT_COUNT
The Nx Cloud plans distributed task execution based on the available information from the running agents. Due to
asynchronous nature of CI jobs, an agent might not have been created or started at the moment when DTE is initiated.
Setting `NX_CLOUD_DISTRIBUTED_EXECUTION_AGENT_COUNT` to say 8 will inform Nx Cloud to assume that there will be 8 agents
running. This can have an impact on better distribution of the tasks and allocation of the agents.
### NX_CLOUD_DISTRIBUTED_EXECUTION_STOP_AGENTS_ON_FAILURE
Setting `NX_CLOUD_DISTRIBUTED_EXECUTION_STOP_AGENTS_ON_FAILURE` to `true` will tell Nx Cloud to stop agents if a command
fails. When set to false (default value), you need to make sure to invoke `nx-cloud stop-all-agents` even if CI fails.
### NX_CLOUD_DISTRIBUTED_EXECUTION
Setting `NX_CLOUD_DISTRIBUTED_EXECUTION` to `true` enables distributed task execution.
### NX_CLOUD_ENCRYPTION_KEY
You can set the `encryptionKey` property in `nx.json` or set the `NX_CLOUD_ENCRYPTION_KEY` environment variable to
@ -61,6 +40,22 @@ By default, Nx Cloud requests will time out after 10 seconds. `NX_CLOUD_NO_TIMEO
Setting `NX_VERBOSE_LOGGING` to true will output the debug information about agents communicating with the main job.
This can be useful for debugging unexpected cache misses and issues with on-prem setups.
## Deprecated
### NX_RUN_GROUP
Older versions of `nx-cloud` used `NX_RUN_GROUP` instead of `NX_CI_EXECUTION_ID` and `NX_CI_EXECUTION_ENV`. It
served the same purpose.
### NX_CLOUD_DISTRIBUTED_EXECUTION_STOP_AGENTS_ON_FAILURE
Setting `NX_CLOUD_DISTRIBUTED_EXECUTION_STOP_AGENTS_ON_FAILURE` to `true` will tell Nx Cloud to stop agents if a command
fails. We recommend using `npx nx-cloud start-ci-run --stop-agents-on-failure=true` instead.
### NX_CLOUD_DISTRIBUTED_EXECUTION
Setting `NX_CLOUD_DISTRIBUTED_EXECUTION` to `false` disables distributed task execution. We recommend passing `--no-dte` or `--no-agents` instead.
## See Also
- [Nx Environment Variables](/reference/environment-variables)

66
docs/nx-cloud/reference/launch-templates.md Normal file
View File

@ -0,0 +1,66 @@
# Launch Templates
You can find built-in launch templates [here](https://github.com/nrwl/nx-cloud-workflows/tree/main/launch-templates).
The easiest way to create a new custom launch template is to modify one of the built-in ones. To do that, create a file in the
`.nx/workflows` folder and copy one of the built-in templates there. You can name the file any way you want (e.g., `agents.yaml`).
This is an example of a launch template using all built-in features:
```yaml
launch-templates:
my-linux-medium-js:
resourceClass: ''
image: 'ubuntu22.04-node20.9-v1'
env: MY_ENV_VAR=shared
init-steps:
- name: Checkout # using a reusable step
uses: 'nrwl/nx-cloud-workflows/v1.1/workflow-steps/checkout/main.yaml'
- name: Restore Node Modules Cache
uses: 'nrwl/nx-cloud-workflows/v1.1/workflow-steps/cache/main.yaml'
env:
KEY: 'package-lock.json|yarn.lock|pnpm-lock.yaml'
PATHS: 'node_modules'
BASE_BRANCH: 'main'
- name: Install Node Modules
uses: 'nrwl/nx-cloud-workflows/v1.1/workflow-steps/install-node-modules/main.yaml'
- name: Run a custom script
git config --global user.email test@test.com
git config --global user.name "Test Test"
- name: Setting env # Redefine PATH for further steps
script: echo "PATH=$HOME/my-folder:$PATH" >> $NX_CLOUD_ENV
- name: Print path
script: echo $PATH # will include my-folder
- name: Define env var for a step
env: MY_ENV_VAR=for-step
script: echo $MY_ENV_VAR # will print for-step
```
## Resource Classes
The following resource classes are available:
- `docker_linux_amd64/small`
- `docker_linux_amd64/medium`
- `docker_linux_amd64/medium+`
- `docker_linux_amd64/large`
- `docker_linux_amd64/large+`
- `docker_linux_amd64/extra_large`
- `docker_linux_amd64/extra_large+`
See their detailed description and pricing at [nx.app/pricing](https://nx.app/pricing).
## Image
The following images are available:
- `ubuntu22.04-node20.9-v1`
- `ubuntu22.04-node20.9-withDind-v1`
- `ubuntu22.04-node20.9-v2`
- `ubuntu22.04-node20.9-withDind-v2`
Enterprise accounts can use custom images.
## Reusable Steps
You can find the list of reusable step [here](https://github.com/nrwl/nx-cloud-workflows/tree/main/workflow-steps).

66
docs/nx-cloud/reference/nx-cloud-cli.md
View File

@ -7,6 +7,38 @@ command correspond to the same CI run.
You can configure your CI run by passing the following flags:
### --distribute-on
Tells Nx Cloud how many agents to use (and what launch templates to use) to distribute tasks. E.g.,
`npx nx-cloud start-ci-run --distribute-on="8 linux-medium-js"` will distribute CI using 8 agents that are initialized
using the `linux-medium-js` launch template.
You can use different types of launch templates as follows:
`npx nx-cloud start-ci-run --distribute-on="5 linux-medium-js, 3 linux-large-js"`.
You can also define the configuration in a file and reference it as follows:
`npx nx-cloud start-ci-run --distribute-on=".nx/workflows/dynamic-changesets.yaml"`.
```yaml {% fileName=".nx/workflows/dynamic-changesets.yaml" %}
distribute-on:
small-changeset: 1 linux-medium-js
medium-changeset: 6 linux-medium-js
large-changeset: 10 linux-medium-js
```
### --with-env-vars
By default, invoking `npx nx-cloud start-ci-run` will take all env vars prefixed with `NX_` and send them over to agents.
This means that your access token, verbose logging configuration and other NX related env vars will be the same on your
main CI jobs and on agents.
If you want to pass other env vars from the main job to agents, you can do it as follows: `--with-env-vars="VAR1,VAR2"`.
This will set `VAR1` and `VAR2` on agents to the same values set on the main job before any steps run.
You can also pass `--with-env-vars="auto"` which will filter out all OS-specific env vars and pass the rest to agents.
Note: none of the values passed to agents are stored by Nx Cloud.
### --use-dte-by-default
By default, invoking `npx nx-cloud start-ci-run` will configure Nx to distribute all commands by default. You can
@ -26,20 +58,36 @@ run.
You can fix it by telling Nx Cloud that it can terminate agents after it sees a certain
target: `npx nx-cloud start-ci-run --stop-agents-after=e2e`.
> Earlier versions of `nx-cloud` required you to set the `NX_CLOUD_DISTRIBUTED_EXECUTION` env variable to `true`
> to
> enable DTE, but in the latest version `npx nx-cloud start-ci-run` does it automatically.
### --require-explicit-completion
## Enabling/Disabling DTE
By default, Nx Cloud will monitor the main CI job and once it completes it will complete the associated CIPE object on the
Nx Cloud side. You can disable this by passing `--require-explicit-completion`. In this case, you will have to add
`npx nx-cloud complete-ci-run`.
## Enabling/Disabling Distribution
Invoking `npx nx-cloud start-ci-run` will tell Nx to distribute by default. You can enable/disable distribution for
individual commands as follows:
- `nx affected -t build --dte` (explicitly enable distribution, Nx >= 14.7)
- `nx affected -t build --no-dte` (explicitly disable distribution, Nx >= 14.7)
- `NX_CLOUD_DISTRIBUTED_EXECUTION=true nx affected -t build` (explicitly enable distribution)
- `NX_CLOUD_DISTRIBUTED_EXECUTION=false nx affected -t build` (explicitly disable distribution)
{% tabs %}
{% tab label="Nx >= 18" %}
- `nx affected -t build --agents` (explicitly enable distribution)
- `nx affected -t build --no-agents` (explicitly disable distribution)
{% /tab %}
{% tab label="Nx >= 14.7" %}
- `nx affected -t build --dte` (explicitly enable distribution)
- `nx affected -t build --no-dte` (explicitly disable distribution)
{% /tab %}
{% /tabs %}
## npx nx-cloud stop-all-agents
This command tells Nx Cloud to terminate all agents associated with this CI run.
Same as `npx nx-cloud complete-ci-run` and `npx nx-cloud complete-run-group`.
This command tells Nx Cloud to terminate all agents associated with this CI pipeline execution.
Invoking this command is not needed anymore. New versions of Nx Cloud can track when the main job terminates
and terminate associated agents automatically.

BIN
docs/nx-cloud/tutorial/cipe-agents-in-progress.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 136 KiB

265
docs/nx-cloud/tutorial/circle.md
View File

@ -49,10 +49,10 @@ To get started:
4. Finally, make sure all task are working on your machine, by running lint, test, build and e2e on all projects of the workspace
```shell
pnpm nx run-many -t lint,test,build,e2e
pnpm nx run-many -t lint test build e2e-ci
```
## Set-up Circle CI
## Set Up Circle CI
In order to use Circle CI, you need to [sign up and create an organization](https://circleci.com/docs/first-steps/#sign-up-and-create-an-org). Follow the steps in the Circle CI documentation to connect to your GitHub repository. When you are asked to configure a pipeline, choose any option, since we'll overwrite it in the next step.
@ -195,7 +195,7 @@ workflows:
- main
```
The `restore_cache` and `save_cache` steps are using a hash key that is created from the contents of the `pnpm-lock.yaml` file. This way if the `pnpm-lock.yaml` file remains the same, the next CI pipeline can pull from the cache instead of downloading `node_modules` again. This is similar to the way [Nx hashes input files to cache the results of tasks](/core-features/cache-task-results).
The `restore_cache` and `save_cache` steps are using a hash key that is created from the contents of the `pnpm-lock.yaml` file. This way if the `pnpm-lock.yaml` file remains the same, the next CI pipeline can pull from the cache instead of downloading `node_modules` again. This is similar to the way [Nx hashes input files to cache the results of tasks](/features/cache-task-results).
Create a new branch with these changes and submit a PR to your repo to test them. Merge your PR into the `main` branch when you're ready to move to the next section.
@ -241,7 +241,7 @@ Nx comes with a dedicated ["affected" command](/ci/features/affected) to help wi
### Configuring the Comparison Range for Affected Commands
To understand which projects are affected, Nx uses the Git history and the [project graph](/core-features/explore-graph). Git knows which files changed, and the Nx project graph knows which projects those files belong to.
To understand which projects are affected, Nx uses the Git history and the [project graph](/features/explore-graph). Git knows which files changed, and the Nx project graph knows which projects those files belong to.
The affected command takes a `base` and `head` commit. The default `base` is your `main` branch and the default `head` is your current file system. This is generally what you want when developing locally, but in CI, you need to customize these values.
@ -279,8 +279,8 @@ jobs:
- ~/.cache/Cypress
- nx/set-shas
- run: pnpm nx affected --base=$NX_BASE --head=$NX_HEAD -t lint,test,build --parallel=3 --configuration=ci
- run: pnpm nx affected --base=$NX_BASE --head=$NX_HEAD -t e2e --parallel=1
- run: pnpm nx affected --base=$NX_BASE --head=$NX_HEAD -t lint test build --parallel=3
- run: pnpm nx affected --base=$NX_BASE --head=$NX_HEAD -t e2e-ci --parallel=1
workflows:
build:
jobs:
@ -308,196 +308,147 @@ When you check the CI logs for this PR, you'll notice that no tasks were run by
Merge your PR into the `main` branch when you're ready to move to the next section.
## Enable Remote Caching on Circle CI
## Enable Remote Caching And Distributed Task Execution Using Nx Cloud
Reducing the number of tasks to run via [affected commands](/ci/features/affected) (as seen in the previous section) is helpful, but might not be enough. By default [Nx caches the results of tasks](/core-features/cache-task-results) on your local machine. But CI and local developer machines are still performing the same tasks on the same code - wasting time and money. The [Nx Cloud remote cache](/ci/features/remote-cache) can eliminate that waste for you.
Only running necessary tasks via [affected commands](/ci/features/affected) (as seen in the previous section) is helpful, but might not be enough. By default [Nx caches the results of tasks](/features/cache-task-results) on your local machine. But CI and other developer machines will still perform the same tasks on the same code - wasting time and money. Also, as your repository grows, running all the tasks on a single agent will cause the CI pipeline to take too long. The only way to decrease the CI pipeline time is to distribute your CI across many machines. Let's solve both of these problems using Nx Cloud.
### Connect Your Workspace to Nx Cloud
Create an account on [nx.app](https://nx.app). There are several ways to connect your repository to Nx Cloud.
#### Connect Directly Through GitHub
The easiest way is to create an Nx Cloud organization based on your GitHub organization.
![Connect Your VCS Account](/nx-cloud/tutorial/connect-vcs-account.png)
After that, connect you repository.
![Connect Your Repository](/nx-cloud/tutorial/connect-repository.png)
This will send a pull request to your repository that will add the `nxCloudAccessToken` property to `nx.json`.
![Nx Cloud Setup PR](/nx-cloud/tutorial/nx-cloud-setup-pr.png)
This wires up all the CI for you and configures access. Folks who can see your repository can see your workspace on nx.app.
#### Manually Connect Your Workspace
To manually connect your workspace to Nx Cloud, run the following command in your repository:
```shell
pnpm nx connect
```
Click the link in the terminal to claim your workspace on [nx.app](https://nx.app). Once your workspace is successfully connected you should see an empty dashboard.
Click the link in the terminal to claim your workspace on [nx.app](https://nx.app).
![Empty Nx Cloud Dashboard](/nx-cloud/tutorial/nx-cloud-empty-workspace.png)
The command generates an `nxCloudAccessToken` property inside of `nx.json`. This is a read-only token that should be committed to the repository.
Once your workspace is connected to Nx Cloud, run some tasks locally to prime the cache:
### Enable Remote Caching using Nx Replay
```shell
pnpm nx run-many -t lint,test,build,e2e
```
[Nx Cloud](https://nx.app) provides [Nx Replay](/ci/features/remote-cache), which is a powerful, scalable and, very importantly, secure way to share task artifacts across machines. It lets you configure permissions and guarantees the cached artifacts cannot be tempered with.
Now let's commit the changes to a new `ci-caching` branch and create a PR. The only change to the source code is adding an `nxCloudAccessToken` property to `nx.json`.
```json {% fileName="nx.json" %}
{
...
"nxCloudAccessToken": "MWM4NTU..."
}
```
[Nx Replay](/ci/features/remote-cache) is enabled by default. To see it in action, rerun the CI for the PR opened by Nx Cloud.
When Circle CI now processes our tasks they'll only take a fraction of the usual time. If you inspect the logs a little closer you'll see a note saying `[remote cache]`, indicating that the output has been pulled from the remote cache rather than running it. The full log of each command will still be printed since Nx restores that from the cache as well.
![Circle CI after enabling remote caching](/nx-cloud/tutorial/circle-ci-remote-cache.png)
The commands could be restored from the remote cache because we had run them locally before pushing the changes, thus priming the cache with the results. You can **configure** whether local runs should be read-only or read/write. [Our docs page has more details on security settings for your remote cache](/ci/concepts/cache-security).
![Run Details with remote cache hits](/nx-cloud/tutorial/nx-cloud-run-details.png)
You might also want to learn more about [how to fine-tune caching](/recipes/running-tasks/customizing-inputs) to get even better results.
What is more, if you run tasks locally, you will also get cache hits:
```{% command="nx run-many -t build" %}
...
✔ nx run express-legacy:build [remote cache]
✔ nx run nx-plugin-legacy:build [remote cache]
✔ nx run esbuild-legacy:build [remote cache]
✔ nx run react-native-legacy:build [remote cache]
✔ nx run angular-legacy:build [remote cache]
✔ nx run remix-legacy:build [remote cache]
————————————————————————————————————————————————
> NX Successfully ran target build for 58 projects and 62 tasks they depend on (1m)
Nx read the output from the cache instead of running the command for 116 out of 120 tasks.
```
You might also want to learn more about [how to fine-tune caching](/recipes/running-tasks/configure-inputs) to get even better results.
Merge your PR into the `main` branch when you're ready to move to the next section.
## Parallelize Tasks across Multiple Machines
### Parallelize Tasks Across Multiple Machines Using Nx Agents
The affected command and remote caching help speed up the average CI time, but there will be some PRs that affect everything in the repository. The only way to speed up that worst case scenario is through efficient parallelization. The best way to parallelize CI with Nx is to use [distributed task execution (DTE)](/ci/features/distribute-task-execution).
The affected command and Nx Replay help speed up the average CI time, but there will be some PRs that affect everything in the repository. The only way to speed up that worst case scenario is through efficient parallelization. The best way to parallelize CI with Nx is to use Nx Agents.
Nx Cloud's DTE feature
The Nx Agents feature
- takes a command (e.g. `run-many -t build,lint,test,e2e`) and splits it into individual tasks which it then distributes across multiple agents
- distributes tasks by considering the dependencies between them; e.g. if `e2e` depends on `build`, Nx Cloud will make sure that `build` is executed before `e2e`; it does this across machines
- takes a command (e.g. `run-many -t build lint test e2e-ci`) and splits it into individual tasks which it then distributes across multiple agents
- distributes tasks by considering the dependencies between them; e.g. if `e2e-ci` depends on `build`, Nx Cloud will make sure that `build` is executed before `e2e-ci`; it does this across machines
- distributes tasks to optimize for CPU processing time and reduce idle time by taking into account historical data about how long each task takes to run
- collects the results and logs of all the tasks and presents them in a single view
- automatically shuts down agents when they are no longer needed
Let's enable DTE in our CI pipeline configuration. First let's define the agent which restores the NPM dependencies and then runs the `nx-cloud start-agent` command which notifies Nx Cloud that this machine is waiting to run tasks that are assigned to it. `no_output_timeout: 60m` means that this agent will automatically shut down if it doesn't receive any instructions for 60 minutes.
Let's enable Nx Agents
```yaml {% fileName=".circleci/config.yml" highlightLines=["5-25"] %}
version: 2.1
orbs:
nx: nrwl/nx@1.5.1
jobs:
agent:
docker:
- image: cimg/node:lts-browsers
parameters:
ordinal:
type: integer
steps:
- checkout
- restore_cache:
key: npm-dependencies-{{ checksum "pnpm-lock.yaml" }}
- run:
name: install dependencies
command: pnpm install --frozen-lockfile
- save_cache:
key: npm-dependencies-{{ checksum "pnpm-lock.yaml" }}
paths:
- node_modules
- ~/.cache/Cypress
- run:
command: pnpm nx-cloud start-agent
no_output_timeout: 60m
main: ...
```
pnpm exec nx-cloud start-ci-run --distribute-on="3 linux-medium-js" --stop-agents-after="e2e-ci"
```
The `main` job looks very similar to the previous configuration, with the addition of a single line above the `nx affected` commands.
We recommend you add this line right after you check out the repo, before installing node modules.
```yaml {% fileName=".circleci/config.yml" highlightLines=[24,29] %}
version: 2.1
orbs:
nx: nrwl/nx@1.5.1
jobs:
agent:
- ...
main:
docker:
- image: cimg/node:lts-browsers
steps:
- checkout
- restore_cache:
key: npm-dependencies-{{ checksum "pnpm-lock.yaml" }}
- run:
name: install dependencies
command: pnpm install --frozen-lockfile
- save_cache:
key: npm-dependencies-{{ checksum "pnpm-lock.yaml" }}
paths:
- node_modules
- ~/.cache/Cypress
- nx/set-shas
- run: pnpm nx-cloud start-ci-run --stop-agents-after="e2e"
- run: pnpm nx affected --base=$NX_BASE --head=$NX_HEAD -t lint,test,build --parallel=3 --configuration=ci
- run: pnpm nx affected --base=$NX_BASE --head=$NX_HEAD -t e2e --parallel=1
```
- `nx-cloud start-ci-run` lets Nx know that all the tasks after this line should be orchestrated with Nx Cloud's DTE process
- `--stop-agents-after="e2e"` lets Nx Cloud know which line is the last command in this pipeline. Once there are no more e2e tasks for an agent to run, Nx Cloud will automatically shut them down. This way you're not wasting money on idle agents while a particularly long e2e task is running on a single agent.
Finally in the `workflows` section we instantiate the number of agents we want to run. The **full pipeline configuration** looks like this:
```yaml {% fileName=".circleci/config.yml" %}
version: 2.1
orbs:
nx: nrwl/nx@1.5.1
jobs:
agent:
docker:
- image: cimg/node:lts-browsers
parameters:
ordinal:
type: integer
steps:
- checkout
- restore_cache:
key: npm-dependencies-{{ checksum "pnpm-lock.yaml" }}
- run:
name: install dependencies
command: pnpm install --frozen-lockfile
- save_cache:
key: npm-dependencies-{{ checksum "pnpm-lock.yaml" }}
paths:
- node_modules
- ~/.cache/Cypress
- run:
command: pnpm nx-cloud start-agent
no_output_timeout: 60m
main:
docker:
- image: cimg/node:lts-browsers
steps:
- checkout
- restore_cache:
key: npm-dependencies-{{ checksum "pnpm-lock.yaml" }}
- run:
name: install dependencies
command: pnpm install --frozen-lockfile
- save_cache:
key: npm-dependencies-{{ checksum "pnpm-lock.yaml" }}
paths:
- node_modules
- ~/.cache/Cypress
- nx/set-shas
- run: pnpm nx-cloud start-ci-run --stop-agents-after="e2e"
- run: pnpm nx affected --base=$NX_BASE --head=$NX_HEAD -t lint,test,build --parallel=3 --configuration=ci
- run: pnpm nx affected --base=$NX_BASE --head=$NX_HEAD -t e2e --parallel=1
workflows:
build:
jobs:
- agent:
matrix:
parameters:
ordinal: [1, 2, 3]
- main
```
- `nx-cloud start-ci-run --distribute-on="3 linux-medium-j` lets Nx know that all the tasks after this line should using Nx Agents and that Nx Cloud should use 3 instances of the `linux-medium-js` launch template. See below on how to configure a custom launch template.
- `--stop-agents-after="e2e-ci"` lets Nx Cloud know which line is the last command in this pipeline. Once there are no more e2e tasks for an agent to run, Nx Cloud will automatically shut them down. This way you're not wasting money on idle agents while a particularly long e2e task is running on a single agent.
Try it out by creating a new PR with the above changes.
Once Circle CI starts, you should see multiple agents running in parallel:
Once Circle CI starts, you should see multiple agents running in parallel similar to this:
![Circle CI showing multiple DTE agents](/nx-cloud/tutorial/circle-dte-multiple-agents.png)
![CIPE Agents In Progress](/nx-cloud/tutorial/cipe-agents-in-progress.png)
If you open your Nx Cloud dashboard, you'll get a better view of the individual tasks and their corresponding logs.
With this pipeline configuration in place, no matter how large the repository scales, Nx Cloud will adjust and distribute tasks across agents in the optimal way. If CI pipelines start to slow down, just add some agents. One of the main advantages is that this pipeline definition is declarative. We tell Nx what commands to run, but not how to distribute them. That way even if our monorepo structure changes and evolves over time, the distribution will be taken care of by Nx Cloud.
![Nx Cloud run details](/nx-cloud/tutorial/nx-cloud-run-details.png)
### Running Commands Without Distribution
With this pipeline configuration in place, no matter how large the repository scales, Nx Cloud will adjust and distribute tasks across agents in the optimal way. If CI pipelines start to slow down, just add some agents to the `ordinal: [1, 2, 3]` array. One of the main advantages is that such a pipeline definition is declarative. We just give instructions what commands to run, but not how to distribute them. As such even if our monorepo structure changes and evolves over time, the distribution will be taken care of by Nx Cloud.
Sometimes you want to distribute most of your commands, but run some of them in Circle CI. You can do this with the `--no-agents` flag as follows:
```yaml {% fileName=".circleci/config.yml" highlightLines=[25] %}
version: 2.1
orbs:
nx: nrwl/nx@1.5.1
jobs:
main:
docker:
- image: cimg/node:lts-browsers
steps:
- checkout
- run: pnpm exec nx-cloud start-ci-run --distribute-on="3 linux-medium-js" --stop-agents-after="e2e-ci"
- restore_cache:
key: npm-dependencies-{{ checksum "pnpm-lock.yaml" }}
- run:
name: install dependencies
command: pnpm install --frozen-lockfile
- save_cache:
key: npm-dependencies-{{ checksum "pnpm-lock.yaml" }}
paths:
- node_modules
- ~/.cache/Cypress
- nx/set-shas
- run: pnpm nx affected --base=$NX_BASE --head=$NX_HEAD -t lint test build --parallel=3
- run: pnpm nx affected --base=$NX_BASE --head=$NX_HEAD -t e2e-ci --parallel=1
- run: pnpm nx affected --base=$NX_BASE --head=$NX_HEAD -t deploy --no-agents # run without distribution
workflows:
build:
jobs:
- main
```
## Next Steps
You now have a highly optimized CI configuration that will scale as your repository scales. See what else you can do with Nx Cloud.
- Set up [GitHub PR integration](/ci/recipes/source-control-integration/github) to view Nx Cloud results directly in your PR
- Choose the [security settings](/ci/concepts/cache-security) that make sense for your organization
- [Record non-Nx commands](/ci/recipes/other/record-commands) and view the results in the Nx Cloud interface
- Configure [dynamic agent allocation](/ci/features/dynamic-agents)
- Learn about [automatically splitting e2e tasks](/ci/features/split-e2e-tasks)
- Identify and re-run [flaky tasks](/ci/features/flaky-tasks)

BIN
docs/nx-cloud/tutorial/connect-repository.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 17 KiB

BIN
docs/nx-cloud/tutorial/connect-vcs-account.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 35 KiB

169
docs/nx-cloud/tutorial/github-actions.md
View File

@ -49,10 +49,10 @@ To get started:
4. Finally, make sure all task are working on your machine, by running lint, test, build and e2e on all projects of the workspace
```shell
pnpm nx run-many -t lint,test,build,e2e
pnpm nx run-many -t lint test build e2e
```
## Set-up GitHub Actions
## Set Up GitHub Actions
To get started with GitHub Actions, we'll create a pipeline that just logs a message. First, checkout a new branch:
@ -190,7 +190,7 @@ jobs:
- run: pnpm nx build cart
```
The `restore_cache` and `save_cache` steps are using a hash key that is created from the contents of the `pnpm-lock.yaml` file. This way if the `pnpm-lock.yaml` file remains the same, the next CI pipeline can pull from the cache instead of downloading `node_modules` again. This is similar to the way [Nx hashes input files to cache the results of tasks](/core-features/cache-task-results).
The `restore_cache` and `save_cache` steps are using a hash key that is created from the contents of the `pnpm-lock.yaml` file. This way if the `pnpm-lock.yaml` file remains the same, the next CI pipeline can pull from the cache instead of downloading `node_modules` again. This is similar to the way [Nx hashes input files to cache the results of tasks](/features/cache-task-results).
Create a new branch with these changes and submit a PR to your repo to test them. Merge your PR into the `main` branch when you're ready to move to the next section.
@ -236,7 +236,7 @@ Nx comes with a dedicated ["affected" command](/ci/features/affected) to help wi
### Configuring the Comparison Range for Affected Commands
To understand which projects are affected, Nx uses the Git history and the [project graph](/core-features/explore-graph). Git knows which files changed, and the Nx project graph knows which projects those files belong to.
To understand which projects are affected, Nx uses the Git history and the [project graph](/features/explore-graph). Git knows which files changed, and the Nx project graph knows which projects those files belong to.
The affected command takes a `base` and `head` commit. The default `base` is your `main` branch and the default `head` is your current file system. This is generally what you want when developing locally, but in CI, you need to customize these values.
@ -286,7 +286,7 @@ jobs:
- uses: nrwl/nx-set-shas@v3
# This line is needed for nx affected to work when CI is running on a PR
- run: git branch --track main origin/main
- run: pnpm nx affected -t lint,test,build --parallel=3 --configuration=ci
- run: pnpm nx affected -t lint test build --parallel=3
- run: pnpm nx affected -t e2e --parallel=1
```
@ -309,40 +309,57 @@ When you check the CI logs for this PR, you'll notice that no tasks were run by
Merge your PR into the `main` branch when you're ready to move to the next section.
## Enable Remote Caching on GitHub Actions
## Enable Remote Caching and Distributed Task Execution Using Nx Cloud
Reducing the number of tasks to run via [affected commands](/ci/features/affected) (as seen in the previous section) is helpful, but might not be enough. By default [Nx caches the results of tasks](/core-features/cache-task-results) on your local machine. But CI and local developer machines are still performing the same tasks on the same code - wasting time and money. The [Nx Cloud remote cache](/ci/features/remote-cache) can eliminate that waste for you.
Only running necessary tasks via [affected commands](/ci/features/affected) (as seen in the previous section) is helpful, but might not be enough. By default [Nx caches the results of tasks](/features/cache-task-results) on your local machine. But CI and other developer machines will still perform the same tasks on the same code - wasting time and money. Also, as your repository grows, running all the tasks on a single agent will cause the CI pipeline to take too long. The only way to decrease the CI pipeline time is to distribute your CI across many machines. Let's solve both of these problems using Nx Cloud.
```shell
pnpm nx connect
```
### Connect Your Workspace to Nx Cloud
Click the link in the terminal to claim your workspace on [nx.app](https://nx.app). Once your workspace is successfully connected you should see an empty dashboard.
Create an account on [nx.app](https://nx.app). The easiest way to connect your repository to Nx Cloud is to create an Nx Cloud organization based on your GitHub organization.
![Empty Nx Cloud Dashboard](/nx-cloud/tutorial/nx-cloud-empty-workspace.png)
![Connect Your VCS Account](/nx-cloud/tutorial/connect-vcs-account.png)
Once your workspace is connected to Nx Cloud, run some tasks locally to prime the cache:
After that, connect you repository.
```shell
pnpm nx run-many -t lint,test,build,e2e
```
![Connect Your Repository](/nx-cloud/tutorial/connect-repository.png)
Now let's commit the changes to a new `ci-caching` branch and create a PR. The only change to the source code is adding an `nxCloudAccessToken` property to `nx.json`.
This will send a pull request to your repository that will add the `nxCloudAccessToken` property to `nx.json`.
```json {% fileName="nx.json" %}
{
...
"nxCloudAccessToken": "MWM4NTU..."
}
```
![Nx Cloud Setup PR](/nx-cloud/tutorial/nx-cloud-setup-pr.png)
This wires up all the CI for you and configures access. Folks who can see your repository can see your workspace on nx.app.
### Enable Remote Caching using Nx Replay
[Nx Cloud](https://nx.app) provides [Nx Replay](/ci/features/remote-cache), which is a powerful, scalable and, very importantly, secure way to share task artifacts across machines. It lets you configure permissions and guarantees the cached artifacts cannot be tempered with.
[Nx Replay](/ci/features/remote-cache) is enabled by default. To see it in action, rerun the CI for the PR opened by Nx Cloud.
When GitHub Actions now processes our tasks they'll only take a fraction of the usual time. If you inspect the logs a little closer you'll see a note saying `[remote cache]`, indicating that the output has been pulled from the remote cache rather than running it. The full log of each command will still be printed since Nx restores that from the cache as well.
![GitHub Actions after enabling remote caching](/nx-cloud/tutorial/gh-ci-remote-cache.png)
The commands could be restored from the remote cache because we had run them locally before pushing the changes, thus priming the cache with the results. You can **configure** whether local runs should be read-only or read/write. [Our docs page has more details on security settings for your remote cache](/ci/concepts/cache-security).
![Run Details with remote cache hits](/nx-cloud/tutorial/nx-cloud-run-details.png)
You might also want to learn more about [how to fine-tune caching](/recipes/running-tasks/customizing-inputs) to get even better results.
What is more, if you run tasks locally, you will also get cache hits:
```{% command="nx run-many -t build" %}
...
✔ nx run express-legacy:build [remote cache]
✔ nx run nx-plugin-legacy:build [remote cache]
✔ nx run esbuild-legacy:build [remote cache]
✔ nx run react-native-legacy:build [remote cache]
✔ nx run angular-legacy:build [remote cache]
✔ nx run remix-legacy:build [remote cache]
————————————————————————————————————————————————
> NX Successfully ran target build for 58 projects and 62 tasks they depend on (1m)
Nx read the output from the cache instead of running the command for 116 out of 120 tasks.
```
You might also want to learn more about [how to fine-tune caching](/recipes/running-tasks/configure-inputs) to get even better results.
Merge your PR into the `main` branch when you're ready to move to the next section.
@ -369,21 +386,42 @@ This will verify that Nx Cloud can connect to your repo. Upon a successful test,
Now any new PRs in your repo should have a comment automatically added that links directly to Nx Cloud. For other ways of setting up PR integration, read the [Enable GitHub PR Integration recipe](/ci/recipes/source-control-integration/github).
## Parallelize Tasks across Multiple Machines
### Parallelize Tasks Across Multiple Machines Using Nx Agents
The affected command and remote caching help speed up the average CI time, but there will be some PRs that affect everything in the repository. The only way to speed up that worst case scenario is through efficient parallelization. The best way to parallelize CI with Nx is to use [distributed task execution (DTE)](/ci/features/distribute-task-execution).
The affected command and Nx Replay help speed up the average CI time, but there will be some PRs that affect everything in the repository. The only way to speed up that worst case scenario is through efficient parallelization. The best way to parallelize CI with Nx is to use Nx Agents.
Nx Cloud's DTE feature
The Nx Agents feature
- takes a command (e.g. `run-many -t build,lint,test,e2e`) and splits it into individual tasks which it then distributes across multiple agents
- distributes tasks by considering the dependencies between them; e.g. if `e2e` depends on `build`, Nx Cloud will make sure that `build` is executed before `e2e`; it does this across machines
- takes a command (e.g. `run-many -t build lint test e2e-ci`) and splits it into individual tasks which it then distributes across multiple agents
- distributes tasks by considering the dependencies between them; e.g. if `e2e-ci` depends on `build`, Nx Cloud will make sure that `build` is executed before `e2e-ci`; it does this across machines
- distributes tasks to optimize for CPU processing time and reduce idle time by taking into account historical data about how long each task takes to run
- collects the results and logs of all the tasks and presents them in a single view
- automatically shuts down agents when they are no longer needed
Let's enable DTE in our CI pipeline configuration. We'll use two reusable workflows from the `nrwl/ci` repository. You can check out the full [API](https://github.com/nrwl/ci) for those workflows.
Let's enable Nx Agents
```yaml {% fileName=".github/workflows/ci.yml" highlightLines=["9-21"] %}
```shell
pnpm exec nx-cloud start-ci-run --distribute-on="3 linux-medium-js" --stop-agents-after="e2e-ci"
```
We recommend you add this line right after you check out the repo, before installing node modules.
- `nx-cloud start-ci-run --distribute-on="3 linux-medium-j` lets Nx know that all the tasks after this line should using Nx Agents and that Nx Cloud should use 3 instances of the `linux-medium-js` launch template. See below on how to configure a custom launch template.
- `--stop-agents-after="e2e-ci"` lets Nx Cloud know which line is the last command in this pipeline. Once there are no more e2e tasks for an agent to run, Nx Cloud will automatically shut them down. This way you're not wasting money on idle agents while a particularly long e2e task is running on a single agent.
Try it out by creating a new PR with the above changes.
Once GitHub Actions starts, you should see multiple agents running in parallel:
![GitHub Actions showing multiple DTE agents](/nx-cloud/tutorial/gh-dte-multiple-agents.png)
With this pipeline configuration in place, no matter how large the repository scales, Nx Cloud will adjust and distribute tasks across agents in the optimal way. If CI pipelines start to slow down, just add some agents. One of the main advantages is that this pipeline definition is declarative. We tell Nx what commands to run, but not how to distribute them. That way even if our monorepo structure changes and evolves over time, the distribution will be taken care of by Nx Cloud.
### Running Commands Without Distribution
Sometimes you want to distribute most of your commands, but run some of them in Github Actions. You can do this with the `--no-agents` flag as follows:
```yaml {% fileName=".github/workflows/ci.yml" highlightLines=["18-21","44"] %}
name: CI
on:
push:
@ -393,38 +431,47 @@ on:
jobs:
main:
name: Nx Cloud - Main Job
uses: nrwl/ci/.github/workflows/nx-cloud-main.yml@v0.13.0
with:
number-of-agents: 3
parallel-commands-on-agents: |
npx nx affected -t lint,test,build,e2e --parallel=2
agents:
name: Nx Cloud - Agents
uses: nrwl/ci/.github/workflows/nx-cloud-agents.yml@v0.13.0
with:
number-of-agents: 3
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: pnpm/action-setup@v2
with:
version: 8
- run: |
pnpm exec nx-cloud start-ci-run \
--distribute-on="3 linux-medium-js" \
--stop-agents-after="e2e-ci"
- name: Restore cached npm dependencies
id: cache-dependencies-restore
uses: actions/cache/restore@v3
with:
path: |
node_modules
~/.cache/Cypress # needed for the Cypress binary
key: npm-dependencies-${{ hashFiles('pnpm-lock.yaml') }}
- run: pnpm install --frozen-lockfile
- name: Cache npm dependencies
id: cache-dependencies-save
uses: actions/cache/save@v3
with:
path: |
node_modules
~/.cache/Cypress # needed for the Cypress binary
key: ${{ steps.cache-dependencies-restore.outputs.cache-primary-key }}
- uses: nrwl/nx-set-shas@v3
# This line is needed for nx affected to work when CI is running on a PR
- run: git branch --track main origin/main
- run: pnpm nx affected -t lint test build --parallel=3
- run: pnpm nx affected -t e2e-ci --parallel=1
- run: pnpm nx affected -t deploy --no-agents
```
This workflow runs all the affected tasks on 3 agents, with 2 tasks running in parallel on each agent.
Try it out by creating a new PR with the above changes.
Once GitHub Actions starts, you should see multiple agents running in parallel:
![GitHub Actions showing multiple DTE agents](/nx-cloud/tutorial/gh-dte-multiple-agents.png)
If you open your Nx Cloud dashboard, you'll get a better view of the individual tasks and their corresponding logs.
![Nx Cloud run details](/nx-cloud/tutorial/nx-cloud-run-details.png)
With this pipeline configuration in place, no matter how large the repository scales, Nx Cloud will adjust and distribute tasks across agents in the optimal way. If CI pipelines start to slow down, just add some agents to the `number-of-agents: 3` properties. One of the main advantages is that such a pipeline definition is declarative. We just give instructions what commands to run, but not how to distribute them. As such even if our monorepo structure changes and evolves over time, the distribution will be taken care of by Nx Cloud.
## Next Steps
You now have a highly optimized CI configuration that will scale as your repository scales. See what else you can do with Nx Cloud.
- Set up [GitHub PR integration](/ci/recipes/source-control-integration/github) to view Nx Cloud results directly in your PR
- Choose the [security settings](/ci/concepts/cache-security) that make sense for your organization
- [Record non-Nx commands](/ci/recipes/other/record-commands) and view the results in the Nx Cloud interface
- Configure [dynamic agent allocation](/ci/features/dynamic-agents)
- Learn about [automatically splitting e2e tasks](/ci/features/split-e2e-tasks)
- Identify and re-run [flaky tasks](/ci/features/flaky-tasks)

BIN
docs/nx-cloud/tutorial/nx-cloud-setup-pr.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 101 KiB

150
docs/shared/angular-standalone-tutorial/1-code-generation.md
View File

@ -1,150 +0,0 @@
---
title: 'Angular Standalone Tutorial - Part 1: Code Generation'
description: In this tutorial you'll create a frontend-focused workspace with Nx.
---
{% callout type="check" title="Looking for Angular monorepos?" %}
This tutorial sets up a repo with a single application at the root level that breaks out its code into libraries to add structure. If you are looking for a Angular monorepo setup then check out our [Angular monorepo tutorial](/getting-started/tutorials/angular-monorepo-tutorial).
{% /callout %}
{% youtube
src="https://www.youtube.com/embed/LYPVrWQNnEc"
title="Tutorial: Standalone Angular Application"
/%}
{% github-repository url="https://github.com/nrwl/nx-recipes/tree/main/angular-standalone" /%}
# Angular Standalone Tutorial - Part 1: Code Generation
## Contents
- [1 - Code Generation](/angular-standalone-tutorial/1-code-generation)
- [2 - Project Graph](/angular-standalone-tutorial/2-project-graph)
- [3 - Task Running](/angular-standalone-tutorial/3-task-running)
- [4 - Task Pipelines](/angular-standalone-tutorial/4-task-pipelines)
- [5 - Summary](/angular-standalone-tutorial/5-summary)
## Creating a New Workspace
Run the command `npx create-nx-workspace@latest` and when prompted, provide the following responses:
```{% command="npx create-nx-workspace@latest" path="~" %}
> NX Let's create a new workspace [https://nx.dev/getting-started/intro]
✔ Where would you like to create your workspace? · store
✔ Which stack do you want to use? · angular
✔ Standalone project or integrated monorepo? · standalone
✔ Default stylesheet format · css
✔ Would you like to use Standalone Components in your application? · No
✔ Would you like to add routing? · Yes
✔ Do you want Nx Cloud to make your CI fast? · Yes
```
{% card title="Opting into Nx Cloud" description="You will also be prompted whether to add Nx Cloud to your workspace. We won't address this in this tutorial, but you can see the introduction to Nx Cloud for more details." url="/ci/intro/ci-with-nx" /%}
Once the command completes, the file structure should look like this:
```treeview
store/
├── e2e/
├── src/
├── tools/
├── nx.json
├── package.json
├── project.json
├── README.md
├── tsconfig.base.json
└── tsconfig.json
```
There are two projects that have been created for you:
- An Angular application (`store`) with its configuration files at the root of the repo and source code in `src`.
- A project for Cypress e2e tests for our `store` application in `e2e`.
As far as Nx is concerned, the root-level `store` app owns every file that doesn't belong to a different project. So files in the `e2e` folder belong to the `e2e` project, everything else belongs to `store`.
{% card title="Nx Cypress Support" description="While we see the Cypress project here, we won't go deeper on Cypress in this tutorial. You can find more materials on Nx Cypress support on the @nx/cypress package page." url="/nx-api/cypress" /%}
## Generating a component for the store
```{% command="npx nx g @nx/angular:component shop --project=store" path="~/store" %}
> NX Generating @nx/angular:component
CREATE src/app/shop/shop.component.css
CREATE src/app/shop/shop.component.html
CREATE src/app/shop/shop.component.spec.ts
CREATE src/app/shop/shop.component.ts
UPDATE src/app/app.module.ts
```
![Nx Generator Syntax](/shared/angular-standalone-tutorial/generator-syntax.svg)
## Generating Libraries
To create the `cart` and `shared/ui` libraries, use the nx/angular:lib` generator:
```{% command="npx nx g @nx/angular:library cart" path="~/store" %}
> NX Generating @nx/angular:library
CREATE cart/README.md
CREATE cart/tsconfig.lib.json
CREATE cart/tsconfig.spec.json
CREATE cart/src/index.ts
CREATE cart/src/lib/cart.module.ts
CREATE cart/project.json
CREATE cart/tsconfig.json
UPDATE tsconfig.base.json
CREATE cart/jest.config.ts
CREATE cart/src/test-setup.ts
CREATE cart/.eslintrc.json
```
```{% command="npx nx g @nx/angular:lib shared/ui --buildable" path="~/store" %}
> NX Generating @nx/angular:library
UPDATE jest.config.ts
CREATE jest.config.app.ts
UPDATE project.json
CREATE shared/ui/README.md
CREATE shared/ui/ng-package.json
CREATE shared/ui/package.json
CREATE shared/ui/tsconfig.lib.json
CREATE shared/ui/tsconfig.lib.prod.json
CREATE shared/ui/tsconfig.spec.json
CREATE shared/ui/src/index.ts
CREATE shared/ui/src/lib/shared-ui.module.ts
CREATE shared/ui/project.json
CREATE shared/ui/tsconfig.json
UPDATE tsconfig.base.json
CREATE shared/ui/jest.config.ts
CREATE shared/ui/src/test-setup.ts
CREATE shared/ui/.eslintrc.json
UPDATE package.json
added 89 packages, removed 17 packages, changed 2 packages, and audited 1515 packages in 27s
201 packages are looking for funding
run `npm fund` for details
8 low severity vulnerabilities
To address all issues (including breaking changes), run:
npm audit fix --force
Run `npm audit` for details.
```
You should now be able to see all three projects of our design:
- `store` in the root
- `cart` in `cart`
- `shared-ui` in `shared/ui`
## What's Next
- Continue to [2: Project Graph](/angular-standalone-tutorial/2-project-graph)

254
docs/shared/angular-standalone-tutorial/2-project-graph.md
View File

@ -1,254 +0,0 @@
# Angular Standalone Tutorial - Part 2: Project Graph
Run the command: `npx nx graph`. A browser should open up with the following contents:
{% graph height="450px" %}
```json
{
"hash": "85fd0561bd88f0bcd8703a9e9369592e2805f390d04982fb2401e700dc9ebc59",
"projects": [
{
"name": "cart",
"type": "lib",
"data": {
"tags": []
}
},
{
"name": "shared-ui",
"type": "lib",
"data": {
"tags": []
}
},
{
"name": "e2e",
"type": "e2e",
"data": {
"tags": []
}
},
{
"name": "store",
"type": "app",
"data": {
"tags": []
}
}
],
"dependencies": {
"cart": [],
"shared-ui": [],
"e2e": [{ "source": "e2e", "target": "store", "type": "implicit" }],
"store": []
},
"workspaceLayout": { "appsDir": "apps", "libsDir": "libs" },
"affectedProjectIds": [],
"focus": null,
"groupByFolder": false,
"exclude": []
}
```
{% /graph %}
Nx creates the graph based on the source code. The projects are not linked in this diagram because we haven't actually finished our application. Once we use the shared components in another project, Nx will create the dependency in the graph. Let's do that now.
### Set Up the Router
Configure the routes:
```javascript {% fileName="src/app/app.module.ts" %}
import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { RouterModule } from '@angular/router';
import { SharedUiModule } from '@store/shared/ui';
import { AppComponent } from './app.component';
import { NxWelcomeComponent } from './nx-welcome.component';
import { ShopComponent } from './shop/shop.component';
@NgModule({
declarations: [AppComponent, NxWelcomeComponent, ShopComponent],
imports: [
BrowserModule,
SharedUiModule,
RouterModule.forRoot([
{
path: 'cart',
loadChildren: () => import('@store/cart').then((m) => m.CartModule),
},
{
path: '**',
component: ShopComponent,
},
]),
],
providers: [],
bootstrap: [AppComponent],
})
export class AppModule {}
```
```javascript {% fileName="src/app/app.component.html" %}
<router-outlet></router-outlet>
```
{% callout type="note" title="Typescript Paths" %}
When a library is created, Nx adds a new Typescript path to the `tsconfig.base.json` file. The running Typescript server process inside of your editor sometimes doesn't pick up these changes and you have to restart the server to remove inline errors on your import statements. This can be done in VS Code from the command palette when viewing a typescript file (Command-Shift-P) "Typescript: Restart TS server"
{% /callout %}
### `shared-ui`
Run the `@nx/angular:component` generator with the command:
```{% command="npx nx g @nx/angular:component banner --project=shared-ui --export" path="~/store" %}
> NX Generating @nx/angular:component
CREATE shared/ui/src/lib/banner/banner.component.css
CREATE shared/ui/src/lib/banner/banner.component.html
CREATE shared/ui/src/lib/banner/banner.component.spec.ts
CREATE shared/ui/src/lib/banner/banner.component.ts
UPDATE shared/ui/src/lib/shared-ui.module.ts
UPDATE shared/ui/src/index.ts
```
Then create a simple `Banner` component in the generated file:
```javascript {% fileName="shared/ui/src/lib/banner/banner.component.ts" %}
import { Component, Input } from '@angular/core';
@Component({
selector: 'store-banner',
standalone: true,
templateUrl: './banner.component.html',
styleUrls: ['./banner.component.css'],
})
export class BannerComponent {
@Input() text = '';
}
```
```javascript {% fileName="shared/ui/src/lib/banner/banner.component.html" %}
<header>{{ text }}</header>
```
### `cart`
Create a cart-route component:
```{% command="npx nx g @nx/angular:component cart-route --project=cart" path="~/store" %}
> NX Generating @nx/angular:component
CREATE cart/src/lib/cart-route/cart-route.component.css
CREATE cart/src/lib/cart-route/cart-route.component.html
CREATE cart/src/lib/cart-route/cart-route.component.spec.ts
CREATE cart/src/lib/cart-route/cart-route.component.ts
UPDATE cart/src/lib/cart.module.ts
```
Add the `Banner` component to the cart route and link back to the main page:
```javascript {% fileName="cart/src/lib/cart.module.ts" %}
import { NgModule } from '@angular/core';
import { CommonModule } from '@angular/common';
import { RouterModule } from '@angular/router';
import { CartRouteComponent } from './cart-route/cart-route.component';
import { SharedUiModule } from '@store/shared/ui';
@NgModule({
declarations: [CartRouteComponent],
imports: [
CommonModule,
SharedUiModule,
RouterModule.forChild([
{
path: '',
component: CartRouteComponent,
},
]),
],
})
export class CartModule {}
```
```javascript {% fileName="cart/src/lib/cart-route/cart-route.component.html" %}
<store-banner text="Welcome to the cart." ></store-banner>
<a routerLink="/">Continue Shopping</a>
```
### `store`
Update the `shop` component to use the `Banner` component and link to the cart.
```javascript {% fileName="src/app/shop/shop.component.html" %}
<store-banner text="Here is a list of products to buy..." ></store-banner>
<a routerLink="/cart">View Cart</a>
```
Now run `npx nx graph` again:
{% graph height="450px" %}
```json
{
"hash": "85fd0561bd88f0bcd8703a9e9369592e2805f390d04982fb2401e700dc9ebc59",
"projects": [
{
"name": "cart",
"type": "lib",
"data": {
"tags": []
}
},
{
"name": "shared-ui",
"type": "lib",
"data": {
"tags": []
}
},
{
"name": "e2e",
"type": "e2e",
"data": {
"tags": []
}
},
{
"name": "store",
"type": "app",
"data": {
"tags": []
}
}
],
"dependencies": {
"cart": [{ "source": "cart", "target": "shared-ui", "type": "static" }],
"shared-ui": [],
"e2e": [{ "source": "e2e", "target": "store", "type": "implicit" }],
"store": [
{ "source": "store", "target": "cart", "type": "dynamic" },
{ "source": "store", "target": "shared-ui", "type": "static" }
]
},
"workspaceLayout": { "appsDir": "apps", "libsDir": "libs" },
"affectedProjectIds": [],
"focus": null,
"groupByFolder": false,
"exclude": []
}
```
{% /graph %}
Your graph now shows the dependency lines we expected.
The Project Graph is more than just a visualization - Nx provides tooling to optimize your task-running and even automate your CI based on this graph. This will be covered in more detail in: [4: Task Pipelines](/angular-standalone-tutorial/4-task-pipelines).
## What's Next
- Continue to [3: Task Running](/angular-standalone-tutorial/3-task-running)

144
docs/shared/angular-standalone-tutorial/3-task-running.md
View File

@ -1,144 +0,0 @@
# Angular Standalone Tutorial - 3: Task-Running
Common tasks include:
- Building an application
- Serving a local web server with the built project
- Running your unit tests
- Linting your code
- Running e2e tests
When you ran your generators in Part 1, you already set up these common tasks for each project.
## Defining Targets
Here's the `project.json` file for your `shared-ui` project:
```json {% fileName="shared/ui/project.json" %}
{
"name": "shared-ui",
"$schema": "../../node_modules/nx/schemas/project-schema.json",
"projectType": "library",
"sourceRoot": "shared/ui/src",
"prefix": "store",
"targets": {
"build": {
"executor": "@nx/angular:ng-packagr-lite",
"outputs": ["{workspaceRoot}/dist/{projectRoot}"],
"options": {
"project": "shared/ui/ng-package.json"
},
"configurations": {
"production": {
"tsConfig": "shared/ui/tsconfig.lib.prod.json"
},
"development": {
"tsConfig": "shared/ui/tsconfig.lib.json"
}
},
"defaultConfiguration": "production"
},
"test": {
"executor": "@nx/jest:jest",
"outputs": ["{workspaceRoot}/coverage/{projectRoot}"],
"options": {
"jestConfig": "shared/ui/jest.config.ts",
"passWithNoTests": true
}
},
"lint": {
"executor": "@nx/eslint:lint",
"options": {
"lintFilePatterns": ["shared/ui/**/*.ts", "shared/ui/**/*.html"]
}
}
},
"tags": []
}
```
You can see that three targets are defined here: `build`, `test` and `lint`.
The properties inside each of these these targets is defined as follows:
- `executor` - which Nx executor to run. The syntax here is: `<plugin name>:<executor name>`
- `outputs` - this is an array of files that would be created by running this target. (This informs Nx on what to save
for it's caching mechanisms you'll learn about in [4 - Task Pipelines](/angular-standalone-tutorial/4-task-pipelines))
.
- `options` - this is an object defining which executor options to use for the given target. Every Nx executor allows
for options as a way to parameterize it's functionality.
## Running Tasks
![Syntax for Running Tasks in Nx](/shared/images/run-target-syntax.svg)
Run the `test` target for your `shared-ui` project:
```{% command="npx nx test shared-ui" path="~/store" %}
> nx run shared-ui:test
PASS shared-ui shared/ui/src/lib/banner/banner.component.spec.ts
BannerComponent
✓ should create (19 ms)
Test Suites: 1 passed, 1 total
Tests: 1 passed, 1 total
Snapshots: 0 total
Time: 1.561 s
Ran all test suites.
—————————————————————————————————————————————————————————————————————————————————————————————————————————————————
> NX Successfully ran target test for project shared-ui (3s)
```
Next, run a lint check on your `shared-ui` project:
```{% command="npx nx lint shared-ui" path="~/store" %}
> nx run shared-ui:lint
Linting "shared-ui"...
All files pass linting.
———————————————————————————————————————————————————————————————————————————————————————————————————
> NX Successfully ran target lint for project shared-ui (2s)
```
Also, by running the `serve` target for your `store` application, you can run local web server during development that
will allow you to manually check the changes you've made:
```{% command="npx nx serve store" path="~/store" %}
> nx run store:serve:development
✔ Browser application bundle generation complete.
Initial Chunk Files | Names | Raw Size
vendor.js | vendor | 2.04 MB |
polyfills.js | polyfills | 316.06 kB |
styles.css, styles.js | styles | 211.31 kB |
main.js | main | 47.60 kB |
runtime.js | runtime | 12.61 kB |
| Initial Total | 2.62 MB
Lazy Chunk Files | Names | Raw Size
cart_src_index_ts.js | store-cart | 4.93 kB |
Build at: 2023-03-24T10:13:24.014Z - Hash: e52a884fc7a311e1 - Time: 8609ms
** Angular Live Development Server is listening on localhost:4200, open your browser on http://localhost:4200/ **
✔ Compiled successfully.
```
## What's Next
- Continue to [4: Workspace Optimization](/angular-standalone-tutorial/4-task-pipelines)

269
docs/shared/angular-standalone-tutorial/4-task-pipelines.md
View File

@ -1,269 +0,0 @@
# Angular Standalone Tutorial - Part 4: Task Pipelines
## Running Dependent Tasks
Let's build the `store` application:
```{% command="npx nx build store" path="~/store" %}
✔ 1/1 dependent project tasks succeeded [0 read from cache]
Hint: you can run the command with --verbose to see the full dependent project outputs
—————————————————————————————————————————————————————————————————————————————————————————————————————————————————
> nx run store:build:production
✔ Browser application bundle generation complete.
✔ Copying assets complete.
✔ Index html generation complete.
Initial Chunk Files | Names | Raw Size | Estimated Transfer Size
main.dc68f58360ec52f7.js | main | 203.69 kB | 55.81 kB
polyfills.19459ef8805e51da.js | polyfills | 33.04 kB | 10.64 kB
runtime.639feb9584ec9047.js | runtime | 2.62 kB | 1.23 kB
styles.ef46db3751d8e999.css | styles | 0 bytes | -
| Initial Total | 239.35 kB | 67.68 kB
Lazy Chunk Files | Names | Raw Size | Estimated Transfer Size
967.25ab9a0a8950995f.js | store-cart | 719 bytes | 395 bytes
Build at: 2022-11-30T16:44:43.171Z - Hash: 9850ece7cc7c6b7c - Time: 6527ms
—————————————————————————————————————————————————————————————————————————————————————————————————————————————————
> NX Successfully ran target build for project store and 1 task(s) they depend on (9s)
```
Notice this line:
```shell
✔ 1/1 dependent project tasks succeeded [0 read from cache]
```
When you run a task, Nx will run all the task's dependencies before running the task you specified. This ensures all the needed artifacts are in place before the task is run.
## Configuring Task Pipelines
Nx can infer how projects depend on each other by examining the source code, but Nx doesn't know which tasks depend on each other.
In the `nx.json` file you can see the default set up:
```json
{
"targetDefaults": {
"build": {
"dependsOn": ["^build"],
"inputs": ["production", "^production"]
}
}
}
```
The `"dependsOn": ["^build"]` line says that every `build` task depends on the `build` tasks for its project dependencies. You can override the `dependsOn` setting for individual projects in the `project.json` files.
{% card title="More On The Task Pipeline Configuration" description="See the Task Pipeline Configuration Guide for more details on how to configure your Task Graph." url="/concepts/task-pipeline-configuration" /%}
## Skip Repeated Tasks
Why does Nx always run the dependent tasks? Doesn't that waste time repeating the same work?
It would, if Nx didn't have a robust caching mechanism to take care of that problem for you. Let's build the `store` app again.
```{% command="npx nx build store" path="~/store" %}
✔ 1/1 dependent project tasks succeeded [1 read from cache]
Hint: you can run the command with --verbose to see the full dependent project outputs
————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————
> nx run store:build:production [existing outputs match the cache, left as is]
Initial Chunk Files | Names | Raw Size | Estimated Transfer Size
main.dc68f58360ec52f7.js | main | 203.69 kB | 55.81 kB
polyfills.19459ef8805e51da.js | polyfills | 33.04 kB | 10.64 kB
runtime.639feb9584ec9047.js | runtime | 2.62 kB | 1.23 kB
styles.ef46db3751d8e999.css | styles | 0 bytes | -
| Initial Total | 239.35 kB | 67.68 kB
Lazy Chunk Files | Names | Raw Size | Estimated Transfer Size
967.25ab9a0a8950995f.js | store-cart | 719 bytes | 395 bytes
Build at: 2022-11-30T16:44:43.171Z - Hash: 9850ece7cc7c6b7c - Time: 6527ms
————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————
> NX Successfully ran target build for project store and 1 task(s) they depend on (13ms)
Nx read the output from the cache instead of running the command for 2 out of 2 tasks.
```
This time the build only took 13 ms. Also, if you delete the `dist` folder and run the command again, the build output will be recreated.
{% card title="More Task Caching Details" description="See the documentation for more information on caching." url="/core-features/cache-task-results" /%}
## Cache Inputs and Outputs
How does Nx know when to replace a cached task result? And how does Nx know what should be cached?
Nx determines if a project has been modified by looking at the task's defined `inputs`. And then when the task is completed, it caches the terminal output and all the defined file `outputs`.
### Inputs
When you run a task, Nx uses the inputs for your task to create a hash that is used as an index for the task results. If the task has already been run with the same inputs, Nx replays the results stored in the cache.
If this index does not exist, Nx runs the command and if the command succeeds, it stores the result in the cache.
{% card title="More On Customizing Inputs" description="See the Customizing Inputs Guide for more details on how to set inputs for your tasks." url="/recipes/running-tasks/customizing-inputs" /%}
### Outputs
Outputs of the cache include the terminal output created by the task, as well as any files created by the task - for example: the artifact created by running a `build` task.
Here are the outputs defined for the `shared-ui` project:
```json {% fileName="shared/ui/project.json" %}
{
"name": "shared-ui",
"$schema": "../../node_modules/nx/schemas/project-schema.json",
"projectType": "library",
"sourceRoot": "shared/ui/src",
"prefix": "store",
"targets": {
"build": {
"executor": "@nx/angular:ng-packagr-lite",
"outputs": ["{workspaceRoot}/dist/{projectRoot}"],
"options": {
"project": "shared/ui/ng-package.json"
},
"configurations": {
"production": {
"tsConfig": "shared/ui/tsconfig.lib.prod.json"
},
"development": {
"tsConfig": "shared/ui/tsconfig.lib.json"
}
},
"defaultConfiguration": "production"
},
"test": {
"executor": "@nx/jest:jest",
"outputs": ["{workspaceRoot}/coverage/{projectRoot}"],
"options": {
"jestConfig": "shared/ui/jest.config.ts",
"passWithNoTests": true
}
},
"lint": {
"executor": "@nx/eslint:lint",
"options": {
"lintFilePatterns": ["shared/ui/**/*.ts", "shared/ui/**/*.html"]
}
}
},
"tags": []
}
```
Outputs are stored in the cache so that terminal output can be replayed, and any created files can be pulled from your cache, and placed where they were created the original time the task was run.
## Testing Affected Projects
Another way that Nx saves you from unnecessary work is the `affected` command. `affected` is a mechanism that relies on your git metadata to determine the projects in your workspace that were affected by a given commit.
Run the command:
```shell
git add . ; git commit -m "commiting to test affected"
```
Then make a change to the styles of your `cart` project:
```css {% fileName="cart/src/lib/cart-route/cart-route.component.css" %}
a {
color: blue;
}
```
You can visualize how our workspace is affected by this change using the command:
```shell
npx nx affected:graph
```
{% graph height="450px" %}
```json
{
"hash": "85fd0561bd88f0bcd8703a9e9369592e2805f390d04982fb2401e700dc9ebc59",
"projects": [
{
"name": "cart",
"type": "lib",
"data": {
"tags": []
}
},
{
"name": "shared-ui",
"type": "lib",
"data": {
"tags": []
}
},
{
"name": "e2e",
"type": "e2e",
"data": {
"tags": []
}
},
{
"name": "store",
"type": "app",
"data": {
"tags": []
}
}
],
"dependencies": {
"cart": [{ "source": "cart", "target": "shared-ui", "type": "static" }],
"shared-ui": [],
"e2e": [{ "source": "e2e", "target": "store", "type": "implicit" }],
"store": [
{ "source": "store", "target": "cart", "type": "dynamic" },
{ "source": "store", "target": "shared-ui", "type": "static" }
]
},
"workspaceLayout": { "appsDir": "apps", "libsDir": "libs" },
"affectedProjectIds": ["cart", "store", "e2e"],
"focus": null,
"groupByFolder": false,
"exclude": []
}
```
{% /graph %}
The change made to the `cart` project is also affecting the `store` project. This can be leveraged to run tasks only on the projects that were affected by this commit.
To run the `test` targets only for affected projects, run the command:
```shell
npx nx affected -t test
```
This can be particularly helpful in CI pipelines for larger repos, where most commits only affect a small subset of the entire workspace.
{% card title="Affected Documentation" description="Checkout Affected documentation for more details" url="/nx-api/nx/documents/affected" /%}
## What's Next
- Continue to [5: Summary](/angular-standalone-tutorial/5-summary)

22
docs/shared/angular-standalone-tutorial/5-summary.md
View File

@ -1,22 +0,0 @@
# Angular Standalone Tutorial - Part 5: Summary
In this tutorial you:
- Learned how to use Nx's Generators to generate code for your workspace.
- Learned how Nx determines a graph of your workspace
- Learned how to configure and run tasks in your workspace
- Learned how Nx's built-in optimizations work, and how to apply those to your own workspace
## Learn More
{% cards %}
{% card title="Core Features" description="Read about the core features of Nx." url="/core-features" /%}
{% card title="Plugin Features" description="Read about the plugin features of Nx." url="/core-features/plugin-features" /%}
{% card title="Mental Model" description="Get a deeper understanding of the mental model." url="/concepts/mental-model" /%}
{% card title="Adopting Nx" description="Learn how to add Nx to your existing repo." url="/recipes/adopting-nx" /%}
{% /cards %}

293
docs/shared/angular-standalone-tutorial/angular-standalone.md
View File

@ -40,13 +40,13 @@ Create a new Angular application with the following command:
✔ Default stylesheet format · css
✔ Do you want to enable Server-Side Rendering (SSR) and Static Site Generation (SSG/Prerendering)? · No
✔ Test runner to use for end to end (E2E) tests · cypress
✔ Do you want Nx Cloud to make your CI fast? · Yes
✔ Set up CI with caching, distribution and test deflaking · github
```
You get asked a few questions that help Nx preconfigure your new Angular application. These include
- Angular specific questions, such as which bundler to use, whether to enable server-side rendering and which stylesheet format to use
- General Nx questions, such as whether to enable remote caching with Nx Cloud. Nx comes with built-in [local caching](/core-features/cache-task-results). If you want to benefit from this cache in CI, you can enable [remote caching](/ci/features/remote-cache) which will set up [Nx Cloud](https://nx.app). This is also a prerequisite for enabling [distributed task execution](/ci/features/distribute-task-execution).
- General Nx questions, such as whether to enable remote caching with Nx Cloud. Nx comes with built-in [local caching](/features/cache-task-results). If you want to benefit from this cache in CI, you can enable [remote caching](/ci/features/remote-cache) which will set up [Nx Cloud](https://nx.app). This is also a prerequisite for enabling [distributed task execution](/ci/features/distribute-task-execution).
For the sake of this tutorial, let's respond to all the questions with the default response.
@ -104,7 +104,7 @@ Compared to the Angular CLI, you might notice the addition of an `nx.json` file
| File | Description |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `nx.json` | This is where we can fine-tune how Nx works, define the [cacheable operations](/core-features/cache-task-results), our [task pipelines](/concepts/task-pipeline-configuration) as well as defaults for the Nx generators. Find more details in [the reference docs](/reference/nx-json). |
| `nx.json` | This is where we can fine-tune how Nx works, define the [cacheable operations](/features/cache-task-results), our [task pipelines](/concepts/task-pipeline-configuration) as well as defaults for the Nx generators. Find more details in [the reference docs](/reference/nx-json). |
| `project.json` | Nx uses this file to define targets that can be run, similar to how the Angular CLI uses the `angular.json` file. If you're familiar with the Angular CLI you should have no difficulty navigating the `project.json` file. If you're curious how the two compare, you can learn more in [the Nx and Angular CLI comparision article](/concepts/more-concepts/nx-and-angular). The [project-configuration documentation page](/reference/project-configuration) has more details on how to use the `project.json` file. |
## Serving the App
@ -137,7 +137,276 @@ Nx uses the following syntax to run tasks:
![Syntax for Running Tasks in Nx](/shared/images/run-target-syntax.svg)
All targets, such as `serve`, `build`, `test` or your custom ones, are defined in the `project.json` file.
### Inferred Tasks
Nx identifies available tasks for your project from [tooling configuration files](/concepts/inferred-tasks), `package.json` scripts and the targets defined in `project.json`. To view the tasks that Nx has detected, look in the [Nx Console](/features/integrate-with-editors) project detail view or run:
```shell
nx show project myngapp --web
```
{% project-details title="Project Details View" height="100px" %}
```json
{
"project": {
"name": "myngapp",
"data": {
"root": ".",
"includedScripts": [],
"name": "myngapp",
"targets": {
"lint": {
"cache": true,
"inputs": [
"default",
"{workspaceRoot}/.eslintrc.json",
"{workspaceRoot}/tools/eslint-rules/**/*",
{
"externalDependencies": ["eslint"]
}
],
"executor": "nx:run-commands",
"options": {
"cwd": ".",
"command": "eslint ./src"
},
"configurations": {}
},
"test": {
"options": {
"cwd": ".",
"command": "jest"
},
"cache": true,
"inputs": [
"default",
"^production",
{
"externalDependencies": ["jest"]
}
],
"outputs": ["{projectRoot}/coverage/myngapp"],
"executor": "nx:run-commands",
"configurations": {}
},
"build": {
"cache": true,
"dependsOn": ["^build"],
"inputs": ["production", "^production"],
"executor": "@angular-devkit/build-angular:application",
"outputs": ["{options.outputPath}"],
"options": {
"outputPath": "dist/myngapp",
"index": "./src/index.html",
"browser": "./src/main.ts",
"polyfills": ["zone.js"],
"tsConfig": "./tsconfig.app.json",
"assets": ["./src/favicon.ico", "./src/assets"],
"styles": ["./src/styles.css"],
"scripts": []
},
"configurations": {
"production": {
"budgets": [
{
"type": "initial",
"maximumWarning": "500kb",
"maximumError": "1mb"
},
{
"type": "anyComponentStyle",
"maximumWarning": "2kb",
"maximumError": "4kb"
}
],
"outputHashing": "all"
},
"development": {
"optimization": false,
"extractLicenses": false,
"sourceMap": true
}
},
"defaultConfiguration": "production"
},
"serve": {
"executor": "@angular-devkit/build-angular:dev-server",
"configurations": {
"production": {
"buildTarget": "myngapp:build:production"
},
"development": {
"buildTarget": "myngapp:build:development"
}
},
"defaultConfiguration": "development",
"options": {}
},
"extract-i18n": {
"executor": "@angular-devkit/build-angular:extract-i18n",
"options": {
"buildTarget": "myngapp:build"
},
"configurations": {}
},
"serve-static": {
"executor": "@nx/web:file-server",
"options": {
"buildTarget": "myngapp:build",
"staticFilePath": "dist/myngapp/browser"
},
"configurations": {}
}
},
"sourceRoot": "./src",
"projectType": "application",
"$schema": "node_modules/nx/schemas/project-schema.json",
"prefix": "myngapp",
"tags": [],
"implicitDependencies": []
}
},
"sourceMap": {
"root": ["project.json", "nx/core/project-json"],
"includedScripts": ["package.json", "nx/core/package-json-workspaces"],
"name": ["project.json", "nx/core/project-json"],
"targets": ["project.json", "nx/core/project-json"],
"targets.lint": ["project.json", "@nx/eslint/plugin"],
"targets.lint.cache": ["project.json", "@nx/eslint/plugin"],
"targets.lint.options": ["project.json", "@nx/eslint/plugin"],
"targets.lint.inputs": ["project.json", "@nx/eslint/plugin"],
"targets.lint.executor": ["project.json", "@nx/eslint/plugin"],
"targets.lint.options.cwd": ["project.json", "@nx/eslint/plugin"],
"targets.lint.options.command": ["project.json", "@nx/eslint/plugin"],
"targets.test": ["jest.config.ts", "@nx/jest/plugin"],
"targets.test.options": ["jest.config.ts", "@nx/jest/plugin"],
"targets.test.cache": ["jest.config.ts", "@nx/jest/plugin"],
"targets.test.inputs": ["jest.config.ts", "@nx/jest/plugin"],
"targets.test.outputs": ["jest.config.ts", "@nx/jest/plugin"],
"targets.test.executor": ["jest.config.ts", "@nx/jest/plugin"],
"targets.test.options.cwd": ["jest.config.ts", "@nx/jest/plugin"],
"targets.test.options.command": ["jest.config.ts", "@nx/jest/plugin"],
"targets.build": ["project.json", "nx/core/project-json"],
"targets.build.cache": ["project.json", "nx/core/target-defaults"],
"targets.build.dependsOn": ["project.json", "nx/core/target-defaults"],
"targets.build.inputs": ["project.json", "nx/core/target-defaults"],
"sourceRoot": ["project.json", "nx/core/project-json"],
"projectType": ["project.json", "nx/core/project-json"],
"$schema": ["project.json", "nx/core/project-json"],
"prefix": ["project.json", "nx/core/project-json"],
"tags": ["project.json", "nx/core/project-json"],
"targets.build.executor": ["project.json", "nx/core/project-json"],
"targets.build.outputs": ["project.json", "nx/core/project-json"],
"targets.build.options": ["project.json", "nx/core/project-json"],
"targets.build.configurations": ["project.json", "nx/core/project-json"],
"targets.build.defaultConfiguration": [
"project.json",
"nx/core/project-json"
],
"targets.build.options.outputPath": [
"project.json",
"nx/core/project-json"
],
"targets.build.options.index": ["project.json", "nx/core/project-json"],
"targets.build.options.browser": ["project.json", "nx/core/project-json"],
"targets.build.options.polyfills": ["project.json", "nx/core/project-json"],
"targets.build.options.tsConfig": ["project.json", "nx/core/project-json"],
"targets.build.options.assets": ["project.json", "nx/core/project-json"],
"targets.build.options.styles": ["project.json", "nx/core/project-json"],
"targets.build.options.scripts": ["project.json", "nx/core/project-json"],
"targets.build.configurations.production": [
"project.json",
"nx/core/project-json"
],
"targets.build.configurations.production.budgets": [
"project.json",
"nx/core/project-json"
],
"targets.build.configurations.production.outputHashing": [
"project.json",
"nx/core/project-json"
],
"targets.build.configurations.development": [
"project.json",
"nx/core/project-json"
],
"targets.build.configurations.development.optimization": [
"project.json",
"nx/core/project-json"
],
"targets.build.configurations.development.extractLicenses": [
"project.json",
"nx/core/project-json"
],
"targets.build.configurations.development.sourceMap": [
"project.json",
"nx/core/project-json"
],
"targets.serve": ["project.json", "nx/core/project-json"],
"targets.serve.executor": ["project.json", "nx/core/project-json"],
"targets.serve.configurations": ["project.json", "nx/core/project-json"],
"targets.serve.defaultConfiguration": [
"project.json",
"nx/core/project-json"
],
"targets.serve.configurations.production": [
"project.json",
"nx/core/project-json"
],
"targets.serve.configurations.production.buildTarget": [
"project.json",
"nx/core/project-json"
],
"targets.serve.configurations.development": [
"project.json",
"nx/core/project-json"
],
"targets.serve.configurations.development.buildTarget": [
"project.json",
"nx/core/project-json"
],
"targets.extract-i18n": ["project.json", "nx/core/project-json"],
"targets.extract-i18n.executor": ["project.json", "nx/core/project-json"],
"targets.extract-i18n.options": ["project.json", "nx/core/project-json"],
"targets.extract-i18n.options.buildTarget": [
"project.json",
"nx/core/project-json"
],
"targets.serve-static": ["project.json", "nx/core/project-json"],
"targets.serve-static.executor": ["project.json", "nx/core/project-json"],
"targets.serve-static.options": ["project.json", "nx/core/project-json"],
"targets.serve-static.options.buildTarget": [
"project.json",
"nx/core/project-json"
],
"targets.serve-static.options.staticFilePath": [
"project.json",
"nx/core/project-json"
]
}
}
```
{% /project-details %}
If you expand the `test` task, you can see that it was created by the `@nx/jest` plugin by analyzing your `jest.config.ts` file. Notice the outputs are defined as `{projectRoot}/coverage/myngapp`. This value is being read from the `coverageDirectory` defined in your `jest.config.ts` file. Let's change that value in your `jest.config.ts` file:
```ts {% fileName="jest.config.ts" %}
export default {
// ...
coverageDirectory: './coverage/myngapp-changed',
// ...
};
```
Now if you look at the project details view, the outputs for the `test` target will say `{projectRoot}/coverage/angular-store-changed`. This feature ensures that Nx will always cache the correct files.
You can also override the settings for inferred tasks by modifying the [`targetDefaults` in `nx.json`](/reference/nx-json#target-defaults) or setting a value in your [`project.json` file](/reference/project-configuration). Nx will merge the values from the inferred tasks with the values you define in `targetDefaults` and in your specific project's configuration.
### Manually Defined Tasks
The `serve` and `build` tasks are defined in the `project.json` file.
```json {% fileName="project.json"}
{
@ -183,7 +452,7 @@ The most critical parts are:
- `executor` - This corresponds to the `builder` property in an Angular CLI workspace. You can use Angular builders or executors from [Nx plugins](/extending-nx/intro/getting-started).
- `options` - these are additional properties and flags passed to the executor function to customize it
Learn more about how to [run tasks with Nx](/core-features/run-tasks).
Learn more about how to [run tasks with Nx](/features/run-tasks).
## Testing and Linting - Running Multiple Tasks
@ -215,7 +484,7 @@ More conveniently, we can also run them in parallel using the following syntax:
{% video-link link="https://youtu.be/ZAO0yXupIIE?t=443" /%}
One thing to highlight is that Nx is able to [cache the tasks you run](/core-features/cache-task-results).
One thing to highlight is that Nx is able to [cache the tasks you run](/features/cache-task-results).
Note that all of these targets are automatically cached by Nx. If you re-run a single one or all of them again, you'll see that the task completes immediately. In addition, (as can be seen in the output example below) there will be a note that a matching cache result was found and therefore the task was not run again.
@ -233,7 +502,7 @@ Note that all of these targets are automatically cached by Nx. If you re-run a s
Nx read the output from the cache instead of running the command for 4 out of 4 tasks.
```
Not all tasks might be cacheable though. You can configure the `cache` properties in the targets under `targetDefaults` in the `nx.json` file. You can also [learn more about how caching works](/core-features/cache-task-results).
Not all tasks might be cacheable though. You can configure the `cache` properties in the targets under `targetDefaults` in the `nx.json` file. You can also [learn more about how caching works](/features/cache-task-results).
## Creating New Components
@ -289,7 +558,7 @@ Generators allow you to easily scaffold code, configuration or entire projects.
If you prefer a more integrated experience, you can install the "Nx Console" extension for your code editor. It has support for VSCode, IntelliJ and ships a LSP for Vim. Nx Console provides autocompletion support in Nx configuration files and has UIs for browsing and running generators.
More info can be found in [the integrate with editors article](/core-features/integrate-with-editors).
More info can be found in [the integrate with editors article](/features/integrate-with-editors).
{% /callout %}
@ -499,7 +768,7 @@ import { CommonModule } from '@angular/common';
standalone: true,
imports: [CommonModule],
templateUrl: './products.component.html',
styleUrls: ['./products.component.css'],
styleUrl: './products.component.css',
})
export class ProductsComponent {}
```
@ -578,7 +847,7 @@ A couple of notes:
{% video-link link="https://youtu.be/ZAO0yXupIIE?t=958" /%}
Nx automatically detects the dependencies between the various parts of your workspace and builds a [project graph](/core-features/explore-graph). This graph is used by Nx to perform various optimizations such as determining the correct order of execution when running tasks like `nx build`, identifying [affected projects](/core-features/run-tasks#run-tasks-affected-by-a-pr) and more. Interestingly you can also visualize it.
Nx automatically detects the dependencies between the various parts of your workspace and builds a [project graph](/features/explore-graph). This graph is used by Nx to perform various optimizations such as determining the correct order of execution when running tasks like `nx build`, identifying [affected projects](/features/run-tasks#run-tasks-affected-by-a-pr) and more. Interestingly you can also visualize it.
Just run:
@ -812,7 +1081,7 @@ If you have the ESLint plugin installed in your IDE you should immediately see a
![ESLint module boundary error](/shared/images/tutorial-angular-standalone/boundary-rule-violation-vscode.png)
Learn more about how to [enforce module boundaries](/core-features/enforce-module-boundaries).
Learn more about how to [enforce module boundaries](/features/enforce-module-boundaries).
## Migrating to a Monorepo
@ -829,7 +1098,7 @@ Here's some more things you can dive into next:
- Learn more about the [underlying mental model of Nx](/concepts/mental-model)
- Learn about popular generators such as [how to setup Tailwind](/recipes/angular/using-tailwind-css-with-angular-projects) or [add Storybook to your UI library](/recipes/storybook/overview-angular)
- Learn how to [migrate your existing Angular CLI repo to Nx](/recipes/angular/migration/angular)
- [Speed up CI: Run only tasks for project that got changed](/core-features/run-tasks#run-tasks-affected-by-a-pr)
- [Speed up CI: Run only tasks for project that got changed](/features/run-tasks#run-tasks-affected-by-a-pr)
- [Speed up CI: Share your cache](/ci/features/remote-cache)
- [Speed up CI: Distribute your tasks across machines](/ci/features/distribute-task-execution)

412
docs/shared/angular-tutorial/angular-monorepo.md
View File

@ -24,7 +24,7 @@ Nx evolved from being an extension of the Angular CLI to a [fully standalone CLI
Advantages of Nx over the Angular CLI:
- [Cache any target](/core-features/cache-task-results)
- [Cache any target](/features/cache-task-results)
- [Run only tasks affected by a code change](/ci/features/affected)
- [Split a large angular.json into multiple project.json files](/concepts/more-concepts/nx-and-angular#projectjson-vs-angularjson)
- [Integrate with modern tools](/concepts/more-concepts/nx-and-angular#integrating-with-modern-tools)
@ -125,7 +125,389 @@ Nx uses the following syntax to run tasks:
![Syntax for Running Tasks in Nx](/shared/images/run-target-syntax.svg)
All targets, such as `serve`, `build`, `test` or your custom ones, are defined in the `project.json` file.
### Inferred Tasks
Nx identifies available tasks for your project from [tooling configuration files](/concepts/inferred-tasks), `package.json` scripts and the targets defined in `project.json`. To view the tasks that Nx has detected, look in the [Nx Console](/features/integrate-with-editors) project detail view or run:
```shell
nx show project angular-store --web
```
{% project-details title="Project Details View" height="100px" %}
```json
{
"project": {
"name": "angular-store",
"data": {
"root": "apps/angular-store",
"targets": {
"lint": {
"cache": true,
"options": {
"cwd": "apps/angular-store",
"command": "eslint ."
},
"inputs": [
"default",
"{workspaceRoot}/.eslintrc.json",
"{workspaceRoot}/apps/angular-store/.eslintrc.json",
"{workspaceRoot}/tools/eslint-rules/**/*",
{
"externalDependencies": ["eslint"]
}
],
"executor": "nx:run-commands",
"configurations": {}
},
"test": {
"options": {
"cwd": "apps/angular-store",
"command": "jest"
},
"cache": true,
"inputs": [
"default",
"^production",
{
"externalDependencies": ["jest"]
}
],
"outputs": ["{workspaceRoot}/coverage/apps/angular-store"],
"executor": "nx:run-commands",
"configurations": {}
},
"build": {
"cache": true,
"dependsOn": ["^build"],
"inputs": ["production", "^production"],
"executor": "@angular-devkit/build-angular:application",
"outputs": ["{options.outputPath}"],
"options": {
"outputPath": "dist/apps/angular-store",
"index": "apps/angular-store/src/index.html",
"browser": "apps/angular-store/src/main.ts",
"polyfills": ["zone.js"],
"tsConfig": "apps/angular-store/tsconfig.app.json",
"assets": [
"apps/angular-store/src/favicon.ico",
"apps/angular-store/src/assets"
],
"styles": ["apps/angular-store/src/styles.css"],
"scripts": []
},
"configurations": {
"production": {
"budgets": [
{
"type": "initial",
"maximumWarning": "500kb",
"maximumError": "1mb"
},
{
"type": "anyComponentStyle",
"maximumWarning": "2kb",
"maximumError": "4kb"
}
],
"outputHashing": "all"
},
"development": {
"optimization": false,
"extractLicenses": false,
"sourceMap": true
}
},
"defaultConfiguration": "production"
},
"serve": {
"executor": "@angular-devkit/build-angular:dev-server",
"configurations": {
"production": {
"buildTarget": "angular-store:build:production"
},
"development": {
"buildTarget": "angular-store:build:development"
}
},
"defaultConfiguration": "development",
"options": {}
},
"extract-i18n": {
"executor": "@angular-devkit/build-angular:extract-i18n",
"options": {
"buildTarget": "angular-store:build"
},
"configurations": {}
},
"serve-static": {
"executor": "@nx/web:file-server",
"options": {
"buildTarget": "angular-store:build",
"staticFilePath": "dist/apps/angular-store/browser"
},
"configurations": {}
}
},
"name": "angular-store",
"$schema": "../../node_modules/nx/schemas/project-schema.json",
"projectType": "application",
"prefix": "angular-monorepo",
"sourceRoot": "apps/angular-store/src",
"tags": [],
"implicitDependencies": []
}
},
"sourceMap": {
"root": ["apps/angular-store/project.json", "nx/core/project-json"],
"targets": ["apps/angular-store/project.json", "nx/core/project-json"],
"targets.lint": ["apps/angular-store/project.json", "@nx/eslint/plugin"],
"targets.lint.cache": [
"apps/angular-store/project.json",
"@nx/eslint/plugin"
],
"targets.lint.options": [
"apps/angular-store/project.json",
"@nx/eslint/plugin"
],
"targets.lint.inputs": [
"apps/angular-store/project.json",
"@nx/eslint/plugin"
],
"targets.lint.executor": [
"apps/angular-store/project.json",
"@nx/eslint/plugin"
],
"targets.lint.options.cwd": [
"apps/angular-store/project.json",
"@nx/eslint/plugin"
],
"targets.lint.options.command": [
"apps/angular-store/project.json",
"@nx/eslint/plugin"
],
"targets.test": ["apps/angular-store/jest.config.ts", "@nx/jest/plugin"],
"targets.test.options": [
"apps/angular-store/jest.config.ts",
"@nx/jest/plugin"
],
"targets.test.cache": [
"apps/angular-store/jest.config.ts",
"@nx/jest/plugin"
],
"targets.test.inputs": [
"apps/angular-store/jest.config.ts",
"@nx/jest/plugin"
],
"targets.test.outputs": [
"apps/angular-store/jest.config.ts",
"@nx/jest/plugin"
],
"targets.test.executor": [
"apps/angular-store/jest.config.ts",
"@nx/jest/plugin"
],
"targets.test.options.cwd": [
"apps/angular-store/jest.config.ts",
"@nx/jest/plugin"
],
"targets.test.options.command": [
"apps/angular-store/jest.config.ts",
"@nx/jest/plugin"
],
"targets.build": [
"apps/angular-store/project.json",
"nx/core/project-json"
],
"targets.build.cache": [
"apps/angular-store/project.json",
"nx/core/target-defaults"
],
"targets.build.dependsOn": [
"apps/angular-store/project.json",
"nx/core/target-defaults"
],
"targets.build.inputs": [
"apps/angular-store/project.json",
"nx/core/target-defaults"
],
"name": ["apps/angular-store/project.json", "nx/core/project-json"],
"$schema": ["apps/angular-store/project.json", "nx/core/project-json"],
"projectType": ["apps/angular-store/project.json", "nx/core/project-json"],
"prefix": ["apps/angular-store/project.json", "nx/core/project-json"],
"sourceRoot": ["apps/angular-store/project.json", "nx/core/project-json"],
"tags": ["apps/angular-store/project.json", "nx/core/project-json"],
"targets.build.executor": [
"apps/angular-store/project.json",
"nx/core/project-json"
],
"targets.build.outputs": [
"apps/angular-store/project.json",
"nx/core/project-json"
],
"targets.build.options": [
"apps/angular-store/project.json",
"nx/core/project-json"
],
"targets.build.configurations": [
"apps/angular-store/project.json",
"nx/core/project-json"
],
"targets.build.defaultConfiguration": [
"apps/angular-store/project.json",
"nx/core/project-json"
],
"targets.build.options.outputPath": [
"apps/angular-store/project.json",
"nx/core/project-json"
],
"targets.build.options.index": [
"apps/angular-store/project.json",
"nx/core/project-json"
],
"targets.build.options.browser": [
"apps/angular-store/project.json",
"nx/core/project-json"
],
"targets.build.options.polyfills": [
"apps/angular-store/project.json",
"nx/core/project-json"
],
"targets.build.options.tsConfig": [
"apps/angular-store/project.json",
"nx/core/project-json"
],
"targets.build.options.assets": [
"apps/angular-store/project.json",
"nx/core/project-json"
],
"targets.build.options.styles": [
"apps/angular-store/project.json",
"nx/core/project-json"
],
"targets.build.options.scripts": [
"apps/angular-store/project.json",
"nx/core/project-json"
],
"targets.build.configurations.production": [
"apps/angular-store/project.json",
"nx/core/project-json"
],
"targets.build.configurations.production.budgets": [
"apps/angular-store/project.json",
"nx/core/project-json"
],
"targets.build.configurations.production.outputHashing": [
"apps/angular-store/project.json",
"nx/core/project-json"
],
"targets.build.configurations.development": [
"apps/angular-store/project.json",
"nx/core/project-json"
],
"targets.build.configurations.development.optimization": [
"apps/angular-store/project.json",
"nx/core/project-json"
],
"targets.build.configurations.development.extractLicenses": [
"apps/angular-store/project.json",
"nx/core/project-json"
],
"targets.build.configurations.development.sourceMap": [
"apps/angular-store/project.json",
"nx/core/project-json"
],
"targets.serve": [
"apps/angular-store/project.json",
"nx/core/project-json"
],
"targets.serve.executor": [
"apps/angular-store/project.json",
"nx/core/project-json"
],
"targets.serve.configurations": [
"apps/angular-store/project.json",
"nx/core/project-json"
],
"targets.serve.defaultConfiguration": [
"apps/angular-store/project.json",
"nx/core/project-json"
],
"targets.serve.configurations.production": [
"apps/angular-store/project.json",
"nx/core/project-json"
],
"targets.serve.configurations.production.buildTarget": [
"apps/angular-store/project.json",
"nx/core/project-json"
],
"targets.serve.configurations.development": [
"apps/angular-store/project.json",
"nx/core/project-json"
],
"targets.serve.configurations.development.buildTarget": [
"apps/angular-store/project.json",
"nx/core/project-json"
],
"targets.extract-i18n": [
"apps/angular-store/project.json",
"nx/core/project-json"
],
"targets.extract-i18n.executor": [
"apps/angular-store/project.json",
"nx/core/project-json"
],
"targets.extract-i18n.options": [
"apps/angular-store/project.json",
"nx/core/project-json"
],
"targets.extract-i18n.options.buildTarget": [
"apps/angular-store/project.json",
"nx/core/project-json"
],
"targets.serve-static": [
"apps/angular-store/project.json",
"nx/core/project-json"
],
"targets.serve-static.executor": [
"apps/angular-store/project.json",
"nx/core/project-json"
],
"targets.serve-static.options": [
"apps/angular-store/project.json",
"nx/core/project-json"
],
"targets.serve-static.options.buildTarget": [
"apps/angular-store/project.json",
"nx/core/project-json"
],
"targets.serve-static.options.staticFilePath": [
"apps/angular-store/project.json",
"nx/core/project-json"
]
}
}
```
{% /project-details %}
If you expand the `test` task, you can see that it was created by the `@nx/jest` plugin by analyzing your `jest.config.ts` file. Notice the outputs are defined as `{workspaceRoot}/coverage/apps/angular-store`. This value is being read from the `coverageDirectory` defined in your `jest.config.ts` file. Let's change that value in your `jest.config.ts` file:
```ts {% fileName="apps/angular-store/jest.config.ts" %}
export default {
// ...
coverageDirectory: '../../coverage/apps/angular-store-changed',
// ...
};
```
Now if you look at the project details view, the outputs for the `test` target will say `{workspaceRoot}/coverage/apps/angular-store-changed`. This feature ensures that Nx will always cache the correct files.
You can also override the settings for inferred tasks by modifying the [`targetDefaults` in `nx.json`](/reference/nx-json#target-defaults) or setting a value in your [`project.json` file](/reference/project-configuration). Nx will merge the values from the inferred tasks with the values you define in `targetDefaults` and in your specific project's configuration.
### Manually Defined Tasks
The `serve` and `build` tasks are defined in the `project.json` file.
```json {% fileName="apps/angular-store/project.json"}
{
@ -135,8 +517,6 @@ All targets, such as `serve`, `build`, `test` or your custom ones, are defined i
"build": { ... },
"serve": { ... },
"extract-i18n": { ... },
"lint": { ... },
"test": { ... },
"serve-static": { ... },
},
}
@ -176,13 +556,13 @@ The most critical parts are:
- `executor` - this is of the syntax `<plugin>:<executor-name>`, where the `plugin` is an NPM package containing an [Nx Plugin](/extending-nx/intro/getting-started) and `<executor-name>` points to a function that runs the task.
- `options` - these are additional properties and flags passed to the executor function to customize it
Learn more about how to [run tasks with Nx](/core-features/run-tasks). We'll [revisit running tasks](#testing-and-linting-running-multiple-tasks) later in this tutorial.
Learn more about how to [run tasks with Nx](/features/run-tasks). We'll [revisit running tasks](#testing-and-linting-running-multiple-tasks) later in this tutorial.
## Adding Another Application
<!-- {% video-link link="https://youtu.be/OQ-Zc5tcxJE?t=706" /%} -->
Nx plugins usually provide [generators](/core-features/plugin-features/use-code-generators) that allow you to easily scaffold code, configuration or entire projects. To see what capabilities the `@nx/angular` plugin provides, run the following command and inspect the output:
Nx plugins usually provide [generators](/features/generate-code) that allow you to easily scaffold code, configuration or entire projects. To see what capabilities the `@nx/angular` plugin provides, run the following command and inspect the output:
```{% command="npx nx list @nx/angular" path="angular-monorepo" %}
@ -221,7 +601,7 @@ This executor is similar to the `@angular-devkit/build-angular:ng-packagr` with
If you prefer a more integrated experience, you can install the "Nx Console" extension for your code editor. It has support for VSCode, IntelliJ and ships a LSP for Vim. Nx Console provides autocompletion support in Nx configuration files and has UIs for browsing and running generators.
More info can be found in [the integrate with editors article](/core-features/integrate-with-editors).
More info can be found in [the integrate with editors article](/features/integrate-with-editors).
{% /callout %}
@ -385,7 +765,7 @@ All libraries that we generate automatically have aliases created in the root-le
Hence we can easily import them into other libraries and our Angular application. As an example, let's create and expose a `ProductListComponent` component from our `libs/products` library. Either create it by hand or run
```shell
nx g @nx/angular:component product-list --directory=libs/products/src/lib/product-list --nameAndDirectoryFormat=as-provided --standalone --export
nx g @nx/angular:component product-list --directory=libs/products/src/lib/product-list --standalone --export
```
We don't need to implement anything fancy as we just want to learn how to import it into our main Angular application.
@ -503,7 +883,7 @@ export class AppComponent {
<!-- {% video-link link="https://youtu.be/OQ-Zc5tcxJE?t=1416" /%} -->
Nx automatically detects the dependencies between the various parts of your workspace and builds a [project graph](/core-features/explore-graph). This graph is used by Nx to perform various optimizations such as determining the correct order of execution when running tasks like `nx build`, identifying [affected projects](/core-features/run-tasks#run-tasks-affected-by-a-pr) and more. Interestingly you can also visualize it.
Nx automatically detects the dependencies between the various parts of your workspace and builds a [project graph](/features/explore-graph). This graph is used by Nx to perform various optimizations such as determining the correct order of execution when running tasks like `nx build`, identifying [affected projects](/features/run-tasks#run-tasks-affected-by-a-pr) and more. Interestingly you can also visualize it.
Just run:
@ -624,7 +1004,7 @@ nx run-many -t test lint e2e
### Caching
One thing to highlight is that Nx is able to [cache the tasks you run](/core-features/cache-task-results).
One thing to highlight is that Nx is able to [cache the tasks you run](/features/cache-task-results).
Note that all of these targets are automatically cached by Nx. If you re-run a single one or all of them again, you'll see that the task completes immediately. In addition, (as can be seen in the output example below) there will be a note that a matching cache result was found and therefore the task was not run again.
@ -642,7 +1022,7 @@ Note that all of these targets are automatically cached by Nx. If you re-run a s
Nx read the output from the cache instead of running the command for 10 out of 10 tasks.
```
Not all tasks might be cacheable though. You can configure `cacheableOperations` in the `nx.json` file. You can also [learn more about how caching works](/core-features/cache-task-results).
Not all tasks might be cacheable though. You can configure `cacheableOperations` in the `nx.json` file. You can also [learn more about how caching works](/features/cache-task-results).
### Testing Affected Projects
@ -835,7 +1215,7 @@ Nx comes with a generic mechanism that allows you to assign "tags" to projects.
```json {% fileName="libs/orders/project.json" %}
{
...
"tags": ["type:feature", "scope:orders"]
"tags": ["type:feature", "scope:orders"],
}
```
@ -844,7 +1224,7 @@ Then go to the `project.json` of your `products` library and assign the tags `ty
```json {% fileName="libs/products/project.json" %}
{
...
"tags": ["type:feature", "scope:products"]
"tags": ["type:feature", "scope:products"],
}
```
@ -853,7 +1233,7 @@ Finally, go to the `project.json` of the `shared-ui` library and assign the tags
```json {% fileName="libs/shared/ui/project.json" %}
{
...
"tags": ["type:ui", "scope:shared"]
"tags": ["type:ui", "scope:shared"],
}
```
@ -977,7 +1357,7 @@ If you have the ESLint plugin installed in your IDE you should immediately see a
![ESLint module boundary error](/shared/angular-tutorial/module-boundary-lint-rule.png)
Learn more about how to [enforce module boundaries](/core-features/enforce-module-boundaries).
Learn more about how to [enforce module boundaries](/features/enforce-module-boundaries).
## Setting Up CI
@ -1012,7 +1392,7 @@ Here's some more things you can dive into next:
- Learn about popular generators such as [how to setup Tailwind](/recipes/angular/using-tailwind-css-with-angular-projects)
- Learn how to [migrate your existing Angular CLI repo to Nx](/recipes/angular/migration/angular)
- [Setup Storybook for our shared UI library](/recipes/storybook/overview-angular)
- [Speed up CI: Run only tasks for project that got changed](/core-features/run-tasks#run-tasks-affected-by-a-pr)
- [Speed up CI: Run only tasks for project that got changed](/features/run-tasks#run-tasks-affected-by-a-pr)
- [Speed up CI: Share your cache](/ci/features/remote-cache)
- [Speed up CI: Distribute your tasks across machines](/ci/features/distribute-task-execution)

22
docs/shared/concepts/how-caching-works.md
View File

@ -1,6 +1,6 @@
# How Caching Works
Before running any task, Nx computes its computation hash. As long as the computation hash is the same, the output of
Before running any cacheable task, Nx computes its computation hash. As long as the computation hash is the same, the output of
running the task is the same.
By default, the computation hash for something like `nx test remixapp` includes:
@ -40,13 +40,25 @@ As your workspace grows, the task graph looks more like this:
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.
## Fine-tuning Nx's Cache
Each cacheable task defines a set of inputs and outputs. Inputs are factors Nx considers when calculating the computation hash.
Outputs are files that will be cached and restored when the computation hash matches.
For more information on how to fine-tune caching, see the [Fine-tuning Caching with Inputs recipe](/recipes/running-tasks/configure-inputs).
### Inputs
Inputs are factors Nx considers when calculating the computation hash for a task.
For more information on the different types of inputs and how to configure inputs for your tasks, read the [Fine-tuning Caching with Inputs recipe](/recipes/running-tasks/configure-inputs)
## What is Cached
Nx works on the process level. Regardless of the tools used to build/test/lint/etc.. your project, the results are cached.
It sets up hooks to collect stdout/stderr before running the command. All the output is cached and then replayed during a cache hit.
It collects terminal output when running tasks. All the terminal output is cached and then replayed during a cache hit.
Nx also caches the files generated by a command. The list of files/folders is listed in the `outputs` property of the project's `package.json` or `project.json`:
Nx can also cache the files generated by a task. The list of files/folders is listed in the `outputs` property of the project's `package.json` or `project.json`:
{% tabs %}
{% tab label="package.json" %}
@ -162,7 +174,7 @@ Inputs may include
- runtime inputs
- command line arguments
Learn more about fine tuning caching in the [Fine-tuning Caching with Inputs page](/recipes/running-tasks/customizing-inputs).
Learn more about fine tuning caching in the [Fine-tuning Caching with Inputs page](/recipes/running-tasks/configure-inputs).
## Args Hash Inputs
@ -199,4 +211,4 @@ npx nx build footer
Learn more about how to configure caching, where the cache is stored, how to reset it and more.
- [Cache Task Results](/core-features/cache-task-results)
- [Cache Task Results](/features/cache-task-results)

4
docs/shared/concepts/illustrated-dte-guide.md
View File

@ -8,7 +8,7 @@ The illustrations in this guide are created by Nrwlian [Nicole Oliver](https://t
![what's a task? project + target (i.e. shared-product-ui + test). each run contains many tasks. affected:test contains shared-product-ui:test, product-page:test, shared-e2e-util:test and shared-ui:test](/shared/images/dte/whats-a-task.jpeg)
A task, from Nx's perspective, is a target running on a project. i.e. The target `test` running on the project `shared-product-ui` is a task. For more information about tasks, see the [Run Tasks article](/core-features/run-tasks).
A task, from Nx's perspective, is a target running on a project. i.e. The target `test` running on the project `shared-product-ui` is a task. For more information about tasks, see the [Run Tasks article](/features/run-tasks).
## Nx Cloud Schedules Your CI Tasks Automatically
@ -28,7 +28,7 @@ When you set up DTE, you define (1) the tasks that you want to run and (2) the n
![but don't some tasks depend on others' results? Yep! Nx knows about your dependency tree, so it will execute tasks in the right order and make sure the results are available where they're needed.](/shared/images/dte/task-dependencies.jpeg)
There are some tasks that need to be executed before other tasks, but Nx Cloud takes that into account when it assigns tasks to agents. For a more detailed look at defining those dependencies, read the [Run Tasks article](/core-features/run-tasks).
There are some tasks that need to be executed before other tasks, but Nx Cloud takes that into account when it assigns tasks to agents. For a more detailed look at defining those dependencies, read the [Run Tasks article](/features/run-tasks).
## Why Distribute Tasks?

BIN
docs/shared/concepts/inferred-target-config.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 56 KiB

67
docs/shared/concepts/inferred-tasks.md Normal file
View File

@ -0,0 +1,67 @@
# Inferred Tasks
In Nx version 18, many Nx plugins will automatically infer tasks for your projects based on the configuration of different tools. Many tools have configuration files which determine what a tool does. Nx is able to cache the results of running the tool. Nx plugins use the same configuration files to infer how Nx should [run the task](/features/run-tasks). This includes [fine-tuned cache settings](/features/cache-task-results) and automatic [task dependencies](/concepts/task-pipeline-configuration).
For example, the `@nx/webpack` plugin infers tasks to run webpack through Nx based on your repository's webpack configuration. This configuration already defines the destination of your build files, so Nx reads that value and caches the correct output files.
## How Does a Plugin Infer Tasks?
Every plugin has its own custom logic, but in order to infer tasks, they all go through the following steps.
### 1. Detect Tooling Configuration in Workspace
The plugin will search the workspace for configuration files of the tool. For each configuration file found, the plugin will infer tasks. i.e. The `@nx/webpack` plugin searches for `webpack.config.js` files to infer tasks that run webpack.
### 2. Create an Inferred Task
The plugin then configures tasks with a name that you specified in the plugin's configuration in `nx.json`. The settings for the task are determined by the tool configuration.
The `@nx/webpack` plugin creates tasks named `build`, `serve` and `preview` by default and it automatically sets the task caching settings based on the values in the webpack configuration files.
## What Is Inferred
Nx plugins infer the following properties by analyzing the tool configuration.
- Command - How is the tool invoked
- [Cacheability](/concepts/how-caching-works) - Whether the task will be cached by Nx. When the Inputs have not changed the Outputs will be restored from the cache.
- [Inputs](/recipes/running-tasks/configure-inputs) - Inputs are used by the task to produce Outputs. Inputs are used to determine when the Outputs of a task can be restored from the cache.
- [Outputs](/recipes/running-tasks/configure-outputs) - Outputs are the results of a task. Outputs are restored from the cache when the Inputs are the same as a previous run.
- [Task Dependencies](/concepts/task-pipeline-configuration) - The list of other tasks which must be completed before running this task.
## Nx Uses Plugins to Build the Graph
A typical workspace will have many plugins inferring tasks. Nx processes all the plugins registered in `nx.json` to create project configuration for individual projects and a project and task graph that shows the connections between them all.
### Plugin Order Matters
Plugins are processed in the order that they appear in the `plugins` array in `nx.json`. So, if multiple plugins create a task with the same name, the plugin listed last will win. If, for some reason, you have a project with both a `vite.config.js` file and a `webpack.config.js` file, both the `@nx/vite` plugin and the `@nx/webpack` plugin will try to create a `build` task. The `build` task that is executed will be the task that belongs to the plugin listed lower in the `plugins` array.
## View Inferred Tasks
To view the task settings for projects in your workspace, [show the project details](/features/explore-graph) either from the command line or using Nx Console.
```shell
nx show project my-project --web
```
{% project-details jsonFile="shared/concepts/myreactapp.json"%}
{% /project-details %}
## Overriding Inferred Task Configuration
You can override the task configuration inferred by plugins in several ways.
If you want to overwrite the task configuration for multiple projects, [use the `targetDefaults` object](/reference/nx-json#target-defaults) in the `nx.json` file.
If you only want to override the task configuration for a specific project, [update that project's configuration](/reference/project-configuration) in `package.json` or `project.json`.
This configuration is more specific so it will override both the inferred configuration and the `targetDefaults`.
The order of precedence for task configuration is:
1. Inferred Task Configurations from plugins in `nx.json`.
2. `targetDefaults` in `nx.json`.
3. Project Configuration in `package.json` or `project.json`.
More details about how to override task configuration is available in these recipes:
- [Configure Inputs for Task Caching](/recipes/running-tasks/configure-inputs)
- [Configure Outputs for Task Caching](/recipes/running-tasks/configure-outputs)
- [Defining a Task Pipeline](/recipes/running-tasks/defining-task-pipeline)

34
docs/shared/concepts/integrated-vs-package-based.md
View File

@ -1,9 +1,12 @@
# Integrated Repos vs. Package-Based Repos vs. Standalone Apps
There are two styles of monorepos that you can build with Nx: integrated repos and package-based repos. At the most basic level, package-based repos utilize Nx's core features while integrated repos also use the plugin features. But the difference is more about the mindset than the features used and the style choice is on a spectrum - not a boolean.
There are many different ways to structure a repository and Nx is designed to support them all. To better discuss how Nx can improve a repository, it is helpful to define some terms.
- Package-based repos focus on flexibility and ease of adoption.
- Integrated repos focus on efficiency and ease of maintenance.
- Standalone Application - A repository with a single application
- Package-Based Repository - A repository with multiple projects that depend on each other via `package.json` and often have nested `node_modules`
- Integrated Repository - A repository with multiple projects that depend on each other via typescript imports and often employ a single version policy
Nx's features can be enabled in each of these types of repositories. Just as each repository is unique and may not exactly fit in one of these categories, the way Nx is used will vary between repositories.
{% cards %}
{% card title="Packaged based vs Integrated Style - Use Nx however it works best for you" description="Choose your style and what works best for you!" type="video" url="https://youtu.be/ArmERpNvC8Y" /%}
@ -15,7 +18,13 @@ There are two styles of monorepos that you can build with Nx: integrated repos a
A package-based repo is a collection of packages that depend on each other via `package.json` files and nested `node_modules`. With this setup, you typically have [different dependencies for each project](/concepts/more-concepts/dependency-management). Build tools like Jest and Webpack work as usual, since everything is resolved as if each package was in a separate repo and all of its dependencies were published to npm. Moving an existing package into a package-based repo is very easy since you generally leave that package's existing build tooling untouched. Creating a new package inside the repo is just as difficult as spinning up a new repo since you have to create all the build tooling from scratch.
Lerna, Yarn, Lage, [Turborepo](/concepts/more-concepts/turbo-and-nx) and Nx (without plugins) support this style.
Lerna, Yarn, Lage, [Turborepo](/concepts/more-concepts/turbo-and-nx) and Nx support this style.
Someone who appreciates the flexibility of a package-based repository will be most interested in the following features of Nx:
- Add [caching](/features/cache-task-results) and [task orchestration](/features/run-tasks) without modifying tooling or file structure
- Import existing projects into the repo without modifying their tooling
- Easily create new projects or tools with [code generators](/features/generate-code)
{% cards %}
{% card title="Tutorial: Getting Started with Package-Based Repos" description="Walkthrough for creating a package-based monorepo with Nx" type="documentation" url="/getting-started/tutorials/package-based-repo-tutorial" /%}
@ -25,7 +34,13 @@ Lerna, Yarn, Lage, [Turborepo](/concepts/more-concepts/turbo-and-nx) and Nx (wit
An integrated repo contains projects that depend on each other through standard import statements. There is typically a [single version of every dependency](/concepts/more-concepts/dependency-management) defined at the root. Sometimes build tools like Jest and Webpack need to be wrapped to work correctly. It's harder to add an existing package to this repo style because the build tooling for that package may need to be modified. It's straightforward to add a brand-new project to the repo because all the tooling decisions have already been made.
Bazel and Nx (with plugins) support this style.
Bazel and Nx support this style.
Someone who appreciates the structure and consistency of an integrated repository will be most interested in the following features of Nx:
- [Enforce architectural decisions](/features/enforce-module-boundaries) with tagging rules
- Encourage consistency with custom [code generators](/features/generate-code)
- [Automate updating dependencies](/features/automate-updating-dependencies) of the entire toolchain
{% cards %}
{% card title="Tutorial: Getting Started with Integrated Repos" description="Walkthrough for creating an integrated monorepo with Nx" type="documentation" url="/getting-started/tutorials/integrated-repo-tutorial" /%}
@ -33,7 +48,12 @@ Bazel and Nx (with plugins) support this style.
## Standalone Applications
Nx plugins, especially the [generators](/core-features/plugin-features/use-code-generators), [executors](/core-features/plugin-features/use-task-executors) and [migrations](/core-features/automate-updating-dependencies) that come with them, are not only valuable for a monorepo scenario. In fact, many developers use Nx not primarily for its monorepo support, but for its tooling support, particularly its ability to modularize a codebase and, thus, better scale it. In v15.3, Nx introduced support for Standalone Applications. It is like an integrated monorepo setup, but with just a single, root-level application. Think of it as an advanced, more capable Create-React-App or Angular CLI. And obviously, you can still leverage all the generators and executors and structure your application into libraries or submodules.
Nx plugins, especially the [generators](/features/generate-code), [executors](/concepts/executors-and-configurations) and [migrations](/features/automate-updating-dependencies) that come with them, are not only valuable for a monorepo scenario. In fact, many developers use Nx not primarily for its monorepo support, but for its tooling support, particularly its ability to modularize a codebase and, thus, better scale it. In v15.3, Nx introduced support for Standalone Applications. It is like an integrated monorepo setup, but with just a single, root-level application. Think of it as an advanced, more capable Create-React-App or Angular CLI. And obviously, you can still leverage all the generators and executors and structure your application into libraries or submodules.
Someone whose main focus is on improving their single application will be most interested in the following features of Nx:
- Set up a [fast CI system](/ci/intro/ci-with-nx) without CI expertise
- Easily [add new tooling](/plugin-registry)
{% cards %}
{% card title="Standalone Applications with Nx" description="Learn what Standlone Apps are and how Nx can be useful" type="video" url="https://youtu.be/qEaVzh-oBBc" /%}
@ -43,7 +63,7 @@ Nx plugins, especially the [generators](/core-features/plugin-features/use-code-
## How to Choose
Nx itself doesn't care which style you choose. You can have a package-based repo setup and still host projects that use Nx plugins from the integrated repo setup. Hence you end up with a "hybrid" approach. Similarly, a Standalone App workspace setup is none other than an integrated Nx monorepo, but with only one application using a different folder layout.
Nx itself doesn't care which style you choose. You can use all the features of Nx whether you are in a package based repo or integrated repo. Certain Nx features will be more or less valuable for a standalone app, but all the features of Nx are still available to be put in place as soon as that repo grows to include more apps.
You can be successful working in any style, and there are ways to transition between them. At a high level

213
docs/shared/concepts/myreactapp.json Normal file
View File

@ -0,0 +1,213 @@
{
"project": {
"name": "myreactapp",
"type": "app",
"data": {
"root": "apps/myreactapp",
"targets": {
"build": {
"options": {
"cwd": "apps/apps/myreactapp",
"command": "vite build"
},
"cache": true,
"dependsOn": ["^build"],
"inputs": [
"production",
"^production",
{
"externalDependencies": ["vite"]
}
],
"outputs": ["{workspaceRoot}/dist/apps/app1"],
"executor": "nx:run-commands",
"configurations": {}
},
"serve": {
"options": {
"cwd": "apps/apps/myreactapp",
"command": "vite serve"
},
"executor": "nx:run-commands",
"configurations": {}
},
"preview": {
"options": {
"cwd": "apps/apps/myreactapp",
"command": "vite preview"
},
"executor": "nx:run-commands",
"configurations": {}
},
"serve-static": {
"executor": "@nx/web:file-server",
"options": {
"buildTarget": "build"
},
"configurations": {}
},
"test": {
"options": {
"cwd": "apps/apps/myreactapp",
"command": "vitest run"
},
"cache": true,
"inputs": [
"default",
"^production",
{
"externalDependencies": ["vitest"]
}
],
"outputs": ["{workspaceRoot}/coverage/apps/app1"],
"executor": "nx:run-commands",
"configurations": {}
},
"lint": {
"cache": true,
"options": {
"cwd": "apps/myreactapp",
"command": "eslint ."
},
"inputs": [
"default",
"{workspaceRoot}/.eslintrc.json",
"{workspaceRoot}/apps/myreactapp/.eslintrc.json",
"{workspaceRoot}/tools/eslint-rules/**/*",
{
"externalDependencies": ["eslint"]
}
],
"executor": "nx:run-commands",
"configurations": {}
}
},
"name": "myreactapp",
"$schema": "../../../node_modules/nx/schemas/project-schema.json",
"sourceRoot": "apps/apps/myreactapp/src",
"projectType": "application",
"tags": [],
"implicitDependencies": []
}
},
"sourceMap": {
"root": ["apps/myreactapp/project.json", "nx/core/project-json"],
"targets": ["apps/myreactapp/project.json", "nx/core/project-json"],
"targets.build": ["apps/myreactapp/vite.config.ts", "@nx/vite/plugin"],
"targets.build.command": [
"apps/myreactapp/vite.config.ts",
"@nx/vite/plugin"
],
"targets.build.options": [
"apps/myreactapp/vite.config.ts",
"@nx/vite/plugin"
],
"targets.build.cache": [
"apps/myreactapp/vite.config.ts",
"@nx/vite/plugin"
],
"targets.build.dependsOn": [
"apps/myreactapp/vite.config.ts",
"@nx/vite/plugin"
],
"targets.build.inputs": [
"apps/myreactapp/vite.config.ts",
"@nx/vite/plugin"
],
"targets.build.outputs": [
"apps/myreactapp/vite.config.ts",
"@nx/vite/plugin"
],
"targets.build.options.cwd": [
"apps/myreactapp/vite.config.ts",
"@nx/vite/plugin"
],
"targets.serve": ["apps/myreactapp/vite.config.ts", "@nx/vite/plugin"],
"targets.serve.command": [
"apps/myreactapp/vite.config.ts",
"@nx/vite/plugin"
],
"targets.serve.options": [
"apps/myreactapp/vite.config.ts",
"@nx/vite/plugin"
],
"targets.serve.options.cwd": [
"apps/myreactapp/vite.config.ts",
"@nx/vite/plugin"
],
"targets.preview": ["apps/myreactapp/vite.config.ts", "@nx/vite/plugin"],
"targets.preview.command": [
"apps/myreactapp/vite.config.ts",
"@nx/vite/plugin"
],
"targets.preview.options": [
"apps/myreactapp/vite.config.ts",
"@nx/vite/plugin"
],
"targets.preview.options.cwd": [
"apps/myreactapp/vite.config.ts",
"@nx/vite/plugin"
],
"targets.serve-static": [
"apps/myreactapp/vite.config.ts",
"@nx/vite/plugin"
],
"targets.serve-static.executor": [
"apps/myreactapp/vite.config.ts",
"@nx/vite/plugin"
],
"targets.serve-static.options": [
"apps/myreactapp/vite.config.ts",
"@nx/vite/plugin"
],
"targets.serve-static.options.buildTarget": [
"apps/myreactapp/vite.config.ts",
"@nx/vite/plugin"
],
"targets.test": ["apps/myreactapp/vite.config.ts", "@nx/vite/plugin"],
"targets.test.command": [
"apps/myreactapp/vite.config.ts",
"@nx/vite/plugin"
],
"targets.test.options": [
"apps/myreactapp/vite.config.ts",
"@nx/vite/plugin"
],
"targets.test.cache": ["apps/myreactapp/vite.config.ts", "@nx/vite/plugin"],
"targets.test.inputs": [
"apps/myreactapp/vite.config.ts",
"@nx/vite/plugin"
],
"targets.test.outputs": [
"apps/myreactapp/vite.config.ts",
"@nx/vite/plugin"
],
"targets.test.options.cwd": [
"apps/myreactapp/vite.config.ts",
"@nx/vite/plugin"
],
"targets.lint": ["apps/myreactapp/project.json", "@nx/eslint/plugin"],
"targets.lint.command": [
"apps/myreactapp/project.json",
"@nx/eslint/plugin"
],
"targets.lint.cache": ["apps/myreactapp/project.json", "@nx/eslint/plugin"],
"targets.lint.options": [
"apps/myreactapp/project.json",
"@nx/eslint/plugin"
],
"targets.lint.inputs": [
"apps/myreactapp/project.json",
"@nx/eslint/plugin"
],
"targets.lint.options.cwd": [
"apps/myreactapp/project.json",
"@nx/eslint/plugin"
],
"name": ["apps/myreactapp/project.json", "nx/core/project-json"],
"$schema": ["apps/myreactapp/project.json", "nx/core/project-json"],
"sourceRoot": ["apps/myreactapp/project.json", "nx/core/project-json"],
"projectType": ["apps/myreactapp/project.json", "nx/core/project-json"],
"tags": ["apps/myreactapp/project.json", "nx/core/project-json"]
}
}

27
docs/shared/concepts/nx-plugins.md Normal file
View File

@ -0,0 +1,27 @@
# What Are Nx Plugins?
Nx plugins help developers use a tool or framework with Nx. They allow the plugin author who knows the best way to use a tool with Nx to codify their expertise and allow the whole community to reuse those solutions.
For example, plugins can accomplish the following:
- [Configure Nx cache settings](/concepts/inferred-tasks) for a tool. The [`@nx/webpack`](/nx-api/webpack) plugin can automatically configure the [inputs](/recipes/running-tasks/configure-inputs) and [outputs](/recipes/running-tasks/configure-outputs) for a `build` task based on the settings in the `webpack.config.js` file it uses.
- [Update tooling configuration](/features/automate-updating-dependencies) when upgrading the tool version. When Storybook 7 introduced a [new format](https://storybook.js.org/blog/storybook-csf3-is-here) for their configuration files, anyone using the [`@nx/storybook`](/nx-api/storybook) plugin could automatically apply those changes to their repository when upgrading.
- [Set up a tool](/features/generate-code) for the first time. With the [`@nx/playwright`](/nx-api/playwright) plugin installed, you can use the `@nx/playwright:configuration` code generator to set up Playwright tests in an existing project.
- [Run a tool in an advanced way](/concepts/executors-and-configurations). The [`@nx/js`](/nx-api/js) plugin's [`@nx/js:tsc` executor](/nx-api/js/executors/tsc) combines Nx's understanding of your repository with Typescript's native batch mode feature to make your builds [even more performant](/recipes/tips-n-tricks/enable-tsc-batch-mode).
## Plugin Features
{% cards %}
{% card title="Infer tasks" description="Automatically configure Nx settings for tasks based on tooling configuration" type="documentation" url="/concepts/inferred-tasks" /%}
{% card title="Generate Code" description="Generate and modify code to set up and use the tool or framework" type="documentation" url="/features/generate-code" /%}
{% card title="Maintain Dependencies" description="Automatically update package versions and tooling configuration" type="documentation" url="/features/generate-code" /%}
{% card title="Enhance Tooling with Executors" description="Run a tool in an advanced way that may not be possible from the command line" type="documentation" url="/concepts/executors-and-configurations" /%}
{% /cards %}
## Types of Plugins
{% cards %}
{% card title="Official Plugins" description="The API documentation for Nx Plugins maintained by the Nx core team" type="documentation" url="/nx-api" /%}
{% card title="Community Plugins" description="Browse the plugin registry to discover plugins created by the community" type="documentation" url="/plugin-registry" /%}
{% card title="Build Your Own Plugin" description="Build your own plugin to use internally or share with the community" type="documentation" url="/extending-nx/tutorials/create-plugin" /%}
{% /cards %}

163
docs/shared/core-features/distribute-task-execution.md
View File

@ -1,163 +0,0 @@
# Distribute Task Execution (DTE)
Nx speeds up your average CI time with [caching](/core-features/cache-task-results) and
the [affected command](/ci/features/affected). But neither of these features help with the worst case scenario. When
something at the core of your repo has been modified and every task needs to be run in CI, the only way to improve the
performance is by adding more agent jobs and efficiently parallelizing the tasks.
The most obvious way to parallelize tasks is to split tasks up by type: running all tests on one job, all builds on
another and all lint tasks on a third. This strategy is called binning. This can be made difficult if some test tasks
have build tasks as prerequisites, but assuming you figure out some way to handle that, a typical set up can look like
the diagram below. Here the test tasks are delayed until all necessary build artifacts are ready, but the build and lint
tasks can start right away.
![CI using binning](/shared/images/dte/binning.svg)
The problem with the binning approach is you'll end up with some idle time on one or more jobs. Nx's distributed task
execution reduces that idle time to the minimum possible by assigning each individual task to agent jobs based on the
task's average run time. Nx also guarantees that tasks are executed in the correct order and uses remote caching to
make sure that build artifacts from previous tasks are present on every agent job that needs them.
When you set up Nx's distributed task execution, your task graph will look more like this:
![CI using DTE](/shared/images/dte/3agents.svg)
And not only will CI finish faster, but the debugging experience is the same as if you ran all of your CI on a single
job. That's because Nx uses remote caching to recreate all of the logs and build artifacts on the main job.
Find more information in this [guide to parallelization and distribution in CI](/ci/concepts/parallelization-distribution).
## Set up
To distribute your task execution, you need to (1) connect to Nx Cloud and (2) enable DTE in your CI workflow. Each of
these steps can be enabled with a single command:
```shell title="1. Connect to Nx Cloud"
nx connect
```
{% callout type="note" title="Use the latest version of Nx Cloud" %}
This command installs the latest version of `nx-cloud`. The latest version works with any version of Nx >= 13.0.
{% /callout %}
If you have a new workspace, you can generate the CI configuration as follows:
```shell title="2. Enable DTE in CI"
nx generate @nx/workspace:ci-workflow --ci=github
```
The `--ci` flag can be `github`, `circleci`, `azure`, `gitlab`, or `bitbucket`.
For existing workspaces you would probably want to adjust your configuration by hand. See below for examples.
## CI Execution Flow
Distributed task execution can work on any CI provider. You are responsible for launching jobs in your CI system. Nx
Cloud then coordinates the way those jobs work together. There are two different kinds of jobs that you'll need to
create in your CI system. If you would like Nx Cloud to dynamically provision agents for you, check out [Nx Agents](/ci/features/nx-agents)
1. Main job that controls what is going to be executed
2. Multiple agent jobs that actually execute the tasks
![Diagram showing Nx Cloud distributing tasks to multiple agents](/shared/images/dte/distributed-caching-and-task-execution.svg)
The main CI job execution flow looks like this:
```yaml
# Coordinate the agents to run the tasks
- npx nx-cloud start-ci-run --stop-agents-after="build" # makes all nx commands distributed by default
# Run any commands you want here
- nx affected -t test lint build # run on agents in a distributed fashion
- nx affected -t deploy --no-dte # run the main job
```
The agent job execution flow is simple:
```yaml
# Wait for tasks to execute
- npx nx-cloud start-agent
```
Depending on your CI setup, you might want to stop the agents explicitly. You can do it as follows
```yam
# Stop any run away agents
- npx nx-cloud stop-all-agents
```
> For most CI providers, Nx Cloud is able to able to match the main and the agents automatically but for some you might
> need to provision the `NX_BRANCH` and `NX_CI_EXECUTION_ID` env variables (
> see [Environment Variables](/ci/reference/env-vars) for more info).
The main job looks more or less the same way as if you haven't used any distribution. The only thing you need to do is
to invoke `npx nx-cloud start-ci-run` at the beginning and, optionally, invoke `npx nx-cloud stop-all-agents` at the
end.
The agent jobs run long-running `start-agent` processes that execute all the tasks associated with a given CI run. The
only thing you need to do to set them up is to invoke `npx nx-cloud start-agent`. This process will keep running until
Nx Cloud tells it to terminate.
> Note it's important that the main job and the agent jobs have the same environment and the same source code. They
> start
> around the same time. And, once the main job completes, all the agents
> will be stopped.
It's also important to note that an Nx Cloud agent isn't a machine but rather a long-running process that runs on a
machine. I.e., Nx Cloud doesn't manage your agents--you need to do it in your CI config (check out CI examples below).
Nx Cloud is an orchestrator. The main job tells Nx Cloud what you want to run, and Nx Cloud will distribute those tasks
across the agents. Nx Cloud will automatically move files from one agent to another, from the agents to the main job.
The end result is that when say `nx affected -t build` completes on the main job, all the file artifacts created
on agents are copied over to the main job, as if the main job had built everything locally.
## Running Things in Parallel
`--parallel` is propagated to the agents. E.g., `npx nx affected -t build --parallel=3` tells Nx Cloud to
run
up to 3 build targets in parallel on each agent. So if you have say 10 agents, you will run up to 30 builds in parallel
across all of them.
You also want to run as many commands in parallel as you can. For instance,
```yaml
- nx affected -t build
- nx affected -t test
- nx affected -t lint
```
is worse than
```yaml
- nx affected -t build & nx affected -t test & nx affected -t lint
```
or
```yaml
- nx affected -t build test lint
```
The latter two are going to schedule all the three commands at the same time, so if an agent cannot find anything to
build, they will start running tests and lints. The result is better agent utilization and shorter CI time.
## CI/CD Examples
The examples below show how to set up CI using Nx and Nx Cloud using distributed task execution and remote caching.
Every organization manages their CI/CD pipelines differently, so the examples don't cover org-specific aspects of
CI/CD (e.g., deployment). They mainly focus on configuring Nx correctly.
Read the guides for more information on how to configure them in CI.
- [Azure Pipelines](/ci/recipes/set-up/monorepo-ci-azure#distributed-ci-with-nx-cloud)
- [Circle CI](/ci/recipes/set-up/monorepo-ci-circle-ci#distributed-ci-with-nx-cloud)
- [GitHub Actions](/ci/recipes/set-up/monorepo-ci-github-actions#distributed-ci-with-nx-cloud)
- [Jenkins](/ci/recipes/set-up/monorepo-ci-jenkins#distributed-ci-with-nx-cloud)
Note that only cacheable operations can be distributed because they have to be replayed on the main job.
## Relevant Repositories and Examples
- [Nx: On how to make your CI 16 times faster with a small config change](https://github.com/vsavkin/interstellar)
- ["Lerna & Distributed Task Execution" Example](https://github.com/vsavkin/lerna-dte)

144
docs/shared/core-features/explore-graph.md
View File

@ -1,144 +0,0 @@
# Explore the Graph
For Nx to run tasks quickly and correctly, it creates a graph of the dependencies between all the projects in the
repository. Exploring this graph visually can be useful
to understand why Nx is behaving in a certain way and to get a
high level view of your code architecture.
To launch the project graph visualization run:
```shell
npx nx graph
```
This will open a browser window with an interactive representation of the project graph of your current codebase.
Viewing the entire graph can be unmanageable even for smaller repositories, so there are several ways to narrow the
focus of the visualization down to the most useful part of the graph at the moment.
1. Focus on a specific project and then use the proximity and group by folder controls to modify the graph around that
project.
2. Use the search bar to find all projects with names that contain a certain string.
3. Manually hide or show projects in the sidebar
Once the graph is displayed, you can click on an individual dependency link to find out what specific file(s) created
that dependency.
Try playing around with a [fully interactive graph on a sample repo](https://nrwl-nx-examples-dep-graph.netlify.app/?focus=cart) or look at the more limited example below:
{% graph height="450px" %}
```json
{
"hash": "58420bb4002bb9b6914bdeb7808c77a591a089fc82aaee11e656d73b2735e3fa",
"projects": [
{
"name": "shared-product-state",
"type": "lib",
"data": {
"tags": ["scope:shared", "type:state"]
}
},
{
"name": "shared-product-types",
"type": "lib",
"data": {
"tags": ["type:types", "scope:shared"]
}
},
{
"name": "shared-product-data",
"type": "lib",
"data": {
"tags": ["type:data", "scope:shared"]
}
},
{
"name": "cart-cart-page",
"type": "lib",
"data": {
"tags": ["scope:cart", "type:feature"]
}
},
{
"name": "shared-styles",
"type": "lib",
"data": {
"tags": ["scope:shared", "type:styles"]
}
},
{
"name": "cart-e2e",
"type": "e2e",
"data": {
"tags": ["scope:cart", "type:e2e"]
}
},
{
"name": "cart",
"type": "app",
"data": {
"tags": ["type:app", "scope:cart"]
}
}
],
"dependencies": {
"shared-product-state": [
{
"source": "shared-product-state",
"target": "shared-product-data",
"type": "static"
},
{
"source": "shared-product-state",
"target": "shared-product-types",
"type": "static"
}
],
"shared-product-types": [],
"shared-product-data": [
{
"source": "shared-product-data",
"target": "shared-product-types",
"type": "static"
}
],
"shared-e2e-utils": [],
"cart-cart-page": [
{
"source": "cart-cart-page",
"target": "shared-product-state",
"type": "static"
}
],
"shared-styles": [],
"cart-e2e": [
{ "source": "cart-e2e", "target": "cart", "type": "implicit" }
],
"cart": [
{ "source": "cart", "target": "shared-styles", "type": "implicit" },
{ "source": "cart", "target": "cart-cart-page", "type": "static" }
]
},
"workspaceLayout": {
"appsDir": "apps",
"libsDir": "libs"
},
"affectedProjectIds": [],
"focus": null,
"groupByFolder": false,
"exclude": [],
"enableTooltips": true
}
```
{% /graph %}
## Export Project Graph to JSON
If you prefer to analyze the underlying data of the project graph with a script or some other tool, you can run:
```shell
nx graph --file=output.json
```
This will give you all the information that is used to create the project graph visualization.

97
docs/shared/core-features/remote-cache.md
View File

@ -1,97 +0,0 @@
# Use Remote Caching
By default Nx [caches task computations locally](/core-features/cache-task-results). However, to benefit from the cache across your team and in particular on CI, the computation cache can also be distributed across multiple machines. Nx Cloud is an app that provides a fast and zero-config implementation of remote caching. It is a commercial add-on to Nx, is completely free for OSS projects and comes with generous plans for startups and dedicated offerings for enterprise customers ([read more here](https://nx.app/pricing)).
![Diagram showing Teika sharing his cache with CI, Kimiko and James](/shared/images/dte/distributed-caching.svg)
In this diagram, Teika runs the build once on his machine, then CI, Kimiko and James can use the cached artifact from Teika instead of re-executing the same work.
## Setup Remote Caching with Nx Cloud
To enable remote caching for your Nx workspace run the following command:
```shell
npx nx connect
```
This connects your workspace with Nx Cloud's remote caching service. It will also allow you to benefit from other Nx Cloud features such as [distributed task execution](/ci/features/distribute-task-execution).
To see the remote cache in action, run:
```{% command="nx build header && nx reset && nx build header"%}
> nx run header:build
> header@0.0.0 build
> rimraf dist && rollup --config
src/index.tsx → dist...
created dist in 786ms
—————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————
> NX Successfully ran target build for project header (2s)
See logs and investigate cache misses at https://cloud.nx.app/runs/k0HDHACpL8
> NX Resetting the Nx workspace cache and stopping the Nx Daemon.
This might take a few minutes.
> NX Daemon Server - Stopped
> NX Successfully reset the Nx workspace.
> nx run header:build [remote cache]
> header@0.0.0 build
> rimraf dist && rollup --config
src/index.tsx → dist...
created dist in 786ms
—————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————
> NX Successfully ran target build for project header (664ms)
Nx read the output from the cache instead of running the command for 1 out of 1 tasks.
Nx Cloud made it possible to reuse header: https://nx.app/runs/P0X6ZGTkqZ
```
## Claim your Nx Cloud Workspace
During the setup process you might have seen a link to claim your Nx Cloud connected workspace.
```plaintext
> NX NOTE Nx Cloud has been enabled
Your workspace is currently public. Anybody with code access
can view the workspace on nx.app.
You can connect the workspace to your Nx Cloud account at
https://nx.app/orgs/workspace-setup?accessToken=N2Y3NzcyO...
(You can do this later.)
```
Click on this link to associate the workspace with your Nx Cloud account. If you don't have an Nx Cloud account, you can create one on the spot.
![Nx Cloud Workspace Dashboard](/shared/images/nx-cloud/nx-cloud-workspace-overview.png)
Claiming your workspace allows you to
- see stats about your CI runs, cache hits number of agents used for distributing tasks
- enable [source control integrations](/ci/recipes/source-control-integration) to get information embedded in your GitHub, Bitbucket or GitLab PRs
- manage and create access tokens and [adjust access and permission](/ci/concepts/cache-security)
- manage your organization & user permissions for your Nx Cloud workspace
**If you lose this link, you can still connect your workspace to Nx Cloud**. Go to [nx.app](https://nx.app), create an account, and connect your workspace using the access token from `nx.json`.
## Skipping Cloud Cache
Similar to how `--skip-nx-cache` will instruct Nx not to use the local cache, passing `--no-cloud` will tell Nx not to use the remote cache from Nx Cloud.

2
docs/shared/core-tutorial/01-create-blog.md
View File

@ -3,7 +3,7 @@
In this tutorial you create multiple projects in a monorepo and take advantage of the core Nx features with a minimum of configuration.
{% callout type="check" title="Package-Based Repo" %}
This tutorial sets up a [package-based repo](/concepts/integrated-vs-package-based). If you prefer an [integrated repo](/concepts/integrated-vs-package-based), check out the [React](/getting-started/tutorials/react-monorepo-tutorial), [Angular](/getting-started/tutorials/angular-monorepo-tutorial) or [Node](/getting-started/tutorials/node-server-tutorial) tutorials.
This tutorial sets up a [package-based repo](/concepts/integrated-vs-package-based). If you prefer an [integrated repo](/concepts/integrated-vs-package-based), check out the [React](/getting-started/tutorials/react-monorepo-tutorial) or [Angular](/getting-started/tutorials/angular-monorepo-tutorial) tutorials.
{% /callout %}
## Contents:

2
docs/shared/deprecated/as-provided-vs-derived.md
View File

@ -12,7 +12,7 @@ Here are some of the issues with the `derived` behavior that are addressed with
## Using Nx Console
You can use [Nx Console](/core-features/integrate-with-editors) for an intuitive experience running generators.
You can use [Nx Console](/features/integrate-with-editors) for an intuitive experience running generators.
1. If you right-click a folder and choose `Nx generate`, the code generation will be run from that folder.
2. As you fill out the generate form, Nx Console will show you a preview of where the new files will be generated.

5
docs/shared/deprecated/cacheable-operations.md Normal file
View File

@ -0,0 +1,5 @@
# cacheableOperations
In Nx < 17, the way to define which tasks were cacheable was to add the task name to the `cacheableOperations` array in `nx.json`. This way of defining cacheable tasks required all tasks named `test` to be either cacheable or not cacheable.
In Nx 17, use the `cache` property in `targetDefaults` or individual target definitions in the project level configuration.

4
docs/shared/deprecated/global-implicit-dependencies.md
View File

@ -1,6 +1,6 @@
# Global Implicit Dependencies
Since v14.4, Nx supports [`inputs` and `namedInputs`](/recipes/running-tasks/customizing-inputs) for setting up implicit dependencies. As of Nx v16, the `implicitDependencies` defined in `nx.json` are ignored and do not influence the affected graph. This field will be removed in v17. The [`implicitDependencies` in the project configuration](/reference/project-configuration#implicitdependencies) are still the best way to manually set up a dependency between two projects that Nx is not able to detect automatically.
Since v14.4, Nx supports [`inputs` and `namedInputs`](/recipes/running-tasks/configure-inputs) for setting up implicit dependencies. As of Nx v16, the `implicitDependencies` defined in `nx.json` are ignored and do not influence the affected graph. This field will be removed in v17. The [`implicitDependencies` in the project configuration](/reference/project-configuration#implicitdependencies) are still the best way to manually set up a dependency between two projects that Nx is not able to detect automatically.
## Projects Depending on Global Files
@ -34,7 +34,7 @@ To express the same dependencies with `inputs` and `namedInputs`, modify the def
The `sharedGlobals` are included in the `default` named input, so most targets will be set up to depend on them.
For a more detailed explanation, read the [Customizing Inputs and Named Inputs guide](/recipes/running-tasks/customizing-inputs)
For a more detailed explanation, read the [Customizing Inputs and Named Inputs guide](/recipes/running-tasks/configure-inputs)
### Dependencies on Sections of the Root `package.json` File

7
docs/shared/deprecated/npm-scope.md Normal file
View File

@ -0,0 +1,7 @@
# NPM Scope
The `npmScope` property of the `nx.json` file is deprecated as of version 16.2.0. `npmScope` was used as a prefix for the names of newly created projects. The new recommended way to define the organization prefix is to set the `name` property in the root `package.json` file to `@my-org/root`. Then `@my-org/` will be used as a prefix for all newly created projects.
In Nx 16, if the `npmScope` property is present, it will be used as a prefix. If the `npmScope` property is not present, the `name` property of the root `package.json` file will be used to infer the prefix.
In Nx 17+, the `npmScope` property is ignored.

2
docs/shared/deprecated/v1-nx-plugin-api.md
View File

@ -234,7 +234,7 @@ builder.addDynamicDependency(
### Visualizing the Project Graph
You can then visualize the project graph as described [here](/core-features/explore-graph). However, there is a cache that Nx uses to avoid recalculating the project graph as much as possible. As you develop your project graph plugin, it might be a good idea to set the following environment variable to disable the project graph cache: `NX_CACHE_PROJECT_GRAPH=false`.
You can then visualize the project graph as described [here](/features/explore-graph). However, there is a cache that Nx uses to avoid recalculating the project graph as much as possible. As you develop your project graph plugin, it might be a good idea to set the following environment variable to disable the project graph cache: `NX_CACHE_PROJECT_GRAPH=false`.
It might also be a good idea to ensure that the dep graph is not running on the nx daemon by setting `NX_DAEMON=false`, as this will ensure you will be able to see any `console.log` statements you add as you're developing.

3
docs/shared/deprecated/workspace-executors.md
View File

@ -7,8 +7,7 @@ In Nx 13.10+, local nx plugins can contain executors that are used in the worksp
- If you don't already have a local plugin, use Nx to generate one:
```shell
# replace `latest` with the version that matches your Nx version
npm install @nx/plugin@latest
npm add -D @nx/plugin
nx g @nx/plugin:plugin my-plugin
```

3
docs/shared/deprecated/workspace-generators.md
View File

@ -15,8 +15,7 @@ When migrating to Nx 16, a new workspace plugin is automatically generated in th
- If you don't already have a local plugin, use Nx to generate one:
```shell
# replace `latest` with the version that matches your Nx version
npm install @nx/plugin@latest
npm add -D @nx/plugin
nx g @nx/plugin:plugin my-plugin
```

2
docs/shared/core-features/automate-updating-dependencies.md → docs/shared/features/automate-updating-dependencies.md
View File

@ -68,7 +68,7 @@ Note: You may want to keep the `migrations.json` until every branch that was cre
## Keep Nx Packages on the Same Version
When you run `nx migrate`, the `nx` package and all the `@nx/` packages get updated to the same version. It is important to [keep these versions in sync](/recipes/tips-n-tricks/keep-nx-versions-in-sync), or you can encounter some difficult to debug errors. As long as you run `nx migrate` instead of manually changing the version numbers, you shouldn't have to worry about it.
When you run `nx migrate`, the `nx` package and all the `@nx/` packages get updated to the same version. It is important to [keep these versions in sync](/recipes/tips-n-tricks/keep-nx-versions-in-sync), or you can encounter some difficult to debug errors. As long as you run `nx migrate` instead of manually changing the version numbers, you shouldn't have to worry about it. Also, when you add a new plugin, use `nx add <plugin>` to automatically install the version that matches your repository's version of Nx.
{% callout type="note" title="Use the latest nx-cloud version" %}
The `nx-cloud` package does not need to be in sync with the other Nx packages. For best results, stay on the latest version of `nx-cloud`. The latest `nx-cloud` version supports the most recent 2 major versions of `nx`, although earlier versions of `nx` may also be compatible.

8
docs/shared/core-features/cache-task-results.md → docs/shared/features/cache-task-results.md
View File

@ -64,6 +64,10 @@ Keep reading to learn how to fine-tune what gets cached.
## Fine-tune Caching with Inputs and Outputs
{% callout type="note" title="Detect Inputs and Outputs" %}
Nx can automatically set inputs and outputs for you based on your tooling configuration settings when you use [inferred tasks](/concepts/inferred-tasks)
{% /callout %}
Nx's caching feature starts with sensible defaults, but you can also fine-tune the defaults to control exactly what gets cached and when. There are two main options that control caching:
- **Inputs -** define what gets included as part of the calculated hash (e.g. files, environment variables, etc.)
@ -111,7 +115,7 @@ To achieve this, we can add an `inputs` and `outputs` definition globally for al
Note, you only need to define output locations if they differ from the usual `dist` or `build` directory which Nx automatically recognizes.
Learn more [about configuring inputs including `namedInputs`](/recipes/running-tasks/customizing-inputs).
Learn more [about configuring inputs including `namedInputs`](/recipes/running-tasks/configure-inputs).
## Where is the Cache Stored?
@ -135,7 +139,7 @@ If you want to ignore the cache (both reads and writes), use the `--skip-nx-cach
nx build header --skip-nx-cache
```
Alternatively if you want to disable caching for a particular task, just make sure it is not part [of the cached targets](/core-features/cache-task-results#define-cacheable-tasks). If [you're using Nx Cloud](/ci/features/remote-cache#skipping-cloud-cache), you might want to use `--no-cloud` to skip remote caching.
Alternatively if you want to disable caching for a particular task, just make sure it is not part [of the cached tasks](/features/cache-task-results#define-cacheable-tasks). If [you're using Nx Cloud](/ci/features/remote-cache#skipping-cloud-cache), you might want to use `--no-cloud` to skip remote caching.
## Clear the Local Cache

82
docs/shared/features/distribute-task-execution.md Normal file
View File

@ -0,0 +1,82 @@
# Distribute Task Execution (Nx Agents)
{% youtube
src="https://youtu.be/XLOUFZeqRpM"
title="Nx Agents in action splitting e2e tests at a file level"
/%}
**Nx Agents** lets you distribute your CI across many machines with minimal configuration. It comes with features such as dynamically allocating agents based on the size of the PR, flaky task re-running, and intelligent task splitting and distribution. Keep reading to learn more.
![Distribute Task Execution with Nx Agents](/shared/images/dte/nx-agents-orchestration-diagram.svg)
For a more thorough explanation of how Nx Agents optimizes your CI pipeline, read this [guide to parallelization and distribution in CI](/ci/concepts/parallelization-distribution).
## Enabling Nx Agents
To enable task distribution with Nx Agents, there are two requirements:
1. Enable version control system integration. The integrations currently available are [GitHub](/ci/recipes/source-control-integration/github), [GitLab](/ci/recipes/source-control-integration/gitlab) and [Bitbucket](/ci/recipes/source-control-integration/bitbucket-cloud). These integrations can be enabled from your [Nx Cloud dashboard](https://nx.app).
2. Add a single line to your CI pipeline configuration.
Add the `start-ci-run` command to your CI pipeline configuration after checking out the repository and before installing `node_modules`:
```yaml {% fileName=".github/workflows/main.yaml" %}
# After checkout repository
- name: Start CI run
run: 'npx nx-cloud start-ci-run --distribute-on="8 linux-medium-js" --stop-agents-after="e2e-ci"'
# Before install node_modules
# Run any nx commands as if running on a single machine
```
The `--distribute-on` flag instructs Nx Cloud to distribute tasks across 8 agents of type `linux-medium-js`. `linux-medium-js` is the name of the launch template that will be used to provision the agent. The default launch templates [can be found here](https://github.com/nrwl/nx-cloud-workflows/blob/main/launch-templates/linux.yaml)
## Launch Templates
You can also define your own "launch templates" (here's an [example from the Nx repo](https://github.com/nrwl/nx/blob/master/.nx/workflows/agents.yaml)):
```yaml {% fileName=".nx/workflows/agents.yaml" %}
launch-templates:
linux-medium:
resource-class: 'docker_linux_amd64/medium+'
init-steps:
- name: Pnpm Install
script: |
pnpm install --frozen-lockfile
- name: Install Cypress
script: pnpm exec cypress install
- name: Install Rust
- ...
```
Here are the [available resource classes](https://nx.app/pricing#resource-classes).
## Related Features
{% cards %}
{% card title="Dynamically Allocate Agents" description="Assign a different number of agents to a pipeline based on the size of the PR" type="documentation" url="/ci/features/dynamic-agents" /%}
{% card title="Automatically Split E2E Tasks" description="Split large e2e tasks into separate tasks for each spec file" type="documentation" url="/ci/features/split-e2e-tasks" /%}
{% card title="Identify and Re-run Flaky Tasks" description="Re-run flaky tasks in CI whenever they fail" url="/ci/features/flaky-tasks" /%}
{% /cards %}
## CI/CD Guides
Every organization manages their CI/CD pipelines differently, so the guides don't cover org-specific aspects of
CI/CD (e.g., deployment). They mainly focus on configuring Nx correctly using Nx Agents and [Nx Replay](/ci/features/remote-cache).
- [Azure Pipelines](/ci/recipes/set-up/monorepo-ci-azure#distributed-ci-with-nx-cloud)
- [Circle CI](/ci/recipes/set-up/monorepo-ci-circle-ci#distributed-ci-with-nx-cloud)
- [GitHub Actions](/ci/recipes/set-up/monorepo-ci-github-actions#distributed-ci-with-nx-cloud)
- [Jenkins](/ci/recipes/set-up/monorepo-ci-jenkins#distributed-ci-with-nx-cloud)
Note that only cacheable operations can be distributed because they have to be replayed on the main job.
## Relevant Repositories and Examples
- [Nx: On how to make your CI 16 times faster with a small config change](https://github.com/vsavkin/interstellar)
- ["Lerna & Distributed Task Execution" Example](https://github.com/vsavkin/lerna-dte)

22
docs/shared/core-features/enforce-module-boundaries.md → docs/shared/features/enforce-module-boundaries.md
View File

@ -15,30 +15,10 @@ Nx provides an `enforce-module-boundaries` eslint rule that enforces the public
To set up the lint rule, install these dependencies:
{% tabs %}
{% tab label="npm" %}
```shell
npm add @nx/eslint-plugin @nx/devkit
nx add @nx/eslint-plugin @nx/devkit
```
{% /tab %}
{% tab label="yarn" %}
```shell
yarn add @nx/eslint-plugin @nx/devkit
```
{% /tab %}
{% tab label="pnpm" %}
```shell
pnpm add @nx/eslint-plugin @nx/devkit
```
{% /tab %}
{% /tabs %}
And configure the rule in your root `.eslintrc.json` file:
```jsonc {% fileName=".eslintrc.json" %}

215
docs/shared/features/explore-graph.md Normal file
View File

@ -0,0 +1,215 @@
---
title: Explore your Workspace
description: 'Learn how Nx helps you understand your workspace by viewing project details, the project graph, and the task graph.'
---
# Explore your Workspace
Nx understands your workspace as a collection of projects.
Each project can be explored to view the different tasks which can be run.
The projects in the workspace have dependencies between them and form a graph known as the **Project Graph**.
Nx uses this project graph in many ways to make informed decisions such as which tasks to run, when the results of a task can be restored from cache, and more.
In addition to the project graph, Nx also runs your tasks as a **Task Graph**.
This is a separate graph of tasks and their dependencies which is based on the project graph and determines the way in which the tasks are executed.
Nx allows you to interactively explore your workspace through a UI which shows the information above.
Using this tool is _vital_ to understanding both your workspace as well as how Nx behaves.
This guide will teach you to use this tool to explore projects, the project graph, and the task graphs for your workspace.
## Explore Projects in your Workspace
Projects in Nx are the different parts of the monorepo which can have tasks run for them.
The best way to see what projects are in your workspace is to view the [project graph](#explore-the-project-graph) which will be covered in the next section.
Another way is to look at the **Projects** pane in [Nx Console](/features/integrate-with-editors) or run `nx show projects` to show a list of projects in your terminal.
You can see more details about a specific project in Nx Console or by running `nx show project <project-name> --web`. Both methods will show something like the example below:
{% project-details jsonFile="shared/concepts/myreactapp.json"%}
{% /project-details %}
The view shows a list of targets which can be [run by Nx](/features/run-tasks).
Each target has different options which determine how Nx runs the task.
## Explore the Project Graph
Nx understands the projects in your workspace as a graph and uses this understanding to behave intelligently.
Exploring this graph visually is vital to understanding how your code is structured and how Nx behaves.
It always stays up to date without having to actively maintain a document as it is [calculated by analyzing your source code](/concepts/more-concepts/how-project-graph-is-built#how-the-project-graph-is-built)
### Launching the Project Graph
To launch the project graph visualization for your workspace, use [Nx Console](/features/integrate-with-editors) or run:
```shell
npx nx graph
```
This will open a browser window with an interactive view of the project graph of your workspace.
### Focusing on Valuable Projects
Viewing the entire graph can be unmanageable even for smaller repositories, so there are several ways to narrow the
focus of the visualization down to the most useful part of the graph at the moment.
1. Focus on a specific project and then use the proximity and group by folder controls in the sidebar to modify the graph around that
project. You can also start the graph with a project focused by running `nx graph --focus <project-name>`.
2. Use the search bar to find all projects with names that contain a certain string.
3. Manually hide or show projects in the sidebar.
Once the graph is displayed, you can explore deeper by clicking on nodes and edges in the graph.
Click on a node to show a tooltip which also has a link to view more details about the project.
You can trace the dependency chain between two projects by choosing a **Start** and **End** point in the project tooltips.
Click on any dependency line to find which file(s) created the dependency.
Try playing around with a [fully interactive graph on a sample repo](https://nrwl-nx-examples-dep-graph.netlify.app/?focus=cart) or look at the more limited example below:
{% graph height="450px" %}
```json
{
"hash": "58420bb4002bb9b6914bdeb7808c77a591a089fc82aaee11e656d73b2735e3fa",
"projects": [
{
"name": "shared-product-state",
"type": "lib",
"data": {
"tags": ["scope:shared", "type:state"]
}
},
{
"name": "shared-product-types",
"type": "lib",
"data": {
"tags": ["type:types", "scope:shared"]
}
},
{
"name": "shared-product-data",
"type": "lib",
"data": {
"tags": ["type:data", "scope:shared"]
}
},
{
"name": "cart-cart-page",
"type": "lib",
"data": {
"tags": ["scope:cart", "type:feature"]
}
},
{
"name": "shared-styles",
"type": "lib",
"data": {
"tags": ["scope:shared", "type:styles"]
}
},
{
"name": "cart-e2e",
"type": "e2e",
"data": {
"tags": ["scope:cart", "type:e2e"]
}
},
{
"name": "cart",
"type": "app",
"data": {
"tags": ["type:app", "scope:cart"]
}
}
],
"dependencies": {
"shared-product-state": [
{
"source": "shared-product-state",
"target": "shared-product-data",
"type": "static"
},
{
"source": "shared-product-state",
"target": "shared-product-types",
"type": "static"
}
],
"shared-product-types": [],
"shared-product-data": [
{
"source": "shared-product-data",
"target": "shared-product-types",
"type": "static"
}
],
"shared-e2e-utils": [],
"cart-cart-page": [
{
"source": "cart-cart-page",
"target": "shared-product-state",
"type": "static"
}
],
"shared-styles": [],
"cart-e2e": [
{ "source": "cart-e2e", "target": "cart", "type": "implicit" }
],
"cart": [
{ "source": "cart", "target": "shared-styles", "type": "implicit" },
{ "source": "cart", "target": "cart-cart-page", "type": "static" }
]
},
"workspaceLayout": {
"appsDir": "apps",
"libsDir": "libs"
},
"affectedProjectIds": [],
"focus": null,
"groupByFolder": false,
"exclude": [],
"enableTooltips": true
}
```
{% /graph %}
### Export Project Graph to JSON
If you prefer to analyze the underlying data of the project graph with a script or some other tool, you can run:
```shell
nx graph --file=output.json
```
This will give you all the information that is used to create the project graph visualization.
### Export the Project Graph as an Image
There is a floating action button in the bottom right of the project graph view which will save the graph as a `.png` file.
Sharing this image with other developers is a great way to express how a project fits into the workspace.
Some moments which you may want to share these images are:
- When providing a high-level overview of the workspace
- When introducing new project(s) into the workspace
- When changing how project(s) are related
- To share which other projects are directly affected by changes you are making
## Explore the Task Graph
Nx uses the project graph of your workspace to determine the order in which to [run tasks](/features/run-tasks). Pass the `--graph` flag to view the **task graph** which is executed by Nx when running a command.
```shell
nx build myreactapp --graph # View the graph for building myreactapp
nx run-many -targets build --graph # View the graph for building all projects
nx affected --targets build --graph # View the graph for building the affected projects
```
Click on the nodes of this graph to see more information about the task such as:
- Which executor was used to run the command
- Which [inputs](/recipes/running-tasks/configure-inputs) are used to calculate the computation hash.
- A link to see more details about the project which the task belongs to
Dependencies in this graph mean that Nx will need to wait for all task dependencies to complete successfully before running the task.

2
docs/shared/plugin-features/use-code-generators.md → docs/shared/features/generate-code.md
View File

@ -1,4 +1,4 @@
# Use Code Generators
# Generate Code
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.

0
docs/shared/core-features/integrate-with-editors.md → docs/shared/features/integrate-with-editors.md
View File

0
docs/shared/core-features/manage-releases.md → docs/shared/features/manage-releases.md
View File

67
docs/shared/features/remote-cache.md Normal file
View File

@ -0,0 +1,67 @@
# Use Remote Caching (Nx Replay)
By default Nx [caches task computations locally](/features/cache-task-results). However, to benefit from the cache across your team and in particular on CI, the computation cache can also be distributed across multiple machines.
The **Nx Replay** feature of Nx Cloud is a fast, secure and zero-config implementation of remote caching.
![Diagram showing Teika sharing his cache with CI, Kimiko and James](/shared/images/dte/distributed-caching.svg)
In this diagram, Teika runs the build once on his machine, then CI, Kimiko and James can use the cached artifact from Teika instead of re-executing the same work.
## Setting Up Nx Cloud
To use **Nx Replay** you need to connect your workspace to Nx Cloud. See the [connect to Nx Cloud recipe](/ci/recipes/set-up/connect-to-cloud).
## See Remote Caching in Action
To see the remote cache in action, run:
```{% command="nx build header && nx reset && nx build header"%}
> nx run header:build
> header@0.0.0 build
> rimraf dist && rollup --config
src/index.tsx → dist...
created dist in 786ms
—————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————
> NX Successfully ran target build for project header (2s)
See logs and investigate cache misses at https://cloud.nx.app/runs/k0HDHACpL8
> NX Resetting the Nx workspace cache and stopping the Nx Daemon.
This might take a few minutes.
> NX Daemon Server - Stopped
> NX Successfully reset the Nx workspace.
> nx run header:build [remote cache]
> header@0.0.0 build
> rimraf dist && rollup --config
src/index.tsx → dist...
created dist in 786ms
—————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————
> NX Successfully ran target build for project header (664ms)
Nx read the output from the cache instead of running the command for 1 out of 1 tasks.
Nx Cloud made it possible to reuse header: https://nx.app/runs/P0X6ZGTkqZ
```
## Skipping Cloud Cache
Similar to how `--skip-nx-cache` will instruct Nx not to use the local cache, passing `--no-cloud` will tell Nx not to use the remote cache from Nx Cloud.

56
docs/shared/core-features/run-tasks.md → docs/shared/features/run-tasks.md
View File

@ -2,51 +2,11 @@
Monorepos can have hundreds or even thousands of projects, so being able to run actions against all (or some) of them is a key feature of a tool like Nx.
## Definitions
## Types of Tasks
- **Command -** anything the developer types into the terminal (e.g., `nx run header:build`).
- **Target -** the name of an action taken on a project (e.g., `build`)
- **Task -** an invocation of a target on a specific project (e.g., `header:build`).
Nx tasks can be created from existing `package.json` scripts, [inferred from tooling configuration files](/concepts/inferred-tasks), or defined in a `project.json` file. Nx will merge all three sources together to determine the tasks for a particular project.
## Define Tasks
For these examples, we'll imagine a repo that has three projects: `myapp`, `header` and `footer`. `myapp` is a deployable app and uses the `header` and `footer` libraries.
Each project has the `test` and `build` targets defined. Tasks can be defined as npm scripts in a project's `package.json` file or as targets in a `project.json` file:
{% tabs %}
{% tab label="package.json" %}
```json {% fileName="package.json" %}
{
"scripts": {
"build": "webpack -c webpack.conf.js",
"test": "jest --coverage"
}
}
```
{% /tab %}
{% tab label="project.json" %}
```json {% fileName="project.json" %}
{
"targets": {
"build": {
"command": "webpack -c webpack.conf.js"
},
"test": {
"executor": "@nx/jest:jest",
"options": {
"codeCoverage": true
}
}
}
}
```
{% /tab %}
{% /tabs %}
Read the [Project Configuration docs](/reference/project-configuration) to see all the configuration options for a task.
## Running Tasks
@ -56,7 +16,7 @@ Nx uses the following syntax:
### Run a Single Task
To run the `test` target on the `header` project run this command:
To run the `test` task for the `header` project run this command:
```shell
npx nx test header
@ -66,19 +26,19 @@ npx nx test header
You can use the `run-many` command to run a task for multiple projects. Here are a couple of examples.
Run the `build` target for all projects in the repo:
Run the `build` task for all projects in the repo:
```shell
npx nx run-many -t build
```
Run the `build`, `lint` and `test` target for all projects in the repo:
Run the `build`, `lint` and `test` task for all projects in the repo:
```shell
npx nx run-many -t build lint test
```
Run the `build`, `lint` and `test` target just on the `header` and `footer` projects:
Run the `build`, `lint` and `test` task just on the `header` and `footer` projects:
```shell
npx nx run-many -t build lint test -p header footer
@ -102,7 +62,7 @@ Learn more about the affected command [here](/ci/features/affected).
It is pretty common to have dependencies between tasks, requiring one task to be run before another. For example, you might want to run the `build` target on the `header` project before running the `build` target on the `app` project.
Nx is already able to automatically understand the dependencies between projects (see [project graph](/core-features/explore-graph)).
Nx is already able to automatically understand the dependencies between projects (see [project graph](/features/explore-graph)).
{% graph height="450px" %}

2
docs/shared/getting-started/installation.md
View File

@ -48,7 +48,7 @@ Once you've created your workspace, you can
Run `npx nx run-many -t build` twice to see how Nx's powerful caching speeds up your build.
Learn more about [running tasks](/core-features/run-tasks).
Learn more about [running tasks](/features/run-tasks).
## Installing Nx Into an Existing Repository

12
docs/shared/getting-started/intro.md
View File

@ -4,14 +4,14 @@ Nx is a powerful open-source build system that provides tools and techniques for
## Core Features
- **Run Tasks Efficiently**: Nx [runs tasks in parallel](/core-features/run-tasks) and orders the tasks based on the dependencies between them.
- **Cache Locally & Remotely**: With [local](/core-features/cache-task-results) and [remote caching](/ci/features/remote-cache), Nx prevents unnecessary re-runs of tasks, saving you valuable dev time.
- **Automate Dependency Updates**: if you leverage Nx plugins you gain additional features such as [code generation](/core-features/plugin-features/use-code-generators) and tools to [automatically upgrade](core-features/automate-updating-dependencies) your codebase and dependencies.
- **Run Tasks Efficiently**: Nx [runs tasks in parallel](/features/run-tasks) and orders the tasks based on the dependencies between them.
- **Cache Locally & Remotely**: With [local](/features/cache-task-results) and [remote caching](/ci/features/remote-cache), Nx prevents unnecessary re-runs of tasks, saving you valuable dev time.
- **Automate Dependency Updates**: if you leverage Nx plugins you gain additional features such as [code generation](/features/generate-code) and tools to [automatically upgrade](features/automate-updating-dependencies) your codebase and dependencies.
- **Make it Your Own**: Nx is highly customizable and extensible. Fine-tune it by [creating your own plugins](/extending-nx/intro/getting-started) and optionally [share them with the community](/extending-nx/tutorials/publish-plugin#publish-your-nx-plugin).
<!-- - **Monorepo and Single Projects**: Nx supports both, monorepos as well as single-project (standalone) workspaces. -->
Find out more about [why you should use Nx](/getting-started/why-nx) or browse our [core features](/core-features).
Find out more about [why you should use Nx](/getting-started/why-nx) or browse our [features](/features).
## Try Nx Yourself!
@ -47,9 +47,7 @@ npx create-nx-workspace@latest
<!-- {% link-card title="React Monorepo" type="tutorial" url="/getting-started/tutorials/react-standalone-tutorial" icon="reactMono" /%}
{% link-card title="Angular Monorepo" type="tutorial" url="/getting-started/tutorials/angular-standalone-tutorial" icon="angularMono" /%}
{% link-card title="Node Monorepo" type="tutorial" url="/getting-started/tutorials/node-server-tutorial" icon="nodeMono" /%} -->
{% link-card title="Angular Monorepo" type="tutorial" url="/getting-started/tutorials/angular-standalone-tutorial" icon="angularMono" /%}-->
{% /cards %}

8
docs/shared/getting-started/why-nx.md
View File

@ -27,11 +27,11 @@ Nx is built in a modular fashion to let you only use the features you need.
![High-level Nx architecture](/shared/images/nx-architecture.svg)
- The **Nx** package provides fundamental technology-agnostic capabilities such as: [workspace analysis](/core-features/explore-graph), [task running](/core-features/run-tasks), [caching](/core-features/cache-task-results), [distribution](/ci/features/distribute-task-execution), [code generation](/core-features/plugin-features/use-code-generators) and [automated code migrations](/core-features/automate-updating-dependencies).
- **Plugins** are NPM packages that built on top of the fundamental capabilities provided by the Nx package. Nx plugins contain [code generators](/core-features/plugin-features/use-code-generators), [executors](/core-features/plugin-features/use-task-executors) (to abstract lower-level build tooling) and automated code migrations for keeping your tools up to date. Contrary to the Nx package, which works the same way with any JS or non-JS project, plugins are usually technology specific. For instance, `@nx/react` adds support for building React apps and libs, `@nx/cypress` adds e2e testing capabilities with Cypress. Plugins make developers more productive by removing any friction of integrating different tools with each other and by providing utilities to keep them up to date. The Nx team maintains plugins for React, Next, Remix, Angular, Jest, Cypress, Storybook and more. You can use the `@nx/plugin` package to easily [scaffold a new plugin](/extending-nx/intro/getting-started) or even just [automate your local workspace](/extending-nx/recipes/local-generators). There are also more than 80 [community plugins](/plugin-registry).
- The **Nx** package provides fundamental technology-agnostic capabilities such as: [workspace analysis](/features/explore-graph), [task running](/features/run-tasks), [caching](/features/cache-task-results), [distribution](/ci/features/distribute-task-execution), [code generation](/features/generate-code) and [automated code migrations](/features/automate-updating-dependencies).
- **Plugins** are NPM packages that build on top of the fundamental capabilities provided by the Nx package. Nx plugins contain [code generators](/features/generate-code), [executors](/concepts/executors-and-configurations) (to abstract lower-level build tooling) and automated code migrations for keeping your tools up to date. Contrary to the Nx package, which works the same way with any JS or non-JS project, plugins are usually technology specific. For instance, `@nx/react` adds support for building React apps and libs, `@nx/cypress` adds e2e testing capabilities with Cypress. Plugins make developers more productive by removing any friction of integrating different tools with each other and by providing utilities to keep them up to date. The Nx team maintains plugins for React, Next, Remix, Angular, Jest, Cypress, Storybook and more. You can use the `@nx/plugin` package to easily [scaffold a new plugin](/extending-nx/intro/getting-started) or even just [automate your local workspace](/extending-nx/recipes/local-generators). There are also more than 80 [community plugins](/plugin-registry).
- **Devkit** is a set of utilities for [building Nx plugins](/extending-nx/intro/getting-started).
- **Nx Cloud** helps scale your project on CI by [adding remote caching](/concepts/how-caching-works) and [distributed task execution](/concepts/more-concepts/illustrated-dte). It also improves developer ergonomics by integrating with GitHub, GitLab and BitBucket and providing searchable structured logs. Learn more at [nx.app](https://nx.app).
- **Nx Console** is an extension for **VSCode, IntelliJ and VIM**. It provides code autocompletion, interactive generators, workspace visualizations, powerful refactorings and more. You can [install it here](/core-features/integrate-with-editors).
- **Nx Console** is an extension for **VSCode, IntelliJ and VIM**. It provides code autocompletion, interactive generators, workspace visualizations, powerful refactorings and more. You can [install it here](/features/integrate-with-editors).
## How can I adopt Nx in my existing project?
@ -41,6 +41,6 @@ As shown in the section before, there's a core [nx package](https://www.npmjs.co
npx nx@latest init
```
By adding the `nx` package you can use [Nx commands](/core-features/run-tasks) to run your `package.json` scripts and benefit from running tasks in parallel as well as [caching](/core-features/cache-task-results). Over time you can then also add in Nx Plugins to further enhance your experience when working with specific tech stacks.
By adding the `nx` package you can use [Nx commands](/features/run-tasks) to run your `package.json` scripts and benefit from running tasks in parallel as well as [caching](/features/cache-task-results). Over time you can then also add in Nx Plugins to further enhance your experience when working with specific tech stacks.
Check out our [migration guides](/recipes/adopting-nx) for all the details.

32
docs/shared/guides/module-federation/faster-builds.md
View File

@ -89,42 +89,14 @@ take advantage of remote caching and other features it provides.
Then, for React users, install the `@nx/react` plugin; and for Angular users, install the `@nx/angular` plugin.
{% tabs %}
{% tab label="npm" %}
```shell
# If you use React
npm add -D @nx/react
nx add @nx/react
# If you use Angular
npm add -D @nx/angular
nx add @nx/angular
```
{% /tab %}
{% tab label="yarn" %}
```shell
# If you use React
yarn add -D @nx/react
# If you use Angular
yarn add -D @nx/angular
```
{% /tab %}
{% tab label="pnpm" %}
```shell
# If you use React
pnpm add -D @nx/react
# If you use Angular
pnpm add -D @nx/angular
```
{% /tab %}
{% /tabs %}
Next, generate the host and remote applications.
{% tabs %}

70
docs/shared/guides/nx-and-angular-cli.md
View File

@ -23,30 +23,30 @@ Note, the Nx team's focus is on building the best possible developer productivit
Here's a quick side-by-side overview comparing the features between the Angular CLI and Nx. _(Kudos to [Daniel Glejzner](https://twitter.com/DanielGlejzner) for helping with this)_
| Feature/Tool | Angular CLI | Nx |
| ---------------------------------------------------------------------------------------------------------- | --------------- | ------------- |
| Create Angular Apps | ✅ | ✅ |
| Generate Angular Components, Services, etc. | ✅ | ✅ |
| Building & Bundling | ✅ | ✅ |
| Local Development Server | ✅ | ✅ |
| Code Schematics | ✅ | ✅ |
| Automated Update with Migrations | ✅ | ✅ (Enhanced) |
| Generators | ✅ (Schematics) | ✅ |
| Executors | ✅ (Builders) | ✅ |
| Advanced Generators (e.g. Module Federation, Tailwind,...) | ❌ | ✅ |
| Integrated Tooling (Jest, Cypress, Playwright etc.) | ❌ | ✅ |
| Support for [single-project Workspaces](/getting-started/tutorials/angular-standalone-tutorial) | ✅ | ✅ |
| First-Class [Monorepo Support](/getting-started/tutorials/angular-monorepo-tutorial) | ❌\* | ✅ |
| [Enforced Module Boundaries](/core-features/enforce-module-boundaries) | ❌ | ✅ |
| Interactive [Project Graph](/core-features/explore-graph) | ❌ | ✅ |
| Task Graph | ❌ | ✅ |
| [Running Tasks in Parallel](/recipes/running-tasks/run-tasks-in-parallel) | ❌ | ✅ |
| Building, Testing [Only What is Affected](/core-features/run-tasks#run-tasks-on-projects-affected-by-a-pr) | ❌ | ✅ |
| [Local Caching](/core-features/cache-task-results) | ❌\*\* | ✅ |
| [Remote Caching](/ci/features/remote-cache) | ❌ | ✅ |
| [Distributed Task Execution on CI](/ci/features/distribute-task-execution) | ❌ | ✅ |
| Custom Hashers | ❌ | ✅ |
| [Extensible Plugin System](/extending-nx/intro/getting-started) | ❌ | ✅ |
| Feature/Tool | Angular CLI | Nx |
| ----------------------------------------------------------------------------------------------------- | --------------- | ------------- |
| Create Angular Apps | ✅ | ✅ |
| Generate Angular Components, Services, etc. | ✅ | ✅ |
| Building & Bundling | ✅ | ✅ |
| Local Development Server | ✅ | ✅ |
| Code Schematics | ✅ | ✅ |
| Automated Update with Migrations | ✅ | ✅ (Enhanced) |
| Generators | ✅ (Schematics) | ✅ |
| Executors | ✅ (Builders) | ✅ |
| Advanced Generators (e.g. Module Federation, Tailwind,...) | ❌ | ✅ |
| Integrated Tooling (Jest, Cypress, Playwright etc.) | ❌ | ✅ |
| Support for [single-project Workspaces](/getting-started/tutorials/angular-standalone-tutorial) | ✅ | ✅ |
| First-Class [Monorepo Support](/getting-started/tutorials/angular-monorepo-tutorial) | ❌\* | ✅ |
| [Enforced Module Boundaries](/features/enforce-module-boundaries) | ❌ | ✅ |
| Interactive [Project Graph](/features/explore-graph) | ❌ | ✅ |
| Task Graph | ❌ | ✅ |
| [Running Tasks in Parallel](/recipes/running-tasks/run-tasks-in-parallel) | ❌ | ✅ |
| Building, Testing [Only What is Affected](/features/run-tasks#run-tasks-on-projects-affected-by-a-pr) | ❌ | ✅ |
| [Local Caching](/features/cache-task-results) | ❌\*\* | ✅ |
| [Remote Caching](/ci/features/remote-cache) | ❌ | ✅ |
| [Distributed Task Execution on CI](/ci/features/distribute-task-execution) | ❌ | ✅ |
| Custom Hashers | ❌ | ✅ |
| [Extensible Plugin System](/extending-nx/intro/getting-started) | ❌ | ✅ |
{% callout type="info" title="Notes" %}
@ -118,7 +118,7 @@ More details: Nx [project configuration](/reference/project-configuration).
Nx comes with slightly different terminology than the Angular CLI for some features.
**Angular Builders** are called [Executors](/core-features/plugin-features/use-task-executors) in Nx but work very much similarly. You use them in your project configuration to define how to build, test, lint, and serve your project. You can use both Nx executors from [Nx Plugins](/plugin-registry) or Angular Builders from the Angular Devkit.
**Angular Builders** are called [Executors](/concepts/executors-and-configurations) in Nx but work very much similarly. You use them in your project configuration to define how to build, test, lint, and serve your project. You can use both Nx executors from [Nx Plugins](/plugin-registry) or Angular Builders from the Angular Devkit.
```json
{
@ -134,7 +134,7 @@ Nx comes with slightly different terminology than the Angular CLI for some featu
}
```
**Angular Schematics** are called [Generators](/core-features/plugin-features/use-code-generators) in Nx. You can invoke them in the same way as you would with the Angular CLI, but you use the `nx` command instead of `ng`:
**Angular Schematics** are called [Generators](/features/generate-code) in Nx. You can invoke them in the same way as you would with the Angular CLI, but you use the `nx` command instead of `ng`:
```shell
npx nx g @nx/angular:component my-component
@ -154,7 +154,7 @@ Commands are run in the very same way as with the Angular CLI. You just switch `
npx nx serve
```
Nx has more abilities to run commands in parallel, just for specific projects etc. Find out more [in the docs](/core-features/run-tasks).
Nx has more abilities to run commands in parallel, just for specific projects etc. Find out more [in the docs](/features/run-tasks).
### Integrating with Modern Tools
@ -189,7 +189,7 @@ What's the difference?
`nx migrate` does this by splitting the process into two steps. `nx migrate latest` creates a `migrations.json` file with a list of all the migrations needed by Nx, Angular, and other packages. You can then modify that file before running `nx migrate --run-migrations` to execute those migrations.
To reiterate: `nx migrate` runs the migrations written by the Angular team the same way `ng update` runs them. So everything should still work. You just get more control over how it works. You can learn more in our docs about [Automate Updating Dependencies](/core-features/automate-updating-dependencies).
To reiterate: `nx migrate` runs the migrations written by the Angular team the same way `ng update` runs them. So everything should still work. You just get more control over how it works. You can learn more in our docs about [Automate Updating Dependencies](/features/automate-updating-dependencies).
### 'ng add'
@ -210,16 +210,16 @@ Nx is designed to be fast. The Angular CLI leverages Webpack's caching, which Nx
Features like
- only running tasks on [affected projects](/ci/features/affected)
- running [tasks in parallel](/core-features/run-tasks#run-tasks-for-multiple-projects)
- applying [computation caching](/core-features/cache-task-results)
- running [tasks in parallel](/features/run-tasks#run-tasks-for-multiple-projects)
- applying [computation caching](/features/cache-task-results)
- offering [remote caching abilities](/ci/features/remote-cache) on CI
- offering [task distribution across machines (DTE)](/ci/features/distribute-task-execution)
- offering [task distribution across machines (Nx Agents)](/ci/features/distribute-task-execution)
And, Nx already uses fast, modern tooling like [ESBuild](/nx-api/esbuild), [Vite](/nx-api/vite), Vitest and [Rspack](/nx-api/rspack) for non-Angular stacks. So once Angular is ready to use these tools, Nx will also be ready.
### Editor Integration
Nx goes beyond being just a CLI and comes with [Nx Console](/core-features/integrate-with-editors), a VSCode and WebStorm extension allowing you to run commands, generate code and visualize your workspace.
Nx goes beyond being just a CLI and comes with [Nx Console](/features/integrate-with-editors), a VSCode and WebStorm extension allowing you to run commands, generate code and visualize your workspace.
![Nx Console screenshot](/shared/images/nx-console/nx-console-screenshot.webp)
@ -228,13 +228,13 @@ Nx goes beyond being just a CLI and comes with [Nx Console](/core-features/integ
Nx is really made to scale with you. You can
- start small with a single-project workspace
- modularize your application into more fine-grained libraries for better maintainability as your application (and team) grows ([more about that here](/getting-started/tutorials/angular-standalone-tutorial#modularizing-your-angular-app-with-local-libraries)), including mechanisms to make sure [things stay within their boundaries](/core-features/enforce-module-boundaries)
- modularize your application into more fine-grained libraries for better maintainability as your application (and team) grows ([more about that here](/getting-started/tutorials/angular-standalone-tutorial#modularizing-your-angular-app-with-local-libraries)), including mechanisms to make sure [things stay within their boundaries](/features/enforce-module-boundaries)
- you can then migrate to a monorepo when you are ready and need one ([more here](/recipes/tips-n-tricks/standalone-to-integrated))
- or even [add Webpack Module Federation support](/recipes/angular/module-federation-with-ssr)
### Visualize your Workspace
As you start modularizing your Angular workspace, Nx can visualize it using the `nx graph` command or via [Nx Console](/core-features/integrate-with-editors) directly in your editor.
As you start modularizing your Angular workspace, Nx can visualize it using the `nx graph` command or via [Nx Console](/features/integrate-with-editors) directly in your editor.
{% graph height="450px" %}
@ -344,7 +344,7 @@ As you start modularizing your Angular workspace, Nx can visualize it using the
{% /graph %}
Learn more about the [graph features here](/core-features/explore-graph).
Learn more about the [graph features here](/features/explore-graph).
### Extensible and Customizable: Make it fit your own needs

Some files were not shown because too many files have changed in this diff Show More