Monorepo-Only Architecture

V2 only supports monorepo projects. Single-app projects are no longer supported.

Why Monorepo-Only?

1. Workspace Dependencies

Monorepos enable workspace:* protocol for internal dependencies:

{
  "dependencies": {
    "@myproject/ui": "workspace:*",
    "@myproject/auth": "workspace:*"
  }
}

Benefits:

• No version conflicts
• Always use latest internal code
• Faster development (no publishing needed)

2. Shared Code

Packages can be shared across apps:

my-project/
├── apps/
│   ├── web/          # Uses packages/ui, packages/auth
│   └── mobile/       # Uses packages/ui, packages/auth
└── packages/
    ├── ui/           # Shared UI components
    └── auth/          # Shared auth logic

Benefits:

• Write once, use everywhere
• Consistent behavior across apps
• Single source of truth

3. Consistent Structure

All V2 projects have the same structure:

project/
├── apps/
│   ├── web/
│   ├── mobile/
│   └── api/
├── packages/
│   ├── database/
│   ├── auth/
│   └── ui/
└── package.json      # Workspaces configuration

Benefits:

• Predictable structure
• Easier onboarding
• Tooling compatibility

4. Better Dependency Management

Monorepos provide:

• Centralized dependency management
• Workspace protocol for internal deps
• Consistent versions across packages

Limitations

No Single-App Projects

V2 cannot create single-app projects. If you need a simple single-app project:

Option 1: Use V1 (legacy support)

# V1 still supports single-app
architech new genome-v1.ts

Option 2: Create minimal monorepo

// Minimal monorepo (one app, no packages)
apps: {
  web: {
    type: 'web',
    framework: 'nextjs',
    packages: []  // No packages
  }
}

Migration Required

Existing single-app projects must migrate to monorepo:

Before (V1):

my-app/
├── src/
├── package.json
└── ...

After (V2):

my-app/
├── apps/
│   └── web/        # Your app
│       ├── src/
│       └── package.json
├── packages/       # Empty (no packages)
└── package.json    # Root with workspaces

Migration Path

Step 1: Restructure

Move your app to apps/web/:

mkdir -p apps/web
mv src apps/web/
mv package.json apps/web/

Step 2: Create Root package.json

{
  "name": "my-project",
  "private": true,
  "workspaces": [
    "apps/*",
    "packages/*"
  ]
}

Step 3: Update V2Genome

apps: {
  web: {
    type: 'web',
    framework: 'nextjs',
    packages: []
  }
}

Benefits Summary

When to Use V2

Use V2 if:

• ✅ You want workspace dependencies
• ✅ You have multiple apps
• ✅ You want shared packages
• ✅ You want consistent structure

Use V1 if:

• ⚠️ You need a simple single-app project
• ⚠️ You don't want monorepo complexity

Note: V1 is still supported but V2 is recommended for new projects.

Related

• V2Genome Structure - How V2Genome defines structure
• Migration Guide - Step-by-step migration from V1
• Getting Started - Create your first V2 project