OpenWikivercel/turborepo

Crafting Your Repository

Purpose and Scope

The Crafting Your Repository section is the bridge between learning Turborepo concepts and making concrete design choices in a real workspace. Its overview describes monorepo architecture as a careful process and frames these guides as a step-by-step path for designing, building, and optimizing a Turborepo repository. The reader problem is not just how to run turbo; it is how to shape packages, scripts, cache boundaries, development servers, and CI pipelines so that a multi-package workspace makes every team faster rather than adding coordination cost.

Sources: apps/docs/content/docs/crafting-your-repository/index.mdx

In this section, a monorepo means a multi-package workspace where applications and libraries live together and are coordinated by package-manager metadata plus Turborepo configuration. The official sequence starts with repository structure and dependency management, then moves into internal packages, task configuration, task execution, caching, application development, environment variables, CI, upgrades, and repository understanding. The overview explicitly says the guides build on previous knowledge but can be read independently, which is important for teams adopting Turborepo incrementally inside an existing repository.

Sources: apps/docs/content/docs/crafting-your-repository/index.mdx

This page should be read as an orientation layer rather than a replacement for the individual guides. Use it to decide which design question you are answering first: where code should live, how code should be shared, how tasks should be ordered, what outputs should be cached, how developers should run long-lived processes, or how CI should avoid repeating local work. Each of those questions maps to a source-backed guide in this section, and each guide assumes the same core model: Turborepo learns package relationships from the workspace and task relationships from turbo.json.

Sources: apps/docs/content/docs/crafting-your-repository/index.mdx, apps/docs/content/docs/crafting-your-repository/configuring-tasks.mdx

Relevant Source Files

  • apps/docs/content/docs/crafting-your-repository/index.mdx — Defines the section purpose, reader path, related links, and the ordered “From zero to turbo” guide sequence.
  • apps/docs/content/docs/crafting-your-repository/caching.mdx — Explains task caching, local cache restoration, remote caching setup, deterministic task assumptions, and cache troubleshooting themes.
  • apps/docs/content/docs/crafting-your-repository/configuring-tasks.mdx — Defines tasks as scripts Turborepo runs, introduces the root turbo.json, and explains task dependencies, outputs, and parallel execution.
  • apps/docs/content/docs/crafting-your-repository/constructing-ci.mdx — Shows how CI pipelines use Remote Caching, TURBO_TOKEN, TURBO_TEAM, task filtering, affected work, and Docker-oriented flows.
  • apps/docs/content/docs/crafting-your-repository/creating-an-internal-package.mdx — Demonstrates creating an internal package and explains how package metadata makes shared code discoverable in the Package Graph.
  • apps/docs/content/docs/crafting-your-repository/developing-applications.mdx — Documents long-running development tasks, terminal UI behavior, watch mode, setup tasks, and package filtering for application development.

System-to-Code Mapping

The overview page is intentionally a routing document. Its frontmatter identifies the page as an overview with the summary “Step-by-step guides for designing, building, and optimizing a monorepo with Turborepo,” and its cards establish the intended progression. The early cards answer repository-shape questions: structure the repository, manage dependencies, and create an internal package. The middle cards answer execution questions: configure tasks, run tasks, and cache work. The later cards answer operational questions: develop applications, account for environment variables, construct CI, upgrade, and understand the repository.

Sources: apps/docs/content/docs/crafting-your-repository/index.mdx

The internal-package guide gives the first concrete package-design example. It describes Internal Packages as building blocks for sharing code and functionality across the repo, and it states that Turborepo automatically understands relationships between those packages using dependencies in package.json. The example creates ./packages/math, gives it a package name such as @repo/math, defines dev and build scripts, exports compiled entry points, and depends on shared TypeScript configuration using workspace protocol syntax. That turns package design into something Turborepo can reason about.

Sources: apps/docs/content/docs/crafting-your-repository/creating-an-internal-package.mdx

The task-configuration guide turns package relationships into execution relationships. It defines a task as a script that Turborepo runs and explains that each key in the root turbo.json tasks object can be executed by turbo run. Turborepo searches packages for matching package.json scripts, parallelizes work where it can, and uses dependsOn to express ordering constraints. The guide’s build example uses dependsOn: ["^build"], where the caret microsyntax means dependency packages should build before the package that depends on them.

Sources: apps/docs/content/docs/crafting-your-repository/configuring-tasks.mdx

Caching completes the loop by teaching Turborepo what work can be reused. The caching guide states that Turborepo restores task results from cache using a fingerprint of known inputs from the first run. A first run of a task such as turbo build produces a cache miss because the repository has not seen that set of inputs before; the next identical run can restore outputs rather than rebuilding from zero. The guide also emphasizes the deterministic-task assumption: if a task can produce different outputs from the inputs Turborepo knows about, caching may not behave as expected.

Sources: apps/docs/content/docs/crafting-your-repository/caching.mdx

Design Path: From Workspace to Fast Feedback

A practical adoption path starts with package boundaries. Applications are the deployable ends of the workspace, while internal and library packages hold shared code that applications consume. The repository-crafting overview points readers to structuring and dependency-management guides before creating internal packages because package placement and dependency declarations become the Package Graph. If those boundaries are unclear, later task configuration becomes harder: ^build only helps when dependencies accurately represent which packages must be prepared before another package can run its own build.

Sources: apps/docs/content/docs/crafting-your-repository/index.mdx, apps/docs/content/docs/crafting-your-repository/creating-an-internal-package.mdx

After boundaries are clear, define task patterns in the root turbo.json. Start by registering task names that correspond to scripts already present in package-level package.json files. Then add the relationships that would otherwise be hidden in shell command chains. The configuring guide contrasts sequential workspace commands such as running lint, build, and test one after another with turbo run lint build test, where independent work can run in parallel. The repository decision is to encode real prerequisites, not to serialize everything defensively.

Sources: apps/docs/content/docs/crafting-your-repository/configuring-tasks.mdx

Next, decide what each task produces and whether those results should be cached. Build and code-generation tasks usually have concrete outputs; development servers usually do not. The caching guide shows the local cache in .turbo/cache and describes Remote Caching as the way to share cached task outputs with teammates and CI. The development guide then gives the contrasting configuration for a long-lived dev task: set cache to false and persistent to true so the terminal UI treats it as an interactive process and Turborepo prevents other tasks from depending on a command that will not exit.

Sources: apps/docs/content/docs/crafting-your-repository/caching.mdx, apps/docs/content/docs/crafting-your-repository/developing-applications.mdx

Finally, carry the same model into CI. The constructing-CI guide says builds, lints, tests, and other pipeline tasks can be accelerated through parallelization and Remote Caching. CI should not be a separate mental model from local development: the same tasks registered in turbo.json can run on CI machines. The guide also calls out task filtering by package, directory, or Git history, plus affected execution, as ways to focus work on the relevant subset of the Package Graph when source-control history is available.

Sources: apps/docs/content/docs/crafting-your-repository/constructing-ci.mdx

Core Primitives

The core primitives in this section are packages, tasks, cache entries, development processes, and CI environment credentials. A package is discovered through workspace structure and package metadata; an internal package becomes useful when its name, exports, scripts, and dependencies make it importable by other packages. A task is a named script registered in turbo.json and executed by turbo run. A task edge, expressed with dependsOn, says what must complete first. A cache entry is the reusable result of a deterministic task for a known fingerprint of inputs.

Sources: apps/docs/content/docs/crafting-your-repository/creating-an-internal-package.mdx, apps/docs/content/docs/crafting-your-repository/configuring-tasks.mdx, apps/docs/content/docs/crafting-your-repository/caching.mdx

A development process is a special kind of task because it is long-running and interactive. The development guide recommends configuring dev with cache: false and persistent: true, then running it with turbo dev. Setup work can still be modeled explicitly with dependencies, including root tasks such as //#dev:setup, and developers can narrow the run with turbo dev --filter=web. This preserves the repository-wide graph while letting one engineer focus on one application and the packages needed for that application.

Sources: apps/docs/content/docs/crafting-your-repository/developing-applications.mdx

A CI credential is not a task, but it is part of the operational primitive set for Remote Caching. The CI guide names TURBO_TOKEN as the bearer token used to access Remote Cache and TURBO_TEAM as the account name associated with the repository. Once those values are available, CI can hit cache when running tasks through turbo. For Vercel Remote Cache, the guide notes that Vercel’s built-in CI/CD is connected automatically, while other CI vendors can use tokens and the same task commands.

Sources: apps/docs/content/docs/crafting-your-repository/constructing-ci.mdx

Implementation Details and Examples

A minimal task-configuration example starts by adding a root turbo.json and declaring tasks under tasks. The configuring guide warns that a completely empty build task will run matching scripts in parallel but will not cache file outputs, which can quickly lead to errors. The first meaningful improvement is usually ordering: library package builds should complete before application package builds. The guide expresses that with the following shape, then separately directs readers to specify outputs so caching can safely restore build artifacts.

Sources: apps/docs/content/docs/crafting-your-repository/configuring-tasks.mdx

{
  "tasks": {
    "build": {
      "dependsOn": ["^build"]
    }
  }
}

Development tasks deliberately look different from build tasks. They are meant to keep running while code changes, so the guide disables caching and marks them persistent. If setup work is required before development begins, model that setup as another task rather than hiding it in an ad hoc shell command. This keeps the workflow visible to Turborepo and to other developers reading the repository configuration.

Sources: apps/docs/content/docs/crafting-your-repository/developing-applications.mdx

{
  "tasks": {
    "dev": {
      "cache": false,
      "persistent": true,
      "dependsOn": ["//#dev:setup"]
    },
    "//#dev:setup": {
      "outputs": [".codegen/**"]
    }
  }
}

Remote cache setup has both local and CI forms. Locally, the caching guide shows authenticating with npx turbo login and linking the repository with npx turbo link; after that, Turborepo can send task outputs to the remote cache and restore them later. In CI, the constructing-CI guide emphasizes environment variables instead: provide TURBO_TOKEN and TURBO_TEAM, then run the same registered tasks. The design principle is that cache sharing should reduce duplicate work without changing what the tasks mean.

Sources: apps/docs/content/docs/crafting-your-repository/caching.mdx, apps/docs/content/docs/crafting-your-repository/constructing-ci.mdx

Execution Flow

A healthy crafted repository follows a predictable flow. First, create or identify packages and declare dependencies between them in package.json. Second, register task names in the root turbo.json so Turborepo can find matching package scripts. Third, add task dependencies such as ^build so package-dependency order is respected. Fourth, declare outputs for cacheable work and avoid caching long-lived development tasks. Fifth, run tasks locally, enable Remote Caching when team-wide reuse matters, and bring the same commands into CI with the needed remote-cache credentials.

Sources: apps/docs/content/docs/crafting-your-repository/creating-an-internal-package.mdx, apps/docs/content/docs/crafting-your-repository/configuring-tasks.mdx, apps/docs/content/docs/crafting-your-repository/caching.mdx, apps/docs/content/docs/crafting-your-repository/constructing-ci.mdx

When troubleshooting or reviewing a repository design, inspect it in the same order. If a task runs too early, check package dependencies and dependsOn. If a build repeats unnecessarily, check whether outputs and inputs are modeled and whether the task is deterministic. If development feels noisy, use filtering and persistent task configuration to focus on one application. If CI is slow, confirm Remote Cache credentials, source-control history for Git-based filters, and whether the pipeline is running the same task names developers run locally.

Sources: apps/docs/content/docs/crafting-your-repository/configuring-tasks.mdx, apps/docs/content/docs/crafting-your-repository/caching.mdx, apps/docs/content/docs/crafting-your-repository/developing-applications.mdx, apps/docs/content/docs/crafting-your-repository/constructing-ci.mdx

Next Steps

Continue with the repository-crafting guides in the order presented by the overview when you are designing a new workspace: structure the repository, manage dependencies, create an internal package, configure tasks, run tasks, and then tune caching and development workflows. If you are adopting Turborepo in an existing repository, start at the guide that matches your current bottleneck, but keep the sequence in mind. Most performance wins come from aligning package boundaries, task dependencies, cache outputs, and CI execution rather than treating them as isolated features.

Sources: apps/docs/content/docs/crafting-your-repository/index.mdx

Ask a question...