Skill: goldath/monorepo-turborepo (version 1.0.0)

--- name: monorepo-turborepo description: Use when setting up or managing a Turborepo-based monorepo. Covers workspace configuration, task pipelines, caching strategies, shared packages, and CI/CD integration for multi-package repositories with Turborepo. --- # Monorepo with Turborepo A practical guide to building and managing scalable monorepos using Turborepo. ## When to Use - Setting up a new monorepo with multiple apps/packages - Optimizing build/test pipelines with caching - Sharing UI components, utilities, or configs across apps - Configuring CI for monorepo with selective builds ## Core Workflow ### 1. Initialize Monorepo ```bash npx create-turbo@latest my-monorepo cd my-monorepo ``` **Workspace layout:** ``` my-monorepo/ ├── apps/ │ ├── web/ # Next.js app │ └── docs/ # Docusaurus ├── packages/ │ ├── ui/ # Shared components │ ├── config/ # Shared ESLint/TS configs │ └── utils/ # Shared utilities ├── turbo.json └── package.json ``` ### 2. Configure turbo.json Pipeline ```json { "$schema": "https://turbo.build/schema.json", "tasks": { "build": { "dependsOn": ["^build"], "outputs": [".next/**", "!.next/cache/**", "dist/**"] }, "test": { "dependsOn": ["^build"], "outputs": ["coverage/**"] }, "lint": { "outputs": [] }, "dev": { "cache": false, "persistent": true }, "type-check": { "dependsOn": ["^build"], "outputs": [] } } } ``` ### 3. Package.json Root Config ```json { "name": "my-monorepo", "private": true, "workspaces": ["apps/*", "packages/*"], "scripts": { "build": "turbo build", "dev": "turbo dev", "lint": "turbo lint", "test": "turbo test", "type-check": "turbo type-check", "clean": "turbo clean && rm -rf node_modules" }, "devDependencies": { "turbo": "latest" } } ``` ### 4. Shared Package Setup (packages/ui) ```json // packages/ui/package.json { "name": "@repo/ui", "version": "0.0.1", "exports": { "./*": { "import": "./src/*.tsx", "require": "./src/*.tsx" } }, "scripts": { "build": "tsc", "lint": "eslint src/", "dev": "tsc --watch" } } ``` ### 5. Remote Caching (Vercel) ```bash npx turbo login npx turbo link ``` Or with custom remote cache: ```bash turbo build --api="https://your-cache-server.com" --[REDACTED_SECRET]" --team="your-team" ``` ### 6. Selective Builds (Filter) ```bash # Build only affected packages turbo build --filter=...[HEAD^1] # Build specific app and its dependencies turbo build --filter=web... # Exclude a package turbo build --filter=!docs ``` ### 7. CI/CD Integration (GitHub Actions) See `references/ci-github-actions.yml` for a complete workflow. ## Key Principles - **`^` prefix** in `dependsOn` means "build all dependencies first" - **`outputs`** defines what gets cached; be explicit - **`cache: false`** for dev/watch tasks - **`persistent: true`** for long-running processes - Always define `exports` in package.json for shared packages ## Troubleshooting | Issue | Solution | |-------|----------| | Cache miss every run | Check `outputs` paths are correct | | Circular dependency | Use `turbo graph` to visualize | | Package not found | Verify `workspaces` glob in root package.json | | Slow cold build | Enable remote caching |


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)