From eec00147fffce9f9ef468649adaf3490792bbcc4 Mon Sep 17 00:00:00 2001 From: Jack Hsu Date: Thu, 19 Sep 2024 13:11:02 -0400 Subject: [PATCH] fix(core): link to sync generators page during sync prompt, and provide more info on docs page for disabling and applyChanges (#28001) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This PR expands the concept page for sync generators to show config examples for `applyChanges` and `disableTaskSyncGenerators`. It also adds a link when during the sync prompt for users to read more about it. Screenshot 2024-09-19 at 12 00 14 PM Preview: https://nx-dev-git-feat-sync-docs-and-links-nrwl.vercel.app/concepts/sync-generators ## Current Behavior ## Expected Behavior ## Related Issue(s) Fixes # --- docs/shared/concepts/sync-generators.md | 72 ++++++++++++++++++- .../lib/tags/project-details.component.tsx | 3 +- packages/nx/src/tasks-runner/run-command.ts | 4 +- 3 files changed, 75 insertions(+), 4 deletions(-) diff --git a/docs/shared/concepts/sync-generators.md b/docs/shared/concepts/sync-generators.md index 32ffcd0114e8b..803cc336aeca4 100644 --- a/docs/shared/concepts/sync-generators.md +++ b/docs/shared/concepts/sync-generators.md @@ -15,7 +15,77 @@ Nx does this in different ways, depending on whether the task is being run on a On a developer machine, the sync generator is run in `--dry-run` mode and if files would be changed by the generator, the user is prompted to run the generator or skip it. This prompt can be disabled by setting the `sync.applyChanges` property to `true` or `false` in the `nx.json` file. -In CI, the sync generator is run in `--dry-run` mode and if files would be changed by the generator, the task fails with an error provided by the sync generator. The sync generator can be skipped in CI by passing the `--skip-sync` flag when executing the task or you can skip an individual sync generator by adding that generator to the `sync.disabledTaskSyncGenerators` in `nx.json`. +```json {% fileName="nx.json" highlightLines=["4-6"] %} +{ + "$schema": "packages/nx/schemas/nx-schema.json", + ... + "sync": { + "applyChanges": true + } +} +``` + +{% callout type="warning" title="Opting out of automatic sync" %} +If you set `sync.applyChanges` to `false`, then developers must run `nx sync` manually before pushing changes. Otherwise, CI may fail due to the workspace being out of sync. +{% /callout %} + +In CI, the sync generator is run in `--dry-run` mode and if files would be changed by the generator, the task fails with an error provided by the sync generator. The sync generator can be skipped in CI by passing the `--skip-sync` flag when executing the task, or you can skip an individual sync generator by adding that generator to the `sync.disabledTaskSyncGenerators` in `nx.json`. + +```json {% fileName="nx.json" highlightLines=["4-6"] %} +{ + "$schema": "packages/nx/schemas/nx-schema.json", + ... + "sync": { + "disabledTaskSyncGenerators": ["@nx/js:typescript-sync"] + } +} + +``` + +Use the project details view to **find registered sync generators** for a given task. + +```shell +nx show project +``` + +The above command opens up the project details view, and the registered sync generators are under the **Sync Generators** for each target. Most sync generators are inferred when using an [inference plugin](/concepts/inferred-tasks). For example, the `@nx/js/typescript` plugin registers the `@nx/js:typescript-sync` generator on `build` and `typecheck` targets. + +{% project-details title="Project Details View" expandedTargets="build" %} + +```json +{ + "project": { + "name": "foo", + "data": { + "root": " packages/foo", + "projectType": "library", + "targets": { + "build": { + "dependsOn": ["^build"], + "cache": true, + "inputs": [ + "{workspaceRoot}/tsconfig.base.json", + "{projectRoot}/tsconfig.lib.json", + "{projectRoot}/src/**/*.ts" + ], + "outputs": ["{workspaceRoot}/packages/foo/dist"], + "syncGenerators": ["@nx/js:typescript-sync"], + "executor": "nx:run-commands", + "options": { + "command": "tsc --build tsconfig.lib.json --pretty --verbose" + } + } + } + } + }, + "sourceMap": { + "targets": ["packages/foo/tsconfig.ts", "@nx/js/typescript"], + "targets.build": ["packages/foo/tsconfig.ts", "@nx/js/typescript"] + } +} +``` + +{% /project-details %} Task sync generators can be thought of like the `dependsOn` property, but for generators instead of task dependencies. diff --git a/nx-dev/ui-markdoc/src/lib/tags/project-details.component.tsx b/nx-dev/ui-markdoc/src/lib/tags/project-details.component.tsx index 796b606b88b8b..e50106dde1ac9 100644 --- a/nx-dev/ui-markdoc/src/lib/tags/project-details.component.tsx +++ b/nx-dev/ui-markdoc/src/lib/tags/project-details.component.tsx @@ -9,6 +9,7 @@ import { } from 'react'; import { ProjectDetails as ProjectDetailsUi } from '@nx/graph-internal/ui-project-details'; import { ExpandedTargetsProvider } from '@nx/graph/shared'; +import { twMerge } from 'tailwind-merge'; export function Loading() { return ( @@ -110,7 +111,7 @@ export function ProjectDetails({ )}
diff --git a/packages/nx/src/tasks-runner/run-command.ts b/packages/nx/src/tasks-runner/run-command.ts index 2447b189bb10e..a09ceaeffbc71 100644 --- a/packages/nx/src/tasks-runner/run-command.ts +++ b/packages/nx/src/tasks-runner/run-command.ts @@ -491,7 +491,7 @@ async function promptForApplyingSyncGeneratorChanges(): Promise { name: 'applyChanges', type: 'select', message: - 'Would you like to sync the identified changes to get your worskpace up to date?', + 'Would you like to sync the identified changes to get your workspace up to date?', choices: [ { name: 'yes', @@ -504,7 +504,7 @@ async function promptForApplyingSyncGeneratorChanges(): Promise { ], footer: () => chalk.dim( - '\nYou can skip this prompt by setting the `sync.applyChanges` option in your `nx.json`.' + '\nYou can skip this prompt by setting the `sync.applyChanges` option to `true` in your `nx.json`.\nFor more information, refer to the docs: https://nx.dev/concepts/sync-generators.' ), };