Quickstart

Create a new Nx workspace, run your first task, and see caching and affected commands in action.

This guide walks you through creating a new Nx workspace, running tasks, and experiencing the two features that make Nx essential for monorepos: local caching and affected commands.

1. Create a new workspace

   Run the following command to scaffold a new Nx workspace:

   npx create-nx-workspace@latest
   

   The interactive prompt asks for:

   • Workspace name — the name of your root directory
   • Starter template — choose from React, Angular, Node, and more

   For a minimal TypeScript monorepo that you can extend incrementally, use the empty template:

   npx create-nx-workspace@latest --template=nrwl/empty-template
   

   After the command completes, you’ll have a workspace directory containing:

   my-workspace/
   ├── nx.json          # Nx configuration
   ├── package.json     # Root package.json with nx as a dev dependency
   ├── packages/        # Your projects live here
   └── tsconfig.base.json
   
2. Run a task

   Move into your workspace directory and run a task on one of your projects:

   nx build myapp
   

   Nx reads the build target from myapp’s project configuration or package.json scripts, resolves the correct task pipeline (including any dependencies that must build first), and runs the task.

   You’ll see terminal output as the build runs, along with how long it took.

3. See caching in action

   Run the exact same command a second time:

   nx build myapp
   

   This time you’ll see:

   > nx run myapp:build  [existing outputs match the cache, left as is]
   
   ——————————————————————————————————————————
   
   NX   Successfully ran target build for project myapp (31ms)
   
   Nx read the output from the cache instead of running the command for 1 out of 1 tasks.
   

   Nx computes a hash of your source files, environment variables, and task configuration. When the hash matches a previous run, it restores the outputs from cache instantly — no rebuilding required.

   Cache hits work across your whole team when you enable remote caching with Nx Cloud. A build that passes on CI will never need to run again locally.

4. Run tasks across all projects

   Run a target across every project in your workspace with run-many:

   nx run-many -t build test
   

   Nx resolves the task dependency graph, runs tasks in the right order, parallelizes where it can, and applies caching to every individual task. Projects whose outputs haven’t changed get instant cache hits.

5. Run only affected tasks

   When working in a branch, you usually only want to test and build what your changes could have broken. Use the affected command:

   nx affected -t build test
   

   Nx compares your current branch against the base branch (main by default), computes which projects are affected by the changed files using the project graph, and runs the specified targets only on those projects.

   This dramatically reduces CI time as your monorepo grows.

6. Visualize your project graph

   See how all your projects relate to each other:

   nx graph
   

   This opens a browser-based interactive visualization of your project dependency graph. You can filter to specific projects, see what a given project depends on, and understand the impact of changes.

Next steps

Configure task caching

Control what gets cached, set cache inputs and outputs, and enable remote caching.

Add Nx plugins

Add plugins for your tech stack to get auto-configured tasks, code generation, and more.

Set up CI

Connect Nx to GitHub Actions, GitLab, Azure, or any other CI provider.

AI integration

Give AI coding assistants real context about your workspace with the Nx MCP server.