Flagged Respawn

2.0.0 · active · verified Sun Apr 19

flagged-respawn is a utility designed to address the common problem in Node.js applications where V8 or Node.js runtime flags (e.g., `--harmony`, `--experimental-modules`) are incorrectly placed within `process.argv`, leading them to be interpreted as application arguments rather than runtime options. This library identifies such flags and automatically respawns the Node.js process with the flags correctly prepended to the `node` executable command. The current stable version is 2.0.0. While there isn't a strict release cadence, it's part of the Gulp.js ecosystem, suggesting active maintenance for relevant Node.js versions. Its key differentiators include automatically handling stdio piping, ensuring the child process's exit code and signals are propagated to the parent, and providing a mechanism to prevent multiple respawns.

Common errors

```
TypeError: flaggedRespawn is not a function
```
cause 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.

fix For 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.
```
cause Running `flagged-respawn` version 2.0.0 or higher on an unsupported Node.js version.

fix Upgrade 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.
```
cause Passing V8 flags with underscores (e.g., `--harmony_async_await`) in `process.argv` to `flagged-respawn@2.x`.

fix Change the flag syntax to use dashes instead of underscores (e.g., `--harmony-async-await`).

Warnings

breaking Version 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`.
Fix: Upgrade Node.js to version 10.13.0 or higher, or explicitly pin `flagged-respawn` to a 1.x version.
breaking In 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`).
Fix: Ensure all V8 flags passed to `process.argv` use dashes as word separators, conforming to standard Node.js flag syntax.
breaking Version 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.
Fix: Review the API documentation for `flaggedRespawn(flags, argv, [ forcedFlags, ] callback)` and adapt your code to the new signature.
breaking Version 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.
Fix: Always pass an array of flags (e.g., obtained from `v8flags`) as the first argument to `flaggedRespawn`.
gotcha The `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.
Fix: Always 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.

Install

npm install flagged-respawn npm
yarn add flagged-respawn yarn
pnpm add flagged-respawn pnpm

Imports

flaggedRespawn
wrong:
```
import { flaggedRespawn } from 'flagged-respawn';
```
correct:
```
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.

Quickstart

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');
  }
});

view raw JSON →