A simple setup for a TypeScript monorepo.

There are countless guides online for setting up a TypeScript monorepo.

Most rely on external tools like Lerna, Yarn, Turborepo, Yalc, or something else.

Here's a simple, zero-opinion way to get a TypeScript monorepo going.

First, make a structure like this:

root/
  package-1/
    package.json
    tsconfig.json
  package-2/
    package.json
    tsconfig.json
  package.json

The root/package.json can be empty, with only the following set:

{
  "private": true,
  "workspaces": [
    "package-1",
    "package-2"
  ]
}

Now, assuming package-1 depends on package-2, add this to the tsconfig.json for package-1:

{
  ...
  "references": [
    { "path": "../package-2/" }
  ]
}

And add this to the tsconfig.json for package-2:

{
  "compilerOptions": {
     ...
    "composite": true
  }
}

Now, go into into package-1 and run npm install.

Now, you can install package-2 as a dependency, even though it is not published to npm! Run npm install --save package-2.

Everything is set up now! Notice, if you update TypeScript code in package-2, you don't have to rebuild it or reinstall it. Stuff just works!

khalidx/typescript-monorepo.md