docs(core): add troubelshooting guide for convert-to-inferred migrations (#26630)

<!-- Please make sure you have read the submission guidelines before
posting an PR -->
<!--
https://github.com/nrwl/nx/blob/master/CONTRIBUTING.md#-submitting-a-pr
-->

<!-- Please make sure that your commit message follows our format -->
<!-- Example: `fix(nx): must begin with lowercase` -->

<!-- If this is a particularly complex change or feature addition, you
can request a dedicated Nx release for this pull request branch. Mention
someone from the Nx team or the `@nrwl/nx-pipelines-reviewers` and they
will confirm if the PR warrants its own release for testing purposes,
and generate it for you if appropriate. -->

## Current Behavior
<!-- This is the behavior we have today -->

## Expected Behavior
<!-- This is the behavior we should expect with the changes in this PR
-->

## Related Issue(s)
<!-- Please link the issue being fixed so it gets closed when this is
merged. -->

Fixes #

docs/generated/manifests/menus.json

@@ -3588,7 +3588,7 @@
         "disableCollapsible": false
       },
       {
-        "name": "Troubleshooting Nx Console Issues",
+        "name": "Troubleshoot Nx Console Issues",
         "path": "/recipes/nx-console/console-troubleshooting",
         "id": "console-troubleshooting",
         "isExternal": false,
@@ -4458,7 +4458,7 @@
             "disableCollapsible": false
           },
           {
-            "name": "Troubleshooting Nx Install Issues",
+            "name": "Troubleshoot Nx Install Issues",
             "path": "/troubleshooting/troubleshoot-nx-install-issues",
             "id": "troubleshoot-nx-install-issues",
             "isExternal": false,
@@ -4490,12 +4490,20 @@
             "disableCollapsible": false
           },
           {
-            "name": "Troubleshooting Nx Console Issues",
+            "name": "Troubleshoot Nx Console Issues",
             "path": "/recipes/nx-console/console-troubleshooting",
             "id": "console-troubleshooting",
             "isExternal": false,
             "children": [],
             "disableCollapsible": false
+          },
+          {
+            "name": "Troubleshoot Convert to Inferred Migration",
+            "path": "/troubleshooting/convert-to-inferred",
+            "id": "convert-to-inferred",
+            "isExternal": false,
+            "children": [],
+            "disableCollapsible": false
           }
         ],
         "disableCollapsible": false
@@ -4509,7 +4517,7 @@
         "disableCollapsible": false
       },
       {
-        "name": "Troubleshooting Nx Install Issues",
+        "name": "Troubleshoot Nx Install Issues",
         "path": "/troubleshooting/troubleshoot-nx-install-issues",
         "id": "troubleshoot-nx-install-issues",
         "isExternal": false,
@@ -4540,6 +4548,14 @@
         "children": [],
         "disableCollapsible": false
       },
+      {
+        "name": "Troubleshoot Convert to Inferred Migration",
+        "path": "/troubleshooting/convert-to-inferred",
+        "id": "convert-to-inferred",
+        "isExternal": false,
+        "children": [],
+        "disableCollapsible": false
+      },
       {
         "name": "Deprecated",
         "path": "/deprecated",

docs/generated/manifests/nx.json

@@ -4912,7 +4912,7 @@
   },
   "/recipes/nx-console/console-troubleshooting": {
     "id": "console-troubleshooting",
-    "name": "Troubleshooting Nx Console Issues",
+    "name": "Troubleshoot Nx Console Issues",
     "description": "",
     "mediaImage": "",
     "file": "shared/recipes/console-troubleshooting",
@@ -6104,7 +6104,7 @@
       },
       {
         "id": "troubleshoot-nx-install-issues",
-        "name": "Troubleshooting Nx Install Issues",
+        "name": "Troubleshoot Nx Install Issues",
         "description": "",
         "mediaImage": "",
         "file": "shared/installation/troubleshoot-installation",
@@ -6148,7 +6148,7 @@
       },
       {
         "id": "console-troubleshooting",
-        "name": "Troubleshooting Nx Console Issues",
+        "name": "Troubleshoot Nx Console Issues",
         "description": "",
         "mediaImage": "",
         "file": "shared/recipes/console-troubleshooting",
@@ -6156,6 +6156,17 @@
         "isExternal": false,
         "path": "/recipes/nx-console/console-troubleshooting",
         "tags": []
+      },
+      {
+        "id": "convert-to-inferred",
+        "name": "Troubleshoot Convert to Inferred Migration",
+        "description": "",
+        "mediaImage": "",
+        "file": "shared/guides/troubleshoot-convert-to-inferred",
+        "itemList": [],
+        "isExternal": false,
+        "path": "/troubleshooting/convert-to-inferred",
+        "tags": []
       }
     ],
     "isExternal": false,
@@ -6175,7 +6186,7 @@
   },
   "/troubleshooting/troubleshoot-nx-install-issues": {
     "id": "troubleshoot-nx-install-issues",
-    "name": "Troubleshooting Nx Install Issues",
+    "name": "Troubleshoot Nx Install Issues",
     "description": "",
     "mediaImage": "",
     "file": "shared/installation/troubleshoot-installation",
@@ -6217,6 +6228,17 @@
     "path": "/troubleshooting/performance-profiling",
     "tags": ["environment-variables"]
   },
+  "/troubleshooting/convert-to-inferred": {
+    "id": "convert-to-inferred",
+    "name": "Troubleshoot Convert to Inferred Migration",
+    "description": "",
+    "mediaImage": "",
+    "file": "shared/guides/troubleshoot-convert-to-inferred",
+    "itemList": [],
+    "isExternal": false,
+    "path": "/troubleshooting/convert-to-inferred",
+    "tags": []
+  },
   "/deprecated": {
     "id": "deprecated",
     "name": "Deprecated",

docs/map.json

@@ -1264,7 +1264,7 @@
               "file": "shared/recipes/resolve-circular-dependencies"
             },
             {
-              "name": "Troubleshooting Nx Install Issues",
+              "name": "Troubleshoot Nx Install Issues",
               "id": "troubleshoot-nx-install-issues",
               "file": "shared/installation/troubleshoot-installation"
             },
@@ -1287,10 +1287,16 @@
               "file": "shared/guides/performance-profiling"
             },
             {
-              "name": "Troubleshooting Nx Console Issues",
+              "name": "Troubleshoot Nx Console Issues",
               "id": "console-troubleshooting",
               "path": "/recipes/nx-console/console-troubleshooting",
               "file": "shared/recipes/console-troubleshooting"
+            },
+            {
+              "name": "Troubleshoot Convert to Inferred Migration",
+              "id": "convert-to-inferred",
+              "tags": [],
+              "file": "shared/guides/troubleshoot-convert-to-inferred"
             }
           ]
         },

docs/shared/guides/troubleshoot-convert-to-inferred.md

@@ -0,0 +1,141 @@
+# Troubleshoot Convert to Inferred Migration
+
+Nx comes with plugins that automatically [infer tasks](/concepts/inferred-tasks) (i.e. Project Crystal) for your projects based on the configuration of different tools. Inference plugins come with many benefits, such as reduced boilerplate and access to features such as [task splitting](/ci/features/split-e2e-tasks). To make the transition easier for existing projects that are not yet using inference plugins, many plugins provide the `convert-to-inferred` generator that will switch from executor-based tasks to inferred tasks.
+
+To see a list of the available migration generators, run:
+
+```shell
+nx g convert-to-inferred
+```
+
+This will prompt you to choose a plugin to run the migration for.
+
+Although the `convert-to-inferred` generator should work for most projects, there are situations that require additional changes to be done by hand. If you run into issues that are not covered on this page, please open an issue on [GitHub](https://github.com/nrwl/nx/issues).
+
+## Error: The nx plugin did not find a project inside...
+
+This error occurs when a configuration file matching the tooling cannot be found. For example, Vite works with `vite.config.ts` (or `.js`, `.cts`, `.mts`, etc.). If you've named your configuration file to something unconventional, you must rename it back to the standard naming convention before running the migration generator again.
+
+For example, if you have a `apps/demo/vite.custom.ts` file and are running `nx g @nx/vite:convert-to-inferred`, you must first rename the file to `apps/demo/vite.config.ts` before running the generator.
+
+## Remix: Unsupported `outputPath` Option
+
+The [`outputPath`](/nx-api/remix/executors/build#outputpath) option from `@nx/remix:build` is ignored because it often leads to ESM errors when the output path is outside the project root. The ESM error occurs because the root `package.json` may not have `"type": "module"` set, which means that the compiled ESM code will fail to run. To guarantee that `serve` works, we migrate the outputs to the Remix defaults (`build` and `public/build` inside the project root). If you have custom directories already defined in your Remix config, it will continue to be used.
+
+To change the outputs after the migration, edit the remix config file, and look for `serverBuildPath` and `assetsBuildDirectory` and set it to the locations you want.
+
+```ts
+// ...
+export default {
+  assetsBuildDirectory: '../../dist/apps/demo/public/build',
+  serverBuildPath: '../../dist/apps/demo/build/index.js',
+  // ...
+};
+```
+
+Note that you will need to address potential ESM issues that may arise. For example, change the root `package.json` to `"type": "module"`.
+
+## Remix: Unsupported `generatePackageJson` and `generateLockFile` Options
+
+The `generatePackageJson` and `generateLockFile` options in [`@nx/remix:build`](/nx-api/remix/executors/build) cannot currently be migrated. There is support for this feature in the [Nx Vite plugin](/recipes/vite/configure-vite#typescript-paths), so in the future we may be able to support it if using Remix+Vite.
+
+## Storybook: Conflicting `staticDir` Options
+
+Using `staticDir` for both `@nx/storybook:build-storybook` and `@nx/storybook:storybook` executor options will result in the one from `build-storybook` being used in the resulting `.storybook/main.ts` file. It is not possible for us to support both automatically.
+
+If you need to differentiate `staticDir` between build and serve, then consider putting logic into your `main.ts` file directly.
+
+```ts
+// ...
+const config: StorybookConfig = {
+  // ...
+  staticDirs:
+    process.env.NODE_ENV === 'production'
+      ? ['../static-prod']
+      : ['../static-dev'],
+};
+
+export default config;
+```
+
+## Vite: Unsupported `proxyConfig` Option
+
+Projects that used the [`proxyConfig`](/nx-api/vite/executors/dev-server#proxyconfig) option of `@nx/vite:dev-server` will need to inline the proxy configuration from the original file into `vite.config.ts`.
+
+For example, if you previously used this in `proxy.config.json`:
+
+```json
+{
+  "/api/*": {
+    "target": "http://localhost:3333"
+  }
+}
+```
+
+Then, you will need to add this entry to your `vite.config.ts` file:
+
+```ts
+export default defineConfig({
+  //...
+  server: {
+    // ...
+    proxy: {
+      '/api': {
+        target: 'http://localhost:3333',
+      },
+    },
+  },
+});
+```
+
+## Webpack: Project Cannot Be Migrated
+
+Projects that use [Nx-enhanced Webpack configuration](/recipes/webpack/webpack-config-setup#nxenhanced-configuration-with-composable-plugins) files cannot be migrated to use Webpack CLI. Nx-enhanced configuration files that contain `composePlugins` and `withNx` require the `@nx/webpack:webpack` executor to work.
+
+To solve this issue, run `nx g @nx/webpack:convert-config-to-webpack-plugin` first, and then try again.
+
+## Webpack: Usage of `useLegacyNxPlugin`
+
+When converting from Nx-enhanced to basic Webpack configuration, we add the `useLegacyNxPlugin` utility to ensure that the functionality of your existing configuration continues to function normally. We recommend that you refactor the configuration such that `useLegacyNxPlugin` is not needed.
+
+For example, if you previously added plugins using the configuration function.
+
+```js
+// webpack.config.old.js
+modules.exports = (config) => {
+  config.plugins.push(new SomePlugin());
+  return config;
+};
+```
+
+Then, we recommend that you move the plugin entry to the new configuration file, in the `plugins` option.
+
+```js
+module.exports = async () => ({
+  devServer: devServerOptions,
+  plugins: [new NxAppWebpackPlugin(pluginOptions), new SomePlugin()],
+});
+```
+
+If you need to apply configuration changes after `NxAppWebpackPlugin` is applied, then you can create a plugin object as follows.
+
+```js
+module.exports = async () => ({
+  devServer: devServerOptions,
+  plugins: [
+    new NxAppWebpackPlugin(pluginOptions),
+    {
+      apply(compiler) {
+        const babelLoader = compiler.options.module.rules.find(
+          (rule) =>
+            rule &&
+            typeof rule !== 'string' &&
+            rule.loader?.toString().includes('babel-loader')
+        );
+
+        // do something with `babelLoader...
+      },
+    },
+  ],
+});
+```

docs/shared/recipes/console-troubleshooting.md

@@ -1,4 +1,4 @@
-# Nx Console Troubleshooting
+# Troubleshoot Nx Console Issues
 
 Often, issues with Nx Console are the result of underlying issues with Nx. Make sure to read the [Nx installation troubleshooting docs](/troubleshooting/troubleshoot-nx-install-issues) for more help.
 

docs/shared/reference/sitemap.md

@@ -166,7 +166,7 @@
       - [Publish a Custom Dist Directory](/recipes/nx-release/publish-custom-dist-directory)
     - [Other](/recipes/other)
       - [Rescope Packages from @nrwl to @nx](/recipes/other/rescope)
-      - [Troubleshooting Nx Console Issues](/recipes/nx-console/console-troubleshooting)
+      - [Troubleshoot Nx Console Issues](/recipes/nx-console/console-troubleshooting)
   - [Showcase](/showcase)
     - [Nx with your favorite tech](/showcase/example-repos)
       - [Express](/showcase/example-repos/add-express)
@@ -199,10 +199,11 @@
     - [Releases](/reference/releases)
   - [Troubleshooting](/troubleshooting)
     - [Resolve Circular Dependencies](/troubleshooting/resolve-circular-dependencies)
-    - [Troubleshooting Nx Install Issues](/troubleshooting/troubleshoot-nx-install-issues)
+    - [Troubleshoot Nx Install Issues](/troubleshooting/troubleshoot-nx-install-issues)
     - [Troubleshoot Cache Misses](/troubleshooting/troubleshoot-cache-misses)
     - [Unknown Local Cache Error](/troubleshooting/unknown-local-cache)
     - [Profiling Build Performance](/troubleshooting/performance-profiling)
+    - [Troubleshoot Convert to Inferred Migration](/troubleshooting/convert-to-inferred)
   - [Deprecated](/deprecated)
     - [affected:graph](/deprecated/affected-graph)
     - [print-affected](/deprecated/print-affected)