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.
Good to know:
If you're finding that turbo is having issues like not being able to
discover packages in your workspace or not following your dependency graph,
visit our Structuring a
repository page
for tips.
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
Install turbo
We recommend you install turbo both globally and into your repository's root for the best developer experience.
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.
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.
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.
Edit .gitignore
Add .turbo to your .gitignore file. The turbo CLI uses these folders for persisting logs, outputs, and other functionality.
Run the build and check-types tasks with turbo
This runs build and check-types at the same time.
Without making any changes to the code, try running build and check-types again:
You should see terminal output like this:
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.
You can also use a filter to focus on a specific package and its dependencies.
Note that this step doesn't provide much value in a single-package workspace since:
- 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 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:
Was this helpful?