From bbd7960b0f2976730e298db5a7aa481fa02c056f Mon Sep 17 00:00:00 2001 From: MaxKless <34165455+MaxKless@users.noreply.github.com> Date: Wed, 27 Mar 2024 18:19:51 +0100 Subject: [PATCH] docs(core): update troubleshooting guide & console adjustments (#22519) --- docs/shared/installation/troubleshoot-installation.md | 9 +++++++++ docs/shared/recipes/console-project-details.md | 6 ++++++ docs/shared/recipes/console-troubleshooting.md | 4 +++- 3 files changed, 18 insertions(+), 1 deletion(-) diff --git a/docs/shared/installation/troubleshoot-installation.md b/docs/shared/installation/troubleshoot-installation.md index e613245064657..429406ce77222 100644 --- a/docs/shared/installation/troubleshoot-installation.md +++ b/docs/shared/installation/troubleshoot-installation.md @@ -14,6 +14,7 @@ are a few reasons why this could potentially happen: 1. The package-lock.json file was not correctly updated by npm, and missed optional dependencies used by Nx. You can read more about this [issue on the npm repository.](https://github.com/npm/cli/issues/4828) 1. [Your platform is not supported](#supported-native-module-platforms) +1. [Node.js wasn't installed for the proper architecture ](#nodejs-installation-issues) {% callout type="note" title="Updating Nx" %} When updating Nx that is already on 15.8, the package-lock.json should continue to be updated properly with all the proper optional dependencies. @@ -45,3 +46,11 @@ We publish modules for the following platforms: - FreeBSD (x64) If you're running a machine that isn't part of the list above, then Nx does not support it at this time. [Please open an issue on GitHub](https://github.com/nrwl/nx/issues/new/choose) if you feel Nx should support that platform and we will assess what can be done, please make sure to include your platform and architecture in the issue. + +### Node.js Installation Issues + +Ensure that the architecture of your Node.js installation matches your hardware. Run `nx report` and check that the `OS` property is correct (e.g. `darwin-arm64` for MacOS on Apple silicon). If it contains `x64` even though you're on an `arm64` chip, then something is wrong. A mismatch in architecture can lead to errors loading Nx's native binary. + +Often, the culprit of the mismatch is a faulty installation of your toolchain: Homebrew (MacOS), Node.js or VSCode (if using Nx Console). You should reinstall your toolchain with the correct architecture. Run `nx report` again to validate the installation. + +For issues inside VSCode or Nx Console, also refer to the [Nx Console troubleshooting docs](recipes/nx-console/console-troubleshooting) diff --git a/docs/shared/recipes/console-project-details.md b/docs/shared/recipes/console-project-details.md index 385fa8b900639..b08c42901e2ba 100644 --- a/docs/shared/recipes/console-project-details.md +++ b/docs/shared/recipes/console-project-details.md @@ -10,3 +10,9 @@ You can access the integrated Project Details View in multiple ways: - By clicking on the Preview icon to the top right of your `project.json`, `package.json` or any file that modifies targets (for example `jest.config.ts` or `cypress.config.ts`) - By using the codelenses in any of these files - By running the `Nx: Open Project Details to Side` action while any file in a project is open + +In addition to viewing the Project Details View, Codelenses in tooling configuration files (like `jest.config.ts`) allow you to run targets via Nx with a single click. +If you would like to disable the Codelens feature, you can do so easily: + +- In VSCode, simply turn off the `nxConsole.enableCodeLens` setting +- In JetBrains IDEs, right-click a Codelens and select `` Hide `Code Vision: Nx Config Files` Inlay Hints `` diff --git a/docs/shared/recipes/console-troubleshooting.md b/docs/shared/recipes/console-troubleshooting.md index fe223d087fdbd..c69e2071b0db8 100644 --- a/docs/shared/recipes/console-troubleshooting.md +++ b/docs/shared/recipes/console-troubleshooting.md @@ -1,5 +1,7 @@ # Nx Console Troubleshooting +Often, issues with Nx Console are the result of underlying issues with Nx. Make sure to read the [Nx installation troubleshooting docs](recipes/troubleshooting/troubleshoot-nx-install-issues) for more help. + ## VSCode + nvm Issues VSCode loads a version of Node when it starts. It can use versions set via [`nvm`](https://github.com/nvm-sh/nvm) but there are some caveats. @@ -10,7 +12,7 @@ VSCode loads a version of Node when it starts. It can use versions set via [`nvm - If you work with lots of different Node versions, there are various VSCode extensions available to dynamically run `nvm use` whenever you open a new integrated terminal. Search for `nvm`. - You can set a static version by using a launch configuration with `runtimeVersion` set. Refer to [this guide](https://code.visualstudio.com/docs/nodejs/nodejs-debugging#_multi-version-support). -We try to make noticing discrepancies easier by showing you the currently loaded Node version on startup. You can disable this in the Nx Console settings. +We try to make noticing discrepancies easier by showing you the currently loaded Node version on startup. To enable this, toggle the `nxConsole.showNodeVersionOnStartup` setting in VSCode. ## JetBrains WSL Support