Tamagui CLI

Installation

Install the CLI as a development dependency:

yarn add -D @tamagui/cli

Commands

build

Pre-compile Tamagui components in-place for production builds. This is useful for bundlers that don't have a Tamagui plugin yet (like Turbopack) or when you want a simple setup that works with any bundler.

# Build all components in a directory (web + native by default)
npx tamagui build ./src

# Build for web only
npx tamagui build --target web ./src

# Build for native only
npx tamagui build --target native ./src

# Build a specific file
npx tamagui build ./src/components/MyComponent.tsx

# Include/exclude patterns
npx tamagui build --include "components/**" --exclude "**/*.test.tsx" ./src

# Output to a separate directory (source files unchanged)
npx tamagui build --output ./dist ./src

# Create platform-specific files next to source files (.web.tsx or .native.tsx)
npx tamagui build --target native --output-around ./src

# Preview changes without writing files
npx tamagui build --dry-run ./src

Flags:

• --target <platform> - Target platform: web, native, or both (default: both)
• --include <pattern> - Glob pattern to include files
• --exclude <pattern> - Glob pattern to exclude files
• --output <path> - Output directory for optimized files (preserves directory structure). When specified, source files are not modified
• --output-around - Create platform-specific files (.web.tsx or .native.tsx) next to source files instead of modifying them. Errors if the file already exists
• --expect-optimizations <number> - Fail if fewer than this many components are optimized (useful for CI)
• --dry-run - Preview what would be optimized without writing any files
• --debug - Enable debug output
• --verbose - Enable verbose debug output

Platform-Specific File Handling:

The CLI automatically handles platform-specific files:

• Files with .web.tsx or .ios.tsx extensions are optimized for web only
• Files with .native.tsx or .android.tsx extensions are optimized for native only
• Base files (.tsx) without platform-specific versions are optimized for all platforms
• If both .web.tsx and .native.tsx exist, the base .tsx file is skipped

Configuration:

Create a tamagui.build.ts config file in your project root:

import type { TamaguiBuildOptions } from 'tamagui'

export default {
  config: './tamagui.config.ts',
  components: ['tamagui'],
  importsWhitelist: ['constants.js', 'colors.js'],
  outputCSS: './public/tamagui.generated.css',
} satisfies TamaguiBuildOptions

Integration Examples:

The CLI can wrap your build command using --, which optimizes files beforehand and automatically restores them after:

{
  "scripts": {
    "build": "tamagui build --target web ./src -- next build"
  }
}

The -- separator tells the CLI to run next build after optimization, then restore your source files automatically. This is the recommended approach as it keeps your source files unchanged.

Alternatively, run tamagui build separately (files will remain modified):

{
  "scripts": {
    "build": "tamagui build --target web ./src && next build"
  }
}

Important: Without the -- wrapper, files are modified in-place and not restored. Only use this approach if you're building in a CI environment where the files are discarded anyway.

Alternatively, use --output to write optimized files to a separate directory:

{
  "scripts": {
    "build": "tamagui build --target web --output ./dist ./src && next build"
  }
}

With --output, source files are never modified and no restoration is needed.

For more details, see the Compiler Installation guide.

check

Check your dependencies for inconsistent versions across your project. This helps identify version mismatches that can cause issues, especially in monorepos.

npx tamagui check

Flags:

• --debug - Enable debug output
• --verbose - Enable verbose debug output

Example output:

The command will scan your project and report any packages with mismatched versions, helping you maintain consistency across your dependencies.

generate

Build your entire Tamagui configuration and output CSS. This is useful for pre-generating your design system's CSS and validating your configuration.

npx tamagui generate

Flags:

• --debug - Enable debug output
• --verbose - Enable verbose debug output

What it does:

1. Loads and validates your Tamagui configuration
2. Generates CSS for all your tokens, themes, and components
3. Outputs to the .tamagui directory
4. Also generates an LLM-friendly prompt file at .tamagui/prompt.md

generate-css

Generate the tamagui.generated.css file from your configuration. Useful for build pipelines or when you need to regenerate CSS without running a full build.

npx tamagui generate-css

Flags:

• --output <path> - Custom output path (default: tamagui.generated.css)
• --debug - Enable debug output
• --verbose - Enable verbose debug output

Example:

npx tamagui generate-css --output ./public/styles/tamagui.generated.css

generate-themes

Pre-build your theme configuration for faster runtime performance. This generates optimized theme objects from your theme definitions.

npx tamagui generate-themes <input-path> <output-path>

Example:

npx tamagui generate-themes ./themes/input.ts ./themes/generated.ts

Flags:

• --debug - Enable debug output
• --verbose - Enable verbose debug output

Use case: If you have complex theme generation logic, this command pre-computes your themes at build time rather than runtime.

add

Add pre-configured fonts and icons from Tamagui's curated collections. This includes Google Fonts and Iconify icon packs.

# Add a font
npx tamagui add font [packages-path]

# Add an icon pack
npx tamagui add icon [packages-path]

Flags:

• --debug - Enable debug output
• --verbose - Enable verbose debug output

Interactive selection:

The command will present an interactive menu where you can search and select from available fonts or icons:

• Fonts: Browse Google Fonts with weight, style, and subset information
• Icons: Browse Iconify collections with icon counts and license information

Default path: If you don't provide a path, packages are installed to ./packages in your current directory.

Requirements: This feature requires Tamagui Pro membership for access to the font and icon repositories.

generate-prompt

Generate an LLM-friendly markdown file from your Tamagui configuration. This creates comprehensive documentation of your design system for use with AI assistants.

npx tamagui generate-prompt

Flags:

• --output <path> - Custom output path (default: .tamagui/prompt.md)
• --debug - Enable debug output

What it includes:

• All your tokens (colors, sizes, space, etc.)
• Theme definitions and variants
• Component configurations
• Font families and configurations
• Media queries and breakpoints

Use case: Share this file with AI assistants like Claude or ChatGPT to get better suggestions that align with your design system.

Global Flags

All commands support these flags:

• --help - Show help for the command
• --version - Show CLI version
• --debug - Enable debug output
• --verbose - Enable verbose debug output (more detailed than --debug)

Examples

Production Build Pipeline

{
  "scripts": {
    "build": "tamagui check && tamagui build --target web ./src -- next build"
  }
}

CI with Optimization Verification

{
  "scripts": {
    "build": "tamagui build --target web --expect-optimizations 10 ./src -- next build"
  }
}

This fails the build if fewer than 10 components are optimized, helping catch configuration issues in CI.

Cross-Platform Mobile App

{
  "scripts": {
    "build:ios": "tamagui build --target native ./src -- eas build --platform ios",
    "build:android": "tamagui build --target native ./src -- eas build --platform android",
    "build:web": "tamagui build --target web ./src -- vite build"
  }
}

Troubleshooting

Build command fails with "cannot find module"

Make sure you have a tamagui.build.ts config file that correctly points to your configuration:

export default {
  config: './tamagui.config.ts', // Verify this path is correct
  components: ['tamagui'],
}

Check command reports false positives

The check command is strict about version consistency. If you have a specific reason for version mismatches (like testing), you can document them in your README.

Add command shows "Repository not found"

The add command requires Tamagui Takeout access. Visit tamagui.dev/takeout to learn more.