Installation

Requirements#

1. Install the packages#

npx expo install react-native-webgpu react-native-reanimated react-native-worklets expo-asset expo-file-system react-native-gesture-handler
npm install [email protected]
npm install @apricot/react @apricot/assets @apricot/core
npm install --save-dev @apricot/metro

Versions the Apricot playground is tested with: expo 57.0.27, react-native 0.86.3, react 19.2.3, react-native-webgpu 0.12.1, three 0.186.1, react-native-reanimated 4.5.1, react-native-worklets 0.10.1, react-native-gesture-handler 2.32.0.

2. Add the config plugin#

The plugin applies react-native-webgpu's own plugin, sets Android minSdkVersion to at least 26, and lets iOS ProMotion screens run at 120 Hz.

module.exports = {
  expo: {
    name: "My App",
    slug: "my-app",
    plugins: ["@apricot/react"],
  },
};

With app.json, add "@apricot/react" to expo.plugins the same way.

3. Configure Metro#

withApricot makes Metro bundle .glb and .gltf files as assets, and resolves every three import to the WebGPU build so the bundle holds one copy of three.

const { getDefaultConfig } = require("expo/metro-config");
const { withApricot } = require("@apricot/metro");

module.exports = withApricot(getDefaultConfig(__dirname));

4. Wrap the app for gestures#

If you use gestures (the recipes do), wrap the root of the app once:

import { Stack } from "expo-router";
import { GestureHandlerRootView } from "react-native-gesture-handler";

export default function Layout() {
  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      <Stack />
    </GestureHandlerRootView>
  );
}

No Babel changes are needed: babel-preset-expo already includes the Reanimated / worklets plugin.

5. Build and run#

Native code changed, so build a development client:

npx expo prebuild
npx expo run:ios      # or: npx expo run:android

Then start Metro for later JavaScript changes:

npx expo start --dev-client

6. Check it works#

Render a scene on any screen:

import { Box, Scene, Spin } from "@apricot/react";

export default function Home() {
  return (
    <Scene style={{ flex: 1 }} debug>
      <Spin speed={1}>
        <Box size={1.6} color="#ff9f59" />
      </Spin>
    </Scene>
  );
}

You should see an orange cube turning on a cream background, and debug adds a small HUD with fps, render and present times. The first second shows only the background while shaders compile: that is expected (see Scenes).

If something fails, see Troubleshooting.

Next#

• Quick start: build a scene step by step.
• Building with AI: rules for AI assistants writing Apricot code.