Skip to main content

Installation

Install Nudo tools via npm, pnpm, or yarn. Surfaces: the CLI (nudojs), the VS Code extension (nudo-vscode), the Zed extension, and the Vite plugin (vite-plugin-nudo).

Prerequisites​

  • Run the published CLI: Node.js >= 22 (engines on all published packages; Node 20 is EOL)
  • Develop this repo: Node.js >= 22 (CI uses Node 24)

Packages ship compiled ESM in dist/ (files: ["dist"]), not TypeScript source. There is no separate runtime to install — the CLI is plain Node.

CLI​

# global install — provides the `nudo` command
npm install -g nudojs
# or add as a project dependency
npm install nudojs
# or
pnpm add nudojs
# or
yarn add nudojs

Then observe and gate your code:

npx nudojs check path/to/file.js # signatures + contract gate
npx nudojs test path/to/file.js # call-site case reports
# after a global install, the command is simply `nudo`

Primary verbs: check / test / contract / export / health. There is no infer verb — observation is check signatures, test cases, and IDE hover.

Install styleCommand shapeUse when
Global (npm i -g nudojs)nudo check …Day-to-day local work, shell scripts
Project dep (pnpm add nudojs)npx nudojs check …CI, reproducible versions next to the code
One-shot (npx nudojs …)no installTrying Nudo before committing to a dep

npx​

npx nudojs check src/ is the standard CI invocation — it resolves the project-local install when present, and downloads one otherwise. Prefer a project dependency (plus a lockfile) in pipelines so the analyzer version is pinned.

Monorepo / pnpm workspaces​

Install nudojs once in the workspace root, or per package that Nudo should gate. Scope IDE analysis with nudo.analysis.include / exclude so JS packages get Nudo and TS packages stay on tsc:

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

Details: Coexistence with TypeScript · Recipes — monorepo.

VS Code extension​

Install the nudo-vscode extension for inline type hints and diagnostics:

  1. Download nudo-vscode.vsix from the latest GitHub release
  2. In VS Code: Extensions (Ctrl+Shift+X / Cmd+Shift+X) → … menu → Install from VSIX…
  3. Pick the downloaded file
code --install-extension nudo-vscode.vsix

The extension is also published to the VS Code Marketplace and Open VSX (wmzy.nudo-vscode) — if your editor finds it in the extension view, installing from there is equivalent:

code --install-extension wmzy.nudo-vscode # when the listing is reachable

Listings are release artifacts, not a promise: the .vsix on GitHub Releases is the source of truth, and the marketplace tokens can lapse (the release job warns instead of failing). Building from source is always available: pnpm --filter nudo-vscode run build && pnpm --filter nudo-vscode run package.

The vsix is self-contained: it bundles the language server, so you do not need a separate @nudojs/lsp install for the extension to start. Activation is onLanguage:javascript / onLanguage:typescript; whether a buffer is analyzed is the nudo.analysis.mode gate. Full surface: VS Code guide.

Zed​

The nudo Zed extension attaches Nudo's language server to JavaScript and TypeScript buffers as a secondary language server (alongside vtsls). It lives in a standalone repository (nudojs/nudo-zed) and needs @nudojs/lsp ≥ 0.5.0 available project-locally, globally, or via Zed's npm fallback.

Install and settings walkthrough: Zed extension. Other editors: LSP clients.

Vite plugin​

Use vite-plugin-nudo to run Nudo during development or build:

npm install vite-plugin-nudo --save-dev
# or
pnpm add -D vite-plugin-nudo

In vite.config.js:

import { defineConfig } from "vite";
import nudo from "vite-plugin-nudo";

export default defineConfig({
plugins: [nudo()],
});

During the build the plugin analyzes files that pass nudo.analysis.mode (shipped default "exports") and reports Nudo diagnostics — evaluator issues plus refinement-gate violations (nudo:constraint-violated, nudo:assign-mismatch, nudo:arg-structure) — as build warnings, or as errors with failOnError. See the Vite plugin guide.

Verify the install​

Trust boundary

Nudo analyzes by executing the target code (Abs semantics, in-process evaluation). Do not run nudo check / nudo test on untrusted code; in CI this is the same trust as running the project's tests. Why execution is the model: Language semantics.

Smoke-test the CLI on any small JS file:

npx nudojs check path/to/file.js

You should see signatures printed on success and failure — check is not silent. Exit 0 means the gate passed; exit 1 means an error-level diagnostic (L1 contract or L2 entry may-throw). Next, open the same file in VS Code or Zed and hover an export: the inferred signature should match the CLI.

If npx nudojs is missing or fails to resolve, check the Node version (node -v ≥ 20) and that the package name is nudojs (the npm package), while the binary is nudo / nudojs.

Next steps​