---
id: wiki-20260508-ambient-declarations-redir
title: Ambient Declarations
category: 10_Wiki/Topics
status: verified
canonical_id: self
aliases: [Ambient Declarations, declare, .d.ts, Type Declarations]
duplicate_of: none
source_trust_level: A
confidence_score: 0.92
verification_status: applied
tags: [typescript, types, declaration, dts]
raw_sources: []
last_reinforced: 2026-05-10
github_commit: pending
tech_stack:
  language: typescript
  framework: TypeScript 5.x
---

# Ambient Declarations

## 매 한 줄
> **"매 TS 가 외부 의 untyped JS / runtime global / module 의 type 의 알려주는 declaration"**. 매 `declare` keyword 로 매 implementation 없이 매 type shape 만 표현 — 매 .d.ts file 의 핵심. 매 TypeScript 의 gradual typing 의 backbone, 매 DefinitelyTyped (`@types/*`) 의 1B+ weekly downloads 의 base.

## 매 핵심

### 매 Forms
- **Ambient variable**: `declare const VERSION: string;`
- **Ambient function**: `declare function gtag(...args: unknown[]): void;`
- **Ambient class**: `declare class Foo { x: number; }`
- **Ambient module**: `declare module "lodash" { ... }`
- **Ambient namespace**: `declare namespace JSX { interface Element {} }`
- **Global augmentation**: `declare global { interface Window { myApp: App; } }`

### 매 Use cases
1. Untyped 3rd-party JS lib 의 type shim.
2. Build-time globals (Webpack `process.env.NODE_ENV`, Vite `import.meta.env`).
3. Module augmentation (Express `Request.user`).
4. Asset imports (`*.svg`, `*.css`).

### 매 응용
- 매 `@types/node`, `@types/react` — DefinitelyTyped 의 ambient declarations.
- 매 `vite-env.d.ts`, `next-env.d.ts` — framework boilerplate.
- 매 internal monorepo 의 shared globals.

## 💻 패턴

### Global ambient
```typescript
// globals.d.ts
declare const __APP_VERSION__: string;  // injected by webpack DefinePlugin
declare const gtag: (cmd: string, ...args: unknown[]) => void;
```

### Module declaration (untyped lib)
```typescript
// shims.d.ts
declare module "untyped-lib" {
  export function doThing(x: number): string;
  export const version: string;
}
```

### Asset imports
```typescript
// assets.d.ts
declare module "*.svg" {
  const content: string;
  export default content;
}
declare module "*.css" {
  const styles: { readonly [key: string]: string };
  export default styles;
}
```

### Module augmentation
```typescript
// express.d.ts
import { User } from "./user";
declare global {
  namespace Express {
    interface Request {
      user?: User;
    }
  }
}
export {};  // 매 file 의 module 로 만든 — augmentation 의 trigger
```

### Window augmentation
```typescript
declare global {
  interface Window {
    __REDUX_DEVTOOLS_EXTENSION__?: () => unknown;
    dataLayer: Array<Record<string, unknown>>;
  }
}
export {};
```

### .d.ts for own JS file
```typescript
// my-lib.d.ts (next to my-lib.js)
export declare function add(a: number, b: number): number;
export declare const VERSION: string;
```

## 매 결정 기준
| 상황 | Approach |
|---|---|
| 3rd-party lib + DefinitelyTyped 존재 | `pnpm add -D @types/<lib>` |
| 3rd-party lib, types 없음 | 자체 `.d.ts` shim |
| Build-time global (`process.env`) | `declare const` in `env.d.ts` |
| Add field to Express Request | module augmentation |
| Add to Window | `declare global { interface Window {} }` |
| Asset (SVG, CSS module) | `declare module "*.svg"` |

**기본값**: 매 framework template 의 `*-env.d.ts` 의 활용 + DefinitelyTyped first.

## 🔗 Graph
- 부모: [[TypeScript]] · [[Type System]]
- 변형: [[선언 파일(dts)]] · [[Module Augmentation]]
- 응용: [[DefinitelyTyped]] · [[@types/node]]
- Adjacent: [[Declaration Merging]] · [[Triple-Slash Directives]]

## 🤖 LLM 활용
**언제**: 매 .d.ts shim 의 생성, module augmentation 의 syntax, type shape 의 inference.
**언제 X**: 매 type 의 정확성 의 verify — 매 runtime 의 mismatch 의 silent.

## ❌ 안티패턴
- **`declare module "*"` (catch-all)**: 매 typo 의 silent — 매 specific glob 의 사용.
- **`any` 의 default in shim**: 매 type safety 의 lose.
- **`.d.ts` outside `include`**: tsconfig 의 안 잡힘 — `typeRoots` / `types` 의 verify.
- **Forgetting `export {}`** in module augmentation file: 매 global script 로 처리 — augmentation 의 fail.

## 🧪 검증 / 중복
- Verified (typescriptlang.org/docs/handbook/declaration-files).
- 신뢰도 A.

## 🕓 Changelog
| 날짜 | 변경 |
|---|---|
| 2026-05-08 | Phase 1 |
| 2026-05-10 | Manual cleanup — full ambient/global/augmentation coverage |