OpenWikivercel/turborepo

Getting Started

Purpose and Scope

This page gives a first learning path for people who are new to Turborepo and want to move from installation to a useful repository workflow. Turborepo’s beginner path is not only about running one command; it is about understanding the smallest set of primitives that make a monorepo fast: packages, tasks, task dependencies, cacheable outputs, development processes, and CI execution. The official getting-started flow begins with installing the turbo CLI, then choosing whether to create a new repository, start from an example, follow the in-depth repository guides, or add Turborepo to an existing codebase.

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

A good first session should end with a repository that can run ordinary package scripts through Turborepo rather than through a one-package-at-a-time workspace command. The configuring guide defines a task as a script that Turborepo runs, and it explains that tasks are registered in the root configuration so Turborepo can search packages for matching scripts. The running guide then turns that configuration into daily commands, recommending root package scripts for repeated workflows and global turbo for on-demand local or CI usage.

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

Relevant Source Files

  • apps/docs/content/docs/crafting-your-repository/configuring-tasks.mdx — Defines the beginner mental model for tasks, the root turbo.json file, task names, dependsOn, outputs, and package-graph-aware ordering.
  • apps/docs/content/docs/crafting-your-repository/running-tasks.mdx — Explains how users execute configured tasks through package scripts, global turbo, automatic package scoping, and filters.
  • apps/docs/content/docs/crafting-your-repository/caching.mdx — Introduces local caching, cache misses, cache hits, deterministic task expectations, and remote cache setup commands.
  • apps/docs/content/docs/crafting-your-repository/constructing-ci.mdx — Shows how the same task model carries into CI with Remote Caching, TURBO_TOKEN, TURBO_TEAM, filters, affected work, and Docker-related workflows.
  • apps/docs/content/docs/crafting-your-repository/creating-an-internal-package.mdx — Grounds the first shared-code workflow by explaining Internal Packages, package.json discovery, package names, exports, and workspace dependencies.
  • apps/docs/content/docs/crafting-your-repository/developing-applications.mdx — Describes development tasks, persistent processes, cache disabling for dev, setup tasks, filters, watch mode, and the terminal UI.

Core Primitives

Start by treating each workspace package as a participant in a larger graph. Internal packages are the shared libraries and utilities that applications depend on, and Turborepo understands their relationships from package metadata. That package graph lets the tool build dependencies before dependents when task relationships request it. For a newcomer, this means the repository layout and package names matter: a shared package must be discoverable, must have a package manifest, and should expose the code that applications import in the same way any other workspace dependency would.

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

Tasks are the second primitive. A task is registered in the root configuration, then matched to scripts in package manifests. A beginner might define a build task and assume Turborepo now has everything it needs, but the task guide warns that a bare task will run matching scripts in parallel without cached outputs. The next step is to add ordering and output information. Use dependency-aware ordering when libraries must finish before applications, then declare generated files so future runs can restore work instead of rebuilding everything.

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

Caching is the third primitive and the first major performance payoff. Turborepo fingerprints known inputs, checks whether the same work has already been done, and restores outputs from the local cache when possible. The caching guide emphasizes that tasks should be deterministic: if a task can produce different results from inputs Turborepo does not know about, cache behavior may surprise you. New users should therefore learn caching together with inputs, outputs, and environment-variable handling rather than treating it as an invisible speed feature.

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

First Workflow

A practical first workflow is to create or open a workspace, add a root configuration, and register the tasks you expect every package to provide. The official path recommends installing turbo globally for convenient terminal usage, while the repository-crafting guides show that repeated commands should also be placed in the root package scripts. Keeping Turborepo commands at the root avoids recursive calls from package-level scripts and gives the team one entry point for local development and CI. This pattern makes the monorepo feel like one coordinated system instead of a folder of unrelated projects.

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

npm install turbo --global
# or
pnpm add turbo --global
# or
yarn global add turbo
{
  "scripts": {
    "dev": "turbo run dev",
    "build": "turbo run build",
    "test": "turbo run test",
    "lint": "turbo run lint"
  }
}

After the root scripts exist, run one task through your package manager and one task directly with global turbo. The running guide explains that turbo can automatically scope commands when executed from inside a package directory, which is useful when you are focused on one app. Filters give explicit control when you need a subset by package, directory, or source-control changes. This is the same command model you will later use in CI, so the time spent learning local filters and multi-task execution directly transfers to production pipelines.

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

turbo run build
turbo build --filter=@repo/ui
cd apps/docs
turbo build

Development, Caching, and CI

Development tasks need different defaults from build tasks because they are usually long-running watchers or servers. The developing applications guide shows a dev task with caching disabled and persistence enabled. Disabling caching is appropriate because a dev server’s value is the live process, not a reusable output directory. Marking the task persistent tells Turborepo and its terminal UI that the process is long-lived and interactive, and it also prevents accidental dependency declarations on work that will not naturally exit.

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

{
  "tasks": {
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

Once ordinary builds work locally, run them twice to observe the cache. The first run should miss because Turborepo has not seen that input fingerprint before. The second run can restore results from the local cache when the known inputs are unchanged. Remote Caching extends the same idea across teammates and CI machines. The caching guide introduces login and link commands for connecting a repository to a remote provider, while the CI guide identifies the environment variables CI needs to read and write shared artifacts.

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

npx create-turbo@latest
turbo build
turbo build
npx turbo login
npx turbo link

In CI, begin with the same registered tasks rather than inventing a separate pipeline vocabulary. The constructing CI guide frames Turborepo as a way to accelerate builds, lints, tests, and other required checks through parallelization and Remote Caching. Configure the remote cache token and team name in the vendor environment, then run the same build, lint, and test tasks used locally. When the job needs less work, add filters or affected-task selection, remembering that Git-history-based filtering only works when the CI checkout includes the necessary history.

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

Starter Checklist and Next Steps

Use this checklist as the smallest complete beginner path: install the CLI, choose a new template or existing repository, define tasks in the root configuration, add root package scripts, declare build ordering and outputs, run a local build twice, configure dev as persistent and uncached, and finally move the same task commands into CI with Remote Caching. If your next problem is repository shape, read the internal package and structuring guidance. If your next problem is speed, continue with caching, task configuration, filters, and CI vendor guides.

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

Ask a question...