@keyframerdev/vitals

Motion Vitals for React Native: slow frames and janky animations from production, by screen and by the line of code that started the animation. Reports go to your project on keyframer.dev.

• Safe for store builds: it never connects to Metro or a relay, never changes an animation, and does no work while nothing moves.
• JavaScript only: no native module and no config plugin. Works in Expo apps, Expo Go included.
• Never sends screenshots, text, values, touches, identifiers or absolute times.

Needs Reanimated 4.1 or later with react-native-worklets 0.5 or later (React Native 0.78 or later, New Architecture).

Install

npm i @keyframerdev/vitals

A regular dependency, not a dev dependency: it ships in your release build.

Start it

At the app's entry, with the project's field key (kfp_live_…, public and write-only, safe to ship):

import { startVitals } from '@keyframerdev/vitals'
import AsyncStorage from '@react-native-async-storage/async-storage'
import Constants from 'expo-constants'
import { Platform } from 'react-native'

const build = Platform.OS === 'ios' ? Constants.platform?.ios?.buildNumber : Constants.expoConfig?.android?.versionCode

startVitals({
  key: 'kfp_live_…',
  appVersion: Constants.expoConfig?.version ?? '0',
  build: build == null ? undefined : String(build),
  navigationRef, // React Navigation's createNavigationContainerRef() or expo-router's useNavigationContainerRef()
  storage: AsyncStorage, // optional: checkpoints, retries and the daily cap survive restarts
})

Nothing is measured or sent before startVitals. If your app asks for consent, call it after.

expo-constants rather than expo-application: the latter is a native module, and an EAS Update that adds it crashes every installed binary built without it. Without Expo, use react-native-device-info or your own constants.

Before your store release, declare it in the stores' privacy forms (App Store: Diagnostics > Performance Data; Google Play: Diagnostics) and add a sentence to your privacy policy: what to declare.

| Option | Default | What it does | | --- | --- | --- | | key | required | The project's field key | | appVersion | required | The version people see (2.4.1) | | build | none | The build number (812) | | environment | 'development' when __DEV__, else 'production' | Development reports are kept only when the project accepts development builds | | sampleRate | 0.1 | The share of sessions that report. Release builds use it until the project's settings arrive, then the project's rate. Development builds always use it, and report every session when you leave it out (no daily cap either: someone is testing) | | navigationRef | none | Screens are named from its routes | | screenName | the route's name | (route) => string, to name routes yourself (still masked) | | storage | none | Anything with getItem, setItem and removeItem (AsyncStorage, an MMKV wrapper) | | device | none | { model, memoryBytes, memoryGb, tier, displayHz }, read by the app (for example from expo-device) | | appId | none | The bundle id or package name | | endpoint | https://vitals.keyframer.dev | The ingest server | | debug | false | Logs what the SDK decides, measures and sends: the session and its sampling, frames a second per thread, each report against the server's limits. Lines are tagged [Keyframer.dev] and go through console.debug, so Metro shows them as DEBUG (a note for you, such as development builds being off, is INFO; a refused report is WARN). For development builds |

Call sites with file and line

Add the Babel plugin, beside Reanimated's (react-native-worklets') plugin, in any order:

// babel.config.js
module.exports = function (api) {
  api.cache(true)
  return {
    presets: ['babel-preset-expo'],
    plugins: ['@keyframerdev/vitals/babel'],
  }
}

It tags each Reanimated animation, layout animation and animated scroll handler with where it is written, so the dashboard shows app/feed.tsx:42:9 withSpring, not only the screen. Without it, frames are still counted per screen. Restart Metro with a clean cache after changing Babel: npx expo start -c.

To keep file paths out of the bundle, pass { hashSites: true, salt: 'kfp_live_…' } and upload the sites file the build writes with @keyframerdev/vitals-cli.

More

import { setVitalsEnabled, setVitalsScreen, VitalsRoot } from '@keyframerdev/vitals'

setVitalsScreen('Checkout') // where navigation is not automatic
setVitalsEnabled(false)     // stops now and drops what is pending; true starts again
<VitalsRoot>{app}</VitalsRoot> // optional: touches open motion windows, so plain lists are measured while they scroll

Docs: React Native setup, consent and privacy, store privacy answers.

License

MIT