{"id":15435919,"url":"https://github.com/uetchy/epicfail","last_synced_at":"2025-04-19T18:24:12.197Z","repository":{"id":47453960,"uuid":"280613483","full_name":"uetchy/epicfail","owner":"uetchy","description":"⛑ Better error reporting for Node.js command-line apps.","archived":false,"fork":false,"pushed_at":"2021-08-31T04:44:24.000Z","size":8204,"stargazers_count":11,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-29T11:34:42.867Z","etag":null,"topics":["cli","command-line","error-handling","error-reporting","javascript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/uetchy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-07-18T08:19:15.000Z","updated_at":"2024-07-30T14:42:17.000Z","dependencies_parsed_at":"2022-08-24T10:40:13.332Z","dependency_job_id":null,"html_url":"https://github.com/uetchy/epicfail","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uetchy%2Fepicfail","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uetchy%2Fepicfail/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uetchy%2Fepicfail/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uetchy%2Fepicfail/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/uetchy","download_url":"https://codeload.github.com/uetchy/epicfail/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249352775,"owners_count":21255934,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","command-line","error-handling","error-reporting","javascript"],"created_at":"2024-10-01T18:46:57.849Z","updated_at":"2025-04-19T18:24:12.181Z","avatar_url":"https://github.com/uetchy.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eepicfail\u003c/h1\u003e\n\u003cp align=\"center\"\u003eBetter error reporting for Node.js command-line apps.\u003c/p\u003e\n\u003cimg  align=\"center\" src=\"https://raw.githubusercontent.com/uetchy/epicfail/master/docs/top.png\" /\u003e\n\n## Features\n\n[![npm-version]][npm-url]\n[![npm-downloads]][npm-url]\n![npm bundle size](https://img.shields.io/bundlephobia/minzip/epicfail)\n[![Actions Status: test](https://github.com/uetchy/epicfail/workflows/test/badge.svg)](https://github.com/uetchy/epicfail/actions?query=test)\n\n[npm-version]: https://badgen.net/npm/v/epicfail\n[npm-downloads]: https://badgen.net/npm/dt/epicfail\n[npm-url]: https://npmjs.org/package/epicfail\n\n\u003e **epicfail** converts `unhandledRejection` and `uncaughtException` into graceful and helpful error message for both users and developers.\n\n⬇️ Prints error messages in _copy and paste ready_ Markdown.  \n🌐 Asks users to report a bug (navigate users to `bugs.url` in `package.json`).  \n🍁 Shows machine environments (OS, Node.js version, etc).  \n👀 Suggests related issues in GitHub.  \n🛠 Integration with error aggregation service (like Sentry).\n\n## Table of Contents\n\n\u003c!-- START mdmod {use: 'toc'} --\u003e\n\n\n- [epicfail](#epicfail)\n  - [Features](#features)\n  - [Table of Contents](#table-of-contents)\n  - [Install](#install)\n  - [Use](#use)\n    - [ESModules](#esmodules)\n    - [CommonJS](#commonjs)\n  - [Options](#options)\n    - [stacktrace (default: `true`)](#stacktrace-default-true)\n    - [issues (default: `false`)](#issues-default-false)\n    - [env](#env)\n    - [message (default: `true`)](#message-default-true)\n    - [assertExpected (default: `() =\u003e false`)](#assertexpected-default---false)\n    - [onError (default: `undefined`)](#onerror-default-undefined)\n  - [Advanced Usage](#advanced-usage)\n    - [Print error message without extra information](#print-error-message-without-extra-information)\n    - [Sentry integration](#sentry-integration)\n    - [Runtime options](#runtime-options)\n\n\u003c!-- END mdmod --\u003e\n\n## Install\n\n```bash\nnpm install --save epicfail\n# or\nyarn add epicfail\n```\n\n## Use\n\n### ESModules\n\n```js\nimport { epicfail } from \"epicfail\";\n\nepicfail(import.meta.url);\n\n// your CLI app code goes here\nfs.readFileSync(\"foo\"); // =\u003e will cause \"ENOENT: no such file or directory, open 'foo'\"\n```\n\n### CommonJS\n\n```js\nconst { epicfail } = require(\"epicfail\");\n\nepicfail(require.main.filename);\n\n// your CLI app code goes here\nfs.readFileSync(\"foo\"); // =\u003e will cause \"ENOENT: no such file or directory, open 'foo'\"\n```\n\n![With stacktrace](https://raw.githubusercontent.com/uetchy/epicfail/master/docs/full.png)\n\n## Options\n\n### stacktrace (default: `true`)\n\nShow stack trace.\n\n```js\nimport { epicfail } from \"epicfail\";\n\nepicfail(import.meta.url, {\n  stacktrace: false,\n});\n```\n\n![Without stacktrace](https://raw.githubusercontent.com/uetchy/epicfail/master/docs/without-stacktrace.png)\n\n### issues (default: `false`)\n\nSearch and show related issues in GitHub Issues.\n\n```js\nimport { epicfail } from \"epicfail\";\n\nepicfail(import.meta.url, {\n  issues: true,\n});\n```\n\n![With issues](https://raw.githubusercontent.com/uetchy/epicfail/master/docs/with-issues.png)\n\n### env\n\nShow environment information. You can find all possible options [here](https://github.com/tabrindle/envinfo#cli-usage). Set to `false` to disable it.\n\n```js\nimport { epicfail } from \"epicfail\";\n\nepicfail(import.meta.url, {\n  env: {\n    System: [\"OS\", \"CPU\"],\n    Binaries: [\"Node\", \"Yarn\", \"npm\"],\n    Utilities: [\"Git\"],\n  },\n});\n```\n\nDefault values:\n\n```json\n{\n  \"System\": [\"OS\"],\n  \"Binaries\": [\"Node\"]\n}\n```\n\n![With envinfo](https://raw.githubusercontent.com/uetchy/epicfail/master/docs/with-envinfo.png)\n\n### message (default: `true`)\n\nShow bug tracker URL and ask users to report the error.\n\n```js\nimport { epicfail } from \"epicfail\";\n\nepicfail(import.meta.url, { message: false });\n```\n\n### assertExpected (default: `() =\u003e false`)\n\nWhile processing an error, if `assertExpected(error)` returns `true`, epicfail just prints the error message without any extra information; which is the same behaviour as the `logAndExit()` function described below.\n\n```js\nimport { epicfail } from \"epicfail\";\n\nepicfail(import.meta.url, {\n  assertExpected: (err) =\u003e err.name === \"ArgumentError\",\n});\n```\n\n### onError (default: `undefined`)\n\nPass the function that process the error and returns event id issued by external error aggregation service.\n\n```js\nimport { epicfail } from \"epicfail\";\nimport Sentry from \"@sentry/node\";\n\nepicfail(import.meta.url, {\n  onError: (err) =\u003e Sentry.captureException(err), // will returns an event id issued by Sentry\n});\n```\n\n## Advanced Usage\n\n### Print error message without extra information\n\nUse `logAndExit()` to print error message in red text without any extra information (stack trace, environments, etc), then quit program. It is useful when you just want to show the expected error message without messing STDOUT around with verbose log messages.\n\n```js\nimport { epicfail, logAndExit } from \"epicfail\";\n\nepicfail(import.meta.url);\n\nfunction cli(args) {\n  if (args.length === 0) {\n    logAndExit(\"usage: myapp \u003cinput\u003e\");\n  }\n}\n\ncli(process.argv.slice(2));\n```\n\nYou can also pass an Error instance:\n\n```js\nfunction cli(args) {\n  try {\n    someFunction();\n  } catch (err) {\n    logAndExit(err);\n  }\n}\n```\n\n### Sentry integration\n\n```js\nimport { epicfail } from \"epicfail\";\nimport Sentry from \"@sentry/node\";\n\nepicfail(import.meta.url, {\n  stacktrace: false,\n  env: false,\n  onError: Sentry.captureException, // will returns event_id issued by Sentry\n});\n\nSentry.init({\n  dsn: \"\u003cyour sentry token here\u003e\",\n  defaultIntegrations: false, // required\n});\n\n// your CLI app code goes here\nfs.readFileSync(\"foo\"); // =\u003e will cause \"ENOENT: no such file or directory, open 'foo'\"\n```\n\n![Sentry integration](https://raw.githubusercontent.com/uetchy/epicfail/master/docs/with-sentry.png)\n\n### Runtime options\n\n```js\nimport {epicfail} from 'epicfail';\n\nepicfail(import.meta.url);\n\n// 1. Use epicfail property in Error instance.\nconst expected = new Error('Wooops');\nexpected.epicfail = { stacktrace: false, env: false, message: false };\nthrow expected;\n\n// 2. Use fail method\nimport { fail } from 'epicfail';\nfail('Wooops', { stacktrace: false, env: false, message: false });\n\n// 3. Use EpicfailError class (useful in TypeScript)\nimport { EpicfailError } from 'epicfail';\nconst err = new EpicfailError('Wooops', { stacktrace: false, env: false, message: false };);\nthrow err;\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuetchy%2Fepicfail","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fuetchy%2Fepicfail","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuetchy%2Fepicfail/lists"}