Skip to content

Tag as latest after a stable beta being tested for more than a year

Choose a tag to compare

View all tags
@github-actions github-actions released this 24 Feb 15:30
· 7 commits to 4.x since this release
v4.1.0
4ea3505

4.1.0 (2026-02-24)

Breaking Changes

  • Switch from CommonJS to ESM. The package can no longer be require()'d.
  • Switch from a default export to named exports. 
    - import Youch from 'youch'
+ import { Youch } from 'youch'
  • The Youch constructor no longer accepts the error or request object. Instead, the error is passed directly to toHTML(), toJSON(), and the new toANSI() methods. 
    - const youch = new Youch(error, req)
- const html = await youch.toHTML()
- const json = await youch.toJSON()
+ const youch = new Youch()
+ const html = await youch.toHTML(error)
+ const json = await youch.toJSON(error)
  • The HTTP request is no longer passed to the constructor. Pass it as an option to toHTML() instead. The request must be a plain object with url, method, and headers properties (not a Node.js http.IncomingMessage). 
    - const youch = new Youch(error, req)
- const html = await youch.toHTML()
+ const youch = new Youch()
+ const html = await youch.toHTML(error, {
+   request: {
+     url: req.url,
+     method: req.method,
+     headers: req.headers,
+   },
+ })
  • The toJSON() return value is now a ParsedError object directly, instead of being wrapped inside { error: {...} }. 
    - const { error } = await youch.toJSON()
- console.log(error.message)
+ const error = await youch.toJSON(error)
+ console.log(error.message)
  • The toHTML() method no longer accepts arbitrary template data. Use the structured options object instead, which accepts title, cspNonce, ide, request, offset, and frameSourceBuffer. 
    - await youch.toHTML({ cspNonce: 'abc123' })
+ await youch.toHTML(error, { cspNonce: 'abc123' })
  • The preLines and postLines constructor options have been replaced by frameSourceBuffer on each render method. 
    - const youch = new Youch(error, req, { preLines: 8, postLines: 8 })
- const html = await youch.toHTML()
+ const youch = new Youch()
+ const html = await youch.toHTML(error, { frameSourceBuffer: 8 })
  • Remove the addLink() method. Custom links can no longer be added to the error page. Use the new template/component system to customize the HTML output instead.
  • Remove the toggleShowAllFrames() method. Frame visibility is now handled by the new HTML UI.

Features

  • Add toANSI() method for rendering errors as ANSI-colored terminal output. 
    const youch = new Youch()
const output = await youch.toANSI(error)
console.log(output)
  • Add structured Metadata API for attaching contextual information to error pages. Metadata is organized into groups, sections, and rows. 
    const youch = new Youch()
youch.metadata.group('Request', {
  Headers: [
    { key: 'Host', value: 'localhost:3000' },
    { key: 'Accept', value: 'text/html' },
  ],
  Cookies: [
    { key: 'session_id', value: 'abc123' },
  ],
})
  • Add useParser() for pre-processing errors before they are parsed. 
    youch.useParser((source) => {
  // Normalize or transform the error before parsing
  return source
})
  • Add useTransformer() for post-processing parsed errors. 
    youch.useTransformer((error, source) => {
  // Mutate the ParsedError after parsing
  error.hint = 'Did you forget to install dependencies?'
})
  • Add defineSourceLoader() for custom source code loading (e.g., remote files, bundled sources). 
    youch.defineSourceLoader(async (frame) => {
  const contents = await fetchSource(frame.fileName)
  return { contents }
})
  • Add pluggable template/component system. Every section of the HTML output (header, layout, errorInfo, errorStack, errorStackSource, errorCause, errorMetadata) can be replaced with a custom component. 
    youch.templates.use('errorInfo', new MyCustomErrorInfo())
  • Add IDE integration. Clicking file paths in the HTML output opens them in your editor. Configurable via the ide option ("vscode", "sublime", "phpstorm", etc.) or a custom URL format. 
    await youch.toHTML(error, { ide: 'vscode' })
  • Add templates.injectStyles() for injecting custom CSS into the error page. 
    youch.templates.injectStyles(':root { --surface-bg: #1a1a2e; }')
  • Add dark mode support with automatic theme toggle in the HTML output.
  • Export BaseComponent class for building custom template components.
  • Export Metadata class for standalone use.

What's Changed

New Contributors

Full Changelog: v2.0.10...v4.1.0

Contributors

peterp, yorch, and 14 other contributors
Assets 2
Loading