2nd/10_Wiki/Topics/Programming & Language/Ambient Declarations.md

id, title, category, status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, verification_status, tags, raw_sources, last_reinforced, github_commit, tech_stack

id	title	category	status	canonical_id	aliases	duplicate_of	source_trust_level	confidence_score	verification_status	tags	raw_sources	last_reinforced	github_commit	tech_stack
wiki-20260508-ambient-declarations-redir	Ambient Declarations	10_Wiki/Topics	verified	self	Ambient Declarations declare .d.ts Type Declarations	none	A	0.92	applied	typescript types declaration dts		2026-05-10	pending	language framework typescript 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

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

Module declaration (untyped lib)

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

Asset imports

// 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

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

Window augmentation

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

.d.ts for own JS file

// 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