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.
npm install -D motherload typescript@beta
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:
Load Motherload when your code runs, so that a data-file import works at run time too. On Node:
node --import motherload/register main.ts
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)
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:
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
name = "demo"port = 8080[server]host = "localhost"
[!NOTE]
Importing a .env file suits a script you run where the file is, such as a seed or a migration on your own machine. An application is often built where the file is not, in CI or on a host, and a missing file fails the build.
A variable the environment already sets keeps its value, and a bundle holds none of the file's values.
A file whose name ends in .env, such as local.env, needs no setup. Imported first, its values win over .env's:
import "./local.env";import "./.env";
Any other name, such as .env.local, goes in extensions in full:
A bundle reads no .env file, since it runs wherever it is deployed. It takes its variables from the environment there, and stops at startup if one the file declares is unset, so on your own machine it runs with the file passed to Node:
node --env-file=.env dist/main.mjs
.csv
The header names the columns, and every value is a string, as written.
Importing a .md file gives its frontmatter, typed from the file, and its Markdown body:
---title: Hellodraft: false---# HelloThe body of the post.
import post from "./post.md";// post: {// readonly md: string;// readonly frontmatter: {// readonly title: "Hello";// readonly draft: false;// };// }
Each part is also a named export, so a bundle that imports the frontmatter alone leaves out the body:
import { frontmatter } from "./post.md";
Errors
Invalid data in a file is a type error, at the line and column of the problem:
$ tsc --noEmit --runExternalCodeusers.csv:3:1 - error motherload1: This row has 3 fields; the header has 2.3 Grace,grace@example.com,extra ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~