Monorepo Setup Guide

# Monorepo Setup Guide for Google Antigravity

Build scalable monorepos with Turborepo for efficient code sharing and development with Google Antigravity IDE.

## Turborepo Configuration

```json
// turbo.json
{
  "$schema": "https://turbo.build/schema.json",
  "globalDependencies": ["**/.env.*local"],
  "globalEnv": ["NODE_ENV", "CI"],
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**", "!.next/cache/**"],
      "env": ["DATABASE_URL", "API_URL"]
    },
    "lint": {
      "dependsOn": ["^lint"],
      "outputs": []
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": ["coverage/**"],
      "inputs": ["src/**/*.tsx", "src/**/*.ts", "test/**/*.ts"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "typecheck": {
      "dependsOn": ["^typecheck"],
      "outputs": []
    }
  }
}
```

## Package Structure

```
// Recommended monorepo structure
monorepo/
  apps/
    web/              # Next.js frontend
    api/              # Express/Fastify backend
    mobile/           # React Native app
    admin/            # Admin dashboard
  packages/
    ui/               # Shared UI components
    config-eslint/    # ESLint configurations
    config-typescript/# TypeScript configurations
    database/         # Database schema and client
    utils/            # Shared utilities
    types/            # Shared TypeScript types
  tooling/
    scripts/          # Build and CI scripts
```

## Shared Package Configuration

```typescript
// packages/ui/package.json
{
  "name": "@repo/ui",
  "version": "0.0.0",
  "private": true,
  "exports": {
    "./button": "./src/button.tsx",
    "./card": "./src/card.tsx",
    "./form": "./src/form/index.tsx",
    "./styles.css": "./dist/styles.css"
  },
  "scripts": {
    "build": "tsup",
    "dev": "tsup --watch",
    "lint": "eslint src/",
    "typecheck": "tsc --noEmit"
  },
  "devDependencies": {
    "@repo/config-typescript": "workspace:*",
    "@repo/config-eslint": "workspace:*",
    "tsup": "^8.0.0",
    "typescript": "^5.3.0"
  },
  "peerDependencies": {
    "react": "^18.0.0",
    "react-dom": "^18.0.0"
  }
}

// packages/ui/tsup.config.ts
import { defineConfig } from "tsup";

export default defineConfig({
  entry: ["src/index.ts", "src/button.tsx", "src/card.tsx"],
  format: ["esm", "cjs"],
  dts: true,
  splitting: true,
  clean: true,
  external: ["react", "react-dom"]
});
```

## Shared TypeScript Configuration

```json
// packages/config-typescript/base.json
{
  "$schema": "https://json.schemastore.org/tsconfig",
  "display": "Base",
  "compilerOptions": {
    "target": "ES2022",
    "lib": ["ES2022"],
    "module": "ESNext",
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "skipLibCheck": true,
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitOverride": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "declaration": true,
    "declarationMap": true
  }
}

// packages/config-typescript/nextjs.json
{
  "$schema": "https://json.schemastore.org/tsconfig",
  "display": "Next.js",
  "extends": "./base.json",
  "compilerOptions": {
    "lib": ["dom", "dom.iterable", "ES2022"],
    "module": "ESNext",
    "jsx": "preserve",
    "incremental": true,
    "plugins": [{ "name": "next" }]
  }
}
```

## Workspace Package Management

```yaml
# pnpm-workspace.yaml
packages:
  - "apps/*"
  - "packages/*"
  - "tooling/*"
```

```json
// Root package.json
{
  "name": "monorepo",
  "private": true,
  "scripts": {
    "build": "turbo run build",
    "dev": "turbo run dev",
    "lint": "turbo run lint",
    "test": "turbo run test",
    "typecheck": "turbo run typecheck",
    "clean": "turbo run clean && rm -rf node_modules",
    "format": "prettier --write .",
    "changeset": "changeset",
    "version": "changeset version",
    "release": "turbo run build --filter=./packages/* && changeset publish"
  },
  "devDependencies": {
    "@changesets/cli": "^2.27.0",
    "prettier": "^3.2.0",
    "turbo": "^2.0.0"
  },
  "packageManager": "pnpm@8.15.0"
}
```

## Internal Package Imports

```typescript
// apps/web/package.json
{
  "name": "@repo/web",
  "dependencies": {
    "@repo/ui": "workspace:*",
    "@repo/database": "workspace:*",
    "@repo/utils": "workspace:*"
  }
}

// apps/web/src/app/page.tsx
import { Button, Card } from "@repo/ui";
import { db } from "@repo/database";
import { formatDate } from "@repo/utils";

export default async function Page() {
  const users = await db.query.users.findMany();
  
  return (
    <Card>
      <h1>Users</h1>
      {users.map(user => (
        <div key={user.id}>
          <span>{user.name}</span>
          <span>{formatDate(user.createdAt)}</span>
          <Button>View</Button>
        </div>
      ))}
    </Card>
  );
}
```

## Best Practices

1. **Keep shared code in packages/** directory
2. **Use workspace protocol** for internal dependencies
3. **Configure task dependencies** properly in turbo.json
4. **Share configurations** for TypeScript, ESLint, Prettier
5. **Use changesets** for versioning and publishing
6. **Implement caching** for faster builds
7. **Run tasks in parallel** where possible

Google Antigravity understands monorepo structures and provides intelligent cross-package refactoring support.