Skip to content

Commit d7db5dc

Browse files
AmanVarshney01AmanVarshney01
committed
docs(compute): add monorepo deployment guide
1 parent c4baaa4 commit d7db5dc

4 files changed

Lines changed: 189 additions & 7 deletions

File tree

‎apps/docs/content/docs/compute/configuration.mdx‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -143,7 +143,7 @@ The config file's directory is treated as the project directory: the [`.prisma/l
143143

144144
## Monorepos
145145

146-
Use `apps` instead of `app` to declare several apps in one repository, keyed by a target name:
146+
Use `apps` instead of `app` to declare several apps in one repository, keyed by a target name. For an end-to-end setup with local builds, single-app deploys, deploy-all, and GitHub automation, see [Deploy a monorepo](/compute/monorepos).
147147

148148
```ts title="prisma.compute.ts"
149149
import { defineComputeConfig } from "@prisma/compute-sdk/config";
@@ -199,6 +199,7 @@ A config that fails to load or validate stops the deploy before any remote work,
199199

200200
## What's next
201201

202+
- [Deploy a monorepo](/compute/monorepos): configure, verify, and deploy several apps from one repository.
202203
- [CLI reference](/compute/cli-reference): every command, flag, and error code.
203204
- [Deploy your first app](/prisma-compute/deploy): the end-to-end quickstart.
204205
- [Environment variables](/compute/environment-variables): scoped configuration, secrets, and your database connection string.

‎apps/docs/content/docs/compute/github.mdx‎

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -58,13 +58,12 @@ Connecting doesn't deploy anything on its own; it wires up automation for *futur
5858

5959
## CI and monorepos
6060

61-
Auto-deploy handles monorepos that declare their apps in `prisma.compute.ts`: one pushed commit fans out into a targeted build per app. For custom pipelines, or anywhere you want full control, run the CLI directly with a service token and explicit targets:
61+
Auto-deploy handles [monorepos that declare their apps in `prisma.compute.ts`](/compute/monorepos): one pushed commit fans out into a targeted build per app. For custom pipelines, or anywhere you want full control, set `PRISMA_SERVICE_TOKEN` and `PRISMA_PROJECT_ID`, then name the config target positionally:
6262

63-
```bash
64-
PRISMA_SERVICE_TOKEN=... npx @prisma/cli@latest app deploy \
65-
--project my-app \
66-
--app web \
67-
--branch "$GITHUB_HEAD_REF" \
63+
```bash title="CI"
64+
PRISMA_SERVICE_TOKEN=... PRISMA_PROJECT_ID=... \
65+
npx @prisma/cli@latest app deploy web \
66+
--branch "${GITHUB_HEAD_REF:-$GITHUB_REF_NAME}" \
6867
--json \
6968
--no-interactive
7069
```

‎apps/docs/content/docs/compute/meta.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@
99
"---Features---",
1010
"branching",
1111
"deployments",
12+
"monorepos",
1213
"keeping-instances-awake",
1314
"image-transformations",
1415
"environment-variables",

‎apps/docs/content/docs/compute/monorepos.mdx‎

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
---
2+
title: Monorepos
3+
description: Deploy several apps from one repository with a root-level Prisma Compute config.
4+
url: /compute/monorepos
5+
metaTitle: Deploy a monorepo | Prisma Compute
6+
metaDescription: Configure, build, and deploy multiple apps from a monorepo with prisma.compute.ts and Prisma Compute.
7+
---
8+
9+
Prisma Compute can deploy several apps from one repository. Put one `prisma.compute.ts` at the repository root, declare each deployable app under `apps`, and use the app's key as its CLI target.
10+
11+
Each target becomes a separate Compute app with its own deployments and URL. The targets share one Prisma project and deploy to the same branch, so a preview branch can contain your whole application.
12+
13+
Before you start, install the monorepo's dependencies and complete the sign-in and project-linking steps in [Get started](/compute/getting-started). Run commands from the repository root unless a step says otherwise.
14+
15+
## Example repository
16+
17+
This guide uses a Next.js frontend and a Hono API:
18+
19+
```text title="Repository structure"
20+
acme-shop/
21+
├── apps/
22+
│ ├── api/
23+
│ │ ├── src/index.ts
24+
│ │ └── package.json
25+
│ └── web/
26+
│ ├── app/
27+
│ ├── next.config.ts
28+
│ └── package.json
29+
├── package.json
30+
├── pnpm-workspace.yaml
31+
└── prisma.compute.ts
32+
```
33+
34+
Your apps can use different supported frameworks and can depend on shared workspace packages. Each app must still have a working build from its configured root.
35+
36+
## 1. Add the Compute config
37+
38+
Create `prisma.compute.ts` at the monorepo root:
39+
40+
```ts title="prisma.compute.ts"
41+
import { defineComputeConfig } from "@prisma/compute-sdk/config";
42+
43+
export default defineComputeConfig({
44+
apps: {
45+
web: {
46+
root: "apps/web",
47+
framework: "nextjs",
48+
},
49+
api: {
50+
root: "apps/api",
51+
framework: "hono",
52+
entry: "src/index.ts",
53+
httpPort: 3000,
54+
},
55+
},
56+
});
57+
```
58+
59+
Here, `web` and `api` are **target keys**. They identify the apps in CLI commands and become the deployed app names unless you set `name` explicitly.
60+
61+
Paths have two different bases:
62+
63+
- `root` is relative to `prisma.compute.ts`.
64+
- `entry` and build output paths are relative to that app's `root`.
65+
66+
`httpPort` must match the port the deployed server listens on. A server you start yourself must also listen on `0.0.0.0`, not only `localhost`.
67+
68+
The Next.js app in this example also enables standalone output:
69+
70+
```ts title="apps/web/next.config.ts"
71+
export default { output: "standalone" };
72+
```
73+
74+
The CLI can load this config without a local SDK installation. Install `@prisma/compute-sdk` as a root development dependency if you want editor autocomplete and type checking. See the [configuration reference](/compute/configuration) for every field, environment inputs, custom build settings, and the JSON config format.
75+
76+
## 2. Verify every app locally
77+
78+
Build each target from the repository root before deploying:
79+
80+
```npm title="Terminal"
81+
npx @prisma/cli@latest app build web
82+
npx @prisma/cli@latest app build api
83+
```
84+
85+
`app build` always builds one target. If you omit the target at the monorepo root, the CLI returns `COMPUTE_CONFIG_TARGET_REQUIRED` and lists the available targets.
86+
87+
From inside a configured `root`, the CLI infers the target, so this builds `api` too:
88+
89+
```npm title="Terminal"
90+
cd apps/api
91+
npx @prisma/cli@latest app build
92+
```
93+
94+
If roots overlap, the deepest matching root wins. Prefer non-overlapping roots unless that behavior is intentional.
95+
96+
## 3. Deploy one app
97+
98+
Pass the target key as the positional argument:
99+
100+
```npm title="Terminal"
101+
npx @prisma/cli@latest app deploy web
102+
```
103+
104+
To deploy the API instead:
105+
106+
```npm title="Terminal"
107+
npx @prisma/cli@latest app deploy api
108+
```
109+
110+
You can also run the command from inside an app's `root` and omit the target:
111+
112+
```npm title="Terminal"
113+
cd apps/web
114+
npx @prisma/cli@latest app deploy
115+
```
116+
117+
:::warning
118+
119+
The positional `web` in `app deploy web` selects `apps.web` from the config. `--app web` has a different purpose: it overrides the deployed app name. It does not select a config target.
120+
121+
:::
122+
123+
## 4. Deploy the whole monorepo
124+
125+
When your current directory is not inside a configured app root, a bare deploy covers the whole config. With the example structure, run this from the monorepo root:
126+
127+
```npm title="Terminal"
128+
npx @prisma/cli@latest app deploy
129+
```
130+
131+
The CLI deploys every target in config order. Project-, branch-, database-, and production-level options apply to the whole run. For example, this deploys every app to the same preview branch:
132+
133+
```npm title="Terminal"
134+
npx @prisma/cli@latest app deploy --branch feature/search
135+
```
136+
137+
A deploy-all run rejects per-app overrides such as `--app`, `--framework`, `--entry`, `--http-port`, `--region`, `--env`, and `PRISMA_APP_ID`. Put stable per-app values in `prisma.compute.ts`, or select one target before using an override:
138+
139+
```npm title="Terminal"
140+
npx @prisma/cli@latest app deploy api --env apps/api/.env.preview
141+
```
142+
143+
Targets deploy in order and the run stops at the first failure. The error tells you which targets are already live, which target failed, and which targets were not attempted. Fix the failure and rerun the command to converge the repository.
144+
145+
## Command summary
146+
147+
| Goal | Run from the monorepo root |
148+
| --- | --- |
149+
| Build one app | `npx @prisma/cli@latest app build web` |
150+
| Deploy one app | `npx @prisma/cli@latest app deploy web` |
151+
| Deploy every app | `npx @prisma/cli@latest app deploy` |
152+
| Deploy every app to a preview branch | `npx @prisma/cli@latest app deploy --branch feature/search` |
153+
154+
## Deploy on push with GitHub
155+
156+
The [GitHub integration](/compute/github) reads the same root config. On each push, Prisma discovers the targets and starts one build per app. Each build uses its target's `root`, framework, entrypoint, port, region, and build settings.
157+
158+
Connect the linked project once:
159+
160+
```npm title="Terminal"
161+
npx @prisma/cli@latest git connect
162+
```
163+
164+
For a custom CI pipeline, set `PRISMA_SERVICE_TOKEN` and `PRISMA_PROJECT_ID`, then name the config target positionally:
165+
166+
```bash title="CI"
167+
PRISMA_SERVICE_TOKEN=... PRISMA_PROJECT_ID=... \
168+
npx @prisma/cli@latest app deploy web \
169+
--branch "${GITHUB_HEAD_REF:-$GITHUB_REF_NAME}" \
170+
--json \
171+
--no-interactive
172+
```
173+
174+
Run one command per target when your pipeline needs independent jobs. Use a bare `app deploy` when one job should deploy the entire monorepo.
175+
176+
## What to read next
177+
178+
- [Configuration](/compute/configuration): all config fields and precedence rules.
179+
- [GitHub integration](/compute/github): deploy-on-push and preview branches.
180+
- [Environment variables](/compute/environment-variables): production, preview, and branch-specific values.
181+
- [Deployments](/compute/deployments): inspect, promote, and roll back deployments.

0 commit comments

Comments
 (0)