Runtime functions

A runtime function is a function that can be scheduled on a named runtime and awaited from somewhere else. Two shapes:

• call(fn).on(runtimeName)(...args) — the caller picks the runtime
• 'background' directive — the function always runs on the same runtime

Both compile to the same underlying mechanism: a registered function on the target runtime, called by stable id, with JSON-serialized arguments.

Caller picks the runtime

import { call, runtimeFunction } from '@react-native-runtimes/core';

export const fibonacci = runtimeFunction((n: number): number => {
  return n <= 1 ? n : fibonacci(n - 1) + fibonacci(n - 2);
});

const result = await call(fibonacci).on('worker-runtime')(38);

This is the right shape when the same function might be called from different runtimes, or against different worker pools.

Function pinned to one runtime

async function refreshCache(key: string) {
  'background';
  await cacheStore.hydrate();
  return cacheStore.getPathState(key);
}

const value = await refreshCache('settings');

The first directive ('background' or any other secondary runtime name) is the target. Metro rewrites the function into a registered runtime function plus a local scheduled alias, so call sites stay ordinary. Directives target secondary runtimes — to get data back to the main runtime, return a value or write to shared state.

How lookup works

1. Metro assigns each exported runtimeFunction(...) a stable id and registers it in the bundle.
2. Both runtimes load the same bundle, so they install the same registration table.
3. To call, native sends the target runtime name, the stable id, and JSON-stringified arguments.
4. The target runtime looks up the loader, caches the loaded JS function, calls it with parsed arguments, and serializes the return value back to the caller.

Code is never sent over the wire. Only id + args.

Constraints

• Arguments and return values must be JSON-serializable.
• runtimeFunction(...) values must be exported at module scope. Directive functions only need to be declared at module scope — Metro exports the generated registration for you.
• Closures aren't captured — pass everything through arguments (module-scope imports work, since every runtime loads the same bundle).
• Inline lambdas are not supported.

See Scheduling functions on another runtime for the full API.