What happened?
npm run typecheck is both broken and destructive. Running it corrupts the working tree in a way that silently breaks npm run build afterwards.
Two separate defects in tsconfig.json:
1. It fails outright — the base config isn't installed.
tsconfig.json extends @tsconfig/docusaurus/tsconfig.json, which is not a dependency of this repo. The dependency we actually have is @docusaurus/tsconfig. So the very first thing tsc reports is:
tsconfig.json(3,14): error TS6053: File '@tsconfig/docusaurus/tsconfig.json' not found.
With the base config missing, none of its compiler options apply, so tsc falls back to defaults and emits a cascade of ~100 misleading errors that are purely artifacts of the missing config — no jsx, no esModuleInterop, no path aliases:
src/pages/index.tsx(13,5): error TS17004: Cannot use JSX unless the '--jsx' flag is provided.
src/pages/index.tsx(1,8): error TS1259: Module '.../@types/react/index' can only be default-imported using the 'esModuleInterop' flag
src/pages/index.tsx(3,18): error TS2307: Cannot find module '@docusaurus/Link' or its corresponding type declarations.
2. It has no noEmit, so it writes compiled .js files into src/ — and that breaks the build.
Because the missing base config also carried noEmit, tsc emits. It drops ~32 compiled CommonJS .js files right next to their .tsx sources:
src/components/background-gradient-animation.js (next to .tsx)
src/components/tracing-beam.js (next to .tsx)
src/components/lamp.js, spotlight.js, parallax.js, …
src/components/aceternity/*.js
src/pages/index.js
src/utils/cn.js
Webpack resolves .js before .tsx, so it picks up this broken output instead of the real sources. The compiled files are CommonJS (exports.BackgroundGradientAnimation = void 0), which webpack reads as having no usable named exports:
export 'BackgroundGradientAnimation' was not found in '@site/src/components/background-gradient-animation' (possible exports: __esModule)
export 'default' (imported as 'TracingBeam') was not found in '@site/src/components/tracing-beam' (possible exports: __esModule)
and then the production build dies during SSG on every page:
Error: Can't render static file for pathname "/docs/SDKs/partner-go"
[cause]: Error: Element type is invalid: expected a string (for built-in components)
or a class/function (for composite components) but got: undefined.
The emitted files are untracked, so git status shows a wall of 32 unexplained ?? entries and nothing in the build output points back at typecheck as the cause. Hit this while validating #131 — it reads as "the dependency bump broke the build," which is exactly the wrong conclusion and cost a debugging cycle to rule out.
Steps to reproduce
- Fresh clone,
npm ci (or any tree where npm run build currently succeeds).
- Confirm the build is green:
npm run build → Generated static files in "build".
- Run
npm run typecheck. It exits non-zero with TS6053 plus ~100 downstream errors.
git status --porcelain | grep '^??' | wc -l → 32 newly emitted .js files under src/.- Run
npm run build again → now fails with Element type is invalid on every page.
- Recover with:
git status --porcelain | grep '^??' | sed 's/^?? //' | xargs rm -f && npm run clear, then the build is green again.
Version / environment
main @ e6a3db5 (and every commit before it — long-standing, not introduced by #131). Docusaurus 3.10.1, TypeScript ~5.2.2, Node v24.14.0, Linux.
Logs / screenshots
Suggested fix — both defects are in tsconfig.json:
noEmit is the important half — it makes the failure mode non-destructive even if the extends is wrong again later. Worth adding src/**/*.js to .gitignore as a belt-and-braces guard, though the real fix makes it unnecessary.
Note the comment already at the top of tsconfig.json: "This file is not used in compilation. It is here just for a nice editor experience." That's precisely why it should never emit.
Found while validating #131 (zero-vulnerability dependency sweep). Noted at the bottom of change record #130.
What happened?
npm run typecheckis both broken and destructive. Running it corrupts the working tree in a way that silently breaksnpm run buildafterwards.Two separate defects in
tsconfig.json:1. It fails outright — the base config isn't installed.
tsconfig.jsonextends@tsconfig/docusaurus/tsconfig.json, which is not a dependency of this repo. The dependency we actually have is@docusaurus/tsconfig. So the very first thing tsc reports is:With the base config missing, none of its compiler options apply, so tsc falls back to defaults and emits a cascade of ~100 misleading errors that are purely artifacts of the missing config — no
jsx, noesModuleInterop, no path aliases:2. It has no
noEmit, so it writes compiled.jsfiles intosrc/— and that breaks the build.Because the missing base config also carried
noEmit, tsc emits. It drops ~32 compiled CommonJS.jsfiles right next to their.tsxsources:Webpack resolves
.jsbefore.tsx, so it picks up this broken output instead of the real sources. The compiled files are CommonJS (exports.BackgroundGradientAnimation = void 0), which webpack reads as having no usable named exports:and then the production build dies during SSG on every page:
The emitted files are untracked, so
git statusshows a wall of 32 unexplained??entries and nothing in the build output points back attypecheckas the cause. Hit this while validating #131 — it reads as "the dependency bump broke the build," which is exactly the wrong conclusion and cost a debugging cycle to rule out.Steps to reproduce
npm ci(or any tree wherenpm run buildcurrently succeeds).npm run build→Generated static files in "build".npm run typecheck. It exits non-zero withTS6053plus ~100 downstream errors.git status --porcelain | grep '^??' | wc -l→ 32 newly emitted.jsfiles undersrc/.npm run buildagain → now fails withElement type is invalidon every page.git status --porcelain | grep '^??' | sed 's/^?? //' | xargs rm -f && npm run clear, then the build is green again.Version / environment
main@e6a3db5(and every commit before it — long-standing, not introduced by #131). Docusaurus 3.10.1, TypeScript ~5.2.2, Node v24.14.0, Linux.Logs / screenshots
Suggested fix — both defects are in
tsconfig.json:{ // This file is not used in compilation. It is here just for a nice editor experience. "extends": "@docusaurus/tsconfig", // was: "@tsconfig/docusaurus/tsconfig.json" (not installed) "compilerOptions": { "noEmit": true, // never write .js next to the .tsx sources "baseUrl": "." // … } }noEmitis the important half — it makes the failure mode non-destructive even if the extends is wrong again later. Worth addingsrc/**/*.jsto.gitignoreas a belt-and-braces guard, though the real fix makes it unnecessary.Note the comment already at the top of
tsconfig.json: "This file is not used in compilation. It is here just for a nice editor experience." That's precisely why it should never emit.Found while validating #131 (zero-vulnerability dependency sweep). Noted at the bottom of change record #130.