Installation

Stratum requires Expo SDK 52+, React Native 0.78+ (New Architecture), and a dev client build — it does not work in Expo Go because Unistyles requires native modules.

Prerequisites

• Node.js 18+
• A new or existing Expo project with the New Architecture enabled
• A dev client build (run via expo run:ios or expo run:android)

If you don’t have an Expo project yet:

npx create-expo-app MyApp --template blank-typescript
cd MyApp

Enable New Architecture in app.json:

{
  "expo": {
    "newArchEnabled": true
  }
}

Install dependencies

Stratum’s components depend on three packages:

npx expo install react-native-unistyles phosphor-react-native react-native-nitro-modules

• react-native-unistyles — the styling engine (zero re-renders on theme switch)
• phosphor-react-native — the icon library used by <Icon> and <IconButton>
• react-native-nitro-modules — required by Unistyles 3.x (native module bridge)

Add Stratum files

CLI coming in Phase 7

A CLI (npx stratum init + npx stratum add) is planned for Phase 7. For now, copy files manually or clone the repo and copy the src/ directory.

Copy the following directories from the Stratum repo into your project:

src/tokens/          →  your-app/src/tokens/
src/providers/       →  your-app/src/providers/
src/hooks/           →  your-app/src/hooks/
src/components/      →  your-app/src/components/

Configure path aliases

Add @/ aliases to tsconfig.json:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

And to babel.config.js:

module.exports = {
  presets: ['babel-preset-expo'],
  plugins: [
    ['module-resolver', {
      root: ['./'],
      alias: { '@': './src' },
    }],
  ],
};

Install the babel plugin if not already present:

npm install --save-dev babel-plugin-module-resolver

Wrap your app

In your root layout (e.g. app/_layout.tsx with expo-router, or App.tsx):

import '@/providers/unistyles'; // must be imported before ThemeProvider
import { ThemeProvider } from '@/providers/ThemeProvider';

export default function RootLayout() {
  return (
    <ThemeProvider initialTheme="slate" initialColorScheme="light">
      {/* your navigator */}
    </ThemeProvider>
  );
}

Build and run

npx expo run:ios
npx expo run:android

Expo Go will not work — you need a dev client build because Unistyles requires compiled native modules.

Next: Quick Start

See Quick Start to add your first component.