Getting started

1. Create a project

npm

npm create nola

pnpm

pnpm create nola

yarn

yarn create nola

bun

bun create nola

The scaffolder asks for a name and a template — starter (typed extraction that runs offline against a mock provider), empty (just nola.config.ts and tsconfig.json), or one of the curated examples. Non-interactive: npm create nola my-app -- --template extract-resume.

Already have a project? npm create nola -- --add (or nola init --add) writes nola.config.ts and adds the packages to your existing package.json. Pick VS Code at the prompt (or pass --ide vscode) to get a launch.json for F5 debugging and a recommendation for the Nola extension.

2. Configure a provider

nola.config.ts lives at the project root. providers.default is required; every other key becomes an ask with <name> target.

nola.config.ts

import { openai } from "@nola-lang/providers";
import { defineConfig } from "@nola-lang/runtime";

export default defineConfig({
  providers: {
    // Reads OPENAI_API_KEY from the environment at the first ask.
    default: openai({ model: "gpt-5-mini" }),
  },
});

defineConfig comes from @nola-lang/runtime; everything provider-shaped comes from @nola-lang/providers. Those two specifiers are the whole import surface.

3. Write an infer function

src/person.tsi

export interface Person { name: string; age: number; employer: string }

export infer function extractPerson(.message: string) {
  return ask ..`the person described in the text`<Person>;
}

• .message is a context parameter — its value is shown to the model.
• ask ..`…`<Person> asks the model for a Person and resolves it. Raw intents are always resolved with ask, never a bare await (that throws NOLA3010); the return value of an infer function may be awaited.
• Imports of .tsi files keep the extension (./person.tsi); imports of plain TS use NodeNext style (./types.js).

4. Run it

src/main.ts

import { extractPerson } from "./person.tsi";

const person = await extractPerson("Alice Smith, 32, is a staff engineer at Acme Corp.");
console.log(person);

node --import nola-lang/register src/main.ts   # the loader lowers .tsi in memory
nola check                                     # type-check, positions mapped back to .tsi
nola build                                     # emit .js + .map (+ adjacent .d.tsi.ts) for deployment

nola run <entry> is a shortcut for the loader invocation. Scaffolded projects wire npm start to it.

Next steps

• Browse the examples — ten runnable projects.
• Install the VS Code extension for highlighting, diagnostics and go-to-definition in .tsi.
• Source and issues on GitHub; packages on npm.