raf - requestAnimationFrame polyfill

Common errors

• TypeError: raf is not a function

  cause This error typically occurs when `require('raf/polyfill')` or `import 'raf/polyfill';` is used to polyfill the global scope, and then the developer attempts to call `raf()` as if it were a locally imported function, rather than accessing `window.requestAnimationFrame` or `global.requestAnimationFrame`.
  fix If you are only polyfilling the global scope, access the function via `window.requestAnimationFrame` (or `global.requestAnimationFrame` in Node). If you intend to use `raf` as a local function, ensure you explicitly `import raf from 'raf';` or `const raf = require('raf');`.

• ReferenceError: window is not defined

  cause Attempting to access `window.requestAnimationFrame` or `window.raf` directly in a Node.js environment where the `window` object does not exist, before `raf/polyfill` has been correctly applied to polyfill the `global` object.
  fix In Node.js, ensure `require('raf/polyfill');` or `import 'raf/polyfill';` is executed early in your application's lifecycle to polyfill `global.requestAnimationFrame`. Alternatively, use the `raf` function returned by `require('raf')` directly without relying on global `window`.

Warnings

• breaking The stream and event emitter logic that was part of `raf` in versions prior to 1.0.0 has been removed. This functionality was extracted and moved to a separate package, `raf-stream`.
  Fix: If your application relied on the stream or event emitter API of `raf`, you must migrate to using the `raf-stream` package instead, or reimplement the streaming logic using the core `raf` function directly.
• gotcha There's a distinction between importing the `raf` function directly (e.g., `import raf from 'raf'`) and applying the polyfill to the global scope (e.g., `import 'raf/polyfill'`). The former provides a local utility, while the latter modifies `window.requestAnimationFrame` (or `global.requestAnimationFrame` in Node).
  Fix: Determine whether you need to polyfill the global environment or simply use the `raf` function as a local import. Use `import 'raf/polyfill';` for global polyfilling or `raf.polyfill()` for explicit control over the target object.
• gotcha The `raf` package provides different consumption patterns for various environments: CommonJS (Node, bundlers), AMD (RequireJS), and direct `<script>` inclusion. Mis-matching the import/require method with your environment can lead to errors.
  Fix: Ensure you are using the correct method for your build system or runtime environment. Use `require('raf')` or `import raf from 'raf'` for modules, and rely on `window.raf` after including the UMD bundle via a script tag.

Install

• npm install raf npm
• yarn add raf yarn
• pnpm add raf pnpm

Imports

• raf
  wrong:

  import { raf } from 'raf';

  correct:

  import raf from 'raf';

  The primary `raf` function is a default export, common in modern ESM usage.
• raf (CommonJS)
  wrong:

  import raf from 'raf';

  correct:

  const raf = require('raf');

  CommonJS `require` is the standard for Node.js and older bundler configurations documented by the library.
• raf.polyfill
  wrong:

  import { polyfill } from 'raf';

  correct:

  import 'raf/polyfill';

  To apply the polyfill to the global scope (`window` or `global`), import 'raf/polyfill' directly as a side effect or call `raf.polyfill()`.
• raf (global)

  window.raf(...);

  When included via a `<script>` tag or after `raf.polyfill()` is executed in a browser-like environment, the `raf` function is available on the global `window` object.

Quickstart

Demonstrates a basic animation loop using `raf` to schedule a function (`animate`) to run on subsequent animation frames, logging progress until a predefined frame limit is reached.

import raf from 'raf';

let frameCount = 0;
const maxFrames = 100;

console.log('Starting animation loop...');

function animate() {
  // Perform animation logic here
  console.log(`Processing animation frame: ${frameCount}`);
  frameCount++;

  if (frameCount < maxFrames) {
    raf(animate); // Schedule the next frame
  } else {
    console.log('Animation finished after', maxFrames, 'frames.');
  }
}

// Start the initial animation frame
raf(animate);