Typescript Monorepo

TypeScript Monorepo Patterns

Structure (Turborepo + pnpm workspaces)

my-monorepo/
├── apps/
│   ├── web/              # Next.js frontend
│   ├── api/              # Node.js / Fastify backend
│   └── docs/             # Docs site
├── packages/
│   ├── ui/               # Shared React component library
│   ├── utils/            # Shared utility functions
│   ├── types/            # Shared TypeScript types
│   ├── config/           # Shared configs (eslint, tsconfig)
│   └── db/               # Prisma client & schema
├── turbo.json
├── pnpm-workspace.yaml
└── package.json

pnpm-workspace.yaml

packages:
  - 'apps/*'
  - 'packages/*'

Root package.json

{
  "name": "my-monorepo",
  "private": true,
  "scripts": {
    "build":  "turbo run build",
    "dev":    "turbo run dev --parallel",
    "lint":   "turbo run lint",
    "test":   "turbo run test",
    "type-check": "turbo run type-check"
  },
  "devDependencies": {
    "turbo": "latest"
  }
}

turbo.json

{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "dist/**", "!dist/**/*.map"]
    },
    "dev": {
      "persistent": true,
      "cache": false
    },
    "lint": {
      "outputs": []
    },
    "test": {
      "outputs": ["coverage/**"],
      "env": ["CI"]
    },
    "type-check": {
      "outputs": []
    }
  }
}

Shared Package (packages/ui)

// packages/ui/package.json
{
  "name": "@repo/ui",
  "version": "0.0.1",
  "private": true,
  "exports": {
    ".": {
      "import": "./src/index.ts",
      "require": "./dist/index.js",
      "types": "./dist/index.d.ts"
    },
    "./button": {
      "import": "./src/button.tsx"
    }
  },
  "scripts": {
    "build": "tsup src/index.ts --format esm,cjs --dts",
    "dev":   "tsup src/index.ts --watch"
  },
  "peerDependencies": {
    "react": "^19.0.0"
  }
}

Consuming Shared Packages

// apps/web/package.json
{
  "dependencies": {
    "@repo/ui":    "workspace:*",
    "@repo/utils": "workspace:*",
    "@repo/types": "workspace:*"
  }
}

TypeScript Project References

// packages/utils/tsconfig.json
{
  "compilerOptions": {
    "composite": true,
    "declaration": true,
    "declarationMap": true,
    "outDir": "dist"
  },
  "include": ["src"]
}

// apps/web/tsconfig.json
{
  "extends": "@repo/config/tsconfig.base.json",
  "compilerOptions": { "baseUrl": "." },
  "references": [
    { "path": "../../packages/utils" },
    { "path": "../../packages/types" }
  ]
}

Shared ESLint Config (packages/config)

// packages/config/eslint-base.js
module.exports = {
  extends: [
    'eslint:recommended',
    'plugin:@typescript-eslint/recommended',
    'plugin:import/recommended',
  ],
  rules: {
    '@typescript-eslint/no-explicit-any': 'warn',
    '@typescript-eslint/consistent-type-imports': 'error',
    'import/order': ['error', { 'newlines-between': 'always' }],
  },
}

// apps/web/.eslintrc.js
module.exports = {
  extends: ['@repo/config/eslint-base', 'next/core-web-vitals'],
}

Filtering Turbo Runs

# Run only for affected packages
turbo run build --filter=...[HEAD^1]

# Run for specific app and its dependencies
turbo run dev --filter=web...

# Run for a package and all consumers
turbo run build --filter=...ui

Shared Environment Variables

# .env (root — turbo reads this)
DATABASE_URL=postgres://...

# turbo.json — declare which vars affect caching
{
  "globalEnv": ["NODE_ENV", "DATABASE_URL"],
  "tasks": {
    "build": { "env": ["NEXT_PUBLIC_API_URL"] }
  }
}