TypeScript Monorepo with Nx

# TypeScript Monorepo with Nx

Build scalable monorepos with Nx and TypeScript using Google Antigravity IDE. This comprehensive guide covers workspace configuration, dependency management, and build optimization.

## Why Nx Monorepo?

Nx provides powerful tooling for managing multiple projects with shared code. Google Antigravity IDE's Gemini 3 engine suggests optimal project organization and caching strategies.

## Workspace Setup

```json
// nx.json
{
  "$schema": "./node_modules/nx/schemas/nx-schema.json",
  "namedInputs": {
    "default": ["{projectRoot}/**/*", "sharedGlobals"],
    "production": [
      "default",
      "!{projectRoot}/**/*.spec.ts",
      "!{projectRoot}/tsconfig.spec.json"
    ],
    "sharedGlobals": ["{workspaceRoot}/tsconfig.base.json"]
  },
  "targetDefaults": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["production", "^production"],
      "cache": true
    },
    "test": {
      "inputs": ["default", "^production"],
      "cache": true
    },
    "lint": {
      "inputs": ["default"],
      "cache": true
    }
  },
  "parallel": 3,
  "defaultBase": "main",
  "tasksRunnerOptions": {
    "default": {
      "runner": "nx/tasks-runners/default",
      "options": {
        "cacheableOperations": ["build", "lint", "test", "e2e"]
      }
    }
  }
}
```

## Project Configuration

```json
// apps/web/project.json
{
  "name": "web",
  "$schema": "../../node_modules/nx/schemas/project-schema.json",
  "projectType": "application",
  "sourceRoot": "apps/web/src",
  "tags": ["scope:web", "type:app"],
  "targets": {
    "build": {
      "executor": "@nx/next:build",
      "outputs": ["{options.outputPath}"],
      "options": {
        "outputPath": "dist/apps/web"
      },
      "configurations": {
        "production": {
          "optimization": true,
          "sourceMap": false
        },
        "development": {
          "optimization": false,
          "sourceMap": true
        }
      }
    },
    "serve": {
      "executor": "@nx/next:server",
      "options": {
        "port": 3000,
        "buildTarget": "web:build"
      }
    }
  }
}
```

## Shared Libraries

```typescript
// libs/shared/utils/src/lib/validation.ts
import { z } from "zod";

export const emailSchema = z.string().email();
export const passwordSchema = z.string().min(8).max(100);

export const userSchema = z.object({
  email: emailSchema,
  password: passwordSchema,
  name: z.string().min(2).max(100),
});

export type User = z.infer<typeof userSchema>;

export function validateUser(data: unknown): User {
  return userSchema.parse(data);
}
```

```typescript
// libs/shared/ui/src/lib/Button/Button.tsx
import { forwardRef, ButtonHTMLAttributes } from "react";
import styles from "./Button.module.css";

export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: "primary" | "secondary" | "ghost";
  size?: "sm" | "md" | "lg";
  loading?: boolean;
}

export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
  ({ variant = "primary", size = "md", loading, children, ...props }, ref) => {
    return (
      <button
        ref={ref}
        className={`${styles.button} ${styles[variant]} ${styles[size]}`}
        disabled={loading || props.disabled}
        {...props}
      >
        {loading ? <Spinner size={size} /> : children}
      </button>
    );
  }
);
```

## Dependency Constraints

```json
// .eslintrc.json
{
  "root": true,
  "plugins": ["@nx"],
  "overrides": [
    {
      "files": ["*.ts", "*.tsx"],
      "rules": {
        "@nx/enforce-module-boundaries": [
          "error",
          {
            "enforceBuildableLibDependency": true,
            "allow": [],
            "depConstraints": [
              {
                "sourceTag": "scope:web",
                "onlyDependOnLibsWithTags": ["scope:shared", "scope:web"]
              },
              {
                "sourceTag": "scope:api",
                "onlyDependOnLibsWithTags": ["scope:shared", "scope:api"]
              },
              {
                "sourceTag": "type:app",
                "onlyDependOnLibsWithTags": ["type:lib", "type:util"]
              }
            ]
          }
        ]
      }
    }
  ]
}
```

## CI/CD Pipeline

```yaml
# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main]
  pull_request:

jobs:
  main:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: "npm"

      - run: npm ci

      - uses: nrwl/nx-set-shas@v4

      - run: npx nx affected -t lint test build --parallel=3

      - name: Upload artifacts
        uses: actions/upload-artifact@v4
        with:
          name: dist
          path: dist/
```

## Best Practices

- Use project tags for dependency constraints
- Leverage computation caching for faster builds
- Apply affected commands in CI/CD
- Create shared libraries for common code
- Use buildable libraries for incremental builds
- Configure remote caching for team workflows

Google Antigravity IDE provides Nx workspace templates and automatically enforces module boundaries in your monorepo.