motherload README

项目的 README,来自 github.com/colinhacks/motherload。合并为一个 markdown 文件:README.md。


Motherload

Import data files into TypeScript, fully typed
by @colinhacks


stars


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 [email protected]). 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:

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:

// tsconfig.json
{
  "compilerOptions": { /* ... */ },
  "contentMappers": [
    {
      "package": "motherload",
      "extensions": [
        ".toml", ".yaml", ".yml", ".jsonc", ".json5", ".env",
        ".csv", ".tsv", ".txt", ".md"
      ]
    }
  ]
}
// package.json
{
  "scripts": {
    "typecheck": "tsc --noEmit --runExternalCode"
  }
}

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)
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:

// .vscode/settings.json
{
  "js/ts.experimental.useTsgo": true,
  "js/ts.tsdk.path": "./node_modules/typescript"
}

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"
import config from "./config.toml";
// config: {
//   readonly name: "demo";
//   readonly port: 8080;
//   readonly server: { readonly host: "localhost" };
// }

.yaml

Motherload reads .yaml and .yml files:

- name: Ada
  role: admin
- name: Grace
  role: member
import team from "./team.yaml";
// team: readonly [
//   { readonly name: "Ada"; readonly role: "admin" },
//   { readonly name: "Grace"; readonly role: "member" },
// ]

A file of several documents, separated by ---, is the list of them:

kind: Service
---
kind: Deployment
replicas: 2
import deploy from "./deploy.yaml";
// deploy: readonly [
//   { readonly kind: "Service" },
//   { readonly kind: "Deployment"; readonly replicas: 2 },
// ]

.jsonc

{
  // the editor's font size
  "fontSize": 14,
  "exclude": ["dist",],
}
import settings from "./settings.jsonc";
// settings: {
//   readonly fontSize: 14;
//   readonly exclude: readonly ["dist"];
// }

.json5

{
  // shown on the sign-in page
  welcome: 'Welcome back',
  retries: 3,
}
import strings from "./strings.json5";
// strings: { readonly welcome: "Welcome back"; readonly retries: 3 }

[!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 a string:

DATABASE_URL=postgres://localhost/app
PORT=3000
import "./.env";

process.env.DATABASE_URL; // string
process.env.PORT;         // string

[!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:

{ "package": "motherload", "extensions": [".env", ".env.local" /* ... */] }

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.

name,email
Ada,[email protected]
Grace,[email protected]
import users from "./users.csv";
// users: readonly {
//   readonly name: string;
//   readonly email: string;
// }[]

.tsv

The same as .csv, with a tab between fields.

player	score
Ada	42
Grace	37
import scores from "./scores.tsv";
// scores: readonly {
//   readonly player: string;
//   readonly score: string;
// }[]

.txt

Notes from the lab.
import notes from "./notes.txt";
// notes: string

.md

Importing a .md file gives its frontmatter, typed from the file, and its Markdown body:

---
title: Hello
draft: false
---
# Hello

The 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 --runExternalCode
users.csv:3:1 - error motherload1: This row has 3 fields; the header has 2.

3 Grace,[email protected],extra
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

motherload (colinhacks/motherload)

正在搜索数据库…

这是什么?Motherload 是一组 TypeScript 加载器,让你可以把 TOML、YAML、JSON5、CSV、TSV、Markdown、纯文本或 .env 等数据文件直接导入到代码中,并得到一个带完整类型的模块,其背后依靠的是 TypeScript 新的内容映射器(content mappers)功能。
这是编译器功能还是需要安装的包?它是一个 npm 包,一方面作为 tsc 的插件(内容映射器),让 TypeScript 类型检查器了解数据的结构;另一方面还提供一个对应的运行时加载器,供实际读取该文件的打包工具或运行环境使用。
怎么把它加到项目里?先用 `npm install motherload` 安装,然后在 tsconfig.json 中用 `--runExternalCode` 注册它需要处理的扩展名,最后为你的技术栈配置对应的运行时加载器(Bun preload、nub preload、Vite/Vitest/Rollup 插件、esbuild 插件、webpack 规则、Next.js 包装器或 Jest transform)。
用这个需要特定版本的 TypeScript 吗?需要。Motherload 要求 TypeScript 7.1 beta 或更高版本(首个支持内容映射器的版本),以及 Node 24+、Bun 或 nub。
只在 tsconfig 里配置,导入就能在运行时生效吗?不能。类型检查和实际的运行时导入是分开配置的:你还需要为你的运行环境或打包工具注册 Motherload 的加载器,否则文件虽然能通过类型检查,但代码真正运行时会加载失败。
Motherload 能导入哪些文件格式?TOML、YAML/YML、JSONC、JSON5、CSV、TSV、纯文本、Markdown(带类型化的 frontmatter),以及 .env 文件。
如果数据文件内容有误会怎样?它会以 TypeScript 类型错误的形式报出,并精确指出出错的行和列,与代码错误的提示方式相同。
我的编辑器能识别这些导入吗?在 VS Code 或 Cursor 中,你需要安装 TypeScript 7 扩展,并将其指向项目使用的 TypeScript 安装路径,然后信任该工作区,使其能够使用内置的编译器;Zed 则需要更多的手动配置。
我能导入 JSON Schema 文件吗?Motherload 本身不能直接导入。对于 .schema.jsonc 或 .schema.json5 文件,README 建议改用配套的 dotschema 包。
它属于哪些主题?dotenv, jest, type-safe, config, webpack, data, csv, parser, build-tool, yaml, bun, vite
大小
1.9 MB
星标
319
时长
1个月
提交 · 90 天