RULE

my-monorepo/
├── apps/                    # Application packages (deployable)
│   ├── web/
│   ├── docs/
│   └── api/
├── packages/                # Library packages (shared code)
│   ├── ui/
│   ├── utils/
│   └── config-*/           # Shared configs (eslint, typescript, etc.)
├── package.json            # Root package.json (minimal deps)
├── turbo.json              # Turborepo configuration
├── pnpm-workspace.yaml     # (pnpm) or workspaces in package.json
└── pnpm-lock.yaml          # Lockfile (required)

// apps/web/package.json
{
  "name": "web",
  "private": true,
  "dependencies": {
    "@repo/ui": "workspace:*",
    "next": "latest"
  }
}

// packages/ui/package.json
{
  "name": "@repo/ui",
  "exports": {
    "./button": "./src/button.tsx",
    "./card": "./src/card.tsx"
  }
}

{
  "name": "@repo/ui",
  "exports": {
    "./button": "./src/button.tsx"
  }
}

{
  "name": "@repo/ui",
  "exports": {
    "./button": {
      "types": "./src/button.tsx",
      "default": "./dist/button.js"
    }
  },
  "scripts": {
    "build": "tsc"
  }
}

# Good: Install in the package that needs it
pnpm add lodash --filter=@repo/utils

# Avoid: Installing everything at root
pnpm add lodash -w  # Only for repo-level tools

// pnpm/bun
{ "@repo/ui": "workspace:*" }

// npm/yarn
{ "@repo/ui": "*" }

{
  "exports": {
    ".": "./src/index.ts",
    "./button": "./src/button.tsx",
    "./utils": "./src/utils.ts"
  }
}

// BAD: packages/ui/src/index.ts
export * from './button';
export * from './card';
export * from './modal';
// ... imports everything even if you need one thing

// GOOD: Direct exports in package.json
{
  "exports": {
    "./button": "./src/button.tsx",
    "./card": "./src/card.tsx"
  }
}

// Good
{ "name": "@repo/ui" }
{ "name": "@acme/utils" }

// Avoid (conflicts with npm registry)
{ "name": "ui" }
{ "name": "utils" }

// BAD: Reaching into another package
import { Button } from "../../packages/ui/src/button";

// GOOD: Install and import properly
import { Button } from "@repo/ui/button";

// BAD
apps/
  web/
    shared/        # This should be a package!
      utils.ts

// GOOD
packages/
  utils/           # Proper shared package
    src/utils.ts

// BAD: Root has app dependencies
{
  "dependencies": {
    "react": "^18",
    "next": "^14",
    "lodash": "^4"
  }
}

// GOOD: Root only has repo tools
{
  "devDependencies": {
    "turbo": "latest",
    "husky": "latest"
  }
}