From 719c5f55fbd1e71f66c44d32343140a4e89f3ac0 Mon Sep 17 00:00:00 2001 From: Jack Hsu Date: Tue, 10 Jun 2025 09:34:10 -0400 Subject: [PATCH] docs(core): update Nx installation steps to prefer global installs (#31513) This PR makes the global install more prominent. This is important for non-JS workspaces since they may not have node or npm available. The installation flow should be: 1. Install Nx (e.g. `brew install nx`) 2. Run `nx init` in your project The `create-nx-workspace` is removed since it's already mentioned on the intro page, and it is covered in tutorials. It is also not technically an "install" command. Preview: https://nx-dev-git-docs-update-installation-nrwl.vercel.app/getting-started/installation **Note:** The cross-platform NPM install is still featured first because it'll work for everyone. It shouldn't be a concern for non-JS devs since other tools like Claude Code also has `npm install --global` as their install step. --- .../packages/gradle/documents/overview.md | 17 ++- docs/shared/getting-started/installation.md | 121 ++++-------------- docs/shared/packages/gradle/gradle-plugin.md | 17 ++- 3 files changed, 50 insertions(+), 105 deletions(-) diff --git a/docs/generated/packages/gradle/documents/overview.md b/docs/generated/packages/gradle/documents/overview.md index 461032335e..4353480b11 100644 --- a/docs/generated/packages/gradle/documents/overview.md +++ b/docs/generated/packages/gradle/documents/overview.md @@ -25,24 +25,33 @@ This plugin requires Java 17 or newer. Using older Java versions is unsupported You can install Nx globally. Depending on your package manager, use one of the following commands: {% tabs %} -{% tab label="Homebrew" %} +{% tab label="npm" %} + +```shell +npm add --global nx@latest +``` + +{% /tab %} +{% tab label="Homebrew (macOS, Linux)" %} ```shell brew install nx ``` {% /tab %} -{% tab label="Chocolatey" %} +{% tab label="Chocolatey (Windows)" %} ```shell choco install nx ``` {% /tab %} -{% tab label="npm" %} +{% tab label="apt (Ubuntu)" %} ```shell -npm add --global nx@latest +sudo add-apt-repository ppa:nrwl/nx +sudo apt update +sudo apt install nx ``` {% /tab %} diff --git a/docs/shared/getting-started/installation.md b/docs/shared/getting-started/installation.md index b142eb5ac7..4c13272ded 100644 --- a/docs/shared/getting-started/installation.md +++ b/docs/shared/getting-started/installation.md @@ -5,146 +5,73 @@ description: Learn how to install Nx in a new workspace, add it to an existing r # Installation -Create a new Nx workspace using the following command: +To install Nx on your machine, choose one of the following methods based on your operating system and package manager. You can also use `npx` to run Nx without installing it globally. {% tabs %} {% tab label="npm" %} ```shell -npx create-nx-workspace +npm add --global nx ``` +**Note:** You can also use yarn, pnpm, or bun + {% /tab %} -{% tab label="yarn" %} - -```shell -npx create-nx-workspace --pm yarn -``` - -{% /tab %} -{% tab label="pnpm" %} - -```shell -npx create-nx-workspace --pm pnpm -``` - -{% /tab %} -{% tab label="Bun" %} - -```shell -bunx create-nx-workspace --pm bun -``` - -{% /tab %} -{% /tabs %} - -This will guide you through the setup, asking whether you want a monorepo or a standalone app and whether you want to start with a blank or a preconfigured setup. - -```{% command="npx create-nx-workspace@latest" path="~" %} - -NX Let's create a new workspace [https://nx.dev/getting-started/intro] - -✔ Where would you like to create your workspace? · myorg -? Which stack do you want to use? … -None: Configures a TypeScript/JavaScript project with minimal structure. -React: Configures a React application with your framework of choice. -Vue: Configures a Vue application with your framework of choice. -Angular: Configures a Angular application with modern tooling. -Node: Configures a Node API application with your framework of choice. -``` - -Once you've created your workspace, you can - -- run single tasks with `npx nx ` -- run multiple tasks with `npx nx run-many -t ` - -Run `npx nx run-many -t build` twice to see how Nx's powerful caching speeds up your build. - -Learn more about [running tasks](/features/run-tasks). - -## Installing Nx Into an Existing Repository - -If you want to add Nx to an existing repository run: - -```shell -npx nx@latest init -``` - -You can also manually install the nx NPM package and create a [nx.json](/reference/nx-json) to configure it. Learn more about [adopting Nx in an existing project](/recipes/adopting-nx) - -## Installing Nx Globally - -You can install Nx globally. Depending on your package manager, use one of the following commands: - -{% tabs %} -{% tab label="Homebrew" %} +{% tab label="Homebrew (macOS, Linux)" %} ```shell brew install nx ``` {% /tab %} -{% tab label="Chocolatey" %} +{% tab label="Chocolatey (Windows)" %} ```shell choco install nx ``` {% /tab %} -{% tab label="npm" %} +{% tab label="apt (Ubuntu)" %} ```shell -npm add --global nx@latest -``` - -{% /tab %} -{% tab label="yarn (v1 only)" %} - -```shell -yarn global add nx@latest -``` - -{% /tab %} -{% tab label="pnpm" %} - -```shell -pnpm add --global nx@latest -``` - -{% /tab %} -{% tab label="Bun" %} - -```shell -bun install --global nx@latest +sudo add-apt-repository ppa:nrwl/nx +sudo apt update +sudo apt install nx ``` {% /tab %} {% /tabs %} -The advantage of a global installation is that you don't have to prefix your commands with npx, yarn or pnpm. The global Nx installation hands off the process execution to the local Nx installation in your repository, which eliminates any issues with outdated globally installed packages. +## Adding Nx Into Your Repository -## Install Nx in a Non-Javascript Repo - -Nx can manage its own installation without requiring a `package.json` file or a `node_modules` folder. This type of installation is useful for repositories that may not contain any JavaScript or TypeScript (e.g. .Net or Java based workspaces that want to leverage Nx features). In this setup, the Nx CLI is all contained within a `.nx` folder. To set this up run the `nx init` command in a folder without a `package.json` file. +To add Nx to an existing repository run: ```shell -npx nx init +nx init ``` -See the [install Nx in a non-javascript repo](/recipes/installation/install-non-javascript) recipe for more information. +**Note:** You can also manually install the nx NPM package and create a [nx.json](/reference/nx-json) to configure it. Learn more about [adopting Nx in an existing project](/recipes/adopting-nx) + +### Starter Repository + +To create a starter repository, you can use the `create-nx-workspace` command. This will create a new Nx workspace with a default configuration and example applications. + +```shell +npx create-nx-workspace@latest +``` ## Update Nx When you update Nx, Nx will also [automatically update your dependencies](/features/automate-updating-dependencies) if you have an [Nx plugin](/concepts/nx-plugins) installed for that dependency. To update Nx, run: ```shell -npx nx migrate latest +nx migrate latest ``` This will create a `migrations.json` file with any update scripts that need to be run. Run them with: ```shell -npx nx migrate --run-migrations +nx migrate --run-migrations ``` {% callout title="Update One Major Version at a Time" %} diff --git a/docs/shared/packages/gradle/gradle-plugin.md b/docs/shared/packages/gradle/gradle-plugin.md index 461032335e..4353480b11 100644 --- a/docs/shared/packages/gradle/gradle-plugin.md +++ b/docs/shared/packages/gradle/gradle-plugin.md @@ -25,24 +25,33 @@ This plugin requires Java 17 or newer. Using older Java versions is unsupported You can install Nx globally. Depending on your package manager, use one of the following commands: {% tabs %} -{% tab label="Homebrew" %} +{% tab label="npm" %} + +```shell +npm add --global nx@latest +``` + +{% /tab %} +{% tab label="Homebrew (macOS, Linux)" %} ```shell brew install nx ``` {% /tab %} -{% tab label="Chocolatey" %} +{% tab label="Chocolatey (Windows)" %} ```shell choco install nx ``` {% /tab %} -{% tab label="npm" %} +{% tab label="apt (Ubuntu)" %} ```shell -npm add --global nx@latest +sudo add-apt-repository ppa:nrwl/nx +sudo apt update +sudo apt install nx ``` {% /tab %}