Path aliases stop working when migrating to ESM on v12

[hfhchan-plb]

Did you read the migration guide?

• I have read the whole migration guide

Is there an existing issue that is already proposing this?

• I have searched the existing issues

Potential Commit/PR that introduced the regression

No response

NestJS version

11.0 -> 12.0

Describe the regression

Path aliases stop working when migrating to ESM on v12 with monorepo: true with tsc.

It appears that tsc doesn't transform them any more when on ESM. There is no mention of this breaking in the https://docs.nestjs.com/migration-guide.

Minimum reproduction code

No response

Input code

Expected behavior

Path aliases continue to be transformed, or a note is made in the Migration Guide on how to migrate - either by adding more transforms on the compiled output, or by moving to native subpath support in node.

Other

No response

[xia-chao]

I hit this too after moving to ESM on v12, so I attached a debugger to nest build and followed the alias through lib/compiler/hooks/tsconfig-paths.hook.ts. Four screenshots, in order.

Setup (plain v12 scaffold, nothing hand-edited):

• @nestjs/cli 12.0.0 (1b37e5a), monorepo: true, builder: tsc
• generated apps/api + libs/lib, package.json has "type": "module"
• alias is exactly what the generator writes: "@app/lib": ["./libs/lib/src"]

1. The alias matches a folder, not a file

Breakpoint in getNotAliasedPath, on import { LibModule } from '@app/lib':

• text = @app/lib
• result = .../libs/lib/src — a directory, no file extension

2. One line later, that folder becomes the specifier written to the output

• resolvedPath = '../../../libs/lib/src'

3. nest build api fails, but still emits

• TS2307: Cannot find module '@app/lib' or its corresponding type declarations.
• the output still contains import { LibModule } from "../../../libs/lib/src";

4. Node refuses to load it

Error [ERR_UNSUPPORTED_DIR_IMPORT]: Directory import '.../libs/lib/src'
is not supported resolving ES modules imported from .../dist/apps/api/app.module.js

What's going on

• The generated alias points at a directory (libs/lib/src).
• With moduleResolution: nodenext + ESM, TypeScript does no directory-index lookup, so it reports TS2307. Under CJS it still probes index.* — which is why this only shows up once you move to ESM.
• The CLI's paths hook resolves the same alias to that same directory and writes it out as a relative path with no index.js, so the emitted code carries a specifier ESM cannot load.
• Separately, v12's templates put composite + rootDir: ./src on each project; an alias pointing at a sibling project's source then also trips TS6059 / TS6307. That part is independent of ESM (CJS hits it too).

About nest-cli#3545

I applied nest-cli#3545 on the same clone and re-ran the build. It fixes the emit layer (directory → index.js), but TS2307 stays because the paths target itself still points at a directory, so the build still fails before that fix can help. It is necessary but not sufficient to close this issue.

I deliberately did not open a competing PR — happy to hand over the fixture, the instrumented hook logs and the case matrix if that's useful.

[xia-chao]

@micalevisk should this stay open for the tsconfig/schematics half (see the debugger repro above), or be consolidated into #17650?

[micalevisk]

@xia-chao i guess its better to address that in two PRs that would land in the same release, so we can keep this open

[xia-chao]

@micalevisk agreed — two PRs, same release, keep it open.

I can take the schematics side: the generated paths target still points at a folder, which is what breaks resolution under nodenext. Then I'll verify it together with the CLI hook fix on a fresh v12 monorepo (nest g library → nest build → node dist/...).

If that half is already being handled, I'll just do the verification. Which do you want from me?

[micalevisk]

@xia-chao That plan sounds good! Go ahead please

[xia-chao]

@micalevisk Before I write the PR, one thing needs a decision.

I tested the template side with #3545 applied, on a fresh v12 monorepo. Fixing the paths target alone is not enough.

The reason: v12 also sets composite: true + rootDir: "./src" in tsconfig.app.json / tsconfig.lib.json. As soon as the alias points at a sibling library's source, TS throws TS6059 / TS6307. This also breaks CJS, not just ESM.

What I measured (build + boot):

project tsconfig	alias target	build
composite + rootDir: ./src (today)	./libs/x/src	TS2307
composite + rootDir: ./src	./libs/x/src/index.ts	TS6059 / TS6307
rootDir: "../..", no composite	./libs/x/src/index.ts	clean, boots
rootDir: "../..", no composite	./libs/x/src (CJS)	clean, boots

So the schematics PR would:

• set rootDir: "../.." and drop composite in the two project tsconfig templates
• write the file target (./libs/x/src/index.ts) for ESM, keep the folder target for CJS
• leave the emit side to Hot reload and injection issues #3545

One thing to confirm first: this moves the entry from dist/apps/api/main.js to dist/apps/api/apps/api/src/main.js (the pre-v12 layout). nest start finds it by itself, but node dist/apps/api/main and the docs would need updating.

Is that layout fine? Or should the entry stay at dist/apps/api/main.js? That would need a different approach.

[hfhchan-plb]

TS6059 goes away if I remove the references section in the root of tsconfig.json. This seems to match the v11 old behaviour.

[xia-chao]

@micalevisk
Opened nestjs/schematics#2444 for the schematics half. It needs nestjs/nest-cli#3545 in the same release.

[xia-chao]

references如果我移除tsconfig.json 根目录下的相应部分，TS6059 错误就会消失。这似乎与 v11 版本的行为一致。

@hfhchan-plb
I tried dropping references from the root tsconfig.json, and it did not remove TS6059 here.
Measured on a generated v12 monorepo (ESM, tsc, nest-cli#3545 applied):

root references	composite	rootDir	alias target	build
yes	yes	./src	./libs/x/src	TS2307
no	yes	./src	./libs/x/src/index.ts	TS6059 + TS6307
no	no	./src	./libs/x/src/index.ts	TS6059
no	no	../..	./libs/x/src/index.ts	clean

What removes TS6059 is rootDir — a sibling library's source is outside rootDir: "./src";
references did not change it. composite is what adds TS6307.

Could you share the tsconfig.json that worked for you? Your setup may differ.

[hfhchan-plb]

Sorry, I think I removed both files and references in the root tsconfig.json to get it to stop warning about TS6059.

(There is a delay between saving and the TypeScript server picking up the changes and the error disappearing so I was confused.)

This may or may not be the right fix, as apparently it simply asks typescript to compile the whole thing instead of each folder separately. This seems more elegant than say moving the rootDir to the root though, if makes the compiled output get nested twice.

(I am comparing this with a project which started with v6, in Jan 2021. These two properties were not present when we turned on monorepo back then 😆 )

[hfhchan-plb]

I am also able to confirm that in my old v6 -> v7 -> v8 -> v9 -> v10 -> v11 -> v12 upgraded set up, tsc will generate the dist folder structure matching the outside repo exactly, i.e. apps/api/src/main.ts -> dist/apps/api/src/main.js, with no TS6059 warning (this is after converting all path aliases to node-native subpath imports).

[old project] tsconfig.json:

{
  "compilerOptions": {
    "module": "nodenext",
    "declaration": true,
    "removeComments": true,
    "emitDecoratorMetadata": true,
    "experimentalDecorators": true,
    "noImplicitReturns": true,
    "target": "ES2022",
    "useDefineForClassFields": false,
    "sourceMap": true,
    "outDir": "./dist",
    "lib": ["ES2022", "DOM", "ESNext.Disposable"],
    "strict": true,
    "incremental": true,
    "skipLibCheck": true,
    "paths": {
      "*": ["./*"],
      "@lib/core": ["./libs/core/src"],
      "@lib/core/*": ["./libs/core/src/*"]
    }
  },
  "exclude": ["node_modules", "dist", "packages/e2e", "packages/integration"]
}

[old project] apps/api/tsconfig.app.json:

{
  "extends": "../../tsconfig.json",
  "compilerOptions": {
    "declaration": false,
    "rootDir": "./src",
    "outDir": "../../dist/apps/api"
  },
  "include": ["src/**/*", "../../global.d.ts"],
  "exclude": ["node_modules", "dist", "test", "**/*spec.ts"]
}

---

[fresh v12 project] tsconfig.json:

{
  "compilerOptions": {
    "module": "nodenext",
    "moduleResolution": "nodenext",
    "resolvePackageJsonExports": true,
    "esModuleInterop": true,
    "isolatedModules": true,
    "declaration": true,
    "removeComments": true,
    "emitDecoratorMetadata": true,
    "experimentalDecorators": true,
    "allowSyntheticDefaultImports": true,
    "target": "ES2023",
    "sourceMap": true,
    "outDir": "./dist",
    "incremental": true,
    "skipLibCheck": true,
    "strict": true,
    "strictPropertyInitialization": false,
    "types": [
      "vitest/globals",
      "node"
    ],
    "paths": {
      "@lib/core": [
        "./libs/core/src"
      ],
      "@lib/core/*": [
        "./libs/core/src/*"
      ]
    }
  },
}

[fresh project] apps/api/tsconfig.app.json:

{
  "extends": "../../tsconfig.json",
  "compilerOptions": {
    "composite": true,
    "declaration": true,
    "rootDir": "./src",
    "outDir": "../../dist/apps/admin"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist", "test", "**/*spec.ts"]
}

[xia-chao]

The configuration you shared has been very helpful in my judgment!

The key detail is the subpath imports. Once imports in package.json points at the built output,
the app only reads the built types, so TS6059 is gone and the output stays flat. I verified that
here and it works.

So there are two ways to go: keep paths pointing at source (this PR — one build step, nested
output, which is what v11 did under nest build), or move to subpath imports (flat output, but
libraries have to be built first).