Antigravity Agent
147 lines
4.5 KiB
Markdown
147 lines
4.5 KiB
Markdown
---
|
|
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 |
|