Turborepo Tutorial: Build Faster JavaScript and TypeScript

Turborepo is a build system from Vercel that speeds up JavaScript and TypeScript monorepos. It caches task outputs based on file content, runs tasks like build, lint, and test in parallel, and shares that cache across your whole team through Remote Caching. Result: repeat builds that took minutes often finish in under a second.

TL;DR Summary

• Turborepo manages tasks across multiple packages in one repository (a monorepo).
• It skips work it has already done by caching build, test, and lint results.
• A single config file, turbo.json, controls how your tasks run and depend on each other.
• Remote Caching lets your whole team and CI pipeline share the same cache.
• You can be running your first cached build in under ten minutes.

If you have ever waited five minutes for a build to finish, just to find out only one file actually changed, you already know the problem Turborepo solves. Most teams handle multiple apps and shared packages inside one repository, and every commit ends up rebuilding code that never changed.

This Turborepo tutorial walks you through setting up a real project, understanding turbo.json, running your first cached build, and turning on Remote Caching so your team stops rebuilding the same code over and over.

What is Turborepo?

Turborepo is a high performance build system for JavaScript and TypeScript codebases, built in Rust and maintained by Vercel. It was originally created by Jared Palmer and joined Vercel in 2021.

Instead of running every script in every package every time, Turborepo looks at what actually changed. It hashes your source files, dependencies, and environment variables, then checks if it has already produced that exact output before. If it has, it restores the result instantly instead of rebuilding.

Why Teams Move to Turborepo

Without a tool like this, a monorepo gets painful fast. One small change in a shared utility package can force a full rebuild of every app that depends on it, even ones that did not actually need to change.

Turborepo fixes that by running independent tasks in parallel, caching anything it has already built, and rebuilding only the packages your change actually affects. A CI run that used to take ten minutes can finish in under a minute on a cache hit.

Setting Up Your First Turborepo Project

You do not need an existing project to try this. Run the official starter command and follow the prompts:

npx create-turbo@latest

You will be asked to name your folder and pick a package manager, npm, Yarn, pnpm, or Bun all work. Once it finishes, you get a ready made structure:

my-turborepo/

├── apps/

│   ├── web/

│   └── docs/

├── packages/

│   ├── ui/

│   └── typescript-config/

├── package.json

└── turbo.json

Notice the split: apps holds your applications, and packages holds shared code they depend on, like a UI library or shared config. This split is what lets Turborepo build a dependency graph.

Understanding turbo.json

This is where the real configuration lives. Open turbo.json in your new project and you will see a tasks object:

//json

{

  "$schema": "https://turbo.build/schema.json",

  "tasks": {

    "build": {

      "dependsOn": ["^build"],

      "outputs": ["dist/**", ".next/**"]

    },

    "lint": {

      "outputs": []

    },

    "dev": {

      "cache": false,

      "persistent": true

    }

  }

}

A quick note if you have read older tutorials: Turborepo 2.0 renamed the old pipeline key to tasks. If you spot pipeline anywhere online, that guide is written for Turborepo 1.x.

Each key is a task name matching a script in your package.json files. The caret in dependsOn: [“^build”] tells Turborepo to finish that task in every dependency first. outputs lists which folders to cache, and cache: false is for tasks like a dev server that should never be cached.

Running Tasks and Watching the Cache Work

With your tasks defined, run one from the project root:

turbo run build

The first run builds everything from scratch. Run the exact same command again without changing any code, and you will see FULL TURBO next to each task, along with a run that finishes almost instantly.

✅ Best Practice: Add your common commands straight into your root package.json (“build”: “turbo run build”), so your whole team and your CI pipeline call the same script instead of remembering raw turbo flags.

Turning On Remote Caching

Local caching helps one developer. Remote Caching helps the whole team by sharing that same cache through a hosted server instead of just your own machine.

turbo login

turbo link

If your project is connected to Vercel, Remote Caching is free. Once linked, your teammate’s laptop and your CI server can both reuse a build that already ran elsewhere, instead of repeating it.

Filtering Tasks for Specific Packages

Large monorepos do not always need every package built. Use –filter to scope a task:

turbo run build --filter=web

Newer versions of Turborepo also support –affected for CI, comparing your branch against a base like origin/main and running tasks only for packages that actually changed, exactly what keeps a 50 package monorepo from rebuilding all 50 on every pull request.

Turborepo vs Other Monorepo Tools

Common Beginner Mistakes

⚠️ Warning: Forgetting to declare outputs is the most common mistake. Without it, Turborepo has nothing to restore, so every run looks like a cache miss even if nothing changed.

Another frequent slip is writing turbo commands inside a package’s own package.json instead of the root one, which can cause Turborepo to call itself recursively.

If you are intrigued by Turborepo and want to learn more tools like this in JavaScript, consider enrolling in HCL GUVI’s JavaScript Course For Beginners, where you’ll learn about JavaScript, which is used to create dynamic and interactive web content like applications and browsers.

Key Takeaways

• Turborepo caches tasks by file content, not by timestamps, so it never serves a stale build.
• The config file is turbo.json, and the task key is called tasks, not pipeline, in version 2 and above.
• dependsOn, outputs, and –filter are the three settings you will use the most as a beginner.
• Remote Caching turns your team’s combined build history into one shared cache.
• Start with create-turbo, then read the official docs once you are comfortable with the basics.

If you want to go deeper into building real, production grade JavaScript applications, GUVI’s Full Stack Development course walks you through the kind of project structure this Turborepo tutorial assumes you already have.

FAQs

1. Is Turborepo free to use?

Yes, Turborepo itself is open source and free. Remote Caching is also free for projects connected to Vercel, or you can self host it.

2. Do I need Vercel to use Turborepo?

No. Turborepo runs fine without Vercel. You only need Vercel if you want their hosted Remote Cache or want to deploy your apps there.

3. What is the difference between Turborepo and Nx?

Turborepo focuses on fast task running and caching with minimal setup, while Nx adds code generators and a deeper project graph, with a steeper learning curve.

4. Can I use Turborepo with an existing project?

Yes. You can add a turbo.json and the turbo package to an existing npm, Yarn, pnpm, or Bun workspace without rewriting your project structure.

5. Why does my build still show a cache miss every time?

This usually means your outputs array in turbo.json does not match where your build script actually writes files.

6. Does Turborepo support Bun?

Yes. Bun workspace support became stable in a recent Turborepo release, alongside existing npm, Yarn, and pnpm support.

7. What does FULL TURBO mean in my terminal?

It means Turborepo found a matching cache entry and restored your output instead of re running the task, so the task finished almost instantly.

8. Is Turborepo only for big companies?

No. Even a two app, one package monorepo benefits from caching and parallel task running from day one.