Claude Code dan Nx Workspace: panduan monorepo praktis

Nx Workspace bukan sekadar repository besar

Kalau kamu meminta Claude Code “buatkan monorepo”, ia bisa menghasilkan banyak file. Masalah sebenarnya muncul beberapa minggu kemudian: apakah perubahan di apps/web memengaruhi apps/admin? Komponen tombol sebaiknya di app atau di shared UI library? Apakah CI harus menjalankan semua test di setiap pull request?

Nx Workspace menjawabnya dengan project graph, task graph, affected commands, dan cache. Nx mental model resmi menjelaskan bagaimana Nx menganalisis project dan menjalankan pekerjaan yang perlu saja. Untuk pemula, anggap Nx sebagai peta dependency sekaligus task runner.

Di panduan ini, Claude Code dipakai sebagai reviewer dan partner implementasi, bukan generator tanpa batas. Gunakan dokumentasi resmi sebagai sumber utama: create-nx-workspace, workspace generators, affected, CI setup, dan caching tasks. Untuk konteks tambahan, baca manajemen monorepo Claude Code, pnpm workspace, dan CI/CD setup.

---

Kapan Nx layak dipakai

Nx kuat, tetapi tidak wajib untuk semua proyek kecil. Landing page dan API kecil sering lebih nyaman di repository sederhana. Nx mulai berguna ketika boundary dan biaya verifikasi mulai terasa.

Use case pertama adalah beberapa app berbagi type atau UI. Misalnya apps/web, apps/admin, apps/api, libs/contracts, dan libs/ui tinggal dalam satu repo agar type API dan komponen dasar bisa diubah dalam satu PR.

Use case kedua adalah CI selektif. Jika content site, halaman training, admin, dan API berada di satu repo, menjalankan semua build di setiap PR akan lambat. nx affected -t test build memakai perubahan Git dan dependency graph untuk memilih project yang mungkin terdampak.

Use case ketiga adalah membuat Claude Code lebih aman. Saat libs/ui hanya UI, libs/contracts hanya type API, libs/config konfigurasi tooling, dan apps/* app deployable, ruang gerak Claude Code menjadi lebih kecil. Ini penting untuk halaman dengan AdSense, affiliate, form konsultasi, atau CTA pembayaran.

Jika boundary repo belum bisa kamu jelaskan, mulai dari repo map first pass. Nx mempercepat struktur yang jelas; ia tidak otomatis merapikan struktur yang belum jelas.

---

Struktur target

Kita mulai kecil: dua app React, satu API Node, satu UI library, satu contracts library, dan satu 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

Aturannya sederhana. apps/* adalah unit yang dijalankan atau dideploy. libs/* adalah bagian reusable. Library tidak boleh import dari app. UI library tidak membaca environment variable API, dan contracts library tidak berisi komponen React.

Berikan boundary ini ke Claude Code sebelum edit:

Pahami Nx Workspace ini terlebih dahulu. Jangan edit file dulu.

Aturan:
- apps/web dan apps/admin adalah frontend apps
- apps/api adalah API
- libs/ui hanya berisi komponen UI reusable
- libs/contracts berisi type API dan Zod schemas
- libs/config berisi konfigurasi shared ESLint, Vitest, dan TypeScript
- libs/* tidak boleh import dari apps/*

Sebelum perubahan, cek nx graph. Setelah perubahan, berikan command nx affected untuk verifikasi.

---

Setup yang bisa dicopy

Command berikut mengasumsikan Node.js 20+, Git, dan pnpm sudah tersedia. Opsi dibuat eksplisit agar tidak bergantung pada prompt interaktif.

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

Buat app dan library dengan Nx generators. Generator memperbarui konfigurasi Nx, TypeScript paths, dan metadata project secara konsisten.

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

Sebelum edit, lihat hasilnya:

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

Jika graph sudah rumit sejak awal, sederhanakan struktur sebelum menambah library.

---

Baca project.json sebelum mengubahnya

Untuk pemula, project.json adalah daftar pekerjaan yang bisa dijalankan oleh sebuah project.

{
  "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"]
}

Minta Claude Code menjelaskan sebelum edit:

Baca apps/web/project.json dan jelaskan build, test, dan serve untuk pemula.
Jika perubahan diperlukan, usulkan diff paling kecil saja.
Jangan merusak outputs, perilaku cache, atau relasi dependsOn.

outputs penting karena Nx memakainya untuk cache. Path yang salah bisa membuat cache tidak berguna atau memakai artifact lama.

---

Masukkan affected ke CI

affected membandingkan perubahan Git dengan project graph dan menjalankan task hanya pada project yang mungkin terdampak.

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

Di GitHub Actions, ambil full history agar branch comparison berjalan. Jalankan task melalui nx; memanggil vitest, eslint, atau tsc langsung akan melewati affected logic dan cache Nx.

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

Untuk tim, Nx Cloud remote cache bisa mengurangi pekerjaan berulang di CI. Buktikan dulu nilainya dengan local cache dan affected, lalu tambahkan remote cache saat waktu CI benar-benar menjadi bottleneck.

---

Kesalahan umum

Kesalahan pertama adalah membuat libs/shared lalu menaruh semuanya di sana. Sebelum memindahkan kode, minta Claude Code mengklasifikasikan apakah itu UI, contracts, config, atau pure utility.

Kesalahan kedua adalah libs/* import dari apps/*. Ini membalik arah dependency dan membuat library sulit digunakan ulang.

Kesalahan ketiga adalah menjalankan raw tools di CI. Gunakan pnpm nx run-many -t test atau pnpm nx affected -t test.

Kesalahan keempat adalah over-engineering pada minggu pertama. Jangan buat libs/auth, libs/domain, dan libs/data-access sebelum ada duplikasi nyata.

Kesalahan kelima adalah membiarkan Claude Code edit tanpa konteks graph. Masukkan pnpm nx graph sebelum kerja dan pnpm nx affected -t test build setelah kerja.

---

Monetisasi: lindungi halaman yang menghasilkan

Di situs seperti ClaudeCodeLab, artikel, halaman training, admin, form lead, dan analytics bisa berbagi repo. Nx bukan hanya soal cepat; ia membantu menjelaskan apakah halaman revenue terdampak. Jika libs/cta berubah, graph menunjukkan halaman yang perlu dicek. Jika libs/analytics berubah, affected CI menunjukkan app mana yang butuh smoke test.

Ini berguna untuk layout AdSense, blok affiliate, CTA checkout, dan form konsultasi. Untuk menstandarkan Claude Code dan monorepo di tim, lihat ClaudeCodeLab training. Jika bekerja sendiri, buat workspace contoh ini dan simpan screenshot nx graph sebelum menambah package.

Verifikasi langsung

Dalam pengujian saya sebagai Masa, saya pertama hanya membuat web, admin, api, ui, dan contracts. Setelah mengubah satu type di libs/contracts, pnpm nx affected -t test build --base=main --head=HEAD memilih app yang bergantung pada contracts. Saat hanya libs/ui berubah, build API tidak masuk scope. Pelajaran utamanya bukan menghafal opsi Nx, tetapi membuat graph dan boundary terlihat sebelum meminta Claude Code mengubah kode.

Ringkasan

Nx Workspace bukan alasan untuk membuat repository menjadi besar. Ia membuat dependency terlihat, memverifikasi hanya project yang terdampak, dan memberi Claude Code boundary yang jelas.

Mulai kecil, baca project.json, inspect nx graph, dan masukkan nx affected ke CI. Dengan begitu, Claude Code bukan sekadar generator file, tetapi reviewer struktur monorepo yang berguna.