Writing .d.ts, module augmentation, global declarations, @types.

Declaration Files — .d.ts Type Definitions

Declaration files (.d.ts) provide type information for JavaScript code without TypeScript source. Generated automatically by tsc --declaration. Written manually for JS libraries without bundled types. Ambient module declarations (declare module "lib" { ... }) add types to untyped modules. Module augmentation extends existing module types (extending Express Request). Global augmentation adds to global namespace (Window, process.env). DefinitelyTyped (@types/lodash) provides community types for popular libraries.

Interactive Pipeline Flow

UnderstandImplementOptimise

🔧 Generate — tsc --declaration

Generate: tsc --declaration --emitDeclarationOnly creates .d.ts files without JavaScript. Add declaration:true, declarationDir to tsconfig. This is the output of a TypeScript library build.

Architecture Diagrams

Extending Express Request with custom properties.

Loading diagram...

Key Design Decisions

➕Module augmentation requires a module context

declare module 'express' {} in a script file (.d.ts without import/export) creates a new module, not an augmentation. Add import {} from 'express' at the top to make it a module context.

📦Always verify @types version matches library version

@types/react@18 and react@19 may have type incompatibilities. Check peerDependencies of the @types package. When mismatched, you can use typeRoots to prefer custom types over @types.

🌐Use declare global for extending built-ins

declare global { interface Window { gtag: Function } } adds gtag to Window type globally. Must be in a module file (has import/export). Without it, window.gtag is a type error.

Discussion