Essentials

1.2.0 verified Thu Apr 23 auth: no javascript

Essentials is a lightweight JavaScript utility designed for fundamental process initialization, primarily targeting Node.js and other V8-based environments (Chrome, Edge). Its main functions are to ensure that error stack traces include all available stack frames (a common limitation in many JavaScript engines outside of Firefox's hardcoded 128-frame limit) and, crucially, to convert unhandled promise rejections into uncaught exceptions. This prevents silent failures in asynchronous code, making debugging significantly easier. The package is currently at version 1.2.0 (last updated December 2021), indicating a stable project with a low release cadence, focusing on core process hygiene rather than feature expansion. It differentiates itself by providing these essential process-level enhancements with a minimal footprint and simple integration.

Common errors

error UnhandledPromiseRejectionWarning: This is an unhandled promise rejection! ↓

cause The 'essentials' module was not loaded, or was loaded too late in the process lifecycle to capture all rejections.

fix

Ensure require('essentials'); is the very first line in your main application entry point (e.g., index.js or app.js).

error TypeError: require is not a function (when using import) ↓

cause Attempting to use `require('essentials')` in an ES module environment (e.g., a file with `type: module` in `package.json` or `.mjs` extension).

fix

While essentials is primarily designed for CommonJS, if you must use it in an ES Module context, you might need to use import {} from 'essentials'; or dynamic import (import('essentials');) for its side-effects, though its primary intended usage is with require at the root of a CJS application.

Warnings

gotcha Essentials primarily targets V8-based engines (Node.js, Chrome, Microsoft Edge). While stack trace adjustments may have some effect elsewhere, the conversion of unhandled promise rejections to uncaught exceptions is specific to V8's behavior. For other engines, relying on Promise polyfills that emit `unhandledrejection` events is recommended for similar functionality. ↓

fix Ensure you understand the runtime environment. For non-V8 engines, consider a robust Promise polyfill that emits 'unhandledrejection' events for comprehensive error reporting.

breaking Prior to v1.2.0, requiring the 'essentials' module multiple times within the same process could lead to silent unhandled rejections, as the error handling mechanisms might be inadvertently overridden or re-initialized incorrectly. ↓

fix Update to `essentials@1.2.0` or higher to prevent doubled module loads. Ensure `require('essentials')` is called only once at the very top of your main application entry point.

gotcha The stack frame adjustment only affects the maximum number of frames reported. Firefox has a hardcoded limit of 128 frames that cannot be adjusted by this package. ↓

fix Be aware of engine-specific limitations. This feature provides a best-effort improvement for stack traces on adjustable engines, but cannot override browser-specific hard limits.

Install

npm install essentials

yarn add essentials

pnpm add essentials

Imports

Side-effect import
wrong
```
import 'essentials'; // ESM is not the primary usage model
```
correct
```
require('essentials');
```
This package is designed for a side-effect CommonJS `require()` at the very top of your main entry file to initialize global error handling behavior. There are no named exports.

Quickstart

Initializes essentials to ensure unhandled promise rejections become uncaught exceptions, demonstrating its core functionality.

/* In your main entry file (e.g., index.js) */
require('essentials');

console.log('Essentials initialized.');

// Demonstrate unhandled rejection becoming an uncaught exception
const myPromise = new Promise((resolve, reject) => {
  setTimeout(() => {
    reject(new Error('This is an unhandled promise rejection!'));
  }, 100);
});

// In a real application, you might do other setup here.
// The script will exit with an uncaught exception after 100ms.