Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

TypeScript 7 native tsc: moduleResolution, baseUrl and API errors

The native compiler changes three defaults and drops the compiler API. Fix tsconfig first, then alias TypeScript 6 for eslint and ts-node.

~5 min readTypeScript
#TypeScript#tsconfig#Migration#Build Tools
A Go-compiled tsc binary in a steel cube beside an API socket marked empty, headline TS7 NATIVE

Introduction & Quick Summary

Symptom. You install typescript@7 and the first npx tsc --noEmit fails on things that have nothing to do with your code:

code
error TS5107: Option 'moduleResolution=node10' is deprecated and will stop functioning in TypeScript 7.0. error TS5102: Option 'baseUrl' has been removed. Please remove it from your configuration. error TS2307: Cannot find module 'node:fs' or its corresponding type declarations. error TS2688: Cannot find type definition file for 'jest'.

Or the type check is green and linting died instead: Cannot find module 'typescript' from ts-node, or Cannot read properties of undefined (reading 'server') from typescript-eslint, because the 7.0 package ships no compiler API.

Cause. TypeScript 7.0 is the native port of the compiler: tsc is a compiled binary, not the JavaScript implementation. It reproduces 6.0's checking, adopts 6.0's new defaults, and turns every 6.0 deprecation into a hard error. Three defaults do most of the damage — rootDir is now ./, types is now [], and moduleResolution: node plus baseUrl no longer exist. The fourth cause is tooling.

Fix. Pin the config explicitly, and keep 6.0 alongside 7.0 for anything that imports the compiler API.

{ "compilerOptions": { "rootDir": "./src", "types": ["node"], "module": "esnext", "moduleResolution": "bundler", "strict": true, "noEmit": true }, "include": ["src"] }
{ "devDependencies": { "typescript": "npm:@typescript/typescript6@^6.0.2", "@typescript/native": "npm:typescript@^7.0.2" } }

Now npx tsc is the 7.0 binary, tsc6 is the 6.0 compiler, and import ts from "typescript" still finds an API.

Core Mechanics, Signatures & Reproducible Setup

Same checker, compiled, with the same tsconfig.json surface minus removed options, and roughly ten times faster on large projects. That speed is why the upgrade is worth an afternoon; it is also why the failures are config-shaped rather than type-shaped.

Reproduce each default in isolation:

bash
mkdir ts7-lab && cd ts7-lab npm init -y && npm i -D typescript@7.0.2 @types/node mkdir src && printf 'export const n: number = 1;\n' > src/index.ts npx tsc --noEmit --init && npx tsc --noEmit

Then add the constructs projects carried for years:

{ "compilerOptions": { "baseUrl": ".", "paths": { "@/*": ["src/*"] }, "module": "commonjs", "moduleResolution": "node", "target": "es5", "allowSyntheticDefaultImports": true, "esModuleInterop": false } }

Removed options are reported as configuration errors before a single file is checked, so the output is short and complete. These are hard errors: there is no ignoreDeprecations: "6.0" escape hatch in 7.0, because that flag was itself removed.

The second mechanical change is the exit code. tsc 6.x exited 2 for type errors; the native compiler exits 1. CI scripts that separate "type errors" (2) from "the compiler crashed" (1) now read every ordinary type error as a crash.

bash
# before npx tsc --noEmit || { [ $? -eq 2 ] && echo "types failed" || exit 1; } # after npx tsc --noEmit || exit 1

Key Comparison Table

Setting or behaviourTypeScript 5.x / 6.xTypeScript patchesMigration action
strictfalse unless settrue by defaultfix errors, do not disable
moduleResolution: node / node10supportedremovedbundler for apps, nodenext for libraries
baseUrl with pathsanchor for pathsremovedmake paths relative to the config file
typesall @types loaded[]list node, jest, vite/client
rootDirinferred common root./set ./src when the config sits above it
target: es5, downlevelIterationsupportedremovedtarget es2020 or later
module: amd / umd / systemjssupportedremovedesnext or preserve
import assert { type }acceptedrejecteduse with { type: "json" }
Type error exit code21stop branching on the value
import "typescript"returns APIno APIalias 6.0 for API consumers
Failure you will seeDefault that caused itFirst thing to check
TS2307: Cannot find module 'node:fs'types: []add "types": ["node"]
TS2688 for jesttypes: []list the test runner types
TS6059: File is not under 'rootDir'rootDir: "./"set rootDir to ./src
TS5102: Option 'baseUrl' has been removedbaseUrl gonerewrite paths without it
TS2304: Cannot find name 'describe'types: []add the test types
Cannot find module 'typescript'no API in 7.0alias @typescript/typescript6
Output lands in dist/src/...new rootDirset rootDir and outDir together

Practical Edge Cases, Error Fixes & Deep Dive Code Examples

1. paths without baseUrl

baseUrl was the anchor that made paths relative to a directory. It is gone; paths now resolve relative to the tsconfig.json that declares them. This is the change that quietly breaks monorepos, because the replacement looks almost identical:

{ "compilerOptions": { "paths": { "@app/*": ["./src/*"], "@shared/*": ["../shared/src/*"] } }, "include": ["src"] }

The ./ prefix replaces baseUrl: ".". An old baseUrl: ".." becomes a ../ prefix instead. Bundlers reading tsconfig.paths keep working, since the resolved mapping is unchanged.

2. Node built-ins and node: specifiers

With types: [], no ambient @types package loads automatically, so a backend fails on its first built-in import even though the types are installed:

ts
import { readFile } from "node:fs/promises"; // TS2307 without types: ["node"]

Add the types you actually use rather than ["*"]. The wildcard restores the old behaviour and restores the reason laptops and CI disagreed: it loads whatever happens to be installed. The same applies to vitest/globals, @cloudflare/workers-types and framework ambient modules.

3. Libraries need nodenext, applications usually need bundler

moduleResolution: node never understood exports maps and resolved modern packages to the wrong .d.ts. There is no single replacement:

{ "compilerOptions": { "module": "nodenext", "moduleResolution": "nodenext" } }

nodenext enforces extension rules and exports conditions, which is what a published library needs so its declarations describe the runtime truthfully. Application code behind Vite or Next.js wants bundler, which reads exports without demanding .js extensions:

{ "compilerOptions": { "module": "preserve", "moduleResolution": "bundler" } }

nodenext in a bundled app produces hundreds of TS2835 errors about extensions the bundler never needed. bundler in a published package produces declarations that Node ESM consumers cannot resolve.

4. Tools that import the compiler API

typescript-eslint, ts-node, ts-morph, dts-bundle-generator, GraphQL codegen and most codemods do not call the binary; they walk the AST. The release notes point at 7.1 for a new API, so alias 6.0 meanwhile:

bash
npm i -D typescript@npm:@typescript/typescript6@^6.0.2 @typescript/native@npm:typescript@^7.0.2

Tools that accept a compiler path should be pointed at 6.0 explicitly, for example "ts-node": { "compiler": "@typescript/typescript6" } in tsconfig.json. If ESLint still crashes on ts.server, the parser resolved 7.0 and there is no language-service object to read.

5. Frameworks that are not ready

Vue, Svelte, Astro, MDX and Angular templates type-check through a language service built on the compiler API, so they stay on 6.0 until 7.1 ships one. Upgrading blindly leaves a green CLI and a red editor. The workable split is CLI checking on 7.0, editor and template checking on 6.0:

{ "scripts": { "typecheck": "tsc --noEmit", "typecheck:compat": "tsc6 --noEmit -p tsconfig.json" } }

For a vue-tsc project the honest answer is to wait, or to keep 7.0 out of the editor workspace.

6. Template literal types and Unicode

Template literal inference now treats code points as units instead of UTF-16 halves, so HeadTail<"😀abc"> yields ["😀", "abc"] where 6.0 produced surrogate fragments. Type-level string utilities built on that recursion change behaviour, and snapshot tests pinning the old count fail:

ts
type HeadTail<S> = S extends `${infer Head}${infer Tail}` ? [Head, Tail] : never; type R = HeadTail<"😀abc">; // ["😀", "abc"] on 7.0

Usually the new answer is the one you wanted, since it matches for...of. Confirm with the JSON formatter whether the difference is a surrogate pair or a real type change before you rewrite the utility.

Common Compilation/Runtime Mistakes & Version Gotchas

  • Setting strict: false to clear the noise. It works and it disables the checks that made the upgrade worth doing. Fix the errors, or place a narrow // @ts-expect-error at the boundary.
  • Assuming tsc still exits 2. set -e scripts that used to continue now stop on the first type error.
  • Leaving old flags in package.json. Unknown options are fatal in 7.0, so the build dies before compiling.
  • Passing file paths to tsc with a tsconfig.json present. 7.0 refuses unless you pass --ignoreConfig.
  • Upgrading typescript-eslint to fix an API error. The parser pins the compiler it needs; the alias is the missing piece.
  • Passing bundler resolution to a non-bundled runtime. Node still resolves by exports at run time, so a clean check can hide a broken import. Run the built output once.
  • Branching on typescript.version. Both versions can be installed; check the resolved path or a feature instead.

Compare the 6.0 and 7.0 diagnostic text with the text diff tool before assuming a message means something new.

Reference: Announcing TypeScript 7.0 and the TypeScript 6.0 release notes whose deprecations 7.0 enforces.

Official references

primary documentation

The TypeScript documentation that defines the behaviour this guide explains.

Try matching browser tools

All tools

Small utilities that fit TypeScript work — they run entirely in this browser tab, so nothing you paste leaves your device.

All TypeScript guides

More in TypeScript

All TypeScript guides

The guides filed next to this one in TypeScript, in library order.