Youch: Pretty Print JavaScript Errors

4.1.1 · active · verified Sun Apr 19

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.

Common errors

```
TypeError: Youch is not a constructor
```
cause 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.
```
cause 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')
```
cause 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)`.

Warnings

breaking Youch 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.
breaking The 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'`.
breaking The `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)`.
gotcha Versions 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.
gotcha Dependencies 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`.

Install

npm install youch npm
yarn add youch yarn
pnpm add youch pnpm

Imports

Youch
wrong:
```
import Youch from 'youch'
```
correct:
```
import { Youch } from 'youch'
```
Since v4.1.0, `Youch` is a named export. Previous major versions used a default export.
Youch (CommonJS)
wrong:
```
const Youch = require('youch')
```
correct:
```
const { Youch } = await import('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
wrong:
```
const youch = new Youch(error, request); const html = await youch.toHTML();
```
correct:
```
const youch = new Youch(); const html = await youch.toHTML(error, request);
```
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.

Quickstart

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.');
});

view raw JSON →