Debugging TypeScript Module Augmentation When It Silently Fails

The first ten minutes — establish facts before touching code.

• 1Run `npx tsc --noEmit --traceResolution` and grep for your target module to see exactly how TypeScript resolves it.
• 2Check the augmentation file for a top-level `import` or `export` statement—without one, it's an ambient module, not a module augmentation.
• 3Verify the module name string: `declare module 'my-library'` must match exactly the string used in `import from 'my-library'` inside your project.
• 4Open the compiled `.d.ts` file (if emitDeclarationOnly) and confirm the augmentation is present; if not, the file may be excluded from `tsconfig.json`.
• 5In the runtime code, add a `console.log` in the augmentation file and see if it executes when you import the target module. If not, the augmentation file isn't being loaded.

The specific files, logs, configs, and dashboards that usually own this bug.

• search`tsconfig.json` – Check `files`, `include`, `exclude`, and `rootDir` settings that might omit the augmentation file.
• searchThe augmentation file itself – Ensure it has at least one `export {}` to make it a module.
• searchThe target library's type definitions – Look at `node_modules/library/index.d.ts` for the exact module name used in `declare module`.
• searchThe compiled output – If using `declaration`, check the `.d.ts` file for your augmentation. If missing, TypeScript is not considering it.
• search`node_modules/@types/library` – Sometimes the types are in a different package, causing module name mismatch.
• searchBundler configuration (webpack, Rollup) – Check that side-effect imports aren't tree-shaken. Look for `sideEffects` in `package.json`.
• search`tsconfig.json` `paths` or `baseUrl` – These can alter module resolution and cause the augmentation to target a different resolved path.

Practical causes, not theory. These are the things you will actually find.

• warningAugmentation file is an ambient module (no import/export) – TypeScript treats it as a script, not a module, so the `declare module` becomes a global augmentation, not a module augmentation.
• warningModule name string mismatch – Even a trailing slash or different case causes the augmentation to silently target a different module (or none).
• warningAugmentation file excluded from compilation – The file is not included via `include`/`files` or is excluded via `exclude`.
• warningMissing import of the augmentation file – The augmentation file must be imported as a side effect somewhere in your project (e.g., `import './augment'`).
• warningTree-shaking by bundler – The bundler removes the side-effect import because it detects no used exports. Fix with `sideEffects: false` in package.json or use a direct import.
• warningMultiple augmentations conflict – Two augmentation files that try to augment the same module can cause one to override the other silently.
• warningTypeScript version differences – Some older versions had bugs with module augmentation resolution.

Concrete fix directions. Pick the one that matches your root cause.

• buildAdd `export {}` at the top of your augmentation file to make it a module. This turns `declare module` into a proper module augmentation.
• buildDouble-check the module name by copying it from the actual import statement in your code. Use `console.log(require.resolve('my-library'))` in Node to verify path.
• buildImport the augmentation file at the entry point of your application: `import './path/to/augment';`. Ensure this import is not removed by tree-shaking by setting `"sideEffects": ["./path/to/augment"]` in package.json.
• buildIf using `paths` in tsconfig, ensure the augmentation uses the same alias. Better: avoid `paths` for the target module and use the real module name.
• buildCheck for typeRoots or types configuration that might be overriding the default type resolution. Remove custom typeRoots if not needed.
• buildUse `tsc --listFiles` to confirm your augmentation file is included in the compilation. If not, add it to `include`.
• buildFor global augmentations (adding to `Window` etc.), use `declare global { interface Window { ... } }` inside a module.

A fix you cannot prove is a guess. Close the loop.

• verifiedAfter fix, run `npx tsc --noEmit` and observe zero errors. Then check that IntelliSense shows the augmented members.
• verifiedWrite a simple test file that imports the target module and uses the augmented property. Compile with `tsc` and run the output in Node or browser.
• verifiedInspect the generated `.d.ts` file (if declaration is enabled) to confirm the augmentation is present.
• verifiedCheck the runtime: add `console.log('augmentation loaded')` in the augmentation file and verify it appears in the console when the app runs.
• verifiedUse `tsc --traceResolution` and grep for your target module name to see if the augmentation file is resolved as a module.
• verifiedTest in CI: ensure the same version of TypeScript, same node_modules, and same tsconfig are used locally and in CI.

Things that make this bug worse or harder to find.

• warningDon't assume that no compile errors means the augmentation works. TypeScript often compiles successfully even when the augmentation is not applied.
• warningAvoid naming the augmentation file `types.d.ts` – such files are often treated as ambient declarations. Use `.ts` extension instead.
• warningDon't forget that module augmentation only adds types; you still need to provide the runtime implementation. Many devs augment types but forget to polyfill the runtime.
• warningNever use `declare module 'my-library'` inside a file that is itself a declaration file (`.d.ts`) without an import/export. It becomes an ambient module declaration, not augmentation.
• warningDon't rely on `/// <reference>` directives for module augmentation; they don't work for augmenting modules.
• warningAvoid mixing `declare module` and `export` in the same file incorrectly – if you have exports, the `declare module` is a module augmentation; if not, it's an ambient module.

Frequently asked questions