Mode d’emploi
- Copiez la commande et examinez le paquet avant de l’installer dans votre environnement agent.
- Consultez le document original pour les outils, identifiants et environnements requis.
- Décrivez les entrées et le livrable souhaité ; comparez la sortie aux sources.
npx skills add https://github.com/giuseppe-trisciuoglio/developer-kit --skill turborepo-monorepoAvant de commencer
- L’installation n’inclut ni abonnement au modèle, ni quota API, ni accès aux fichiers.
- Étoiles et installations reflètent l’activité, pas un test indépendant de qualité ou de sécurité.
Rendu depuis le dépôt source en conservant titres, exemples, code, tableaux, liens et images.
Turborepo Monorepo
Overview
Provides guidance for Turborepo monorepo management: workspace creation, turbo.json task configuration, Next.js/NestJS integration, testing pipelines (Vitest/Jest), CI/CD setup, and build performance optimization.
When to Use
- Create or initialize Turborepo workspaces
- Configure
turbo.jsontasks with dependencies and outputs - Set up Next.js/NestJS apps in monorepo structure
- Configure Vitest/Jest test pipelines
- Build CI/CD workflows (GitHub Actions, GitLab CI)
- Implement remote caching with Vercel Remote Cache
- Optimize build times and cache hit ratios
- Debug task dependency or cache issues
- Migrate from other monorepo tools to Turborepo
Instructions
Workspace Creation
- Create a new workspace:
pnpm create turbo@latest my-workspace
cd my-workspace- Initialize in existing project:
pnpm add -D -w turbo- Create turbo.json in root (minimal config):
{
"$schema": "https://turborepo.dev/schema.json",
"pipeline": {
"build": { "dependsOn": ["^build"], "outputs": ["dist/**", ".next/**"] },
"lint": { "outputs": [] },
"test": { "dependsOn": ["build"], "outputs": ["coverage/**"] }
}
}- Add scripts to root package.json:
{ "scripts": { "build": "turbo run build", "dev": "turbo run dev", "lint": "turbo run lint", "test": "turbo run test", "clean": "turbo run clean" } }- Validate task graph before CI:
turbo run build --dry-run --filter=... # Verify task execution orderTask Configuration
- Configure tasks in
turbo.json:
{ "pipeline": { "build": { "dependsOn": ["^build"], "outputs": ["dist/**"] }, "test": { "dependsOn": ["build"], "outputs": ["coverage/**"] }, "lint": { "outputs": [] } } }- Run tasks:
turbo run build # All packages
turbo run lint test build # Multiple tasks
turbo run build --filter=web # Specific package- Parallel type checking (use transit nodes to avoid cache issues):
{ "pipeline": { "transit": { "dependsOn": ["^transit"] }, "typecheck": { "dependsOn": ["transit"] } } }- Validate before committing:
turbo run build --dry-run # Check task order and affected packagesFramework Integration
Next.js: outputs ".next/**" and env ["NEXT_PUBLIC_*"] - See references/nextjs-config.md
NestJS: outputs "dist/**", dev tasks with cache: false, persistent: true - See references/nestjs-config.md
Testing Setup
- Vitest configuration:
{
"pipeline": {
"test": {
"outputs": [],
"inputs": ["$TURBO_DEFAULT$", "vitest.config.ts"]
},
"test:watch": {
"cache": false,
"persistent": true
}
}
}- Run affected tests:
turbo run test --filter=[HEAD^]See references/testing-config.md for complete testing setup.
Package Configurations
- Create package-specific turbo.json:
{
"extends": ["//"],
"tasks": {
"build": {
"outputs": ["$TURBO_EXTENDS$", ".next/**"]
}
}
}See references/package-configs.md for detailed package configuration patterns.
CI/CD Setup
- GitHub Actions with validation checkpoints:
- name: Install dependencies
run: pnpm install
- name: Validate affected packages (dry-run)
run: pnpm turbo run build --filter=[HEAD^] --dry-run
# VALIDATE: Review output to confirm only expected packages will build
- name: Run tests
run: pnpm run test --filter=[HEAD^]
- name: Build affected packages
run: pnpm run build --filter=[HEAD^]
- name: Verify cache hits
run: pnpm turbo run build --filter=[HEAD^] --dry-run | grep "Cache"
# VALIDATE: Confirm cache hits for unchanged packages- Remote cache setup:
# Login to Vercel
npx turbo login
# Link repository
npx turbo linkSee references/ci-cd.md for complete CI/CD setup examples.
Task Properties Reference
| Property | Description | Example |
|---|---|---|
dependsOn | Tasks that must complete first | ["^build"] - dependencies first |
outputs | Files/folders to cache | ["dist/**"] |
inputs | Files for cache hash | ["src/**/*.ts"] |
env | Environment variables affecting hash | ["DATABASE_URL"] |
cache | Enable/disable caching | true or false |
persistent | Long-running task | true for dev servers |
outputLogs | Log verbosity | "full", "new-only", "errors-only" |
Dependency Patterns
^task- Run task in dependencies first (topological order)task- Run task in same package firstpackage#task- Run specific package's task
Filter Syntax
| Filter | Description |
|---|---|
web | Only web package |
web... | web + all dependencies |
...web | web + all dependents |
...web... | web + deps + dependents |
[HEAD^] | Packages changed since last commit |
./apps/* | All packages in apps/ |
Best Practices
Performance Optimization
- Use specific outputs - Only cache what's needed
- Fine-tune inputs - Exclude files that don't affect output
- Transit nodes - Enable parallel type checking
- Remote cache - Share cache across team/CI
- Package configurations - Customize per-package behavior
Caching Strategy
{
"pipeline": {
"build": {
"outputs": ["dist/**"],
"inputs": ["$TURBO_DEFAULT$", "!README.md", "!**/*.md"]
}
}
}Task Organization
- Independent tasks - No
dependsOn: lint, format, spellcheck - Build tasks -
dependsOn: ["^build"]: build, compile - Test tasks -
dependsOn: ["build"]: test, e2e - Dev tasks -
cache: false, persistent: true: dev, watch
Common Issues
Tasks not running in order
Problem: Tasks execute in wrong order
Solution: Check dependsOn configuration
{
"build": {
"dependsOn": ["^build"]
}
}Cache misses on unchanged files
Problem: Cache invalidating unexpectedly
Solution: Review globalDependencies and inputs
{
"globalDependencies": ["tsconfig.json"],
"pipeline": {
"build": {
"inputs": ["$TURBO_DEFAULT$", "!*.md"]
}
}
}Type errors after cache hit
Problem: TypeScript errors not caught due to cache
Solution: Use transit nodes for type checking
{
"transit": { "dependsOn": ["^transit"] },
"typecheck": { "dependsOn": ["transit"] }
}Examples
Example 1: Create New Workspace
Input: "Create a Turborepo with Next.js and NestJS"
pnpm create turbo@latest my-workspace
cd my-workspace
# Add Next.js app
pnpm add next react react-dom -F apps/web
# Add NestJS API
pnpm add @nestjs/core @nestjs/common -F apps/apiExample 2: Configure Testing Pipeline
Input: "Set up Vitest for all packages"
{
"pipeline": {
"test": {
"dependsOn": ["build"],
"outputs": ["coverage/**"],
"inputs": ["$TURBO_DEFAULT$", "vitest.config.ts"]
},
"test:watch": {
"cache": false,
"persistent": true
}
}
}Example 3: Run Affected Tests in CI
Input: "Only test changed packages in CI"
pnpm run test --filter=[HEAD^]Example 4: Debug Cache Issues
Input: "Why is my cache missing?"
# Dry run to see what would be executed
turbo run build --dry-run --filter=web
# Show hash inputs
turbo run build --force --filter=webConstraints and Warnings
- Node.js 18+ is required for Turborepo
- Package manager field required in root
package.json - Outputs must be specified for caching to work
- Persistent tasks cannot have dependents
- Windows: WSL or Git Bash recommended
- Remote cache requires Vercel account or self-hosted solution
- Large monorepos may need increased
concurrencysettings
Reference Files
For detailed guidance on specific topics, consult:
| Topic | Reference File |
|---|---|
| turbo.json template | references/turbo.json |
| Next.js integration | references/nextjs-config.md |
| NestJS integration | references/nestjs-config.md |
| Vitest/Jest/Playwright | references/testing-config.md |
| GitHub/CircleCI/GitLab CI | references/ci-cd.md |
| Package configurations | references/package-configs.md |


