nextjs-monorepo

@danmarauda/nextjs-monorepo

0 forks

Updated 4/6/2026

Next.js monorepo patterns with Turborepo and pnpm workspaces. Use this skill when working with multi-package Next.js projects, managing dependencies across packages, optimizing build pipelines, or configuring Turborepo.

Installation

$npx agent-skills-cli install @danmarauda/nextjs-monorepo

Claude Code

Cursor

Copilot

Codex

Antigravity

Details

Repositorydanmarauda/pro

Pathnext-prisma-authjs/.claude/skills/nextjs-monorepo/SKILL.md

Branchmonorepo

Scoped Name@danmarauda/nextjs-monorepo

Usage

After installing, this skill will be available to your AI coding assistant.

Verify installation:

npx agent-skills-cli list

Skill Instructions

name: nextjs-monorepo description: Next.js monorepo patterns with Turborepo and pnpm workspaces. Use this skill when working with multi-package Next.js projects, managing dependencies across packages, optimizing build pipelines, or configuring Turborepo. metadata: author: alias version: "1.0.0" project: monorepo-next-prisma

Next.js Monorepo Skill

Best practices for developing Next.js applications in a monorepo using Turborepo and pnpm workspaces.

Architecture

monorepo/
├── apps/
│   ├── dashboard/     # Next.js app
│   ├── marketing/     # Next.js app
│   └── public-api/    # Next.js app
├── packages/
│   ├── ui/            # Shared UI components
│   ├── config/        # Shared configs (ESLint, TS, etc.)
│   └── database/      # Shared database layer
├── package.json       # Root package.json
├── pnpm-workspace.yaml
├── turbo.json         # Turborepo config
└── tsconfig.json      # Root TS config

When to Use This Skill

Use when:

Setting up a new monorepo
Adding new apps or packages
Managing cross-package dependencies
Optimizing build performance
Configuring Turborebo pipelines
Setting up CI/CD for monorepo

Key Principles

1. Workspace Organization

Package Naming:

Internal packages must have unique names
Use scope prefix: @myorg/ui, @myorg/database
Reference in package.json: "@myorg/ui": "workspace:*"

Dependency Management:

# Add dependency to specific package
pnpm --filter dashboard add react

# Add to all apps
pnpm --filter ./apps/* add next

# Add shared dependency to all packages
pnpm -w add typescript

2. Turborebo Configuration

Pipeline Setup:

{
  "$schema": "https://turbo.build/schema.json",
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "!.next/cache/**", "dist/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "lint": {
      "dependsOn": ["^lint"]
    },
    "test": {
      "dependsOn": ["^build"],
      "outputs": ["coverage/**"]
    }
  }
}

Task Execution:

# Run task in all packages
turbo run build

# Run task in specific package
turbo run build --filter=dashboard

# Run with affected detection
turbo run build --filter=[HEAD^1]

3. TypeScript Configuration

Root tsconfig.json:

{
  "compilerOptions": {
    "composite": true,
    "paths": {
      "@myorg/ui": ["./packages/ui/src"],
      "@myorg/database": ["./packages/database/src"]
    }
  },
  "references": [
    { "path": "./apps/dashboard" },
    { "path": "./packages/ui" }
  ]
}

Package tsconfig.json:

{
  "extends": "../../tsconfig.json",
  "compilerOptions": {
    "composite": true,
    "outDir": "dist",
    "rootDir": "src"
  },
  "references": [
    { "path": "../../packages/ui" }
  ],
  "include": ["src"]
}

4. Import Paths

Use workspace names for imports:

// apps/dashboard/page.tsx
import { Button } from '@myorg/ui'
import { db } from '@myorg/database'

// NOT: import { Button } from '../../../packages/ui/src'

Common Tasks

Add New App

# 1. Create app directory
mkdir -p apps/my-app
cd apps/my-app

# 2. Initialize Next.js
pnpm create next-app . --typescript --tailwind --app

# 3. Update package.json with workspace name
# "name": "@myorg/my-app"

# 4. Add to root tsconfig references
# 5. Add to turbo.json pipeline if needed

Add New Package

# 1. Create package directory
mkdir -p packages/my-package
cd packages/my-package

# 2. Initialize
pnpm init

# 3. Update package.json
{
  "name": "@myorg/my-package",
  "version": "0.0.0",
  "private": true,
  "main": "./src/index.ts",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": "./src/index.ts"
  }
}

# 4. Add to root tsconfig.json references
# 5. Add path mapping to root tsconfig

Build Optimization

# Build only changed packages
turbo run build --filter=[HEAD^1]

# Build specific package and dependents
turbo run build --filter=my-package

# Parallel build with cache
turbo run build --force

# Clean all build artifacts
turbo run clean

Troubleshooting

"Cannot find module" errors

Check pnpm-workspace.yaml includes the package
Run pnpm install from root
Verify package name in package.json
Check tsconfig paths are correct

"Module not found" in Turborepo

Ensure dependencies are listed in package.json
Run pnpm install before turbo commands
Check for circular dependencies

Build cache issues

# Clear turbo cache
turbo run build --force

# Clear pnpm cache
pnpm store prune

# Reinstall everything
rm -rf node_modules packages/*/node_modules apps/*/node_modules
pnpm install

Best Practices

Keep packages focused - Single responsibility per package
Use strict dependencies - Only depend on what you need
Internal packages only - Use private: true for workspace packages
Version together - Use shared versions for core packages
CI/CD with affected - Only test/deploy changed packages
Lock files - Commit pnpm-lock.yaml
Explicit types - Export types from packages

CI/CD Configuration

# .github/workflows/ci.yml
name: CI
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: pnpm/action-setup@v2
        with:
          version: 8
      - uses: actions/setup-node@v3
        with:
          node-version: 20
          cache: 'pnpm'
      - run: pnpm install
      - run: pnpm turbo run build --filter=[HEAD^1]
      - run: pnpm turbo run test --filter=[HEAD^1]
      - run: pnpm turbo run lint --filter=[HEAD^1]

Related Skills

vercel-react-best-practices - React/Next.js performance
typescript-strict - TypeScript configuration
vercel-deploy-claimable - Deployment

Resources

More by danmarauda

View all

vercel-deploy

Deploy applications and websites to Vercel. Use this skill when the user requests deployment actions such as "Deploy my app", "Deploy this to production", "Create a preview deployment", "Deploy and give me the link", or "Push this live". No authentication required - returns preview URL and claimable deployment link.

convex-tanstack

Comprehensive guide for building full-stack applications with Convex and TanStack Start. This skill should be used when working on projects that use Convex as the backend database with TanStack Start (React meta-framework). Covers schema design, queries, mutations, actions, authentication with Better Auth, routing, data fetching patterns, SSR, file storage, scheduling, AI agents, and frontend patterns. Use this when implementing features, debugging issues, or needing guidance on Convex + TanStack Start best practices.

convex-queries

This skill should be used when implementing Convex query functions. It provides comprehensive guidelines for defining, registering, calling, and optimizing queries, including pagination, full text search, and indexing patterns.

ai-elements-workflow

This skill provides guidance for building workflow visualizations using Vercel AI Elements and React Flow. It should be used when implementing interactive node-based interfaces, workflow diagrams, or process flow visualizations in Next.js applications. Covers Canvas, Node, Edge, Connection, Controls, Panel, and Toolbar components.