Skip to main content

Recipes

Task-shaped how-tos. Pattern: Goal → Steps → Verify → Pitfalls.

1. Gate CI on nudo check​

Goal: Fail the pipeline when contracts or entry throws break.

# .github/workflows/nudo.yml
jobs:
nudo:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
- run: npm i -g nudojs
- run: npx nudojs check src/

Verify: npx nudojs check src/ exits 0 on a clean tree; 1 on L1/L2 errors.

Pitfalls: --ignore-throws only filters L2. Prefer fixing contracts over muting L1. Full flags: check · CLI reference.

2. Gradual contracts on an existing package​

Goal: Observation → draft → handwritten sidecar → CI.

npx nudojs check src/ # signatures + L2
npx nudojs contract --draft src/lib.js
npx nudojs contract --draft --write src/lib.js --fn importantFn
# review lib.nudo.draft.js → copy into lib.nudo.js
npx nudojs check src/lib.js

Pitfalls: drafts are not ambient-loaded; handwritten wins over @generated. Guide: contract · migrating-js.

3. Monorepo: scope analysis next to tsserver​

{
"nudo": {
"analysis": {
"mode": "exports",
"include": ["packages/js-lib/src/**"],
"exclude": ["**/*.test.ts", "packages/ts-lib/**"]
}
}
}

JS packages → Nudo LSP + nudo check. TS packages → tsc. Details: coexistence.

4. Export types for TS consumers​

npx nudojs export src/api.js --format dts --out dist/types
npx nudojs export src/api.js --format schema --dialect zod --out dist/schema

Projections are lossy; Abs + nudo check remain the truth. Guide: export.

5. Mock boundaries + env​

/// @nudo:env node
// @nudo:mock fetch = (url) => ({ ok: true, json: () => ({ id: 1 }) })

Package-shaped APIs from @types are auto-filled at analysis time. Env is not a mock substitute. See Dependency types · Limits.

6. Teaching an AI agent this repo​

Paste block for coding agents:

Read https://nudojs.github.io/nudo/docs/reference/agents
Then: npx nudojs check src/
Contracts are *.nudo.js / @nudo:contract. Do not invent body-AST obligations.
@nudo:case is debug-only.

More: Agents · Agent integration · API · agent.

7. IDE inlay + CodeLens​

Install nudo-vscode (or Zed extension). Default analysis mode "exports". See VS Code · LSP clients.

8. Read check output quickly​

signatures
getName(user: any) => any throws TypeError
subtract(a: any, b: any) => number throws TypeError
issues
[ERROR L1 getName] getName (export): may throw TypeError (nudo:entry-may-throw)
[ERROR L5 subtract] subtract (export): may throw TypeError (nudo:entry-may-throw)

any = unconstrained entry. throws = L2 domain. L1 in the header is the line number (getName is declared on line 1 here) — the layer is L2. Codes: Diagnostics · full transcript walkthrough: nudo check.


Next​