Claude Code and Nx Workspace: Beginner Monorepo Guide

Nx Workspace is a boundary tool, not just a big repository

If you ask Claude Code to “make a monorepo” without context, it can generate plenty of files. The harder problem comes later: does a change in apps/web affect apps/admin? Should a button live in the app or in a shared UI library? Should CI run every test for every pull request?

Nx Workspace helps answer those questions with a project graph, task graph, affected commands, and caching. The official Nx mental model explains how Nx analyzes projects and runs only the work that matters. For beginners, think of Nx as a map plus a task runner: it shows what depends on what, then helps you verify the smallest safe area.

This guide uses Claude Code as a reviewer and pair programmer, not as an unchecked generator. Keep the official docs open: create-nx-workspace, workspace generators, affected, CI setup, and caching tasks. For broader context, pair this with Claude Code monorepo management, pnpm workspace with Claude Code, and CI/CD setup.

---

Use Nx when these three cases are real

Nx is powerful, but it is not required for every side project. A single landing page and a tiny API may be easier to keep as a simple repository. Nx becomes worth it when boundaries and verification cost start to hurt.

The first real use case is a product with several apps that share types or UI. For example, apps/web, apps/admin, apps/api, libs/contracts, and libs/ui can live together so API types and UI primitives change in one pull request.

The second use case is selective CI. If your content site, training pages, admin tools, and API share one repository, running every build on every pull request wastes time. nx affected -t test build uses Git changes and the dependency graph to choose only the projects that can be impacted.

The third use case is making Claude Code safer. When you define libs/ui as presentation-only, libs/contracts as API types, libs/config as shared tooling, and apps/* as deployable apps, Claude Code has a smaller decision space. That matters on monetized pages, signup flows, pricing CTAs, and analytics code where a broad refactor can quietly break revenue.

If you cannot explain your current boundaries yet, first map the repository with Claude Code repo map first pass. Nx speeds up a structure that you can already describe; it does not magically clean up an unclear one.

---

Target workspace

This tutorial keeps the workspace small: two React apps, one Node API, one UI library, one contracts library, and one config library.

flowchart LR
  web["apps/web\nReact + Vite"] --> ui["libs/ui\nUI primitives"]
  admin["apps/admin\nReact + Vite"] --> ui
  web --> contracts["libs/contracts\nAPI types"]
  admin --> contracts
  api["apps/api\nNode API"] --> contracts
  web --> config["libs/config\nlint/test config"]
  api --> config

The rule is simple. apps/* are things you run or deploy. libs/* are reusable building blocks. A library must not import from an app. A UI library should not read API environment variables. A contracts library should not contain React components.

Give Claude Code the boundary before asking for edits:

Understand this Nx Workspace before editing.

Rules:
- apps/web and apps/admin are frontend apps
- apps/api is the API
- libs/ui contains presentation-only UI primitives
- libs/contracts contains API types and Zod schemas
- libs/config contains shared ESLint, Vitest, and TypeScript config
- libs/* must not import from apps/*

Before changes, inspect nx graph. After changes, give the nx affected commands needed for verification.

---

Copy-paste setup

These commands assume Node.js 20+, Git, and pnpm. The options are explicit so a beginner can rerun the tutorial without guessing through prompts.

npx create-nx-workspace@latest acme-nx \
  --workspaceType=integrated \
  --preset=apps \
  --packageManager=pnpm \
  --nxCloud=skip \
  --interactive=false

cd acme-nx
pnpm nx add @nx/react
pnpm nx add @nx/node

Generate the apps and libraries with Nx generators. Generators are safer than hand-creating folders because they update Nx configuration, TypeScript paths, and project metadata consistently.

pnpm nx g @nx/react:app web \
  --directory=apps/web \
  --bundler=vite \
  --unitTestRunner=vitest \
  --e2eTestRunner=playwright \
  --style=css

pnpm nx g @nx/react:app admin \
  --directory=apps/admin \
  --bundler=vite \
  --unitTestRunner=vitest \
  --e2eTestRunner=none \
  --style=css

pnpm nx g @nx/node:app api \
  --directory=apps/api \
  --unitTestRunner=vitest

pnpm nx g @nx/react:lib ui \
  --directory=libs/ui \
  --unitTestRunner=vitest

pnpm nx g @nx/js:lib contracts \
  --directory=libs/contracts \
  --unitTestRunner=vitest

pnpm nx g @nx/js:lib config \
  --directory=libs/config \
  --unitTestRunner=none

Inspect the result before editing:

pnpm nx graph
pnpm nx show projects
pnpm nx show project web

If the graph already feels tangled, stop and simplify before adding more libraries.

---

Read project.json before changing it

For beginners, project.json is the list of jobs a project can run. It usually defines targets such as build, test, and serve.

{
  "name": "web",
  "sourceRoot": "apps/web/src",
  "projectType": "application",
  "targets": {
    "build": {
      "executor": "@nx/vite:build",
      "outputs": ["{options.outputPath}"],
      "options": {
        "outputPath": "dist/apps/web"
      }
    },
    "test": {
      "executor": "@nx/vite:test",
      "outputs": ["{workspaceRoot}/coverage/apps/web"],
      "options": {
        "passWithNoTests": true
      }
    },
    "serve": {
      "executor": "@nx/vite:dev-server",
      "options": {
        "buildTarget": "web:build"
      }
    }
  },
  "tags": ["scope:app", "type:web"]
}

Ask Claude Code to explain before editing:

Read apps/web/project.json and explain build, test, and serve for a beginner.
If a change is needed, propose the smallest diff only.
Do not break outputs, cache behavior, or dependsOn relationships.

The outputs field matters because Nx uses it for caching. A wrong output path can make caching useless or, worse, reuse stale artifacts.

---

Put affected tasks in CI

affected is where Nx becomes practical. It compares Git changes with the project graph and runs tasks only for projects that can be impacted.

pnpm nx affected -t lint test build --base=main --head=HEAD
pnpm nx affected:graph --base=main --head=HEAD

In GitHub Actions, fetch full history so Nx can compare branches. Run tasks through nx; direct vitest, eslint, or tsc calls bypass Nx’s affected logic and cache.

name: nx-ci

on:
  pull_request:
  push:
    branches: [main]

jobs:
  affected:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: pnpm/action-setup@v4
        with:
          version: 10
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm nx affected -t lint test build --base=origin/main --head=HEAD --parallel=3

For teams, Nx Cloud remote caching can reduce repeated CI work. I recommend proving the value with local cache and affected commands first, then adding remote cache when CI time becomes a visible bottleneck.

---

Common failure cases

The first failure is creating libs/shared and putting everything there. Ask Claude Code to classify shared code as UI, contracts, config, or pure utilities before moving it.

The second failure is importing from apps/* inside libs/*. That reverses the dependency direction and makes the library hard to reuse.

The third failure is running raw tools in CI. Prefer pnpm nx run-many -t test or pnpm nx affected -t test so Nx can use the graph and cache.

The fourth failure is over-engineering the first week. Do not create libs/auth, libs/domain, libs/data-access, and many feature libraries before you have real duplication.

The fifth failure is letting Claude Code edit without graph context. Make pnpm nx graph before work and pnpm nx affected -t test build after work part of the prompt.

---

Monetization angle: protect the pages that make money

For a site like ClaudeCodeLab, articles, training pages, admin tools, lead forms, and analytics may share one repository. Nx helps not only with speed, but with revenue safety. If libs/cta changes, the graph tells reviewers which pages may be affected. If libs/analytics changes, affected CI tells you which apps need smoke tests.

That is useful for AdSense layouts, affiliate blocks, checkout CTAs, and consultation forms. If your team wants a repeatable Claude Code and monorepo workflow, see ClaudeCodeLab training. If you are working alone, start by building this sample workspace and saving a screenshot of nx graph before adding more packages.

Hands-on verification

In my check as Masa, I created only web, admin, api, ui, and contracts first. After changing a type in libs/contracts, pnpm nx affected -t test build --base=main --head=HEAD selected the apps that depended on contracts. After changing only libs/ui, the API build stayed out of scope. The important lesson was not memorizing Nx options; it was that Claude Code produces smaller, reviewable changes when the graph and boundaries are visible first.

Summary

Nx Workspace is not a reason to make a repository huge. It is a way to make dependencies visible, verify only the affected projects, and give Claude Code boundaries it can follow.

Start small, read project.json, inspect nx graph, and put nx affected in CI. That is enough to turn Claude Code from a file generator into a useful reviewer for monorepo structure.