Metro Guide

How to set up Tamagui 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 @tamagui/metro-plugin which loads your Tamagui config and watches for changes:

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

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

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

const config = getDefaultConfig(__dirname)

// reads from tamagui.build.ts automatically
module.exports = withTamagui(config)

Or pass options inline:

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

const config = getDefaultConfig(__dirname)

module.exports = withTamagui(config, {
  components: ['tamagui'],
  config: './tamagui.config.ts',
})

Optimized Production Builds

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

Terminal
# Optimize and build, then restore source files
tamagui 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": "tamagui 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 'tamagui'

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.

Webpack

Upgrading from v1 to v2

Edit this page on GitHub.