Tutorial: Setting Up a Monorepo with Turborepo

Learning Objectives and Outcomes

In this tutorial, you will:

• Understand the concept of a monorepo and its benefits.
• Learn how to set up a monorepo using Turborepo.
• Manage multiple packages within a single repository for efficient builds.
• Gain insights into optimizing build processes using caching and parallel execution.

Prerequisites and Setup

Before starting, ensure you have the following prerequisites:

• Node.js installed (version 14 or above).
• Basic understanding of npm workspaces and build systems.
• Familiarity with JavaScript and package management.

Installation Steps

1. Install Turborepo: Run the following command to install Turborepo globally:

   npx create-turbo@latest
   

2. Create a new directory for your project:

   mkdir my-monorepo && cd my-monorepo
   

3. Initialize a new npm project:

   npm init -y
   

4. Set up npm workspaces: Add the following configuration to your package.json:

   {
     "name": "my-monorepo",
     "private": true,
     "workspaces": [
       "packages/*"
     ]
   }
   

Step-by-Step Instructions

Step 1: Create Packages

1. Create a packages folder:

   mkdir packages
   

2. Inside the packages folder, create your first package:

   mkdir packages/package-a && cd packages/package-a
   npm init -y
   

3. Create a simple index.js file for package-a:

   // packages/package-a/index.js
   module.exports = () => 'Hello from package A!';
   

4. Repeat the above steps to create package-b:

   mkdir ../package-b && cd ../package-b
   npm init -y
   

   // packages/package-b/index.js
   const packageA = require('package-a');
   module.exports = () => `Package B says: ${packageA()}`;
   

Step 2: Configure Turborepo

1. Create a turbo.json configuration file in the root directory:

   {
     "pipeline": {
       "build": {
         "dependsOn": ["^build"],
         "outputs": ["dist/**"]
       }
     }
   }
   

2. Add build scripts to package.json of each package: For package-a:

   "scripts": {
     "build": "echo 'Building package A'"
   }
   

   For package-b:

   "scripts": {
     "build": "echo 'Building package B'"
   }
   

Step 3: Running Builds

1. From the root of your monorepo, run:

   npx turbo run build
   

   This command will build your packages in parallel and utilize caching for efficiency.

Key Concepts Explained

• Monorepo: A repository structure that houses multiple projects or packages, promoting code reusability and simplified dependency management.
• Turborepo: A high-performance build system for JavaScript and TypeScript monorepos, enabling efficient and fast builds.
• Caching and Parallel Execution: Turborepo caches previous builds and runs tasks in parallel, significantly reducing build times.

Common Mistakes and How to Avoid Them

• Not using private: true in package.json: Ensure your root package.json is marked as private to prevent accidental publishing.
• Incorrect workspace paths: Double-check that your workspace paths correctly point to the intended directories.
• Neglecting to install dependencies: Ensure all necessary dependencies are installed in each package by running npm install from the root directory.

Exercises and Practice Suggestions

• Add a third package: Create package-c and make it utilize both package-a and package-b.
• Implement tests: Add a testing framework (e.g., Jest) to your packages and configure it in your turbo.json.
• Experiment with scripts: Modify the build scripts to perform additional tasks, such as linting or code formatting.

Next Steps and Further Learning

• Explore Turborepo's official documentation for advanced features and configuration options.
• Learn about continuous integration tools that support monorepo setups, like GitHub Actions or CircleCI.
• Consider diving into more complex build systems and dependency management patterns.