turborepo-monorepo

name	turborepo-monorepo
description	Turborepo monorepo structure and pnpm workspace conventions. Use when adding packages, configuring build pipelines, managing dependencies, running scripts, or working with the monorepo root config. Triggers on tasks involving workspace setup, package management, turbo.json, pnpm-workspace.yaml, or cross-package dependencies.
frameworks	["turborepo"]
languages	["typescript"]
category	tooling
updated	"2026-03-06T00:00:00.000Z"

Turborepo Monorepo Skill

Quick Reference

When to Use: Adding workspace packages, configuring build pipelines, managing dependencies, or cross-package operations

Package Manager: pnpm 10.27+ (NEVER use npm or yarn)

Runtime: Node.js ≥22.20.0

Workspace Structure

turbo-template-laravel/
├── apps/
│   ├── web/              # Next.js 16 frontend (port 3001)
│   ├── laravel/          # Laravel 12 API (PHP-FPM + Nginx in Docker, port 8000)
│   └── mobile/           # Flutter mobile app
├── packages/
│   ├── api-client/       # @repo/api-client — Orval-generated TanStack Query hooks
│   └── e2e-web/          # Playwright end-to-end tests
├── tooling/
│   ├── eslint/           # @repo/eslint-config — ESLint configs
│   ├── prettier/         # @repo/prettier-config — Prettier config
│   └── typescript/       # @repo/typescript-config — TSConfig bases
├── turbo.json            # Task pipeline configuration
├── pnpm-workspace.yaml   # Workspace definition + catalogs
└── package.json          # Root scripts

pnpm Workspace Config

# pnpm-workspace.yaml
packages:
  - apps/*
  - packages/*
  - tooling/*

# Version catalog — pin shared dependency versions
catalog:
  "@tanstack/react-query": ^5.90.16
  next: 16.1.1
  react: 19.2.3
  tailwindcss: ^4.1.18
  typescript: ^5.9.3
  zod: ^4.3.5

Common Scripts

Development

pnpm dev              # Start all apps in dev mode (Laravel + MySQL + Next.js)
pnpm dev:web          # Start only web app
pnpm dev:mobile       # Start only mobile app (Flutter)

Build & Quality

pnpm build            # Build all apps (respects pipeline deps)
pnpm lint             # ESLint across all TS packages
pnpm lint:fix         # ESLint auto-fix
pnpm format           # Check Prettier formatting
pnpm format:fix       # Fix Prettier formatting
pnpm typecheck        # TypeScript type checking

Laravel (via pnpm -F @repo/laravel)

pnpm -F @repo/laravel test           # Run Pest test suite
pnpm -F @repo/laravel lint           # Check PHP code style (Pint)
pnpm -F @repo/laravel format         # Auto-fix PHP style (Pint)
pnpm -F @repo/laravel typecheck      # PHPStan static analysis
pnpm -F @repo/laravel openapi:generate  # Regenerate openapi.json from Scribe

API Client

pnpm -F @repo/api-client generate    # Regenerate TypeScript hooks from openapi.json

Turbo Pipeline Configuration

// turbo.json
{
  "tasks": {
    "build": {
      "dependsOn": ["^build", "^lint", "^typecheck"],
      "outputs": [".cache/tsbuildinfo.json", "dist/**"],
      "cache": true
    },
    "dev": { "cache": false, "persistent": false },
    "lint": {
      "dependsOn": ["^topo", "^build"],
      "outputs": [".cache/.eslintcache"],
      "cache": true
    },
    "typecheck": {
      "dependsOn": ["^topo", "^build"],
      "outputs": [".cache/tsbuildinfo.json"],
      "cache": true
    }
  },
  "globalPassThroughEnv": ["NODE_ENV", "CI", "VERCEL", "VERCEL_ENV", "VERCEL_URL"]
}

Key points:

• ^build = build dependencies first (topological)
• build depends on ^lint + ^typecheck for quality gate
• dev is not cached (live reload)
• globalPassThroughEnv passes env vars to all tasks

Package Cross-References

Importing Workspace Packages

// In apps/web/package.json
{
  "dependencies": {
    "@repo/api-client": "workspace:*"
  }
}

// Usage in app code
import { useGetApiV1Todos, configureFetcher } from "@repo/api-client"

Package with Sub-Path Exports

// packages/api-client/package.json
{
  "name": "@repo/api-client",
  "exports": {
    ".": { "types": "./src/index.ts", "default": "./src/index.ts" }
  }
}

Next.js transpilePackages

// apps/web/next.config.ts
const config: NextConfig = {
  transpilePackages: [
    "@repo/api-client",
    "@t3-oss/env-core", "@t3-oss/env-nextjs",
  ],
}

Creating a New Package

1. Create directory structure:

   packages/[name]/
   ├── src/index.ts
   ├── package.json
   └── tsconfig.json
   

2. Package manifest:

   {
     "name": "@repo/[name]",
     "version": "0.0.0",
     "private": true,
     "type": "module",
     "exports": { ".": "./src/index.ts" },
     "scripts": { "build": "tsc", "dev": "tsc --watch" }
   }
   

3. TypeScript config:

   { "extends": "@repo/typescript-config/pkg.json", "include": ["src"], "exclude": ["node_modules"] }
   

4. Add to consumers:

   { "dependencies": { "@repo/[name]": "workspace:*" } }
   

5. Run pnpm install to link the new package.

Tooling Config Sharing

ESLint

// apps/backend/eslint.config.mjs
import nestConfig from "@repo/eslint-config/nest.mjs"
export default [...nestConfig]

TypeScript

// apps/web/tsconfig.json
{ "extends": "@repo/typescript-config/next.json" }

Prettier

// apps/web/package.json
{ "prettier": "@repo/prettier-config" }

Key Rules

1. Always use pnpm — never npm or yarn
2. Use workspace:* for internal package dependencies
3. Use pnpm catalog for shared version pinning
4. Packages MUST have index.ts — exception to no-barrel-files rule
5. Apps must NOT have barrel files — import directly from specific files
6. Run pnpm lint && pnpm typecheck before committing
7. Add transpilePackages in Next.js for workspace packages
8. Update .env.example when adding environment variables