Turborepo — AGENTS.md

# Turborepo — AGENTS.md

## Overview

Turborepo is a high-performance build system for JavaScript and TypeScript monorepos. It uses caching, task parallelization, and remote caching to speed up builds.

## Key Concepts

- **Pipeline**: Defines task dependencies and cache behavior in `turbo.json`.
- **Cache**: Tasks are cached by inputs. Unchanged outputs are replayed.
- **Remote Caching**: Share cache across machines with Vercel Remote Cache.
- **Package Graph**: Turborepo understands your workspace dependency graph.

## Repository Structure

```
crates/          # Rust implementation (turbo CLI)
packages/        # JS/TS packages
app/             # Next.js documentation app
examples/        # Starter templates
```

## Development

```bash
# Rust CLI development
cargo build
cargo test

# JS packages
pnpm install
pnpm build
pnpm test
```

## turbo.json Configuration

```json
{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "dist/**"]
    },
    "test": {
      "dependsOn": ["build"],
      "cache": false
    },
    "lint": {
      "outputs": []
    }
  }
}
```

## Best Practices for AI Agents

- Always run `turbo build` from the repo root, not individual packages.
- Use `--filter` to scope tasks to specific packages.
- Check `turbo.json` before modifying build scripts — task order matters.
- Never modify `.turbo/` cache directories.
- Use `turbo run lint --filter=...` for targeted linting.

## Adding a New Package

1. Create directory under `packages/`.
2. Add `package.json` with proper `name` (matching workspace convention).
3. Add to `pnpm-workspace.yaml` if not using glob patterns.
4. Define pipeline tasks in root `turbo.json`.