Expo Guide

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

This template requires Yarn 4.4.0 or greater. You can set yarn to the latest version by running yarn set version stable.

yarn create gui@latest --template expo-router

There are also pre-made community Expo starters.

Install

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

To support dark mode, update your app.json to app.config.ts and set userInterfaceStyle to "automatic".

Native

Create a new Expo project:

yarn dlx create-expo-app -t expo-template-blank-typescript

This guide assumes Expo is configured with TypeScript support.

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 add @hanzogui/babel-plugin

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

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

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

If you're using a monorepo you probably want to use this Metro configuration.

Expo Router / Web

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

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

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

export const guiConfig = createGui(defaultConfig)

export default guiConfig

export type Conf = typeof guiConfig

declare module '@hanzo/gui' {
  interface GuiCustomConfig extends Conf {}
}

Then update app/_layout.tsx:

import '../gui.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 { guiConfig } from '../gui.config'

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

  return (
    // add this
    <GuiProvider config={guiConfig} 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>
  )
}

Setup Hanzo GUI

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

Loading fonts

Install the expo-font package:

npx expo install expo-font

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

GuiExpo Google Fonts

Use the @hanzogui/font-inter package, a pre-configured version of the Inter font that works with Hanzo GUI:

Import the useFonts hook and load the fonts:

import { useFonts } from 'expo-font'

function App() {
  const [loaded] = useFonts({
    Inter: require('@hanzogui/font-inter/otf/Inter-Medium.otf'),
    InterBold: require('@hanzogui/font-inter/otf/Inter-Bold.otf'),
  })

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

  if (!loaded) {
    return null
  }

  return <MyApp />
}

Use the @expo-google-fonts package, a collection of Google Fonts that work with Expo:

You can find the full list of fonts and usage instructions in the Expo documentation.

Install the font package:

npx expo install @expo-google-fonts/inter

Import the useFonts hook and load the fonts:

import { useFonts, Inter_400Regular, Inter_900Black } from '@expo-google-fonts/inter'

function App() {
  const [loaded] = useFonts({
    Inter_400Regular,
    Inter_900Black,
  })

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

  if (!loaded) {
    return null
  }

  return <MyApp />
}

For more information on loading fonts in Expo, see the Expo documentation.

First time starting Expo

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

npx expo start -c

Your package.json scripts should look something like this:

{
  "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"
  }
}