externals.d.ts

Overview

The externals.d.ts file is a TypeScript declaration file automatically generated by Umi (a React framework). It provides type declarations for various static asset modules that can be imported in a TypeScript project, such as CSS preprocessors, images, media files, fonts, and other miscellaneous file types.

This file enables TypeScript to understand how to handle imports of non-code assets by defining the shape and types of the modules those imports resolve to. It prevents TypeScript compilation errors when importing assets like .css, .png, .svg, .mp4, .woff2, etc., by declaring their module types and export formats.

Detailed Explanation

Purpose of Declarations

TypeScript, by default, does not understand files with extensions other than .ts or .tsx. To import assets such as stylesheets, images, fonts, and media files without type errors, this file declares modules for these file extensions and defines what is exported when these files are imported.

Type Alias

type CSSModuleClasses = { readonly [key: string]: string };

• Description: Defines the shape of CSS modules imported as objects where each key is a class name (string) and the value is its corresponding generated class name (string).

• Usage: Used for stylesheets modules to provide type safety and IntelliSense for CSS classes.

Module Declarations for Stylesheets

The following file extensions are declared to export a CSSModuleClasses object:

• *.css

• *.scss

• *.sass

• *.less

• *.styl

• *.stylus

Example:

import styles from './button.module.scss';
console.log(styles.primary); // 'button_primary__3fX6k' (example generated class)

Each stylesheet import exports an object mapping class names to their scoped/generated class names as strings.

Module Declarations for Images

File extensions representing images export a string which is the URL/path to the image file after build:

• *.jpg

• *.jpeg

• *.png

• *.gif

• *.ico

• *.webp

• *.avif

Special case for SVGs:

declare module '*.svg' {
  import * as React from 'react';
  export const ReactComponent: React.FunctionComponent<
    React.SVGProps<SVGSVGElement> & { title?: string }
  >;

  const src: string;
  export default src;
}

• SVG imports provide two exports:

  • ReactComponent: A React functional component to render the SVG inline with optional props.

  • Default export: The SVG file path as a string.

Example usage:

import Logo, { ReactComponent as LogoIcon } from './logo.svg';

<img src={Logo} alt="Logo" />
<LogoIcon title="Company Logo" />

Module Declarations for Media Files

These extensions export a string representing the media file path:

• Video: .mp4, .webm, *.ogg

• Audio: .mp3, .wav, .flac, .aac

Example:

import sound from './alert.mp3';
const audio = new Audio(sound);
audio.play();

Module Declarations for Fonts

Fonts also export a string path:

• *.woff

• *.woff2

• *.eot

• *.ttf

• *.otf

Other File Types

• WebAssembly (.wasm):

declare module '*.wasm' {
  const initWasm: (
    options: WebAssembly.Imports,
  ) => Promise<WebAssembly.Exports>;
  export default initWasm;
}

• Instead of exporting a URL string, .wasm files export a function initWasm which accepts WebAssembly imports and returns a promise resolving to WebAssembly exports.

• Manifest (.webmanifest), PDF (.pdf), Text (.txt):

Exports are strings representing file paths.

Important Implementation Details

• The file is auto-generated by Umi's build system and should not be modified manually.

• It leverages TypeScript’s module declaration syntax (declare module) to extend the module system.

• The declarations enable seamless integration of static assets in a typed React + TypeScript environment.

• The SVG declaration uniquely integrates React by exporting both a React component and a file path.

• For .wasm files, the declaration reflects asynchronous loading and instantiation patterns typical for WebAssembly modules.

Interaction with the System / Application

• Role in the build process: When importing assets in a TypeScript codebase, these declarations inform the compiler how to type-check the imports.

• Integration with bundlers: Tools like Webpack or Vite handle actual loading and bundling of these assets. This file ensures TypeScript compatibility.

• Umi framework: Umi automatically generates this file to keep asset type declarations in sync with the framework configuration and plugins.

Usage Examples

Importing a CSS Module:

import styles from './App.module.css';

function App() {
  return <div className={styles.container}>Hello</div>;
}

Importing an Image:

import logo from './logo.png';

const img = <img src={logo} alt="Logo" />;

Importing an SVG as React Component:

import { ReactComponent as Icon } from './icon.svg';

function Button() {
  return <Icon title="Button icon" />;
}

Importing a WebAssembly file:

import initWasm from './module.wasm';

async function loadWasm() {
  const wasmExports = await initWasm({});
  // use wasmExports...
}

Mermaid Diagram

flowchart TD
    A[externals.d.ts] -->|declares| B[CSSModuleClasses]
    A -->|declares modules| C[Stylesheets: .css, .scss, .sass, .less, .styl, .stylus]
    A -->|declares modules| D[Images: .jpg, .jpeg, .png, .gif, .ico, .webp, .avif]
    D -->|special case| D1[.svg exports ReactComponent + src string]
    A -->|declares modules| E[Media: .mp4, .webm, .ogg, .mp3, .wav, .flac, .aac]
    A -->|declares modules| F[Fonts: .woff, .woff2, .eot, .ttf, .otf]
    A -->|declares module| G[.wasm exports initWasm function]
    A -->|declares modules| H[Other: .webmanifest, .pdf, .txt]

Summary

externals.d.ts is a critical support file in TypeScript React projects using Umi, defining how static assets are typed when imported. It covers stylesheets, images, media, fonts, and other files, thereby enabling smooth integration of these resources in the typed environment without manual type declarations. The file's auto-generated nature ensures it stays consistent with the evolving asset handling setup in the project.