docs(docs): fix Compute production/preview, promote, and framework support docs#8032
Conversation
…pport docs Linear: DR-8720 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
🍈 Lychee Link Check Report52 links: ✅ All links are working!Full Statistics Table
|
WalkthroughDocumentation across Prisma Compute pages was updated to clarify that production versus preview environments are resolved from branch context ( ChangesCompute Documentation Updates
Estimated code review effort: 2 (Simple) | ~12 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
Comment |
|
The latest updates on your projects. Learn more about Argos notifications ↗︎
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
apps/docs/content/docs/compute/limitations.mdx (1)
20-25: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win"production and default branches" implies two distinct concepts.
Per this file's own line 20, the production branch is the default branch. "left alone" phrasing on line 24 reads as if these could differ.
✏️ Suggested tweak
-- Deleting a branch on GitHub can tear down the matching platform branch, but production and default branches are always left alone. +- Deleting a branch on GitHub can tear down the matching platform branch, but the production (default) branch is always left alone.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@apps/docs/content/docs/compute/limitations.mdx` around lines 20 - 25, Clarify the wording in the limitations copy so “production branch” and “default branch” are not treated as separate concepts, since the text already says the production branch is the default branch. Update the relevant sentences in the documentation content to use one consistent term or explicitly say “production/default branch” where needed, and keep the behavior notes for app deploy, app promote, branch list, and branch deletion aligned with that single definition.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@apps/docs/content/docs/compute/deployments.mdx`:
- Around line 121-135: The “Promote and roll back” section in deployments.mdx
should be made branch-neutral because the current wording in the `app promote`
example and surrounding text implies only production deployments and production
environment variables. Update the prose around `app promote` so it matches the
branch-scoped behavior described later in the same section and in the `app
promote` documentation: make clear it rebuilds using the current branch’s
environment variables (production on the production branch, preview on preview
branches) and still note that the rebuild is required before verifying the live
result.
In `@apps/docs/content/docs/compute/limitations.mdx`:
- Around line 28-30: Clarify the framework support wording in the limitations
doc so it does not imply that all accepted `app deploy --framework` values are
dedicated framework integrations. Update the copy near the `app deploy
--framework` and `app build --build-type` descriptions in the limitations
content to distinguish the dedicated frameworks from the generic fallback values
(`bun` and `custom`), and make the text consistent with the support matrix
described elsewhere (for example, the dedicated support list used in
getting-started). Use the existing `app deploy --framework` and `app build
--build-type` references to keep the wording accurate and unambiguous.
---
Nitpick comments:
In `@apps/docs/content/docs/compute/limitations.mdx`:
- Around line 20-25: Clarify the wording in the limitations copy so “production
branch” and “default branch” are not treated as separate concepts, since the
text already says the production branch is the default branch. Update the
relevant sentences in the documentation content to use one consistent term or
explicitly say “production/default branch” where needed, and keep the behavior
notes for app deploy, app promote, branch list, and branch deletion aligned with
that single definition.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: b861884c-7cb1-4cbd-92fb-e71bfea6409b
📒 Files selected for processing (7)
apps/docs/content/docs/compute/branching.mdxapps/docs/content/docs/compute/cli-reference.mdxapps/docs/content/docs/compute/deployments.mdxapps/docs/content/docs/compute/environment-variables.mdxapps/docs/content/docs/compute/faq.mdxapps/docs/content/docs/compute/getting-started.mdxapps/docs/content/docs/compute/limitations.mdx
| ## Promote and roll back | ||
|
|
||
| Promote an earlier deployment to production: | ||
| Promote an earlier **production** deployment back to live: | ||
|
|
||
| ```npm | ||
| npx @prisma/cli@latest app promote dep_123 --app web | ||
| ``` | ||
|
|
||
| Promotion rebuilds the deployment with your production environment variables. The rebuild is necessary because values are baked in at deploy time: a preview build still carries preview config, so it can't serve production as-is. | ||
| Promotion rebuilds the deployment with your current production environment variables. The rebuild is necessary because values are baked in at deploy time, so an old build can't pick up new config as-is. Because it rebuilds, verify the result serves correctly afterwards — `app logs` or a request to the live URL. | ||
|
|
||
| `app promote` works within one branch. It has no `--branch` flag; the branch comes from your active Git branch (or `main` outside a repo), and the deployment id must belong to that branch's app. It cannot move a preview deployment to production: | ||
|
|
||
| - From a preview Git branch, promote resolves the *preview* app. Promoting that branch's live deployment succeeds with the warning `The selected deployment is already live for this app` and changes nothing. | ||
| - From the production branch, a preview deployment id fails with `DEPLOYMENT_NOT_FOUND`. | ||
|
|
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Promote intro contradicts its own branch-scoped clarification below.
Line 123 frames promote as acting on a "production deployment," and line 129 says it rebuilds with "your current production environment variables." But lines 131-135 (and cli-reference.mdx's app promote row, plus the FAQ) clarify promote is branch-scoped and, run from a preview branch, uses that branch's preview env vars — not production ones. The opening framing should be branch-neutral to avoid misleading preview-branch users.
📝 Suggested rewording
-Promote an earlier **production** deployment back to live:
+Promote an earlier deployment of the current branch's app back to live:
```npm
npx `@prisma/cli`@latest app promote dep_123 --app web-Promotion rebuilds the deployment with your current production environment variables. The rebuild is necessary because values are baked in at deploy time, so an old build can't pick up new config as-is. Because it rebuilds, verify the result serves correctly afterwards — app logs or a request to the live URL.
+Promotion rebuilds the deployment with the current branch's environment variables (production variables on the production branch, preview variables plus overrides elsewhere). The rebuild is necessary because values are baked in at deploy time, so an old build can't pick up new config as-is. Because it rebuilds, verify the result serves correctly afterwards — app logs or a request to the live URL.
</details>
<!-- suggestion_start -->
<details>
<summary>📝 Committable suggestion</summary>
> ‼️ **IMPORTANT**
> Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
```suggestion
## Promote and roll back
Promote an earlier deployment of the current branch's app back to live:
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@apps/docs/content/docs/compute/deployments.mdx` around lines 121 - 135, The
“Promote and roll back” section in deployments.mdx should be made branch-neutral
because the current wording in the `app promote` example and surrounding text
implies only production deployments and production environment variables. Update
the prose around `app promote` so it matches the branch-scoped behavior
described later in the same section and in the `app promote` documentation: make
clear it rebuilds using the current branch’s environment variables (production
on the production branch, preview on preview branches) and still note that the
rebuild is required before verifying the live result.
| - `app deploy --framework` accepts `nextjs`, `nuxt`, `astro`, `hono`, `nestjs`, `tanstack-start`, `custom`, and `bun`. This list is exhaustive: no other framework has dedicated support. | ||
| - Frameworks not on the list (Elysia, Express, Fastify, and anything else that runs as a plain HTTP server) deploy with `--framework bun --entry <server-file>`. They get no framework-specific handling: the server must bind `0.0.0.0`, listen on the deployed port, and bundle any files it reads at runtime. | ||
| - `app build --build-type` accepts `auto`, `bun`, `nextjs`, `nuxt`, `astro`, `nestjs`, `tanstack-start`, and `custom`. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
"Exhaustive... dedicated support" claim conflates fallback flag values with dedicated framework support.
Line 28 lists all 8 accepted --framework values (including custom and bun) and asserts "no other framework has dedicated support" — implying these 8 all have dedicated support. But bun and custom are the generic fallback path (as line 29 itself describes: "no framework-specific handling"), and getting-started.mdx explicitly limits dedicated build support to 6 frameworks (Next.js, Nuxt, Astro, Hono, NestJS, TanStack Start). This contradicts the framework-support clarification that's the point of this PR.
✏️ Suggested rewording
-- `app deploy --framework` accepts `nextjs`, `nuxt`, `astro`, `hono`, `nestjs`, `tanstack-start`, `custom`, and `bun`. This list is exhaustive: no other framework has dedicated support.
+- `app deploy --framework` accepts `nextjs`, `nuxt`, `astro`, `hono`, `nestjs`, `tanstack-start`, `custom`, and `bun`. Dedicated build support exists only for the first six; `custom` and `bun` are the fallback path for everything else.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - `app deploy --framework` accepts `nextjs`, `nuxt`, `astro`, `hono`, `nestjs`, `tanstack-start`, `custom`, and `bun`. This list is exhaustive: no other framework has dedicated support. | |
| - Frameworks not on the list (Elysia, Express, Fastify, and anything else that runs as a plain HTTP server) deploy with `--framework bun --entry <server-file>`. They get no framework-specific handling: the server must bind `0.0.0.0`, listen on the deployed port, and bundle any files it reads at runtime. | |
| - `app build --build-type` accepts `auto`, `bun`, `nextjs`, `nuxt`, `astro`, `nestjs`, `tanstack-start`, and `custom`. | |
| - `app deploy --framework` accepts `nextjs`, `nuxt`, `astro`, `hono`, `nestjs`, `tanstack-start`, `custom`, and `bun`. Dedicated build support exists only for the first six; `custom` and `bun` are the fallback path for everything else. | |
| - Frameworks not on the list (Elysia, Express, Fastify, and anything else that runs as a plain HTTP server) deploy with `--framework bun --entry <server-file>`. They get no framework-specific handling: the server must bind `0.0.0.0`, listen on the deployed port, and bundle any files it reads at runtime. | |
| - `app build --build-type` accepts `auto`, `bun`, `nextjs`, `nuxt`, `astro`, `nestjs`, `tanstack-start`, and `custom`. |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@apps/docs/content/docs/compute/limitations.mdx` around lines 28 - 30, Clarify
the framework support wording in the limitations doc so it does not imply that
all accepted `app deploy --framework` values are dedicated framework
integrations. Update the copy near the `app deploy --framework` and `app build
--build-type` descriptions in the limitations content to distinguish the
dedicated frameworks from the generic fallback values (`bun` and `custom`), and
make the text consistent with the support matrix described elsewhere (for
example, the dedicated support list used in getting-started). Use the existing
`app deploy --framework` and `app build --build-type` references to keep the
wording accurate and unambiguous.
2 participants
What changed and why
Docs audit driven by real user + agent deployment feedback (a Glitch-style Elysia app port that went sideways). Every behavioral claim below was verified today against a live Compute app with
@prisma/cli@latest; nothing is inferred from old docs.Verified behaviors that contradicted the docs
app deploy --prodfrom a non-default Git branch silently creates a preview deployment.--prodconfirms production, it doesn't select it; branch resolution (--branch→ active Git branch →main) decides the environment, and the CLI doesn't warn. The JSON output even reports"promoted": true(live-within-branch), which reads like a production promotion.app promoteis same-branch only. From a preview Git branch it no-ops with the warningThe selected deployment is already live for this app; from the production branch a preview deployment id fails withDEPLOYMENT_NOT_FOUND. Preview→production promotion is impossible; the old text implied otherwise. It also has no--branchflag (nor doesapp remove) — branch context is Git-only.--frameworkacceptsnextjs, nuxt, astro, hono, nestjs, tanstack-start, custom, bun;app build --build-typeacceptsauto, bun, nextjs, nuxt, astro, nestjs, tanstack-start, custom(checked against CLI validation errors). "First-class support" wording removed — an agent extrapolated it into claiming Elysia has first-class support. The docs now state the dedicated list is exhaustive and that everything else (Elysia, Express, Fastify, …) deploys as a plain Bun server with no framework-specific handling.Page-by-page
--prod; promote section rewritten with same-branch semantics, the two failure modes, the correct path to production, and what to do when promote "does nothing"; new troubleshooting section "The deploy succeeded but the app only serves an error page" (bind0.0.0.0, listen onprocess.env.PORT, runtime-read files must ship in the artifact, repro withapp build/app run) — none of this was documented anywhere.--prod+ branch resolution.--prodandapp promotelimitations; corrected framework/build-type lists; stated the generic-Bun-server path explicitly.--prodfrom a non-default branch still gets preview vars, and how to check viabranch.kind.app deploy --prod. Why did I get a preview deployment?" and "Why didapp promotedo nothing?".--prodbranch-context note.How it was tested
Content-only MDX change. CLI behavior verified against a live project: deployed
--prodfrom a throwaway non-default branch (got"kind": "preview"), exercised promote from both branch contexts (observed the no-op warning andDEPLOYMENT_NOT_FOUND), extracted flag enums from CLI validation errors, and cleaned the test branch up afterwards.Follow-ups / known limitations
--prodis passed but the resolved branch is a preview?app promoteof a valid production deployment also returned a transientDEPLOY_FAILED(Internal Server Error) that succeeded on retry — and the rebuilt old deployment served 404s until rollback, which is worth a look.prisma-computeagent skill should get the same corrections so agents stop overclaiming framework support.Linear: DR-8720
🤖 Generated with Claude Code
Summary by CodeRabbit
--proddoes.