A TypeScript project has a declaration file containing `declare const BUILD_ID: string;`. Every use of `BUILD_ID` type-checks, yet the deployed app throws "BUILD_ID is not defined" at runtime. What does the `declare` keyword actually guarantee, and how would you stop this class of failure?

## What declare means `declare` marks a declaration as **ambient**: a description of something that exists elsewhere, provided by a script tag, a build-time substitution, a host environment, or a JavaScript file the compiler never sees. Ambient declarations have no implementation and produce no output. `declare const BUILD_ID: string` compiles to nothing at all, exactly like an `interface`. The compiler's contract is one-directional. You promise that a `BUILD_ID` of type `string` will be reachable at runtime; the compiler believes you and type-checks every use against that promise. It never verifies the claim, because it cannot — the thing you are describing is outside the program by definition. That makes every ambient declaration an untested integration point. The most common failures are all the same shape: - The bundler's compile-time replacement was never configured, or the name in the config differs by one character from the name in the declaration. - The `<script>` that defines the global is missing in one environment (the test harness, a preview build) but present in another. - The value exists but is not a `string` — a number, or `undefined` under some conditions — and everything downstream silently misbehaves rather than failing loudly. ## The same trap in other ambient forms ```ts declare function trackEvent(name: string): void; declare class LegacyWidget { constructor(el: HTMLElement); render(): void; } declare module 'legacy-charts'; ``` Each emits nothing. `declare class` is especially misleading: `new LegacyWidget(el)` type-checks and compiles to a plain `new` on a name that may not exist. The shorthand ambient module in the third line is the bluntest of all — a `declare module` with **no body** types every import from that specifier as `any`, so `import { anything } from 'legacy-charts'` compiles no matter what you name and every downstream type check is disabled. It is a useful unblocking tool during a migration and a very poor permanent state. ## Diagnosing the failure When a symbol type-checks but is undefined at runtime, work from the emitted output backwards: 1. Search the built bundle for the identifier. If the build was supposed to substitute a literal, the identifier should not be there at all; if it is, the substitution never happened. 2. Check whether the declaration is the *only* place that name appears in the repo. An ambient name with no build config and no script that defines it is a dangling promise. 3. Confirm the environment. Globals injected by one host are frequently absent in another, so the same code passes in the browser bundle and fails in a server render or a unit test. ## Designing the failure out The durable fix is to replace the promise with something the compiler can check. **Prefer a module over a global.** If the build can generate a small module, do that instead: ```ts // generated at build time: src/build-info.ts export const BUILD_ID = 'a1b2c3'; ``` Now a missing file is a module-resolution error at compile time, and the value has one obvious owner. Nothing is ambient. **If it must be a global, validate it once at the boundary.** Declare it as possibly missing and force the check: ```ts declare global { var BUILD_ID: string | undefined; } export function buildId(): string { const value = globalThis.BUILD_ID; if (typeof value !== 'string') { throw new Error('BUILD_ID was not injected by the build'); } return value; } ``` The type now tells the truth, the checker forces every caller through one accessor, and the failure becomes a loud startup error with a message that names the cause instead of a `ReferenceError` deep in a request path. **Keep ambient surface small.** Every `declare` is a line of type-checking you have opted out of. Concentrate them in one declarations file, review them like a public API, and make the build assert what it injects — a single startup check that all expected globals are present is worth more than any amount of type annotation, because the annotation is the one thing that provably cannot fail. ## The general principle This is the erasure rule showing its teeth. TypeScript's type layer is removed at emit, so no annotation can create, verify, or defend a runtime value. Assertions, non-null `!`, type predicates and ambient declarations all share the property that the compiler trusts you; ambient declarations are simply the version where the trusted claim is about a value that may not exist at all.