{"id":15168,"library":"raf","title":"raf - requestAnimationFrame polyfill","description":"The `raf` package provides a `requestAnimationFrame` polyfill, making the browser animation API available in non-browser environments like Node.js and ensuring broader compatibility across older browser versions. The current stable version is 3.4.1. It maintains a simple, direct API for scheduling animation callbacks, distinct from event emitter or stream-based approaches which were moved to the separate `raf-stream` package in versions prior to 1.0.0. Its primary differentiator is its lightweight nature and dedicated support for Node.js environments without relying on heavy browser emulation. Release cadence is infrequent, typical for a stable polyfill, with updates primarily addressing compatibility issues or minor bug fixes, rather than introducing new features. This package is a foundational utility for cross-environment animation loops.","status":"active","version":"3.4.1","language":"javascript","source_language":"en","source_url":"git://github.com/chrisdickinson/raf","tags":["javascript","requestAnimationFrame","polyfill"],"install":[{"cmd":"npm install raf","lang":"bash","label":"npm"},{"cmd":"yarn add raf","lang":"bash","label":"yarn"},{"cmd":"pnpm add raf","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary `raf` function is a default export, common in modern ESM usage.","wrong":"import { raf } from 'raf';","symbol":"raf","correct":"import raf from 'raf';"},{"note":"CommonJS `require` is the standard for Node.js and older bundler configurations documented by the library.","wrong":"import raf from 'raf';","symbol":"raf (CommonJS)","correct":"const raf = require('raf');"},{"note":"To apply the polyfill to the global scope (`window` or `global`), import 'raf/polyfill' directly as a side effect or call `raf.polyfill()`.","wrong":"import { polyfill } from 'raf';","symbol":"raf.polyfill","correct":"import 'raf/polyfill';"},{"note":"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.","symbol":"raf (global)","correct":"window.raf(...);"}],"quickstart":{"code":"import raf from 'raf';\n\nlet frameCount = 0;\nconst maxFrames = 100;\n\nconsole.log('Starting animation loop...');\n\nfunction animate() {\n  // Perform animation logic here\n  console.log(`Processing animation frame: ${frameCount}`);\n  frameCount++;\n\n  if (frameCount < maxFrames) {\n    raf(animate); // Schedule the next frame\n  } else {\n    console.log('Animation finished after', maxFrames, 'frames.');\n  }\n}\n\n// Start the initial animation frame\nraf(animate);\n","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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`.","severity":"breaking","affected_versions":">=1.0.0"},{"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.","message":"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).","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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');`.","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`.","error":"TypeError: raf is not a function"},{"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`.","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.","error":"ReferenceError: window is not defined"}],"ecosystem":"npm"}