bug: npm run typecheck fails and emits .js into src/, silently breaking npm run build

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

1. Fresh clone, npm ci (or any tree where npm run build currently succeeds).
2. Confirm the build is green: npm run build → Generated static files in "build".
3. Run npm run typecheck. It exits non-zero with TS6053 plus ~100 downstream errors.
4. git status --porcelain | grep '^??' | wc -l → 32 newly emitted .js files under src/.
5. Run npm run build again → now fails with Element type is invalid on every page.
6. 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:

{
  // 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": "."
    // …
  }
}

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.

Start with tsconfig.json and compare its extends setting with the installed Docusaurus configuration. Run npm ci, npm run typecheck, and npm run build before and after the change; done means typecheck no longer emits JavaScript into src/ and a subsequent build succeeds without the reported export or SSG errors.