Metro Guide

How to set up Tamagui with Metro

Expo’s default Metro configuration runs Tamagui directly, with an optional plugin for config loading and CSS extraction.

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 the Metro plugin, which loads your Tamagui config and watches for changes. It ships inside @tamagui/cli along with the CLI and the other bundler integrations:

yarnnpmbunpnpm
yarn add -D @tamagui/cli

If Metro is the only bundler this project will ever use, yarn add @tamagui/metro-plugin on its own is a smaller install and exports exactly the same things.

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/cli/metro')

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/cli/metro')

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 to v3

Edit this page on GitHub.