Create a new Turborepo
First, run npx create-turbo@latest
Next, choose where you'd like to create your project
And finally choose your package manager
This will create a bunch of workspaces in the "app" and "packages" directory.
What is a workspace
Workspace is basically a folder containing a package.json. Each workspace can declare its own dependencies, run its own scripts, and export code for other workspaces to use.
Examining the package.json
First, open the package.json inside "packages/ui" folder. You'll notice that the package's name is "name": "ui" - right at the top of the file.
Next, open the package.json inside "apps/web" folder. You'll notice that this package's name is "name": "web". You'll also see that "web" depends on a package called "ui". If you're using pnpm, you'll see it's declared like this:
Now if we run the lint script again, since our code hadn't changed, Turborepo will replay the logs from the previous run, making it much faster this time.
Building with Turborepo
Let's build our project by running pnpm run build, this will run the build script on all workspaces who have included a build script. Currently, only the "docs" and "web" workspaces have specified a build script in their package.json; therefore only those will run.
Specifying outputs for the build pipeline, means that when turbo finishes running that task, it'll save the output you specify in its cache.
To see this in action, delete the apps/docs/.next build folder, and run the build script again. Since Turborepo has cached the result of our previous build, it will restore the entire .next folder from the cache instantly, without having to run the build process again, making it super fast and efficient.
Running dev scripts
Only two scripts will execute, docs:dev and web:dev. Since these are the only two workspaces which specify dev. Both dev scripts are run simultaneously, starting your NextJs apps on ports 3000 and 3001.
Inside dev, we've specified "cache": false. This means we're telling Turborepo not to cache the results of the dev script.
Running dev script only on one workspace
By default, turbo run dev will run dev on all workspaces at once. But sometimes, we might only want to choose one workspace. Using pnpm we can add a --filter flag to filter the script to any given workspace; we can achieve the same by passing a workspace using yarn:
# running the dev script on the "docs" workspace# pnpm
pnpm --filter docs run dev
yarn workspace docs run dev
How to add dependencies
Similar to how we filtered the script we ran in the previous step to a specific workspace, we can add dependencies to a specific workspace by passing a filter:
We can setup our workspaces so we can share one tailwind.config.js through out our monorepo. First we can create a new workspace in the packages folder; we're going to name it "tailwind-config", this is where we keep our shared tailwindcss configuration:
That's it, you can now use tailwind throughout your monorepo and share the same config between them. You can even take this further by setting up the "ui" workspace to build and output the transpiled source and compiled styles to a dist/ folder. This will make sharing one tailwind.config.js easy, and also ensures only the CSS that is used by the current application and its dependencies is generated. You can read more in the official examples from Turborepo here.
That's a wrap folks. Turborepo is an amazing tool to optimize your tasks and manage multiple packages from a single repository.