Monorepo with TypeScript: Code Organization for Beginners

Monorepo with TypeScript: Code Organization for Beginners

Developing modern applications in TypeScript often requires managing several interconnected packages (e.g., a component library, a backend service, and utilities). Instead of storing each package in a separate repository (multirepo), many teams choose a monorepo — a single repository containing all projects. In this article, we will break down how to organize a monorepo with TypeScript, even if you are a beginner.

What is a Monorepo and Why Do You Need It?

A monorepo is an approach where the code of several projects (packages, modules) is stored in a single repository. This does not mean all projects are lumped together: they remain logically separated but are under one roof.

Advantages for TypeScript projects:

• Single version of dependencies. You avoid situations where different packages use different versions of TypeScript or the same library.
• Easy refactoring. Changing a shared interface or type in one place immediately updates it across all dependent packages.
• Simplified publishing. Monorepo tools (e.g., Lerna or Nx) help automatically publish only the changed packages.
• Shared configurations. You can have one tsconfig.json for all packages, overriding it when necessary.

Tools for Creating a Monorepo

Several popular tools exist for working with a monorepo in TypeScript:

• npm Workspaces — a built-in npm feature starting from version 7. Simple and effective.
• Yarn Workspaces — a similar function in the Yarn package manager.
• Lerna — a classic tool often used on top of npm or Yarn Workspaces.
• Nx — a powerful monorepo system with advanced caching and code generation capabilities.
• Turborepo — a modern tool from Vercel focused on speed and simplicity.

In this guide, we will use npm Workspaces, as it is the simplest method requiring no additional global tools to install.

Step-by-Step Setup of a Monorepo with TypeScript

1. Creating the Root Structure

Start by creating the root folder of your monorepo and initializing package.json:

mkdir my-monorepocd my-monoreponpm init -y

Now edit the root package.json, adding the workspaces field. This tells npm where to find your packages:

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

The "private": true flag prevents accidental publishing of the root package to npm.

2. Creating Packages

Create the folder structure for your packages. A typical structure looks like this:

my-monorepo/├── packages/│   ├── utils/          # Common utilities│   ├── ui/             # Component library│   └── backend/        # Server application├── package.json└── tsconfig.json

Create the packages folder and inside it, folders for each package. Each package should have its own package.json. For example, for the utils package:

mkdir -p packages/utilscd packages/utilsnpm init -y

Edit packages/utils/package.json, adding a name and possibly a version:

{  "name": "@my-project/utils",  "version": "1.0.0",  "main": "dist/index.js",  "types": "dist/index.