Mastering Tamagui Monorepo Setup with Cursor: Step-by-Step Guide for React Native and Web

Discover how to efficiently build a performant UI kit monorepo using Tamagui, Turborepo, and Cursor AI. This comprehensive guide covers setup, configuration, and optimization for cross-platform development.

Why Choose a Monorepo for Tamagui Projects?

In modern development, monorepos have gained popularity for managing multiple related projects in a single repository. Unlike traditional polyrepos, where each app or package lives separately, a monorepo centralizes code sharing, simplifies dependency management, and streamlines CI/CD pipelines. For Tamagui—a powerful, universal UI kit designed for React Native and the web—a monorepo setup shines by allowing shared components, themes, and configurations across platforms.

Monorepo vs. Polyrepo: A Quick Comparison

Tamagui's design philosophy aligns perfectly with monorepos. It optimizes for performance with CSS-in-JS alternatives, styled-system utilities, and theming that works seamlessly on native and web. Real-world applications include Expo apps, Next.js sites, and hybrid setups like those at Tamagui's core repo.

Using Cursor, an AI-powered code editor, accelerates this process. Cursor understands monorepo structures, suggests configurations, and auto-generates boilerplate, making setup 5-10x faster than manual coding.

Prerequisites and Initial Setup

Before diving in, ensure you have:

• Node.js 18+ installed.
• Cursor editor (download from cursor.com).
• Yarn or npm as package manager (Yarn recommended for workspaces).

Start by creating a new directory and initializing the monorepo:

mkdir my-tamagui-monorepo
cd my-tamagui-monorepo
yarn init -y
yarn add -D turbo@latest typescript @types/node

This sets up Turborepo, the build tool that orchestrates tasks across packages with intelligent caching. Turborepo detects changes and only rebuilds affected packages, crucial for large UIs like Tamagui.

Next, configure turbo.json for pipeline definitions:

{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "lint": {},
    "type-check": {}
  }
}

Add package.json scripts:

{
  "scripts": {
    "dev": "turbo run dev",
    "build": "turbo run build",
    "lint": "turbo run lint",
    "type-check": "turbo run type-check"
  },
  "workspaces": ["apps/*", "packages/*"]
}

Structuring Your Monorepo Packages

Organize into apps/ for deployable projects and packages/ for shared libs:

my-tamagui-monorepo/
├── apps/
│   ├── web/       # Next.js app
│   └── native/    # Expo/React Native app
├── packages/
│   ├── ui/        # Tamagui components
│   ├── config/    # Tamagui config
│   └── eslint-config/
├── turbo.json
└── package.json

This structure promotes reusability. For instance, packages/ui holds styled Tamagui buttons reusable in both web and native apps.

Integrating Tamagui Core

Tamagui requires specific TypeScript and bundler configs for optimal performance. Install it across the monorepo:

yarn workspace @repo/ui add tamagui
yarn workspace apps/web add tamagui
yarn workspace apps/native add tamagui expo

Use Yarn's workspace protocol (@repo/ui) for internal deps, avoiding version mismatches.

Create packages/config/tamagui.config.ts:

import { createTamagui, createTokens } from 'tamagui'

const tokens = createTokens({
  size: {
    0: 0,
    1: 4,
    // ... full token set
  },
  // colors, space, radius, etc.
})

export default createTamagui({
  tokens,
  themes: {
    light: {
      background: '#fff',
      // ...
    },
  },
})

This config enables Tamagui's optimizations like static CSS extraction and tree-shaking.

App-Specific Configurations

Web App (Next.js)

In apps/web/next.config.js:

const { withTamagui } = require('@tamagui/next-plugin')

/** @type {import('next').NextConfig} */
const config = {
  transpilePackages: ['@repo/ui'],
}

module.exports = withTamagui(config)

apps/web/tamagui.config.ts imports from @repo/config:

import config from '@repo/config'
export default config

Root tsconfig.json:

{
  "compilerOptions": {
    "strict": true,
    "baseUrl": ".",
    "paths": {
      "@repo/*": ["./packages/*"]
    }
  }
}

Package-level tsconfig.json extends root with Tamagui plugins.

Native App (Expo)

apps/native/app.json:

{
  "expo": {
    "plugins": [
      "tamagui",
      {
        "config": "./tamagui.config.ts",
        "components": ["./src/components"]
      }
    ]
  }
}

This enables compile-time optimizations for React Native.

Shared UI Package Development

In packages/ui/package.json:

{
  "name": "@repo/ui",
  "dependencies": {
    "tamagui": "*"
  }
}

Example component Button.tsx:

import { styled } from 'tamagui'

export const Button = styled({
  backgroundColor: '$blue10',
  color: 'white',
  padding: '$4',
  borderRadius: '$10',
}, {
  variants: {
    variant: {
      primary: { backgroundColor: '$blue10' },
    },
  },
})

Use in apps: import { Button } from '@repo/ui'.

Running and Testing the Setup

yarn turbo run dev

This spins up web at localhost:3000 and native via Expo. Cursor's AI can debug issues like path aliasing or theme mismatches instantly.

Linting with ESLint: Create packages/eslint-config and reference in apps.

Optimization and Best Practices

• Caching: Turbo caches builds; invalidate with --force.
• TypeScript Paths: Ensure consistent resolution.
• Theming: Use tokens for responsive design (e.g., size: { true: 16, lg: 20 }).
• Performance: Tamagui extracts CSS, reducing bundle size by 70% vs. Emotion.

Real-world example: Tamagui's monorepo app example demonstrates a full web/native setup. Scale to enterprise apps like dashboards shared across platforms.

Troubleshooting Common Issues

• Path Errors: Verify tsconfig paths and next.config transpilePackages.
• Native Linking: Run expo install after plugin adds.
• Turbo Cache Misses: Clear with yarn turbo run build --force.

Cursor excels here—prompt it with "Fix Tamagui path alias in monorepo" for instant resolutions.

Scaling Your Monorepo

Add more packages like animations/ or icons/. Integrate Storybook for component docs:

yarn workspace @repo/ui add -D @tamagui/storybook

For CI, use GitHub Actions with Turbo cache.

This setup empowers efficient, performant cross-platform UIs. Experiment in Cursor to iterate rapidly.