Metro setup

The Metro plugin scans your source files for threaded components, scheduled runtime functions, and runtime-specific bootstrap files, then writes a small generated entry that secondary runtimes load.

const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config');
const { withThreadedRuntime } = require('@react-native-runtimes/core/metro');

const config = {};

module.exports = withThreadedRuntime(
  mergeConfig(getDefaultConfig(__dirname), config),
);

Options

Loading the generated entry

The generated entry registers component loaders, runtime functions, and the ThreadedRuntimeHost root. Require it at the top of index.js so it runs in every runtime:

require('./.threaded-runtime/entry');

Component registrations are lazy (() => require(...)), so this adds nothing to main-runtime startup. Loading it on main is required for the JSI function dispatch mechanism, which enables calling functions on secondary runtimes.

.gitignore

Always exclude the generated folder from version control:

.threaded-runtime/

Per-runtime bootstrap files

For startup code that should only run on a specific runtime, create a root-level file with the runtime's name:

index.background.ts

The Metro plugin discovers files matching index.<runtime>.ts in the project root and emits a static conditional require. The generated entry loads index.background.ts only inside runtimes whose name or kind is background.

import { registerThreadedHeadlessTask } from '@react-native-runtimes/core';
import { business } from './src/businessStore';

registerThreadedHeadlessTask<{ reason: string }>(
  'business:refresh',
  async ({ payload }) => {
    await business.hydrate();
    await business.update(state => ({
      ...state,
      lastRefreshReason: payload.reason,
      refreshCount: state.refreshCount + 1,
    }));
  },
);

void business.hydrate();

The file suffix must match the runtime name used at the native side. If your native prewarm uses a different name, use that name as the suffix:

ThreadedRuntime.prewarmBusinessRuntime(applicationContext, "sync-engine")

index.sync-engine.ts

Troubleshooting