\n \n Daniel Bannert's open source work is supported by the community on GitHub Sponsors\n \n
\n
\n\n---\n\n| Light Mode | Dark Mode |\n| -------------------------------- | ------------------------------ |\n|  |  |\n\n## Install\n\n```sh\npnpm add @visulima/ono\n```\n\n```sh\nnpm i @visulima/ono\n```\n\n```sh\nyarn add @visulima/ono\n```\n\n## Features\n\n- Pretty, theme‑aware error page\n - Sticky header (shows error name/message while scrolling)\n - One‑click copy for error title (icon feedback)\n- Stack trace viewer\n - Shiki‑powered syntax highlighting (singleton highlighter)\n - Tabs for frames; grouping for internal/node_modules/application frames\n - Tooltips and labels to guide usage\n - Optional \"Open in editor\" button per frame\n- Error causes viewer (nested causes, each with its own viewer)\n- Solutions panel\n - Default open; smooth expand/collapse without layout jump\n - Animated height/opacity; icon toggles open/close\n - Built-in rule-based Markdown hints for common issues (ESM/CJS interop, export mismatch, port in use, missing files/case, TS path mapping, DNS/connection, React hydration mismatch, undefined property access)\n - Custom solution finders support\n- Raw stack trace panel\n- Theme toggle (auto/dark/light) with persistence\n- **Copy to Clipboard** - One-click copying for all data sections\n- **Responsive Design** - Sticky sidebar navigation with smooth scrolling\n- Consistent tooltips (one global script; components only output HTML)\n\n**New in latest version:**\n\n- **Tabbed Interface** - Switch between Stack and Context views\n- **Request Context Panel** - Detailed HTTP request debugging information\n - cURL command with proper formatting and copy functionality\n - Headers, cookies, body, and session data\n - App routing, client info, Git status, and version details\n - Smart data sanitization and masking for sensitive information\n - **Flexible Context API** - Add any custom context data via `createRequestContextPage()`\n- **Modern Ono Class API** - Simple, consistent interface for both HTML and ANSI rendering\n- **Solution Finders** - Extensible system for custom error solutions\n\nAccessibility and keyboard UX\n\n- ARIA-correct tabs and panels for stack frames; improved labeling\n- Focus trap within the overlay; restores focus on close\n- Keyboard shortcuts help dialog (press Shift+/ or “?” button)\n- Buttons/controls are keyboard-activatable (Enter/Space)\n\nEditor integration\n\n- Editor selector is always visible; selection persists (localStorage)\n- Uses server endpoint when configured; otherwise opens via editor URL scheme (defaults to VS Code)\n\n### Using the Ono class (recommended)\n\nThe new Ono class provides a simple, consistent API for both HTML and ANSI error rendering:\n\n```ts\nimport { Ono } from \"@visulima/ono\";\n\nconst ono = new Ono();\n\n// HTML error page\nconst html = await ono.toHTML(error, {\n cspNonce: \"your-nonce\",\n theme: \"dark\",\n solutionFinders: [\n /* custom finders */\n ],\n});\n\n// ANSI terminal output\nconst { errorAnsi, solutionBox } = await ono.toANSI(error, {\n solutionFinders: [\n /* custom finders */\n ],\n});\n```\n\n### Node.js HTTP Server Example\n\n```ts\nimport { createServer } from \"node:http\";\nimport { Ono } from \"@visulima/ono\";\nimport createRequestContextPage from \"@visulima/ono/page/context\";\nimport { createNodeHttpHandler } from \"@visulima/ono/server/open-in-editor\";\n\nconst ono = new Ono();\nconst openInEditorHandler = createNodeHttpHandler();\n\nconst server = createServer(async (request, response) => {\n const url = new URL(request.url || \"/\", `http://localhost:3000`);\n\n // Open-in-editor endpoint\n if (url.pathname === \"/__open-in-editor\") {\n return openInEditorHandler(request, response);\n }\n\n try {\n // Your app logic here\n throw new Error(\"Something went wrong!\");\n } catch (error) {\n // Create context page with request information\n const contextPage = await createRequestContextPage(request, {\n context: {\n request: {\n method: request.method,\n url: request.url,\n headers: request.headers,\n },\n user: {\n client: {\n ip: request.socket?.remoteAddress,\n userAgent: request.headers[\"user-agent\"],\n },\n },\n },\n });\n\n // Generate HTML error page\n const html = await ono.toHTML(error, {\n content: [contextPage],\n openInEditorUrl: \"__open-in-editor\",\n cspNonce: \"nonce-\" + Date.now(),\n theme: \"auto\",\n });\n\n response.writeHead(500, {\n \"Content-Type\": \"text/html\",\n \"Content-Length\": Buffer.byteLength(html, \"utf8\"),\n });\n response.end(html);\n }\n});\n\nserver.listen(3000);\n```\n\n### Hono Framework Example\n\n```ts\nimport { serve } from \"@hono/node-server\";\nimport { Hono } from \"hono\";\nimport { Ono } from \"@visulima/ono\";\nimport createRequestContextPage from \"@visulima/ono/page/context\";\n\nconst app = new Hono();\nconst ono = new Ono();\n\napp.get(\"/\", (c) => c.text(\"OK\"));\n\napp.get(\"/error\", () => {\n throw new Error(\"Boom from Hono\");\n});\n\napp.onError(async (err, c) => {\n const contextPage = await createRequestContextPage(c.req.raw, {\n context: {\n request: {\n method: c.req.method,\n url: c.req.url,\n headers: Object.fromEntries(c.req.raw.headers.entries()),\n },\n },\n });\n\n const html = await ono.toHTML(err, {\n content: [contextPage],\n cspNonce: \"hono-nonce-\" + Date.now(),\n theme: \"dark\",\n });\n\n return c.html(html, 500);\n});\n\nserve({ fetch: app.fetch, port: 3000 });\n```\n\n## API\n\n### Ono Class\n\nThe main API for rendering errors in both HTML and ANSI formats.\n\n#### Constructor\n\n```ts\nconst ono = new Ono();\n```\n\n#### Methods\n\n##### `toHTML(error, options?)` => `Promise`\n\nRenders an error as an HTML page.\n\n- **error**: `unknown` - The error to render\n- **options**: `TemplateOptions` (optional)\n - `content?: ContentPage[]` - Additional pages to display as tabs\n - `cspNonce?: string` - CSP nonce for inline scripts/styles\n - `editor?: Editors` - Default editor for \"Open in editor\" functionality\n - `openInEditorUrl?: string` - Server endpoint for opening files in editor\n - `solutionFinders?: SolutionFinder[]` - Custom solution finders\n - `theme?: 'dark' | 'light' | 'auto'` - Theme preference\n\nReturns the complete HTML string for the error page.\n\n##### `toANSI(error, options?)` => `Promise<{ errorAnsi: string; solutionBox?: string }>`\n\nRenders an error as ANSI terminal output.\n\n- **error**: `unknown` - The error to render\n- **options**: `CliOptions` (optional)\n - `solutionFinders?: SolutionFinder[]` - Custom solution finders\n - All other options from `@visulima/error` renderError options\n\nReturns an object with `errorAnsi` (the formatted error) and optional `solutionBox` (suggested solutions).\n\n##### `toJSON(error, options?)` => `Promise`\n\nRenders an error as a structured, JSON-serializable payload — the error name/message, the parsed\nstack frames for the error and every entry in its `cause` chain, the detected runtime, and a\nsuggested solution (using the same solution-finder protocol as `toHTML`/`toANSI`). Useful for\nSPA/REST error responses when the client sends `Accept: application/json`.\n\n- **error**: `unknown` - The error to render\n- **options**: `ToJsonOptions` (optional)\n - `solutionFinders?: SolutionFinder[]` - Custom solution finders\n\n```ts\nimport { renderJson } from \"@visulima/ono\";\n\napp.use((error, request, response, next) => {\n if (request.accepts(\"json\")) {\n renderJson(error).then((payload) => response.status(500).json(payload));\n\n return;\n }\n\n next(error);\n});\n```\n\n#### Standalone renderers\n\nThe same three renderers are also exported as standalone, tree-shakeable functions — prefer these\nover instantiating `Ono`:\n\n```ts\nimport { renderAnsi, renderHtml, renderJson } from \"@visulima/ono\";\n\nconst html = await renderHtml(error);\nconst { errorAnsi } = await renderAnsi(error);\nconst json = await renderJson(error);\n```\n\n### createRequestContextPage(request, options) => `Promise`\n\nCreates a context page with detailed request debugging information.\n\n- **request**: `Request` - The HTTP request object\n- **options**: `ContextContentOptions`\n - `context?: Record` - Additional context data\n - `headerAllowlist?: string[]` - Headers to include (default: all)\n - `headerDenylist?: string[]` - Headers to exclude\n - `maskValue?: string` - Mask for sensitive values (default: \"[masked]\")\n\n### createNodeHttpHandler(options) => `(req, res) => void`\n\nCreates an HTTP handler for opening files in editors.\n\n- **options**: `OpenInEditorOptions` (optional)\n - `projectRoot?: string` - Project root directory\n - `allowOutsideProject?: boolean` - Allow opening files outside project\n\nReturns an Express/Node.js compatible request handler.\n\n### CLI Example\n\n```ts\nimport { Ono } from \"@visulima/ono\";\n\nconst ono = new Ono();\n\ntry {\n throw new Error(\"Something went wrong!\");\n} catch (error) {\n // Basic ANSI output\n const result = await ono.toANSI(error);\n console.log(result.errorAnsi);\n\n if (result.solutionBox) {\n console.log(\"\\n\" + result.solutionBox);\n }\n\n // With custom solution finder\n const resultWithCustom = await ono.toANSI(error, {\n solutionFinders: [\n {\n name: \"custom-finder\",\n priority: 100,\n handle: async (err, context) => ({\n header: \"Custom Solution\",\n body: \"Try checking your configuration.\",\n }),\n },\n ],\n });\n}\n```\n\n### Request Context Panel\n\nUse `createRequestContextPage()` to create a \"Context\" tab with comprehensive debugging information:\n\n- **Request Overview** - cURL command with proper formatting and copy functionality\n- **Headers** - HTTP headers with smart masking for sensitive data (authorization, cookies, API keys, tokens, secrets)\n- **Body** - Request body content with sensitive-looking keys (password, token, secret, …) masked in both the rendered body and the copyable cURL\n- **Session** - Session data in organized key-value tables\n- **Cookies** - Cookie values are masked by default (the `cookie` header is treated as sensitive); pass an empty `maskValue` to disable\n- **Dynamic Context Sections** - Any additional context keys you provide are automatically rendered as sections with:\n - Proper titles (capitalized)\n - Copy buttons for JSON data\n - Organized key-value tables\n - Sticky sidebar navigation\n\n**Built-in sections** (when data is provided):\n\n- `app` - Application routing details (route, params, query)\n- `user` - Client information (IP, User-Agent, geo)\n- `git` - Repository status (branch, commit, tag, dirty state)\n- `versions` - Package versions and dependencies\n\n**Custom sections** - Add any context data you want:\n\n- `database` - Database connection info, queries, etc.\n- `cache` - Cache status and keys\n- `environment` - Environment variables\n- `performance` - Performance metrics\n- And more!\n\n**Deep Object & Array Support** - The context panel intelligently renders:\n\n- Nested objects with proper indentation and visual hierarchy\n- Arrays with indexed items and collapsible structure\n- Complex data types (strings, numbers, booleans, null, undefined)\n- Performance-optimized rendering with depth limits (max 3 levels)\n- Smart truncation for large datasets (shows first 10 items/keys)\n\nAll sections include copy buttons for easy data extraction and debugging.\n\n### Custom Solution Finders\n\nCreate custom solution finders to provide specific guidance for your application's errors:\n\n```ts\nimport { Ono } from \"@visulima/ono\";\n\nconst customFinder = {\n name: \"my-app-finder\",\n priority: 100, // Higher priority = checked first\n handle: async (error, context) => {\n if (error.message.includes(\"database connection\")) {\n return {\n header: \"Database Connection Issue\",\n body: \"Check your database configuration and ensure the server is running.\",\n };\n }\n\n if (error.message.includes(\"authentication\")) {\n return {\n header: \"Authentication Error\",\n body: \"Verify your API keys and authentication tokens are valid.\",\n };\n }\n\n return undefined; // No solution found\n },\n};\n\nconst ono = new Ono();\nconst html = await ono.toHTML(error, {\n solutionFinders: [customFinder],\n});\n```\n\n### Copy to Clipboard\n\nAll data sections in the Request Context Panel include copy buttons that:\n\n- Copy data in JSON format for easy debugging\n- Provide visual feedback (button changes to \"Copied!\" with green styling)\n- Support both modern `navigator.clipboard` API and fallback methods\n- Work across all browsers and environments\n\n### Adding custom pages/tabs via `options.content`\n\nYou can add any number of custom pages using the `content` option:\n\n```ts\nimport { Ono } from \"@visulima/ono\";\nimport createRequestContextPage from \"@visulima/ono/page/context\";\n\nconst ono = new Ono();\n\n// Create a context page with request information\nconst contextPage = await createRequestContextPage(request, {\n context: {\n request: request,\n app: { routing: { route: \"/api/users\", params: {}, query: {} } },\n user: { client: { ip: \"127.0.0.1\", userAgent: \"Mozilla/5.0...\" } },\n database: { connection: \"active\", queries: [\"SELECT * FROM users\"] },\n },\n});\n\n// Add custom pages\nconst customPages = [\n contextPage, // Context page with request info\n {\n id: \"performance\",\n name: \"Performance\",\n code: {\n html: \"
\",\n },\n },\n];\n\nconst html = await ono.toHTML(error, {\n content: customPages,\n cspNonce: \"your-nonce\",\n});\n```\n\n## Examples\n\nThe `examples/` directory contains working examples for different use cases:\n\n### CLI Example (`examples/cli/`)\n\nDemonstrates basic ANSI output and custom solution finders:\n\n```bash\ncd examples/cli\nnode index.js\n```\n\n### Node.js HTTP Server (`examples/node/`)\n\nComplete HTTP server example with rich context pages:\n\n```bash\ncd examples/node\nnode index.js\n```\n\nTry these routes:\n\n- `/error` - Basic error with context\n- `/esm-cjs` - ESM/CJS interop error\n- `/export-mismatch` - Export mismatch error\n- `/custom-solution` - Custom solution finder demo\n\n### Hono Framework (`examples/hono/`)\n\nHono framework integration example:\n\n```bash\ncd examples/hono\nnode index.js\n```\n\nTry these routes:\n\n- `/error` - Basic error handling\n- `/error-html` - HTML error page\n- `/api/error-json` - JSON error response\n\n### Server helpers\n\nFrom `@visulima/ono/server/open-in-editor`:\n\n- `createOpenInEditorMiddleware(options)` — universal handler factory (Node `http` and Connect/Express), backed by `launch-editor-middleware`\n- `createNodeHttpHandler(options)` — returns `(req, res) => Promise` for Node `http` servers\n- `createExpressHandler(options)` — returns an Express/Connect-compatible handler\n\nOptions:\n\n- `projectRoot?: string` — defaults to `process.cwd()`\n- `allowOutsideProject?: boolean` — defaults to `false`\n\n### Editor selector\n\n- Always visible\n- Persists user choice in `localStorage` (`ono:editor`)\n- Used for both the server opener (sent as `editor` in the POST body) and the client-side fallback\n\n### Client-side fallback editor links\n\n- If `openInEditorUrl` is not set, clicking “Open in editor” uses editor URL schemes on the client. The default editor is VS Code. The selected editor in the header is respected.\n- Supported editors and templates (placeholders: `%f` = file, `%l` = line, `%c` = column when supported):\n - textmate: `txmt://open?url=file://%f&line=%l`\n - macvim: `mvim://open?url=file://%f&line=%l`\n - emacs: `emacs://open?url=file://%f&line=%l`\n - sublime: `subl://open?url=file://%f&line=%l`\n - phpstorm: `phpstorm://open?file=%f&line=%l`\n - atom: `atom://core/open/file?filename=%f&line=%l`\n - atom-beta: `atom-beta://core/open/file?filename=%f&line=%l`\n - brackets: `brackets://open?url=file://%f&line=%l`\n - clion: `clion://open?file=%f&line=%l`\n - code (VS Code): `vscode://file/%f:%l:%c`\n - code-insiders: `vscode-insiders://file/%f:%l:%c`\n - codium (VSCodium): `vscodium://file/%f:%l:%c`\n - cursor: `cursor://file/%f:%l:%c`\n - emacs: `emacs://open?url=file://%f&line=%l`\n - idea: `idea://open?file=%f&line=%l`\n - intellij: `idea://open?file=%f&line=%l`\n - macvim: `mvim://open?url=file://%f&line=%l`\n - notepad++: `notepad-plus-plus://open?file=%f&line=%l`\n - phpstorm: `phpstorm://open?file=%f&line=%l`\n - pycharm: `pycharm://open?file=%f&line=%l`\n - rider: `rider://open?file=%f&line=%l`\n - rubymine: `rubymine://open?file=%f&line=%l`\n - sublime: `subl://open?url=file://%f&line=%l`\n - textmate: `txmt://open?url=file://%f&line=%l`\n - vim: `vim://open?url=file://%f&line=%l`\n - visualstudio: `visualstudio://open?file=%f&line=%l`\n - vscode: `vscode://file/%f:%l:%c`\n - vscodium: `vscodium://file/%f:%l:%c`\n - webstorm: `webstorm://open?file=%f&line=%l`\n - xcode: `xcode://open?file=%f&line=%l`\n - zed: `zed://open?file=%f&line=%l&column=%c`\n - android-studio: `idea://open?file=%f&line=%l`\n\n### Keyboard Shortcuts\n\n- **Shift+/ (or ?)** — Open shortcuts help dialog\n- **Esc** — Close dialogs\n- **Enter/Space** — Activate focused control (e.g., toggles, tabs)\n\n### Tooltips\n\nComponents emit HTML with `data-tooltip-trigger`; a single script exported by the tooltip module is imported once by the layout (so there's no duplication).\n\n### Extend the VisulimaError\n\n```ts\nimport { VisulimaError } from \"@visulima/error\";\n\nclass MyError extends VisulimaError {\n constructor(message: string) {\n super({\n name: \"MyError\",\n message,\n });\n }\n}\n\nthrow new MyError(\"My error message\");\n\n// or\n\nconst error = new MyError(\"My error message\");\n\nerror.hint = \"My error hint\";\n\nthrow error;\n```\n\n### Pretty code frame\n\n```ts\nimport { codeFrame } from \"@visulima/error\";\n\nconst source = \"const x = 10;\\nconst error = x.y;\\n\";\nconst loc = { column: 16, line: 2 };\n\nconst frame = codeFrame(source, loc);\n\nconsole.log(frame);\n// 1 | const x = 10;\n// > 2 | const error = x.y;\n// | ^\n```\n\n## Supported Node.js Versions\n\nLibraries in this ecosystem make the best effort to track [Node.js’ release schedule](https://github.com/nodejs/release#release-schedule).\nHere’s [a post on why we think this is important](https://medium.com/the-node-js-collection/maintainers-should-consider-following-node-js-release-schedule-ab08ed4de71a).\n\n## Contributing\n\nIf you would like to help take a look at the [list of issues](https://github.com/visulima/visulima/issues) and check our [Contributing](.github/CONTRIBUTING.md) guild.\n\n> **Note:** please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.\n\n## Credits\n\n- [Daniel Bannert](https://github.com/prisis)\n- [All Contributors](https://github.com/visulima/visulima/graphs/contributors)\n\n## Made with ❤️ at Anolilab\n\nThis is an open source project and will always remain free to use. If you think it's cool, please star it 🌟. [Anolilab](https://www.anolilab.com/open-source) is a Development and AI Studio. Contact us at [hello@anolilab.com](mailto:hello@anolilab.com) if you need any help with these technologies or just want to say hi!\n\n## License\n\nThe visulima error is open-sourced software licensed under the [MIT][license]\n\n\n\n[license-badge]: https://img.shields.io/npm/l/@visulima/ono?style=for-the-badge\n[license]: https://github.com/visulima/visulima/blob/main/LICENSE\n[npm-downloads-badge]: https://img.shields.io/npm/dm/@visulima/ono?style=for-the-badge\n[npm-downloads]: https://www.npmjs.com/package/@visulima/ono\n[prs-welcome-badge]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=for-the-badge\n[prs-welcome]: https://github.com/visulima/visulima/blob/main/.github/CONTRIBUTING.md\n[chat-badge]: https://img.shields.io/discord/902465130518949899.svg?style=for-the-badge\n[chat]: https://discord.gg/eajEZvk2PG\n[typescript-badge]: https://img.shields.io/badge/Typescript-294E80.svg?style=for-the-badge&logo=typescript\n[typescript-url]: https://www.typescriptlang.org/\n","readmeFilename":"README.md"}
![\"ono\"](\"__assets__/package-og.svg\")
\n\n