Tamagui（tamagui/tamagui）

Bun モノレポ · @tamagui/core · @tamagui/static · tamagui UI — Web と React Native でコードを共有

1 — 概要

位置づけ

Tamagui は、React と React Native の両方で動くスタイルライブラリ・デザインシステム・コンポーネント群の集合体。Web とネイティブで UI コードを共有しつつ、パフォーマンスと型・DX を維持することを目的とする（README および公式ドキュメントの説明に基づく）。

ランタイムの styled() とテーマトークンに加え、最適化コンパイラがビルド時に styled コンポーネントを Web では atomic CSS 付きの div、ネイティブではスタイルオブジェクトをホイストした View へ平坦化する。公式サイトの Hero セクションでは、コンパイラ有効時に Lighthouse スコアが約 15% 改善した例が示されている。

core@tamagui/core

static@tamagui/static

tamaguiUI キット

bunpackageManager

段階的導入: コンパイラなしでも View / Text と styled() だけから始められ、後から Vite・Metro・Next 用プラグインを足せる。

2 — 3 層スタック

公開パッケージの役割

@tamagui/core + @tamagui/static（任意） → tamagui

パッケージ	役割	典型的な利用
`@tamagui/core`	プラットフォーム横断のスタイル・テーマ・`styled()`・variants	デザイントークンと低レベル View / Text
`@tamagui/static`	extract コンパイラ本体。Bundler プラグイン経由で利用	本番ビルドでのスタイル抽出・コンポーネント平坦化
`tamagui`	`core` のスーパーセット。Button・Sheet・Dialog 等の UI	アプリ UI の大半。コード生成も `tamagui` 経由が一般的

スタイルの書き方（2 パターン）

インライン props と styled() + variants の両方をサポートする（library 内ドキュメントより）。

import { View, Text, styled } from 'tamagui'

export default () => (
  <>
    <View backgroundColor="red" />
    <Text fontSize={16} color="$color" />
  </>
)

const Card = styled(View, {
  borderRadius: 12,
  variants: {
    size: {
      sm: { padding: 8 },
      lg: { padding: 20 },
    },
  } as const,
})

variants では boolean・文字列キー・'...size' のようなトークン spread など、型安全な条件スタイルを 1 コンポーネントに集約できる。

3 — リポジトリ構成

モノレポの骨格

ルート package.json の workspaces が code/ 配下を束ねる。Turbo が build / test をオーケストレーションし、Bun が install とスクリプト実行の基盤になる。

flowchart TB
  subgraph root["tamagui/tamagui ルート"]
    SCR[scripts/]
    LIB[library/]
  end
  subgraph code["code/"]
    CORE[core/ — スタイル・テーマ・RN 基盤]
    COMP[compiler/ — static, vite, metro, next]
    UI[ui/ — Button, Sheet, Dialog 等]
    PKG[packages/ — build, lucide, starters 補助]
    DEV[tamagui.dev — 公式サイト]
    KS[kitchen-sink — 統合テスト]
    DEM[demos/]
    ST[starters/]
  end
  root --> code
  CORE --> COMP
  CORE --> UI
  UI --> DEV
  KS --> UI

code/core/     # config, themes, web, animations, font, cli …
code/compiler/ # static, vite-plugin, metro-plugin, next-plugin
code/ui/       # コンポーネントキット（accordion, dialog, sheet …）
code/packages/ # build, lucide-icons, native-ci, starters 補助
code/tamagui.dev/ # tamagui.dev サイトと docs データ
code/kitchen-sink/ # Playwright 統合・usecases
code/demos/    # コンポーネントデモ
code/starters/ # create-tamagui 系テンプレート

領域	主な責務
`code/core`	テーマ生成（v3–v5）、config、shorthands、アニメーション driver、Floating 等
`code/compiler`	AST 抽出、クラス名生成、Vite / Metro / Next / loader 連携
`code/ui`	ヘッドレス寄り〜高レベル UI。kitchen-sink と demos で検証
`code/tamagui.dev`	ドキュメントサイト。docs データは `code/tamagui.dev/data/docs/`

4 — 最適化コンパイラ

ビルド時 extract

@tamagui/static は単体では使わず、@tamagui/vite-plugin・@tamagui/babel-plugin（Metro）・@tamagui/next-plugin などのバンドラ統合経由で有効化する（library/tamagui.mdx）。

flowchart LR
  SRC[styled コンポーネント TSX]
  EXT[static extractor]
  WEB[Web: div + atomic CSS]
  NAT[Native: View + hoisted styles]
  SRC --> EXT
  EXT --> WEB
  EXT --> NAT

複雑なロジックやクロスモジュール import を含む styled でも、多くが単純な DOM / View に平坦化される
コンパイル時とランタイムの両方で動作。段階的に extract 範囲を広げられる
開発時は TAMAGUI_EXTRACT=1 付きの dev:extract で extract 挙動を確認可能（ルート scripts）

パッケージ変更時: ルートで bun run watch を回すか、変更したパッケージディレクトリで bun run build しないと downstream が古いビルドを参照する（CONTRIBUTING / claude.md）。

5 — 開発と CI

ルート scripts（抜粋）

コマンド	用途
`bun install`	postinstall で monorepo セットアップ
`bun run build`	turbo run build（全 workspace）
`bun run watch`	TS + パッケージの並列 watch（長時間デバッグ向け）
`bun run dev`	tamagui.dev 開発サーバ
`bun run check`	deps / unused / tamagui check / references
`bun run ci`	install → check → lint → typecheck → build → test
`bun run test:web` / `test:native`	プラットフォーム別テスト（turbo）
`npm create tamagui@latest`	スターター生成（README 推奨）

品質ゲートは manypkg・knip・oxfmt / oxlint・独自 check:references などが組み合わさる。React 19.1 / RN 0.83 系にピン留めされた overrides がルートにある。

6 — UI キットとテスト

kitchen-sink

code/kitchen-sink がコンポーネント統合テストの中心。Web は bun run start:web（既定ポート 7979）で起動し、Playwright が複数アニメーション driver（css / native / reanimated / motion）に対して走る（claude.md）。

テスト種別	ファイル命名	実行回数
通常	`ComponentName.test.tsx`	既定 driver で 1 回
アニメーション依存	`ComponentName.animated.test.tsx`	全 driver で繰り返し

ブラウザ確認: ?test=SelectFocusScopeCase（usecases 名）や ?demo=Select（demos の Demo 名から Demo を除いたもの）。

周辺プロダクト（ルート scripts より）

kitchen-sink — クロスプラットフォーム検証アプリ
starter / create — 学習用〜本番向け monorepo テンプレート
takeout / studio — 商用テンプレ・スタジオ系（@tamagui スコープ）
sandbox — 実験用サンドボックス

7 — 導入

新規プロジェクト

npm create tamagui@latest
# または
bun create tamagui

最小構成では tamagui を import し View / Text / styled から開始。本番最適化では Vite または Metro の Tamagui プラグインを設定し、テーマ config（tamagui.config.ts）をプロジェクトに置く。

このリポジトリを clone して開発する場合は Bun 1.3 系を使い、初回 bun install 後に bun run build または bun run watch を推奨する。

8 — 出典

一次情報

GitHub: tamagui/tamagui — 本体（MIT）
tamagui.dev — 公式ドキュメント・デモ
Introduction — コンセプトとコンパイラの説明
リポジトリ内 README.md — 3 パッケージの概要とスターター
リポジトリ内 CONTRIBUTING.md · claude.md — ビルド・テスト・コミット規約
リポジトリ内 library/tamagui.mdx — core / styled / コンパイラのクイックリファレンス