Metro Guide

How to set up Gui with Metro

Basic Setup

The default Expo Metro configuration works out of the box:

metro.config.js
const { getDefaultConfig } = require('expo/metro-config')

module.exports = getDefaultConfig(__dirname)

With Metro Plugin (Recommended)

For better dev experience, use @hanzogui/metro-plugin which loads your Gui config and watches for changes:

yarn
npm
bun
pnpm
yarn add @hanzogui/metro-plugin

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

metro.config.js
const { getDefaultConfig } = require('expo/metro-config')
const { withGui } = require('@hanzogui/metro-plugin')

const config = getDefaultConfig(__dirname)

// reads from hanzogui.build.ts automatically
module.exports = withGui(config)

Or pass options inline:

metro.config.js
const { getDefaultConfig } = require('expo/metro-config')
const { withGui } = require('@hanzogui/metro-plugin')

const config = getDefaultConfig(__dirname)

module.exports = withGui(config, {
  components: ['@hanzo/gui'],
  config: './hanzogui.config.ts',
})

Optimized Production Builds

For maximum optimization, use the hanzogui build command which pre-compiles your components:

Terminal
# Optimize and build, then restore source files
hanzogui build --target web ./app -- expo export --platform web

The -- syntax runs the command after optimization, then automatically restores your source files. Add this to your package.json:

{
  "scripts": {
    "build:web": "expo export --platform web",
    "build:web:optimized": "hanzogui build --target web ./app -- expo export --platform web"
  }
}

Debugging

To debug the compiler output, add // debug at the top of a file:

// debug
import { YStack } from '@hanzo/gui'

export function MyComponent() {
  return <YStack flex={1} bg="$background" />
}

This will print detailed compiler output showing what optimizations are happening:

[✅] flattened YStack div

Use // debug-verbose for even more detailed output.

One

Upgrading from v1 to v2

Edit this page on GitHub.