nostics

nostics is a library designed for library authors to replace ad hoc error strings with structured, actionable error reporting. It allows you to use stable error codes (e.g., NUXT_B2011), provide actionable fixes, link to documentation, and include source locations within a Diagnostic object.

Key capabilities include:

• Stable codes: Permanent identifiers for known problems that remain constant even if the wording changes.
• Actionable fixes: Integrated instructions on how to resolve the error.
• Typed params: Using functions to ensure dynamic error messages and fixes are type-safe via TypeScript.
• Reporters: Support for logging to the console, appending NDJSON to files, POSTing to endpoints, or implementing custom reporters.
• Production stripping: A build plugin to remove report-only diagnostics and their catalog text from production bundles.
• Vite dev collection: Ability to forward browser diagnostics to a local log file during Vite development.

In nostics, a Reporter is responsible for sending a diagnostic to a destination (like the console, a file, or an HTTP endpoint), while a Formatter is responsible for turning a Diagnostic object into a string representation.

Crucial Note: A diagnostic will not be visible anywhere (including the console) unless a reporter is configured. If you call a diagnostic code like diagnostics.NUXT_B2011() without any reporters in your defineDiagnostics configuration, it will simply return a Diagnostic object and do nothing else. To surface it, you must either:

1. Add a reporter to your defineDiagnostics configuration.
2. Manually throw the returned diagnostic object.

import { createConsoleReporter, defineDiagnostics } from 'nostics'

export const diagnostics = defineDiagnostics({
  reporters: [createConsoleReporter()], // Without this, diagnostics are silent
  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}".`
      },
    },
  },
})

The docsBase option in defineDiagnostics controls how documentation links are generated for your codes. You have three ways to configure it:

1. Function: Provides full control. The function receives the code as an argument. This is useful for complex URL patterns (e.g., stripping prefixes or changing case).
2. String: If the URL structure is regular, providing a string will append the lowercased code to the end of the base URL.
3. Code-level override: You can override the global docsBase by setting a docs property directly on a specific code. Set docs: false to omit the link entirely for that code.

Note: If docsBase is a string, the code is appended as base/code_name.

defineDiagnostics({
  docsBase: 'https://example.com/errors',
  codes: {
    NUXT_B2011: { why: 'Plugin mode conflict.' }, // URL: https://example.com/errors/nuxt_b2011
    NUXT_I001: {
      why: 'Default config.',
      docs: 'https://example.com/guide',
    }, // URL: https://example.com/guide
    NUXT_X999: {
      why: 'No docs.',
      docs: false,
    }, // No URL
  },
})

Code Naming

Use the pattern PREFIX_XNNNN. The letter represents the area, not severity:

• B: Build
• R: Runtime
• C: Config
• D: Deprecation

Message Composition

Split original warnings: Do not copy a full warning string into why. Instead, put the diagnosis in why and the remedy in fix. If the remedy requires data, make fix a parameter function.

Example of splitting a warning:

• Bad: { why: (p) => "A hash should start with '#'. Replace ${p.hash} with #${p.hash}.", fix: "Prefix with #" } (Redundant)
• Good: { why: (p) => "A hash should start with "#" but received "${p.hash}".", fix: (p) => "Prepend "#": use "#${p.hash}"" }

Parameters

• cause (the original error) and sources (array of 'file:line:column' strings) must be passed inside the first argument (the params object).
• The second argument is for reporter options (e.g., { method: 'error' }).