Monorepo Best Practices

earna-ai/
├── apps/                 # Main customer-facing application
│   ├── package.json     # App-specific dependencies
│   ├── vercel.json      # Deployment configuration
│   └── components/      # App-specific components
├── console/             # Admin console application
│   ├── package.json
│   ├── vercel.json
│   └── app/            # Next.js app directory
├── docs-nextra/        # Documentation website
│   ├── package.json
│   ├── vercel.json
│   └── src/content/    # MDX documentation files
├── credit-engine/      # Credit processing service
│   ├── package.json
│   └── vercel.json
├── turbo.json          # Turborepo configuration
├── pnpm-workspace.yaml # Workspace definitions
├── package.json        # Root dependencies
└── pnpm-lock.yaml     # Lockfile for all workspaces

# Add to specific workspace
pnpm --filter console add react-query
 
# Add to root (shared tooling)
pnpm add -w -D eslint
 
# Add to all workspaces
pnpm add -r lodash

{
  "dependencies": {
    "@earna/shared": "workspace:*",
    "@earna/ui": "workspace:^"
  }
}

// Good: Absolute imports within workspace
import { Button } from '@/components/ui/button'
 
// Good: Cross-workspace imports
import { utils } from '@earna/shared'
 
// Bad: Relative imports across workspaces
import { Button } from '../../../console/components/button'

# Run specific app
pnpm --filter console dev
pnpm --filter apps dev
pnpm --filter docs-nextra dev

# Run all development servers
pnpm turbo dev
 
# Run specific combination
pnpm turbo dev --filter=console --filter=apps

{
  "build": {
    "dependsOn": ["^build"],
    "outputs": [".next/**", "dist/**"]
  }
}

# Build everything
pnpm turbo build
 
# Build specific project and dependencies
pnpm turbo build --filter=console...
 
# Build without cache
pnpm turbo build --force

# Test specific workspace
pnpm --filter console test
 
# Test all workspaces
pnpm turbo test

# Run integration tests
pnpm turbo test:integration
 
# Run E2E tests
pnpm turbo test:e2e

# Create shared package
mkdir packages/shared
cd packages/shared
pnpm init
 
# Configure package.json
{
  "name": "@earna/shared",
  "version": "1.0.0",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts"
}

packages/
├── eslint-config/      # Shared ESLint rules
├── tsconfig/          # Shared TypeScript configs
└── tailwind-config/   # Shared Tailwind presets

// apps/tsconfig.json
{
  "extends": "@earna/tsconfig/nextjs.json",
  "compilerOptions": {
    "baseUrl": "."
  }
}

type(scope): description

[optional body]

[optional footer]

feat(console): add user authentication
fix(apps): resolve D3 import issues
docs(infrastructure): add Turborepo migration guide
chore: update dependencies

feature/[workspace]-description
fix/[workspace]-issue
docs/topic
chore/description

feature/console-user-management
fix/apps-d3-imports
docs/turborepo-migration
chore/update-dependencies

# Only build changed packages
pnpm turbo build --filter=[HEAD^1]
 
# Build affected by changes
pnpm turbo build --filter=...[origin/main]

{
  "buildCommand": "pnpm turbo build --filter=workspace-name",
  "installCommand": "pnpm install",
  "outputDirectory": ".next"
}

# Cache location
.turbo/
 
# Clear cache
rm -rf .turbo
pnpm turbo build --force

{
  "remoteCache": {
    "signature": true
  }
}

# Check bundle size
pnpm --filter console analyze
 
# Find duplicate dependencies
pnpm dedupe
 
# Prune unnecessary packages
pnpm prune

.env.local           # Local development (gitignored)
.env.development     # Development defaults
.env.production      # Production defaults
.env.example         # Template for developers

// turbo.json
{
  "globalEnv": ["NODE_ENV"],
  "env": ["NEXT_PUBLIC_*", "DATABASE_URL"]
}

{
  "scripts": {
    "dev": "turbo dev",
    "build": "turbo build",
    "lint": "turbo lint",
    "clean": "turbo clean && rm -rf node_modules"
  }
}

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint"
  }
}

# Reset and reinstall
pnpm store prune
rm -rf node_modules pnpm-lock.yaml
pnpm install

# Clear all caches
rm -rf .turbo .next
pnpm turbo build --force

# Rebuild TypeScript references
pnpm turbo typecheck --force