Tamagui CLI

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

Just starting out? Skim this section, the CLI is not necessary to get going.

Installation

Install the CLI as a development dependency:

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

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"
  }
}
Copy

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"
  }
}
Copy

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"
  }
}
Copy

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

For more details, see the Compiler Installation guide.

Check flat style values, inconsistent versions, duplicate installs, lockfile issues, and missing config:

yarn
npm
bun
pnpm
Copy
yarn dlx tamagui check

Flags:

• --strict: Validate conditional style payloads against the project config too
• --styles-only: Skip the dependency checks
• --deps-only: Skip the style checks
• --debug: Enable debug output
• --verbose: Enable verbose debug output

The command exits non-zero when it finds diagnostics, so it works as a CI gate.

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

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

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.

yarn
npm
bun
pnpm
Copy
yarn dlx tamagui generate-css

Flags:

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

Example:

yarn
npm
bun
pnpm
Copy
yarn dlx tamagui generate-css --output ./public/styles/tamagui.generated.css

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

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

Example:

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

Generate typed, themed SVG icon components for only the icons you use. Each icon becomes one file, and index.ts in the output folder exports all of them. Running it again adds to the folder and rewrites the index.

Terminal
Copy
# lucide (the default source)
npx @tamagui/cli@beta icons add Search ChevronDown X

# phosphor, with a weight: regular, bold, duotone, fill, light, thin
npx @tamagui/cli@beta icons add Copy --from phosphor --weight bold

# heroicons, with a variant: outline, solid, mini, micro
npx @tamagui/cli@beta icons add Clipboard --from heroicons --variant solid

# your own svg files, looked up as <kebab-name>.svg
npx @tamagui/cli@beta icons add Logo --from ./assets/icons

Flags:

• --from: lucide (default), heroicons, phosphor, or a folder of svg files
• --weight: Phosphor weight
• --variant: Heroicons variant
• --out: Output folder (default: components/icons)

Names are PascalCase (ChevronDown) or the source’s kebab-case file name (chevron-down). Name=source-name keeps your component name while drawing a different source icon, so a set can move between libraries without changing its imports: icons add Search=magnifying-glass --from phosphor. Library versions are pinned per CLI release. The generated components need react-native-svg and @tamagui/helpers-icon. See Lucide Icons for usage.

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

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

Print an agent brief for migrating an existing app to v3.

yarn
npm
bun
pnpm
Copy
yarn dlx tamagui migrate --from v2
npx tamagui migrate --from v1

--from v1 sequences the v1-to-v2 pass ahead of the v2-to-v3 one. The brief is the checklist of record for the upgrade: dependency updates, the config and theme moves, the flat-values codemod, the Sheet codemod, and every deprecated API with its before and after. The prose version is the upgrade guide.

Print an agent brief for adding Tamagui to a project that does not use it yet.

yarn
npm
bun
pnpm
Copy
yarn dlx tamagui setup

It covers the version baseline, a pinned install, the config and provider, the right bundler adapter, and the flat-value style grammar, and it ends by making the agent verify with tamagui check and a real run rather than a typecheck.

Pair it with migrate for projects already on v1 or v2, or copy the setup prompt directly:

Upgrade all Tamagui packages in your workspace to the latest version:

yarn
npm
bun
pnpm
Copy
yarn dlx tamagui upgrade

Flags:

• --from <version>: Lower bound of the upgrade range
• --to <version>: Upper bound of the upgrade range
• --dry-run: Preview changes without writing files
• --changelog-only: Print the changelog without changing files
• --debug: Enable debug output

Convert Tamagui JSX props in files or globs to Tailwind className syntax:

yarn
npm
bun
pnpm
Copy
yarn dlx tamagui to-tailwind ./src

Flags:

• --write: Write changes to files (default prints a diff)
• --config <path>: Resolve tokens against your Tamagui config (required with --write, or pass --use-default-config)
• --rename-dom: Rename View to div and other DOM equivalents

Generate an LLM-friendly markdown file documenting your design system for AI assistants.

yarn
npm
bun
pnpm
Copy
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"
  }
}
Copy

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

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"
  }
}
Copy

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

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.