Add Nola to an existing project

Run Nola’s setup command in your existing TypeScript project to add the packages and configuration for .tsi files.

Run the retrofit

npm create nola -- --add

A bare interactive npm create nola also offers Add Nola to this project when it finds a package.json in the current directory. Use --add for an existing project or --template for a new one; they cannot be combined. If nola-lang is already installed, nola init --add runs the same setup.

The setup includes editor files, a coding-agent skill and a provider choice:

• Editor files: .vscode/launch.json enables F5 debugging and .vscode/extensions.json recommends the Nola extension. Use --ide none to skip them. See Editor setup.
• Coding-agent skill: setup writes .agents/skills/nola/ and links .claude/skills/nola to it for Claude Code. Use --agents none to skip it, or --agents claude,universal,agents-md to also embed the skill in AGENTS.md. You can install it later with nola skill install and refresh it after an upgrade with nola skill install --force.
• Provider: choose interactively or pass --provider nola|openai|anthropic|google|typesafe|none. --trial and --no-trial are shortcuts for nola and none.

Choosing Nola requests a key for 25 free hosted runs, saves NOLA_API_KEY in .env and adds .env and .env.* to .gitignore. Existing .env entries are preserved. If this machine already has a trial key, the browser opens for sign-in and the new key belongs to your Nola account.

Choosing a vendor writes a config for that provider; add its key to .env yourself. The typesafe.ai option supports only literal unions and booleans. If nola.config.ts already exists, setup keeps it and prints the model setting you can apply manually.

What it writes, merges, and leaves alone

	Files	Detail
Written if absent	nola.config.ts	Uses model: "nola" for Nola or the chosen vendor factory. With none, it writes an OpenAI config with a commented mockProvider alternative.
Merged	package.json	Adds @nola-lang/runtime and @nola-lang/providers to dependencies, and nola-lang and typescript to devDependencies. The Nola packages use matching versions. Existing entries are preserved; the file changes only if a package was added.
Written by default	.vscode/ settings, Nola agent skill	Adds the editor and agent setup described above. Existing VS Code settings files are skipped.
Updated for a Nola key	.env, .gitignore	Adds the key and environment-file ignore rules. Existing key entries are preserved.
Suggested	package.json scripts, tsconfig.json	Prints install instructions, an optional "start": "nola run src/main.ts" script and the tsconfig settings below. These files are not changed for you.

Then run your package manager’s install.

tsconfig requirements

tsconfig.json

{
  "compilerOptions": {
    "strict": true,
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "allowArbitraryExtensions": true,
    "noEmit": true,
    "skipLibCheck": true
  },
  "include": ["src"]
}

Three settings matter for Nola:

• module / moduleResolution: NodeNext — in this Node setup, plain TypeScript imports use ./x.js even when the source file is x.ts. Imports of .tsi files keep the .tsi extension.
• allowArbitraryExtensions: true — required so TypeScript accepts the declaration pairs Nola emits for .tsi modules.
• Directory-style include — use ["src"] so the editor can include .tsi files. A glob such as ["src/**/*.ts"] excludes them and prevents auto-import from finding your infer functions.

First .tsi file

src/hello.tsi

export infer function summarize(.text: string) {
  return ask `a one-sentence summary`: string;
}

src/main.ts

import { summarize } from "./hello.tsi";

console.log(await summarize("Nola is a TypeScript superset where asking an LLM is part of the language."));

npx nola-lang run src/main.ts    # run with the loader and nola.config.ts applied
npx nola-lang check              # type-check .tsi and .ts together

Existing build pipelines

Use nola check to type-check .tsi source and nola build to compile it. Plain tsc cannot parse the added syntax.

If a framework build or tsc --noEmit needs to resolve .tsi imports, enable allowArbitraryExtensions and run nola declarations. It writes adjacent <name>.d.tsi.ts files for TypeScript to read. Add *.d.tsi.ts to .gitignore; the editor hides these declarations beside the source, and nola check ignores them.

For a bundled application, use the matching Nola plugin: @nola-lang/vite, @nola-lang/webpack, @nola-lang/rollup, @nola-lang/rolldown, @nola-lang/esbuild, @nola-lang/rspack or @nola-lang/next. It handles lowering during the build. See The nola CLI.

Next: Editor setup