Tamagui CLI

The Tamagui CLI provides a suite of command-line tools for optimizing components, managing dependencies, adding fonts and icons, and more.

Installation

Install the CLI as a development dependency:

yarn
npm
bun
pnpm
yarn add -D @tamagui/cli

Commands

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.

Terminal
# 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

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
• --expect-optimizations <number> - Fail if fewer than this minimum number of components are optimized (useful for CI)
• --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.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.

For more details, see the Compiler Installation guide.

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

yarn
npm
bun
pnpm
yarn dlx 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.

Builds your entire Tamagui configuration and outputs any CSS. This is useful for pre-generating your design system's CSS and validating your configuration.

yarn
npm
bun
pnpm
yarn dlx 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

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

yarn
npm
bun
pnpm
yarn dlx tamagui generate-themes <input-path> <output-path>

Example:

yarn
npm
bun
pnpm
yarn dlx 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 pre-configured fonts and icons from Tamagui's curated collections. This includes Google Fonts and Iconify icon packs.

Terminal
# 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 an LLM-friendly markdown file from your Tamagui configuration. This creates comprehensive documentation of your design system that can be used with AI assistants.

yarn
npm
bun
pnpm
yarn dlx 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

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

{
  "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.

{
  "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

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

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.

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