Add to an existing repository

Turborepo can be incrementally adopted in any repository, single or multi-package, to speed up the developer and CI workflows of the repository.

After installing turbo and configuring your tasks in turbo.json, you'll notice how caching helps you run tasks much faster.

Preparing a single-package workspace

A single-package workspace is, for example, what you get after running npx create-next-app or npm create vite. You don't need to do any extra work for Turborepo to handle your repo so you can jump to the first step below.

To learn more about Turborepo in single-package workspaces, visit the dedicated guide.

Preparing a multi-package workspace (monorepo)

turbo is built on top of Workspaces, a feature of the major package managers in the JavaScript ecosystem. This makes it easy to adopt in your existing codebase.

Note that you don't have to start running all your tasks for all your packages using turbo right away. You can start with a single task in just a few packages and incrementally add more tasks and packages as you get more familiar with Turborepo.

Adding Turborepo to your repository

We recommend you install turbo both globally and into your repository's root for the best developer experience.

```bash title="Terminal"
# Global install
pnpm add turbo --global
# Install in repository
pnpm add turbo --save-dev --workspace-root
```

```bash title="Terminal"
# Global install
yarn global add turbo
# Install in repository
yarn add turbo --dev
```

```bash title="Terminal"
# Global install
npm install turbo --global
# Install in repository
npm install turbo --save-dev
```

```bash title="Terminal"
# Global install
bun install turbo --global
# Install in repository
bun install turbo --dev
```

To learn more about why we recommend both installations, visit the Installation page.

Add a turbo.json file

In the root of your repository, create a turbo.json file.

We'll be using build and check-types tasks in this guide but you can replace these with other tasks that interest you, like lint or test.

<Tabs items={['Next.js', 'Vite']} storageKey="framework-preference"> <Tab value="Next.js">

{
  "$schema": "https://turborepo.dev/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "!.next/cache/**"]
    },
    "check-types": {
      "dependsOn": ["^check-types"]
    },
    "dev": {
      "persistent": true,
      "cache": false
    }
  }
}

For more information on configuring your turbo.json, see the Configuration Options documentation.

In your Next.js application, make sure you have a check-types script for turbo to run.

{
  "scripts": {
+   "check-types": "tsc --noEmit"
  }
}

Some Vite starters ship with a package.json that looks like this:

{
  "scripts": {
    "build": "tsc && vite build"
  }
}

We recommend splitting these into a check-types and build script so that turbo can run them in parallel.

{
  "scripts": {
    "build": "vite build",
    "check-types": "tsc --noEmit"
  }
}

In a multi-package workspace, you may also want to add a check-types script to one or more of your library packages to see how multiple scripts across different packages run with one turbo command.

Add .turbo to your .gitignore file. The turbo CLI uses these folders for persisting logs, outputs, and other functionality.

+ .turbo

Turborepo optimizes your repository using information from your package manager. To declare which package manager you're using, add a packageManager field to your root package.json if you don't have one already.

{
+  "packageManager": "[email protected]"
}

{
+  "packageManager": "[email protected]"
}

{
+  "packageManager": "[email protected]"
}

{
+  "packageManager": "[email protected]"
}

For multi-package workspaces, you'll need to configure your package manager to recognize your workspace structure.

The workspaces field tells your package manager which directories contain your packages. Common patterns include apps/* for applications and packages/* for shared libraries.

For more details on how to structure your repository, see Structuring a Repository.

You can now run the tasks you added to turbo.json earlier using Turborepo. Using the example tasks from above:

turbo build check-types

This runs the build and check-types tasks at the same time. The dependency graph of your Workspace will be used to run tasks in the right order.

turbo check-types build

You should see terminal output like this:

Tasks:    2 successful, 2 total
Cached:    2 cached, 2 total
Time:    185ms >>> FULL TURBO

Congratulations! You just built and type checked your code in milliseconds.

To learn more about how turbo makes this possible, check out the caching documentation.

Begin developing by running dev with turbo

In a multi-package workspace, you can run turbo dev to start the development tasks for all your packages at once.

turbo dev

You can also use a filter to focus on a specific package and its dependencies.

• You don't cache the outputs for a development task.
• There's only one development script so there's nothing to run in parallel.

Next steps

You're now up and running with Turborepo! To learn about more ways you can improve your workflow and get the most out of turbo, we recommend checking out the following pages:

• Enabling Remote Caching for development machines
• Enabling Remote Caching in CI
• Handling environment variables
• Filtering tasks