TypeScript 配置

本页的功能（.toml / .yaml 加载器）需要 Nub 的全局类型声明包，以避免 TypeScript 编译器错误。

# 安装类型包
npm i -D @nubjs/types @types/node@25

# tsconfig.json
{ "compilerOptions": { "types": ["node", "@nubjs/types"] } }

直接导入配置或数据文件。

import config from "./config.yaml";  // 解析后的对象
import flags from "./feature.jsonc"; // 解析后的对象（注释已剥离）
import pkg from "./Cargo.toml";      // 解析后的对象
import schema from "./schema.json5"; // 解析后的对象（JSON5 超集）
import prompt from "./prompt.txt";   // 字符串

扩展名

加载器按键文件扩展名工作：

  • .jsonc — 带注释的 JSON
  • .json5 — JSON5 超集
  • .toml
  • .yaml / .yml
  • .txt — 作为字符串加载，不解析

.json 扩展名故意不在此集合中——它是 Node 原生的（resolveJsonModule），所以 Nub 将它留给 Node。

默认导出

数据模块暴露单个默认导出——解析后的值，与 Node 自身的 JSON 模块完全一样。没有命名导出；解构默认导出来提取顶层键。

# config.yaml
host: localhost
port: 5432
import config from "./config.yaml"; // { host: "localhost", port: 5432 }
const { host, port } = config;      // "localhost", 5432

对象格式的类型为 Record<string, unknown>，所以解构的键是 unknown——在使用处收窄或转换。顶层值为数组或标量的数据文件通过默认导出导入为该值；需要转换，因为通配类型假设是对象。

将任意文件作为文本导入

添加 with { type: "text" } 导入属性以将文件原始内容读取为字符串，无论其扩展名。

import readme from "./README.md" with { type: "text" };  // 字符串
import query from "./query.sql" with { type: "text" };   // 字符串
import raw from "./config.yaml" with { type: "text" };    // YAML 源码，未解析

该属性优先于解析：以这种方式读取的 .yaml 或 .json 文件是原始文本，而非解析后的值。文本导入是单个默认导出，与数据加载器一样——没有命名导出。