TypeScript baseUrl Deprecated? Here's the Real Fix

If you just upgraded TypeScript and your build spat out something like Option 'baseUrl' is deprecated and will stop functioning in TypeScript 7, take a breath — you didn’t break anything. This is one of the most-hit warnings of the TypeScript 6.0 release, and the fix usually takes less time than reading this sentence twice.

Here’s the short version: TypeScript’s baseUrl compiler option is officially deprecated starting in TypeScript 6.0, and the team has confirmed it will be fully removed in TypeScript 7.0. So the warning isn’t a typo or a fluke — it’s a real heads-up that your tsconfig.json needs a small update before you upgrade further. In this guide, I’ll walk through exactly why this happened, how to fix it in a few minutes using TypeScript’s own migration tool, and what else tends to break at the same time (because baseUrl is rarely traveling alone).

What the “baseUrl Is Deprecated” Warning Actually Means

TypeScript’s compiler options don’t usually disappear overnight. When the team wants to retire something, they roll it out in two stages: a deprecation warning first, then removal a couple of major versions later. That’s exactly what’s happening here.

Looking at the actual source behind this warning, the deprecation is defined as running from version 6.0 through 7.0 — meaning baseUrl starts warning in 6.0 and genuinely stops working once you’re on 7.0. So if you’re seeing this now, you’re on 6.0 (or later) and the compiler is politely telling you the clock is ticking.

Here’s the thing most people miss: baseUrl isn’t being removed because it’s broken. It’s being removed because it’s redundant for almost everyone who still has it in their config.

Why This Change Even Happened

Back before TypeScript 4.1, baseUrl was a hard requirement if you wanted to use path aliases (paths) in your tsconfig.json. Lots of teams added it purely to unlock paths — not because they actually wanted module resolution to be relative to some base directory.

Since 4.1, that requirement quietly went away. paths has worked fine without baseUrl for years now. The problem is that nobody went back and cleaned up their old configs, so thousands of projects are still carrying a baseUrl entry that’s doing nothing except sitting there waiting to eventually break.

TypeScript 6.0 is essentially the team saying: let’s finally clean this up before the 7.0 rewrite ships.

The Fast Fix: Remove baseUrl and Adjust paths

For most projects, the fix comes down to one of two moves.

Option 1 — You Only Used baseUrl to Enable paths

If your tsconfig.json looks something like this:

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

You can just delete baseUrl entirely. Nothing else needs to change:

{
  "compilerOptions": {
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

This covers a surprising number of real-world projects — especially anything scaffolded by Create React App, Vite, or Next.js templates a few years back, where "baseUrl": "." got added by default and nobody ever touched it again.

Option 2 — Your baseUrl Isn’t “.”

If your baseUrl points somewhere other than the project root, deleting it will silently change how your paths resolve. In that case, you need to prepend the baseUrl value to each paths entry instead of just removing it.

Say you had this:

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

It becomes:

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

Simple in theory. Tedious if you’ve got a dozen path mappings across three tsconfig files that all extend each other. Which is exactly why the next section matters.

Step-by-Step: Migrating With the Official Script

You don’t have to do this by hand. The TypeScript team pointed people toward a small open-source tool built specifically for this exact migration, and it handles both baseUrl cleanup and the related rootDir change (more on that below) in one pass.

Here’s the walkthrough:

Open a terminal in your project root — wherever your main tsconfig.json lives.
Run the baseUrl fixer without installing anything globally: npx @andrewbranch/ts5to6 --fixBaseUrl .
Let it do the traversal. The tool follows references and extends automatically, so if you’ve got a monorepo with multiple tsconfig files pointing at each other, it updates all of them — not just the one you ran it against.
Diff your changes before committing. The script is safe, but you should still eyeball what it touched. Sometimes a paths entry gets a prefix you didn’t expect if your folder structure is unusual.
Re-run your build. The warning should be gone. If it isn’t, check whether you have a second, separate tsconfig (like tsconfig.build.json or tsconfig.test.json) that the script didn’t reach — point it there too.
Point a non-default config file explicitly if your setup isn’t just tsconfig.json: npx @andrewbranch/ts5to6 --fixBaseUrl ./tsconfig.app.json

Honestly, this is the part people overtink. The script exists precisely so you don’t have to manually cross-reference every path alias against your old baseUrl value. Use it.

rootDir, module, and the Other 6.0 Changes You’ll Bump Into

This trips up a lot of people: baseUrl almost never shows up alone. TypeScript 6.0 deprecated a batch of related options at the same time, and if you’re touching your tsconfig anyway, it’s worth checking for these too — because they’ll surface the moment you fix baseUrl and re-run your build.

Option	What Changed	Quick Fix
`baseUrl`	Deprecated, unnecessary since TS 4.1	Remove it or fold into `paths`
`rootDir`	Now defaults to the tsconfig’s directory instead of being inferred from your files	Set `rootDir` explicitly if output nesting looks off
`moduleResolution: "node10"` / `"classic"`	Deprecated in favor of modern resolution modes	Switch to `"bundler"` or `"node16"`/`"nodenext"`
`module: "amd"` / `"umd"`	Functionality removed outright	Use a bundler (esbuild, Rollup, webpack, Vite) instead
`target: "ES5"`	Deprecated	Bump to a modern target like `"ES2020"` or later
`esModuleInterop: false` / `allowSyntheticDefaultImports: false`	Deprecated as `false`	Leave them at their (now-default) `true` value
`types` default	Used to auto-include everything in `@types`; now defaults to `[]`	Explicitly list needed type packages, e.g. `"types": ["node", "jest"]`

That rootDir one deserves a callout on its own, because the symptom looks completely unrelated to the fix. If your compiled output suddenly nests everything one folder deeper than before — like files landing in dist/src/ instead of dist/ — that’s this change, not a bug in your build tool. Either set rootDir explicitly or let the same migration script handle it:

npx @andrewbranch/ts5to6 --fixRootDir .

Silencing the Warning Temporarily (If You Need Breathing Room)

Sometimes you genuinely can’t fix this today — maybe it’s a huge legacy codebase, maybe the fix needs sign-off from another team. TypeScript gives you an escape hatch, but it’s a pause button, not a permanent solution.

Add this to your compilerOptions:

{
  "compilerOptions": {
    "ignoreDeprecations": "6.0"
  }
}

This tells the compiler you’re aware baseUrl (and the other options deprecated at the same version) is on its way out, and to hold off on erroring about it. Only "5.0" and "6.0" are accepted values here — there’s no wildcard “ignore everything forever” setting, which is deliberate. It buys you time; it doesn’t buy you an exemption from TypeScript 7.

A word of caution from having watched teams do this: ignoreDeprecations is exactly the kind of flag that gets added under deadline pressure and then forgotten for two years. If you set it, drop a linked ticket or a // TODO comment right next to it so someone actually circles back before the 7.0 upgrade lands.

Common Pitfalls After Removing baseUrl

A few things catch people off guard even after they’ve technically “fixed” the warning:

Absolute imports without any alias. If your code did import { thing } from 'utils/thing' relying purely on baseUrl resolution — with no paths entry backing it — removing baseUrl breaks those imports outright. You’ll need to either add a proper paths alias or switch those imports to relative paths.
IDE autocomplete lagging behind. VS Code sometimes caches the old TS server state. If imports look broken in the editor but the CLI build is clean, restart the TS server (Cmd/Ctrl+Shift+P → “TypeScript: Restart TS Server”) before assuming something’s actually wrong.
Monorepo tools that read tsconfig separately from tsc. Tools like Jest’s moduleNameMapper, webpack’s resolve.alias, or ESLint’s import resolver often duplicate your paths config independently. Fixing tsconfig.json alone won’t update those — you’ll need to mirror the change wherever else the alias is declared.
Editors and linters flagging “unused” baseUrl differently. Not every tool understands the deprecation the same way tsc does, so don’t be surprised if one tool stays quiet while another still nags you — check each one separately rather than assuming a single fix covers everything.

This won’t apply to everyone, but for larger codebases with multiple build tools layered on top of TypeScript, budget a bit more time than “delete one line.”

Quick Checklist Before You Ship the Fix

[ ] Confirm whether your baseUrl value is "." (safe to delete) or something else (needs prefixing into paths)
[ ] Run the migration script, or do the manual prefix update
[ ] Check for the related rootDir output-nesting issue
[ ] Search for any raw imports that relied on baseUrl with no paths entry
[ ] Update Jest/webpack/ESLint alias configs if they mirror your tsconfig paths
[ ] Rebuild and confirm the warning is gone
[ ] Remove any ignoreDeprecations flag once the real fix is in

Frequently Asked Questions

What does “Option ‘baseUrl’ is deprecated and will stop functioning in TypeScript 7” actually mean?

It means you’re running TypeScript 6.0 or later, and baseUrl is scheduled for full removal once you upgrade to TypeScript 7.0. The compiler is warning you ahead of time so you can update your tsconfig.json before that happens.

Do I have to fix this right now?

Not immediately — the option still works in 6.0, it’s just flagged. But you’ll want to fix it before upgrading to 7.0, since at that point the option simply won’t do anything anymore.

Can I just delete baseUrl from my tsconfig.json?

Only if your baseUrl value is "." (the project root) and you’re not relying on it for anything besides enabling paths. If it points somewhere else, deleting it outright will change how your module paths resolve.

Will removing baseUrl break my paths aliases?

It can, if you don’t prepend the old baseUrl value to your existing paths entries. paths doesn’t need baseUrl to function anymore, but the mappings are still relative to wherever baseUrl used to point — so the paths themselves may need updating.

Is there an official tool to fix this automatically?

Yes. The TypeScript team’s migration guide points to a script (npx @andrewbranch/ts5to6 --fixBaseUrl .) that rewrites your tsconfig.json — including any files it references or extends — automatically.

What’s the difference between deprecated and removed?

Deprecated means TypeScript still honors the option but shows a warning. Removed means the option is ignored completely. For baseUrl, that transition happens between TypeScript 6.0 (deprecated) and TypeScript 7.0 (removed).

How do I temporarily silence this warning without fixing it?

Add "ignoreDeprecations": "6.0" to your compilerOptions. It’s meant as a short-term buffer, not a permanent setting — it won’t protect you once you’re actually on TypeScript 7.

Why does my build output suddenly have an extra folder level after upgrading?

That’s most likely the related rootDir change from the same TypeScript 6.0 release, not the baseUrl fix itself. Set rootDir explicitly in your tsconfig to restore the old output layout.

Does this affect JavaScript projects using jsconfig.json?

The same deprecation logic applies to jsconfig.json since it uses the same compiler options under the hood. If you’ve got baseUrl there for path aliases, follow the same fix.

Will my editor show this warning too, or only the CLI build?

Both, generally — VS Code’s built-in TypeScript support uses the same compiler, so you’ll typically see the squiggly warning in your tsconfig.json file as well as in terminal builds.

Is this related to the TypeScript 7 native compiler rewrite?

Not directly a feature of it, but the timing lines up. The TypeScript team has been cleaning up legacy, redundant options ahead of the bigger TypeScript 7 changes, and baseUrl was one of several candidates that had been unnecessary for years.

What other options were deprecated alongside baseUrl?

In the same release, the team also flagged moduleResolution: "node10"/"classic", target: "ES5", module: "amd"/"umd" (removed outright), esModuleInterop: false, allowSyntheticDefaultImports: false, and a change to how rootDir defaults are inferred.

Wrapping It Up

To recap the key points:

baseUrl is deprecated starting in TypeScript 6.0 and will be fully removed in TypeScript 7.0
Most projects can simply delete baseUrl if its value is "."
If it points elsewhere, prepend that value to each entry in paths instead
The official migration script (npx @andrewbranch/ts5to6 --fixBaseUrl .) handles this automatically, including across referenced tsconfig files
Watch for the related rootDir default change hitting your build output at the same time
ignoreDeprecations buys you time — it isn’t a fix

Your next move is straightforward: open your tsconfig.json, check what baseUrl is actually set to, and either delete it or run the migration script. It’s a five-minute job for most projects, and it clears the way for a smoother upgrade whenever TypeScript 7 actually ships.

You may also read: How to Migrate Legacy tsconfig.json Files to Modern Module Resolution

For the complete, official breakdown straight from the TypeScript team, check the TypeScript 6.0 migration guide on GitHub.

This article reflects the TypeScript 6.0 deprecation behavior as documented in the TypeScript compiler source and the official migration guide. Always check your installed TypeScript version (tsc -v) and the official release notes before making config changes on a production codebase.

TypeScript baseUrl Deprecated? Here’s the Real Fix