Extending

The app's navigators refer to screens by a stable screen id, and a registry resolves each id to the app's own screen, a build's replacement, or a selected variant. A build changes screens from brand/storefront.extensions.ts without touching the navigators, so it keeps taking new releases as a plain merge.

Replacements are ordinary modules compiled into the build. The app never downloads or runs code from an API; configuration can only select variants that are already compiled in.

Replacing a screen

import React from 'react';
import { YStack } from 'tamagui';
import type { StorefrontScreen } from '../../src/extensions';
import { UIText } from '../../src/ui';

const HomeScreen: StorefrontScreen<'store.home'> = ({ route, navigation, DefaultScreen }) => (
    <YStack flex={1}>
        <UIText variant='title'>Welcome</UIText>
        {/* Optional: reuse the app's own screen below yours */}
        <DefaultScreen route={route} navigation={navigation} />
    </YStack>
);

export default HomeScreen;

// brand/storefront.extensions.ts
import { defineStorefrontExtensions } from '../src/extensions';

export default defineStorefrontExtensions({
    screens: {
        'store.home': { load: () => import('./screens/HomeScreen') },
    },
});

Routes, deep links, sign-in guards and headers stay as they were. HomeScreen.web.tsx and HomeScreen.native.tsx work as usual, and platforms: ['ios', 'android'] applies a replacement on some platforms only.

Variants

A replacement (or the app itself) can offer named variants, chosen in the brand file:

// brand/storefront.extensions.ts
screens: {
    'store.home': {
        load: () => import('./screens/HomeScreen'),
        variants: { editorial: () => import('./screens/EditorialHomeScreen') },
    },
},

// brand/storefront.brand.ts
screens: { 'store.home': { variant: 'editorial' } },

The app's built-in variants are chosen the same way, for example the Network shop home: screens: { 'network.home': { variant: 'shop' } }. An unknown variant falls back to the replacement, or to the app's screen.

Adding screens and tabs

import { defineStorefrontExtensions } from '../src/extensions';
import { faGift } from '@fortawesome/free-solid-svg-icons';

export default defineStorefrontExtensions({
    routes: {
        Rewards: { load: () => import('./screens/RewardsScreen'), path: 'rewards' },
        RewardDetail: { load: () => import('./screens/RewardDetailScreen'), path: 'rewards/:rewardId', presentation: 'modal' },
    },
    tabs: {
        RewardsTab: { initialRoute: 'Rewards', icon: faGift, labelKey: 'Brand.tabs.rewards', editions: ['store'] },
    },
});

Routes

• Each route is added to every stack of its editions (editions, both by default), so navigation.navigate('RewardDetail', { rewardId }) works from any screen and opens in the current tab.
• Names are PascalCase. A name that matches one of the app's routes is skipped with a warning; replace app screens with screens instead.
• path makes the route deep-linkable. presentation: 'modal' presents it over the current screen.
• A route that fails to load or throws shows an error view in its place instead of crashing the app.

Tabs

• A tab opens one of your routes (initialRoute). Its stack also has every custom route and the edition's shared screens (products, offers, locations; in a Network also stores, categories, reviews and notifications).
• icon is a FontAwesome icon or a function ({ color, size, focused }) => ReactNode. labelKey is a translation key; label is plain text or { en: 'Rewards', mn: '…' }.
• Place it with navigation.store.tabs or navigation.network.tabs in the brand file; otherwise it goes at position, or just before Cart. initial: true opens the app on it.

Copy

brand/translations/<locale>.json is merged over the app's translations: change any string, or add keys for your own screens (for example under a Brand namespace). A file for a language the app doesn't ship adds it; offer it with AVAILABLE_LOCALES.

What your screens can use

Client screens may rely on:

• src/extensions: types, defineStorefrontExtensions, screen ids and their params
• src/ui: the app's components, tokens and display helpers
• src/branding: defineBranding, useBranding
• the hooks use-cart, use-cart-summary, use-storefront, use-current-location, use-food-trucks, use-store-locations, use-customer-coordinates, and useStorefrontRuntime, useLanguage, useAuth

Breaking changes to these, to screen ids and params, and to branding options are listed in the release notes. Anything else in src/ may change between releases. Replacements are typed (StorefrontScreen<'store.home'>), so a type check after a merge points at what needs updating.

When something fails

• A replacement that fails to load, has no default export or throws while rendering is swapped for the app's own screen, and the error is logged.
• If that fails too, a "Something went wrong" view is shown.
• In development, unknown screen ids and malformed entries stop the app at start so you notice; in release builds they are skipped with a warning.

Screen ids

The boot, location permission, payment gateway, phone verification and account deletion screens can't be replaced.