node-boost

node-boost is Boost for the Node ecosystem: a CLI and MCP guidance layer that installs project-specific AI instructions, agent skills, audit rules, and guard hooks. It supports Astro 5–7, Next.js, and Vite React projects.

No telemetry. node-boost reads your local project, writes local files, and does not phone home.

Quick Start

npm i -D @node-boost/node-boost
npx node-boost install

The npm package is published as @node-boost/node-boost; the installed CLI binary is node-boost.

Requirements

node-boost requires Node.js 22.12.0 or newer. Node.js 20 is no longer supported; upgrade the runtime before installing or running the package. CI and release checks cover Node.js 22 and 24.

Content-only extensions publish a versioned node-boost.plugin.json manifest. node-boost resolves and validates that manifest without importing the plugin package entrypoint. The intentionally small @node-boost/node-boost/plugin subpath remains available to plugin authoring tools for validation and TypeScript types; installer, MCP, and audit internals are not exposed.

The installer detects your stack and capabilities, writes node-boost.json, composes .ai/guidelines/** and .ai/skills/**, generates .ai/docs/llms.txt, and configures selected agents:

• Claude Code: CLAUDE.md, .claude/skills/**, .mcp.json, optional .claude/settings.json hooks.
• Codex: AGENTS.md, .agents/skills/**, .codex/config.toml, optional .codex/hooks.json.
• Cursor: .cursor/rules/node-boost.mdc, .cursor/mcp.json, optional .cursor/hooks.json.

CLI

| Command | Purpose | | --- | --- | | node-boost install | Generate guidelines, skills, config, MCP, and optional hook files. | | node-boost update | Regenerate from node-boost.json without prompts. | | node-boost doctor | Check config, generated resources, agent files, hooks, overrides, and TS strictness. | | node-boost audit | Scan source files against enabled architecture rules. | | node-boost guard | Run audit as a hard CI/agent gate; supports --changed, --base, and explicit paths. | | node-boost explain NB-ARCH-005 | Explain a finding and link it back to the generated guideline. | | node-boost mcp | Start the MCP server over stdio. |

Machine-readable commands use --agent:

npx node-boost audit --all --agent
npx node-boost doctor --agent

MCP Tools

| Tool | Purpose | | --- | --- | | application_info | Return detected stack, capabilities, Astro profile, package manager, packages, routes, and node-boost config summary. | | library_docs | Return version-aware official documentation routes and exact package references. | | list_routes | List Next routes or Astro pages, endpoints, dynamic params, partials, and rendering mode. | | list_islands | List Astro client:* and server:defer islands with their source locations. | | architecture_map | Return Astro content collections, Actions, middleware, and advanced routing entrypoints. | | doctor | Run the same full checks as node-boost doctor. | | audit | Run node-boost audit --all and return JSON. | | explain_finding | Explain a rule such as NB-ARCH-005. |

Library Documentation

install and update generate .ai/docs/llms.txt from detected dependency versions. Agents are instructed to prefer its version-matched routes over current-only upstream documentation.

The routing policy is conservative:

• Prefer an official exact- or major-version archive when one is available.
• Otherwise use the exact npm package version as the primary reference and list current upstream docs as secondary.
• Keep an upstream llms.txt as secondary when it describes only the current release.
• When node_modules is unavailable, label versions as inferred from declared ranges. Install dependencies and run node-boost update to pin resolved versions.

Architecture Patterns

| Pattern | What it protects | | --- | --- | | feature-modules | Feature boundaries. Variant public-api allows imports through index.ts; variant forbid blocks all cross-feature imports. | | server-first-components | Next app entries stay server-first; client code moves into child boundaries. | | data-access-layer | Components call data functions or query hooks instead of raw network clients. | | typed-contracts | Env and JSON boundaries are centralized and validated. | | state-management | Client stores hold UI state, not fetched server state. | | custom-hooks | Hooks are extracted only for real reuse, readability, or testability. | | component-composition | UI composition stays explicit and testable. | | styling-tailwind | Tailwind version-specific conventions stay current. | | testing-strategy | Tests target user-visible behavior and high-risk boundaries. | | error-loading-boundaries | Async Next segments have loading/error boundaries. | | secure-by-default | Public env names and HTML injection are checked. | | modern-typescript | Strict TS and no explicit any in source. | | ui-states | Loading, empty, error, disabled, and optimistic states are represented deliberately. | | islands-architecture | Astro hydration stays explicit and server-only code does not enter client islands. | | rendering-strategy | Static-first, server-first, and mixed rendering rules match the detected project. | | content-modeling | Astro content collections and their build or live loaders remain typed and local. | | request-boundaries | Astro endpoints, Actions, middleware, sessions, and caching keep request data isolated. | | multi-framework-boundaries | Projects using multiple Astro UI integrations keep framework ownership explicit. |

Audit And Guard

audit reads enabled architectures from node-boost.json.

npx node-boost audit --all
npx node-boost audit --changed --agent
npx node-boost audit --base origin/main --agent

Suppress a finding only with a reason:

// nb-disable NB-ARCH-005 -- legacy SDK must be wrapped in a follow-up

Suppression without -- reason is reported as NB-META-001.

Astro template findings can use an HTML comment on the finding line or the line above:

<!-- nb-disable NB-ARCH-011 -- trusted CMS output is sanitized upstream -->
<article set:html={trustedHtml} />

Astro support

Astro detection runs before the Vite fallback and builds one capability profile from direct dependencies, statically readable astro.config.*, and src/**. Dynamic configuration is never executed. In that case application_info returns a warning and the detector uses conservative dependency and source fallbacks.

The profile covers Astro 5, 6, and 7, static and server output, mixed prerendering, official deployment adapters, React, Preact, Vue, Svelte, Solid, Lit, MDX, content collections, Actions, middleware, sessions, route cache, i18n, advanced routing, endpoints, and islands. The audit parses .astro templates with @astrojs/compiler and sends only frontmatter to the TypeScript analyzer. It reports high-confidence unsafe set:html, secret-looking public env, server-only imports in hydrated islands, incompatible Astro integrations, missing astro check, and request-dependent cached routes.

Authoring custom Astro integrations, deployment adapters, themes, starters, and renderers is outside this application-support scope.

Declared project profiles

Profiles are optional, user-owned intent. Install with node-boost install --profile=static-content-site --no-interaction, or select a profile interactively. Non-interactive installation without a profile keeps detected defaults. Interactive suggestions require confirmation and never override an explicit choice.

| Profile | Compatible stack | Contract | | --- | --- | --- | | static-content-site | Astro, Next.js static export | Static output. Client interactivity and external APIs are allowed. Server adapters, Actions, server islands, and request-time routes violate the contract. Next must declare output: 'export'. | | server-app | Astro, Next.js | Server request handling is allowed. Static routes and static exports are also allowed. | | spa | Vite React | Browser application with optional external APIs. Own SSR and server endpoints violate the contract. |

Fresh installation derives architecture defaults from the selected profile, including testing-strategy. For an existing project, add profile to node-boost.json and run node-boost update. Update preserves your architecture list, audit settings, and hook selection. Re-running install is not the migration path for existing configuration.

Incompatible profile/stack combinations and static-content-site with a contradictory rendering variant fail validation. Change the profile explicitly when changing the hosting contract. application_info exposes declaredProfile separately from detected rendering and astro facts. Profile contract checks run independently of the enabled architecture list. NB-PROFILE-001 reports violations and NB-PROFILE-002 warns when dynamic configuration prevents verification. Configuration is never executed. doctor treats benign differences as informational and violations as failures.

Test presence

application_info.testTools includes the built-in node:test runner when a supported runtime and a node --test script are detected. nodeTest reports the runtime source, original declaration, runner support and whether native erasable TypeScript is available. Unresolved project declarations such as lts/iron report a null runtime and unknown support instead of using the Node process that runs Boost. Node 22.18 and 23.6 enable stripping by default; Node 22.6 through 22.17 needs --experimental-strip-types. A JavaScript runner capability does not imply native TypeScript support. No test command is generated or assumed.

With testing-strategy enabled, NB-ARCH-015 warns once when neither a recognized tool nor test files are present after exclusions. It checks presence, not coverage percentage. Tests anywhere in the project count, including outside the current changed-file scope. Disable it with audit.rules["NB-ARCH-015"] = "off". Existing configurations without testing-strategy remain opt-in; profiles enable it by default.

Skill copies and shared instructions

By default .ai/skills holds the common source and Codex and Claude Code receive copies in their conventional discovery directories. Cursor reads the common index. The copies are deliberate for agent discovery and portability across Windows and fresh checkouts; Node Boost does not generate skill symlinks.

For exactly one Codex or Claude Code agent, set skillLayout: "single-agent" in node-boost.json and run update. Skills are written only to that agent's directory and instruction pointers follow it. Switching back restores the common copies. The generated manifest removes only unchanged retired files; manual edits become conflicts and remain on disk.

Existing CLAUDE.md symlinks to AGENTS.md are preserved. Node Boost composes one shared managed block for the enabled agents and leaves the surrounding hand-written instructions intact. Install, update, and doctor use the same desired contents. Repeating update leaves content and modification times unchanged.

Bundled upstream skills

node-boost also ships verbatim copies of Vercel's agent skills, so install and update write them alongside the built-in skills without a network call. Each skill is copied with its references, scripts, and a LICENSE.md notice into .ai/skills/<name>/ and mirrored like any other skill.

| Skills | Installed when | | --- | --- | | next-dev-loop, next-cache-components-optimizer, next-cache-components-adoption, next-partial-prefetching-optimizer, next-partial-prefetching-adoption, next-bundle-optimizer (from vercel/next.js) | Next.js 16.3 or newer | | vercel-react-best-practices, vercel-composition-patterns, vercel-react-view-transitions (from vercel-labs/agent-skills) | React is a dependency | | web-design-guidelines | Every supported stack | | vercel-optimize | Next.js and Astro |

Upstream commits are pinned in resources/vendor/skills/sources.json; maintainers refresh them with npm run sync:skills. Sync stages the complete set before replacing the previous one; failed copies leave the previous set intact. A concurrent sync is rejected. If a process is killed, inspect resources/vendor/.skills-sync-* for a backup before removing a leftover resources/vendor/skills.sync-lock. Generated skill directories are excluded from audit and guard. Shadow any file through .node-boost/**, or set features.skills to false to skip skills entirely.

Hooks

When features.hooks is enabled, node-boost wires guard --hook <agent> into each selected agent:

• Claude Code: Stop hook in .claude/settings.json.
• Codex: Stop hook in .codex/hooks.json.
• Cursor: stop hook in .cursor/hooks.json.

Post-tool hooks report findings from edited files without blocking the completed edit:

• Codex: PostToolUse, matched to Write|Edit; canonical apply_patch paths are read from patch headers.
• Claude Code: PostToolUse, matched to Write|Edit; tool_input.file_path selects the file.
• Cursor: postToolUse, matched to Write|Edit; feedback uses additional_context. afterFileEdit has no documented feedback output, so the generic post-tool event is used.

Only existing source files inside the real project root are audited. Global project warnings are not repeated in edit feedback. Shell edits and unsupported tool payloads remain covered by Stop. The Stop hook audits changed files. Error findings block or continue the agent in that agent's native protocol. Disable hooks by setting:

Hook payloads are validated against each agent's documented Stop protocol. Claude Code uses stop_hook_active and Cursor uses loop_count to prevent continuation loops; Codex uses continue and stopReason. The payload working directory selects the audited project only after absolute-directory validation.

By default, enabling features.hooks wires hooks for every configured agent. Set hookAgents to a subset such as ["codex"] to enable blocking hooks only for those agents; an explicit empty list enables none.

Protocol references: Codex hooks, Claude Code hooks, and Cursor hooks.

{
  "features": {
    "hooks": false
  }
}

Then run:

npx node-boost update

Configuration

node-boost.json is the source of truth:

{
  "$schema": "./.ai/node-boost.schema.json",
  "version": 1,
  "generatedWith": "0.4.0",
  "stack": "next",
  "agents": ["claude-code", "codex", "cursor"],
  "plugins": ["@acme/node-boost-plugin"],
  "features": {
    "guidelines": true,
    "skills": true,
    "mcp": true,
    "architecture": true,
    "hooks": false
  },
  "architectures": [
    { "name": "feature-modules", "boundary": "public-api" },
    "server-first-components",
    "data-access-layer",
    { "name": "@acme/node-boost-plugin:service-layer", "variant": "strict" }
  ],
  "audit": {
    "exclude": [],
    "rules": {
      "NB-ARCH-007": "off",
      "NB-ARCH-002": "warn"
    },
    "ruleOptions": {
      "NB-ARCH-005": {
        "dataLayerGlobs": ["**/api/**", "src/orval/**"]
      }
    }
  }
}

Project overrides live under .node-boost/** and shadow built-in resources during install and update.

After npm accepts a publication, registry metadata can take several minutes to appear. npm run release:readback waits up to ten minutes for the expected name, version, integrity and provenance, with each lookup limited to fifteen seconds. It fails if the metadata stays unavailable or incomplete; a readback failure does not mean publication should be repeated.

Run the Verify existing npm release workflow from the branch containing the fix to check the version in that branch's package.json without publishing again. For this fix that version is 0.7.0. Re-running the original publish workflow still checks out the old release tag and must not be used to repeat publication.

Release candidates are verified from a clean source checkout with npm run smoke:pack. The smoke builds through prepack, installs the resulting tarball in a temporary consumer, and runs CLI install/doctor from the packed binary.

Content-only plugins

Plugins are installed as ordinary project dependencies and must be listed explicitly in plugins. There is no auto-discovery or remote download. The package must export its static manifest as ./node-boost.plugin.json:

{
  "name": "@acme/node-boost-plugin",
  "version": "1.0.0",
  "exports": {
    "./node-boost.plugin.json": "./node-boost.plugin.json"
  },
  "files": ["node-boost.plugin.json", "resources"]
}

{
  "apiVersion": 1,
  "name": "@acme/node-boost-plugin",
  "architectures": [{
    "slug": "service-layer",
    "title": "Service layer",
    "stacks": ["next", "vite-react"],
    "resources": {
      "guideline": "resources/service-layer/guideline.md",
      "skill": "resources/service-layer/SKILL.md",
      "variants": {
        "strict": { "guideline": "resources/service-layer/strict.md" }
      }
    }
  }]
}

Plugin resource paths are package-relative, cannot traverse outside the package, and are validated before node-boost writes any generated files. Plugins are content-only: executable third-party audit rules are rejected. The plugin entrypoint is never imported; packages using the executable 0.2.0 default-export contract receive a migration error instead.

Interface stability

The CLI commands, their machine-readable reports, and MCP tools are the stable product surface. Since 0.2.0, the package root is intentionally not a JavaScript API. Since 0.3.0, custom architecture extensions use the static manifest contract. Authoring tools may use the dedicated @node-boost/node-boost/plugin subpath, which exposes only content-plugin validation and types. Imports from package internals are unsupported.

CI

Example pull request guard:

name: Node Boost Guard

on:
  pull_request:
  push:
    branches: [main]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/[email protected]
        with:
          fetch-depth: 0
      - uses: actions/[email protected]
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npm run check
      - run: npx node-boost guard --base origin/main

This repository also ships a package CI workflow in .github/workflows/ci.yml.

Git Ignore

Keep implementation planning local unless your team wants to publish it:

implementation-plans/

Generated .ai/**, including .ai/docs/llms.txt, agent files, and node-boost.json are intended to be committed in consumer projects.

Roadmap

• third-party package guidelines beyond the current stacks,
• standalone Angular and Vue application support,
• React Native,
• additional architecture patterns from the v1 backlog.