Tamagui Best Practices

Tamagui Best Practices

Tamagui v1.x patterns beyond fundamentals: Config v4, compiler optimization, compound components, and gotchas.

Reference Files — Read Before Writing Code

Config v4

Minimal setup with @tamagui/config/v4. Add styleCompat: 'react-native' for new projects to align flexBasis with React Native behavior:

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

For custom themes use createThemes with palette/accent/childrenThemes — see @DESIGN_SYSTEM.md.

Compiler Optimization Rules

• Use styled() variants instead of inline conditionals — dynamic values break flattening.
• Avoid style={{ ... }} with variables; use variant props instead.
• The context pattern (createStyledContext) disables compiler flattening — use for higher-level components (Button, Card), not primitives.