TypeScript

TypeScript is an excellent tool in monorepos, allowing teams to safely add types to their JavaScript code. While there is some complexity to getting set up, this guide will walk you through the important parts of a TypeScript setup for most use cases.

• Sharing TypeScript configuration
• Building a TypeScript package
• Making type checking faster across your workspace

Sharing tsconfig.json

You want to build consistency into your TypeScript configurations so that your entire repo can use great defaults and your fellow developers can know what to expect when writing code in the Workspace.

TypeScript's tsconfig.json sets the configuration for the TypeScript compiler and features an extends key that you'll use to share configuration across your workspace.

This guide will use create-turbo as an example.

npx create-turbo@latest

Use a base tsconfig file

Inside packages/tsconfig, we have a few json files which represent different ways you might want to configure TypeScript in various packages. The base.json file is extended by every other package.json in the workspace and looks like this:

"compilerOptions": {
    "esModuleInterop": true,
    "skipLibCheck": true,
    "target": "es2022",
    "allowJs": true,
    "resolveJsonModule": true,
    "moduleDetection": "force",
    "isolatedModules": true,
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "module": "NodeNext"
}

Creating the rest of the package

The other tsconfig files in this package use the extends key to start with the base configuration and customize for specific types of projects, like for Next.js (nextjs.json) and a React library (react-library.json).

Inside package.json, name the package so it can be referenced in the rest of the Workspace:

{
  "name": "@repo/typescript-config"
}

Building a TypeScript package

Using the configuration package

First, install the @repo/typescript-config package into your package:

{
  "devDependencies": {
     "@repo/typescript-config": "*",
     "typescript": "latest",
  }
}

Then, extend the tsconfig.json for the package from the @repo/typescript-config package. In this example, the web package is a Next.js application:

{
  "extends": "@repo/typescript-config/nextjs.json",
  "compilerOptions": {
    "outDir": "dist"
  },
  "include": ["src"],
  "exclude": ["node_modules"]
}

Creating entrypoints to the package

First, make sure your code gets compiled with tsc so there will be a dist directory. You'll need a build script as well as a dev script:

{
  "scripts": {
    "dev": "tsc --watch",
    "build": "tsc"
  }
}

Then, set up the entrypoints for your package in package.json so that other packages can use the compiled code:

{
  "exports": {
    "./button": {
      "types": "./src/button.ts"
      "default": "./dist/button.js",
    },
    "./input": {
      "types": "./src/input.ts"
      "default": "./dist/input.js",
    }
  }
}

Setting up exports this way has several advantages:

• Using the types field allows tsserver to use the code in src as the source of truth for your code's types. Your editor will always be up-to-date with the latest interfaces from your code.
• You can quickly add new entrypoints to your package without creating dangerous barrel files.
• You'll receive auto-importing suggestions for your imports across package boundaries in your editor. For more information about why you may not want to wildcard the entrypoints, see the limitations section.

Linting your codebase

To use TypeScript as a linter, you can check the types across your workspace fast using Turborepo's caching and parallelization.

First, add a check-types script to any package that you want to check the types for:

{
  "scripts": {
    "check-types": "tsc --noEmit"
  }
}

Then, create a check-types task in turbo.json. From the Configuring tasks guide, we can make the task run in parallel while respecting source code changes from other packages using a Transit Node:

{
  "tasks": {
    "topo": {
      "dependsOn": ["^topo"]
    },
    "check-types": {
      "dependsOn": ["topo"]
  },
}

Then, run your task using turbo check-types.

Best practices

Use tsc to compile your packages

For Internal Packages, we recommend that you use tsc to compile your TypeScript libraries whenever possible. While you can use a bundler, it's not necessary and adds extra complexity to your build process. Additionally, bundling a library can mangle the code before it makes it to your applications' bundlers, causing hard to debug issues.

Use Node.js subpath imports instead of TypeScript compiler paths

It's possible to create absolute imports in your packages using the TypeScript compiler's paths option. However, as of TypeScript 5.4, you can use Node.js subpath imports instead.

Additionally, Node.js subpath imports are usable in Just-in-Time Packages while TypeScript's compilerOptions#paths are not.

This strategy brings your Node.js and TypeScript configurations closer together, making your project's configuration simpler.

You likely don't need a tsconfig.json file in the root of your project

As mentioned in the Structuring your repository guide, you want to treat each package in your tooling as its own unit. This means each package should have its own tsconfig.json to use instead of referencing a tsconfig.json in the root of your project. Following this practice will make it easier for Turborepo to cache your type checking tasks, simplifying your configuration.

The only case in which you may want to have a tsconfig.json in the Workspace root is to set configuration for TypeScript files that are not in packages. For example, if you have a script written with TypeScript that you need to run from the root, you may need a tsconfig.json for that file.

However, this practice is also discouraged since any changes in the Workspace root will cause all tasks to miss cache. Instead, move those scripts to a different directory in the repository.

You likely don't need TypeScript Project References

We don't recommend using TypeScript Project References as they introduce both another point of configuration as well as another caching layer to your workspace. Both of these can cause problems in your repository with little benefit, so we suggest avoiding them when using Turborepo.

Limitations

Your editor won't use a package's TypeScript version

tsserver is not able to use different Typescript versions for different packages in your code editor. Instead, it will discover a specific version and use that everywhere.

This can result in differences between the linting errors that show in your editor and when you run tsc scripts to check types. If this is an issue for you, consider keeping the TypeScript dependency on the same version.

Package entrypoint wildcards

We recommend listing the entrypoints to your package explicitly - but, to some, this feels too verbose. Instead, you can use wildcards to capture entrypoints:

{
  "exports": {
    "./*": {
      "types": "./src/*.ts",
      "default": "./dist/*.js"
    }
  }
}

While this will work, it comes with the tradeoff of not being able to auto-import across package boundaries due to performance reasons with the TypeScript compiler. This tradeoff may or may not be worth it to you depending on your use case.