Migration Guide

Reset example content

Run your chosen reset script:

npm run reset-template

This removes all example screens and leaves you with a clean app that has working navigation, theming, and i18n infrastructure.

Verify the reset

Run all validation checks to make sure nothing is broken:

npm run validate

This runs TypeScript type-checking, ESLint, and Prettier format verification. All checks should pass cleanly after a reset.

Update app identity

Update the app name, bundle identifier, and metadata in these files:

app.json — the primary Expo configuration:

{
  "expo": {
    "name": "My App Name",
    "slug": "my-app-name",
    "scheme": "myapp",
    "ios": {
      "bundleIdentifier": "com.mycompany.myapp"
    },
    "android": {
      "package": "com.mycompany.myapp"
    }
  }
}

package.json — update name, description, and version:

{
  "name": "my-app-name",
  "version": "0.1.0",
  "description": "My awesome mobile app"
}

Customize the theme

The theme is defined in two files — one for light mode, one for dark mode. Both use semantic tokens so you only need to change values in these two files to restyle the entire app.

To change the primary brand color, update brand.primary in both files:

// src/theme/light-theme.ts
brand: {
  primary: '#6366F1',         // Change this to your brand color
  primaryVariant: '#4F46E5',  // A darker shade
  secondary: '#1E293B',
  tertiary: '#14B8A6',        // Accent color
},

The theme tokens are organized into semantic groups: brand, background, text, border, icon, state, and overlay. See the Theme System documentation for the full token reference.

Configure i18n

Update the locale files with your app’s text:

• src/i18n/locales/en.json — English strings
• src/i18n/locales/ar.json — Arabic strings

Remove any keys from the template that you no longer need, and add your own. The structure is flat with dot-separated namespaces:

{
  "tabs": {
    "home": "Home",
    "settings": "Settings"
  },
  "home": {
    "title": "Welcome",
    "subtitle": "Get started with your app"
  }
}

If you do not need Arabic or RTL support, you can simplify the i18n configuration in src/i18n/config.ts, but the infrastructure is designed to make adding languages easy.

Set up your backend

Create a .env file from the example:

cp .env.example .env

For Supabase, add your credentials:

# .env
EXPO_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
EXPO_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
EXPO_PUBLIC_API_BASE_URL=https://api.your-app.com

Add navigation tabs

Open app/(main)/(tabs)/_layout.tsx and configure your tabs:

export default function TabLayout() {
  const { t } = useTranslation();
 
  return (
    <Tabs
      tabBar={(props) => <TabBar {...props} />}
      screenOptions={{ headerShown: false }}
    >
      <Tabs.Screen
        name="index"
        options={{ title: t('tabs.home') }}
      />
      <Tabs.Screen
        name="explore"
        options={{ title: t('tabs.explore') }}
      />
      <Tabs.Screen
        name="profile"
        options={{ title: t('tabs.profile') }}
      />
      <Tabs.Screen
        name="settings"
        options={{ title: t('tabs.settings') }}
      />
    </Tabs>
  );
}

Create the corresponding screen files in app/(main)/(tabs)/ for each tab. See the Creating a Screen guide for the full process.

Create your first feature

Follow the Creating a Feature guide to build your first feature module. The pattern is the same for every feature:

1. Define types in src/features/<name>/types/
2. Create API service in src/features/<name>/services/
3. Create React Query hooks in src/features/<name>/hooks/
4. Create screen in app/
5. Add i18n keys to both locale files

Configure EAS builds (optional)

For production builds and app store submissions, set up EAS Build :

# Install EAS CLI
npm install -g eas-cli
 
# Log in to your Expo account
eas login
 
# Configure the project
eas build:configure

This creates an eas.json with build profiles for development, preview, and production.