Setting Up Claude Code for a Next.js Monorepo: Complete Guide

Claude Code works great out of the box for single-package projects. But point it at a Next.js monorepo with shared packages, multiple apps, and cross-cutting concerns, and it starts hallucinating import paths and mixing up package conventions. The fix is proper configuration — and once set up, Claude Code becomes even more powerful in a monorepo than in a single project.

The Monorepo Structure

We will use a typical Turborepo setup with two Next.js apps and shared packages:

my-monorepo/
  apps/
    web/          # Customer-facing Next.js app
    admin/        # Internal admin Next.js app
  packages/
    ui/           # Shared component library
    config/       # Shared ESLint, TypeScript configs
    database/     # Prisma schema and client
    utils/        # Shared utility functions
  turbo.json
  package.json
  CLAUDE.md       # Root-level Claude Code config

Root CLAUDE.md: The Foundation

The root CLAUDE.md file gives Claude Code the big picture. It should explain the monorepo architecture, package relationships, and global conventions. Keep it focused on what is unique to your project — Claude already knows how Next.js and Turborepo work:

# Project: Acme Platform

## Architecture
- Turborepo monorepo with pnpm workspaces
- apps/web: Customer portal (Next.js 15, App Router)
- apps/admin: Internal tools (Next.js 15, App Router)
- packages/ui: Shared React components (exported from index.ts)
- packages/database: Prisma client, schema, and migrations
- packages/utils: Pure utility functions, no React dependency

## Cross-Package Rules
- Import shared packages via workspace aliases: @acme/ui, @acme/database
- Never import directly from another app (apps/web cannot import from apps/admin)
- All shared components must be exported from packages/ui/src/index.ts
- Database queries only through packages/database — apps never import Prisma directly

## Commands
- pnpm dev: Run all apps in dev mode
- pnpm build: Build all packages and apps via Turborepo
- pnpm db:push: Sync Prisma schema to database
- pnpm lint: Lint all packages
- pnpm test: Run all tests

Per-App CLAUDE.md Files

Each app gets its own CLAUDE.md with app-specific context. This is critical because the web app and admin app likely have different conventions, authentication strategies, and deployment targets.

Scoped Rules for Packages

The .claude/rules/ directory supports path-scoped rules that activate only when Claude Code is working on files in specific directories. This prevents UI component conventions from leaking into database package code and vice versa.

Custom Commands for Common Tasks

Monorepos have repetitive cross-package tasks that are tedious to explain each time. Claude Code custom commands solve this. Create .claude/commands/ with task-specific prompts like "add-shared-component" that automatically handles creating the component, exporting it, and updating the barrel file.

Workspace-Aware Prompting Tips

When working in a monorepo, always prefix your prompts with the target scope: "In apps/web, create a..." or "In packages/ui, add a...". This prevents Claude Code from creating files in the wrong package. For cross-package changes, be explicit about the order: "First add the type to packages/database, then use it in apps/web."

Key Takeaways

• Root CLAUDE.md defines the monorepo architecture and cross-package rules
• Per-app CLAUDE.md files prevent convention mixing between different apps
• Path-scoped rules in .claude/rules/ activate contextually based on file location
• Custom commands automate repetitive cross-package workflows
• Always scope your prompts to a specific package or app to prevent file placement errors