Motherload is a comprehensive set of TypeScript loaders designed to simplify the integration of various data formats directly into TypeScript projects. By leveraging TypeScript's content mappers—a feature introduced in TypeScript 7.1—Motherload allows developers to import external data files as fully typed modules. This process creates a seamless bridge between data files and the static type system, ensuring that imports are validated during the build process and providing intellisense support within supported code editors. It is maintained by Colin McDonnell and supports a wide array of formats including TOML, YAML, JSONC, JSON5, CSV, TSV, Markdown, plain text, and environment files.

The core functionality of Motherload revolves around its role as a content mapper for the TypeScript compiler. When a project imports a supported data file, Motherload acts as an intermediary, parsing the file content and returning the corresponding module types to the compiler. This mechanism works natively with the TypeScript workflow, allowing for accurate type checking of imported data structures without requiring manual type definitions or runtime parsing logic. At runtime, the library provides plugins and integration paths for major JavaScript environments, bundlers, and frameworks including Node.js, Bun, Vite, Next.js, esbuild, webpack, and Rspack, ensuring that the data is correctly loaded and available in the production build.

Some of the key features are:

• Full Static Typing: Automatically generates type definitions for imported data files based on their content.
• Wide Format Support: Handles TOML, YAML, JSONC, JSON5, CSV, TSV, Markdown, plain text, and .env files.
• Native Integration: Integrates directly with the TypeScript compiler (tsc) using content mappers.
• Editor Support: Provides real-time validation and intellisense within VS Code, Cursor, and Zed.
• Runtime Plugins: Offers official support for Node.js, Bun, Vite, Next.js, and other popular bundling tools.
• Error Reporting: Reports parsing errors directly in the TypeScript compiler output with precise line and column information.
• Markdown Integration: Supports importing Markdown files with frontmatter, allowing access to both the body text and metadata.
• Environment Variables: Dynamically maps .env file keys to process.env with type checking for variable existence.

The operation of the tool involves installing the Motherload package as a dependency and configuring the project's tsconfig.json file to register the content mappers for the desired file extensions. Developers must also set up a type-checking script that invokes the compiler with the --runExternalCode flag to enable the mapper. Depending on the environment, appropriate plugins are installed to handle the transformation of these data files during runtime or bundling processes. Once configured, developers can simply import their data files using standard ES module import statements, and Motherload handles the rest, ensuring that the data is treated as typed objects throughout the project lifecycle.

Some common use cases include:

• Configuration Management: Loading structured configuration data from TOML or YAML files while ensuring strict type safety for application settings.
• Localization Files: Managing translation strings in JSONC or JSON5 files, enabling developers to use autocompletion for translation keys.
• Data Seed Imports: Loading CSV or TSV data sets into applications for testing or data visualization with guaranteed column structures.
• Content Management: Using Markdown files for blog posts or documentation, where frontmatter serves as typed metadata for the application.
• Environment Configuration: Loading sensitive environment variables from .env files with compile-time checks to prevent missing configuration errors.