---
title: Getting Started
---

import Callout from "../../components/callout";
import Beta from "../../components/beta";

# Getting Started with Turborepo

## Clone an example or starter monorepo

If you're starting a brand new monorepo, you can get started with a single command.

```sh
npx create-turbo@latest
```

Follow the prompts to bootstrap a brand new Turborepo.

To see more examples and starters, have a look at the [example directory on GitHub](https://github.com/vercel/turborepo/blob/main/examples)

## Add Turborepo to your existing monorepo

Turborepo was designed to be incrementally adopted. Adding it to an existing monorepo takes just a few minutes.

Turborepo works with [Yarn v1](https://classic.yarnpkg.com/lang/en/), [NPM](https://npmjs.com), and [PNPM](https://pnpm.io/) workspaces. The `turbo` CLI works on the following operating systems.

- macOS darwin 64-bit (Intel), Arm 64-bit (Apple Silicon)
- Linux 32-bit, 64-bit, Arm, Arm 64-bit, mips64le, ppc64le
- Windows 32-bit, 64-bit
- FreeBSD 64-bit, FreeBSD Arm 64-bit

### Install `turbo`

Add `turbo` as a development dependency in the root of your project.

### Yarn

```bash
yarn add turbo -W --dev
```

### NPM

```bash
npm install turbo -D
```

### PNPM

```bash
pnpm add turbo -D
```

The `turbo` package is a little shell that will install the proper `@turborepo/*` packages.

### Add `turbo` to `package.json`

In your root `package.json`, add a key `turbo`. If your git repo's base branch is NOT `origin/master` then you need to specify a `baseBranch` too (for example, our's is set to `origin/main`).

```json
{
  "turbo": {
    "baseBranch": "origin/main"
  }
}
```

### Create a `pipeline`

In your `package.json`, add the commands you want to "turbocharge" to your pipeline.

Your pipeline both defines the way in which your NPM `package.json` scripts relate to each other, and configures cache artifacts for those scripts. These relationships and cache settings are then fanned out and applied to all package tasks across your entire monorepo.

```json
{
  "turbo": {
    "baseBranch": "origin/main",
    "pipeline": {
      "build": {
        "dependsOn": ["^build"],
        "outputs": [".next/**"]
      },
      "test": {
        "dependsOn": ["^build"],
        "outputs": []
      },
      "lint": {
        "outputs": []
      },
      "dev": {
        "cache": false
      }
    }
  }
}
```

In the above example, the `build` and `test` tasks are dependant on their packages `dependencies` and `devDependencies` being built first, this is denoted with the `^` prefix.

For each script in each workspace's `package.json`, Turborepo will cache files outputted to `dist/**` and `build/**` folders by default if an override isn't added. Using the [`outputs`](./features/caching#configuring-cache-outputs-1) array allows you to override the default cache folders,
like in the example above, where the `.next/**` folder is selected to be the default cache folder for the `build` task. Turborepo will automatically record and cache logs to `.turbo/turbo-<script>.log` for you, so you don't ever need to specify that in the `outputs` array.

Finally, the `dev` task has its caching disabled using the `cache` key with a value of `false`.

See the [`Pipelines`](./features/pipelines) documentation for more details on how to configure your pipeline.

### Edit `.gitignore`

Next, add `.turbo` to your `.gitignore` file. The CLI uses these folders for logs and certain task outputs.

```diff
+ .turbo
```

Make sure that your task artifacts (the files you want to be cached) are also ignored. As a rule, any files/folder that you want cached should be gitignored.

```diff
+ build/**
+ dist/**
+ .next/**
```

### Ensure workspaces are configured

If you are moving from another tool to [Yarn workspaces](https://classic.yarnpkg.com/en/docs/workspaces/), be sure to also specify all `workspaces` in your `package.json`. The convention we follow is for applications to go into the `/apps` folder and packages to go in `/packages` folders.

```diff
{
+ "workspaces": [
+    "packages/*",
+    "apps/*"
+  ]
}
```

Now re-run your NPM client's install command just to be sure. You should be good to go now.

## Run stuff!

To build with your freshly installed `turbo`, type the following:

### Yarn

```sh
yarn turbo run build
```

Now run it again. Depending on your monorepo setup, some stuff might already be caching properly. If not, no worries! In the next sections, we'll discuss how `turbo` works, how `scope` works, and then how to get caching working after that.

## Setup Remote Caching <Beta/>

A major key 🔑 to Turborepo's speed is that it is both lazy and efficient—it does the least amount of work possible and it tries to never redo work that's already been done before.
At the moment, Turborepo caches your tasks on your local filesystem (i.e. "single-player mode," if you will). However, what if there was a way to take advantage of the computational work done by your teammates or your CI (i.e. "co-op multiplayer mode")? What if there was a way to teleport and share a single cache across machines? Almost like a "Dropbox" for your Turborepo cache.

> Remote Caching has entered the chat.

Turborepo can use a technique known as Remote Caching to share cache artifacts across machines for an additional speed boost.

<Callout type="error">
  Remote Caching is a powerful feature of Turborepo, but with great power comes great responsibility. Make sure you are caching correctly first and double check handling of environment variables. Please also remember Turborepo treats logs as artifacts, so be aware of what you are printing to the console.
</Callout>

### Link Your Turborepo to Your Remote Cache

As part of Turborepo's initial public launch, [Vercel](https://vercel.com?utm_source=turborepo.org&utm_medium=referral&utm_campaign=docs-link) is offering **free remote caching** on all accounts with zero-configuration needed.

#### Using Remote Caching for Local development

If you want to link your local turborepo to your Remote Cache you do so by first authenticating the Turborepo CLI with your Vercel account:

```sh
npx turbo login
```

Next, you can link your turborepo to your remote cache by running the following command:

```
npx turbo link
```

Once enabled, make some changes to a package or application you are currently caching and run tasks against it with `turbo run`.
Your cache artifacts will now be stored locally _and_ in your Remote Cache. To verify that this worked, delete your local Turborepo cache:

```sh
rm -rf ./node_modules/.cache/turbo
```

Now run the same build again. If things are working properly, `turbo` should not execute tasks locally, but rather download both the logs and artifacts from your Remote Cache and replay them back to you.
