Node Fibers

5.0.3 · deprecated · verified Sun Apr 19

Fibers is a Node.js module that enables cooperative multi-tasking, often referred to as coroutines, by providing an API to jump between multiple call stacks within a single thread. It allows developers to write asynchronous code in a synchronous, blocking style, making it easier to integrate with older synchronous libraries. Originally developed in early 2011 for Node.js v0.1.x, the module's utility has largely been superseded by the standardization of native JavaScript features like Promises, async/await, and Generators. The current stable version is 5.0.3, although its compatibility is limited to Node.js v14.x and older, specifically not supporting v16.0.0 or later due to V8 engine changes. The project maintainer actively recommends avoiding its use due to its obsolescence and the inherent difficulty in maintaining compatibility with the rapidly evolving V8 engine and Node.js platform, which makes its long-term viability uncertain. It does not follow a regular release cadence, with updates primarily driven by critical compatibility fixes for older Node.js versions. A key differentiator was its ability to bring synchronous-looking code to asynchronous environments, a niche now robustly filled by modern JS concurrency primitives. Given its age and the availability of superior native alternatives, it is largely considered a legacy solution.

Common errors

```
Fibers is not compatible with nodejs v16.0.0 or later.
```
cause The V8 engine underwent breaking changes in Node.js v16.0.0, which are incompatible with the internal mechanisms of `fibers`.

fix Downgrade your Node.js version to 14.x or earlier, or refactor your application to use native async/await, Promises, or Generators.
```
Error: `node-gyp rebuild` failed with exit code 1
```
cause Native compilation of the `fibers` module failed, often due to missing build tools (e.g., Python, C++ compiler) or incompatible Node.js headers.

fix Install `node-gyp` globally (`npm install -g node-gyp`) and ensure all required build tools are installed as per `node-gyp` documentation for your operating system. Verify your Node.js version is supported by the `fibers` version you are installing.
```
Cannot find module 'fibers/bin/darwin-x64-v8-XX/fibers.node' (or similar path)
```
cause The `fibers` native module could not be loaded, typically because compilation failed, or a pre-compiled binary for your specific environment (OS, architecture, V8 version) does not exist.

fix Run `npm rebuild fibers` to force a recompilation. If it fails, ensure `node-gyp` and build tools are correctly set up. Verify your Node.js version is compatible with the installed `fibers` version.
```
FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory
```
cause Using `fibers` in certain complex or long-running scenarios can lead to memory exhaustion due to its native memory management and interaction with V8's garbage collector.

fix This often indicates a design issue with using `fibers` for tasks better suited for native async/await or Promises. Consider refactoring your code to avoid `fibers` for memory-intensive operations.
```
TypeError: Fiber is not a constructor
```
cause The `require('fibers')` call did not return the expected Fiber class, possibly due to a corrupted installation or an attempt to use it in an incompatible environment.

fix Ensure `fibers` is correctly installed via `npm install fibers`. Verify that you are using CommonJS `require` and not ES Module `import`. Check Node.js version compatibility and reinstall if necessary.

Warnings

breaking Fibers is not compatible with Node.js v16.0.0 or later due to breaking changes in the V8 engine, specifically V8 commit dacc2fee0f. Workarounds are non-trivial and unsupported.
Fix: Downgrade Node.js to v14.x or earlier, or refactor code to use modern async/await, Promises, or Generators instead of `fibers`.
deprecated The author of `fibers` actively recommends avoiding its use. The module is considered obsolete, as modern JavaScript features like async/await, Promises, and Generators provide superior, native alternatives for asynchronous control flow.
Fix: Migrate existing code to use native async/await, Promises, or Generators, which offer better maintainability, performance, and ecosystem compatibility.
gotcha Specific versions of `fibers` are required for different Node.js major versions. For example, Node.js v10.x requires `fibers@4`, while v12.x and v14.x require `fibers@5`.
Fix: Ensure the correct `fibers` version is installed for your Node.js runtime. For Node.js v10.x, use `npm install fibers@4`. For v12.x/v14.x, use `npm install fibers@5`.
gotcha `fibers` is a native C++ addon and requires `node-gyp` for compilation. Installation may fail if development tools (Python, C++ compiler, Visual Studio on Windows) are not properly set up, or if V8 ABI changes between Node.js minor versions.
Fix: Install `node-gyp` globally (`npm install -g node-gyp`) and ensure all required build tools are available on your system. Refer to `node-gyp` documentation for platform-specific setup instructions.
gotcha Meteor users should generally avoid directly installing `fibers`. Meteor bundles its own compatible version, and manual installation often indicates a misconfiguration or leads to conflicts.
Fix: If using Meteor, uninstall all versions of Node.js and Meteor, then reinstall Meteor to ensure a clean, integrated environment. Do not install `fibers` manually for Meteor projects unless explicitly directed by official Meteor documentation.

Install

npm install fibers npm
yarn add fibers yarn
pnpm add fibers pnpm

Imports

Fiber
wrong:
```
import Fiber from 'fibers';
```
correct:
```
const Fiber = require('fibers');
```
Fibers is a CommonJS module and provides the Fiber class as the default export of `require('fibers')`. It does not support ES Modules.
Fiber.yield
wrong:
```
yield;
```
correct:
```
Fiber.yield();
```
The `yield` operation is a static method of the Fiber class, used to pause the current fiber's execution and return control to the caller. It is not the native JavaScript `yield` keyword.
fiberInstance.run
wrong:
```
myFiber();
```
correct:
```
myFiber.run();
```
Once a Fiber instance is created, its execution is started or resumed by calling the `.run()` method. Calling the Fiber instance directly as a function will not execute it.

Quickstart

Demonstrates the basic usage of `fibers` by creating a fiber, starting its execution, yielding control back to the main thread, and then resuming the fiber multiple times.

const Fiber = require('fibers');

console.log('Main thread start');

const myFiber = Fiber(function() {
  let counter = 0;
  while (true) {
    console.log(`Fiber step ${++counter}`);
    if (counter >= 3) {
      console.log('Fiber exiting');
      break; // Exit the fiber
    }
    Fiber.yield(); // Pause fiber, return to caller
  }
});

console.log('Starting fiber...');
myFiber.run(); // Run until first yield or completion
console.log('Back in main thread after first yield');

myFiber.run(); // Resume fiber
console.log('Back in main thread after second yield');

myFiber.run(); // Resume fiber
console.log('Back in main thread after third yield');

if (!myFiber.isFinished()) {
  myFiber.run(); // In case it hasn't finished (e.g., if break condition isn't met)
}
console.log('Main thread end');

view raw JSON →