Expo Guide

We’ve created a new template repo for starting an Expo Router app based on the Expo starter repo.

yarn
npm
bun
pnpm
yarn create hanzogui@latest --template expo-router
Copy

There are also pre-made community Expo starters.

Install

Use this guide to set up Gui with Expo Native and Web.

Create a new Expo  project:

yarn
npm
bun
pnpm
yarn dlx create-expo-app -t expo-template-blank-typescript
Copy

The following steps are optional but useful for many apps. They enable the optimizing compiler, Reanimated, and support for process.env.XYZ environment variables.

Add @hanzogui/babel-plugin:

yarn
npm
bun
pnpm
yarn add @hanzogui/babel-plugin
Copy

If you have a hanzogui.build.ts (recommended — see compiler install docs), no options are needed:

Update your babel.config.js to include the optional @hanzogui/babel-plugin:

babel.config.js
module.exports = function (api) {
  api.cache(true)
  return {
    presets: ['babel-preset-expo'],
    plugins: ['@hanzogui/babel-plugin'],
  }
}
Copy

• First, follow the Metro configuration guide to enable web support.

Add @hanzogui/config and hanzogui to your package.json and install them. Then create a hanzogui.config.ts:

hanzogui.config.ts
import { defaultConfig } from '@hanzogui/config/v5'
import { createGui } from '@hanzo/gui'

export const hanzoguiConfig = createGui(defaultConfig)

export default hanzoguiConfig

export type Conf = typeof hanzoguiConfig

declare module 'hanzogui' {
  interface GuiCustomConfig extends Conf {}
}
Copy

Then update app/_layout.tsx:

app/_layout.tsx
import '../hanzogui.generated.css'

import { DarkTheme, DefaultTheme, ThemeProvider } from '@react-navigation/native'
import { Stack } from 'expo-router'
import { useColorScheme } from 'react-native'
import { GuiProvider } from '@hanzo/gui'

import { hanzoguiConfig } from '../hanzogui.config'

export default function RootLayout() {
  const colorScheme = useColorScheme()

  return (
    // add this
    <GuiProvider config={hanzoguiConfig} defaultTheme={colorScheme!}>
      <ThemeProvider value={colorScheme === 'dark' ? DarkTheme : DefaultTheme}>
        <Stack>
          <Stack.Screen name="(tabs)" options={{ headerShown: false }} />
          <Stack.Screen name="modal" options={{ presentation: 'modal' }} />
        </Stack>
      </ThemeProvider>
    </GuiProvider>
  )
}
Copy

From here on out you can follow the Installation and Configuration docs.

Loading fonts

Install the expo-font package:

yarn
npm
bun
pnpm
yarn dlx expo install expo-font
Copy

Load your fonts so React Native can recognize them. There are several ways to do this:

App.tsx
import { useFonts } from 'expo-font'

function App() {
  const [loaded] = useFonts({
    Zen: require('@hanzo/font/dist/fonts/zen-sans/Zen-Medium.ttf'),
    ZenBold: require('@hanzo/font/dist/fonts/zen-sans/Zen-Bold.ttf'),
  })

  useEffect(() => {
    if (loaded) {
      // can hide splash screen here
    }
  }, [loaded])

  if (!loaded) {
    return null
  }

  return <MyApp />
}
Copy

First time starting Expo

The first time running your project with Gui, be sure to clear the cache:

yarn
npm
bun
pnpm
yarn dlx expo start -c
Copy

Your package.json scripts should look something like this:

package.json
{
  "scripts": {
    "start-native": "expo start -c",
    "start-web": "expo start -c",
    "android": "yarn expo run:android",
    "ios": "yarn expo run:ios",
    "web": "expo start --web"
  }
}
Copy