{"id":10900,"library":"flagged-respawn","title":"Flagged Respawn","description":"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.","status":"active","version":"2.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/gulpjs/flagged-respawn","tags":["javascript","respawn","flags"],"install":[{"cmd":"npm install flagged-respawn","lang":"bash","label":"npm"},{"cmd":"yarn add flagged-respawn","lang":"bash","label":"yarn"},{"cmd":"pnpm add flagged-respawn","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used 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.","package":"v8flags","optional":false}],"imports":[{"note":"The library exports a default function. For CommonJS, `require('flagged-respawn')` directly returns the function.","wrong":"import { flaggedRespawn } from 'flagged-respawn';","symbol":"flaggedRespawn","correct":"import flaggedRespawn from 'flagged-respawn';"},{"note":"CommonJS import for Node.js environments. This is the primary usage pattern shown in documentation.","symbol":"flaggedRespawn","correct":"const flaggedRespawn = require('flagged-respawn');"}],"quickstart":{"code":"import flaggedRespawn from 'flagged-respawn';\nimport { fetch as fetchV8Flags } from 'v8flags';\n\n// In a real application, you'd fetch v8flags once at startup.\n// For simplicity, we'll fetch it synchronously here.\nconst v8flags = fetchV8Flags();\n\nflaggedRespawn(v8flags, process.argv, function (ready, child, argv) {\n  if (ready) {\n    console.log('Application ready to run! Current process PID:', process.pid);\n    console.log('Arguments:', argv.slice(2).join(' '));\n    // Your main CLI application logic goes here.\n    // Example: process a command or run a task.\n    if (argv.includes('--test-mode')) {\n      console.log('Running in test mode!');\n    }\n    // Simulate work\n    setTimeout(() => {\n      console.log('Application finished.');\n      // process.exit(0); // Uncomment in a real app to exit cleanly\n    }, 1000);\n  } else {\n    console.log('Special flags found, respawning process...');\n    console.log('Old PID:', process.pid, 'New PID (if respawned):', child ? child.pid : 'N/A');\n  }\n});","lang":"javascript","description":"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."},"warnings":[{"fix":"Upgrade Node.js to version 10.13.0 or higher, or explicitly pin `flagged-respawn` to a 1.x version.","message":"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`.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure all V8 flags passed to `process.argv` use dashes as word separators, conforming to standard Node.js flag syntax.","message":"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`).","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Review the API documentation for `flaggedRespawn(flags, argv, [ forcedFlags, ] callback)` and adapt your code to the new signature.","message":"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.","severity":"breaking","affected_versions":"<0.3.0 to >=0.3.0"},{"fix":"Always pass an array of flags (e.g., obtained from `v8flags`) as the first argument to `flaggedRespawn`.","message":"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.","severity":"breaking","affected_versions":"<0.2.0 to >=0.2.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"For CommonJS, use `const flaggedRespawn = require('flagged-respawn');`. For ESM, use `import flaggedRespawn from 'flagged-respawn';`.","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.","error":"TypeError: flaggedRespawn is not a function"},{"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.","cause":"Running `flagged-respawn` version 2.0.0 or higher on an unsupported Node.js version.","error":"Error: Node.js version x.y.z is not supported. Please upgrade to Node.js 10.13.0 or higher."},{"fix":"Change the flag syntax to use dashes instead of underscores (e.g., `--harmony-async-await`).","cause":"Passing V8 flags with underscores (e.g., `--harmony_async_await`) in `process.argv` to `flagged-respawn@2.x`.","error":"Flag --harmony_feature is not recognized."}],"ecosystem":"npm"}