turborepo
Turborepo enables developers to orchestrate complex build and task workflows across monorepos with precision dependency resolution and smart caching layers. Set up efficient pipelines that automatically skip redundant work and scale seamlessly as your project grows. Ideal for teams managing multiple interconnected packages who need reproducible, high-performance builds.
Turborepo enables developers to organize monorepos by creating a root `turbo.json` configuration file and structuring your workspace into `apps/` and `packages/` directories. Each app or package should have its own `package.json`. In your root `package.json`, use workspaces (npm, yarn, or pnpm) to link all packages together. Turborepo then automatically discovers these packages and understands their interdependencies, allowing you to run tasks across your entire monorepo with a single command like `turbo run build`.
AI-generated summary based on this skill's SKILL.md
Install
bklit/bklit-ui/turborepo · repository language: TypeScript
git clone https://github.com/bklit/bklit-ui
cp -r bklit-ui/.agents/skills/turborepo ~/.claude/skills/turborepoFrequently asked questions
AI-generated answers based on this skill's SKILL.md and metadata
How do I set up turborepo monorepo structure with apps and packages?
Turborepo enables developers to organize monorepos by creating a root `turbo.json` configuration file and structuring your workspace into `apps/` and `packages/` directories. Each app or package should have its own `package.json`. In your root `package.json`, use workspaces (npm, yarn, or pnpm) to link all packages together. Turborepo then automatically discovers these packages and understands their interdependencies, allowing you to run tasks across your entire monorepo with a single command like `turbo run build`.
What are turborepo task configuration and dependencies best practices?
Turborepo task configuration and dependencies are defined in `turbo.json` using the `pipeline` object. For each task, specify its `dependsOn` array to declare which tasks must run first—both within the same package (`^taskname`) and in dependent packages. Enable caching by setting `outputs` to specify which directories to cache. Use `inputs` to define which files trigger cache invalidation. This precision dependency resolution ensures tasks run in the correct order and Turborepo skips redundant work when outputs haven't changed.
How do I run only changed packages with --affected in turborepo?
Turborepo's `--affected` flag intelligently identifies which packages have changed since a baseline (typically your main branch) and runs tasks only on those packages and their dependents. Use `turbo run build --affected --since=origin/main` to compare against your main branch. This is especially powerful in CI/CD workflows where you want to avoid rebuilding unchanged packages. Turborepo analyzes your dependency graph to determine not just which packages changed, but which other packages depend on them and therefore need rebuilding.
Why are turborepo environment variables not working in my build tasks?
Turborepo environment variables issues often stem from incorrect cache configuration. If you reference environment variables in your build but don't declare them in `turbo.json`, Turborepo may serve a cached result that was built with different environment values. Declare environment variables in the `env` array within your task's pipeline configuration so Turborepo knows to invalidate the cache when they change. Additionally, ensure variables are exported in your shell before running `turbo run`, and verify they're not being filtered by your CI/CD platform's secret masking.
How do I integrate turborepo into CI/CD workflows with remote caching?
Turborepo integrates into CI/CD by using `turbo run` commands with `--affected` to build only changed packages. For remote caching, authenticate with `turbo login`, then enable remote caching in your `turbo.json` or via environment variables. In GitHub Actions, run `turbo run build --affected` after checking out your code; Turborepo automatically uploads cache artifacts to your configured remote cache backend. This allows subsequent CI runs and developer machines to reuse cached outputs, dramatically reducing build times across your entire team.
What common anti-patterns should I avoid in turborepo monorepos?
Turborepo users should avoid several anti-patterns: don't define root-level task scripts that bypass the pipeline—always use `turbo run` so caching and dependency ordering work correctly. Avoid incorrect filter syntax; use `--filter=@scope/package` or `--filter=./packages/mypackage` precisely. Don't forget to declare `outputs` in your pipeline configuration, or caching won't function. Resist putting all code in a single package; instead, enforce architectural boundaries by organizing code into separate internal packages. Finally, don't ignore cache misses—use `turbo run build --no-cache` to debug and ensure your `inputs` and `env` declarations accurately reflect what affects your build.
SKILL.md
rendered from the published skill — quoted content, verbatim
Turborepo Skill
Build system for JavaScript/TypeScript monorepos. Turborepo caches task outputs and runs tasks in parallel based on dependency graph.
IMPORTANT: Package Tasks, Not Root Tasks
DO NOT create Root Tasks. ALWAYS create package tasks.
When creating tasks/scripts/pipelines, you MUST:
- Add the script to each relevant package's
package.json - Register the task in root
turbo.json - Root
package.jsononly delegates viaturbo run <task>
DO NOT put task logic in root package.json. This defeats Turborepo's parallelization.
```json // DO THIS: Scripts in each package // apps/web/package.json { "scripts": {
(truncated - see the full file via the links below)
Read as markdown · JSON record · Browse the source repository
File tree — 15 files
.agents/skills/turborepo/SKILL.md
.agents/skills/turborepo/command/turborepo.md
.agents/skills/turborepo/references/best-practices/dependencies.md
.agents/skills/turborepo/references/best-practices/packages.md
.agents/skills/turborepo/references/best-practices/structure.md
.agents/skills/turborepo/references/caching/gotchas.md
.agents/skills/turborepo/references/caching/remote-cache.md
.agents/skills/turborepo/references/ci/github-actions.md
.agents/skills/turborepo/references/ci/patterns.md
.agents/skills/turborepo/references/ci/vercel.md
.agents/skills/turborepo/references/cli/commands.md
.agents/skills/turborepo/references/configuration/global-options.md
.agents/skills/turborepo/references/configuration/gotchas.md
.agents/skills/turborepo/references/configuration/tasks.md
.agents/skills/turborepo/references/environment/gotchas.md