Most TypeScript projects fail at the boundary between code and assets. Developers import CSS modules, WASM binaries, or image files, and the compiler stays silent while the build breaks in production. Teams respond by scattering `.d.ts` files across the codebase, each one a maintenance liability that drifts out of sync with the actual asset structure. This approach fails because ambient module declarations force developers to manually replicate type information that already exists elsewhere in the toolchain. ```mermaid flowchart LR Import("import styles from './Button.module.css'") Import --> MissingDef("no matching declaration") MissingDef --> AnyType("implicit any") AnyType --> RuntimeError("runtime error: styles.container undefined") style RuntimeError stroke:#fbbf24,fill:#3a2f0b,color:#fef3c7 ``` TypeScript 6.0's `--allowArbitraryExtensions` flag eliminates this entire class of problems. When enabled, the compiler looks for a `.d.{ext}.ts` file next to any imported file with an unknown extension. This mechanism provides type safety for CSS modules, WASM imports, and static assets without the brittle maintenance burden of global ambient declarations. ```mermaid flowchart LR Import("import styles from './Button.module.css'") Import --> Declaration("Button.module.css.d.ts found") Declaration --> TypedImport("styles typed as Record") TypedImport --> SafeAccess("styles.container autocompletes") style SafeAccess stroke:#34d399,fill:#0b3b2e,color:#d1fae5 ``` ## Key Takeaways - TypeScript 6.0's `--allowArbitraryExtensions` eliminates the need for global ambient module declarations by allowing per-file type definitions for any file extension. - The compiler searches for a `.d.{ext}.ts` declaration file next to the imported asset, providing type safety without modifying tsconfig patterns. - This feature matters for CSS modules, WASM imports, and static assets where build tools handle the actual transformation but TypeScript needs type information. - Migration from ambient declarations to per-file declarations is mechanical and improves type locality without changing runtime behavior. - The tradeoff is file count versus type accuracy: teams gain precise types at the cost of maintaining declaration files alongside assets. ## Understanding `--allowArbitraryExtensions` in TypeScript 6.0 `--allowArbitraryExtensions` changes how the TypeScript compiler resolves imports for files with unknown extensions. Before this flag, importing a `.css` or `.wasm` file required a global ambient module declaration that matched the import path pattern. This created a disconnect: the type information lived in a separate location from the asset itself, making refactoring dangerous and autocomplete unreliable. The flag instructs the compiler to look for a declaration file with the pattern `{filename}.d.{extension}.ts` when it encounters an import ending in an unrecognized extension. For an import like `import styles from './Button.module.css'`, the compiler searches for `Button.module.css.d.ts` in the same directory. If found, that declaration file provides the type for the imported value. ```mermaid flowchart TD Import("import from './file.ext'") Import --> CheckExt{".ext known?"} CheckExt -->|yes| NormalResolution("resolve as JS/TS") CheckExt -->|no, flag off| Error("compilation error") CheckExt -->|no, flag on| SearchDecl("search for file.d.ext.ts") SearchDecl --> Found{declaration found?} Found -->|yes| TypedModule("typed module import") Found -->|no| Fallback("fallback to any") style TypedModule stroke:#34d399,fill:#0b3b2e,color:#d1fae5 style Error stroke:#fbbf24,fill:#3a2f0b,color:#fef3c7 ``` This matters because the declaration file now sits next to the asset, making the type information visible during code review and enforcing locality. When a developer renames `Button.module.css` to `PrimaryButton.module.css`, the corresponding `.d.ts` file must also move or the types break immediately. This coupling prevents the silent staleness that plagued global ambient declarations. The performance implication is negligible. The compiler already performs file system lookups for module resolution. Adding a single additional check for `.d.{ext}.ts` files adds minimal overhead compared to the cost of parsing and type-checking the actual source files. ## Typing CSS Modules Without Declaration Files CSS modules present the canonical use case for `--allowArbitraryExtensions`. Build tools like Webpack and Vite transform CSS files into objects mapping class names to hashed strings, but TypeScript cannot infer these types from the source CSS. Before TypeScript 6.0, developers wrote global ambient declarations: ```typescript // globals.d.ts (the old approach) declare module '*.module.css' { const classes: Record; export default classes; } ``` This declaration applies to every `.module.css` import in the project. The problem surfaces when different CSS modules export different structures. A CSS module using `:export` to expose variables has a different type shape than one exporting only class names. The global declaration cannot represent this distinction. With `--allowArbitraryExtensions`, each CSS module gets its own declaration file: ```typescript // Button.module.css.d.ts declare const styles: { container: string; primary: string; disabled: string; }; export default styles; // Form.module.css.d.ts declare const styles: { fieldset: string; input: string; error: string; submit: string; }; export default styles; ``` Now the consuming code has precise autocomplete and type checking: ```typescript // Button.tsx import styles from './Button.module.css'; function Button({ disabled }: { disabled: boolean }) { // styles.container autocompletes // styles.primry triggers a type error return ( ); } ``` The failure mode here is subtle but expensive. A global declaration lets you reference non-existent class names without error. The bug only appears at runtime when the class name resolves to `undefined` and the styles fail to apply. Per-file declarations catch this during development. Generating these declaration files is straightforward. CSS module tooling already parses the CSS to extract class names. Plugins for Webpack, Vite, and Rollup can emit the `.d.ts` files during the build process. For example, `typescript-plugin-css-modules` generates accurate declarations based on the actual CSS content, keeping types in sync with the source. ## Importing WASM Modules with Type Safety WebAssembly modules expose functions and memory that JavaScript code calls directly. Without type information, these calls rely on runtime documentation and manual validation. A WASM module compiled from Rust might export a `process_image` function expecting a pointer and length, but TypeScript treats it as `any`. `--allowArbitraryExtensions` enables type-safe WASM imports by pairing each `.wasm` file with a declaration: ```typescript // image_processor.d.wasm.ts export interface ImageProcessor { process_image(ptr: number, len: number): number; alloc(size: number): number; dealloc(ptr: number, len: number): void; memory: WebAssembly.Memory; } declare const module: ImageProcessor; export default module; ``` The consuming code now has full type safety: ```typescript // processor.ts import wasmModule from './image_processor.wasm'; async function processImage(imageData: Uint8Array): Promise { const instance = await wasmModule; // Type-safe allocations const ptr = instance.alloc(imageData.length); const view = new Uint8Array(instance.memory.buffer, ptr, imageData.length); view.set(imageData); // Type-safe function call const resultPtr = instance.process_image(ptr, imageData.length); // Cleanup instance.dealloc(ptr, imageData.length); return new Uint8Array(instance.memory.buffer, resultPtr); } ``` This pattern extends to any WASM module. The declaration file acts as a contract between the WASM binary and the TypeScript code. If the WASM module changes its exported interface, the declaration file must update or the type checker catches the mismatch. The distinction is critical: the declaration file does not change how the WASM module loads or executes. Runtime behavior remains identical. The types only prevent incorrect usage patterns that would fail at runtime anyway. For teams using tools like `wasm-pack` or `Emscripten`, these declaration files can be auto-generated from the source language's type system. A Rust crate compiled to WASM can emit TypeScript declarations that match the `#[wasm_bindgen]` exports exactly, ensuring the contract stays synchronized across compilation. ## Handling Static Assets: Images, JSON, and Custom Extensions Static assets like images and JSON files often flow through build pipelines that transform them into importable modules. Webpack's `file-loader` converts an image import into a URL string. Vite handles JSON imports by default. Without type information, these imports lose their structure. For image imports, the declaration file specifies the transformed shape: ```typescript // hero-image.d.png.ts declare const url: string; export default url; // logo.d.svg.ts interface SvgModule { default: string; ReactComponent: React.FC>; } declare const svg: SvgModule; export default svg; ``` This enables type-safe usage across different asset loaders: ```typescript import heroUrl from './hero-image.png'; import logo from './logo.svg'; function Hero() { // heroUrl is typed as string return (

{/* logo.ReactComponent is typed as a React component */}

); } ``` The pattern scales to custom file types. A project using `.graphql` files for query definitions can define their import shape: ```typescript // UserQuery.d.graphql.ts import { DocumentNode } from 'graphql'; declare const query: DocumentNode; export default query; ``` The consuming code now has autocomplete and type safety: ```typescript import userQuery from './UserQuery.graphql'; import { useQuery } from '@apollo/client'; function UserProfile({ id }: { id: string }) { const { data } = useQuery(userQuery, { variables: { id } }); // data is typed based on the GraphQL schema return

{data.user.name}

; } ``` ```mermaid flowchart LR Asset("static asset") Asset --> BuildTool("build tool transforms") BuildTool --> Module("importable module") Module --> DeclFile(".d.{ext}.ts provides types") DeclFile --> TypedImport("typed import in source") TypedImport --> Autocomplete("autocomplete and validation") style Autocomplete stroke:#34d399,fill:#0b3b2e,color:#d1fae5 style DeclFile stroke:#c084fc,fill:#3b0764,color:#f3e8ff,stroke-width:4px ``` The implication here is that type safety extends to the entire asset pipeline. Teams no longer need to choose between type safety and flexible asset handling. The build tool controls the transformation, the declaration file describes the result, and TypeScript enforces correct usage. ## Comparison: `allowArbitraryExtensions` vs Ambient Module Declarations Ambient module declarations solve the same problem with a different tradeoff. A global declaration covers all imports matching a pattern, reducing file count at the cost of precision. `--allowArbitraryExtensions` inverts this: more files, higher precision. ```mermaid flowchart LR subgraph Ambient["Ambient Module Declarations"] GlobalDecl("declare module '*.css'") GlobalDecl --> AllImports("applies to all CSS imports") AllImports --> LowMaintenance("low file count") LowMaintenance --> Imprecise("imprecise types") end subgraph PerFile["Per-File Declarations"] FileDecl("Button.module.css.d.ts") FileDecl --> SingleImport("applies to one import") SingleImport --> HighMaintenance("higher file count") HighMaintenance --> Precise("precise types") end style Imprecise stroke:#fbbf24,fill:#3a2f0b,color:#fef3c7 style Precise stroke:#34d399,fill:#0b3b2e,color:#d1fae5 ``` The failure mode differs. Ambient declarations fail silently when the actual asset structure diverges from the declared type. A CSS module adds a new class, but the global declaration still claims it only exports a `Record`. The type checker cannot warn about the mismatch because it never sees the actual CSS content. Per-file declarations fail loudly when the declaration drifts from the asset. If a CSS module removes a class and the declaration file still exports it, consuming code that references the removed class triggers a type error. This is the desired behavior: early detection of broken contracts. The performance difference is marginal. Both approaches require the compiler to resolve module paths and load declaration files. The cost of loading ten individual `.d.css.ts` files versus one global `globals.d.ts` file is negligible compared to the cost of type-checking the consuming code. Migration from ambient to per-file declarations is mechanical. For each ambient module pattern, generate a declaration file for every matching asset. Tools can automate this: scan the source tree for `.module.css` files, extract their class names, and emit corresponding `.d.ts` files. The transition can happen incrementally, deprecating the global pattern once all assets have individual declarations. The choice depends on team priorities. Projects that value low file count and accept imprecise types continue using ambient declarations. Projects that prioritize type accuracy and can tolerate additional files adopt `--allowArbitraryExtensions`. There is no middle ground: the precision benefit only materializes when declarations become specific to individual assets. ## Migration Patterns: Moving from Manual `.d.ts` Files Migrating from global ambient declarations to per-file declarations requires a systematic approach. The process has three phases: audit, generate, and validate. The audit phase identifies all ambient module declarations in the codebase. Search for `declare module` statements that match file extension patterns. Common patterns include `'*.css'`, `'*.module.css'`, `'*.svg'`, `'*.png'`, `'*.wasm'`. Document which assets each pattern covers and what type it assigns. The generate phase creates individual declaration files for each asset. For CSS modules, this means parsing the CSS to extract class names and generating a typed interface. For images, this means determining whether the build tool returns a URL string or a more complex object. For WASM, this means extracting the exported functions from the binary metadata. ```typescript // Automated generation example import { parse } from 'css'; import { writeFileSync } from 'fs'; function generateCssModuleDeclaration(cssPath: string): void { const css = readFileSync(cssPath, 'utf-8'); const ast = parse(css); const classNames = new Set(); // Extract class names from AST // (implementation omitted for brevity) const declaration = `declare const styles: { ${Array.from(classNames).map(name => ` ${name}: string;`).join('\n')} }; export default styles;`; writeFileSync(`${cssPath}.d.ts`, declaration); } ``` ```mermaid flowchart LR GlobalDecl("global ambient declaration") GlobalDecl --> Audit("audit all covered assets") Audit --> Generate("generate per-file declarations") Generate --> Remove("remove global declaration") Remove --> Validate("validate no type errors") style Validate stroke:#34d399,fill:#0b3b2e,color:#d1fae5 style Generate stroke:#c084fc,fill:#3b0764,color:#f3e8ff,stroke-width:4px ``` The validate phase removes the global ambient declaration and runs the type checker. If the per-file declarations are accurate, the build succeeds without errors. If gaps exist, the type checker reports missing declarations for assets that were previously covered by the global pattern. The implication here is that migration can happen incrementally. A team can generate declarations for high-value assets first, leaving the global pattern in place for less critical imports. Once confidence builds, the global pattern can be removed entirely. The practical constraint is tooling. Without automated generation, maintaining per-file declarations becomes prohibitive. A project with hundreds of CSS modules cannot rely on manual declaration maintenance. The solution is to integrate declaration generation into the build pipeline. The same tools that transform CSS into JavaScript modules can emit TypeScript declarations as a side effect. For teams using Vite, the `vite-plugin-dts` plugin automates this process. For Webpack, `typescript-plugin-css-modules` provides similar functionality. For custom build systems, the pattern is consistent: parse the asset, extract its interface, emit a `.d.{ext}.ts` file. This approach scales to any asset type. The core insight is that the build tool already understands the asset structure. Generating TypeScript declarations is a serialization problem, not a type system problem. The declaration file simply codifies what the build tool already knows. ## Frequently Asked Questions ### Does `--allowArbitraryExtensions` work with all module resolution modes? The flag works with both `node16` and `bundler` resolution modes in TypeScript 6.0. It does not function with legacy `node` resolution because that mode predates the extension-aware resolution logic required for the feature. Teams using older resolution modes must upgrade to benefit from per-file declarations. ### Can I mix ambient declarations and per-file declarations in the same project? Yes, the compiler applies both. Ambient module declarations serve as a fallback when no per-file declaration exists. This enables incremental migration: keep the global pattern for low-priority assets while generating per-file declarations for critical modules. Once all assets have specific declarations, remove the ambient fallback. ### How do I generate declaration files for assets that change frequently? Integrate declaration generation into the build pipeline so the declarations update automatically when assets change. Most build tools support plugins that emit TypeScript declarations as a side effect of processing the asset. For CSS modules, the plugin parses the CSS and generates a `.d.ts` file. For images, the plugin infers the type from the loader configuration. This automation prevents declaration drift. ### What happens if I import an unknown extension without a declaration file? The compiler falls back to `any` if `--allowArbitraryExtensions` is enabled but no matching declaration file exists. This preserves backward compatibility: existing code continues to compile, but loses type safety. To enforce strict typing, enable `noImplicitAny` alongside `--allowArbitraryExtensions` so the compiler reports an error when a declaration is missing. ### Does this feature affect runtime behavior or bundle size? No. The declaration files are compile-time artifacts only. They do not appear in the transpiled JavaScript or the final bundle. The feature only changes how TypeScript validates imports during type checking. Runtime behavior, module loading, and bundle size remain unchanged. ## Conclusion: When to Use This Feature in Production `--allowArbitraryExtensions` eliminates a maintenance burden that teams tolerated for years: the disconnect between asset structure and type information. The feature is production-ready when three conditions hold. First, the project already uses a build tool that transforms non-JS assets into importable modules. Second, the team values precise autocomplete and type checking over minimizing file count. Third, declaration generation can be automated so the type information stays synchronized with the assets. The alternative is to continue using global ambient module declarations and accept their limitations. For small projects or teams that rarely modify asset interfaces, this remains viable. For projects where assets change frequently or where type safety prevents production bugs, the precision of per-file declarations justifies the tooling investment. That covers the essential patterns for typing CSS modules, WASM imports, and static assets in TypeScript 6.0. Apply these in production and the difference will be immediate: fewer runtime errors, better autocomplete, and type information that actually reflects your build pipeline. For deeper exploration of TypeScript's type system, see [10 TypeScript Utility Types for Bulletproof Code](/10-typescript-utility-types-bulletproof-code). Teams working with large-scale refactoring can leverage [AI-Powered TypeScript Refactoring Workflows](/ai-powered-typescript-refactoring-workflows) to automate declaration file generation. For context on managing complex TypeScript projects at scale, [2 Million Token Context Windows for Real Web Apps](/2-million-token-context-windows-real-web-apps) demonstrates the architectural patterns that make type safety feasible.

Posts tagged “Code Agents”

The Claude Code Full Stack: When to Use CLAUDE.md, Skills, MCP, Subagents, and Hooks