Typescript path aliases in a monorepo

[benwainwright]

Hi there!

I'm working on a NextJS app written in TypeScript within a monorepo. The individual packages all have their tsconfig setup like this:

{
  "compilerOptions": {

    // ... other settings

    "baseUrl": "./src",
    "paths": {
      "@/*": ["*"]
    },
}

This allows me to take advantage of relative paths within all of the packages, and then when compiling NextJS with babel I can correctly transpile the aliases by making use of babel-plugin-root-import like this:

const path = require("path");
const findWorkspaceRoot = require("find-yarn-workspace-root");
const workspaceRoot = findWorkspaceRoot(__dirname);

module.exports = {
  plugins: [
    [
      "babel-plugin-root-import",
      {
        functions: ["jest.mock"],
        root: (sourcePath) => {
          const parts = path.relative(workspaceRoot, sourcePath).split("/");
          return path.resolve(workspaceRoot, "packages", parts[1]);
        },
        rootPathPrefix: "@/",
        rootPathSuffix: "./src",
      }
    ]
  ],
  presets: ["next/babel"],
};

This works fine for babel, but unfortunately when I do next build, it appears to hit these aliases and blow up on the initial type checking stage which I can see from your source code takes place before babel transpilation.

Note, that one of my goals in this project is to keep the individual monorepo packages as modular as possible, which means I don't want to put dependencies or config in the root of the project, and ideally individual packages (other than the app package, which is unavoidable) shouldn't know anything about other packages beyond the workspace dependency import.

Since I can do type-checking elsewhere, I have managed to get past type checking by adding

module.exports = {
  // More config ...
   typescript: {
      ignoreBuildErrors: true,
   },
}

To my next.config.js file, as I can probably do a full type check in the build separate to NextJS by using TypeScript project references, which I don't think you support, but it would be nice to have a solution that doesn't involve that.

[AlfreddGco]

Its impressive that monorepos are so popular nowadays and this question hasn't been answered since 2021. Another reason why NextJs is pure hype and doesn't even try to support sophisticaed edge cases

[Umuts-Codes]

In a monorepo setup using TypeScript with Next.js, handling path aliases across packages can be challenging because Next.js performs TypeScript type-checking before Babel transpilation, which is why your build fails despite Babel correctly resolving the aliases.

Recommended approaches

1. Use tsconfig.json project references

   • Configure each package with a tsconfig.json that includes "composite": true.
   • In your app package, reference other packages using "references".
   • This allows TypeScript to resolve aliases during type-checking before Next.js build, without ignoring errors.

2. Ensure consistent baseUrl and paths

   • Keep each package’s baseUrl and paths consistent and aligned with the monorepo structure.
   • Avoid root-level dependencies by defining paths relative to the workspace structure.

3. Separate type-checking from build

   • Continue using typescript.ignoreBuildErrors = true in next.config.js if you want to bypass Next.js type-checking.

   • Run type-checking separately using:

     tsc --build packages

   • This ensures that type errors are caught without blocking the Next.js build.

4. Optional Babel support

   • Keep babel-plugin-root-import for alias resolution during transpilation, but understand that Next.js build does not use Babel for type-checking, only for compiling JavaScript/JSX.

• Summary -

The build errors occur because Next.js type-checking happens before Babel resolves aliases. Using TypeScript project references or separating type-checking from build are the cleanest approaches. Ignoring build errors is a temporary workaround but maintaining proper project references ensures modularity and stability in a monorepo environment.