youch

library4.1.1jsnpmunverified

Youch is an error-parsing library designed to transform raw JavaScript error stack traces into highly readable and visually appealing output. It can render these errors into self-contained HTML pages for web contexts or formatted ANSI output for terminal environments. The current stable version is 4.1.1, with frequent updates, including beta releases for new features and bug fixes. A key differentiator is its ability to provide detailed error information, including code snippets, request/response metadata, and configurable links to code editors, significantly enhancing the developer experience compared to standard unformatted stack traces. It is widely adopted by frameworks like Hono, Nuxt, and AdonisJS, emphasizing its utility in modern web development workflows.

observability web-framework testing

npm install youch

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · YOUCH

youch

observabilityjavascriptv4.1.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Youch

✓ import { Youch } from 'youch'

✗ import Youch from 'youch'

Since v4.1.0, `Youch` is a named export. Previous major versions used a default export.

Youch (CommonJS)

✓ const { Youch } = await import('youch')

✗ const Youch = require('youch')

CommonJS `require()` is not directly supported for Youch v4.1.0 and later due to the switch to ESM. Dynamic `import()` or transpilation is required for CommonJS environments.

toHTML, toJSON, toANSI methods

✓ const youch = new Youch(); const html = await youch.toHTML(error, request);

✗ const youch = new Youch(error, request); const html = await youch.toHTML();

Since v4.1.0, the `error` and `request` objects are passed directly to the `toHTML`, `toJSON`, and `toANSI` methods, rather than to the `Youch` constructor.

Demonstrates how to integrate Youch into a Node.js HTTP server to catch errors and render them as a rich, self-contained HTML error page.

import { Youch } from 'youch'; import http from 'node:http'; const server = http.createServer(async (req, res) => { try { if (req.url === '/error') { throw new Error('This is a simulated error for Youch to display!'); } res.writeHead(200, { 'Content-Type': 'text/plain' }); res.end('Visit /error to see Youch in action.'); } catch (error) { const youch = new Youch(); // The request object is optional, but provides valuable context. const html = await youch.toHTML(error, req); res.writeHead(500, { 'Content-Type': 'text/html' }); res.end(html); } }); const PORT = process.env.PORT ?? 3000; server.listen(PORT, () => { console.log(`Server running on http://localhost:${PORT}`); console.log('Open http://localhost:3000/error in your browser to trigger an error.'); });

Debug

Known issues

breakingYouch switched from CommonJS to ES Modules (ESM) starting with v4.1.0. Direct `require()` statements for Youch will no longer work in a CommonJS context.

fix

Migrate your project to use ES Modules (`import`/`export`) or use dynamic `import()` for Youch if you must remain in a CommonJS environment.

affects: >=4.1.0

breakingThe primary export for Youch changed from a default export to a named export in v4.1.0. Importing Youch via `import Youch from 'youch'` will result in a `TypeError`.

fix

Update your import statements to use named import syntax: `import { Youch } from 'youch'`.

affects: >=4.1.0

breakingThe `Youch` constructor no longer accepts the `error` or `request` objects. These parameters are now passed directly to the `toHTML()`, `toJSON()`, and `toANSI()` methods.

fix

Instantiate `Youch` without arguments: `const youch = new Youch()`. Then, pass the `error` and `request` context when calling a rendering method, e.g., `await youch.toHTML(error, request)`.

affects: >=4.1.0

gotchaVersions of Youch prior to v4.1.0 (specifically before v4.1.0-beta.14) did not properly escape HTML in error content, potentially leading to Cross-Site Scripting (XSS) vulnerabilities if error messages contained untrusted user input.

fix

Upgrade to Youch v4.1.0 or later to ensure proper HTML escaping. If using an older version, manually sanitize any potentially untrusted input before it is incorporated into error messages.

affects: <4.1.0

gotchaDependencies like `@poppinss/colors` and `cookie-es` are crucial for Youch's functionality. In some environments (e.g., Yarn PnP), these might need to be explicitly declared or correctly resolved for Youch to work as expected.

fix

If encountering issues related to missing modules, ensure these dependencies are properly installed and linked, potentially by adding them explicitly to your `package.json`.

affects: >=4.1.0-beta.8

Errors

Common errors & fixes

TypeError: Youch is not a constructor

Attempting to instantiate Youch with `new Youch()` after an `import Youch from 'youch'` statement on Youch v4.1.0 or later.

fix

Change the import statement to `import { Youch } from 'youch'` to use the named export.

ERR_REQUIRE_ESM: require() of ES Module .../node_modules/youch/dist/index.js from ... not supported.

Attempting to load Youch v4.1.0 or later using a CommonJS `require()` call in a CommonJS module.

fix

Refactor your module to use ES Modules, or if absolutely necessary, use a dynamic import: `const { Youch } = await import('youch')` in an `async` context. Otherwise, downgrade Youch to a version prior to 4.1.0.

TypeError: Cannot read properties of undefined (reading 'constructor')

Calling `youch.toHTML()` without passing the `error` and `request` objects as arguments after instantiating `Youch` in v4.1.0 or later.

fix

Ensure `error` and `request` (or `null` for `request` if not applicable) are passed as arguments to the rendering methods: `await youch.toHTML(error, request)`.

Upgrade

Version history

4.1.1latest on npm

Audit

Dependencies

@poppinss/colorsrequiredUsed for generating colored ANSI terminal output for errors, essential for the `toANSI()` method.

cookie-esrequiredDependency for parsing and displaying request cookies within the metadata section of the HTML error page.

Agent activity

51 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/poppinss/youch ↗

packagehttps://www.npmjs.com/package/youch ↗

homepagehttps://youch.dev ↗