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 add @tamagui/metro-plugin

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',
})

CSS Generation

For web, Tamagui outputs CSS containing your themes and tokens. Create a tamagui.build.ts in your project root:

tamagui.build.ts
import type { TamaguiBuildOptions } from 'tamagui'

export default {
  components: ['tamagui'],
  config: './tamagui.config.ts',
  outputCSS: './tamagui-web.css',
} satisfies TamaguiBuildOptions

Then import the CSS in your app's layout:

app/_layout.tsx
import '../tamagui-web.css'
// ... rest of your layout

In development, the CSS is generated automatically when Tamagui loads your config. For production builds, run:

Terminal
tamagui generate

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

create-tamagui

Edit this page on GitHub.