nostics

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.

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