Youch

Pretty print JavaScript errors on the Web and the Terminal

<br />

[![gh-workflow-image]][gh-workflow-url] [![npm-image]][npm-url] ![][typescript-image] [![license-image]][license-url] [![Downloads Stats][npm-downloads-image]][npm-url]

Featured sponsors

Used by

Table of Contents

What is Youch?
Usage
- Render error to HTML output
- Render error to ANSI output
Anatomy of the error page
Using a custom source code loader
Injecting custom styles
Overriding syntax highlighter
Configuring code editors
- How do you detect the user's code editor?
Contributing
Code of Conduct
License

What is Youch?

Youch is an error-parsing library that pretty prints JavaScript errors on a web page or the terminal.

As you can see in the following screenshots, the error presented by Youch is a lot more readable and presentable in comparison to the unformatted stack trace.

<table> <tbody> <tr> <td> <strong>Unformatted stack trace</strong> </td> </tr> <tr> <td> <img src="./assets/raw-stack-trace.png" /> </td> </tr> <tr> <td> <strong>Youch output</strong> </td> </tr> <tr> <td> <img src="./assets/youch-output.jpg" /> </td> </tr> </tbody> <table>

Usage

Install the package from the npm packages registry as follows.

npm i youch@beta

# Yarn
yarn add youch@beta

# Pnpm
pnpm add youch@beta

Render error to HTML output

You can render errors to HTML output using the youch.toHTML method. The HTML output is self-contained and does not require separate CSS or JavaScript files.

In the following example, we use the hono framework and pretty print all the errors in development using Youch. You can replace Hono with any other framework of your choice.

import { Hono } from 'hono'
import { Youch } from 'youch'

const app = new Hono()
const IN_DEV = process.env.NODE_ENV === 'development'

app.onError(async (error, c) => {
  if (IN_DEV) {
    const youch = new Youch()
    const html = await youch.toHTML(error)
    return c.html(html)
  }
  return c.text(error.message)
})

The youch.toHTML method accepts the error as the first argument and the following options as the second argument.

await youch.toHTML(error, {
  title: 'An error occurred',
  cspNonce: '',
  offset: 0,
  ide: 'vscode',
})

| Option | Description | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | title | Define the title for the error page. It defaults to "An error has occurred" | | cspNonce | If your application is using CSP protection, then you must provide the CSP-nonce for rendering inline style and script tags. | | offset | The offset can be used to skip displaying certain frames from the parsed error stack. | | ide | The ide option defines the code editor for opening the files when the filename anchor tag is clicked. Learn more about configuring code editors |

Render error to ANSI output

You can render an error to ANSI output (for terminal) using the youch.toANSI method.

try {
  await performSomeAction()
} catch (error) {
  const youch = new Youch()
  const ansiOutput = await youch.toANSI(error)

  console.error(ansiOutput)
}

The youch.toANSI method accepts the error as the first argument and the following options as the second argument.

await youch.toANSI(error, {
  offset: 0,
})

| Option | Description | | -------- | ------------------------------------------------------------------------------------- | | offset | The offset can be used to skip displaying certain frames from the parsed error stack. |

Anatomy of the error page

Let's deconstruct the error page and understand what each section of the output represents.

Error info

The top-most section displays the Error info, which includes:

The Error class constructor name.
The Error title. It is set using the options.title property.
And the Error message (highlighted in red).

<details> <summary><strong>View HTML output</strong></summary>

</details>

Stack trace

The Stack trace section displays individual frames as accordion sections. Clicking on the section title reveals the frame source code. The source code is unavailable for native stack frames that are part of the Node.js, Deno, and Bun internals.

<details> <summary><strong>View HTML output</strong></summary>

</details>

For the ANSI output, only the first frame from the application code is expanded to show the source code.

<details> <summary><strong>View ANSI output</strong></summary>

</details>

Raw output

Clicking the Raw button displays the Error object in its raw form, with all the error properties (not just the stack trace).

The raw output may be helpful for errors that contain additional properties. HTTP client libraries like Axios, Got, Undici, and others usually contain the HTTP response details within the error object.

<details> <summary><strong>View HTML output</strong></summary>

</details>

In case of ANSI output, you can view the raw output using the YOUCH_RAW environment variable. For example: YOUCH_RAW=true node your-script.js.

<details> <summary><strong>View ANSI output</strong></summary>

</details>

Error cause

Error cause is a standard way to bubble errors while wrapping them within a generic error. Youch displays the error cause as an interactive property within its own section.

<details> <summary><strong>View HTML output</strong></summary>

</details>

For the ANSI output, the nested properties are shown upto the two levels deep. However, you can adjust the depth using the YOUCH_CAUSE environment variable. For example: YOUCH_CAUSE=4 node your-script.js.

<details> <summary><strong>View ANSI output</strong></summary>

</details>

Metadata (HTML only)

Metadata refers to any additional data that you want to display on the error page. It could be the HTTP request headers, the logged-in user info, or the list of available application routes.

Metadata is structured as groups and sections. Each section contains an array of rows, and each row is composed of a key-value pair.

In the following example, we display the request headers under the Request group and the Headers section.

const youch = new Youch()

youch.group('Request', {
  headers: [
    {
      key: 'cookie',
      value: req.headers.cookie,
    },
    {
      key: 'host',
      value: req.headers.host,
    },
  ],
})

Calling the youch.group method multiple times with the same group name will merge the new sections with existing sections.

Using a custom source code loader

Youch reads the source code of files within the stack trace using the Node.js fs module. However, you can override this default and provide a custom source loader using the `youch.sourceLoade

Youch

Install / Use

README

Youch

What is Youch?

Usage

Render error to HTML output

Render error to ANSI output

Anatomy of the error page

Error info

Stack trace

Raw output

Error cause

Metadata (HTML only)

Using a custom source code loader