Skip to content

fix(docs): drop inherited baseUrl so typecheck survives TypeScript 7 - #13

Merged
bloxster merged 1 commit into
mainfrom
fix/tsconfig-drop-baseurl
Jul 27, 2026
Merged

bloxster merged 1 commit into
mainfrom
fix/tsconfig-drop-baseurl

Conversation

@bloxster

Copy link
Copy Markdown
Contributor

Why

npm run typecheck is gated in both workflows here, so Dependabot #9 (typescript 6.0.3 → 7.0.2) is correctly red:

tsconfig.json(3,3): error TS5102: Option 'baseUrl' has been removed.
                                  Please remove it from your configuration.

@docusaurus/tsconfig sets baseUrl. The existing "ignoreDeprecations": "6.0" silenced TS 6's TS5101 deprecation warning, but TS 7 rejects the option itself, so that escape hatch is gone — and an inherited compilerOption cannot be unset by the extending config. While upstream still ships baseUrl (it does as of 3.10.2), extends and a green typecheck are mutually exclusive.

What

  1. tsconfig.json — inline the base config minus baseUrl, dropping the now-useless ignoreDeprecations.
  2. scripts/check-tsconfig-drift.mjs (+ npm run check:tsconfig) — the cost of inlining is that upstream changes stop reaching us, so this diffs our copy against node_modules/@docusaurus/tsconfig modulo declared deltas, and says so when upstream drops baseUrl and the workaround can be deleted. Wired into both workflows beside the existing typecheck.

The guard depends on nothing but Node, deliberately: a guard that imports typescript breaks under the very upgrade it guards (learned the hard way in erigontech/cocoon#37).

This also fixes @site/*, which was silently broken

Relative paths in an extended config resolve against that config's own directory, so the inherited baseUrl: "." pointed inside node_modules:

extends @docusaurus/tsconfig:  pathsBasePath = <root>/node_modules/@docusaurus/tsconfig
                               @site/foo -> UNRESOLVED
inlined, no baseUrl:           pathsBasePath = <root>
                               @site/foo -> <root>/foo

TypeScript now agrees with Docusaurus's own webpack @site → siteDir alias.

Verification

TS 6.0.3 TS 7.0.2
npm run check:tsconfig exit 0 exit 0
npm run typecheck exit 0 exit 0
npm run build exit 0 exit 0

Unblocks #9.

🤖 Generated with Claude Code

`npm run typecheck` is gated in both workflows here, so Dependabot #9
(typescript 6.0.3 -> 7.0.2) is correctly red:

  tsconfig.json(3,3): error TS5102: Option 'baseUrl' has been removed.
                                    Please remove it from your configuration.

`@docusaurus/tsconfig` sets `baseUrl`. The existing `"ignoreDeprecations":
"6.0"` silenced TS 6's TS5101 deprecation warning, but TS 7 rejects the option
itself, so that escape hatch is gone — and an inherited compilerOption cannot
be unset by the extending config. While upstream still ships baseUrl (it does
as of 3.10.2), `extends` and a green typecheck are mutually exclusive.

Inline the base config minus baseUrl. This also fixes `@site/*`, which was
quietly broken: relative paths in an extended config resolve against that
config's own directory, so the inherited `baseUrl: "."` pointed at
node_modules/@docusaurus/tsconfig and `@site/foo` resolved to nothing. With
baseUrl gone, `paths` resolves against the site root, matching Docusaurus's
own webpack alias.

Add scripts/check-tsconfig-drift.mjs (+ `npm run check:tsconfig`) so the
inline copy cannot silently rot, wired into both workflows next to the
existing typecheck. It depends on nothing but Node — deliberately, since a
guard that imports `typescript` breaks under the very upgrade it guards
(learned the hard way in cocoon#37).

Verified: check:tsconfig and typecheck exit 0 under both 6.0.3 and 7.0.2, and
`npm run build` succeeds. Unblocks #9.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@bloxster
bloxster merged commit 124b550 into main Jul 27, 2026
1 check passed
@bloxster
bloxster deleted the fix/tsconfig-drop-baseurl branch July 27, 2026 11:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant