Metro Guide

How to set up Tamagui with Metro

If you're using a monorepo, you probably want to use this Metro configuration in your metro.config.js:

metro.config.js
// Learn more https://docs.expo.io/guides/customizing-metro
const { getDefaultConfig } = require('expo/metro-config')

/** @type {import('expo/metro-config').MetroConfig} */
const config = getDefaultConfig(__dirname, {
  // [Web-only]: Enables CSS support in Metro.
  isCSSEnabled: true,
})

// Expo 49 issue: default metro config needs to include "mjs"
// https://github.com/expo/expo/issues/23180
config.resolver.sourceExts.push('mjs')

module.exports = config

Web support

Early support for Metro web support is here.

First install @tamagui/metro-plugin:


yarn add tamagui @tamagui/config @tamagui/metro-plugin

Then adjust your metro.config.js:

metro.config.js
// Learn more https://docs.expo.io/guides/customizing-metro
const { getDefaultConfig } = require('expo/metro-config')

/** @type {import('expo/metro-config').MetroConfig} */
const config = getDefaultConfig(__dirname, {
  // [Web-only]: Enables CSS support in Metro.
  isCSSEnabled: true,
})

// add nice web support with optimizing compiler + CSS extraction
const { withTamagui } = require('@tamagui/metro-plugin')
module.exports = withTamagui(config, {
  components: ['tamagui'],
  config: './tamagui.config.ts',
  outputCSS: './tamagui-web.css',
  cssInterop: true,
})

Options

cssInterop

When cssInterop: true is set, the compiler writes CSS to .tamagui/css/ files and imports them via require(), letting Metro handle CSS bundling natively. This enables component flattening (View → div) for better performance.

When cssInterop: false (default), CSS is injected inline via JavaScript at runtime. This is simpler but doesn't support flattening.

module.exports = withTamagui(config, {
  components: ['tamagui'],
  config: './tamagui.config.ts',
  outputCSS: './tamagui-web.css',
  cssInterop: true, // enables CSS file output + flattening
})

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.

If you're using Metro as your web bundler, you have to turn isCSSEnabled on. See Expo's docs .

Webpack

create-tamagui

Edit this page on GitHub.