Monorepo with TypeScript: Organizing Code in Practice

Monorepo with TypeScript: Organizing Code in Practice

Modern frontend and backend development increasingly faces the challenge of managing multiple interconnected projects. As the number of packages, libraries, and applications grows, the traditional approach with separate repositories (multi-repo) begins to slow down development: code duplication, difficulties with version synchronization, and long review cycles. The solution is a monorepo, especially in combination with TypeScript. In this article, we will break down the practical aspects of organizing code in a TypeScript monorepo: from choosing tools to specific examples of structure and configuration.

What is a monorepo and why is it needed for TypeScript projects?

A monorepo is an approach where the code of several projects (packages, libraries, services) is stored in a single Git repository. This is especially relevant for TypeScript, as the strictly typed language makes it easy to reuse common types and interfaces between different parts of the system.

Main advantages of a monorepo with TypeScript:

• Single version of dependencies — eliminates the situation where different projects use different versions of the same library.
• Code reuse — common types, utilities, and configurations are easily accessible to all packages.
• Atomic commits — changes affecting multiple packages can be committed together.
• Simplified CI/CD — one pipeline for building and testing all parts.

However, a monorepo requires discipline in code organization. Without proper structure, it turns into a "dump." TypeScript helps bring order thanks to strict typing and a modular system.

Choosing a tool for managing a monorepo

There are several popular tools for working with monorepos on the market. Let's look at the two most common for TypeScript: Nx and Turborepo.

Nx is a powerful system with support for monorepos, code generation, and advanced caching. It is well suited for large projects with many packages.

Turborepo is a lighter and faster tool from Vercel, focused on simplicity. It is ideal for medium-sized projects and teams that want minimal configuration.

Example of basic setup with Turborepo:

// turbo.json{  "$schema": "https://turbo.build/schema.json",  "pipeline": {    "build": {      "dependsOn": ["^build"],      "outputs": ["dist/**"]    },    "test": {      "dependsOn": ["build"]    },    "lint": {}  }}

For TypeScript, configuring tsconfig.json with support for project references is mandatory. This allows the compiler to understand dependencies between packages.

// tsconfig.base.json{  "compilerOptions": {    "target": "ES2020",    "module": "ESNext",    "moduleResolution": "bundler",    "strict": true,    "composite": true,    "declaration": true,    "declarationMap": true,    "sourceMap": true,    "outDir": "./dist",    "rootDir": "./src"  }}

Practical organization of monorepo structure

The key principle is separating code into logical layers. Let's look at a typical structure for a TypeScript monorepo with a web application and backend:

monorepo/├── apps/│   ├── web/          # Frontend application (React, Vue, etc.)│   └── api/          # Backend service (Express, NestJS)├── packages/│   ├── shared/       # Shared types and interfaces│   ├── utils/        # Utility functions│   ├── ui/           # UI components (if used)│   └── config/       # Shared configurations (eslint, tsconfig)├── tools/            # Scripts and tools for CI/CD├── turbo.json├── package.json└── tsconfig.