sailfork / t3code-github / .repos/ alchemy-effect/ website/ src/ content/ docs/ project-structure/ monorepo.mdx

A monorepo is a workspace with a backend package and a frontend that calls it. The one decision Alchemy adds: where do the Stacks live?

Option A — Single Stack

.
├── package.json     # workspaces: ["frontend", "backend"]
├── alchemy.run.ts   # the one Stack — deploys both packages
├── backend/         # Worker + API schema + typed client
└── frontend/        # React app, built by the Stack

One alchemy.run.ts at the workspace root deploys everything in one plan. The frontend reads the Worker's URL directly off the in-memory Output — no references, no deploy ordering.

Walkthrough: Single Stack.

Option B — Multiple Stacks

.
├── package.json           # workspaces: ["frontend", "backend"]
├── backend/
│   ├── alchemy.run.ts     # Backend Stack
│   └── src/Stack.ts       # typed handle the frontend imports
└── frontend/
    └── alchemy.run.ts     # Frontend Stack — yield* Backend

Each package owns its own Stack. The frontend reads the backend's deployed outputs through a typed cross-stack reference, so each package deploys and destroys independently.

Walkthrough: Multiple Stacks.

How to choose

  • Start with a Single Stack — one plan, one state file, no ordering constraints.
  • Go Multiple Stacks when packages deploy on different cadences (different teams, different CI), or the backend has consumers beyond this frontend.
  • Go Multiple Stacks when you need to destroy one package without touching the other.

Where next