Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
flaggedRespawn
✓ import flaggedRespawn from 'flagged-respawn';
✗ import { flaggedRespawn } from 'flagged-respawn';
The library exports a default function. For CommonJS, `require('flagged-respawn')` directly returns the function.
flaggedRespawn
✓ const flaggedRespawn = require('flagged-respawn');
CommonJS import for Node.js environments. This is the primary usage pattern shown in documentation.
Demonstrates how to use flagged-respawn to correctly handle Node.js/V8 flags by respawning the process if necessary, ensuring flags are applied to the Node.js executable.
import flaggedRespawn from 'flagged-respawn';
import { fetch as fetchV8Flags } from 'v8flags';
// In a real application, you'd fetch v8flags once at startup.
// For simplicity, we'll fetch it synchronously here.
const v8flags = fetchV8Flags();
flaggedRespawn(v8flags, process.argv, function (ready, child, argv) {
if (ready) {
console.log('Application ready to run! Current process PID:', process.pid);
console.log('Arguments:', argv.slice(2).join(' '));
// Your main CLI application logic goes here.
// Example: process a command or run a task.
if (argv.includes('--test-mode')) {
console.log('Running in test mode!');
}
// Simulate work
setTimeout(() => {
console.log('Application finished.');
// process.exit(0); // Uncomment in a real app to exit cleanly
}, 1000);
} else {
console.log('Special flags found, respawning process...');
console.log('Old PID:', process.pid, 'New PID (if respawned):', child ? child.pid : 'N/A');
}
});
Debug
Known issues
breakingVersion 2.0.0 dropped support for Node.js versions older than 10.13.0. Applications running on older Node.js runtimes will need to upgrade Node.js or remain on `flagged-respawn@1.x`.fixUpgrade Node.js to version 10.13.0 or higher, or explicitly pin `flagged-respawn` to a 1.x version.
affects: >=2.0.0
breakingIn version 2.0.0, the library no longer supports V8 flags separated by underscores (e.g., `--harmony_async_await`). Flags must now use dashes (e.g., `--harmony-async-await`).fixEnsure all V8 flags passed to `process.argv` use dashes as word separators, conforming to standard Node.js flag syntax.
affects: >=2.0.0
breakingVersion 0.3.0 introduced a major API simplification and rewrite. If upgrading from versions prior to 0.3.0, the `flaggedRespawn` function signature and behavior would have changed significantly.fixReview the API documentation for `flaggedRespawn(flags, argv, [ forcedFlags, ] callback)` and adapt your code to the new signature.
affects: <0.3.0 to >=0.3.0
breakingVersion 0.2.0 introduced a change where `flaggedRespawn` will throw an error if no `flags` array is passed as the first argument. Previously, it might have silently proceeded without any flags to check.fixAlways pass an array of flags (e.g., obtained from `v8flags`) as the first argument to `flaggedRespawn`.
affects: <0.2.0 to >=0.2.0
gotchaThe `callback` function is invoked in both the parent and child process. The `ready` argument differentiates whether the current execution is the final, ready-to-run process (`true`) or the parent process that just initiated a respawn (`false`). It does not indicate whether the current process *is* the respawned child.fixAlways check the `ready` parameter in your callback to ensure your application logic only runs in the intended 'final' process. You can also compare `process.pid` with `child.pid` for explicit child process detection.
affects: >=0.1.0
Errors
Common errors & fixes
TypeError: flaggedRespawn is not a function
Attempting to use `flaggedRespawn` after an incorrect ES module import, or if `require` was called on a module that doesn't export a function directly.
fixFor CommonJS, use `const flaggedRespawn = require('flagged-respawn');`. For ESM, use `import flaggedRespawn from 'flagged-respawn';`. Error: Node.js version x.y.z is not supported. Please upgrade to Node.js 10.13.0 or higher.
Running `flagged-respawn` version 2.0.0 or higher on an unsupported Node.js version.
fixUpgrade your Node.js runtime to version 10.13.0 or newer. Alternatively, if upgrading Node.js is not an option, downgrade `flagged-respawn` to a 1.x version.
Flag --harmony_feature is not recognized.
Passing V8 flags with underscores (e.g., `--harmony_async_await`) in `process.argv` to `flagged-respawn@2.x`.
fixChange the flag syntax to use dashes instead of underscores (e.g., `--harmony-async-await`).
Audit
Dependencies
v8flagsrequiredUsed to fetch a list of all possible V8 flags for the running version of Node.js, which is then passed to `flaggedRespawn` to determine if a respawn is necessary.