tamagui-best-practices

Tamagui のベストプラクティス

基礎を超えた Tamagui v1.x のパターン：Config v4、コンパイラーの最適化、複合コンポーネント、注意点。

参照ファイル — コードを書く前に読む

コンテキスト	ファイル	内容
Dialog、Sheet、モーダルオーバーレイ	@DIALOG_PATTERNS.md	Adapt コンポーネント、アクセシビリティ
Form、Input、Label、バリデーション	@FORM_PATTERNS.md	zod の統合
アニメーション、トランジション	@ANIMATION_PATTERNS.md	ドライバー、enterStyle/exitStyle
Popover、Tooltip、Select	@OVERLAY_PATTERNS.md	オーバーレイのプリミティブ
コンパイラーの最適化	@COMPILER_PATTERNS.md	コンパイラーでフラット化できるもの／できないもの
デザイントークン、テーマ設定	@DESIGN_SYSTEM.md	パレット、トークンの構造

Config v4

@tamagui/config/v4 を使った最小限のセットアップです。新しいプロジェクトでは styleCompat: 'react-native' を追加して、flexBasis を React Native の動作に合わせます。

import { defaultConfig } from '@tamagui/config/v4'
import { createTamagui } from 'tamagui'

export const config = createTamagui({
  ...defaultConfig,
  settings: { ...defaultConfig.settings, styleCompat: 'react-native' },
})

declare module 'tamagui' {
  interface TamaguiCustomConfig extends typeof config {}
}

カスタムテーマには palette/accent/childrenThemes を指定して createThemes を使用してください。@DESIGN_SYSTEM.md を参照してください。

コンパイラー最適化のルール

• インライン条件式ではなく、styled() のバリアントを使用してください。動的な値はフラット化を妨げます。
• 変数を使った style={{ ... }} は避けてください。代わりにバリアントの props を使用します。
• context パターン（createStyledContext）はコンパイラーによるフラット化を無効にします。プリミティブではなく、上位レベルのコンポーネント（Button、Card）で使用してください。

// BAD — breaks compiler
<View backgroundColor={isDark ? '$gray1' : '$gray12'} />

// GOOD — use variants
const Box = styled(View, {
  variants: {
    dark: { true: { backgroundColor: '$gray1' }, false: { backgroundColor: '$gray12' } },
  },
})

styled() とインラインの比較

• styled()：再利用可能なコンポーネント、バリアント駆動の動作、コンパイラーで最適化可能なプリミティブ。
• インライン props：すでにスタイルが設定されたコンポーネントに対する、一度限りのレイアウト調整。
• variants オブジェクトには必ず as const を使用してください（推論される const ジェネリクスが導入されるまでの TypeScript の制限によるものです）。

主な注意点

props の順序によって上書きの優先順位が決まります — スプレッドの後にある props は、呼び出し側から上書きできません。

// width is locked; backgroundColor can be overridden
<View backgroundColor="$red10" {...props} width={200} />

バリアントの順序が重要です — 後の props が優先されます。

<Component scale={3} huge />  // scale = 3 (scale listed first)
<Component huge scale={3} />  // scale = 2 (huge overrides, comes first in variants)

styled コンポーネントをラップする場合は .styleable() を使用してください — バリアントの継承が維持されます。

const CorrectWrapper = StyledText.styleable((props, ref) => (
  <StyledText ref={ref} {...props} />
))

標準以外のトークン解決には accept prop を使用してください（SVG の fill/stroke、contentContainerStyle）。

const StyledSVG = styled(SVG, {}, { accept: { fill: 'color', stroke: 'color' } as const })

インポートの一貫性 — tamagui、@tamagui/core、@tamagui/button は別々のパッケージです。プロジェクトごとに1つの方法を選んでください。

RN StyleSheet と Tamagui を決して混在させないでください — StyleSheet の値ではトークンが解決されません。

Dialog/Sheet のプラットフォーム分岐 — Platform.OS のチェックではなく Adapt を使用してください（@DIALOG_PATTERNS.md を参照）。

クイックリファレンス

Config v4 の省略形：bg backgroundColor、p padding、m margin、w width、h height、br borderRadius

メディアブレークポイント：$xs 660px、$sm 800px、$md 1020px、$lg 1280px、$xl 1420px

アニメーションドライバー：css（Web、デフォルト）、react-native-reanimated（ネイティブ、必須）

トークンの $ 接頭辞：props では使用します（color="$color"）。テーマ定義では省略します（{ color: palette[11] }）。

最新ドキュメントの取得

curl -sL "https://tamagui.dev/docs/core/configuration.md"
curl -sL "https://tamagui.dev/llms.txt"  # full index