colinhacks / motherload

Motherload 
 Import data files into TypeScript, fully typed
 by @colinhacks 
Motherload is a set of TypeScript loaders for data formats: import a TOML, YAML, JSONC, JSON5, CSV, TSV, Markdown, text or `.env` file and get a typed module.
It's powered by TypeScript's _content mappers_ (introduced typescript@7.1). These are like plugins for TypeScript, and it lets Motherload provide _full static types_ for the imported data, in a way that natively integrates with `tsc`.
## Setup
Motherload needs:
- **TypeScript 7.1 beta or later**, the first release with content mappers.
- **Node 24 or later, Bun or nub.**
 [code] 
An app that runs under the preload, not as a bundle, loads its data files at run time, so it installs Motherload as a dependency: `npm install motherload`.
Name Motherload in `tsconfig.json`, with the extensions it should own, and type-check with `--runExternalCode`, the flag that lets `tsc` run content mappers:
 [code] 
 [code] 
Load Motherload when your code runs, so that a data-file import works at run time too. On Node:
 [code] 
| Runtime or bundler | Setup |
| --- | --- |
| Bun | `preload = ["motherload/register"]` in `bunfig.toml` |
| nub | `"preload": ["motherload/register"]` in `nub.jsonc` |
| Vite, Vitest, Rollup, Rolldown | `import motherload from "motherload/vite"`, then `motherload()` in `plugins` |
| esbuild, `Bun.build` | `import motherload from "motherload/esbuild"`, then `motherload()` in `plugins` |
| webpack, Rspack | `use: "motherload/webpack"` in a rule for the data files, in `module.rules` |
| Next.js | `import { withMotherload } from "motherload/next"`, then `export default withMotherload(nextConfig)`: the loader for Turbopack and webpack, and the type check inside `next build` (setup) |
| Jest | `"motherload/jest"` in `transform`, for the data files (setup) |
Each setup has a working example project to copy: examples.
In VS Code or Cursor, install the **TypeScript 7** extension (`TypeScriptTeam.native-preview`) and point it at your project's TypeScript, since the extension bundles TypeScript 7.0:
 [code] 
Then trust the workspace, and click **Allow** when the extension asks to use the workspace's TypeScript. Zed takes a few more settings: see Editors.
The `motherload` package provides one unified content mapper for all data formats. You can also consume them à la carte.
## Loaders
Each file is parsed when the module is built, so a bundle holds the data and no parser. The default export is the data, typed as `as const` would type it.
### `.toml`
 [code] 
 [code] 
### `.yaml`
Motherload reads `.yaml` and `.yml` files:
 [code] 
 [code] 
A file of several documents, separated by `---`, is the list of them:
 [code] 
 [code] 
### `.jsonc`
 [code] 
 [code] 
### `.json5`
 [code] 
 [code] 
> [!NOTE]
> To import a JSON Schema file, `.schema.jsonc` or `.schema.json5`, as its type and a validator, use dotschema.
### `.env`
Importing a `.env` file sets its variables on `process.env` when the module runs, and types each of them as