Registry / web-framework / framesync

framesync

JSON →
library6.1.2jsnpmunverified

Framesync is a JavaScript library designed for scheduling functions into a synchronized render loop, primarily to prevent layout thrashing and ensure predictable execution order within a browser frame. It provides discrete steps for `read`, `update`, `preRender`, `render`, and `postRender` operations, allowing developers to organize DOM interactions efficiently. The current stable version is 6.1.2, and as part of the Popmotion ecosystem, it maintains a steady, mature release cadence focusing on stability and performance. Its primary differentiator is the explicit segregation of frame steps, which is crucial for high-performance animations and UI updates, notably used by libraries like Framer Motion to manage complex transform animations independently. Functions scheduled with Framesync receive frame data including `delta` (time since last frame) and `timestamp`.

npm install framesync
INSTALL
IMPORT
SIG · FRAMESYNC
F
framesync
web-frameworkjavascriptv6.1.2
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

sync
import sync from 'framesync';
const sync = require('framesync');
Framesync uses an ESM default export for the main `sync` object. CommonJS `require` will result in accessing `sync.default` if supported by your build system, or an error in a pure ESM environment.
cancelSync
import { cancelSync } from 'framesync';
const { cancelSync } = require('framesync');
Named exports like `cancelSync` are provided. CommonJS `require` for named exports will fail in pure ESM environments and may behave unexpectedly in others.
FrameData
import type { FrameData } from 'framesync';
Use a type import for the `FrameData` interface (containing `delta` and `timestamp`) when working with TypeScript.

Demonstrates scheduling a function to run on the `update` step of the render loop, accessing frame data, and canceling the process once a condition is met. It also shows an immediate render call.

import sync, { cancelSync } from 'framesync'; let animationProgress = 0; const targetProgress = 100; console.log('Starting framesync animation...'); const updateFunction = ({ delta, timestamp }) => { // In a real app, 'delta' would be used to calculate frame-rate independent updates. // For this example, we'll just increment. animationProgress += 1; // Simulate some DOM read operation (e.g., getBoundingClientRect) const elementWidth = document.body?.clientWidth || 0; console.log(`[Frame ${timestamp.toFixed(2)}] Delta: ${delta.toFixed(2)}ms, Progress: ${animationProgress}, Width: ${elementWidth}`); if (animationProgress >= targetProgress) { cancelSync.update(updateFunction); console.log('Animation complete!'); } }; sync.update(updateFunction, true); // Schedule to run indefinitely on the update step // Simulate an immediate render call for some initial setup sync.render(() => { // This would typically update DOM properties // For example: document.body.style.transform = `translateX(${animationProgress}px)`; console.log('Initial render step executed immediately.'); }, false, true);
Debug
Known issues
gotchaThe `FrameData` object (containing `delta` and `timestamp`) passed to scheduled functions is recycled across frames for performance. If you need to use `delta` or `timestamp` asynchronously (e.g., in a `setTimeout` or `Promise`), you must destructure or copy its values, otherwise, they may change unexpectedly.
fix
Destructure the `FrameData` object immediately: `sync.update(({ delta, timestamp }) => { const currentDelta = delta; // use currentDelta asynchronously })`
affects: >=1.0.0
gotchaBy default, `sync` functions schedule execution for the *next* time that frame step is fired. To execute a function on the *current* frame step, you must explicitly pass `true` as the third parameter for `immediate` execution.
fix
Use `sync.step(callback, keepAlive, true)` to run on the current frame step. For example: `sync.update(() => console.log('now!'), false, true);`
affects: >=1.0.0
gotchaWhen using the `keepAlive: true` option, a scheduled function will run indefinitely on every frame until it is explicitly cancelled using `cancelSync.<step>(process)`. Forgetting to cancel can lead to memory leaks and unnecessary CPU usage.
fix
Always ensure there's a clear condition to call `cancelSync.step(yourProcessFunction)` when using `keepAlive: true`.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: framesync__WEBPACK_IMPORTED_MODULE_0__.default.update is not a function
Attempting to use CommonJS `require` or an incorrect import statement with a bundler that doesn't handle ESM default exports properly, leading to `sync` being an object with a `default` property, not the `sync` object itself.
fix
Ensure you are using `import sync from 'framesync';` for the default export. If using CommonJS, try `const sync = require('framesync').default;` (though this is not recommended for pure ESM libraries).
Uncaught TypeError: cancelSync.render is not a function
`cancelSync` is a named export, and its methods (`.read`, `.update`, `.render`, etc.) are functions. This error often occurs if `cancelSync` itself is not correctly imported as a named export.
fix
Ensure `cancelSync` is imported as a named export: `import { cancelSync } from 'framesync';`
Upgrade
Version history
6.1.2latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
5 hits · last 30 days
node
4
Amazon
1
Resources
framesync — npm install framesync · libregistry