.d.ts Files — Ambient Declarations, Asset Imports, Module Typing#

What it is#

A .d.ts (declaration) file is a types-only TypeScript file — it contains type signatures but no runtime code. The compiler reads .d.ts files to learn about external code (JavaScript libraries, build-tool asset imports, global variables injected by the runtime) without producing any JavaScript output. They are TypeScript’s only mechanism for telling the type-checker “this thing exists at runtime; here is what it looks like.” Every npm package that ships types delivers them as .d.ts files; every Vite project relies on a handful of .d.ts files to type CSS, SVG, and image imports.

When you need a .d.ts file#

You write a .d.ts file in five situations:

1. A JavaScript library without bundled types — older npm packages and internal one-off utilities.
2. Asset imports — your bundler turns import logo from './logo.svg' into a string, but TypeScript needs to be told.
3. Ambient globals — runtime injects window.__INITIAL_STATE__ or a build step defines process.env.API_URL.
4. Module augmentation — extending an existing package’s types (e.g. adding a property to Express’s Request).
5. Custom JSX intrinsics or custom elements — telling TS that <my-button> is a valid tag.

You do not need a .d.ts file for code you author yourself in .ts — the compiler infers types straight from your source.

ls src/types/

Output:

assets.d.ts
env.d.ts
express.d.ts
globals.d.ts

Anatomy of a declaration file#

A .d.ts file looks like a TypeScript file with the bodies stripped out. The declare keyword tells the compiler “trust me, this exists at runtime.”

// src/types/cache.d.ts
declare function memoize<T extends (...args: any[]) => any>(fn: T): T;

declare class Cache<K, V> {
  constructor(maxSize?: number);
  get(key: K): V | undefined;
  set(key: K, value: V): void;
  clear(): void;
}

declare const VERSION: string;

interface CacheStats {
  hits: number;
  misses: number;
}

export { memoize, Cache, VERSION, CacheStats };

Output: (none — exits 0 on success)

The declare keyword is implicit for interface and type aliases — they are inherently type-only. It’s required for function, class, const, let, var, enum, and namespace to make clear that no runtime code is being emitted.

declare module ‘foo’#

When you import an untyped JavaScript package, TypeScript fails with TS7016: “Could not find a declaration file for module ‘foo’.” Fix it by declaring the module’s shape ambiently.

// src/types/legacy-lib.d.ts
declare module 'legacy-lib' {
  export function init(config: { apiKey: string; timeout?: number }): void;
  export function fetch(path: string): Promise<unknown>;
  export const VERSION: string;

  interface User {
    id: string;
    name: string;
  }
  export type { User };
}

// src/app.ts
import { init, fetch, type User } from 'legacy-lib';

init({ apiKey: process.env.API_KEY!, timeout: 5000 });

Output: (none — exits 0 on success)

If you just need anything to silence the error, use the catch-all form. It types everything from the module as any — a stopgap, not a fix.

// src/types/quick-shim.d.ts
declare module 'untyped-lib';

For a wildcard match (every subpath under a namespace), use *:

declare module 'untyped-pkg/*' {
  const value: any;
  export = value;
}

Asset imports — typing the bundler#

Bundlers like Vite, Webpack, and esbuild let you import non-JavaScript files: SVG as URL, CSS Modules, raw text, JSON, images. The runtime works, but TypeScript has no idea what those imports return. You teach it with one-line module declarations.

// src/types/assets.d.ts

// Treat every .svg import as a string URL
declare module '*.svg' {
  const url: string;
  export default url;
}

// Vite's ?url suffix → string
declare module '*.svg?url' {
  const url: string;
  export default url;
}

// Vite's ?raw suffix → raw file contents as a string
declare module '*.svg?raw' {
  const contents: string;
  export default contents;
}

// CSS Modules
declare module '*.module.css' {
  const classes: Record<string, string>;
  export default classes;
}

// JSON
declare module '*.json' {
  const value: unknown;
  export default value;
}

// Images
declare module '*.png' {
  const url: string;
  export default url;
}
declare module '*.jpg' {
  const url: string;
  export default url;
}

Output: (none — exits 0 on success)

The pattern: each Vite/Webpack import suffix gets its own declare module '*.ext' block. The exported shape mirrors what the bundler injects at runtime.

[!TIP] Vite already ships these declarations in vite/client. Add /// <reference types="vite/client" /> (or "types": ["vite/client"] in tsconfig) and you get the full set without authoring them yourself.

The home-hero.svg?raw pattern#

This project’s home page uses Vite’s ?raw import to load an SVG as a literal string, then inlines it into the HTML for styling. The pattern:

// src/pages/index.astro (frontmatter)
import heroSvg from '../assets/home-hero.svg?raw';

// In the template: <div set:html={heroSvg} />

For TypeScript to accept this import without complaint, the project needs the matching declaration:

// src/types/assets.d.ts
declare module '*.svg?raw' {
  const contents: string;
  export default contents;
}

Without it, tsc --noEmit (run by Astro’s astro check) errors with:

src/pages/index.astro:8:23 - error TS2307: Cannot find module '../assets/home-hero.svg?raw' or its corresponding type declarations.

After the declaration is in place, the import is typed as string and the type-checker accepts the use of set:html={heroSvg} in the template.

astro check

Output:

Result (1 file):
- 0 errors
- 0 warnings
- 0 hints

declare global#

Some code reaches for genuinely global symbols — window.__INITIAL_STATE__, process.env, custom DOM elements. The declare global block lets you extend the global namespace from inside a module file.

// src/types/globals.d.ts
export {};   // makes this file a module

declare global {
  interface Window {
    __INITIAL_STATE__: { user: { id: string; name: string } | null };
    gtag: (event: string, action: string, params?: object) => void;
  }

  namespace NodeJS {
    interface ProcessEnv {
      readonly API_URL: string;
      readonly NODE_ENV: 'development' | 'production' | 'test';
      readonly DATABASE_URL: string;
    }
  }

  interface ImportMetaEnv {
    readonly VITE_API_URL: string;
    readonly VITE_FEATURE_FLAGS: string;
  }

  interface ImportMeta {
    readonly env: ImportMetaEnv;
  }
}

// src/app.ts
const initialUser = window.__INITIAL_STATE__?.user;     // typed!
const apiUrl = process.env.API_URL;                     // typed!
const viteApi = import.meta.env.VITE_API_URL;           // typed!

Output: (none — exits 0 on success)

The export {}; at the top is critical. Without it, the file is treated as a script (not a module) and the declare global block becomes ambient by default — which still works but mixes file kinds in ways that bite later.

[!WARNING] declare global only applies if the file is reachable from your tsconfig include. A .d.ts file in src/ is usually picked up automatically; one in types/ outside src/ needs to be added to include or typeRoots.

Ambient vs. module declaration files#

.d.ts files come in two flavours, and the distinction governs how the rest of your code sees them.

// Ambient style — adds Cache and memoize to global scope
declare class Cache<K, V> { /* ... */ }
declare function memoize<T>(fn: T): T;

// Module style — exports Cache and memoize as named imports
export declare class Cache<K, V> { /* ... */ }
export declare function memoize<T>(fn: T): T;

The choice depends on intent. Ambient is right for build-time injection (globals, asset modules); module style is right when consumers should import { Cache } from 'my-types'.

Triple-slash directives#

Triple-slash directives are one-line instructions at the top of a .d.ts (or .ts) file. They predate ES modules and are mostly used to compose declaration files.

/// <reference types="node" />
/// <reference path="./shared.d.ts" />
/// <reference lib="dom" />

The most common use is at the top of a Vite project’s env.d.ts:

/// <reference types="vite/client" />

This single line imports all of Vite’s bundler asset typings (*.svg, *.css, *.svg?raw, *.png, …) so you don’t have to author them.

tsconfig: types, typeRoots, include#

The compiler decides which .d.ts files to load via three settings.

{
  "compilerOptions": {
    "types": ["node", "vite/client"],
    "typeRoots": ["./node_modules/@types", "./src/types"]
  },
  "include": ["src/**/*"]
}

The most frequent mistake: setting types: ["node"] and forgetting to add "vite/client", breaking every asset import. The two are independent — types is an exhaustive list once set.

[!TIP] For most projects, leave types unset and rely on auto-discovery. Only set it when you have conflicting @types packages or want to lock down the type surface explicitly.

declare module augmentation#

You can extend an existing module’s declared types from your own .d.ts. The compiler merges your declarations into the original. This is declaration merging at the module level — see the dedicated declaration merging cheat sheet for the full mechanics.

// src/types/express.d.ts
import 'express';     // import the original module's declarations

declare module 'express' {
  interface Request {
    user?: { id: string; email: string };
    requestId: string;
  }
}

// src/middleware.ts
import type { Request, Response, NextFunction } from 'express';

export function authenticate(req: Request, res: Response, next: NextFunction): void {
  req.user = { id: 'u_1', email: 'alice@example.com' };
  req.requestId = crypto.randomUUID();
  next();
}

Output: (none — exits 0 on success)

The import 'express' at the top of the .d.ts is essential. It makes the file a module (so the declare module block is treated as an augmentation, not a re-declaration).

JSX intrinsic elements and custom elements#

If you use a custom web component (e.g. <my-button>), TypeScript’s JSX checker rejects it with TS2339: “Property ‘my-button’ does not exist on type ‘JSX.IntrinsicElements’.” Fix it by augmenting JSX.IntrinsicElements.

// src/types/custom-elements.d.ts
import type { DetailedHTMLProps, HTMLAttributes } from 'react';

declare global {
  namespace JSX {
    interface IntrinsicElements {
      'my-button': DetailedHTMLProps<HTMLAttributes<HTMLElement>, HTMLElement> & {
        variant?: 'primary' | 'secondary';
        size?: 'sm' | 'md' | 'lg';
      };
      'tool-tip': DetailedHTMLProps<HTMLAttributes<HTMLElement>, HTMLElement> & {
        for: string;
      };
    }
  }
}

// src/App.tsx
function App() {
  return (
    <my-button variant="primary" size="md">
      Click me
    </my-button>
  );
}

Output: (none — exits 0 on success)

Common pitfalls#

1. Missing export {}; in a declare global file — the file silently becomes a script, polluting the global scope. Always add it when the file contains declare global and nothing else.
2. .d.ts files not in include — declarations in types/ outside src/ are never loaded. Either add the directory to include or move it under src/.
3. declare module '*.svg' collides with vite/client — declaring the same module twice causes “Duplicate identifier ‘default’” errors. Remove your custom block if you’ve added /// <reference types="vite/client" />.
4. declare module 'foo' doesn’t merge with the real package — works only when there’s a missing-types error. If the package ships its own .d.ts, you need module augmentation (import 'foo'; declare module 'foo' { … }), not a fresh declaration.
5. Mixing export = and ES exports — export = X declares a single CJS-style export. It’s incompatible with export { X } in the same file. Pick one.
6. declare class with method bodies — .d.ts files cannot contain function bodies. Use signatures only: foo(): string; not foo() { return 'x'; }.
7. process.env.MY_VAR typed as string | undefined even after augmenting ProcessEnv — the augmentation only flows when the file is reachable. Confirm with tsc --listFiles | grep globals.d.ts.
8. Triple-slash directive after the first import — directives must be at the top of the file, before any other statement. Move them above all imports.
9. @types/foo and bundled types conflict — newer versions of foo ship their own types, making @types/foo redundant. Uninstall @types/foo to avoid “Subsequent property declarations must have the same type” errors.
10. export default in a .d.ts for a CJS module — CJS modules use export = . Mixing forms breaks consumer imports under verbatimModuleSyntax.

Real-world recipes#

Typing the Astro home-hero.svg?raw import#

This project’s src/pages/index.astro does:

import heroSvg from '../assets/home-hero.svg?raw';

The matching declaration lives in src/env.d.ts (or any .d.ts reachable from include):

/// <reference types="astro/client" />

declare module '*.svg?raw' {
  const contents: string;
  export default contents;
}

astro check

Output:

Result (12 files):
- 0 errors
- 0 warnings
- 0 hints

astro/client already covers *.svg, *.png, *.jpg, *.css?inline, and a few more. The ?raw suffix is a Vite extension, so you supplement it with the explicit declaration above.

Typing window.INITIAL_STATE for SSR hydration#

A server-rendered page injects initial state into a <script> tag; the client picks it up from window. Type it so the client code doesn’t read any.

<!-- server-rendered HTML -->
<script>window.__INITIAL_STATE__ = { user: { id: 'u_1', name: 'Alice Dev' } };</script>

// src/types/window.d.ts
export {};

declare global {
  interface Window {
    __INITIAL_STATE__: {
      user: { id: string; name: string } | null;
    };
  }
}

// src/hydrate.ts
const state = window.__INITIAL_STATE__;
if (state.user) {
  console.log(`Welcome back, ${state.user.name}`);
}

Output: (none — exits 0 on success)

Typing an untyped npm package#

You depend on legacy-color which doesn’t ship types. The error: Could not find a declaration file for module 'legacy-color'. Author a minimal shim.

// src/types/legacy-color.d.ts
declare module 'legacy-color' {
  export type RGB = [number, number, number];

  export function parse(input: string): RGB;
  export function format(rgb: RGB): string;
  export function darken(rgb: RGB, amount: number): RGB;
  export function lighten(rgb: RGB, amount: number): RGB;

  const DEFAULT_PALETTE: Record<string, RGB>;
  export default DEFAULT_PALETTE;
}

import palette, { parse, darken, type RGB } from 'legacy-color';

const accent: RGB = parse('#8a5cff');
const accentDark = darken(accent, 0.2);
console.log(palette.brand);

Output: (none — exits 0 on success)

Typing process.env#

Without help, process.env.API_URL is string | undefined. Augment NodeJS.ProcessEnv to make required variables string.

// src/types/env.d.ts
declare global {
  namespace NodeJS {
    interface ProcessEnv {
      readonly NODE_ENV: 'development' | 'production' | 'test';
      readonly API_URL: string;
      readonly DATABASE_URL: string;
      readonly STRIPE_KEY?: string;   // optional ones keep ?
    }
  }
}

export {};

const dbUrl = process.env.DATABASE_URL;   // typed: string (not undefined)
const stripe = process.env.STRIPE_KEY;    // typed: string | undefined

Output: (none — exits 0 on success)

[!WARNING] This is type-only — TS doesn’t enforce that the variable is actually set at runtime. Pair the declaration with a runtime check (Zod, envalid) at startup.

Typing Vite’s import.meta.env#

Vite injects import.meta.env with build-time variables. The default type is Record<string, string> — augment it for known variables.

// src/vite-env.d.ts
/// <reference types="vite/client" />

interface ImportMetaEnv {
  readonly VITE_API_URL: string;
  readonly VITE_SENTRY_DSN: string;
  readonly VITE_FEATURE_NEW_NAV: string;   // env vars are always strings
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}

const apiUrl = import.meta.env.VITE_API_URL;
const flag = import.meta.env.VITE_FEATURE_NEW_NAV === 'true';

Output: (none — exits 0 on success)

Shimming a CSS-in-JS library’s theme#

styled-components has its own DefaultTheme interface, intentionally empty so consumers can augment it.

// src/types/styled.d.ts
import 'styled-components';
import type { theme } from '../theme';

declare module 'styled-components' {
  export interface DefaultTheme {
    colors: typeof theme.colors;
    spacing: typeof theme.spacing;
    fonts: typeof theme.fonts;
  }
}

// src/components/Button.tsx
import styled from 'styled-components';

export const Button = styled.button`
  color: ${(props) => props.theme.colors.accent};
  padding: ${(props) => props.theme.spacing.md};
`;

Output: (none — exits 0 on success)

Authoring a .d.ts alongside a published JS library#

If you ship a JavaScript library on npm, generate a .d.ts from your .ts sources with tsc --declaration.

// tsconfig.build.json
{
  "compilerOptions": {
    "declaration": true,
    "declarationMap": true,
    "emitDeclarationOnly": false,
    "outDir": "dist",
    "rootDir": "src"
  },
  "include": ["src"]
}

tsc -p tsconfig.build.json
ls dist/

Output:

index.d.ts
index.d.ts.map
index.js
index.js.map
util.d.ts
util.d.ts.map
util.js
util.js.map

Wire it up via package.json so consumers pick up the types automatically:

{
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js"
    }
  }
}

Generating types from a JSON Schema#

Some APIs publish a JSON Schema or OpenAPI document. Convert it to a .d.ts so your client code is typed end-to-end.

npx openapi-typescript https://api.example.com/openapi.json -o src/types/api.d.ts

Output:

🚀 https://api.example.com/openapi.json → src/types/api.d.ts (412ms)

// src/api-client.ts
import type { paths } from './types/api';

type GetUserResponse = paths['/users/{id}']['get']['responses']['200']['content']['application/json'];

export async function getUser(id: string): Promise<GetUserResponse> {
  const res = await fetch(`/api/users/${id}`);
  return res.json();
}

Output: (none — exits 0 on success)