The Node loader

The Nola loader runs .tsi files in Node without a separate build step. Use it during development or when debugging. nola run registers the loader for you.

Usage

node --import nola-lang/register src/main.ts     # a plain-TS entry that imports .tsi
node --import nola-lang/register src/main.tsi    # or a .tsi entry directly
nola run src/main.ts                             # the same, registered for the entry's directory

What the loader does

• Registers Node module hooks (module.register) for the project and compiles imported .tsi files in memory.
• Inlines source maps that point at the on-disk .tsi files, so breakpoints bind in .tsi source and, with --enable-source-maps, stack traces report .tsi positions.
• Loads nola.config.ts before your entry point runs. The config is bundled and evaluated before the module hooks register, so it cannot import .tsi files (NOLA3012).
• Reads the .env beside nola.config.ts before evaluating the config. Existing environment variables take precedence. Without a config file, the loader does not read .env.
• Resolves ./x.js to x.ts when the .js file is missing. An existing .js file takes precedence. This supports the NodeNext .js imports used in .tsi files.
• Serves views of TypeScript modules when a ./x.tsi import has no matching .tsi file on disk. This lets cross-file schemas work without generated files, including imports emitted by the compiler. See Types as values.

Debugging

You can debug a .tsi or .ts entry point with Node’s debugger. The VS Code launch configuration in Editor setup runs node --import nola-lang/register --enable-source-maps. It also tells VS Code to use the inline source maps and skip runtime code while stepping.

Not for production

For deployment, prefer nola build. It writes JavaScript with the configuration included, so you can run the output with node without registering the loader. See Deploying for the build workflow and the option to run source directly.

Runtimes

The loader requires Node ≥ 22.18 and uses Node’s module hooks. Running it in Bun or Deno (bun --bun, bun src/main.ts, or deno run) fails with NOLA3015. You can still use those tools as package managers: bun run start, pnpm start, and yarn start launch the nola executable under Node.

Nola handles .tsi files. Node handles plain .ts files, including entry points and helpers, through native type stripping. This is enabled by default from Node 22.18 and 23.6.

On earlier Node 22 releases, npm start or F5 may fail with ERR_UNKNOWN_FILE_EXTENSION for src/main.ts. The scaffolder warns about this. Upgrade Node when possible. As a workaround, set NODE_OPTIONS=--experimental-strip-types for npm start and add "--experimental-strip-types" to runtimeArgs in .vscode/launch.json.

Using Node’s type stripping keeps plain TypeScript files subject to the same syntax rules inside and outside a Nola project.

Next: VS Code extension