TypeScript 6.0 Migration — How to Handle baseUrl Removal, rootDir Fixing, and strict Errors All at Once with ts5to6

Honestly, when I first read the TypeScript 6.0 release notes, I rubbed my eyes three times. Nine tsconfig defaults changing all at once. baseUrl deprecated, strict flipped to true by default, module bumped from commonjs to esnext. But once I dug in, the two most breaking changes were handled by tooling, and the scope of what I actually had to touch was much narrower than I expected.

This article is for developers using TypeScript in production. It walks through the actual migration steps, distinguishing what the ts5to6 CLI tool — created by Andrew Branch, who works on module resolution for the TypeScript compiler team — handles automatically, versus what you need to take care of yourself.

TypeScript 7.0 Beta dropped in April 2026, and starting with 7.0, the compiler switches to a Go-based implementation. Skipping the 6.0 migration means a full rewrite awaits you at 7.0, rather than an incremental transition. The timing is perfect right now.

Core Concepts

The 9 Default Changes in TypeScript 6.0

TypeScript 6.0, officially released on March 23, 2026, is the last version of the JavaScript-based TypeScript compiler. Starting with 7.0, a completely rewritten Go-based compiler takes over. The defining characteristic of this release is that the team finally did a sweeping cleanup of long-overdue default values all in one go.

The three that caused me the most trouble were strict, rootDir, and baseUrl. The rest aren't without impact either — noUncheckedSideEffectImports in the table directly affects side-effect-only imports like import './polyfill'. If you use polyfills or CSS imports, you'll need to check those separately. libReplacement: false only affects the special case where you're swapping in custom lib files, so most projects won't feel it.

baseUrl Deprecated — It Doesn't Stop Working Immediately in 6.0

I misunderstood this at first too, so it's worth being precise. In TypeScript 6.0, baseUrl is officially deprecated and will generate a warning, but the feature itself still works. Complete removal is planned for TypeScript 7.0. The timeline is not "all your imports break right now," but rather "you get a warning now, and it's completely removed in 7.0."

What is baseUrl? Setting "baseUrl": "./src" in tsconfig allowed absolute-style imports like import { foo } from 'components/Button'. Starting in 6.0, this approach is deprecated, and you need to migrate to explicit paths configuration.

The reason to migrate now is simple: if baseUrl is still in place when you move to 7.0, that becomes a much bigger burden.

How the rootDir Default Change Silently Breaks Builds

This is the kind of problem with no error message that you only discover after deployment, which makes it especially annoying.

In TS 5.x, if you didn't specify rootDir, it was automatically inferred as the common parent directory of your input files. If your source was under src/, rootDir was set to src/, and the build output came out as dist/index.js. In TS 6.0, the rootDir default changes to the directory where tsconfig.json lives.

# TS 5.x (rootDir unspecified): dist/index.js
# TS 6.0 (rootDir unspecified): dist/src/index.js  ← path is different

If your deployment scripts or runtime entry points reference dist/index.js, it will silently break.

types: [] Default — Only Affects Global Ambient Types

What are @types/*? Packages like @types/node and @types/react that provide TypeScript type definitions for JavaScript libraries.

There's an important distinction here. Changing to types: [] doesn't block all @types/* packages. It only disables ambient types that were previously included globally and automatically. Types that you import directly, like import type { Foo } from 'some-lib', are not affected.

The cases that are actually impacted are Node.js global types like process and Buffer. Previously, having @types/node installed meant it was automatically available globally. Now you need to explicitly add "types": ["node"] to your tsconfig.

Practical Application

Step 1: Automate baseUrl Removal with --fixBaseUrl

ts5to6 can be run directly with npx.

# Remove baseUrl and rewrite paths in the current directory's tsconfig.json
npx @andrewbranch/ts5to6 --fixBaseUrl .
 
# Specify a custom tsconfig file
npx @andrewbranch/ts5to6 --fixBaseUrl ./tsconfig.app.json

Seeing exactly what the tool transforms makes it easier to understand.

Before (tsconfig.json):

{
  "compilerOptions": {
    "baseUrl": "./src",
    "paths": {
      "components/*": ["components/*"],
      "utils/*": ["utils/*"]
    }
  }
}

After (tsconfig.json):

{
  "compilerOptions": {
    "paths": {
      "components/*": ["./src/components/*"],
      "utils/*": ["./src/utils/*"]
    }
  }
}

If you were using baseUrl as a path prefix, ./src/ is automatically prepended to each paths entry. If you only had baseUrl set with no paths at all, a wildcard catch-all entry is also added automatically.

In monorepo environments, it processes all child tsconfigs by following the project references chain and extends inheritance. It works without additional configuration in pnpm workspaces or Turborepo setups.

Step 2: Preserve Build Output Paths with --fixRootDir

# Explicitly fix rootDir to match what TS 5.x would have inferred
npx @andrewbranch/ts5to6 --fixRootDir .
 
# Specify a package tsconfig in a monorepo
npx @andrewbranch/ts5to6 --fixRootDir ./packages/core/tsconfig.json

The tool calculates the rootDir value that TS 5.x would have inferred and inserts it explicitly into your tsconfig. Your build output structure is preserved as-is.

Caution: --fixBaseUrl and --fixRootDir cannot be run simultaneously. Each must be run separately, and the safe order is --fixBaseUrl first, then --fixRootDir. Checking the changes with git diff after each step makes it much easier to trace the root cause if something goes wrong later.

Step 3: Addressing the strict: true Default

With strict now defaulting to true, code that was written without type annotations will start throwing errors. Here are two patterns you'll frequently encounter in production.

// src/utils.ts — patterns that were allowed in TS 5.x
function greet(name) {               // noImplicitAny — no parameter type
  return `Hello ${name}`;
}
 
const val = maybeNull.toUpperCase(); // strictNullChecks — ignoring possible null

// src/utils.ts — addressing TS 6.0 strict: true
function greet(name: string) {
  return `Hello ${name}`;
}
 
const val = maybeNull?.toUpperCase() ?? '';

If there are too many errors to fix all at once, you can use a temporary buffer strategy.

// tsconfig.json
{
  "compilerOptions": {
    "ignoreDeprecations": "6.0",
    "strict": false
  }
}

This temporarily suppresses deprecation warnings and preserves the old behavior. However, since ignoreDeprecations itself is not supported in TypeScript 7.0, you can't defer the real migration indefinitely.

Step 4: Import Changes from the esModuleInterop Default Change

With esModuleInterop now defaulting to true, the import syntax for CommonJS modules changes.

// src/server.ts — TS 5.x style (esModuleInterop: false default)
import * as express from "express";

// src/server.ts — TS 6.0 style (esModuleInterop: true default)
import express from "express";

This change improves compatibility with Vite, esbuild, and Rollup-based projects. For React, if you're using the automatic JSX transform from React 17+, import React from "react" works safely — but in environments that don't, it's worth reviewing your moduleResolution and bundler settings together. In legacy CommonJS projects, there may be additional things to check due to the interplay with the moduleResolution change.

Pros and Cons

Advantages

Of these, the one I felt most in practice was the second one. In a project with around twelve tsconfigs in a monorepo, having a single tool handle all of them was practically the only saving grace of this migration.

Drawbacks and Caveats

Most Common Mistakes in Practice

I personally experienced mistake #1, and it seems like many people make the same mistakes in the same order.

1. Upgrading TypeScript to 6.0 before running ts5to6 — I did this first and got a flood of errors all at once, then had to roll back. It's much safer to run the tool first to clean up the tsconfig, then upgrade the version.
2. Not being aware of the types: [] change and mistaking disappeared Node.js global types for module errors — If process, Buffer, etc. suddenly throw errors, check for a missing "types": ["node"] first. It takes more time than you'd think to find the cause.
3. In a monorepo with a shared base tsconfig, only checking child tsconfigs and calling it done — The combination of paths defined in the base tsconfig and baseUrl in a child is not handled automatically by ts5to6, so if you have a monorepo structure, review the base tsconfig separately as well.

Closing Thoughts

The tool handles 80%, and the remaining 20% is where mistakes happen — following the right order is everything with this migration.

Here are 3 steps you can start right now.

1. Start by auditing your tsconfig — Checking your current configuration from the project root will show you the scope of impact.

   bash

   # Single project
   grep -E '"baseUrl"|"rootDir"|"strict"' tsconfig.json
    
   # Monorepo (recursive search)
   find . -name 'tsconfig*.json' | xargs grep -l '"baseUrl"\|"rootDir"\|"strict"'

2. Run ts5to6 sequentially — The safe flow is: run npx @andrewbranch/ts5to6 --fixBaseUrl ., validate the build, then run npx @andrewbranch/ts5to6 --fixRootDir . and validate the build again. Checking the changes with git diff after each step makes problem tracking much easier.

3. Fix strict errors incrementally — If fixing everything at once is too daunting, temporarily add "strict": false, then use a third-party tool like ts-strictify to apply it file by file. Note that adding a // @ts-strict comment at the top of a file is a third-party tool convention, not an official TypeScript feature — confirm the tool is installed before relying on it.

References

• Announcing TypeScript 6.0 | TypeScript Official Blog
• TypeScript 6.0 Release Notes | Official Docs
• andrewbranch/ts5to6 | GitHub
• 6.0 Migration Guide — microsoft/TypeScript#62508 | GitHub
• TSConfig Reference | Official Docs
• @andrewbranch/ts5to6 | npm
• Announcing TypeScript 6.0 RC | TypeScript Official Blog