Skip to main content

Tamagui Implementation Guide for Daggh Companion

Overview​

This document provides a technical summary of how Tamagui is integrated into the Daggh Companion project, including setup, best practices, common pitfalls, and solutions. It is intended for developers working on or maintaining the codebase.

Project Structure Reference​

  • Tamagui config: daggh-companion/tamagui.config.ts
  • Provider wrapper: daggh-companion/providers/TamaguiProviderWrapper.tsx
  • Babel config: daggh-companion/babel.config.js
  • Theme usage example: daggh-companion/app/(auth)/login.tsx

Key Setup Steps​

  1. Tamagui Configuration

    • The main config is in tamagui.config.ts and uses createTamagui() to extend the default config and add custom themes (brand, brand_dark).
    • Export the result of createTamagui() as the default export.
    • Example: 
      import { createTamagui } from 'tamagui';
      import { defaultConfig } from '@tamagui/config/v4';
      // ...define custom themes...
      const config = { ... };
      export default createTamagui(config);

  2. Provider Setup

    • The app is wrapped in TamaguiProviderWrapper, which imports the config and provides it to the app via TamaguiProvider.
    • This ensures all Tamagui components have access to the theme and tokens.

  3. Babel Plugin Configuration

    • The Tamagui Babel plugin is required for token and theme compilation.
    • In babel.config.js, ensure: 
      plugins: [
        ['@tamagui/babel-plugin', {
          components: ['tamagui'],
          config: './tamagui.config.ts',
          logTimings: true,
          disableExtraction: process.env.NODE_ENV === 'development',
        }],
        ...
      ]
    • Set process.env.TAMAGUI_TARGET = 'native' at the top of the file.

  4. Expo/Metro

    • No custom metro.config.js is required unless you have special needs.
    • Always run with a custom dev client (not Expo Go) for Tamagui native support.

Theme & Token Usage​

  • Use bg or background props for background colors: 
    <Button bg="$primary">Primary</Button>
  • Avoid backgroundColor as it is not type-safe in Tamagui and will cause TypeScript errors.
  • Use theme tokens with a $ prefix (e.g., $primary, $secondary).
  • To apply a custom theme, use the theme prop: 
    <YStack theme="brand">...</YStack>

Common Pitfalls & Solutions​

1. TypeScript Errors with backgroundColor​

  • Problem: backgroundColor is not a valid prop in Tamagui's type definitions.
  • Solution: Use background or bg instead.

2. Custom Theme Tokens Not Available​

  • Problem: Custom tokens (e.g., primary, secondary) are not accessible in components.
  • Solution:
    • Ensure your custom theme is set as the default in the config (defaultTheme: 'brand').
    • Use the theme prop on a parent component if you want to scope a subtree to a custom theme.

3. Styles Not Applying or Tokens Not Working​

  • Problem: Styles or tokens do not work as expected.
  • Solution:
    • Ensure the Tamagui Babel plugin is configured and running (look for Tamagui logs in the terminal).
    • Clear Metro and Babel caches: expo start -c.
    • Do not use Expo Go; use a custom dev client.

4. Config Import Issues​

  • Problem: Importing the config incorrectly (e.g., using a default import for a named export).
  • Solution: Always use the correct import/export style. For Tamagui config, export the result of createTamagui() as default.

References & Further Reading​

Summary Checklist​

  • Use background/bg for backgrounds, not backgroundColor
  • Use theme tokens with $ prefix
  • Wrap app in TamaguiProvider with your config
  • Use the Tamagui Babel plugin and set TAMAGUI_TARGET
  • Run with a custom dev client, not Expo Go
  • Clear caches if styles/tokens are not working

For more details, see the referenced docs and the project structure above.

Tamagui Config (tamagui.config.ts)​

  • The config file is the heart of your design system. It defines tokens, themes, fonts, and more.
  • Extending Themes:
    • To add custom themes (e.g., brand, brand_dark), extend the base themes from defaultConfig.themes.light and defaultConfig.themes.dark.
    • Example: 
      const brand = {
        ...defaultConfig.themes.light,
        background: "#18181b",
        color: "#fff",
        primary: "#6366f1",
        // ...
      }
  • Adding Tokens:
    • You can add or override tokens (e.g., radius, space) by spreading and extending defaultConfig.tokens.
  • Setting Defaults:
    • Set defaultTheme and defaultTheme_dark to your custom themes to make them the app-wide default.
  • Export:
    • Always export the result of createTamagui(config) as the default export.
  • Common Mistakes:
    • Forgetting to spread the base theme (...defaultConfig.themes.light) can cause missing keys and runtime errors.
    • Not exporting the result of createTamagui() will break the provider.
    • Using a named export instead of default can cause import issues in the provider.
  • TypeScript Integration:
    • Use the declare module "tamagui" block to extend Tamagui's types with your config.

See the actual config in daggh-companion/tamagui.config.ts for a working example.