nostics

Errors worth reading.

nostics helps you replace ad hoc error strings with stable diagnostic codes, actionable fixes, source locations, and docs links.

[NUXT_B2011] Plugin `./runtime/analytics.server.ts` is server-only but was registered with mode `client`.
├▶ fix: Rename the file or register it with mode `server`.
├▶ sources: modules/analytics.ts:18:5
╰▶ see: https://nuxt.com/e/b2011

Install

pnpm add nostics

Quick start

import { createConsoleReporter, defineDiagnostics } from 'nostics'

export const diagnostics = defineDiagnostics({
  docsBase: (code) => `https://nuxt.com/e/${code.replace('NUXT_', '').toLowerCase()}`,
  reporters: [createConsoleReporter()],
  codes: {
    NUXT_B2011: {
      why: (p: { src: string; mode: 'client' | 'server' }) => {
        const expected = p.mode === 'client' ? 'server' : 'client'
        return `Plugin "${p.src}" is ${expected}-only but was registered with mode "${p.mode}".`
      },
      fix: (p: { mode: 'client' | 'server' }) => {
        const expected = p.mode === 'client' ? 'server' : 'client'
        return `Rename the file or register it with mode "${expected}".`
      },
    },
    NUXT_B5001: {
      why: (p: { value: string; configPath: string }) =>
        `Invalid compatibilityDate "${p.value}" in ${p.configPath}.`,
      fix: (p: { example: string }) => `Use an ISO date like "${p.example}", or "latest".`,
    },
  },
})

Use the generated handles where the problem happens:

const plugin = resolvePlugin()
const source = locatePluginCall(plugin)
const config = loadNuxtConfig()

diagnostics.NUXT_B2011({
  src: plugin.src,
  mode: plugin.mode,
  sources: [source],
})

throw diagnostics.NUXT_B5001({
  configPath: config.filepath,
  value: config.compatibilityDate,
  example: '2024-04-03',
})

Calling a handle reports the diagnostic and returns a Diagnostic. Throwing the return value raises it. The params are inferred from your why and fix functions.

Claude Code plugin

Install the plugin to give Claude skills for your diagnostic catalog:

claude plugin add https://github.com/vercel-labs/nostics

Claude will automatically pick up the nostics API reference and an add-diagnostic skill that finds the right catalog, chooses the next free code, and wires the call site.

Agent skills

Prefer just the skills, without the plugin? Install them with npx skills into any supported agent (Claude Code, Codex, Cursor, opencode, and more):

npx skills add vercel-labs/nostics

Why use it

• Stable codes that users can search and docs can link to.
• Typed params at the call site.
• Diagnostic instances that extend Error.
• Built-in console, file, fetch, and Vite dev reporters.
• Plain, ANSI, and JSON formatters.
• A build plugin that strips report-only diagnostics from production bundles.

The structured shape also makes diagnostics easier for tools and coding agents to read, without making that the main workflow.

Vite plugins

Build-time plugins live in the separate @nostics/unplugin package:

pnpm add -D @nostics/unplugin

For library builds, use the strip plugin:

import { nosticsStrip } from '@nostics/unplugin/strip-transform'

export default defineConfig({
  plugins: [nosticsStrip.vite()],
})

For browser diagnostics during Vite dev, use createDevReporter() in the browser and nosticsCollector in the consuming app:

import { nosticsCollector } from '@nostics/unplugin/dev-server-collector'

export default defineConfig({
  plugins: [nosticsCollector.vite()],
})

Docs

See the docs site for the guide, production build notes, dev collector setup, and API reference.

License

MIT