TypeScript Monorepo Boilerplate

Pure ESM monorepo using native TypeScript compiler instead of external bundlers 🌟

Requirements

Node.js 22.2.0 or newer is required

NPM 10.8.0 or newer is required

Initialization

git clone https://github.com/negezor/typescript-monorepo-boilerplate.git
cd typescript-monorepo-boilerplate
npm install
npm run build

Configuration

Change namespace name

• In tsconfig.json, change the paths from @template to the one you need
• Change the namespace in the name property of the package.json file of each module

Add or remove packages folder

• In package.json, change workspaces and path in scripts lint:biome & typescript:clean
• In tsconfig.json, change the paths
• In .gitignore, change the # Build place
• Run npm run update:tsconfig for update tsconfig references

Add new package

• Copy template structure
• Run npm run update:tsconfig for update tsconfig references
• Run npm install for create new symlinks in node_modules

Add internal dependency

• Add to package.json dependency in peerDependencies
• Run npm run update:tsconfig for update tsconfig references

Scripts

npm run build

• Starts the build of all packages in monorepo

npm run watch

• Waits for changes in each package and performs build. Used for development.

npm run test

• Runs tests for packages

npm run lint

• Checks the code with the biome.js linter

npm run fmt

• Formats source code using biome.js

npm run clean

• Cleans the entire TypeScript build cache

npm run build --workspaces

• Run build in all packages. More info

npm run build --workspace=name

• Run build in specific package. More info

FAQ

Why not take Rollup/Esbuild/SWC?

Because they are external dependencies, yes of course they can faster than the typescript compiler for a build. But we will still check types and it is trivially easier. It's worth noting that now we use tsx which depends on esbuild (will be replaced later with a simpler solution).

Why Biome.js and not Eslint?

It's very simple, eslint is very slow. Usually the rules that we often need are already available in Biome.js, and those that are not are probably will implemented in the next version. It is also worth noting that eslint pulls a lot of small dependencies, while Biome.js is 1 binary file for your platform, which is much faster when installing and updating dependencies. Also it provides a formatter out of the box, we don't need to install prettier separately.

Why not Jest/Mocha?

Because these are external dependencies, and node:test is available out of the box, plus it's faster. The only thing that may be missing is simpler expect comparison, but you can put a smaller module for that separately.