diff --git a/.circleci/config.yml b/.circleci/config.yml index 02a411c143698c..3e00fd46769e19 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -87,8 +87,9 @@ jobs: NX_E2E_RUN_E2E: 'true' NX_CI_EXECUTION_ENV: 'linux' steps: + - run: lscpu - checkout - - run: npx nx-cloud@next start-ci-run --stop-agents-after="e2e" + - run: npx nx-cloud@next start-ci-run --distributes-on="8 linux-medium" --stop-agents-after="e2e" - run: command: | sudo apt-get update @@ -99,6 +100,9 @@ jobs: os: linux - nx/set-shas: main-branch-name: 'master' + - run: + name: Benchmark + command: node tools/benchmark/benchmark.js - run: name: Check Documentation command: pnpm nx documentation --no-dte @@ -161,6 +165,11 @@ jobs: command: | pnpm nx affected -t e2e-macos --parallel=1 --base=$NX_BASE --head=$NX_HEAD no_output_timeout: 45m + - run: + name: Close CI group + command: | + pnpm nx-cloud stop-all-agents + no_output_timeout: 45m # ------------------------- # WORKFLOWS(JOBS) diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index b447f51690ba05..9874951939317e 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -158,9 +158,11 @@ jobs: timeout-minutes: 45 steps: - uses: actions/checkout@v3 + if: ${{ !contains(github.ref, '-') }} - name: Build id: build - uses: cross-platform-actions/action@v0.21.0 + if: ${{ !contains(github.ref, '-') }} + uses: cross-platform-actions/action@v0.21.1 env: DEBUG: napi:* RUSTUP_IO_THREADS: 1 @@ -197,9 +199,10 @@ jobs: rm -rf node_modules rm -rf dist echo "KILL ALL NODE PROCESSES" - killall node + killall node || true echo "COMPLETE" - name: Upload artifact + if: ${{ !contains(github.ref, '-') }} uses: actions/upload-artifact@v3 with: name: bindings-freebsd @@ -240,12 +243,15 @@ jobs: npm config set //registry.npmjs.org/:_authToken=$NPM_TOKEN pnpm nx-release --local=false $GITHUB_REF_NAME - name: Trigger Docs Release - # Publish docs only on a full release and when publishing the latest version - if: ${{ !github.event.release.prerelease && github.event.release.target_commitish == 'master' }} + # Publish docs only on a full release + if: ${{ !github.event.release.prerelease }} run: | + # Publish docs only when publishing the latest version + if [ "$(git describe --tags `git rev-list --tags --max-count=1`)" = "$GITHUB_REF_NAME" ]; then # We force recreate the branch in order to always be up to date and avoid merge conflicts within the automated workflow git branch -f website git push -f origin website + fi env: GH_TOKEN: ${{ github.token }} NPM_TOKEN: ${{ secrets.NPM_TOKEN }} diff --git a/.nx/workflows/agents.yaml b/.nx/workflows/agents.yaml index 7a5cfe9ca1c61b..97be10d530e5e9 100644 --- a/.nx/workflows/agents.yaml +++ b/.nx/workflows/agents.yaml @@ -1,59 +1,61 @@ -parallelism: 8 -env: - CI: 'true' - GIT_AUTHOR_EMAIL: test@test.com - GIT_AUTHOR_NAME: Test - GIT_COMMITTER_EMAIL: test@test.com - GIT_COMMITTER_NAME: Test - NX_E2E_CI_CACHE_KEY: e2e-circleci-linux - NX_VERBOSE_LOGGING: 'false' - NX_DAEMON: 'true' - NX_PERF_LOGGING: 'false' - NX_NATIVE_LOGGING: 'false' - SELECTED_PM: 'pnpm' - NX_E2E_RUN_E2E: 'true' - NPM_CONFIG_PREFIX: '/home/workflows/.npm-global' - NX_CLOUD_ACCESS_TOKEN: '{{secrets.NX_CLOUD_ACCESS_TOKEN}}' -on: - - events: - - CREATE_RUN_GROUP -steps: - - name: Checkout - uses: 'nrwl/nx-cloud-workflows/v1.1/workflow-steps/checkout/main.yaml' - - - name: Cache restore - uses: 'nrwl/nx-cloud-workflows/v1.1/workflow-steps/cache/main.yaml' +launch-templates: + linux-medium: + resource-class: 'docker_linux_amd64/medium+' env: - KEY: 'pnpm-lock.yaml' - PATHS: | - node_modules - ~/.cache/Cypress - ~/.pnpm-store - BASE_BRANCH: 'master' - - - 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 - script: | - curl --proto '=https' --tlsv1.3 https://sh.rustup.rs -sSf | sh -s -- -y - source "$HOME/.cargo/env" - rustup toolchain install 1.70.0 - - - name: Configure git metadata (needed for lerna smoke tests) - script: | - git config --global user.email test@test.com - git config --global user.name "Test Test" - - - name: Run Agent - script: | - source "$HOME/.cargo/env" - npx nx-cloud start-agent + CI: 'true' + GIT_AUTHOR_EMAIL: test@test.com + GIT_AUTHOR_NAME: Test + GIT_COMMITTER_EMAIL: test@test.com + GIT_COMMITTER_NAME: Test + NX_E2E_CI_CACHE_KEY: e2e-circleci-linux + NX_VERBOSE_LOGGING: 'true' + NX_PERF_LOGGING: 'false' + NX_NATIVE_LOGGING: 'false' + SELECTED_PM: 'pnpm' + NX_E2E_RUN_E2E: 'true' + NPM_CONFIG_PREFIX: '/home/workflows/.npm-global' + NX_CLOUD_ACCESS_TOKEN: '{{secrets.NX_CLOUD_ACCESS_TOKEN}}' + init-steps: + - name: LSCPU + script: | + lscpu + - name: Checkout + uses: 'nrwl/nx-cloud-workflows/v1.1/workflow-steps/checkout/main.yaml' + + - name: Cache restore + uses: 'nrwl/nx-cloud-workflows/v1.1/workflow-steps/cache/main.yaml' + env: + KEY: 'pnpm-lock.yaml' + PATHS: | + node_modules + ~/.cache/Cypress + ~/.pnpm-store + BASE_BRANCH: 'master' + + - 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 + script: | + curl --proto '=https' --tlsv1.3 https://sh.rustup.rs -sSf | sh -s -- -y + source "$HOME/.cargo/env" + rustup toolchain install 1.70.0 + + - name: Configure git metadata (needed for lerna smoke tests) + script: | + git config --global user.email test@test.com + git config --global user.name "Test Test" + + - name: Load Cargo Env + script: echo "PATH=$HOME/.cargo/bin:$PATH" >> $NX_CLOUD_ENV + + - name: Benchmark + script: node tools/benchmark/benchmark.js diff --git a/Cargo.lock b/Cargo.lock index c50e3f6f9ae87f..79cf191b7a86f5 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -293,6 +293,20 @@ dependencies = [ "syn 2.0.15", ] +[[package]] +name = "dashmap" +version = "5.5.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "978747c1d849a7d2ee5e8adc0159961c48fb7e5db2f06af6723b80123bb53856" +dependencies = [ + "cfg-if", + "hashbrown", + "lock_api", + "once_cell", + "parking_lot_core", + "rayon", +] + [[package]] name = "difflib" version = "0.4.0" @@ -435,9 +449,9 @@ dependencies = [ [[package]] name = "futures" -version = "0.3.28" +version = "0.3.29" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "23342abe12aba583913b2e62f22225ff9c950774065e4bfb61a19cd9770fec40" +checksum = "da0290714b38af9b4a7b094b8a37086d1b4e61f2df9122c3cad2577669145335" dependencies = [ "futures-channel", "futures-core", @@ -450,9 +464,9 @@ dependencies = [ [[package]] name = "futures-channel" -version = "0.3.28" +version = "0.3.29" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "955518d47e09b25bbebc7a18df10b81f0c766eaf4c4f1cccef2fca5f2a4fb5f2" +checksum = "ff4dd66668b557604244583e3e1e1eada8c5c2e96a6d0d6653ede395b78bbacb" dependencies = [ "futures-core", "futures-sink", @@ -460,15 +474,15 @@ dependencies = [ [[package]] name = "futures-core" -version = "0.3.28" +version = "0.3.29" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "4bca583b7e26f571124fe5b7561d49cb2868d79116cfa0eefce955557c6fee8c" +checksum = "eb1d22c66e66d9d72e1758f0bd7d4fd0bee04cad842ee34587d68c07e45d088c" [[package]] name = "futures-executor" -version = "0.3.28" +version = "0.3.29" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "ccecee823288125bd88b4d7f565c9e58e41858e47ab72e8ea2d64e93624386e0" +checksum = "0f4fb8693db0cf099eadcca0efe2a5a22e4550f98ed16aba6c48700da29597bc" dependencies = [ "futures-core", "futures-task", @@ -477,15 +491,15 @@ dependencies = [ [[package]] name = "futures-io" -version = "0.3.28" +version = "0.3.29" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "4fff74096e71ed47f8e023204cfd0aa1289cd54ae5430a9523be060cdb849964" +checksum = "8bf34a163b5c4c52d0478a4d757da8fb65cabef42ba90515efee0f6f9fa45aaa" [[package]] name = "futures-macro" -version = "0.3.28" +version = "0.3.29" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "89ca545a94061b6365f2c7355b4b32bd20df3ff95f02da9329b34ccc3bd6ee72" +checksum = "53b153fd91e4b0147f4aced87be237c98248656bb01050b96bf3ee89220a8ddb" dependencies = [ "proc-macro2", "quote", @@ -494,21 +508,21 @@ dependencies = [ [[package]] name = "futures-sink" -version = "0.3.28" +version = "0.3.29" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "f43be4fe21a13b9781a69afa4985b0f6ee0e1afab2c6f454a8cf30e2b2237b6e" +checksum = "e36d3378ee38c2a36ad710c5d30c2911d752cb941c00c72dbabfb786a7970817" [[package]] name = "futures-task" -version = "0.3.28" +version = "0.3.29" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "76d3d132be6c0e6aa1534069c705a74a5997a356c0dc2f86a47765e5617c5b65" +checksum = "efd193069b0ddadc69c46389b740bbccdd97203899b48d09c5f7969591d6bae2" [[package]] name = "futures-util" -version = "0.3.28" +version = "0.3.29" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "26b01e40b772d54cf6c6d721c1d1abd0647a0106a12ecaa1c186273392a69533" +checksum = "a19526d624e703a3179b3d322efec918b6246ea0fa51d41124525f00f1cc8104" dependencies = [ "futures-channel", "futures-core", @@ -930,6 +944,12 @@ version = "1.0.6" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "453ad9f582a441959e5f0d088b02ce04cfe8d51a8eaf077f12ac6d3e94164ca6" +[[package]] +name = "json_comments" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "41ee439ee368ba4a77ac70d04f14015415af8600d6c894dc1f11bd79758c57d5" + [[package]] name = "kqueue" version = "1.0.7" @@ -1053,9 +1073,9 @@ checksum = "ece97ea872ece730aed82664c424eb4c8291e1ff2480247ccf7409044bc6479f" [[package]] name = "lock_api" -version = "0.4.9" +version = "0.4.11" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "435011366fe56583b16cf956f9df0095b405b82d76425bc8981c0e22e60ec4df" +checksum = "3c168f8615b12bc01f9c17e2eb0cc07dcae1940121185446edc3744920e8ef45" dependencies = [ "autocfg", "scopeguard", @@ -1343,6 +1363,7 @@ dependencies = [ "assert_fs", "colored", "crossbeam-channel", + "dashmap", "fs_extra", "globset", "hashbrown", @@ -1366,6 +1387,7 @@ dependencies = [ "tokio", "tracing", "tracing-subscriber", + "tsconfig", "walkdir", "watchexec", "watchexec-events", @@ -1398,15 +1420,15 @@ dependencies = [ [[package]] name = "parking_lot_core" -version = "0.9.7" +version = "0.9.9" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "9069cbb9f99e3a5083476ccb29ceb1de18b9118cafa53e90c9551235de2b9521" +checksum = "4c42a9226546d68acdd9c0a280d17ce19bfe27a46bf68784e4066115788d008e" dependencies = [ "cfg-if", "libc", - "redox_syscall 0.2.16", + "redox_syscall 0.4.1", "smallvec", - "windows-sys 0.45.0", + "windows-targets 0.48.0", ] [[package]] @@ -1536,9 +1558,9 @@ dependencies = [ [[package]] name = "proc-macro2" -version = "1.0.56" +version = "1.0.69" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "2b63bdb0cd06f1f4dedf69b254734f9b45af66e4a031e42a7480257d9898b435" +checksum = "134c189feb4956b20f6f547d2cf727d4c0fe06722b20a0eec87ed445a97f92da" dependencies = [ "unicode-ident", ] @@ -1652,6 +1674,15 @@ dependencies = [ "bitflags 1.3.2", ] +[[package]] +name = "redox_syscall" +version = "0.4.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4722d768eff46b75989dd134e5c353f0d6296e5aaa3132e776cbdb56be7731aa" +dependencies = [ + "bitflags 1.3.2", +] + [[package]] name = "redox_users" version = "0.4.3" @@ -1727,6 +1758,12 @@ dependencies = [ "windows-sys 0.45.0", ] +[[package]] +name = "ryu" +version = "1.0.15" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1ad4cc8da4ef723ed60bced201181d83791ad433213d8c24efffda1eec85d741" + [[package]] name = "same-file" version = "1.0.6" @@ -1774,6 +1811,17 @@ dependencies = [ "syn 1.0.107", ] +[[package]] +name = "serde_json" +version = "1.0.99" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "46266871c240a00b8f503b877622fe33430b3c7d963bdc0f2adc511e54a1eae3" +dependencies = [ + "itoa", + "ryu", + "serde", +] + [[package]] name = "sha1_smol" version = "1.0.0" @@ -2284,6 +2332,19 @@ dependencies = [ "stable_deref_trait", ] +[[package]] +name = "tsconfig" +version = "0.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7c89ed286b13fd7e343eb628d8511fb4fdc99053acccb2263897e0d89526462b" +dependencies = [ + "json_comments", + "regex", + "serde", + "serde_json", + "thiserror", +] + [[package]] name = "typed-arena" version = "2.0.2" diff --git a/Cargo.toml b/Cargo.toml index c4f876bf1acd74..217f75ad61044b 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,7 +1,8 @@ [workspace] +resolver = '2' members = [ - 'packages/nx' + 'packages/nx', ] [profile.release] diff --git a/docs/README.md b/docs/README.md index 58fb7ce570699f..391746b162257d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -149,6 +149,8 @@ You can also statically highlight a set of lines (the user won't be able to chan ‎``` ```` +You can also specify ranges like `highlightLines=[2,3,"8-10"]`. + #### Terminal command To display a terminal command, use: diff --git a/docs/generated/cli/release.md b/docs/generated/cli/release.md index e0b7d91e763026..f1f3cd6c88aa3d 100644 --- a/docs/generated/cli/release.md +++ b/docs/generated/cli/release.md @@ -67,6 +67,42 @@ nx release version [specifier] #### Options +##### git-commit + +Type: `boolean` + +Whether or not to automatically commit the changes made by this command + +##### git-commit-args + +Type: `string` + +Additional arguments (added after the --message argument, which may or may not be customized with --git-commit-message) to pass to the `git commit` command invoked behind the scenes + +##### git-commit-message + +Type: `string` + +Custom git commit message to use when committing the changes made by this command. {version} will be dynamically interpolated when performing fixed releases, interpolated tags will be appended to the commit body when performing independent releases. + +##### git-tag + +Type: `boolean` + +Whether or not to automatically tag the changes made by this command + +##### git-tag-args + +Type: `string` + +Additional arguments to pass to the `git tag` command invoked behind the scenes + +##### git-tag-message + +Type: `string` + +Custom git tag message to use when tagging the changes made by this command. This defaults to be the same value as the tag itself. + ##### help Type: `boolean` @@ -85,6 +121,14 @@ Type: `string` Exact version or semver keyword to apply to the selected release group. +##### stageChanges + +Type: `boolean` + +Default: `false` + +Whether or not to stage the changes made by this command, irrespective of the git config in nx.json related to automated commits. Useful when combining this command with changelog generation. + ##### version Type: `boolean` @@ -107,6 +151,42 @@ Type: `string` The git reference to use as the start of the changelog. If not set it will attempt to resolve the latest tag and use that +##### git-commit + +Type: `boolean` + +Whether or not to automatically commit the changes made by this command + +##### git-commit-args + +Type: `string` + +Additional arguments (added after the --message argument, which may or may not be customized with --git-commit-message) to pass to the `git commit` command invoked behind the scenes + +##### git-commit-message + +Type: `string` + +Custom git commit message to use when committing the changes made by this command. {version} will be dynamically interpolated when performing fixed releases, interpolated tags will be appended to the commit body when performing independent releases. + +##### git-tag + +Type: `boolean` + +Whether or not to automatically tag the changes made by this command + +##### git-tag-args + +Type: `string` + +Additional arguments to pass to the `git tag` command invoked behind the scenes + +##### git-tag-message + +Type: `string` + +Custom git tag message to use when tagging the changes made by this command. This defaults to be the same value as the tag itself. + ##### gitRemote Type: `string` @@ -129,14 +209,6 @@ Choices: [all, workspace, projects] Interactively modify changelog markdown contents in your code editor before applying the changes. You can set it to be interactive for all changelogs, or only the workspace level, or only the project level -##### tagVersionPrefix - -Type: `string` - -Default: `v` - -Prefix to apply to the version when creating the Github release tag - ##### to Type: `string` @@ -203,6 +275,12 @@ Default: `false` Ignore cycles in the task graph +##### otp + +Type: `number` + +A one-time password for publishing to a registry that requires 2FA + ##### output-style Type: `string` diff --git a/docs/generated/devkit/CreateNodesFunction.md b/docs/generated/devkit/CreateNodesFunction.md index 2d47929e9fd510..f26253839cf9af 100644 --- a/docs/generated/devkit/CreateNodesFunction.md +++ b/docs/generated/devkit/CreateNodesFunction.md @@ -1,6 +1,6 @@ # Type alias: CreateNodesFunction -Ƭ **CreateNodesFunction**<`T`\>: (`projectConfigurationFile`: `string`, `options`: `T` \| `undefined`, `context`: [`CreateNodesContext`](../../devkit/documents/CreateNodesContext)) => { `externalNodes?`: `Record`<`string`, [`ProjectGraphExternalNode`](../../devkit/documents/ProjectGraphExternalNode)\> ; `projects?`: `Record`<`string`, `Optional`<[`ProjectConfiguration`](../../devkit/documents/ProjectConfiguration), `"root"`\>\> } +Ƭ **CreateNodesFunction**<`T`\>: (`projectConfigurationFile`: `string`, `options`: `T` \| `undefined`, `context`: [`CreateNodesContext`](../../devkit/documents/CreateNodesContext)) => [`CreateNodesResult`](../../devkit/documents/CreateNodesResult) \| `Promise`<[`CreateNodesResult`](../../devkit/documents/CreateNodesResult)\> #### Type parameters @@ -10,7 +10,7 @@ #### Type declaration -▸ (`projectConfigurationFile`, `options`, `context`): `Object` +▸ (`projectConfigurationFile`, `options`, `context`): [`CreateNodesResult`](../../devkit/documents/CreateNodesResult) \| `Promise`<[`CreateNodesResult`](../../devkit/documents/CreateNodesResult)\> A function which parses a configuration file into a set of nodes. Used for creating nodes for the [ProjectGraph](../../devkit/documents/ProjectGraph) @@ -25,9 +25,4 @@ Used for creating nodes for the [ProjectGraph](../../devkit/documents/ProjectGra ##### Returns -`Object` - -| Name | Type | Description | -| :--------------- | :---------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------- | -| `externalNodes?` | `Record`<`string`, [`ProjectGraphExternalNode`](../../devkit/documents/ProjectGraphExternalNode)\> | A map of external node name -> external node. External nodes do not have a root, so the key is their name. | -| `projects?` | `Record`<`string`, `Optional`<[`ProjectConfiguration`](../../devkit/documents/ProjectConfiguration), `"root"`\>\> | A map of project root -> project configuration | +[`CreateNodesResult`](../../devkit/documents/CreateNodesResult) \| `Promise`<[`CreateNodesResult`](../../devkit/documents/CreateNodesResult)\> diff --git a/docs/generated/devkit/CreateNodesResult.md b/docs/generated/devkit/CreateNodesResult.md new file mode 100644 index 00000000000000..6a7fafe07f03f4 --- /dev/null +++ b/docs/generated/devkit/CreateNodesResult.md @@ -0,0 +1,24 @@ +# Interface: CreateNodesResult + +## Table of contents + +### Properties + +- [externalNodes](../../devkit/documents/CreateNodesResult#externalnodes): Record<string, ProjectGraphExternalNode> +- [projects](../../devkit/documents/CreateNodesResult#projects): Record<string, Optional<ProjectConfiguration, "root">> + +## Properties + +### externalNodes + +• `Optional` **externalNodes**: `Record`<`string`, [`ProjectGraphExternalNode`](../../devkit/documents/ProjectGraphExternalNode)\> + +A map of external node name -> external node. External nodes do not have a root, so the key is their name. + +--- + +### projects + +• `Optional` **projects**: `Record`<`string`, `Optional`<[`ProjectConfiguration`](../../devkit/documents/ProjectConfiguration), `"root"`\>\> + +A map of project root -> project configuration diff --git a/docs/generated/devkit/NxPluginV2.md b/docs/generated/devkit/NxPluginV2.md index a8d3f804034724..4d6d8ec7bb0f4c 100644 --- a/docs/generated/devkit/NxPluginV2.md +++ b/docs/generated/devkit/NxPluginV2.md @@ -1,19 +1,19 @@ -# Type alias: NxPluginV2 +# Type alias: NxPluginV2 -Ƭ **NxPluginV2**<`T`\>: `Object` +Ƭ **NxPluginV2**<`TOptions`\>: `Object` A plugin for Nx which creates nodes and dependencies for the [ProjectGraph](../../devkit/documents/ProjectGraph) #### Type parameters -| Name | Type | -| :--- | :-------- | -| `T` | `unknown` | +| Name | Type | +| :--------- | :-------- | +| `TOptions` | `unknown` | #### Type declaration -| Name | Type | Description | -| :-------------------- | :---------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------- | -| `createDependencies?` | [`CreateDependencies`](../../devkit/documents/CreateDependencies)<`T`\> | Provides a function to analyze files to create dependencies for the [ProjectGraph](../../devkit/documents/ProjectGraph) | -| `createNodes?` | [`CreateNodes`](../../devkit/documents/CreateNodes)<`T`\> | Provides a file pattern and function that retrieves configuration info from those files. e.g. { '\*_/_.csproj': buildProjectsFromCsProjFile } | -| `name` | `string` | - | +| Name | Type | Description | +| :-------------------- | :----------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------- | +| `createDependencies?` | [`CreateDependencies`](../../devkit/documents/CreateDependencies)<`TOptions`\> | Provides a function to analyze files to create dependencies for the [ProjectGraph](../../devkit/documents/ProjectGraph) | +| `createNodes?` | [`CreateNodes`](../../devkit/documents/CreateNodes) | Provides a file pattern and function that retrieves configuration info from those files. e.g. { '\*_/_.csproj': buildProjectsFromCsProjFile } | +| `name` | `string` | - | diff --git a/docs/generated/devkit/README.md b/docs/generated/devkit/README.md index 6661d52e35a412..889a8fe0332c7f 100644 --- a/docs/generated/devkit/README.md +++ b/docs/generated/devkit/README.md @@ -25,6 +25,7 @@ It only uses language primitives and immutable objects - [CreateDependenciesContext](../../devkit/documents/CreateDependenciesContext) - [CreateNodesContext](../../devkit/documents/CreateNodesContext) +- [CreateNodesResult](../../devkit/documents/CreateNodesResult) - [DefaultTasksRunnerOptions](../../devkit/documents/DefaultTasksRunnerOptions) - [ExecutorContext](../../devkit/documents/ExecutorContext) - [ExecutorsJson](../../devkit/documents/ExecutorsJson) diff --git a/docs/generated/manifests/cloud.json b/docs/generated/manifests/cloud.json index c33bb560985c6f..947fa5fa8e9945 100644 --- a/docs/generated/manifests/cloud.json +++ b/docs/generated/manifests/cloud.json @@ -16,13 +16,34 @@ "tags": [] }, { - "id": "nx-cloud-workflows", - "name": "Nx Cloud Workflows", - "description": "", - "file": "nx-cloud/intro/nx-cloud-workflows", - "itemList": [], + "id": "tutorials", + "name": "Tutorials", + "description": "Tutorials setting up CI with Nx", + "file": "", + "itemList": [ + { + "id": "circle", + "name": "Circle CI with Nx", + "description": "", + "file": "nx-cloud/tutorial/circle", + "itemList": [], + "isExternal": false, + "path": "/nx-cloud/intro/tutorials/circle", + "tags": [] + }, + { + "id": "github-actions", + "name": "GitHub Actions with Nx", + "description": "", + "file": "nx-cloud/tutorial/github-actions", + "itemList": [], + "isExternal": false, + "path": "/nx-cloud/intro/tutorials/github-actions", + "tags": [] + } + ], "isExternal": false, - "path": "/nx-cloud/intro/nx-cloud-workflows", + "path": "/nx-cloud/intro/tutorials", "tags": [] } ], @@ -40,14 +61,55 @@ "path": "/nx-cloud/intro/ci-with-nx", "tags": [] }, - "/nx-cloud/intro/nx-cloud-workflows": { - "id": "nx-cloud-workflows", - "name": "Nx Cloud Workflows", + "/nx-cloud/intro/tutorials": { + "id": "tutorials", + "name": "Tutorials", + "description": "Tutorials setting up CI with Nx", + "file": "", + "itemList": [ + { + "id": "circle", + "name": "Circle CI with Nx", + "description": "", + "file": "nx-cloud/tutorial/circle", + "itemList": [], + "isExternal": false, + "path": "/nx-cloud/intro/tutorials/circle", + "tags": [] + }, + { + "id": "github-actions", + "name": "GitHub Actions with Nx", + "description": "", + "file": "nx-cloud/tutorial/github-actions", + "itemList": [], + "isExternal": false, + "path": "/nx-cloud/intro/tutorials/github-actions", + "tags": [] + } + ], + "isExternal": false, + "path": "/nx-cloud/intro/tutorials", + "tags": [] + }, + "/nx-cloud/intro/tutorials/circle": { + "id": "circle", + "name": "Circle CI with Nx", "description": "", - "file": "nx-cloud/intro/nx-cloud-workflows", + "file": "nx-cloud/tutorial/circle", "itemList": [], "isExternal": false, - "path": "/nx-cloud/intro/nx-cloud-workflows", + "path": "/nx-cloud/intro/tutorials/circle", + "tags": [] + }, + "/nx-cloud/intro/tutorials/github-actions": { + "id": "github-actions", + "name": "GitHub Actions with Nx", + "description": "", + "file": "nx-cloud/tutorial/github-actions", + "itemList": [], + "isExternal": false, + "path": "/nx-cloud/intro/tutorials/github-actions", "tags": [] }, "/nx-cloud/features": { @@ -95,6 +157,16 @@ "isExternal": false, "path": "/nx-cloud/features/on-premise", "tags": ["on-premise"] + }, + { + "id": "nx-cloud-workflows", + "name": "Nx Cloud Workflows", + "description": "", + "file": "nx-cloud/intro/nx-cloud-workflows", + "itemList": [], + "isExternal": false, + "path": "/nx-cloud/features/nx-cloud-workflows", + "tags": [] } ], "isExternal": false, @@ -141,6 +213,87 @@ "path": "/nx-cloud/features/on-premise", "tags": ["on-premise"] }, + "/nx-cloud/features/nx-cloud-workflows": { + "id": "nx-cloud-workflows", + "name": "Nx Cloud Workflows", + "description": "", + "file": "nx-cloud/intro/nx-cloud-workflows", + "itemList": [], + "isExternal": false, + "path": "/nx-cloud/features/nx-cloud-workflows", + "tags": [] + }, + "/nx-cloud/concepts": { + "id": "concepts", + "name": "Concepts", + "description": "Learn how to manage Nx Cloud subscriptions and other options.", + "file": "", + "itemList": [ + { + "id": "dte", + "name": "Improve Worst Case CI Times", + "description": "", + "file": "shared/concepts/improve-worst-case-ci-times", + "itemList": [], + "isExternal": false, + "path": "/nx-cloud/concepts/dte", + "tags": ["distribute-task-execution"] + }, + { + "id": "scenarios", + "name": "Security Scenarios", + "description": "", + "file": "nx-cloud/concepts/scenarios", + "itemList": [], + "isExternal": false, + "path": "/nx-cloud/concepts/scenarios", + "tags": [] + }, + { + "id": "encryption", + "name": "End to End Encryption", + "description": "", + "file": "nx-cloud/concepts/encryption", + "itemList": [], + "isExternal": false, + "path": "/nx-cloud/concepts/encryption", + "tags": [] + } + ], + "isExternal": false, + "path": "/nx-cloud/concepts", + "tags": [] + }, + "/nx-cloud/concepts/dte": { + "id": "dte", + "name": "Improve Worst Case CI Times", + "description": "", + "file": "shared/concepts/improve-worst-case-ci-times", + "itemList": [], + "isExternal": false, + "path": "/nx-cloud/concepts/dte", + "tags": ["distribute-task-execution"] + }, + "/nx-cloud/concepts/scenarios": { + "id": "scenarios", + "name": "Security Scenarios", + "description": "", + "file": "nx-cloud/concepts/scenarios", + "itemList": [], + "isExternal": false, + "path": "/nx-cloud/concepts/scenarios", + "tags": [] + }, + "/nx-cloud/concepts/encryption": { + "id": "encryption", + "name": "End to End Encryption", + "description": "", + "file": "nx-cloud/concepts/encryption", + "itemList": [], + "isExternal": false, + "path": "/nx-cloud/concepts/encryption", + "tags": [] + }, "/nx-cloud/recipes": { "id": "recipes", "name": "Recipes", @@ -153,16 +306,6 @@ "description": "Learn how to set up Nx Cloud for your workspace.", "file": "", "itemList": [ - { - "id": "ci-setup", - "name": "CI Setup", - "description": "", - "file": "shared/ci-overview", - "itemList": [], - "isExternal": false, - "path": "/nx-cloud/recipes/set-up/ci-setup", - "tags": ["distribute-task-execution"] - }, { "id": "monorepo-ci-azure", "name": "Setting up Azure Pipelines", @@ -226,6 +369,37 @@ ], "isExternal": false, "path": "/nx-cloud/recipes/set-up", + "tags": ["distribute-task-execution"] + }, + { + "id": "security", + "name": "Security", + "description": "Manage access to Nx Cloud", + "file": "", + "itemList": [ + { + "id": "google-auth", + "name": "Authenticate with Google Identity", + "description": "", + "file": "nx-cloud/recipes/google-auth", + "itemList": [], + "isExternal": false, + "path": "/nx-cloud/recipes/security/google-auth", + "tags": [] + }, + { + "id": "access-tokens", + "name": "Access Tokens", + "description": "", + "file": "nx-cloud/recipes/access-tokens", + "itemList": [], + "isExternal": false, + "path": "/nx-cloud/recipes/security/access-tokens", + "tags": [] + } + ], + "isExternal": false, + "path": "/nx-cloud/recipes/security", "tags": [] }, { @@ -402,16 +576,6 @@ "description": "Learn how to set up Nx Cloud for your workspace.", "file": "", "itemList": [ - { - "id": "ci-setup", - "name": "CI Setup", - "description": "", - "file": "shared/ci-overview", - "itemList": [], - "isExternal": false, - "path": "/nx-cloud/recipes/set-up/ci-setup", - "tags": ["distribute-task-execution"] - }, { "id": "monorepo-ci-azure", "name": "Setting up Azure Pipelines", @@ -475,16 +639,6 @@ ], "isExternal": false, "path": "/nx-cloud/recipes/set-up", - "tags": [] - }, - "/nx-cloud/recipes/set-up/ci-setup": { - "id": "ci-setup", - "name": "CI Setup", - "description": "", - "file": "shared/ci-overview", - "itemList": [], - "isExternal": false, - "path": "/nx-cloud/recipes/set-up/ci-setup", "tags": ["distribute-task-execution"] }, "/nx-cloud/recipes/set-up/monorepo-ci-azure": { @@ -547,6 +701,57 @@ "path": "/nx-cloud/recipes/set-up/monorepo-ci-bitbucket-pipelines", "tags": [] }, + "/nx-cloud/recipes/security": { + "id": "security", + "name": "Security", + "description": "Manage access to Nx Cloud", + "file": "", + "itemList": [ + { + "id": "google-auth", + "name": "Authenticate with Google Identity", + "description": "", + "file": "nx-cloud/recipes/google-auth", + "itemList": [], + "isExternal": false, + "path": "/nx-cloud/recipes/security/google-auth", + "tags": [] + }, + { + "id": "access-tokens", + "name": "Access Tokens", + "description": "", + "file": "nx-cloud/recipes/access-tokens", + "itemList": [], + "isExternal": false, + "path": "/nx-cloud/recipes/security/access-tokens", + "tags": [] + } + ], + "isExternal": false, + "path": "/nx-cloud/recipes/security", + "tags": [] + }, + "/nx-cloud/recipes/security/google-auth": { + "id": "google-auth", + "name": "Authenticate with Google Identity", + "description": "", + "file": "nx-cloud/recipes/google-auth", + "itemList": [], + "isExternal": false, + "path": "/nx-cloud/recipes/security/google-auth", + "tags": [] + }, + "/nx-cloud/recipes/security/access-tokens": { + "id": "access-tokens", + "name": "Access Tokens", + "description": "", + "file": "nx-cloud/recipes/access-tokens", + "itemList": [], + "isExternal": false, + "path": "/nx-cloud/recipes/security/access-tokens", + "tags": [] + }, "/nx-cloud/recipes/source-control-integration": { "id": "source-control-integration", "name": "Source Control Integration", @@ -840,117 +1045,6 @@ "path": "/nx-cloud/recipes/other/ci-deployment", "tags": ["docker", "deploy"] }, - "/nx-cloud/account": { - "id": "account", - "name": "Account Management", - "description": "Learn how to manage Nx Cloud subscriptions and other options.", - "file": "", - "itemList": [ - { - "id": "users", - "name": "Users", - "description": "", - "file": "nx-cloud/account/users", - "itemList": [], - "isExternal": false, - "path": "/nx-cloud/account/users", - "tags": [] - }, - { - "id": "google-auth", - "name": "Authenticate with Google Identity", - "description": "", - "file": "nx-cloud/account/google-auth", - "itemList": [], - "isExternal": false, - "path": "/nx-cloud/account/google-auth", - "tags": [] - }, - { - "id": "access-tokens", - "name": "Access Tokens", - "description": "", - "file": "nx-cloud/account/access-tokens", - "itemList": [], - "isExternal": false, - "path": "/nx-cloud/account/access-tokens", - "tags": [] - }, - { - "id": "scenarios", - "name": "Security Scenarios", - "description": "", - "file": "nx-cloud/account/scenarios", - "itemList": [], - "isExternal": false, - "path": "/nx-cloud/account/scenarios", - "tags": [] - }, - { - "id": "encryption", - "name": "End to End Encryption", - "description": "", - "file": "nx-cloud/account/encryption", - "itemList": [], - "isExternal": false, - "path": "/nx-cloud/account/encryption", - "tags": [] - } - ], - "isExternal": false, - "path": "/nx-cloud/account", - "tags": [] - }, - "/nx-cloud/account/users": { - "id": "users", - "name": "Users", - "description": "", - "file": "nx-cloud/account/users", - "itemList": [], - "isExternal": false, - "path": "/nx-cloud/account/users", - "tags": [] - }, - "/nx-cloud/account/google-auth": { - "id": "google-auth", - "name": "Authenticate with Google Identity", - "description": "", - "file": "nx-cloud/account/google-auth", - "itemList": [], - "isExternal": false, - "path": "/nx-cloud/account/google-auth", - "tags": [] - }, - "/nx-cloud/account/access-tokens": { - "id": "access-tokens", - "name": "Access Tokens", - "description": "", - "file": "nx-cloud/account/access-tokens", - "itemList": [], - "isExternal": false, - "path": "/nx-cloud/account/access-tokens", - "tags": [] - }, - "/nx-cloud/account/scenarios": { - "id": "scenarios", - "name": "Security Scenarios", - "description": "", - "file": "nx-cloud/account/scenarios", - "itemList": [], - "isExternal": false, - "path": "/nx-cloud/account/scenarios", - "tags": [] - }, - "/nx-cloud/account/encryption": { - "id": "encryption", - "name": "End to End Encryption", - "description": "", - "file": "nx-cloud/account/encryption", - "itemList": [], - "isExternal": false, - "path": "/nx-cloud/account/encryption", - "tags": [] - }, "/nx-cloud/reference": { "id": "reference", "name": "Reference", diff --git a/docs/generated/manifests/menus.json b/docs/generated/manifests/menus.json index 41d2bb42b34ac8..a30c68244524e6 100644 --- a/docs/generated/manifests/menus.json +++ b/docs/generated/manifests/menus.json @@ -801,14 +801,6 @@ "children": [], "disableCollapsible": false }, - { - "name": "Improve Worst Case CI Times", - "path": "/concepts/dte", - "id": "dte", - "isExternal": false, - "children": [], - "disableCollapsible": false - }, { "name": "What is a Task Pipeline", "path": "/concepts/task-pipeline-configuration", @@ -1038,14 +1030,6 @@ "children": [], "disableCollapsible": false }, - { - "name": "Improve Worst Case CI Times", - "path": "/concepts/dte", - "id": "dte", - "isExternal": false, - "children": [], - "disableCollapsible": false - }, { "name": "What is a Task Pipeline", "path": "/concepts/task-pipeline-configuration", @@ -5550,11 +5534,28 @@ "disableCollapsible": false }, { - "name": "Nx Cloud Workflows", - "path": "/nx-cloud/intro/nx-cloud-workflows", - "id": "nx-cloud-workflows", + "name": "Tutorials", + "path": "/nx-cloud/intro/tutorials", + "id": "tutorials", "isExternal": false, - "children": [], + "children": [ + { + "name": "Circle CI with Nx", + "path": "/nx-cloud/intro/tutorials/circle", + "id": "circle", + "isExternal": false, + "children": [], + "disableCollapsible": false + }, + { + "name": "GitHub Actions with Nx", + "path": "/nx-cloud/intro/tutorials/github-actions", + "id": "github-actions", + "isExternal": false, + "children": [], + "disableCollapsible": false + } + ], "disableCollapsible": false } ], @@ -5569,9 +5570,42 @@ "disableCollapsible": false }, { - "name": "Nx Cloud Workflows", - "path": "/nx-cloud/intro/nx-cloud-workflows", - "id": "nx-cloud-workflows", + "name": "Tutorials", + "path": "/nx-cloud/intro/tutorials", + "id": "tutorials", + "isExternal": false, + "children": [ + { + "name": "Circle CI with Nx", + "path": "/nx-cloud/intro/tutorials/circle", + "id": "circle", + "isExternal": false, + "children": [], + "disableCollapsible": false + }, + { + "name": "GitHub Actions with Nx", + "path": "/nx-cloud/intro/tutorials/github-actions", + "id": "github-actions", + "isExternal": false, + "children": [], + "disableCollapsible": false + } + ], + "disableCollapsible": false + }, + { + "name": "Circle CI with Nx", + "path": "/nx-cloud/intro/tutorials/circle", + "id": "circle", + "isExternal": false, + "children": [], + "disableCollapsible": false + }, + { + "name": "GitHub Actions with Nx", + "path": "/nx-cloud/intro/tutorials/github-actions", + "id": "github-actions", "isExternal": false, "children": [], "disableCollapsible": false @@ -5613,6 +5647,14 @@ "isExternal": false, "children": [], "disableCollapsible": false + }, + { + "name": "Nx Cloud Workflows", + "path": "/nx-cloud/features/nx-cloud-workflows", + "id": "nx-cloud-workflows", + "isExternal": false, + "children": [], + "disableCollapsible": false } ], "disableCollapsible": false @@ -5649,6 +5691,71 @@ "children": [], "disableCollapsible": false }, + { + "name": "Nx Cloud Workflows", + "path": "/nx-cloud/features/nx-cloud-workflows", + "id": "nx-cloud-workflows", + "isExternal": false, + "children": [], + "disableCollapsible": false + }, + { + "name": "Concepts", + "path": "/nx-cloud/concepts", + "id": "concepts", + "isExternal": false, + "children": [ + { + "name": "Improve Worst Case CI Times", + "path": "/nx-cloud/concepts/dte", + "id": "dte", + "isExternal": false, + "children": [], + "disableCollapsible": false + }, + { + "name": "Security Scenarios", + "path": "/nx-cloud/concepts/scenarios", + "id": "scenarios", + "isExternal": false, + "children": [], + "disableCollapsible": false + }, + { + "name": "End to End Encryption", + "path": "/nx-cloud/concepts/encryption", + "id": "encryption", + "isExternal": false, + "children": [], + "disableCollapsible": false + } + ], + "disableCollapsible": false + }, + { + "name": "Improve Worst Case CI Times", + "path": "/nx-cloud/concepts/dte", + "id": "dte", + "isExternal": false, + "children": [], + "disableCollapsible": false + }, + { + "name": "Security Scenarios", + "path": "/nx-cloud/concepts/scenarios", + "id": "scenarios", + "isExternal": false, + "children": [], + "disableCollapsible": false + }, + { + "name": "End to End Encryption", + "path": "/nx-cloud/concepts/encryption", + "id": "encryption", + "isExternal": false, + "children": [], + "disableCollapsible": false + }, { "name": "Recipes", "path": "/nx-cloud/recipes", @@ -5661,14 +5768,6 @@ "id": "set-up", "isExternal": false, "children": [ - { - "name": "CI Setup", - "path": "/nx-cloud/recipes/set-up/ci-setup", - "id": "ci-setup", - "isExternal": false, - "children": [], - "disableCollapsible": false - }, { "name": "Setting up Azure Pipelines", "path": "/nx-cloud/recipes/set-up/monorepo-ci-azure", @@ -5720,6 +5819,31 @@ ], "disableCollapsible": false }, + { + "name": "Security", + "path": "/nx-cloud/recipes/security", + "id": "security", + "isExternal": false, + "children": [ + { + "name": "Authenticate with Google Identity", + "path": "/nx-cloud/recipes/security/google-auth", + "id": "google-auth", + "isExternal": false, + "children": [], + "disableCollapsible": false + }, + { + "name": "Access Tokens", + "path": "/nx-cloud/recipes/security/access-tokens", + "id": "access-tokens", + "isExternal": false, + "children": [], + "disableCollapsible": false + } + ], + "disableCollapsible": false + }, { "name": "Source Control Integration", "path": "/nx-cloud/recipes/source-control-integration", @@ -5860,14 +5984,6 @@ "id": "set-up", "isExternal": false, "children": [ - { - "name": "CI Setup", - "path": "/nx-cloud/recipes/set-up/ci-setup", - "id": "ci-setup", - "isExternal": false, - "children": [], - "disableCollapsible": false - }, { "name": "Setting up Azure Pipelines", "path": "/nx-cloud/recipes/set-up/monorepo-ci-azure", @@ -5919,14 +6035,6 @@ ], "disableCollapsible": false }, - { - "name": "CI Setup", - "path": "/nx-cloud/recipes/set-up/ci-setup", - "id": "ci-setup", - "isExternal": false, - "children": [], - "disableCollapsible": false - }, { "name": "Setting up Azure Pipelines", "path": "/nx-cloud/recipes/set-up/monorepo-ci-azure", @@ -5975,6 +6083,47 @@ "children": [], "disableCollapsible": false }, + { + "name": "Security", + "path": "/nx-cloud/recipes/security", + "id": "security", + "isExternal": false, + "children": [ + { + "name": "Authenticate with Google Identity", + "path": "/nx-cloud/recipes/security/google-auth", + "id": "google-auth", + "isExternal": false, + "children": [], + "disableCollapsible": false + }, + { + "name": "Access Tokens", + "path": "/nx-cloud/recipes/security/access-tokens", + "id": "access-tokens", + "isExternal": false, + "children": [], + "disableCollapsible": false + } + ], + "disableCollapsible": false + }, + { + "name": "Authenticate with Google Identity", + "path": "/nx-cloud/recipes/security/google-auth", + "id": "google-auth", + "isExternal": false, + "children": [], + "disableCollapsible": false + }, + { + "name": "Access Tokens", + "path": "/nx-cloud/recipes/security/access-tokens", + "id": "access-tokens", + "isExternal": false, + "children": [], + "disableCollapsible": false + }, { "name": "Source Control Integration", "path": "/nx-cloud/recipes/source-control-integration", @@ -6210,95 +6359,6 @@ "children": [], "disableCollapsible": false }, - { - "name": "Account Management", - "path": "/nx-cloud/account", - "id": "account", - "isExternal": false, - "children": [ - { - "name": "Users", - "path": "/nx-cloud/account/users", - "id": "users", - "isExternal": false, - "children": [], - "disableCollapsible": false - }, - { - "name": "Authenticate with Google Identity", - "path": "/nx-cloud/account/google-auth", - "id": "google-auth", - "isExternal": false, - "children": [], - "disableCollapsible": false - }, - { - "name": "Access Tokens", - "path": "/nx-cloud/account/access-tokens", - "id": "access-tokens", - "isExternal": false, - "children": [], - "disableCollapsible": false - }, - { - "name": "Security Scenarios", - "path": "/nx-cloud/account/scenarios", - "id": "scenarios", - "isExternal": false, - "children": [], - "disableCollapsible": false - }, - { - "name": "End to End Encryption", - "path": "/nx-cloud/account/encryption", - "id": "encryption", - "isExternal": false, - "children": [], - "disableCollapsible": false - } - ], - "disableCollapsible": false - }, - { - "name": "Users", - "path": "/nx-cloud/account/users", - "id": "users", - "isExternal": false, - "children": [], - "disableCollapsible": false - }, - { - "name": "Authenticate with Google Identity", - "path": "/nx-cloud/account/google-auth", - "id": "google-auth", - "isExternal": false, - "children": [], - "disableCollapsible": false - }, - { - "name": "Access Tokens", - "path": "/nx-cloud/account/access-tokens", - "id": "access-tokens", - "isExternal": false, - "children": [], - "disableCollapsible": false - }, - { - "name": "Security Scenarios", - "path": "/nx-cloud/account/scenarios", - "id": "scenarios", - "isExternal": false, - "children": [], - "disableCollapsible": false - }, - { - "name": "End to End Encryption", - "path": "/nx-cloud/account/encryption", - "id": "encryption", - "isExternal": false, - "children": [], - "disableCollapsible": false - }, { "name": "Reference", "path": "/nx-cloud/reference", @@ -6469,9 +6529,9 @@ "disableCollapsible": false }, { - "id": "webpack-dev-server", - "path": "/nx-api/angular/executors/webpack-dev-server", - "name": "webpack-dev-server", + "id": "dev-server", + "path": "/nx-api/angular/executors/dev-server", + "name": "dev-server", "children": [], "isExternal": false, "disableCollapsible": false diff --git a/docs/generated/manifests/nx-api.json b/docs/generated/manifests/nx-api.json index 8e9ee162ecc0cc..77d6ed47867758 100644 --- a/docs/generated/manifests/nx-api.json +++ b/docs/generated/manifests/nx-api.json @@ -76,13 +76,13 @@ "path": "/nx-api/angular/executors/webpack-browser", "type": "executor" }, - "/nx-api/angular/executors/webpack-dev-server": { - "description": "The `webpack-dev-server` executor is very similar to the standard `dev-server` builder provided by the Angular Devkit. It is usually used in tandem with `@nrwl/angular:webpack-browser` when your Angular application uses a custom webpack configuration.", - "file": "generated/packages/angular/executors/webpack-dev-server.json", + "/nx-api/angular/executors/dev-server": { + "description": "The `dev-server` executor is very similar to the standard `dev-server` builder provided by the Angular Devkit. It is usually used in tandem with `@nrwl/angular:webpack-browser` when your Angular application uses a custom webpack configuration.", + "file": "generated/packages/angular/executors/dev-server.json", "hidden": false, - "name": "webpack-dev-server", - "originalFilePath": "/packages/angular/src/builders/webpack-dev-server/schema.json", - "path": "/nx-api/angular/executors/webpack-dev-server", + "name": "dev-server", + "originalFilePath": "/packages/angular/src/builders/dev-server/schema.json", + "path": "/nx-api/angular/executors/dev-server", "type": "executor" }, "/nx-api/angular/executors/webpack-server": { diff --git a/docs/generated/manifests/nx.json b/docs/generated/manifests/nx.json index 29c7af28ba1198..913e2569092575 100644 --- a/docs/generated/manifests/nx.json +++ b/docs/generated/manifests/nx.json @@ -994,16 +994,6 @@ "path": "/concepts/types-of-configuration", "tags": [] }, - { - "id": "dte", - "name": "Improve Worst Case CI Times", - "description": "", - "file": "shared/concepts/improve-worst-case-ci-times", - "itemList": [], - "isExternal": false, - "path": "/concepts/dte", - "tags": ["distribute-task-execution"] - }, { "id": "task-pipeline-configuration", "name": "What is a Task Pipeline", @@ -1296,16 +1286,6 @@ "path": "/concepts/types-of-configuration", "tags": [] }, - "/concepts/dte": { - "id": "dte", - "name": "Improve Worst Case CI Times", - "description": "", - "file": "shared/concepts/improve-worst-case-ci-times", - "itemList": [], - "isExternal": false, - "path": "/concepts/dte", - "tags": ["distribute-task-execution"] - }, "/concepts/task-pipeline-configuration": { "id": "task-pipeline-configuration", "name": "What is a Task Pipeline", diff --git a/docs/generated/manifests/tags.json b/docs/generated/manifests/tags.json index 7c17d4b7bf7a17..50b392a13ecd46 100644 --- a/docs/generated/manifests/tags.json +++ b/docs/generated/manifests/tags.json @@ -584,50 +584,6 @@ "path": "/concepts/integrated-vs-package-based" } ], - "distribute-task-execution": [ - { - "description": "", - "file": "shared/concepts/improve-worst-case-ci-times", - "id": "dte", - "name": "Improve Worst Case CI Times", - "path": "/concepts/dte" - }, - { - "description": "", - "file": "shared/concepts/illustrated-dte-guide", - "id": "illustrated-dte", - "name": "Illustrated Distributed Task Execution", - "path": "/concepts/more-concepts/illustrated-dte" - }, - { - "description": "", - "file": "", - "id": "nx-cloud-documentation", - "name": "Nx Cloud Documentation", - "path": "/nx-cloud/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": "/nx-cloud/features/distribute-task-execution" - }, - { - "description": "", - "file": "shared/ci-overview", - "id": "ci-setup", - "name": "CI Setup", - "path": "/nx-cloud/recipes/set-up/ci-setup" - }, - { - "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/connect-to-nx-cloud", - "id": "connect-to-nx-cloud", - "name": "connect-to-nx-cloud", - "path": "/nx-api/nx/documents/connect-to-nx-cloud" - } - ], "repository-types": [ { "description": "", @@ -748,6 +704,50 @@ "path": "/recipes/react/module-federation-with-ssr" } ], + "distribute-task-execution": [ + { + "description": "", + "file": "shared/concepts/illustrated-dte-guide", + "id": "illustrated-dte", + "name": "Illustrated Distributed Task Execution", + "path": "/concepts/more-concepts/illustrated-dte" + }, + { + "description": "", + "file": "", + "id": "nx-cloud-documentation", + "name": "Nx Cloud Documentation", + "path": "/nx-cloud/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": "/nx-cloud/features/distribute-task-execution" + }, + { + "description": "", + "file": "shared/concepts/improve-worst-case-ci-times", + "id": "dte", + "name": "Improve Worst Case CI Times", + "path": "/nx-cloud/concepts/dte" + }, + { + "description": "Learn how to set up Nx Cloud for your workspace.", + "file": "", + "id": "set-up", + "name": "Set Up CI", + "path": "/nx-cloud/recipes/set-up" + }, + { + "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/connect-to-nx-cloud", + "id": "connect-to-nx-cloud", + "name": "connect-to-nx-cloud", + "path": "/nx-api/nx/documents/connect-to-nx-cloud" + } + ], "create-your-own-plugin": [ { "description": "", diff --git a/docs/generated/packages-metadata.json b/docs/generated/packages-metadata.json index c25f789beaae94..43a57fd00c1b7d 100644 --- a/docs/generated/packages-metadata.json +++ b/docs/generated/packages-metadata.json @@ -72,12 +72,12 @@ "type": "executor" }, { - "description": "The `webpack-dev-server` executor is very similar to the standard `dev-server` builder provided by the Angular Devkit. It is usually used in tandem with `@nrwl/angular:webpack-browser` when your Angular application uses a custom webpack configuration.", - "file": "generated/packages/angular/executors/webpack-dev-server.json", + "description": "The `dev-server` executor is very similar to the standard `dev-server` builder provided by the Angular Devkit. It is usually used in tandem with `@nrwl/angular:webpack-browser` when your Angular application uses a custom webpack configuration.", + "file": "generated/packages/angular/executors/dev-server.json", "hidden": false, - "name": "webpack-dev-server", - "originalFilePath": "/packages/angular/src/builders/webpack-dev-server/schema.json", - "path": "angular/executors/webpack-dev-server", + "name": "dev-server", + "originalFilePath": "/packages/angular/src/builders/dev-server/schema.json", + "path": "angular/executors/dev-server", "type": "executor" }, { diff --git a/docs/generated/packages/angular/documents/angular-nx-version-matrix.md b/docs/generated/packages/angular/documents/angular-nx-version-matrix.md index 569a1b7911d6fd..60215afd1d163f 100644 --- a/docs/generated/packages/angular/documents/angular-nx-version-matrix.md +++ b/docs/generated/packages/angular/documents/angular-nx-version-matrix.md @@ -12,22 +12,23 @@ Below is a reference table that matches versions of Angular to the version of Nx We provide a recommended version, and it is usually the latest minor version of Nx in the range provided because there will have been bug fixes added since the first release in the range. -| Angular Version | **Nx Version _(recommended)_** | Nx Version _(range)_ | -| --------------- | ------------------------------ | --------------------------------------- | -| ~16.2.0 | **latest** | 16.7.0 <= latest | -| ~16.1.0 | **latest** | 16.4.0 <= latest | -| ~16.0.0 | **latest** | 16.1.0 <= latest | -| ~15.2.0 | **latest** | 15.8.0 <= latest | -| ~15.1.0 | **latest** | 15.5.0 <= latest | -| ~15.0.0 | **latest** | 15.2.0 <= 15.4.8 \|\| 15.7.0 <= latest | -| ~14.2.0 | **latest** | 14.6.0 <= 15.1.1 \|\| 15.7.0 <= latest | -| ~14.1.0 | **latest** | 14.5.0 <= 14.5.10 \|\| 15.7.0 <= latest | -| ~14.0.0 | **latest** | 14.2.1 <= 14.4.3 \|\| 15.7.0 <= latest | -| ^13.0.0 | **14.1.9** | 13.2.0 <= 14.1.9 | -| ^12.0.0 | **13.1.4** | 12.3.0 <= 13.1.4 | -| ^11.0.0 | **12.2.0** | 11.0.0 <= 12.2.0 | -| ^10.0.0 | **10.4.15** | 9.7.0 <= 10.4.15 | -| ^9.0.0 | **9.6.0** | 8.12.4 <= 9.6.0 | -| ^8.0.0 | **8.12.2** | 8.7.0 <= 8.12.2 | +| Angular Version | **Nx Version _(recommended)_** | Nx Version _(range)_ | +| --------------- | ------------------------------ | -------------------------------------- | +| ~17.0.0 | **latest** | 17.1.0 <= latest | +| ~16.2.0 | **latest** | 16.7.0 <= latest | +| ~16.1.0 | **latest** | 16.4.0 <= latest | +| ~16.0.0 | **latest** | 16.1.0 <= latest | +| ~15.2.0 | **latest** | 15.8.0 <= latest | +| ~15.1.0 | **latest** | 15.5.0 <= latest | +| ~15.0.0 | **latest** | 15.2.0 <= 15.4.8 \|\| 15.7.0 <= latest | +| ~14.2.0 | **~17.0.0** | 14.6.0 <= 15.1.1 \|\| 15.7.0 < 17.1.0 | +| ~14.1.0 | **~17.0.0** | 14.5.0 <= 14.5.10 \|\| 15.7.0 < 17.1.0 | +| ~14.0.0 | **~17.0.0** | 14.2.1 <= 14.4.3 \|\| 15.7.0 < 17.1.0 | +| ^13.0.0 | **14.1.9** | 13.2.0 <= 14.1.9 | +| ^12.0.0 | **13.1.4** | 12.3.0 <= 13.1.4 | +| ^11.0.0 | **12.2.0** | 11.0.0 <= 12.2.0 | +| ^10.0.0 | **10.4.15** | 9.7.0 <= 10.4.15 | +| ^9.0.0 | **9.6.0** | 8.12.4 <= 9.6.0 | +| ^8.0.0 | **8.12.2** | 8.7.0 <= 8.12.2 | Additionally, you can check the supported versions of Node and Typescript for the version of Angular you are using in the [Angular docs](https://angular.io/guide/versions#actively-supported-versions). diff --git a/docs/generated/packages/angular/executors/webpack-dev-server.json b/docs/generated/packages/angular/executors/dev-server.json similarity index 81% rename from docs/generated/packages/angular/executors/webpack-dev-server.json rename to docs/generated/packages/angular/executors/dev-server.json index 4dff6e90b9d62f..8583a356e756f0 100644 --- a/docs/generated/packages/angular/executors/webpack-dev-server.json +++ b/docs/generated/packages/angular/executors/dev-server.json @@ -1,13 +1,13 @@ { - "name": "webpack-dev-server", - "implementation": "/packages/angular/src/builders/webpack-dev-server/webpack-dev-server.impl.ts", + "name": "dev-server", + "implementation": "/packages/angular/src/builders/dev-server/dev-server.impl.ts", "schema": { "version": 2, "outputCapture": "direct-nodejs", "$schema": "http://json-schema.org/draft-07/schema", "title": "Schema for Webpack Dev Server", - "description": "The webpack-dev-server executor is very similar to the standard dev server builder provided by the Angular Devkit. It is usually used in tandem with `@nx/angular:webpack-browser` when your Angular application uses a custom webpack configuration.", - "examplesFile": "##### Seving an application with a custom webpack configuration\n\nThis executor should be used along with `@nx/angular:webpack-browser` to serve an application using a custom webpack configuration.\n\nYour `project.json` file should contain a `build` and `serve` target that matches the following:\n\n```json\n\"build\": {\n \"executor\": \"@nx/angular:webpack-browser\",\n \"options\": {\n ...\n \"customWebpackConfig\": {\n \"path\": \"apps/appName/webpack.config.js\"\n }\n }\n},\n\"serve\": {\n \"executor\": \"@nx/angular:webpack-dev-server\",\n \"configurations\": {\n \"production\": {\n \"buildTarget\": \"appName:build:production\"\n },\n \"development\": {\n \"buildTarget\": \"appName:build:development\"\n }\n },\n \"defaultConfiguration\": \"development\",\n}\n```\n", + "description": "The dev-server executor is very similar to the standard dev server builder provided by the Angular Devkit. It is usually used in tandem with `@nx/angular:webpack-browser` when your Angular application uses a custom webpack configuration.", + "examplesFile": "##### Seving an application with a custom webpack configuration\n\nThis executor should be used along with `@nx/angular:webpack-browser` to serve an application using a custom webpack configuration.\n\nYour `project.json` file should contain a `build` and `serve` target that matches the following:\n\n```json\n\"build\": {\n \"executor\": \"@nx/angular:webpack-browser\",\n \"options\": {\n ...\n \"customWebpackConfig\": {\n \"path\": \"apps/appName/webpack.config.js\"\n }\n }\n},\n\"serve\": {\n \"executor\": \"@nx/angular:dev-server\",\n \"configurations\": {\n \"production\": {\n \"buildTarget\": \"appName:build:production\"\n },\n \"development\": {\n \"buildTarget\": \"appName:build:development\"\n }\n },\n \"defaultConfiguration\": \"development\",\n}\n```\n", "type": "object", "presets": [ { "name": "Using a Different Port", "keys": ["buildTarget", "port"] } @@ -117,9 +117,9 @@ { "required": ["browserTarget"] } ] }, - "description": "The `webpack-dev-server` executor is very similar to the standard `dev-server` builder provided by the Angular Devkit. It is usually used in tandem with `@nrwl/angular:webpack-browser` when your Angular application uses a custom webpack configuration.", + "description": "The `dev-server` executor is very similar to the standard `dev-server` builder provided by the Angular Devkit. It is usually used in tandem with `@nrwl/angular:webpack-browser` when your Angular application uses a custom webpack configuration.", "aliases": [], "hidden": false, - "path": "/packages/angular/src/builders/webpack-dev-server/schema.json", + "path": "/packages/angular/src/builders/dev-server/schema.json", "type": "executor" } diff --git a/docs/generated/packages/angular/executors/webpack-server.json b/docs/generated/packages/angular/executors/webpack-server.json index 9dc0d2f70ba63b..6456956baaef1e 100644 --- a/docs/generated/packages/angular/executors/webpack-server.json +++ b/docs/generated/packages/angular/executors/webpack-server.json @@ -6,7 +6,7 @@ "outputCapture": "direct-nodejs", "$schema": "http://json-schema.org/draft-07/schema", "title": "Schema for Webpack Server", - "description": "The webpack-dev-server executor is very similar to the standard server builder provided by the Angular Devkit. It is usually used in tandem with `@nx/angular:webpack-browser` when your Angular application uses a custom webpack configuration and NgUniversal for SSR.", + "description": "The webpack-server executor is very similar to the standard server builder provided by the Angular Devkit. It is usually used in tandem with `@nx/angular:webpack-browser` when your Angular application uses a custom webpack configuration and NgUniversal for SSR.", "type": "object", "properties": { "assets": { diff --git a/docs/generated/packages/angular/generators/setup-mf.json b/docs/generated/packages/angular/generators/setup-mf.json index 196986cf8a4ea5..9d43cafe2692c8 100644 --- a/docs/generated/packages/angular/generators/setup-mf.json +++ b/docs/generated/packages/angular/generators/setup-mf.json @@ -78,6 +78,11 @@ "type": "boolean", "description": "Whether the module federation configuration and webpack configuration files should use TS.", "default": true + }, + "setParserOptionsProject": { + "type": "boolean", + "description": "Whether or not to configure the ESLint `parserOptions.project` option. We do not do this by default for lint performance reasons.", + "default": false } }, "required": ["appName", "mfType"], diff --git a/docs/generated/packages/devkit/documents/nx_devkit.md b/docs/generated/packages/devkit/documents/nx_devkit.md index 6661d52e35a412..889a8fe0332c7f 100644 --- a/docs/generated/packages/devkit/documents/nx_devkit.md +++ b/docs/generated/packages/devkit/documents/nx_devkit.md @@ -25,6 +25,7 @@ It only uses language primitives and immutable objects - [CreateDependenciesContext](../../devkit/documents/CreateDependenciesContext) - [CreateNodesContext](../../devkit/documents/CreateNodesContext) +- [CreateNodesResult](../../devkit/documents/CreateNodesResult) - [DefaultTasksRunnerOptions](../../devkit/documents/DefaultTasksRunnerOptions) - [ExecutorContext](../../devkit/documents/ExecutorContext) - [ExecutorsJson](../../devkit/documents/ExecutorsJson) diff --git a/docs/generated/packages/eslint/executors/lint.json b/docs/generated/packages/eslint/executors/lint.json index 4a308613d4f5e6..5dcc10ad9bba35 100644 --- a/docs/generated/packages/eslint/executors/lint.json +++ b/docs/generated/packages/eslint/executors/lint.json @@ -20,7 +20,7 @@ "lintFilePatterns": { "type": "array", "description": "One or more files/dirs/globs to pass directly to ESLint's `lintFiles()` method.", - "default": [], + "default": ["{projectRoot}"], "items": { "type": "string" } }, "format": { @@ -140,7 +140,6 @@ "default": true } }, - "required": ["lintFilePatterns"], "examplesFile": "Linter can be configured in multiple ways. The basic way is to provide only `lintFilePatterns`, which is a mandatory property. This tells us where to look for files to lint.\n\n`project.json`:\n\n```json\n\"lint\": {\n \"executor\": \"@nx/eslint:lint\",\n \"options\": {\n \"lintFilePatterns\": [\"apps/frontend/**/*.ts\"]\n }\n}\n```\n\n## Examples\n\n{% tabs %}\n{% tab label=\"Fixing linter issues\" %}\n\nLinter provides an automated way of fixing known issues. To ensure that those changes are properly cached, we need to add an `outputs` property to the `lint` target. Omitting the `outputs` property would produce an invalid cache record. Both of these properties are set by default when scaffolding a new project.\n\n```json\n\"lint\": {\n \"executor\": \"@nx/eslint:lint\",\n \"outputs\": [\"{options.outputFile}\"],\n \"options\": {\n \"lintFilePatterns\": [\"apps/frontend/**/*.ts\"]\n }\n}\n```\n\nWith these settings, we can run the command with a `--fix` flag:\n\n```bash\nnx run frontend:lint --fix\n```\n\nWe can also set this flag via project configuration to always fix files when running lint:\n\n```json\n\"lint\": {\n \"executor\": \"@nx/eslint:lint\",\n \"outputs\": [\"{options.outputFile}\"],\n \"options\": {\n \"lintFilePatterns\": [\"apps/frontend/**/*.ts\"],\n \"fix\": true\n }\n}\n```\n\n{% /tab %}\n{% tab label=\"Custom output format\" %}\n\nESLint executor uses the `stylish` output format by default. You can change this by specifying the `format` property:\n\n```json\n\"lint\": {\n \"executor\": \"@nx/eslint:lint\",\n \"outputs\": [\"{options.outputFile}\"],\n \"options\": {\n \"lintFilePatterns\": [\"apps/frontend/**/*.ts\"],\n \"format\": \"compact\"\n }\n}\n```\n\n{% /tab %}\n{% tab label=\"Silence warnings\" %}\n\nMigrated or legacy projects tend to have an overwhelming amount of lint errors. We might want to change those temporarily to be warnings so they don't block the development. But they would still clutter the report. We can run the command with `--quiet` to hide warning (errors would still break the lint):\n\n```bash\nnx run frontend:lint --quiet\n```\n\nWe can also set this via project configuration as a default option.\n\n```json\n\"lint\": {\n \"executor\": \"@nx/eslint:lint\",\n \"outputs\": [\"{options.outputFile}\"],\n \"options\": {\n \"lintFilePatterns\": [\"apps/frontend/**/*.ts\"],\n \"quiet\": true\n }\n}\n```\n\n{% /tab %}\n{% tab label=\"Flat Config file\" %}\n\n`ESLint` provides several ways of specifying the configuration. The default one is using `.eslintrc.json` but you can override it by setting the `eslintConfig` flag. The new `Flat Config` is now also supported:\n\n```json\n\"lint\": {\n \"executor\": \"@nx/eslint:lint\",\n \"outputs\": [\"{options.outputFile}\"],\n \"options\": {\n \"lintFilePatterns\": [\"apps/frontend/**/*.ts\"],\n \"eslintConfig\": \"eslint.config.js\"\n }\n}\n```\n\n**Note:** In contrast to other configuration formats, the `Flat Config` requires that all configuration files are converted to `eslint.config.js`. Built-in migrations and generators support only `.eslintrc.json` at the moment.\n\n{% /tab %}\n{% /tabs %}\n\n---\n", "presets": [] }, diff --git a/docs/generated/packages/nx/documents/release.md b/docs/generated/packages/nx/documents/release.md index e0b7d91e763026..f1f3cd6c88aa3d 100644 --- a/docs/generated/packages/nx/documents/release.md +++ b/docs/generated/packages/nx/documents/release.md @@ -67,6 +67,42 @@ nx release version [specifier] #### Options +##### git-commit + +Type: `boolean` + +Whether or not to automatically commit the changes made by this command + +##### git-commit-args + +Type: `string` + +Additional arguments (added after the --message argument, which may or may not be customized with --git-commit-message) to pass to the `git commit` command invoked behind the scenes + +##### git-commit-message + +Type: `string` + +Custom git commit message to use when committing the changes made by this command. {version} will be dynamically interpolated when performing fixed releases, interpolated tags will be appended to the commit body when performing independent releases. + +##### git-tag + +Type: `boolean` + +Whether or not to automatically tag the changes made by this command + +##### git-tag-args + +Type: `string` + +Additional arguments to pass to the `git tag` command invoked behind the scenes + +##### git-tag-message + +Type: `string` + +Custom git tag message to use when tagging the changes made by this command. This defaults to be the same value as the tag itself. + ##### help Type: `boolean` @@ -85,6 +121,14 @@ Type: `string` Exact version or semver keyword to apply to the selected release group. +##### stageChanges + +Type: `boolean` + +Default: `false` + +Whether or not to stage the changes made by this command, irrespective of the git config in nx.json related to automated commits. Useful when combining this command with changelog generation. + ##### version Type: `boolean` @@ -107,6 +151,42 @@ Type: `string` The git reference to use as the start of the changelog. If not set it will attempt to resolve the latest tag and use that +##### git-commit + +Type: `boolean` + +Whether or not to automatically commit the changes made by this command + +##### git-commit-args + +Type: `string` + +Additional arguments (added after the --message argument, which may or may not be customized with --git-commit-message) to pass to the `git commit` command invoked behind the scenes + +##### git-commit-message + +Type: `string` + +Custom git commit message to use when committing the changes made by this command. {version} will be dynamically interpolated when performing fixed releases, interpolated tags will be appended to the commit body when performing independent releases. + +##### git-tag + +Type: `boolean` + +Whether or not to automatically tag the changes made by this command + +##### git-tag-args + +Type: `string` + +Additional arguments to pass to the `git tag` command invoked behind the scenes + +##### git-tag-message + +Type: `string` + +Custom git tag message to use when tagging the changes made by this command. This defaults to be the same value as the tag itself. + ##### gitRemote Type: `string` @@ -129,14 +209,6 @@ Choices: [all, workspace, projects] Interactively modify changelog markdown contents in your code editor before applying the changes. You can set it to be interactive for all changelogs, or only the workspace level, or only the project level -##### tagVersionPrefix - -Type: `string` - -Default: `v` - -Prefix to apply to the version when creating the Github release tag - ##### to Type: `string` @@ -203,6 +275,12 @@ Default: `false` Ignore cycles in the task graph +##### otp + +Type: `number` + +A one-time password for publishing to a registry that requires 2FA + ##### output-style Type: `string` diff --git a/docs/generated/packages/nx/executors/noop.json b/docs/generated/packages/nx/executors/noop.json index a4eb444a3f231c..767dddbcf91468 100644 --- a/docs/generated/packages/nx/executors/noop.json +++ b/docs/generated/packages/nx/executors/noop.json @@ -9,7 +9,7 @@ "cli": "nx", "outputCapture": "pipe", "properties": {}, - "additionalProperties": false, + "additionalProperties": true, "presets": [] }, "description": "An executor that does nothing", diff --git a/docs/generated/packages/nx/executors/run-commands.json b/docs/generated/packages/nx/executors/run-commands.json index 4e098d3c26fb02..3caacce04bd87d 100644 --- a/docs/generated/packages/nx/executors/run-commands.json +++ b/docs/generated/packages/nx/executors/run-commands.json @@ -119,6 +119,11 @@ "type": "string", "description": "Current working directory of the commands. If it's not specified the commands will run in the workspace root, if a relative path is specified the commands will run in that path relative to the workspace root and if it's an absolute path the commands will run in that path." }, + "env": { + "type": "object", + "description": "Environment variables that will be made available to the commands. This property has priority over the `.env` files.", + "additionalProperties": { "type": "string" } + }, "__unparsed__": { "hidden": true, "type": "array", diff --git a/docs/generated/packages/react/generators/host.json b/docs/generated/packages/react/generators/host.json index f8b5541d829a53..a64997288735c4 100644 --- a/docs/generated/packages/react/generators/host.json +++ b/docs/generated/packages/react/generators/host.json @@ -68,6 +68,11 @@ "enum": ["eslint"], "default": "eslint" }, + "dynamic": { + "type": "boolean", + "description": "Should the host application use dynamic federation?", + "default": false + }, "skipFormat": { "description": "Skip formatting files.", "type": "boolean", diff --git a/docs/generated/packages/react/generators/remote.json b/docs/generated/packages/react/generators/remote.json index dd82c7410274b0..4852b0af516cf5 100644 --- a/docs/generated/packages/react/generators/remote.json +++ b/docs/generated/packages/react/generators/remote.json @@ -28,6 +28,12 @@ "type": "string", "enum": ["as-provided", "derived"] }, + "dynamic": { + "type": "boolean", + "description": "Should the host application use dynamic federation?", + "default": false, + "x-priority": "internal" + }, "style": { "description": "The file extension to be used for style files.", "type": "string", diff --git a/docs/generated/packages/vite/documents/overview.md b/docs/generated/packages/vite/documents/overview.md index 5d1ae8f9548a1b..035fc88681f544 100644 --- a/docs/generated/packages/vite/documents/overview.md +++ b/docs/generated/packages/vite/documents/overview.md @@ -18,15 +18,7 @@ Read more about Vite and Vitest in the [Vite documentation](https://vitejs.dev/) ## Setting up a new Nx workspace with Vite -You can create a new workspace that uses Vite with one of the following commands: - -- Generate a new monorepo with a Web Components app set up with Vite - -```shell -npx create-nx-workspace@latest --preset=web-components -``` - -- Generate a new standalone React app set up with Vite +Here's an example on how to create a new React app with Vite ```shell npx create-nx-workspace@latest --preset=react-standalone --bundler=vite @@ -64,7 +56,7 @@ You can use the `@nx/vite:configuration` generator to change your React or Web p You can read more about this generator on the [`@nx/vite:configuration`](/nx-api/vite/generators/configuration) generator page. -### Initialize Vite.js +### 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. @@ -100,7 +92,7 @@ pnpm install -D @nx/vite #### Ask Nx to install the necessary dependencies -After you install the plugin, you can initialize Vite.js. You can do this by running the `init` executor. This executor will make sure to install all 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 diff --git a/docs/generated/packages/vite/executors/build.json b/docs/generated/packages/vite/executors/build.json index cd55464e5841c6..76f1b2f215374b 100644 --- a/docs/generated/packages/vite/executors/build.json +++ b/docs/generated/packages/vite/executors/build.json @@ -26,11 +26,6 @@ "description": "Skip type-checking via TypeScript. Skipping type-checking speeds up the build but type errors are not caught.", "default": false }, - "base": { - "type": "string", - "description": "Base public path when served in development or production.", - "alias": "baseHref" - }, "configFile": { "type": "string", "description": "The name of the Vite.js configuration file.", @@ -59,49 +54,6 @@ }, "default": [] }, - "emptyOutDir": { - "description": "When set to false, outputPath will not be emptied during the build process.", - "type": "boolean", - "default": true - }, - "sourcemap": { - "description": "Output sourcemaps. Use 'hidden' for use with error reporting tools without generating sourcemap comment.", - "oneOf": [{ "type": "boolean" }, { "type": "string" }] - }, - "target": { - "description": "Browser compatibility target for the final bundle. For more info: https://vitejs.dev/config/build-options.html#build-target", - "type": "string" - }, - "minify": { - "description": "Output sourcemaps. Use 'hidden' for use with error reporting tools without generating sourcemap comment.", - "oneOf": [{ "type": "boolean" }, { "type": "string" }] - }, - "manifest": { - "description": "Output sourcemaps. Use 'hidden' for use with error reporting tools without generating sourcemap comment.", - "oneOf": [{ "type": "boolean" }, { "type": "string" }] - }, - "ssrManifest": { - "description": "When set to true, the build will also generate an SSR manifest for determining style links and asset preload directives in production. When the value is a string, it will be used as the manifest file name.", - "oneOf": [{ "type": "boolean" }, { "type": "string" }] - }, - "ssr": { - "description": "Produce SSR-oriented build. The value can be a string to directly specify the SSR entry, or true, which requires specifying the SSR entry via rollupOptions.input.", - "oneOf": [{ "type": "boolean" }, { "type": "string" }] - }, - "logLevel": { - "type": "string", - "description": "Adjust console output verbosity.", - "enum": ["info", "warn", "error", "silent"] - }, - "mode": { "type": "string", "description": "Mode to run the build in." }, - "force": { - "description": "Force the optimizer to ignore the cache and re-bundle", - "type": "boolean" - }, - "cssCodeSplit": { - "description": "Enable/disable CSS code splitting. When enabled, CSS imported in async chunks will be inlined into the async chunk itself and inserted when the chunk is loaded.", - "type": "boolean" - }, "watch": { "description": "Enable re-building when files change.", "oneOf": [{ "type": "boolean" }, { "type": "object" }], diff --git a/docs/generated/packages/vite/executors/dev-server.json b/docs/generated/packages/vite/executors/dev-server.json index 9c25f72d7e9af9..7cba326d7d13b7 100644 --- a/docs/generated/packages/vite/executors/dev-server.json +++ b/docs/generated/packages/vite/executors/dev-server.json @@ -27,45 +27,6 @@ "type": "string", "description": "Path to the proxy configuration file.", "x-completion-type": "file" - }, - "port": { - "type": "number", - "description": "Port to listen on.", - "x-priority": "important" - }, - "host": { - "description": "Specify which IP addresses the server should listen on.", - "oneOf": [{ "type": "boolean" }, { "type": "string" }] - }, - "https": { - "oneOf": [{ "type": "boolean" }, { "type": "object" }], - "description": "Serve using HTTPS. https://vitejs.dev/config/server-options.html#server-https" - }, - "hmr": { - "description": "Enable hot module replacement. For more options, use the 'hmr' option in the Vite configuration file.", - "type": "boolean" - }, - "open": { - "description": "Automatically open the app in the browser on server start. When the value is a string, it will be used as the URL's pathname.", - "oneOf": [{ "type": "boolean" }, { "type": "string" }] - }, - "cors": { - "description": "Configure CORS for the dev server.", - "type": "boolean" - }, - "logLevel": { - "type": "string", - "description": "Adjust console output verbosity.", - "enum": ["info", "warn", "error", "silent"] - }, - "mode": { "type": "string", "description": "Mode to run the server in." }, - "clearScreen": { - "description": "Set to false to prevent Vite from clearing the terminal screen when logging certain messages.", - "type": "boolean" - }, - "force": { - "description": "Force the optimizer to ignore the cache and re-bundle", - "type": "boolean" } }, "definitions": {}, diff --git a/docs/generated/packages/vite/executors/preview-server.json b/docs/generated/packages/vite/executors/preview-server.json index 00eb6fcbd30be1..e2081c0e4539e8 100644 --- a/docs/generated/packages/vite/executors/preview-server.json +++ b/docs/generated/packages/vite/executors/preview-server.json @@ -22,29 +22,6 @@ "description": "Path to the proxy configuration file.", "x-completion-type": "file" }, - "port": { "type": "number", "description": "Port to listen on." }, - "host": { - "description": "Specify which IP addresses the server should listen on.", - "oneOf": [{ "type": "boolean" }, { "type": "string" }] - }, - "https": { - "oneOf": [{ "type": "boolean" }, { "type": "object" }], - "description": "Serve using HTTPS. https://vitejs.dev/config/server-options.html#server-https" - }, - "open": { - "description": "Automatically open the app in the browser on server start. When the value is a string, it will be used as the URL's pathname.", - "oneOf": [{ "type": "boolean" }, { "type": "string" }] - }, - "logLevel": { - "type": "string", - "description": "Adjust console output verbosity.", - "enum": ["info", "warn", "error", "silent"] - }, - "mode": { "type": "string", "description": "Mode to run the server in." }, - "clearScreen": { - "description": "Set to false to prevent Vite from clearing the terminal screen when logging certain messages.", - "type": "boolean" - }, "staticFilePath": { "type": "string", "description": "Path where the build artifacts are located. If not provided then it will be infered from the buildTarget executor options as outputPath", diff --git a/docs/generated/packages/vite/executors/test.json b/docs/generated/packages/vite/executors/test.json index 4f71b6bb7a1554..86c15857007046 100644 --- a/docs/generated/packages/vite/executors/test.json +++ b/docs/generated/packages/vite/executors/test.json @@ -9,50 +9,12 @@ "description": "Test using Vitest.", "type": "object", "properties": { - "config": { + "configFile": { "type": "string", "description": "The path to the local vitest config", "x-completion-type": "file", - "x-completion-glob": "@(vitest|vite).config@(.js|.ts)" - }, - "passWithNoTests": { - "type": "boolean", - "default": true, - "description": "Pass the test even if no tests are found" - }, - "testNamePattern": { - "type": "string", - "description": "Run tests with full names matching the pattern" - }, - "mode": { - "type": "string", - "enum": ["test", "benchmark", "typecheck"], - "default": "test", - "description": "The mode that vitest will run on", - "x-priority": "important" - }, - "watch": { - "type": "boolean", - "default": false, - "description": "Enable watch mode" - }, - "reporters": { - "type": "array", - "items": { "type": "string" }, - "description": "An array of reporters to pass to vitest" - }, - "update": { - "type": "boolean", - "default": false, - "alias": "u", - "description": "Update snapshots", - "x-priority": "important" - }, - "coverage": { - "type": "boolean", - "default": false, - "description": "Enable coverage report", - "x-priority": "important" + "x-completion-glob": "@(vitest|vite).config@(.js|.ts)", + "aliases": ["config"] }, "reportsDirectory": { "type": "string", @@ -62,6 +24,10 @@ "aliases": ["testFile"], "type": "array", "items": { "type": "string" } + }, + "watch": { + "description": "Watch files for changes and rerun tests related to changed files.", + "type": "boolean" } }, "required": [], diff --git a/docs/generated/packages/webpack/executors/webpack.json b/docs/generated/packages/webpack/executors/webpack.json index 7b5b12add6c9f5..9f5587e366fdee 100644 --- a/docs/generated/packages/webpack/executors/webpack.json +++ b/docs/generated/packages/webpack/executors/webpack.json @@ -30,8 +30,7 @@ "compiler": { "type": "string", "description": "The compiler to use.", - "enum": ["babel", "swc", "tsc"], - "default": "babel" + "enum": ["babel", "swc", "tsc"] }, "outputPath": { "type": "string", @@ -43,8 +42,7 @@ "type": "string", "alias": "platform", "description": "Target platform for the build, same as the Webpack target option.", - "enum": ["node", "web", "webworker"], - "default": "web" + "enum": ["node", "web", "webworker"] }, "deleteOutputPath": { "type": "boolean", @@ -53,8 +51,7 @@ }, "watch": { "type": "boolean", - "description": "Enable re-building when files change.", - "default": false + "description": "Enable re-building when files change." }, "baseHref": { "type": "string", @@ -66,33 +63,27 @@ }, "vendorChunk": { "type": "boolean", - "description": "Use a separate bundle containing only vendor libraries.", - "default": true + "description": "Use a separate bundle containing only vendor libraries." }, "commonChunk": { "type": "boolean", - "description": "Use a separate bundle containing code used across multiple bundles.", - "default": true + "description": "Use a separate bundle containing code used across multiple bundles." }, "runtimeChunk": { "type": "boolean", - "description": "Use a separate bundle containing the runtime.", - "default": true + "description": "Use a separate bundle containing the runtime." }, "sourceMap": { "description": "Output sourcemaps. Use 'hidden' for use with error reporting tools without generating sourcemap comment.", - "default": true, "oneOf": [{ "type": "boolean" }, { "type": "string" }] }, "progress": { "type": "boolean", - "description": "Log progress to the console while building.", - "default": false + "description": "Log progress to the console while building." }, "assets": { "type": "array", "description": "List of static application assets.", - "default": [], "items": { "oneOf": [ { @@ -163,8 +154,7 @@ "x-completion-glob": "**/*@(.css|.scss|.less|.sass|.styl|.stylus)" } ] - }, - "default": [] + } }, "styles": { "type": "array", @@ -200,18 +190,15 @@ "x-completion-glob": "**/*@(.css|.scss|.less|.sass|.styl|.stylus)" } ] - }, - "default": [] + } }, "namedChunks": { "type": "boolean", - "description": "Names the produced bundles according to their entry file.", - "default": true + "description": "Names the produced bundles according to their entry file." }, "outputHashing": { "type": "string", "description": "Define the output filename cache-busting hashing mode.", - "default": "none", "enum": ["none", "all", "media", "bundles"] }, "stylePreprocessorOptions": { @@ -221,8 +208,7 @@ "includePaths": { "description": "Paths to include. Paths will be resolved to project root.", "type": "array", - "items": { "type": "string" }, - "default": [] + "items": { "type": "string" } } }, "additionalProperties": false @@ -251,13 +237,11 @@ }, "generatePackageJson": { "type": "boolean", - "description": "Generates a `package.json` and pruned lock file with the project's `node_module` dependencies populated for installing in a container. If a `package.json` exists in the project's directory, it will be reused with dependencies populated.", - "default": false + "description": "Generates a `package.json` and pruned lock file with the project's `node_module` dependencies populated for installing in a container. If a `package.json` exists in the project's directory, it will be reused with dependencies populated." }, "transformers": { "type": "array", "description": "List of TypeScript Compiler Transfomers Plugins.", - "default": [], "aliases": ["tsPlugins"], "items": { "oneOf": [ @@ -302,18 +286,15 @@ { "type": "string", "enum": ["none", "all"] }, { "type": "array", "items": { "type": "string" } } ], - "description": "Dependencies to keep external to the bundle. (`all` (default), `none`, or an array of module names)", - "default": "all" + "description": "Dependencies to keep external to the bundle. (`all` (default), `none`, or an array of module names)" }, "extractCss": { "type": "boolean", - "description": "Extract CSS into a `.css` file.", - "default": true + "description": "Extract CSS into a `.css` file." }, "subresourceIntegrity": { "type": "boolean", - "description": "Enables the use of subresource integrity validation.", - "default": false + "description": "Enables the use of subresource integrity validation." }, "polyfills": { "type": "string", @@ -321,30 +302,24 @@ "x-completion-type": "file", "x-completion-glob": "**/*@(.js|.ts|.tsx)" }, - "verbose": { - "type": "boolean", - "description": "Emits verbose output", - "default": false - }, + "verbose": { "type": "boolean", "description": "Emits verbose output" }, "statsJson": { "type": "boolean", - "description": "Generates a 'stats.json' file which can be analyzed using tools such as: 'webpack-bundle-analyzer' or ``.", - "default": false + "description": "Generates a 'stats.json' file which can be analyzed using tools such as: 'webpack-bundle-analyzer' or ``." }, "isolatedConfig": { "type": "boolean", "description": "Do not apply Nx webpack plugins automatically. Plugins need to be applied in the project's webpack.config.js file (e.g. withNx, withReact, etc.).", - "default": false + "default": true, + "x-deprecated": "Automatic configuration of Webpack is deprecated in favor of an explicit 'webpack.config.js' file. This option will be removed in Nx 18. See https://nx.dev/recipes/webpack/webpack-config-setup." }, "extractLicenses": { "type": "boolean", - "description": "Extract all licenses in a separate file, in the case of production builds only.", - "default": false + "description": "Extract all licenses in a separate file, in the case of production builds only." }, "memoryLimit": { "type": "number", - "description": "Memory limit for type checking service process in `MB`.", - "default": 2048 + "description": "Memory limit for type checking service process in `MB`." }, "fileReplacements": { "description": "Replace files with other files in the build.", @@ -365,18 +340,16 @@ }, "additionalProperties": false, "required": ["replace", "with"] - }, - "default": [] + } }, "buildLibsFromSource": { "type": "boolean", - "description": "Read buildable libraries from source instead of building them separately.", + "description": "Read buildable libraries from source instead of building them separately. If set to `false`, the `tsConfig` option must also be set to remap paths.", "default": true }, "generateIndexHtml": { "type": "boolean", - "description": "Generates `index.html` file to the output path. This can be turned off if using a webpack plugin to generate HTML such as `html-webpack-plugin`.", - "default": true + "description": "Generates `index.html` file to the output path. This can be turned off if using a webpack plugin to generate HTML such as `html-webpack-plugin`." }, "postcssConfig": { "type": "string", @@ -391,8 +364,7 @@ }, "babelUpwardRootMode": { "type": "boolean", - "description": "Whether to set rootmode to upward. See https://babeljs.io/docs/en/options#rootmode", - "default": false + "description": "Whether to set rootmode to upward. See https://babeljs.io/docs/en/options#rootmode" }, "babelConfig": { "type": "string", @@ -400,7 +372,7 @@ "x-completion-type": "file" } }, - "required": ["tsConfig", "main"], + "required": [], "definitions": { "assetPattern": { "oneOf": [ diff --git a/docs/map.json b/docs/map.json index f8fae144fc11e8..34c4b8c81f8b88 100644 --- a/docs/map.json +++ b/docs/map.json @@ -288,12 +288,6 @@ "id": "types-of-configuration", "file": "shared/concepts/types-of-configuration" }, - { - "name": "Improve Worst Case CI Times", - "tags": ["distribute-task-execution"], - "id": "dte", - "file": "shared/concepts/improve-worst-case-ci-times" - }, { "name": "What is a Task Pipeline", "tags": ["run-tasks", "use-task-executors"], @@ -1645,9 +1639,21 @@ "file": "nx-cloud/intro/ci-with-nx" }, { - "name": "Nx Cloud Workflows", - "id": "nx-cloud-workflows", - "file": "nx-cloud/intro/nx-cloud-workflows" + "name": "Tutorials", + "id": "tutorials", + "description": "Tutorials setting up CI with Nx", + "itemList": [ + { + "name": "Circle CI with Nx", + "id": "circle", + "file": "nx-cloud/tutorial/circle" + }, + { + "name": "GitHub Actions with Nx", + "id": "github-actions", + "file": "nx-cloud/tutorial/github-actions" + } + ] } ] }, @@ -1682,6 +1688,34 @@ "id": "on-premise", "tags": ["on-premise"], "file": "nx-cloud/private/get-started" + }, + { + "name": "Nx Cloud Workflows", + "id": "nx-cloud-workflows", + "file": "nx-cloud/intro/nx-cloud-workflows" + } + ] + }, + { + "name": "Concepts", + "id": "concepts", + "description": "Learn how to manage Nx Cloud subscriptions and other options.", + "itemList": [ + { + "name": "Improve Worst Case CI Times", + "tags": ["distribute-task-execution"], + "id": "dte", + "file": "shared/concepts/improve-worst-case-ci-times" + }, + { + "name": "Security Scenarios", + "id": "scenarios", + "file": "nx-cloud/concepts/scenarios" + }, + { + "name": "End to End Encryption", + "id": "encryption", + "file": "nx-cloud/concepts/encryption" } ] }, @@ -1694,13 +1728,8 @@ "name": "Set Up CI", "id": "set-up", "description": "Learn how to set up Nx Cloud for your workspace.", + "tags": ["distribute-task-execution"], "itemList": [ - { - "name": "CI Setup", - "id": "ci-setup", - "tags": ["distribute-task-execution"], - "file": "shared/ci-overview" - }, { "name": "Setting up Azure Pipelines", "id": "monorepo-ci-azure", @@ -1733,6 +1762,23 @@ } ] }, + { + "name": "Security", + "id": "security", + "description": "Manage access to Nx Cloud", + "itemList": [ + { + "name": "Authenticate with Google Identity", + "id": "google-auth", + "file": "nx-cloud/recipes/google-auth" + }, + { + "name": "Access Tokens", + "id": "access-tokens", + "file": "nx-cloud/recipes/access-tokens" + } + ] + }, { "name": "Source Control Integration", "id": "source-control-integration", @@ -1822,38 +1868,6 @@ } ] }, - { - "name": "Account Management", - "id": "account", - "description": "Learn how to manage Nx Cloud subscriptions and other options.", - "itemList": [ - { - "name": "Users", - "id": "users", - "file": "nx-cloud/account/users" - }, - { - "name": "Authenticate with Google Identity", - "id": "google-auth", - "file": "nx-cloud/account/google-auth" - }, - { - "name": "Access Tokens", - "id": "access-tokens", - "file": "nx-cloud/account/access-tokens" - }, - { - "name": "Security Scenarios", - "id": "scenarios", - "file": "nx-cloud/account/scenarios" - }, - { - "name": "End to End Encryption", - "id": "encryption", - "file": "nx-cloud/account/encryption" - } - ] - }, { "name": "Reference", "id": "reference", diff --git a/docs/nx-cloud/account/users.md b/docs/nx-cloud/account/users.md deleted file mode 100644 index 1987e9a5df40ca..00000000000000 --- a/docs/nx-cloud/account/users.md +++ /dev/null @@ -1,16 +0,0 @@ -# User Management - -## Managing Members - -You can use Nx Cloud organizations to manage permissions. - -When you create a new organization, you are its only member and admin. You can invite other users using their emails, or using an email domain, in which case everyone under the same domain can join the organization. You can also make sure that members have to log in using their external identity provider (e.g., Google). In this case, if a member loses access to their Google account they will automatically lose the ability to access Nx Cloud. - -You can set one of the two roles for everyone you invited: - -- Admin (can view runs and stats, edit organization/workspace, modify billing, invite other users, etc.) -- Member (can view runs and stats, but cannot make any changes to any of the workspaces) - -## Public Organizations - -Sometimes you don't have a known list of members (for instance, for an open-source project). In this case you can change the organization's type to "public". In a public organization, everyone (including those without an Nx Cloud account) can see and do everything an organization member can see and do. diff --git a/docs/nx-cloud/account/encryption.md b/docs/nx-cloud/concepts/encryption.md similarity index 100% rename from docs/nx-cloud/account/encryption.md rename to docs/nx-cloud/concepts/encryption.md diff --git a/docs/nx-cloud/account/scenarios.md b/docs/nx-cloud/concepts/scenarios.md similarity index 90% rename from docs/nx-cloud/account/scenarios.md rename to docs/nx-cloud/concepts/scenarios.md index 7e2856f0e9c4d5..19ae9848250382 100644 --- a/docs/nx-cloud/account/scenarios.md +++ b/docs/nx-cloud/concepts/scenarios.md @@ -1,5 +1,9 @@ # Security Scenarios +{% callout type="warning" title="Use Caution With Read-Write Tokens" %} +Read-write tokens allow full write access to your remote cache. They should only be used in trusted environments. For instance, open source projects should only use read-write tokens as secrets configured for protected branches (e.g, main). Read-only tokens should be used in all other cases. +{% /callout %} + The following are the three commonly used setups. ## Setup 1: Only main branch has a read-write access token diff --git a/docs/nx-cloud/private/auth-single-admin.md b/docs/nx-cloud/private/auth-single-admin.md index 2324a8732b78a3..97abed502bd39b 100644 --- a/docs/nx-cloud/private/auth-single-admin.md +++ b/docs/nx-cloud/private/auth-single-admin.md @@ -10,14 +10,14 @@ a [video walkthrough of this](https://youtu.be/GT7XIwG1i5A?t=409). By default, when you connect your token to a workspace on your Nx Cloud web app, all links and runs are private to only members of your organisation. This means that you'll either need to explicitly add members, or make your organisation public (which means anyone with access to your Nx Cloud instance will be able to see your runs) -. [More details here.](/nx-cloud/account/users#managing-members) +. ## Setting up a single admin user If you just want to try out running Nx Cloud on prem and set up full membership management later, then the simplest option is to just set up a single admin user. This option might also work for you if you are okay -with [making your organisation public](/nx-cloud/account/users#public-organizations) to anyone that has access to your +with making your organisation public to anyone that has access to your Nx Cloud installation. To do that provision the `ADMIN_PASSWORD` env variable for the `nx-cloud-aggregator` container (if you are running Nx diff --git a/docs/nx-cloud/account/access-tokens.md b/docs/nx-cloud/recipes/access-tokens.md similarity index 85% rename from docs/nx-cloud/account/access-tokens.md rename to docs/nx-cloud/recipes/access-tokens.md index 57fc2a5f3d76e1..f0982a457b2604 100644 --- a/docs/nx-cloud/account/access-tokens.md +++ b/docs/nx-cloud/recipes/access-tokens.md @@ -4,6 +4,10 @@ The permissions and membership define what developers can access on nx.app. They ## Types of Access Tokens +{% callout type="warning" title="Use Caution With Read-Write Tokens" %} +Read-write tokens allow full write access to your remote cache. They should only be used in trusted environments. For instance, open source projects should only use read-write tokens as secrets configured for protected branches (e.g, main). Read-only tokens should be used in all other cases. +{% /callout %} + There are currently two (2) types of Access Tokens for Nx Cloud's runner that you can use on your workspace. Both tokens support distributed task execution and allow Nx Cloud to store metadata about runs. - `read-only` diff --git a/docs/nx-cloud/account/google-auth.md b/docs/nx-cloud/recipes/google-auth.md similarity index 100% rename from docs/nx-cloud/account/google-auth.md rename to docs/nx-cloud/recipes/google-auth.md diff --git a/docs/nx-cloud/account/google_oauth.png b/docs/nx-cloud/recipes/google_oauth.png similarity index 100% rename from docs/nx-cloud/account/google_oauth.png rename to docs/nx-cloud/recipes/google_oauth.png diff --git a/docs/nx-cloud/account/require-google-signin.webp b/docs/nx-cloud/recipes/require-google-signin.webp similarity index 100% rename from docs/nx-cloud/account/require-google-signin.webp rename to docs/nx-cloud/recipes/require-google-signin.webp diff --git a/docs/nx-cloud/account/require_google_signin.png b/docs/nx-cloud/recipes/require_google_signin.png similarity index 100% rename from docs/nx-cloud/account/require_google_signin.png rename to docs/nx-cloud/recipes/require_google_signin.png diff --git a/docs/nx-cloud/tutorial/Circle PR passed.png b/docs/nx-cloud/tutorial/Circle PR passed.png new file mode 100644 index 00000000000000..374a24ec393e02 Binary files /dev/null and b/docs/nx-cloud/tutorial/Circle PR passed.png differ diff --git a/docs/nx-cloud/tutorial/Message Logged.png b/docs/nx-cloud/tutorial/Message Logged.png new file mode 100644 index 00000000000000..27bc8d7022e36c Binary files /dev/null and b/docs/nx-cloud/tutorial/Message Logged.png differ diff --git a/docs/nx-cloud/tutorial/circle-ci-remote-cache.png b/docs/nx-cloud/tutorial/circle-ci-remote-cache.png new file mode 100644 index 00000000000000..5b0f8bcacff2f1 Binary files /dev/null and b/docs/nx-cloud/tutorial/circle-ci-remote-cache.png differ diff --git a/docs/nx-cloud/tutorial/circle-dte-multiple-agents.png b/docs/nx-cloud/tutorial/circle-dte-multiple-agents.png new file mode 100644 index 00000000000000..eddabf17a29376 Binary files /dev/null and b/docs/nx-cloud/tutorial/circle-dte-multiple-agents.png differ diff --git a/docs/nx-cloud/tutorial/circle-orb-security.png b/docs/nx-cloud/tutorial/circle-orb-security.png new file mode 100644 index 00000000000000..afc4c839d056ca Binary files /dev/null and b/docs/nx-cloud/tutorial/circle-orb-security.png differ diff --git a/docs/nx-cloud/tutorial/circle-single-build-success.jpg b/docs/nx-cloud/tutorial/circle-single-build-success.jpg new file mode 100644 index 00000000000000..c1641ee2139ea5 Binary files /dev/null and b/docs/nx-cloud/tutorial/circle-single-build-success.jpg differ diff --git a/docs/nx-cloud/tutorial/circle.md b/docs/nx-cloud/tutorial/circle.md new file mode 100644 index 00000000000000..042f5310280877 --- /dev/null +++ b/docs/nx-cloud/tutorial/circle.md @@ -0,0 +1,514 @@ +--- +title: 'Circle CI Tutorial with Nx' +description: In this tutorial you'll set up continuous integration with Circle CI and Nx +--- + +# Circle CI with Nx + +In this tutorial we're going to learn how to leverage Nx to setup a scalable CI pipeline on Circle CI. You're going to learn + +- how to set up Circle CI and configure Nx +- how to run tasks for only the projects that were affected by a given PR +- how to enable remote caching +- how to parallelize and distribute tasks across multiple machines + +Note, many of these optimizations are incremental, meaning you could set up running tasks for only affected projects and stop there. Later when you experience slow CI runs, you could add caching to further improve CI performance or even go further and distribute tasks across machines. + +## Example Repository + +To follow along with this tutorial, we recommend using the [nx-shops sample repository](https://github.com/nrwl/nx-shops). + +{% github-repository url="https://github.com/nrwl/nx-shops" /%} + +The `nx-shops` repo is useful to demonstrate the value of the CI pipeline because it has the following characteristics: + +- Multiple Nx projects with interdependencies +- Defined lint, test, build and e2e tasks +- Running all the tasks takes more than a minute to finish + +To get started: + +1. [Fork the nx-shop repo](https://github.com/nrwl/nx-shops/fork) and then clone it to your local machine + + ```shell + git clone git@github.com:/nx-shops.git + ``` + +2. Install dependencies (this repo uses [PNPM](https://pnpm.io/) but you should be able to also use any other package manager) + + ```shell + pnpm i + ``` + +3. Explore the structure of the repo using **the Nx Graph** + + ```shell + pnpm nx graph + ``` + +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 + ``` + +## 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. + +To verify that Circle CI is set up correctly we'll create a pipeline that just logs a message. First, checkout a new branch: + +```shell +git checkout -b circle-message +``` + +Then create (or modify) the `.circleci/config.yml` file with these contents: + +```yaml {% fileName=".circleci/config.yml" %} +version: 2.1 + +jobs: + main: + docker: + - image: cimg/node:lts-browsers + steps: + - run: + name: Print a message + command: echo "Hello Circle CI!" + +workflows: + version: 2 + + ci: + jobs: + - main +``` + +Next, commit this change, push the branch and create a PR on your forked GitHub repository: + +```shell +git commit -am "pipeline that logs a message" +git push -u origin HEAD +``` + +If everything was set up correctly, you should see a message from Circle CI in the PR with a success status. + +![All checks have passed in the PR](/nx-cloud/tutorial/Circle%20PR%20passed.png) + +Click on the job details and you should see the `Hello Circle CI` message in the logs. + +![The "Hello Circle CI" message is printed in the logs](/nx-cloud/tutorial/Message%20Logged.png) + +Merge your PR into the `main` branch when you're ready to move to the next section. + +## Configure Nx on Circle CI + +Now let's use Nx in the pipeline. The simplest way to use Nx is to run a single task, so we'll start by building our `cart` application. + +```shell +pnpm nx build cart +``` + +We need to adjust a couple of things on our CI pipeline to make this work: + +- clone the repository +- install NPM dependencies (in our nx-shop using PNPM) +- use Nx to run the `build` command + +Nx is an [npm package](https://www.npmjs.com/package/nx) so once NPM packages are installed we will be able to use it. + +Create a new branch called `build-one-app` and paste this code into the Circle CI config. + +```yaml {% fileName=".circleci/config.yml" highlightLines=["8-14"] %} +version: 2.1 + +jobs: + main: + docker: + - image: cimg/node:lts-browsers + steps: + - checkout + - run: + name: install dependencies + command: pnpm install --frozen-lockfile + - run: + name: Run build + command: pnpm nx build cart + +workflows: + version: 2 + + ci: + jobs: + - main +``` + +Once `node_modules` are in place, you can run normal Nx commands. In this case, we run `pnpm nx build cart`. Push the changes to your repository by creating a new PR and verifying the new CI pipeline correctly builds our application. + +![Building a single app with nx](/nx-cloud/tutorial/circle-single-build-success.jpg) + +You might have noticed that there's also a build running for `shared-header`, `shared-product-types` and `shared-product-ui`. These are projects in our workspace that `cart` depends on. Thanks to the [Nx task pipeline](/concepts/task-pipeline-configuration), Nx knows that it needs to build these projects first before building `cart`. This already helps us simplify our pipeline as we + +- don't need to define these builds automatically +- don't need to make any changes to our pipeline as our `cart` app grows and depends on more projects +- don't need to worry about the order of the builds + +Merge your PR into the `main` branch when you're ready to move to the next section. + +## Optimize our CI by caching NPM dependencies + +While this isn't related to Nx specifically, it's a good idea to cache NPM dependencies in CI. This will speed up the CI pipeline by avoiding downloading the same dependencies over and over again. Circle CI has [a docs page on how to cache NPM dependencies](https://circleci.com/docs/caching/). + +Adjust your CI pipeline script as follows + +```yaml {% fileName=".circleci/config.yml" highlightLines=["10-11", "17-21"] %} +version: 2.1 + +jobs: + main: + docker: + - image: cimg/node:lts-browsers + steps: + - checkout + # look for existing cache and restore if found + - restore_cache: + key: npm-dependencies-{{ checksum "pnpm-lock.yaml" }} + # install dependencies + - run: + name: install dependencies + command: pnpm install --frozen-lockfile + # save any changes to the cache + - save_cache: + key: npm-dependencies-{{ checksum "pnpm-lock.yaml" }} + paths: + - node_modules + - ~/.cache/Cypress # needed for the Cypress binary + - run: + name: Run build + command: pnpm nx build cart + +workflows: + version: 2 + + ci: + jobs: + - 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). + +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. + +## Process Only Affected Projects + +So far we only ran the build for our `cart` application. There are other apps in our monorepo workspace though, namely `admin`, `landing-page` and `products`. We could now adjust our CI pipeline to add these builds as well: + +```plaintext +pnpm nx build cart +pnpm nx build admin +pnpm nx build landing-page +``` + +Clearly this is not a scalable solution as it requires us to manually add every new app to the pipeline (and it doesn't include other tasks like `lint`, `test` etc). To improve this we can change the command to run the `build` for all projects like + +```{% command="nx run-many -t build" %} + ✔ nx run shared-product-types:build (429ms) + ✔ nx run shared-product-ui:build (455ms) + ✔ nx run shared-header:build (467ms) + ✔ nx run landing-page:build:production (3s) + ✔ nx run admin:build:production (3s) + ✔ nx run cart:build:production (3s) + + ———————————————————————————————————————————————————————————————— + + > NX Successfully ran target build for 6 projects (10s) +``` + +This change makes our CI pipeline configuration more maintainable. For a small repository, this might be good enough, but after a little bit of growth this approach will cause your CI times to become unmanageable. + +Nx comes with a dedicated ["affected" command](/nx-cloud/features/affected) to help with that by only running tasks for projects that were affected by the changes in a given PR. + +```{% command="nx affected -t build" %} + ✔ nx run shared-product-types:build (404ms) + ✔ nx run shared-product-ui:build (445ms) + ✔ nx run shared-header:build (465ms) + ✔ nx run cart:build:production (3s) + + —————————————————————————————————————————————————————————————————————————————————————— + + > NX Successfully ran target build for project cart and 3 tasks it depends on (4s) +``` + +### 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. + +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. + +The goal of the CI pipeline is to make sure that the current state of the repository is a good one. To ensure this, we want to verify all the changes **since the last successful CI run** - not just since the last commit on `main`. + +While you could calculate this yourself, we created the [`nrwl/nx` Circle CI orb](https://github.com/nrwl/nx-orb#background) to help with that. It provides you with the `nx/set-shas` step which automatically sets the `$NX_BASE` and `$NX_HEAD` environment variables to the correct commit SHAs for you to use in the affected command. + +In order to use the `nrwl/nx` orb, you need to enable the use of third-party Circle CI orbs in your organization settings. In the Circle CI project dashboard, go to `Organization Settings -> Security` and select `Yes` under Orb Security Settings: Allow Uncertified Orbs. + +![Adjust ORB Security Settings in Circle CI](/nx-cloud/tutorial/circle-orb-security.png) + +### Using the Affected Commands in our Pipeline + +Let's adjust our CI pipeline configuration to use the affected command. Create a new branch called `ci-affected` and create a PR with the following configuration: + +```yaml {% fileName=".circleci/config.yml" highlightLines=[2,3,20,22,23] %} +version: 2.1 +orbs: + nx: nrwl/nx@1.5.1 +jobs: + 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 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: + - main +``` + +Notice how we're using the `$NX_BASE` and `$NX_HEAD` environment variables to set the correct `base` and `head` commits to use for file comparisons. + +We're also using the `--parallel` flag to run up to 3 `lint`, `test` or `build` tasks at once, but we want to make sure that only 1 `e2e` task is running at a time. + +When you check the CI logs for this PR, you'll notice that no tasks were run by the `affected` command. That's because the `.circleci/config.yml` file is not an input for any task. We should really double check every task whenever we make changes to the CI pipeline, so let's fix that by adding an entry in the `sharedGlobals` array in the `nx.json` file. + +```jsonc {% fileName="nx.json" %} +{ + "namedInputs": { + "default": ["{projectRoot}/**/*", "sharedGlobals"], + "sharedGlobals": [ + "{workspaceRoot}/babel.config.json", + "{workspaceRoot}/.circleci/config.yml" // add this line + ] + // etc... + } +} +``` + +Merge your PR into the `main` branch when you're ready to move to the next section. + +## Enable Remote Caching on Circle CI + +Reducing the number of tasks to run via [affected commands](/nx-cloud/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](/nx-cloud/features/remote-cache) can eliminate that waste for you. + +```{% command="pnpm nx connect" %} +✔ Enable distributed caching to make your CI faster · Yes +$ nx g nx:connect-to-nx-cloud --quiet --no-interactive + + > NX Distributed caching via Nx Cloud has been enabled + + In addition to the caching, Nx Cloud provides config-free distributed execution, + UI for viewing complex runs and GitHub integration. Learn more at https://nx.app + + Your workspace is currently unclaimed. Run details from unclaimed workspaces can be viewed on cloud.nx.app by anyone + with the link. Claim your workspace at the following link to restrict access. + + https://cloud.nx.app/orgs/workspace-setup?accessToken=[YourAccessTokenHere] +``` + +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. + +![Empty Nx Cloud Dashboard](/nx-cloud/tutorial/nx-cloud-empty-workspace.png) + +Once your workspace is connected to Nx Cloud, run some tasks locally to prime the cache: + +```shell +pnpm nx run-many -t lint,test,build,e2e +``` + +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..." +} +``` + +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 various scenarios](/nx-cloud/concepts/scenarios) and how to configure them. + +You might also want to learn more about [how to fine-tune caching](/recipes/running-tasks/customizing-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 + +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)](/nx-cloud/features/distribute-task-execution). + +Nx Cloud's DTE 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 +- 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. + +```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: ... +``` + +The `main` job looks very similar to the previous configuration, with the addition of a single line above the `nx affected` commands. + +```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 +``` + +Try it out by creating a new PR with the above changes. + +Once Circle CI starts, you should see multiple agents running in parallel: + +![Circle CI showing multiple DTE agents](/nx-cloud/tutorial/circle-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 `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. + +## 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](/nx-cloud/recipes/source-control-integration/github) to view Nx Cloud results directly in your PR +- Choose the [security scenario](/nx-cloud/concepts/scenarios) that makes sense for your organization +- [Record non-Nx commands](/nx-cloud/recipes/other/record-commands) and view the results in the Nx Cloud interface diff --git a/docs/nx-cloud/tutorial/gh-ci-remote-cache.png b/docs/nx-cloud/tutorial/gh-ci-remote-cache.png new file mode 100644 index 00000000000000..5ceb5fa45212d3 Binary files /dev/null and b/docs/nx-cloud/tutorial/gh-ci-remote-cache.png differ diff --git a/docs/nx-cloud/tutorial/gh-dte-multiple-agents.png b/docs/nx-cloud/tutorial/gh-dte-multiple-agents.png new file mode 100644 index 00000000000000..2b0801f7e7bc2f Binary files /dev/null and b/docs/nx-cloud/tutorial/gh-dte-multiple-agents.png differ diff --git a/docs/nx-cloud/tutorial/gh-message.png b/docs/nx-cloud/tutorial/gh-message.png new file mode 100644 index 00000000000000..ece84126f38efe Binary files /dev/null and b/docs/nx-cloud/tutorial/gh-message.png differ diff --git a/docs/nx-cloud/tutorial/gh-pr-passed.png b/docs/nx-cloud/tutorial/gh-pr-passed.png new file mode 100644 index 00000000000000..8eea77f600a46c Binary files /dev/null and b/docs/nx-cloud/tutorial/gh-pr-passed.png differ diff --git a/docs/nx-cloud/tutorial/gh-single-build-success.png b/docs/nx-cloud/tutorial/gh-single-build-success.png new file mode 100644 index 00000000000000..52e3046a7f3955 Binary files /dev/null and b/docs/nx-cloud/tutorial/gh-single-build-success.png differ diff --git a/docs/nx-cloud/tutorial/github-actions.md b/docs/nx-cloud/tutorial/github-actions.md new file mode 100644 index 00000000000000..5d8d1da702556a --- /dev/null +++ b/docs/nx-cloud/tutorial/github-actions.md @@ -0,0 +1,440 @@ +--- +title: 'GitHub Actions Tutorial with Nx' +description: In this tutorial you'll set up continuous integration with GitHub Actions and Nx +--- + +# GitHub Actions with Nx + +In this tutorial we're going to learn how to leverage Nx to setup a scalable CI pipeline on GitHub Actions. You're going to learn + +- how to set up GitHub Actions and configure Nx +- how to run tasks for only the projects that were affected by a given PR +- how to enable remote caching +- how to parallelize and distribute tasks across multiple machines + +Note, many of these optimizations are incremental, meaning you could set up running tasks for only affected projects and stop there. Later when you experience slow CI runs, you could add caching to further improve CI performance or even go further and distribute tasks across machines. + +## Example Repository + +To follow along with this tutorial, we recommend using the [nx-shops sample repository](https://github.com/nrwl/nx-shops). + +{% github-repository url="https://github.com/nrwl/nx-shops" /%} + +The `nx-shops` repo is useful to demonstrate the value of the CI pipeline because it has the following characteristics: + +- Multiple Nx projects with interdependencies +- Defined lint, test, build and e2e tasks +- Running all the tasks takes more than a minute to finish + +To get started: + +1. [Fork the nx-shop repo](https://github.com/nrwl/nx-shops/fork) and then clone it to your local machine + + ```shell + git clone git@github.com:/nx-shops.git + ``` + +2. Install dependencies (this repo uses [PNPM](https://pnpm.io/) but you should be able to also use any other package manager) + + ```shell + pnpm i + ``` + +3. Explore the structure of the repo using **the Nx Graph** + + ```shell + pnpm nx graph + ``` + +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 + ``` + +## 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: + +```shell +git checkout -b ci-message +``` + +Then create (or modify) the `.github/workflows/ci.yml` file with these contents: + +```yaml {% fileName=".github/workflows/ci.yml" %} +name: CI +on: + push: + branches: + # Change this if your primary branch is not main + - main + pull_request: + +jobs: + main: + runs-on: ubuntu-latest + steps: + - run: echo "Hello GitHub Actions!" +``` + +Next, commit this change, push the branch and create a PR on your forked GitHub repository: + +```shell +git commit -am "pipeline that logs a message" +git push -u origin HEAD +``` + +If everything was set up correctly, you should see a message from GitHub Actions in the PR with a success status. + +![All checks have passed in the PR](/nx-cloud/tutorial/gh-pr-passed.png) + +Click on the job details and you should see the `Hello GitHub Actions` message in the logs. + +![The "Hello GitHub Actions" message is printed in the logs](/nx-cloud/tutorial/gh-message.png) + +Merge your PR into the `main` branch when you're ready to move to the next section. + +## Configure Nx on GitHub Actions + +Now let's use Nx in the pipeline. The simplest way to use Nx is to run a single task, so we'll start by building our `cart` application. + +```shell +pnpm nx build cart +``` + +We need to adjust a couple of things on our CI pipeline to make this work: + +- clone the repository +- install NPM dependencies (in our nx-shop using PNPM) +- use Nx to run the `build` command + +Nx is an [npm package](https://www.npmjs.com/package/nx) so once NPM packages are installed we will be able to use it. + +Create a new branch called `build-one-app` and paste this code into the GitHub Actions config. + +```yaml {% fileName=".github/workflows/ci.yml" highlightLines=["12-20"] %} +name: CI +on: + push: + branches: + - main + pull_request: + +jobs: + main: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + # Setup pnpm + - uses: pnpm/action-setup@v2 + with: + version: 8 + - run: pnpm install --frozen-lockfile + - run: pnpm nx build cart +``` + +Once `node_modules` are in place, you can run normal Nx commands. In this case, we run `pnpm nx build cart`. Push the changes to your repository by creating a new PR and verifying the new CI pipeline correctly builds our application. + +![Building a single app with nx](/nx-cloud/tutorial/gh-single-build-success.png) + +You might have noticed that there's also a build running for `shared-header`, `shared-product-types` and `shared-product-ui`. These are projects in our workspace that `cart` depends on. Thanks to the [Nx task pipeline](/concepts/task-pipeline-configuration), Nx knows that it needs to build these projects first before building `cart`. This already helps us simplify our pipeline as we + +- don't need to define these builds automatically +- don't need to make any changes to our pipeline as our `cart` app grows and depends on more projects +- don't need to worry about the order of the builds + +Merge your PR into the `main` branch when you're ready to move to the next section. + +## Optimize our CI by caching NPM dependencies + +While this isn't related to Nx specifically, it's a good idea to cache NPM dependencies in CI. This will speed up the CI pipeline by avoiding downloading the same dependencies over and over again. GitHub Actions has [an action to cache files](https://github.com/actions/cache) that we'll use. + +Adjust your CI pipeline script as follows + +```yaml {% fileName=".github/workflows/ci.yml" highlightLines=["18-24", "26-32"] %} +name: CI +on: + push: + branches: + - main + pull_request: + +jobs: + main: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + - uses: pnpm/action-setup@v2 + with: + version: 8 + - name: Restore cached npm dependencies + 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 + uses: actions/cache/save@v3 + with: + path: | + node_modules + ~/.cache/Cypress # needed for the Cypress binary + key: npm-dependencies-${{ hashFiles('pnpm-lock.yaml') }} + - 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). + +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. + +## Process Only Affected Projects + +So far we only ran the build for our `cart` application. There are other apps in our monorepo workspace though, namely `admin`, `landing-page` and `products`. We could now adjust our CI pipeline to add these builds as well: + +```plaintext +pnpm nx build cart +pnpm nx build admin +pnpm nx build landing-page +``` + +Clearly this is not a scalable solution as it requires us to manually add every new app to the pipeline (and it doesn't include other tasks like `lint`, `test` etc). To improve this we can change the command to run the `build` for all projects like + +```{% command="nx run-many -t build" %} + ✔ nx run shared-product-types:build (429ms) + ✔ nx run shared-product-ui:build (455ms) + ✔ nx run shared-header:build (467ms) + ✔ nx run landing-page:build:production (3s) + ✔ nx run admin:build:production (3s) + ✔ nx run cart:build:production (3s) + + ———————————————————————————————————————————————————————————————— + + > NX Successfully ran target build for 6 projects (10s) +``` + +This change makes our CI pipeline configuration more maintainable. For a small repository, this might be good enough, but after a little bit of growth this approach will cause your CI times to become unmanageable. + +Nx comes with a dedicated ["affected" command](/nx-cloud/features/affected) to help with that by only running tasks for projects that were affected by the changes in a given PR. + +```{% command="nx affected -t build" %} + ✔ nx run shared-product-types:build (404ms) + ✔ nx run shared-product-ui:build (445ms) + ✔ nx run shared-header:build (465ms) + ✔ nx run cart:build:production (3s) + + —————————————————————————————————————————————————————————————————————————————————————— + + > NX Successfully ran target build for project cart and 3 tasks it depends on (4s) +``` + +### 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. + +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. + +The goal of the CI pipeline is to make sure that the current state of the repository is a good one. To ensure this, we want to verify all the changes **since the last successful CI run** - not just since the last commit on `main`. + +While you could calculate this yourself, we created the [`nx-set-shas` GitHub Action](https://github.com/marketplace/actions/nx-set-shas) to help with that. It provides you with the `nrwl/nx-set-shas` action which automatically sets the `NX_BASE` and `NX_HEAD` environment variables to the correct commit SHAs. The affected command will use these environment variables when they are defined. + +### Using the Affected Commands in our Pipeline + +Let's adjust our CI pipeline configuration to use the affected command. Create a new branch called `ci-affected` and create a PR with the following configuration: + +```yaml {% fileName=".github/workflows/ci.yml" highlightLines=["35-39"] %} +name: CI +on: + push: + branches: + - main + pull_request: + +jobs: + main: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + - uses: pnpm/action-setup@v2 + with: + version: 8 + - 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 --configuration=ci + - run: pnpm nx affected -t e2e --parallel=1 +``` + +We're using the `--parallel` flag to run up to 3 `lint`, `test` or `build` tasks at once, but we want to make sure that only 1 `e2e` task is running at a time. + +When you check the CI logs for this PR, you'll notice that no tasks were run by the `affected` command. That's because the `.github/workflows/ci.yml` file is not an input for any task. We should really double check every task whenever we make changes to the CI pipeline, so let's fix that by adding an entry in the `sharedGlobals` array in the `nx.json` file. + +```jsonc {% fileName="nx.json" highlightLines=[6] %} +{ + "namedInputs": { + "default": ["{projectRoot}/**/*", "sharedGlobals"], + "sharedGlobals": [ + "{workspaceRoot}/babel.config.json", + "{workspaceRoot}/.github/workflows/ci.yml" // add this line + ] + // etc... + } +} +``` + +Merge your PR into the `main` branch when you're ready to move to the next section. + +## Enable Remote Caching on GitHub Actions + +Reducing the number of tasks to run via [affected commands](/nx-cloud/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](/nx-cloud/features/remote-cache) can eliminate that waste for you. + +```{% command="pnpm nx connect" %} +✔ Enable distributed caching to make your CI faster · Yes + + > NX Distributed caching via Nx Cloud has been enabled + + In addition to the caching, Nx Cloud provides config-free distributed execution, + UI for viewing complex runs and GitHub integration. Learn more at https://nx.app + + Your workspace is currently unclaimed. Run details from unclaimed workspaces can be viewed on cloud.nx.app by anyone + with the link. Claim your workspace at the following link to restrict access. + + https://cloud.nx.app/orgs/workspace-setup?accessToken=[YourAccessTokenHere] +``` + +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. + +![Empty Nx Cloud Dashboard](/nx-cloud/tutorial/nx-cloud-empty-workspace.png) + +Once your workspace is connected to Nx Cloud, run some tasks locally to prime the cache: + +```shell +pnpm nx run-many -t lint,test,build,e2e +``` + +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..." +} +``` + +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 various scenarios](/nx-cloud/concepts/scenarios) and how to configure them. + +You might also want to learn more about [how to fine-tune caching](/recipes/running-tasks/customizing-inputs) to get even better results. + +Merge your PR into the `main` branch when you're ready to move to the next section. + +## Enable PR Integration + +The [Nx Cloud GitHub App](https://github.com/marketplace/official-nx-cloud-app) automatically creates a comment on your PRs that provides a direct link to the relevant Nx Cloud logs and quickly shows which command failed. + +### Install the App + +Install the [Nx Cloud GitHub App](https://github.com/marketplace/official-nx-cloud-app) and give it permission to access your repo. + +### Connecting Your Workspace + +Once you have installed the Nx Cloud GitHub App, you must link your workspace to the installation. To do this, sign in to Nx Cloud and navigate to the VCS Integrations setup page. Once on the VCS Integrations setup page, choose GitHub as your version control system. + +![Access VCS Setup](/nx-cloud/set-up/access-vcs-setup.webp) + +### Authenticate Via the GitHub App + +To use the Nx Cloud GitHub App for authentication, select the radio button and then click "Connect". +This will verify that Nx Cloud can connect to your repo. Upon a successful test, your configuration is saved. + +![Use GitHub App for Authentication](/nx-cloud/set-up/use-github-app-auth.webp) + +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](/nx-cloud/recipes/source-control-integration/github). + +## Parallelize Tasks across Multiple Machines + +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)](/nx-cloud/features/distribute-task-execution). + +Nx Cloud's DTE 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 +- 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. + +```yaml {% fileName=".github/workflows/ci.yml" highlightLines=["9-21"] %} +name: CI +on: + push: + branches: + - main + pull_request: + +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 +``` + +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](/nx-cloud/recipes/source-control-integration/github) to view Nx Cloud results directly in your PR +- Choose the [security scenario](/nx-cloud/concepts/scenarios) that makes sense for your organization +- [Record non-Nx commands](/nx-cloud/recipes/other/record-commands) and view the results in the Nx Cloud interface diff --git a/docs/nx-cloud/tutorial/nx-cloud-empty-workspace.png b/docs/nx-cloud/tutorial/nx-cloud-empty-workspace.png new file mode 100644 index 00000000000000..dcbf95ae95d7e3 Binary files /dev/null and b/docs/nx-cloud/tutorial/nx-cloud-empty-workspace.png differ diff --git a/docs/nx-cloud/tutorial/nx-cloud-run-details.png b/docs/nx-cloud/tutorial/nx-cloud-run-details.png new file mode 100644 index 00000000000000..9f816072c8c4fe Binary files /dev/null and b/docs/nx-cloud/tutorial/nx-cloud-run-details.png differ diff --git a/docs/packages.json b/docs/packages.json index 9dcff92fd4ebed..46ad788fe43611 100644 --- a/docs/packages.json +++ b/docs/packages.json @@ -10,7 +10,7 @@ "ng-packagr-lite", "package", "webpack-browser", - "webpack-dev-server", + "dev-server", "webpack-server", "module-federation-dev-server", "module-federation-dev-ssr" diff --git a/docs/shared/angular-tutorial/angular-monorepo.md b/docs/shared/angular-tutorial/angular-monorepo.md index 9636bf69badc83..41a8757b9806f1 100644 --- a/docs/shared/angular-tutorial/angular-monorepo.md +++ b/docs/shared/angular-tutorial/angular-monorepo.md @@ -981,7 +981,7 @@ Learn more about how to [enforce module boundaries](/core-features/enforce-modul ## Setting Up CI -Without adequate tooling, CI times tend to grow exponentially with the size of the codebase. Nx helps decrease the average CI time with the [`affected` command](/nx-cloud/features/affected) and Nx Cloud's [distributed caching](/nx-cloud/features/remote-cache). Nx also [decreases the worst case CI time](/concepts/dte) with Nx Cloud's distributed task execution. +Without adequate tooling, CI times tend to grow exponentially with the size of the codebase. Nx helps decrease the average CI time with the [`affected` command](/nx-cloud/features/affected) and Nx Cloud's [distributed caching](/nx-cloud/features/remote-cache). Nx also [decreases the worst case CI time](/nx-cloud/concepts/dte) with Nx Cloud's distributed task execution. To set up Nx Cloud run: diff --git a/docs/shared/ci-overview.md b/docs/shared/ci-overview.md deleted file mode 100644 index 8185ada12e119d..00000000000000 --- a/docs/shared/ci-overview.md +++ /dev/null @@ -1,10 +0,0 @@ -# Configuring CI for Nx workspaces - -The following guides cover optimizing your CI/CD environments with affected commands and distributed caching: - -- [Setting up CI using Azure Pipelines](/nx-cloud/recipes/set-up/monorepo-ci-azure) -- [Setting up CI using CircleCI](/nx-cloud/recipes/set-up/monorepo-ci-circle-ci) -- [Setting up CI using GitHub Actions](/nx-cloud/recipes/set-up/monorepo-ci-github-actions) -- [Setting up CI using Jenkins](/nx-cloud/recipes/set-up/monorepo-ci-jenkins) -- [Setting up CI using GitLab](/nx-cloud/recipes/set-up/monorepo-ci-gitlab) -- [Setting up CI using Bitbucket](/nx-cloud/recipes/set-up/monorepo-ci-bitbucket-pipelines) diff --git a/docs/shared/concepts/improve-worst-case-ci-times.md b/docs/shared/concepts/improve-worst-case-ci-times.md index 794bb7e033f40f..6335382f46a09d 100644 --- a/docs/shared/concepts/improve-worst-case-ci-times.md +++ b/docs/shared/concepts/improve-worst-case-ci-times.md @@ -87,12 +87,10 @@ Nx Cloud's Distributed Task Execution removes the burden of the complex setup of The setup looks like this: ```yaml {% fileName="main-job.yml" %} -# Coordinate the agents to run the tasks -- npx nx-cloud start-ci-run +# 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 # Run any commands you want here -- nx affected -t lint test build -# Stop any run away agents -- npx nx-cloud stop-all-agents +- nx affected -t lint,test,build ``` ```yaml {% fileName="agent.yml" %} @@ -109,7 +107,7 @@ This approach fully optimizes the binning strategy so that tasks are optimally d ### 🎉 Pro: Easy to Scale -If CI is taking too long, simply increase the number of agent jobs being started in your CI system and Nx will recognize the new agent jobs are available and distribute tasks accordingly. With this approach, your worst case CI time is only limited by your longest running individual task. If you want Nx to automatically provision the agents for you, check out [Nx Cloud Workflows](/nx-cloud/intro/nx-cloud-workflows). +If CI is taking too long, simply increase the number of agent jobs being started in your CI system and Nx will recognize the new agent jobs are available and distribute tasks accordingly. With this approach, your worst case CI time is only limited by your longest running individual task. If you want Nx to automatically provision the agents for you, check out [Nx Cloud Workflows](/nx-cloud/features/nx-cloud-workflows). ### 🎉 Pro: Build Artifacts diff --git a/docs/shared/core-features/distribute-task-execution.md b/docs/shared/core-features/distribute-task-execution.md index 11da7c2a980ffc..22b233af32aa11 100644 --- a/docs/shared/core-features/distribute-task-execution.md +++ b/docs/shared/core-features/distribute-task-execution.md @@ -25,7 +25,7 @@ When you set up Nx's distributed task execution, your task graph will look more 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 distributed caching to recreate all of the logs and build artifacts on the main job. -Find more information in this [detailed guide to improve your worst case CI times](/concepts/dte). +Find more information in this [detailed guide to improve your worst case CI times](/nx-cloud/concepts/dte). ## Set up @@ -54,7 +54,7 @@ For existing workspaces you would probably want to adjust your configuration by 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 Cloud Workflows](/nx-cloud/intro/nx-cloud-workflows) +create in your CI system. If you would like Nx Cloud to dynamically provision agents for you, check out [Nx Cloud Workflows](/nx-cloud/features/nx-cloud-workflows) 1. Main job that controls what is going to be executed 2. Multiple agent jobs that actually execute the tasks @@ -150,7 +150,6 @@ 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. -- [Overview](/nx-cloud/recipes/set-up/ci-setup#distributed-ci-with-nx-cloud) - [Azure Pipelines](/nx-cloud/recipes/set-up/monorepo-ci-azure#distributed-ci-with-nx-cloud) - [Circle CI](/nx-cloud/recipes/set-up/monorepo-ci-circle-ci#distributed-ci-with-nx-cloud) - [GitHub Actions](/nx-cloud/recipes/set-up/monorepo-ci-github-actions#distributed-ci-with-nx-cloud) diff --git a/docs/shared/guides/module-federation/faster-builds.md b/docs/shared/guides/module-federation/faster-builds.md index 630c9d726e2bf6..309a1bb6dcbc07 100644 --- a/docs/shared/guides/module-federation/faster-builds.md +++ b/docs/shared/guides/module-federation/faster-builds.md @@ -372,7 +372,7 @@ module.exports = withModuleFederation({ Now you can run `nx build host` to build all the `host` and all the implicit dependencies in production mode. {% callout type="note" title="Distributed caching" %} -Again, if you don't use [Nx Cloud's Distributed Tasks Execution](/concepts/dte) using Module Federation will be slower +Again, if you don't use [Nx Cloud's Distributed Tasks Execution](/nx-cloud/concepts/dte) using Module Federation will be slower than building everything in a single process. It's only if you enable Distributed Tasks Execution, your CI will be able to build each remote on a separate machine, in parallel, (or not build it at all and retrieve it from cache), which will reduce the CI time. diff --git a/docs/shared/migration/from-turborepo.md b/docs/shared/migration/from-turborepo.md index 70a7227472b38b..d179d6e7fd03b2 100644 --- a/docs/shared/migration/from-turborepo.md +++ b/docs/shared/migration/from-turborepo.md @@ -215,7 +215,7 @@ For each `turbo.json` configuration property, the equivalent Nx property is list | `--parallel` | N/A | | `--remote-only` | N/A. Can [ignore the remote cache](/nx-cloud/features/remote-cache#skipping-cloud) with `--no-cloud`. | | `--summarize` | N/A | -| `--token` | Set the [Nx Cloud token in `nx.json`](/nx-cloud/account/access-tokens#setting-access-tokens) or as an environment variable (`NX_CLOUD_ACCESS_TOKEN`) | +| `--token` | Set the [Nx Cloud token in `nx.json`](/nx-cloud/recipes/security/access-tokens#setting-access-tokens) or as an environment variable (`NX_CLOUD_ACCESS_TOKEN`) | | `--team` | See `--token` for choosing a different Nx Cloud workspace. You can [use `--runner`](/nx-api/nx/documents/run-many#runner) to choose a different runner defined in the `nx.json` file. | | `--preflight` | N/A | | `--trace` | N/A. [`--verbose`](/nx-api/nx/documents/run-many#verbose) for more logging. | diff --git a/docs/shared/migration/lerna-and-nx.md b/docs/shared/migration/lerna-and-nx.md index c885e172104b08..2867ac2a72eef6 100644 --- a/docs/shared/migration/lerna-and-nx.md +++ b/docs/shared/migration/lerna-and-nx.md @@ -23,7 +23,7 @@ Nx comes with a powerful task scheduler that intelligently runs operations and m - **Parallelization and task dependencies -** Nx automatically [knows how your projects relate to each other](/concepts/more-concepts/how-project-graph-is-built). As a result, if `project-a` depends on `project-b` and you run the build command for `project-a`, Nx first runs the builds for all of `project-a`'s dependencies and then the invoked project itself. Nx sorts these tasks to maximize parallelism. - **Only run what changed -** Using [Nx affected commands](/nx-cloud/features/affected) you only really execute tasks on the projects that changed, compared to a given baseline (usually the main branch). - **Caching -** You get Nx's [computation caching](/concepts/how-caching-works) for free. All operations, including artifacts and terminal output are restored from the cache (if present) in a completely transparent way without disrupting your DX. No configuration needed. Obviously this results in an incredible speed improvement. -- **Distributed Task Execution -** This is unique to Nx. In combination with Nx Cloud your tasks are automatically distributed across CI agents, taking into account build order, maximizing parallelization and thus agent utilization. It even learns from previous runs to better distribute tasks! [Learn more](/concepts/dte) +- **Distributed Task Execution -** This is unique to Nx. In combination with Nx Cloud your tasks are automatically distributed across CI agents, taking into account build order, maximizing parallelization and thus agent utilization. It even learns from previous runs to better distribute tasks! [Learn more](/nx-cloud/concepts/dte) ## Integrating Nx with Lerna diff --git a/docs/shared/monorepo-ci-azure.md b/docs/shared/monorepo-ci-azure.md index 24ff858b2e4ade..0dfa16e2bfa949 100644 --- a/docs/shared/monorepo-ci-azure.md +++ b/docs/shared/monorepo-ci-azure.md @@ -1,16 +1,10 @@ # Configuring CI Using Azure Pipelines and Nx -Below is an example of an Azure Pipelines setup for an Nx workspace - building and testing only what is affected. +There are two general approaches to setting up CI with Nx - using a single job or distributing tasks across multiple jobs. For smaller repositories, a single job is faster and cheaper, but once a full CI run starts taking 10 to 15 minutes, using multiple jobs becomes the better option. Nx Cloud's distributed task execution allows you to keep the CI pipeline fast as you scale. As the repository grows, all you need to do is add more agents. -{% callout type="note" title="Check your Shallow Fetch settings" %} - -Nx needs additional Git history available for `affected` to function correctly. Make sure Shallow fetching is disabled in your pipeline settings UI. For more info, check out this article from Microsoft [here](https://learn.microsoft.com/en-us/azure/devops/pipelines/yaml-schema/steps-checkout?view=azure-pipelines#shallow-fetch). - -{% /callout %} - -Unlike `GitHub Actions` and `CircleCI`, you don't have the metadata to help you track the last successful run on `main`. In the example below, the base is set to `HEAD~1` (for push) or branching point (for pull requests), but a more robust solution would be to tag an SHA in the main job once it succeeds and then use this tag as a base. You can also try [using the devops CLI within the pipeline yaml](#get-the-commit-of-the-last-successful-build). See the [nx-tag-successful-ci-run](https://github.com/nrwl/nx-tag-successful-ci-run) and [nx-set-shas](https://github.com/nrwl/nx-set-shas) (version 1 implements tagging mechanism) repositories for more information. +## Process Only Affected Projects With One Job on Azure Pipelines -We also have to set `NX_BRANCH` explicitly. NX_BRANCH does not impact the functionality of your runs, but does provide a human-readable label to easily identify them in the Nx Cloud app. +Below is an example of an Azure Pipelines setup that runs on a single job, building and testing only what is affected. This uses the [`nx affected` command](/nx-cloud/features/affected) to run the tasks only for the projects that were affected by that PR. ```yaml {% fileName="azure-pipelines.yml" %} trigger: @@ -60,6 +54,16 @@ jobs: - script: npx nx affected --base=$(BASE_SHA) -t lint,test,build --parallel=3 --configuration=ci ``` +{% callout type="note" title="Check your Shallow Fetch settings" %} + +Nx needs additional Git history available for [`affected`](/nx-cloud/features/affected) to function correctly. Make sure Shallow fetching is disabled in your pipeline settings UI. For more info, check out this article from Microsoft [here](https://learn.microsoft.com/en-us/azure/devops/pipelines/yaml-schema/steps-checkout?view=azure-pipelines#shallow-fetch). + +{% /callout %} + +Unlike `GitHub Actions` and `CircleCI`, you don't have the metadata to help you track the last successful run on `main`. In the example below, the base is set to `HEAD~1` (for push) or branching point (for pull requests), but a more robust solution would be to tag a SHA in the main job once it succeeds and then use this tag as a base. You can also try [using the devops CLI within the pipeline yaml](#get-the-commit-of-the-last-successful-build). See the [nx-tag-successful-ci-run](https://github.com/nrwl/nx-tag-successful-ci-run) and [nx-set-shas](https://github.com/nrwl/nx-set-shas) (version 1 implements tagging mechanism) repositories for more information. + +We also have to set `NX_BRANCH` explicitly. NX_BRANCH does not impact the functionality of your runs, but does provide a human-readable label to easily identify them in the Nx Cloud app. + The `main` job implements the CI workflow. ## Get the Commit of the Last Successful Build @@ -99,11 +103,17 @@ By default the command returns an entire JSON object with all the information. B Finally we extract the result in a common [custom variable](https://learn.microsoft.com/en-us/azure/devops/pipelines/process/set-variables-scripts?view=azure-devops&tabs=bash) named `BASE_SHA` used later by `nx affected` commands -## Distributed Task Execution with Nx Cloud +## Distribute Tasks Across Agents on Azure Pipelines -Read more about [Distributed Task Execution (DTE)](/nx-cloud/features/distribute-task-execution). +To set up [Distributed Task Execution (DTE)](/nx-cloud/features/distribute-task-execution), you can run this generator: -```yaml +```shell +npx nx g ci-workflow --ci=azure +``` + +Or you can copy and paste the workflow below: + +```yaml {% fileName="azure-pipelines.yml" %} trigger: - main pr: @@ -155,7 +165,15 @@ jobs: - script: npm ci - script: npx nx-cloud start-ci-run --stop-agents-after="build" - script: npx nx-cloud record -- npx nx format:check --base=$(BASE_SHA) --head=$(HEAD_SHA) - - script: npx nx affected --base=$(BASE_SHA) --head=$(HEAD_SHA) -t lint,test,build --parallel=3 --configuration=ci + - script: npx nx affected --base=$(BASE_SHA) --head=$(HEAD_SHA) -t lint,test,build --parallel=2 --configuration=ci ``` -You can also use our [ci-workflow generator](/nx-api/workspace/generators/ci-workflow) to generate the pipeline file. +This configuration is setting up two types of jobs - a main job and three agent jobs. + +The main job tells Nx Cloud to use DTE and then runs normal Nx commands as if this were a single pipeline set up. Once the commands are done, it notifies Nx Cloud to stop the agent jobs. + +The agent jobs set up the repo and then wait for Nx Cloud to assign them tasks. + +{% callout type="warning" title="Two Types of Parallelization" %} +The agent strategy of `parallel: 3` and the `nx affected --parallel=2` flag both parallelize tasks, but in different ways. The way this workflow is written, there will be 3 agents running tasks and each agent will try to run 2 tasks at once. If a particular CI run only has 2 tasks, only one agent will be used. +{% /callout %} diff --git a/docs/shared/monorepo-ci-bitbucket-pipelines.md b/docs/shared/monorepo-ci-bitbucket-pipelines.md index c20d5081f82e2b..c7ee92f1ec5f23 100644 --- a/docs/shared/monorepo-ci-bitbucket-pipelines.md +++ b/docs/shared/monorepo-ci-bitbucket-pipelines.md @@ -1,8 +1,12 @@ # Configuring CI Using Bitbucket Pipelines and Nx -Below is an example of a Bitbucket Pipeline setup for an Nx workspace - building and testing only what is affected. +There are two general approaches to setting up CI with Nx - using a single job or distributing tasks across multiple jobs. For smaller repositories, a single job is faster and cheaper, but once a full CI run starts taking 10 to 15 minutes, using multiple jobs becomes the better option. Nx Cloud's distributed task execution allows you to keep the CI pipeline fast as you scale. As the repository grows, all you need to do is add more agents. -```yaml +## Process Only Affected Projects With One Job on Bitbucket Pipelines + +Below is an example of an Bitbucket Pipelines setup that runs on a single job, building and testing only what is affected. This uses the [`nx affected` command](/nx-cloud/features/affected) to run the tasks only for the projects that were affected by that PR. + +```yaml {% fileName="bitbucket-pipelines.yml" %} image: node:20 pipelines: pull-requests: @@ -30,11 +34,17 @@ pipelines: The `pull-requests` and `main` jobs implement the CI workflow. -## Distributed Task Execution +## Distribute Tasks Across Agents on Bitbucket Pipelines + +To set up [Distributed Task Execution (DTE)](/nx-cloud/features/distribute-task-execution), you can run this generator: + +```shell +npx nx g ci-workflow --ci=bitbucket-pipelines +``` -This pipeline uses [Distributed Task Execution (DTE)](/nx-cloud/features/distribute-task-execution) to automatically distribute work across multiple agent processes. +Or you can copy and paste the workflow below: -```yaml +```yaml {% fileName="bitbucket-pipelines.yml" %} image: node:20 clone: @@ -62,9 +72,18 @@ pipelines: - npm ci - npx nx-cloud start-ci-run --stop-agents-after="build" --agent-count=3 - npx nx-cloud record -- npx nx format:check - - npx nx affected --target=lint,test,build - - npx nx-cloud stop-all-agents + - npx nx affected --target=lint,test,build --parallel=2 - step: *agent - step: *agent - step: *agent ``` + +This configuration is setting up two types of jobs - a main job and three agent jobs. + +The main job tells Nx Cloud to use DTE and then runs normal Nx commands as if this were a single pipeline set up. Once the commands are done, it notifies Nx Cloud to stop the agent jobs. + +The agent jobs set up the repo and then wait for Nx Cloud to assign them tasks. + +{% callout type="warning" title="Two Types of Parallelization" %} +The agents and the `--parallel` flag both parallelize tasks, but in different ways. The way this workflow is written, there will be 3 agents running tasks and each agent will try to run 2 tasks at once. If a particular CI run only has 2 tasks, only one agent will be used. +{% /callout %} diff --git a/docs/shared/monorepo-ci-circle-ci.md b/docs/shared/monorepo-ci-circle-ci.md index c29ebb0d13a1b3..3fe091e77ba427 100644 --- a/docs/shared/monorepo-ci-circle-ci.md +++ b/docs/shared/monorepo-ci-circle-ci.md @@ -1,6 +1,10 @@ -# Configuring CI Using CircleCI and Nx +# Configuring CI Using Circle CI and Nx -Below is an example of a Circle CI setup for an Nx workspace - building and testing only what is affected. For more details on how the Nx orb is used, head over to the [official docs](https://circleci.com/developer/orbs/orb/nrwl/nx). +There are two general approaches to setting up CI with Nx - using a single job or distributing tasks across multiple jobs. For smaller repositories, a single job is faster and cheaper, but once a full CI run starts taking 10 to 15 minutes, using multiple jobs becomes the better option. Nx Cloud's distributed task execution allows you to keep the CI pipeline fast as you scale. As the repository grows, all you need to do is add more agents. + +## Process Only Affected Projects With One Job on Circle CI + +Below is an example of an Circle CI setup that runs on a single job, building and testing only what is affected. This uses the [`nx affected` command](/nx-cloud/features/affected) to run the tasks only for the projects that were affected by that PR. ```yaml {% fileName=".circleci/config.yml" %} version: 2.1 @@ -23,7 +27,10 @@ workflows: - main ``` -`CircleCI` can track the last successful run on the `main` branch and use this as a reference point for the `BASE`. The `Nx Orb` provides a convenient implementation of this functionality which you can drop into your existing CI config. +### Get the Commit of the Last Successful Build + +`CircleCI` can track the last successful run on the `main` branch and use this as a reference point for the `BASE`. The `Nx Orb` provides a convenient implementation of this functionality which you can drop into your existing CI config. Specifically, `nx/set-shas` populates the `$NX_BASE` environment variable with the commit SHA of the last successful run. + To understand why knowing the last successful build is important for the affected command, check out the [in-depth explanation in Orb's docs](https://github.com/nrwl/nx-orb#background). ### Using CircleCI in a private repository @@ -34,15 +41,35 @@ To use the [Nx Orb](https://github.com/nrwl/nx-orb) with a private repository on It should be a user token, not the project token. {% /callout %} -## Distributed Task Execution with Nx Cloud +## Distribute Tasks Across Agents on Circle CI -Read more about [Distributed Task Execution (DTE)](/nx-cloud/features/distribute-task-execution). +To set up [Distributed Task Execution (DTE)](/nx-cloud/features/distribute-task-execution), you can run this generator: + +```shell +npx nx g ci-workflow --ci=circleci +``` + +Or you can copy and paste the workflow below: ```yaml {% fileName=".circleci/config.yml" %} version: 2.1 orbs: nx: nrwl/nx@1.5.1 jobs: + main: + docker: + - image: cimg/node:lts-browsers + steps: + - checkout + - run: npm ci + - nx/set-shas + + # Tell Nx Cloud to use DTE and stop agents when the build tasks are done + - run: npx nx-cloud start-ci-run --stop-agents-after=build + # Send logs to Nx Cloud for any CLI command + - run: npx nx-cloud record -- npx nx format:check + # Lint, test and build on agent jobs everything affected by a change + - run: npx nx affected --base=$NX_BASE --head=$NX_HEAD -t lint,test,build --parallel=2 --configuration=ci agent: docker: - image: cimg/node:lts-browsers @@ -52,20 +79,10 @@ jobs: steps: - checkout - run: npm ci + # Wait for instructions from Nx Cloud - run: command: npx nx-cloud start-agent no_output_timeout: 60m - main: - docker: - - image: cimg/node:lts-browsers - steps: - - checkout - - run: npm ci - - nx/set-shas - - run: npx nx-cloud start-ci-run --stop-agents-after="build" - - - run: npx nx-cloud record -- npx nx format:check - - run: npx nx affected --base=$NX_BASE --head=$NX_HEAD -t lint,test,build --parallel=3 --configuration=ci workflows: build: jobs: @@ -76,4 +93,12 @@ workflows: - main ``` -You can also use our [ci-workflow generator](/nx-api/workspace/generators/ci-workflow) to generate the configuration file. +This configuration is setting up two types of jobs - a main job and three agent jobs. + +The main job tells Nx Cloud to use DTE and then runs normal Nx commands as if this were a single pipeline set up. Once the commands are done, it notifies Nx Cloud to stop the agent jobs. + +The agent jobs set up the repo and then wait for Nx Cloud to assign them tasks. + +{% callout type="warning" title="Two Types of Parallelization" %} +The `ordinal: [1, 2, 3]` line and the `--parallel` flag both parallelize tasks, but in different ways. The way this workflow is written, there will be 3 agents running tasks and each agent will try to run 2 tasks at once. If a particular CI run only has 2 tasks, only one agent will be used. +{% /callout %} diff --git a/docs/shared/monorepo-ci-github-actions.md b/docs/shared/monorepo-ci-github-actions.md index 3e9f74139b9859..6603006046ded3 100644 --- a/docs/shared/monorepo-ci-github-actions.md +++ b/docs/shared/monorepo-ci-github-actions.md @@ -1,10 +1,10 @@ # Configuring CI Using GitHub Actions and Nx -There are two general approaches to setting up CI with Nx - using a single pipeline or using distributed task execution. For smaller repositories, a single pipeline is faster and cheaper, but once a full CI run starts taking 10 to 15 minutes, distributed task execution becomes the better option. Distributed task execution allows you to keep the CI pipeline fast as you scale. As the repository grows, all you need to do is add more agents. +There are two general approaches to setting up CI with Nx - using a single job or distributing tasks across multiple jobs. For smaller repositories, a single job is faster and cheaper, but once a full CI run starts taking 10 to 15 minutes, using multiple jobs becomes the better option. Nx Cloud's distributed task execution allows you to keep the CI pipeline fast as you scale. As the repository grows, all you need to do is add more agents. -## Single Pipeline +## Process Only Affected Projects With One Job on GitHub Actions -This is an example of a GitHub Actions setup that runs on a single pipeline, building and testing only what is affected. +Below is an example of an GitHub Actions setup that runs on a single job, building and testing only what is affected. This uses the [`nx affected` command](/nx-cloud/features/affected) to run the tasks only for the projects that were affected by that PR. ```yaml {% fileName=".github/workflows/ci.yml" %} name: CI @@ -36,10 +36,12 @@ jobs: - run: npx nx affected -t lint,test,build --parallel=3 ``` +### Get the Commit of the Last Successful Build + `GitHub` can track the last successful run on the `main` branch and use this as a reference point for the `BASE`. The `nrwl/nx-set-shas` provides a convenient implementation of this functionality which you can drop into your existing CI config. To understand why knowing the last successful build is important for the affected command, check out the [in-depth explanation in Actions's docs](https://github.com/marketplace/actions/nx-set-shas#background). -## Distributed Task Execution +## Distribute Tasks Across Agents on GitHub Actions To set up [Distributed Task Execution (DTE)](/nx-cloud/features/distribute-task-execution), you can run this generator: @@ -94,10 +96,10 @@ The second workflow is for the agents: The `number-of-agents` property controls how many agent jobs are created. Note that this property should be the same number for each workflow. {% callout type="warning" title="Two Types of Parallelization" %} -The `number-of-agents` property and the `--parallel` flag both parallelize tasks, but in different ways. The way this workflow is written, there will 3 agents running tasks and each agent will try to run 2 tasks at once. If a particular CI run only has 2 tasks, only one agent will be used. +The `number-of-agents` property and the `--parallel` flag both parallelize tasks, but in different ways. The way this workflow is written, there will be 3 agents running tasks and each agent will try to run 2 tasks at once. If a particular CI run only has 2 tasks, only one agent will be used. {% /callout %} -## Custom Distributed CI with Nx Cloud +## Custom Distributed CI with Nx Cloud on GitHub Actions Our [reusable GitHub workflow](https://github.com/nrwl/ci) represents a good set of defaults that works for a large number of our users. However, reusable GitHub workflows come with their [limitations](https://docs.github.com/en/actions/using-workflows/reusing-workflows). @@ -156,8 +158,8 @@ jobs: - name: Check out the default branch run: git branch --track main origin/main - - name: Initialize the Nx Cloud distributed CI run - run: npx nx-cloud start-ci-run + - name: Initialize the Nx Cloud distributed CI run and stop agents when the build tasks are done + run: npx nx-cloud start-ci-run --stop-agents-after=build - name: Run commands in parallel run: | @@ -178,11 +180,6 @@ jobs: exit 0 - - name: Stop all running agents for this CI run - # It's important that we always run this step, otherwise in the case of any failures in preceding non-Nx steps, the agents will keep running and waste billable minutes - if: ${{ always() }} - run: npx nx-cloud stop-all-agents - agents: name: Agent ${{ matrix.agent }} runs-on: ubuntu-latest diff --git a/docs/shared/monorepo-ci-gitlab.md b/docs/shared/monorepo-ci-gitlab.md index 94e7c2ea05691a..cbc0c176d6c65a 100644 --- a/docs/shared/monorepo-ci-gitlab.md +++ b/docs/shared/monorepo-ci-gitlab.md @@ -1,8 +1,12 @@ # Configuring CI Using GitLab and Nx -Below is an example of a GitLab pipeline setup for an Nx workspace - building and testing only what is affected. +There are two general approaches to setting up CI with Nx - using a single job or distributing tasks across multiple jobs. For smaller repositories, a single job is faster and cheaper, but once a full CI run starts taking 10 to 15 minutes, using multiple jobs becomes the better option. Nx Cloud's distributed task execution allows you to keep the CI pipeline fast as you scale. As the repository grows, all you need to do is add more agents. -```yaml +## Process Only Affected Projects With One Job on GitLab + +Below is an example of an GitLab setup that runs on a single job, building and testing only what is affected. This uses the [`nx affected` command](/nx-cloud/features/affected) to run the tasks only for the projects that were affected by that PR. + +```yaml {% fileName=".gitlab-ci.yml" %} image: node:18 stages: @@ -55,11 +59,17 @@ build: The `build` and `test` jobs implement the CI workflow using `.distributed` as a template to keep the CI configuration file more readable. -## Distributed Task Execution with Nx Cloud +## Distribute Tasks Across Agents on GitLab + +To set up [Distributed Task Execution (DTE)](/nx-cloud/features/distribute-task-execution), you can run this generator: + +```shell +npx nx g ci-workflow --ci=gitlab +``` -Read more about [Distributed Task Execution (DTE)](/nx-cloud/features/distribute-task-execution). +Or you can copy and paste the workflow below: -```yaml +```yaml {% fileName=".gitlab-ci.yml" %} image: node:18 # Creating template for DTE agents @@ -101,9 +111,9 @@ nx-dte: stage: affected extends: .base-pipeline script: - - yarn nx-cloud start-ci-run --stop-agents-after="build" + - yarn nx-cloud start-ci-run --stop-agents-after=build - yarn nx-cloud record -- yarn nx format:check --base=$NX_BASE --head=$NX_HEAD - - yarn nx affected --base=$NX_BASE --head=$NX_HEAD -t lint --parallel=3 & yarn nx affected --base=$NX_BASE --head=$NX_HEAD -t test --parallel=3 --configuration=ci & yarn nx affected --base=$NX_BASE --head=$NX_HEAD -t e2e --parallel=3 & yarn nx affected --base=$NX_BASE --head=$NX_HEAD -t build --parallel=3 + - yarn nx affected --base=$NX_BASE --head=$NX_HEAD -t lint,test,build --parallel=2 # Create as many agents as you want nx-dte-agent1: @@ -116,3 +126,13 @@ nx-dte-agent3: extends: .dte-agent stage: affected ``` + +This configuration is setting up two types of jobs - a main job and three agent jobs. + +The main job tells Nx Cloud to use DTE and then runs normal Nx commands as if this were a single pipeline set up. Once the commands are done, it notifies Nx Cloud to stop the agent jobs. + +The agent jobs set up the repo and then wait for Nx Cloud to assign them tasks. + +{% callout type="warning" title="Two Types of Parallelization" %} +The agents and the `--parallel` flag both parallelize tasks, but in different ways. The way this workflow is written, there will be 3 agents running tasks and each agent will try to run 2 tasks at once. If a particular CI run only has 2 tasks, only one agent will be used. +{% /callout %} diff --git a/docs/shared/monorepo-ci-jenkins.md b/docs/shared/monorepo-ci-jenkins.md index 3d08d126aa7a7c..57c8b70edfd1d4 100644 --- a/docs/shared/monorepo-ci-jenkins.md +++ b/docs/shared/monorepo-ci-jenkins.md @@ -1,10 +1,10 @@ # Configuring CI Using Jenkins and Nx -Below is an example of a Jenkins setup for an Nx workspace - building and testing only what is affected. +There are two general approaches to setting up CI with Nx - using a single job or distributing tasks across multiple jobs. For smaller repositories, a single job is faster and cheaper, but once a full CI run starts taking 10 to 15 minutes, using multiple jobs becomes the better option. Nx Cloud's distributed task execution allows you to keep the CI pipeline fast as you scale. As the repository grows, all you need to do is add more agents. -Unlike `GitHub Actions` and `CircleCI`, you don't have the metadata to help you track the last successful run on `main`. In the example below, the base is set to `HEAD~1` (for push) or branching point (for pull requests), but a more robust solution would be to tag an SHA in the main job once it succeeds and then use this tag as a base. See the [nx-tag-successful-ci-run](https://github.com/nrwl/nx-tag-successful-ci-run) and [nx-set-shas](https://github.com/nrwl/nx-set-shas) (version 1 implements tagging mechanism) repositories for more information. +## Process Only Affected Projects With One Job on Jenkins -We also have to set `NX_BRANCH` explicitly. +Below is an example of an Jenkins setup that runs on a single job, building and testing only what is affected. This uses the [`nx affected` command](/nx-cloud/features/affected) to run the tasks only for the projects that were affected by that PR. ```groovy pipeline { @@ -47,11 +47,15 @@ pipeline { } ``` -The `pr` and `main` jobs implement the CI workflow. +### Get the Commit of the Last Successful Build + +Unlike `GitHub Actions` and `CircleCI`, you don't have the metadata to help you track the last successful run on `main`. In the example below, the base is set to `HEAD~1` (for push) or branching point (for pull requests), but a more robust solution would be to tag an SHA in the main job once it succeeds and then use this tag as a base. See the [nx-tag-successful-ci-run](https://github.com/nrwl/nx-tag-successful-ci-run) and [nx-set-shas](https://github.com/nrwl/nx-set-shas) (version 1 implements tagging mechanism) repositories for more information. + +We also have to set `NX_BRANCH` explicitly. -## Distributed Task Execution with Nx Cloud +## Distribute Tasks Across Agents on Jenkins -Read more about [Distributed Task Execution (DTE)](/nx-cloud/features/distribute-task-execution). +To set up [Distributed Task Execution (DTE)](/nx-cloud/features/distribute-task-execution), you can copy and paste the workflow below: ```groovy pipeline { @@ -83,7 +87,7 @@ pipeline { sh "npm ci" sh "npx nx-cloud start-ci-run --stop-agents-after='build'" sh "npx nx format:check" - sh "npx nx affected --base origin/${env.CHANGE_TARGET} -t lint --parallel=3 & npx nx affected --base origin/${env.CHANGE_TARGET} -t test --parallel=3 --configuration=ci & npx nx affected --base origin/${env.CHANGE_TARGET} -t build --parallel=3" + sh "npx nx affected --base origin/${env.CHANGE_TARGET} -t lint --parallel=2 & npx nx affected --base origin/${env.CHANGE_TARGET} -t test --parallel=2 --configuration=ci & npx nx affected --base origin/${env.CHANGE_TARGET} -t build --parallel=2" } } @@ -114,3 +118,13 @@ pipeline { } } ``` + +This configuration is setting up two types of jobs - a main job and three agent jobs. + +The main job tells Nx Cloud to use DTE and then runs normal Nx commands as if this were a single pipeline set up. Once the commands are done, it notifies Nx Cloud to stop the agent jobs. + +The agent jobs set up the repo and then wait for Nx Cloud to assign them tasks. + +{% callout type="warning" title="Two Types of Parallelization" %} +The agents and the `--parallel` flag both parallelize tasks, but in different ways. The way this workflow is written, there will be 3 agents running tasks and each agent will try to run 2 tasks at once. If a particular CI run only has 2 tasks, only one agent will be used. +{% /callout %} diff --git a/docs/shared/node-server-tutorial/affected-project-graph.json b/docs/shared/node-server-tutorial/affected-project-graph.json index ff386c023f127a..e419354106aa48 100644 --- a/docs/shared/node-server-tutorial/affected-project-graph.json +++ b/docs/shared/node-server-tutorial/affected-project-graph.json @@ -76,7 +76,6 @@ "inputs": ["default", "{workspaceRoot}/.eslintrc.json"], "executor": "@nrwl/linter:eslint", "outputs": ["{options.outputFile}"], - "options": { "lintFilePatterns": ["auth/**/*.ts"] }, "configurations": {} }, "test": { @@ -155,7 +154,6 @@ "inputs": ["default", "{workspaceRoot}/.eslintrc.json"], "executor": "@nrwl/linter:eslint", "outputs": ["{options.outputFile}"], - "options": { "lintFilePatterns": ["e2e/**/*.{js,ts}"] }, "configurations": {} } } @@ -324,7 +322,7 @@ "inputs": ["default", "{workspaceRoot}/.eslintrc.json"], "executor": "@nrwl/linter:eslint", "outputs": ["{options.outputFile}"], - "options": { "lintFilePatterns": ["./**/*.ts"] }, + "options": { "lintFilePatterns": ["./src"] }, "configurations": {} } } diff --git a/docs/shared/node-server-tutorial/final-project-graph.json b/docs/shared/node-server-tutorial/final-project-graph.json index 2ac5635fe10912..97969525b72d61 100644 --- a/docs/shared/node-server-tutorial/final-project-graph.json +++ b/docs/shared/node-server-tutorial/final-project-graph.json @@ -58,7 +58,6 @@ "inputs": ["default", "{workspaceRoot}/.eslintrc.json"], "executor": "@nrwl/linter:eslint", "outputs": ["{options.outputFile}"], - "options": { "lintFilePatterns": ["auth/**/*.ts"] }, "configurations": {} }, "test": { @@ -137,7 +136,6 @@ "inputs": ["default", "{workspaceRoot}/.eslintrc.json"], "executor": "@nrwl/linter:eslint", "outputs": ["{options.outputFile}"], - "options": { "lintFilePatterns": ["e2e/**/*.{js,ts}"] }, "configurations": {} } } diff --git a/docs/shared/node-server-tutorial/initial-project-graph.json b/docs/shared/node-server-tutorial/initial-project-graph.json index b2df6ea1d4fe1b..0282c1fd241e3a 100644 --- a/docs/shared/node-server-tutorial/initial-project-graph.json +++ b/docs/shared/node-server-tutorial/initial-project-graph.json @@ -58,7 +58,7 @@ "inputs": ["default", "{workspaceRoot}/.eslintrc.json"], "executor": "@nrwl/linter:eslint", "outputs": ["{options.outputFile}"], - "options": { "lintFilePatterns": ["auth/**/*.ts"] }, + "configurations": {} }, "test": { @@ -137,7 +137,6 @@ "inputs": ["default", "{workspaceRoot}/.eslintrc.json"], "executor": "@nrwl/linter:eslint", "outputs": ["{options.outputFile}"], - "options": { "lintFilePatterns": ["e2e/**/*.{js,ts}"] }, "configurations": {} } } @@ -305,7 +304,7 @@ "inputs": ["default", "{workspaceRoot}/.eslintrc.json"], "executor": "@nrwl/linter:eslint", "outputs": ["{options.outputFile}"], - "options": { "lintFilePatterns": ["./**/*.ts"] }, + "options": { "lintFilePatterns": ["./src"] }, "configurations": {} } } diff --git a/docs/shared/packages/angular/angular-nx-version-matrix.md b/docs/shared/packages/angular/angular-nx-version-matrix.md index 569a1b7911d6fd..60215afd1d163f 100644 --- a/docs/shared/packages/angular/angular-nx-version-matrix.md +++ b/docs/shared/packages/angular/angular-nx-version-matrix.md @@ -12,22 +12,23 @@ Below is a reference table that matches versions of Angular to the version of Nx We provide a recommended version, and it is usually the latest minor version of Nx in the range provided because there will have been bug fixes added since the first release in the range. -| Angular Version | **Nx Version _(recommended)_** | Nx Version _(range)_ | -| --------------- | ------------------------------ | --------------------------------------- | -| ~16.2.0 | **latest** | 16.7.0 <= latest | -| ~16.1.0 | **latest** | 16.4.0 <= latest | -| ~16.0.0 | **latest** | 16.1.0 <= latest | -| ~15.2.0 | **latest** | 15.8.0 <= latest | -| ~15.1.0 | **latest** | 15.5.0 <= latest | -| ~15.0.0 | **latest** | 15.2.0 <= 15.4.8 \|\| 15.7.0 <= latest | -| ~14.2.0 | **latest** | 14.6.0 <= 15.1.1 \|\| 15.7.0 <= latest | -| ~14.1.0 | **latest** | 14.5.0 <= 14.5.10 \|\| 15.7.0 <= latest | -| ~14.0.0 | **latest** | 14.2.1 <= 14.4.3 \|\| 15.7.0 <= latest | -| ^13.0.0 | **14.1.9** | 13.2.0 <= 14.1.9 | -| ^12.0.0 | **13.1.4** | 12.3.0 <= 13.1.4 | -| ^11.0.0 | **12.2.0** | 11.0.0 <= 12.2.0 | -| ^10.0.0 | **10.4.15** | 9.7.0 <= 10.4.15 | -| ^9.0.0 | **9.6.0** | 8.12.4 <= 9.6.0 | -| ^8.0.0 | **8.12.2** | 8.7.0 <= 8.12.2 | +| Angular Version | **Nx Version _(recommended)_** | Nx Version _(range)_ | +| --------------- | ------------------------------ | -------------------------------------- | +| ~17.0.0 | **latest** | 17.1.0 <= latest | +| ~16.2.0 | **latest** | 16.7.0 <= latest | +| ~16.1.0 | **latest** | 16.4.0 <= latest | +| ~16.0.0 | **latest** | 16.1.0 <= latest | +| ~15.2.0 | **latest** | 15.8.0 <= latest | +| ~15.1.0 | **latest** | 15.5.0 <= latest | +| ~15.0.0 | **latest** | 15.2.0 <= 15.4.8 \|\| 15.7.0 <= latest | +| ~14.2.0 | **~17.0.0** | 14.6.0 <= 15.1.1 \|\| 15.7.0 < 17.1.0 | +| ~14.1.0 | **~17.0.0** | 14.5.0 <= 14.5.10 \|\| 15.7.0 < 17.1.0 | +| ~14.0.0 | **~17.0.0** | 14.2.1 <= 14.4.3 \|\| 15.7.0 < 17.1.0 | +| ^13.0.0 | **14.1.9** | 13.2.0 <= 14.1.9 | +| ^12.0.0 | **13.1.4** | 12.3.0 <= 13.1.4 | +| ^11.0.0 | **12.2.0** | 11.0.0 <= 12.2.0 | +| ^10.0.0 | **10.4.15** | 9.7.0 <= 10.4.15 | +| ^9.0.0 | **9.6.0** | 8.12.4 <= 9.6.0 | +| ^8.0.0 | **8.12.2** | 8.7.0 <= 8.12.2 | Additionally, you can check the supported versions of Node and Typescript for the version of Angular you are using in the [Angular docs](https://angular.io/guide/versions#actively-supported-versions). diff --git a/docs/shared/packages/next/next-config-setup.md b/docs/shared/packages/next/next-config-setup.md index e7ccfc46f8c7fb..d6b4511c45e88b 100644 --- a/docs/shared/packages/next/next-config-setup.md +++ b/docs/shared/packages/next/next-config-setup.md @@ -125,7 +125,8 @@ module.exports = async (phase, context) => { // If you have plugins that has to be added after Nx you can do that here. // For example, Sentry needs to be added last. - updatedConfig = require('@sentry/nextjs')(updatedConfig, { silent: true }); + const { withSentryConfig } = require('@sentry/nextjs'); + updatedConfig = withSentryConfig(updatedConfig); return updatedConfig; }; diff --git a/docs/shared/packages/vite/vite-plugin.md b/docs/shared/packages/vite/vite-plugin.md index 5d1ae8f9548a1b..035fc88681f544 100644 --- a/docs/shared/packages/vite/vite-plugin.md +++ b/docs/shared/packages/vite/vite-plugin.md @@ -18,15 +18,7 @@ Read more about Vite and Vitest in the [Vite documentation](https://vitejs.dev/) ## Setting up a new Nx workspace with Vite -You can create a new workspace that uses Vite with one of the following commands: - -- Generate a new monorepo with a Web Components app set up with Vite - -```shell -npx create-nx-workspace@latest --preset=web-components -``` - -- Generate a new standalone React app set up with Vite +Here's an example on how to create a new React app with Vite ```shell npx create-nx-workspace@latest --preset=react-standalone --bundler=vite @@ -64,7 +56,7 @@ You can use the `@nx/vite:configuration` generator to change your React or Web p You can read more about this generator on the [`@nx/vite:configuration`](/nx-api/vite/generators/configuration) generator page. -### Initialize Vite.js +### 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. @@ -100,7 +92,7 @@ pnpm install -D @nx/vite #### Ask Nx to install the necessary dependencies -After you install the plugin, you can initialize Vite.js. You can do this by running the `init` executor. This executor will make sure to install all 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 diff --git a/docs/shared/react-tutorial/react-monorepo.md b/docs/shared/react-tutorial/react-monorepo.md index eef38c8a2a3ecc..e44e11575379b5 100644 --- a/docs/shared/react-tutorial/react-monorepo.md +++ b/docs/shared/react-tutorial/react-monorepo.md @@ -997,7 +997,7 @@ Learn more about how to [enforce module boundaries](/core-features/enforce-modul ## Setting Up CI -Without adequate tooling, CI times tend to grow exponentially with the size of the codebase. Nx helps decrease the average CI time with the [`affected` command](/nx-cloud/features/affected) and Nx Cloud's [distributed caching](/nx-cloud/features/remote-cache). Nx also [decreases the worst case CI time](/concepts/dte) with Nx Cloud's distributed task execution. +Without adequate tooling, CI times tend to grow exponentially with the size of the codebase. Nx helps decrease the average CI time with the [`affected` command](/nx-cloud/features/affected) and Nx Cloud's [distributed caching](/nx-cloud/features/remote-cache). Nx also [decreases the worst case CI time](/nx-cloud/concepts/dte) with Nx Cloud's distributed task execution. To set up Nx Cloud run: diff --git a/docs/shared/recipes/add-stack/add-svelte.md b/docs/shared/recipes/add-stack/add-svelte.md index 4c45ca62102f7f..9da0af4270471e 100644 --- a/docs/shared/recipes/add-stack/add-svelte.md +++ b/docs/shared/recipes/add-stack/add-svelte.md @@ -28,21 +28,21 @@ Because we are not using a Nx plugin for Svelte, there are a few items we'll hav {%tab label="npm"%} ```shell -npx create-nx-workspace@latest workspace --preset=react-monorepo --style=css --bundler=vite --nx-cloud=true --appName=acme +npx create-nx-workspace@latest acme --preset=ts-standalone --nx-cloud=true ``` {% /tab %} {%tab label="yarn"%} ```shell -npx create-nx-workspace@latest workspace --preset=react-monorepo --style=css --bundler=vite --nx-cloud=true --appName=acme --pm yarn +npx create-nx-workspace@latest acme --preset=ts-standalone --nx-cloud=true --pm yarn ``` {% /tab %} {%tab label="pnpm"%} ```shell -npx create-nx-workspace@latest workspace --preset=react-monorepo --style=css --bundler=vite --nx-cloud=true --appName=acme --pm pnpm +npx create-nx-workspace@latest acme --preset=ts-standalone --nx-cloud=true --pm pnpm ``` {% /tab %} @@ -80,13 +80,7 @@ pnpm add --save-dev @nx/vite @nx/js vitest vite svelte svelte-check @sveltejs/vi ## Create the application -Before we start to create our application, let's remove the React application that was created for us. - -```shell -rm -rf apps/acme/src/app/* -``` - -Update your `apps/acme/src/index.html` to the following: +Create your `index.html` at the root with the following: ```html @@ -103,10 +97,10 @@ Update your `apps/acme/src/index.html` to the following: ``` -Navigate to `apps/acme/src/main.tsx` and change it to `apps/acme/src/main.ts` and add the following content: +Navigate to `src/index.ts` and change it to `src/main.ts` and add the following content: ```ts -import App from './app/App.svelte'; +import App from './App.svelte'; const app = new App({ target: document.getElementById('app'), @@ -115,25 +109,45 @@ const app = new App({ export default app; ``` -Create a new file `apps/acme/src/app/App.svelte` and add the following content: +Create a new file `src/App.svelte` and add the following content: -```ts +```ts {% fileName="src/App.svelte" %} + let count: number = 0; + const increment = () => { + count += 1; + }; + + + +``` + +Since we have a `.svelte` file, we'll need to tell typescript how to handle it. Create a new file `src/svelte-shims.d.ts` and add the following content: - +```ts {% fileName="src/svelte-shims.d.ts" %} +declare module '*.svelte' { + import type { ComponentType } from 'svelte'; + const component: ComponentType; + export default component; +} +``` + +Alternatively, you could also extend the `tsconfig.json` file to use tsconfig/svelte. +```json {% fileName="tsconfig.json" %} +{ + "extends": "@tsconfig/svelte/tsconfig.json" + //... other configs +} ``` +See more here: [Svelte TypeScript](https://www.npmjs.com/package/@tsconfig/svelte) + ## Configure Nx to build and serve the application -Navigate to `vite.config.ts` update the file name to `vite.config.mts` and add the following content: +Navigate to `vite.config.ts` add `svelte` to your plugins. ```ts // Add this to your imports @@ -141,10 +155,10 @@ import { svelte } from '@sveltejs/vite-plugin-svelte'; export default defineConfig({ plugins: [ - //... - svelte(), + //... other plugins + svelte(), // Add this line ], - + //... server: { port: 4200, host: 'localhost', @@ -152,42 +166,24 @@ export default defineConfig({ }); ``` -{%callout type="Note" title="Why use the .mts file extension?" %} -We change `vite.config.ts` to `vite.config.mts` because `'@sveltejs/vite-plugin-svelte'` is an ESM only package. As a result, we need to use the `.mts` extension to tell Nx to use the ESM loader. See more here: [ESM Package](https://vitejs.dev/guide/troubleshooting.html#this-package-is-esm-only) -{% /callout %} +Change your `tsconfig.lib.json` to `tsconfig.app.json`. It should look like this: -Update your `tsconfig.app.json` with the following content: - -```json {% fileName="/apps/acme/tsconfig.app.json" %} +```json {% fileName="/tsconfig.app.json" %} { "extends": "./tsconfig.json", "compilerOptions": { - "moduleResolution": "node", - "target": "esnext", - "ignoreDeprecations": "5.0", - "isolatedModules": true, - "sourceMap": true, - "types": ["svelte", "node", "vite/client"], - "strict": false, - "esModuleInterop": true, - "skipLibCheck": true, - "forceConsistentCasingInFileNames": true, - "checkJs": true + "outDir": "./dist/out-tsc", + "declaration": true, + "types": ["node"] }, - "include": [ - "src/**/*.d.ts", - "src/**/*.ts", - "src/**/*.js", - "src/**/*.svelte", - "vite.config.mts" - ], + "include": ["src/**/*.ts", "src/**/*.svelte"], "exclude": ["jest.config.ts", "src/**/*.spec.ts", "src/**/*.test.ts"] } ``` Navigate to `project.json` and update it with the following content: -```json {% fileName="/apps/acme/project.json" %} +```json {% fileName="/project.json" %} { "targets": { "build": { @@ -195,7 +191,7 @@ Navigate to `project.json` and update it with the following content: "outputs": ["{options.outputPath}"], "defaultConfiguration": "production", "options": { - "outputPath": "dist/apps/acme" + "outputPath": "dist/acme" }, "configurations": { "development": { @@ -259,7 +255,7 @@ Test it out nx build acme ``` -Your build artifacts should be in `dist/apps/acme` +Your build artifacts should be in `dist/acme` **Serve the application** @@ -281,7 +277,7 @@ The command below uses the `as-provided` directory flag behavior, which is the d nx generate @nx/js:library --name=Counter --directory=libs/counter --unitTestRunner=vitest --bundler=vite --importPath=@acme/counter ``` -Create the Counter component at `libs/counter/src/lib/Counter.svelte` and copy the contents of your `apps/acme/src/App.svelte` file into it. +Create the Counter component at `libs/counter/src/lib/Counter.svelte` and copy the contents of your `src/App.svelte` file into it. Update your `libs/counter/src/lib/index.ts` to export your Counter component. @@ -293,7 +289,7 @@ export { default as Counter } from './Counter.svelte'; The `default` is import here as due to the aliasing we'll be doing later, we'll need to import the Counter component as `import { Counter } from '@acme/counter'`. {% /callout %} -Update your project's `/apps/acme/vite.config.mts` to include the following: +Update your project's `vite.config.ts` to include the following: ```ts export default defineConfig({ @@ -310,7 +306,7 @@ export default defineConfig({ This allows the runtime to resolve the `@acme/counter` import to the correct location. -Finally update your `apps/acme/src/App.svelte` to use the counter component. +Finally update your `src/App.svelte` to use the counter component. ```ts