Loaders

# install the package
npm i -D @nubjs/types @types/node@25

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

Import a config or data file directly.

import config from "./config.yaml";  // parsed object
import flags from "./feature.jsonc"; // parsed object (comments stripped)
import pkg from "./Cargo.toml";      // parsed object
import schema from "./schema.json5"; // parsed object (JSON5 superset)
import prompt from "./prompt.txt";   // string

Extensions

Loaders are keyed on file extension:

• .jsonc — JSON with comments
• .json5 — the JSON5 superset
• .toml
• .yaml / .yml
• .txt — loaded as a string, no parsing

The .json extension is intentionally not in this set — it is Node-native (resolveJsonModule), so Nub leaves it to Node.

Custom extensions

Map an extension of your own onto one of Nub's loaders from a nub.jsonc.

{
  // ...
  "loader": {
    ".config": "jsonc",  // JSON with comments
    ".data": "yaml"
  }
}

The loader names are:

text  jsonc  json5  toml  yaml  ts  tsx  jsx

Any other value stops the command with an error.

Default export

A data module exposes a single default export — the parsed value, exactly like Node's own JSON modules. There are no named exports; destructure the default to pull out top-level keys.

host: localhost
port: 5432

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

The object formats are typed Record<string, unknown>, so destructured keys are unknown — narrow or cast them at the use site. A data file whose top-level value is an array or scalar imports as that value via the default; cast it, since the wildcard type assumes an object.

Import any file as text

Add the with { type: "text" } import attribute to read a file's raw contents as a string, whatever its extension.

import readme from "./README.md" with { type: "text" };  // string
import query from "./query.sql" with { type: "text" };   // string
import raw from "./config.yaml" with { type: "text" };    // the YAML source, unparsed

The attribute wins over parsing: a .yaml or .json file read this way is the raw text, not the parsed value. A text import is a single default export, like the data loaders — there are no named exports.