| 1 | --- |
| 2 | title: Monorepo |
| 3 | description: Two ways to organize an Alchemy monorepo — one Stack at the workspace root, or one Stack per package wired with typed references. |
| 4 | --- |
| 5 | |
| 6 | A monorepo is a workspace with a backend package and a frontend |
| 7 | that calls it. The one decision Alchemy adds: **where do the |
| 8 | Stacks live?** |
| 9 | |
| 10 | ## Option A — Single Stack |
| 11 | |
| 12 | ```sh |
| 13 | . |
| 14 | ├── package.json # workspaces: ["frontend", "backend"] |
| 15 | ├── alchemy.run.ts # the one Stack — deploys both packages |
| 16 | ├── backend/ # Worker + API schema + typed client |
| 17 | └── frontend/ # React app, built by the Stack |
| 18 | ``` |
| 19 | |
| 20 | One `alchemy.run.ts` at the workspace root deploys everything in |
| 21 | one plan. The frontend reads the Worker's URL directly off the |
| 22 | in-memory Output — no references, no deploy ordering. |
| 23 | |
| 24 | Walkthrough: [Single Stack](/project-structure/monorepo-single-stack). |
| 25 | |
| 26 | ## Option B — Multiple Stacks |
| 27 | |
| 28 | ```sh |
| 29 | . |
| 30 | ├── package.json # workspaces: ["frontend", "backend"] |
| 31 | ├── backend/ |
| 32 | │ ├── alchemy.run.ts # Backend Stack |
| 33 | │ └── src/Stack.ts # typed handle the frontend imports |
| 34 | └── frontend/ |
| 35 | └── alchemy.run.ts # Frontend Stack — yield* Backend |
| 36 | ``` |
| 37 | |
| 38 | Each package owns its own Stack. The frontend reads the backend's |
| 39 | deployed outputs through a typed cross-stack reference, so each |
| 40 | package deploys and destroys independently. |
| 41 | |
| 42 | Walkthrough: [Multiple Stacks](/project-structure/monorepo-multi-stack). |
| 43 | |
| 44 | ## How to choose |
| 45 | |
| 46 | - Start with a **Single Stack** — one plan, one state file, no |
| 47 | ordering constraints. |
| 48 | - Go **Multiple Stacks** when packages deploy on different |
| 49 | cadences (different teams, different CI), or the backend has |
| 50 | consumers beyond this frontend. |
| 51 | - Go **Multiple Stacks** when you need to `destroy` one package |
| 52 | without touching the other. |
| 53 | |
| 54 | ## Where next |
| 55 | |
| 56 | - [File layout](/project-structure/file-layout) — the single-package layout |
| 57 | both options build on. |
| 58 | - [Single Stack](/project-structure/monorepo-single-stack) — the full |
| 59 | two-package walkthrough. |
| 60 | - [Multiple Stacks](/project-structure/monorepo-multi-stack) — typed Stack |
| 61 | handles and cross-stack references. |
| 62 | - [References](/infrastructure-as-code/references) — when to split |
| 63 | Stacks and how to pin stages. |