Declaration Files & Publishing

## The one fact this rests on: types are erased TypeScript is a compile-time layer over JavaScript. When `tsc` compiles a file, it type-checks it and then emits JavaScript with the type layer **removed**. An `interface` emits nothing at all. A parameter annotation emits nothing. A generic parameter emits nothing. What remains is the runtime code you would have written by hand. That is exactly what you want at runtime — zero cost — but it creates a distribution problem. If you publish only the emitted `.js`, everything the compiler knew about your API is gone. A consumer importing your package is importing plain JavaScript, and their compiler has no idea that `createClient` takes an options object with a required `apiKey: string`. ## What a declaration file is A `.d.ts` file is the type-only mirror of a module: the same exported names, with their types, and **no implementations**. Given this source: ```ts export interface Options { apiKey: string; retries?: number } export function createClient(opts: Options) { return { send: (body: string) => body.length }; } ``` the compiler emits a `.js` with the `interface` gone and the function body intact, plus a `.d.ts` like: ```ts export interface Options { apiKey: string; retries?: number } export declare function createClient(opts: Options): { send: (body: string) => number; }; ``` Note that the return type, which you never wrote, has been **inferred and written out**. Declaration emit is a projection of what the checker inferred, not a copy of what you typed. ## Turning it on ```json { "compilerOptions": { "declaration": true, "outDir": "dist" } } ``` By default the `.d.ts` lands beside its `.js` inside `outDir`. `declarationDir` moves declarations to a separate tree if you want them apart. `emitDeclarationOnly` flips the emit around: `tsc` writes the declarations and skips the JavaScript, which is how you use it when a faster transpiler produces the runtime output and `tsc` is kept only for checking and types. Once the files exist, the package has to advertise them. Historically that is the top-level `types` field in `package.json` pointing at the entry declaration; modern packages with an `exports` map declare a `types` condition per entry point instead. ## What a consumer sees when it is missing With `noImplicitAny` on — which `strict` turns on — importing a package with no declarations is an error: *"Could not find a declaration file for module ..."*. With `noImplicitAny` off, it is worse in practice: the import silently becomes `any`, so every call through it is unchecked and nobody notices. A third path is the community `@types` ecosystem, where declarations for an untyped library are published separately. ## The gotcha: not every type can be declared Because declaration emit has to *write down* inferred types, it can fail where normal compilation succeeds. The classic error is a variant of *"has or is using name 'X' from external module ... but cannot be named"*: your exported function returns a type that lives in a module you never exported or imported by name, so the compiler has no way to spell it in the `.d.ts`. The fix is to import and re-export the type, or to annotate the export explicitly. The related cost is speed. To emit declarations, the compiler must fully check and infer — you cannot produce a correct `.d.ts` by looking at one file in isolation the way a transpiler produces `.js`. That is why declaration emit is usually the slow part of a library build, and why later TypeScript versions added an option that forces exported declarations to be explicitly annotated so the emit can be done per-file by other tools. ## Practical checklist for a published package - `"declaration": true` (plus `declarationMap` if you want go-to-definition to land in your source). - The `.d.ts` files are actually inside the published files — a `files` list or `.npmignore` that excludes them silently ships an untyped package. - `package.json` names the entry declaration so the consumer's resolver finds it. - Verify by installing the packed tarball into a scratch project rather than trusting the local build.