From d7db5dcf7ee10aa6d985336600d8617c074ead17 Mon Sep 17 00:00:00 2001 From: Aman Varshney Date: Thu, 16 Jul 2026 17:08:20 +0530 Subject: [PATCH 1/2] docs(compute): add monorepo deployment guide --- .../content/docs/compute/configuration.mdx | 3 +- apps/docs/content/docs/compute/github.mdx | 11 +- apps/docs/content/docs/compute/meta.json | 1 + apps/docs/content/docs/compute/monorepos.mdx | 181 ++++++++++++++++++ 4 files changed, 189 insertions(+), 7 deletions(-) create mode 100644 apps/docs/content/docs/compute/monorepos.mdx diff --git a/apps/docs/content/docs/compute/configuration.mdx b/apps/docs/content/docs/compute/configuration.mdx index cb617e5538..5e38ff2b42 100644 --- a/apps/docs/content/docs/compute/configuration.mdx +++ b/apps/docs/content/docs/compute/configuration.mdx @@ -143,7 +143,7 @@ The config file's directory is treated as the project directory: the [`.prisma/l ## Monorepos -Use `apps` instead of `app` to declare several apps in one repository, keyed by a target name: +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). ```ts title="prisma.compute.ts" 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, ## What's next +- [Deploy a monorepo](/compute/monorepos): configure, verify, and deploy several apps from one repository. - [CLI reference](/compute/cli-reference): every command, flag, and error code. - [Deploy your first app](/prisma-compute/deploy): the end-to-end quickstart. - [Environment variables](/compute/environment-variables): scoped configuration, secrets, and your database connection string. diff --git a/apps/docs/content/docs/compute/github.mdx b/apps/docs/content/docs/compute/github.mdx index cdc1030c56..12c0f2800a 100644 --- a/apps/docs/content/docs/compute/github.mdx +++ b/apps/docs/content/docs/compute/github.mdx @@ -58,13 +58,12 @@ Connecting doesn't deploy anything on its own; it wires up automation for *futur ## CI and monorepos -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: +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: -```bash -PRISMA_SERVICE_TOKEN=... npx @prisma/cli@latest app deploy \ - --project my-app \ - --app web \ - --branch "$GITHUB_HEAD_REF" \ +```bash title="CI" +PRISMA_SERVICE_TOKEN=... PRISMA_PROJECT_ID=... \ + npx @prisma/cli@latest app deploy web \ + --branch "${GITHUB_HEAD_REF:-$GITHUB_REF_NAME}" \ --json \ --no-interactive ``` diff --git a/apps/docs/content/docs/compute/meta.json b/apps/docs/content/docs/compute/meta.json index 9a606f5fb0..2992d41d01 100644 --- a/apps/docs/content/docs/compute/meta.json +++ b/apps/docs/content/docs/compute/meta.json @@ -9,6 +9,7 @@ "---Features---", "branching", "deployments", + "monorepos", "keeping-instances-awake", "image-transformations", "environment-variables", diff --git a/apps/docs/content/docs/compute/monorepos.mdx b/apps/docs/content/docs/compute/monorepos.mdx new file mode 100644 index 0000000000..0f4e5bbb10 --- /dev/null +++ b/apps/docs/content/docs/compute/monorepos.mdx @@ -0,0 +1,181 @@ +--- +title: Monorepos +description: Deploy several apps from one repository with a root-level Prisma Compute config. +url: /compute/monorepos +metaTitle: Deploy a monorepo | Prisma Compute +metaDescription: Configure, build, and deploy multiple apps from a monorepo with prisma.compute.ts and Prisma Compute. +--- + +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. + +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. + +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. + +## Example repository + +This guide uses a Next.js frontend and a Hono API: + +```text title="Repository structure" +acme-shop/ +├── apps/ +│ ├── api/ +│ │ ├── src/index.ts +│ │ └── package.json +│ └── web/ +│ ├── app/ +│ ├── next.config.ts +│ └── package.json +├── package.json +├── pnpm-workspace.yaml +└── prisma.compute.ts +``` + +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. + +## 1. Add the Compute config + +Create `prisma.compute.ts` at the monorepo root: + +```ts title="prisma.compute.ts" +import { defineComputeConfig } from "@prisma/compute-sdk/config"; + +export default defineComputeConfig({ + apps: { + web: { + root: "apps/web", + framework: "nextjs", + }, + api: { + root: "apps/api", + framework: "hono", + entry: "src/index.ts", + httpPort: 3000, + }, + }, +}); +``` + +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. + +Paths have two different bases: + +- `root` is relative to `prisma.compute.ts`. +- `entry` and build output paths are relative to that app's `root`. + +`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`. + +The Next.js app in this example also enables standalone output: + +```ts title="apps/web/next.config.ts" +export default { output: "standalone" }; +``` + +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. + +## 2. Verify every app locally + +Build each target from the repository root before deploying: + +```npm title="Terminal" +npx @prisma/cli@latest app build web +npx @prisma/cli@latest app build api +``` + +`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. + +From inside a configured `root`, the CLI infers the target, so this builds `api` too: + +```npm title="Terminal" +cd apps/api +npx @prisma/cli@latest app build +``` + +If roots overlap, the deepest matching root wins. Prefer non-overlapping roots unless that behavior is intentional. + +## 3. Deploy one app + +Pass the target key as the positional argument: + +```npm title="Terminal" +npx @prisma/cli@latest app deploy web +``` + +To deploy the API instead: + +```npm title="Terminal" +npx @prisma/cli@latest app deploy api +``` + +You can also run the command from inside an app's `root` and omit the target: + +```npm title="Terminal" +cd apps/web +npx @prisma/cli@latest app deploy +``` + +:::warning + +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. + +::: + +## 4. Deploy the whole monorepo + +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: + +```npm title="Terminal" +npx @prisma/cli@latest app deploy +``` + +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: + +```npm title="Terminal" +npx @prisma/cli@latest app deploy --branch feature/search +``` + +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: + +```npm title="Terminal" +npx @prisma/cli@latest app deploy api --env apps/api/.env.preview +``` + +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. + +## Command summary + +| Goal | Run from the monorepo root | +| --- | --- | +| Build one app | `npx @prisma/cli@latest app build web` | +| Deploy one app | `npx @prisma/cli@latest app deploy web` | +| Deploy every app | `npx @prisma/cli@latest app deploy` | +| Deploy every app to a preview branch | `npx @prisma/cli@latest app deploy --branch feature/search` | + +## Deploy on push with GitHub + +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. + +Connect the linked project once: + +```npm title="Terminal" +npx @prisma/cli@latest git connect +``` + +For a custom CI pipeline, set `PRISMA_SERVICE_TOKEN` and `PRISMA_PROJECT_ID`, then name the config target positionally: + +```bash title="CI" +PRISMA_SERVICE_TOKEN=... PRISMA_PROJECT_ID=... \ + npx @prisma/cli@latest app deploy web \ + --branch "${GITHUB_HEAD_REF:-$GITHUB_REF_NAME}" \ + --json \ + --no-interactive +``` + +Run one command per target when your pipeline needs independent jobs. Use a bare `app deploy` when one job should deploy the entire monorepo. + +## What to read next + +- [Configuration](/compute/configuration): all config fields and precedence rules. +- [GitHub integration](/compute/github): deploy-on-push and preview branches. +- [Environment variables](/compute/environment-variables): production, preview, and branch-specific values. +- [Deployments](/compute/deployments): inspect, promote, and roll back deployments. From 9df504d4284443f720254048a0b47accac051eb2 Mon Sep 17 00:00:00 2001 From: Aman Varshney Date: Thu, 16 Jul 2026 17:14:04 +0530 Subject: [PATCH 2/2] docs(compute): centralize monorepo guidance --- .../docs/(index)/prisma-compute/deploy.mdx | 5 +- .../content/docs/compute/cli-reference.mdx | 2 +- .../content/docs/compute/configuration.mdx | 46 ++----------------- apps/docs/content/docs/compute/faq.mdx | 4 +- apps/docs/content/docs/compute/github.mdx | 14 +----- .../docs/content/docs/compute/limitations.mdx | 2 +- 6 files changed, 12 insertions(+), 61 deletions(-) diff --git a/apps/docs/content/docs/(index)/prisma-compute/deploy.mdx b/apps/docs/content/docs/(index)/prisma-compute/deploy.mdx index e50d47cc0a..578cbe8811 100644 --- a/apps/docs/content/docs/(index)/prisma-compute/deploy.mdx +++ b/apps/docs/content/docs/(index)/prisma-compute/deploy.mdx @@ -156,7 +156,7 @@ Make sure your project directory is a Git repository with a GitHub remote, then npx @prisma/cli@latest git connect ``` -`git connect` wires up the project this directory is linked to, which exists once you have deployed at least once. For monorepos and CI, see the [GitHub integration docs](/compute/github). +`git connect` wires up the project this directory is linked to, which exists once you have deployed at least once. For a repository with several apps, see [Deploy a monorepo](/compute/monorepos). For integration details, see the [GitHub docs](/compute/github). ## Hand it to your agent @@ -185,5 +185,6 @@ Notes for your agent: - [Branching](/compute/branching): how preview branches isolate work and map to your Git branches. - [Add environment variables](/compute/environment-variables) for configuration, secrets, and your database connection string. - [Deployments](/compute/deployments): promote, roll back, and inspect what you ship. -- [GitHub integration](/compute/github): the full picture on deploy-on-push, monorepos, and cleanup. +- [Deploy a monorepo](/compute/monorepos): configure, verify, and deploy several apps from one repository. +- [GitHub integration](/compute/github): the full picture on deploy-on-push and cleanup. - [Read the full CLI getting-started guide](/compute/getting-started) for frameworks, project linking, and CI. diff --git a/apps/docs/content/docs/compute/cli-reference.mdx b/apps/docs/content/docs/compute/cli-reference.mdx index a376f483ab..462341d18e 100644 --- a/apps/docs/content/docs/compute/cli-reference.mdx +++ b/apps/docs/content/docs/compute/cli-reference.mdx @@ -61,7 +61,7 @@ Manage apps and deployments for a project. | `app rollback` | Roll back production to the previous deployment, without rebuilding | | `app remove` | Remove the app from the current branch | -Promote and rollback switch the live endpoint between existing deployments; nothing is rebuilt, and env vars stay as resolved when each deployment was created. Most `app` commands also accept an optional `[app]` positional argument to pick a target from `prisma.compute.ts` when the config defines multiple apps. +Promote and rollback switch the live endpoint between existing deployments; nothing is rebuilt, and env vars stay as resolved when each deployment was created. Most `app` commands also accept an optional `[app]` positional argument to pick a target from `prisma.compute.ts` when the config defines multiple apps. See [Deploy a monorepo](/compute/monorepos) for target setup and workflows. ### `app deploy` options diff --git a/apps/docs/content/docs/compute/configuration.mdx b/apps/docs/content/docs/compute/configuration.mdx index 5e38ff2b42..2af909d146 100644 --- a/apps/docs/content/docs/compute/configuration.mdx +++ b/apps/docs/content/docs/compute/configuration.mdx @@ -9,7 +9,7 @@ metaDescription: "Reference for the prisma.compute.ts file: declare your app's f `prisma.compute.ts` is an optional, committed file that declares what you deploy. [`app deploy`](/compute/cli-reference#app) already works with zero config (it detects your framework and builds), so reach for a config file when you want one of these: - **Reproducible deploys.** Pin the framework, port, and build settings so every deploy (yours, a teammate's, or [deploy-on-push](/compute/github)) does the same thing without re-passing flags. -- **A monorepo.** Declare several apps in one repository and deploy them together, or one at a time. +- **A monorepo.** [Declare several apps](/compute/monorepos) in one repository and deploy them together, or one at a time. - **Type safety.** Catch a typo'd field or an invalid framework in your editor, before you deploy. The file is read by `app deploy` and `app build`. It never selects your project, branch, or production; those stay explicit. It also does not configure a database; that stays on the [`--db` flag](/compute/cli-reference#app-deploy-options). @@ -143,47 +143,7 @@ The config file's directory is treated as the project directory: the [`.prisma/l ## Monorepos -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). - -```ts title="prisma.compute.ts" -import { defineComputeConfig } from "@prisma/compute-sdk/config"; - -export default defineComputeConfig({ - apps: { - api: { - root: "apps/api", - framework: "hono", - entry: "src/index.ts", - }, - web: { - root: "apps/web", - framework: "nextjs", - }, - }, -}); -``` - -All the apps live in one project, deploying to the same branch. From here: - -- **Deploy everything** with a bare `app deploy`, which deploys every app in order. This is the default when no target is named or inferred: - - ```npm - npx @prisma/cli@latest app deploy - ``` - -- **Deploy one app** by naming its target, or by running from inside its `root` (the deepest matching root wins): - - ```npm - npx @prisma/cli@latest app deploy api - ``` - - ```npm - cd apps/api && npx @prisma/cli@latest app deploy - ``` - -When you deploy everything at once, per-app flags like `--framework` or `--entry` are rejected as ambiguous. Pass a target to apply them to one app. Project- and branch-level flags (`--branch`, `--db`, `--prod`, `--yes`) apply to the whole run. - -`app build` always targets a single app in a multi-app config. Unlike `deploy`, it has no all-apps form, so pass a target or run from inside the app's `root`. +Use `apps` instead of `app` to declare several apps in one repository. Each map key is a CLI target, and every target accepts the same fields listed above. See [Deploy a monorepo](/compute/monorepos) for the complete config, directory layout, target selection, local builds, deploy-all behavior, and GitHub automation. ## How config and flags interact @@ -203,4 +163,4 @@ A config that fails to load or validate stops the deploy before any remote work, - [CLI reference](/compute/cli-reference): every command, flag, and error code. - [Deploy your first app](/prisma-compute/deploy): the end-to-end quickstart. - [Environment variables](/compute/environment-variables): scoped configuration, secrets, and your database connection string. -- [GitHub integration](/compute/github): deploy-on-push, including monorepos. +- [GitHub integration](/compute/github): deploy-on-push and branch previews. diff --git a/apps/docs/content/docs/compute/faq.mdx b/apps/docs/content/docs/compute/faq.mdx index e7a2d09670..9296fe252e 100644 --- a/apps/docs/content/docs/compute/faq.mdx +++ b/apps/docs/content/docs/compute/faq.mdx @@ -57,7 +57,7 @@ No. Variables resolve at deploy time, so you need to redeploy for the app to pic ## How do I deploy from CI? -Use a service token and explicit targets: +Use a service token and name the remote project and app explicitly: ```bash PRISMA_SERVICE_TOKEN=... npx @prisma/cli@latest app deploy \ @@ -68,7 +68,7 @@ PRISMA_SERVICE_TOKEN=... npx @prisma/cli@latest app deploy \ --no-interactive ``` -Passing every target explicitly keeps the run self-contained; `--json` makes the result parseable, and `--no-interactive` turns any would-be prompt into a structured error. +Passing every selector explicitly keeps the run self-contained; `--json` makes the result parseable, and `--no-interactive` turns any would-be prompt into a structured error. For multiple config targets in one repository, follow [Deploy a monorepo](/compute/monorepos). ## Why did my production deploy fail with `PROD_DEPLOY_REQUIRES_FLAG`? diff --git a/apps/docs/content/docs/compute/github.mdx b/apps/docs/content/docs/compute/github.mdx index 12c0f2800a..379dfc556c 100644 --- a/apps/docs/content/docs/compute/github.mdx +++ b/apps/docs/content/docs/compute/github.mdx @@ -56,19 +56,9 @@ Once a project is connected: Connecting doesn't deploy anything on its own; it wires up automation for *future* events. To deploy right now, run `app deploy` yourself. -## CI and monorepos +## Monorepos -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: - -```bash title="CI" -PRISMA_SERVICE_TOKEN=... PRISMA_PROJECT_ID=... \ - npx @prisma/cli@latest app deploy web \ - --branch "${GITHUB_HEAD_REF:-$GITHUB_REF_NAME}" \ - --json \ - --no-interactive -``` - -This keeps deploys deterministic and gives agents a structured result to read. +A connected repository can deploy several Compute apps from each push. See [Deploy a monorepo](/compute/monorepos) for the root `prisma.compute.ts` config, build fan-out, target selection, and custom CI commands. ## What's not in beta diff --git a/apps/docs/content/docs/compute/limitations.mdx b/apps/docs/content/docs/compute/limitations.mdx index 2bf17269ff..f3ba3fe7cd 100644 --- a/apps/docs/content/docs/compute/limitations.mdx +++ b/apps/docs/content/docs/compute/limitations.mdx @@ -38,7 +38,7 @@ Prisma Compute is in [Public Beta](/console/more/feature-maturity#public-beta). ## GitHub - GitHub is the only supported provider, and a project connects to one repository. -- Auto-deploy supports multiple apps declared in `prisma.compute.ts`: one push build fans out into a targeted build per app. CI with a service token remains available when you need full control. +- Auto-deploy supports [multiple apps declared in a monorepo config](/compute/monorepos). - The webhook path is branch- and push-driven. There are no PR comments or PR status automation. ## Domains