feat: document prisma compute config

Author: AmanVarshney01

prisma-compute/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: prisma-compute
-description: Prisma Compute deployment and hosting guide. Use whenever the user mentions Prisma Compute, deploying or hosting a Prisma app, `@prisma/cli app deploy`, `compute:deploy`, `create-prisma --deploy`, `PRISMA_SERVICE_TOKEN`, Compute apps/deployments/logs/domains, localhost vs `0.0.0.0`, deploy port binding, or framework deploy readiness for Hono, Elysia, Next.js, TanStack Start, Astro, Nuxt, Svelte, Nest, or Turborepo.
+description: Prisma Compute deployment and hosting guide. Use whenever the user mentions Prisma Compute, `prisma.compute.ts`, `defineComputeConfig`, deploying or hosting a Prisma app, `@prisma/cli app deploy`, `compute:deploy`, `create-prisma --deploy`, `PRISMA_SERVICE_TOKEN`, Compute apps/deployments/logs/domains, localhost vs `0.0.0.0`, deploy port binding, or framework deploy readiness for Hono, Elysia, Next.js, TanStack Start, Astro, Nuxt, Svelte, Nest, or Turborepo.
 license: MIT
 metadata:
   author: prisma
@@ -35,7 +35,7 @@ Set `PRISMA_COMPUTE_RUNNER=bunx` to use `bunx` instead of `npx`.
 
 Prefer evidence that matches the user's project and installed tooling:
 
-1. The project's generated scripts and config, especially `compute:deploy`, `prisma.app.json`, framework config, and `package.json`.
+1. The project's generated scripts and config, especially `prisma.compute.ts`, `compute:deploy`, framework config, and `package.json`.
 2. Current CLI help output from `create-prisma` and `@prisma/cli`.
 3. Local installed package code, generated artifacts, and type definitions.
 4. Official docs or launch notes, especially after Compute is public.
@@ -48,6 +48,7 @@ Use this skill for:
 
 - Creating a new app that can deploy to Prisma Compute
 - Deploying an existing TypeScript app to Prisma Compute
+- Creating or updating a typed `prisma.compute.ts` deploy config
 - Deciding whether a framework is Compute-ready
 - Debugging `create-prisma --deploy`, `compute:deploy`, or `app deploy`
 - Managing Compute app logs, deployments, environment variables, branches, and domains
@@ -59,16 +60,19 @@ Use this skill for:
 1. Existing project deployment or redeploy:
    Read [`references/app-deploy-cli.md`](references/app-deploy-cli.md).
 
-2. Framework-specific build/runtime work:
+2. Typed Compute config, monorepos, deploy targets, app roots, or build/env defaults:
+   Read [`references/compute-config.md`](references/compute-config.md).
+
+3. Framework-specific build/runtime work:
    Read [`references/frameworks.md`](references/frameworks.md).
 
-3. New project from a scaffold:
+4. New project from a scaffold:
    Read [`references/create-prisma.md`](references/create-prisma.md).
 
-4. Programmatic deployment, SDKs, APIs, or low-level service/version concepts:
+5. Programmatic deployment, SDKs, APIs, or low-level service/version concepts:
    Read [`references/sdk-api.md`](references/sdk-api.md).
 
-5. Build, auth, env, deploy, or runtime failures:
+6. Build, auth, env, deploy, or runtime failures:
    Read [`references/troubleshooting.md`](references/troubleshooting.md).
 
 ## Rules by Priority
@@ -78,9 +82,10 @@ Use this skill for:
 | 1 | Command verification | CRITICAL | `verify-` |
 | 2 | Framework readiness | CRITICAL | `framework-` |
 | 3 | Runtime host and port binding | CRITICAL | `runtime-` |
-| 4 | Branch, environment, and database wiring | HIGH | `env-` |
-| 5 | Deploy operations | HIGH | `deploy-` |
-| 6 | SDK and API automation | MEDIUM | `sdk-` |
+| 4 | Typed Compute config | HIGH | `config-` |
+| 5 | Branch, environment, and database wiring | HIGH | `env-` |
+| 6 | Deploy operations | HIGH | `deploy-` |
+| 7 | SDK and API automation | MEDIUM | `sdk-` |
 
 ## Quick Rules
 
@@ -91,11 +96,12 @@ Use this skill for:
 - `verify-prisma-vs-platform-cli` - Do not assume `prisma app deploy` exists in the ORM CLI; check whether the task should use `@prisma/cli`.
 - `verify-generated-scripts` - Prefer the generated `compute:deploy` script when a project already has one.
 - `verify-public-url` - After a real deploy, smoke-test the public deployment URL instead of trusting local or readiness-only checks.
+- `verify-config-support` - For `prisma.compute.ts`, verify current CLI help/source because published package help may lag the repo.
 
 ### 2. Framework Readiness
 
 - `framework-cli-first` - Evaluate deploy readiness against current `@prisma/cli app deploy`, not against what `create-prisma` can scaffold.
-- `framework-supported-cli-deploy` - Current CLI deploy framework keys are `nextjs`, `hono`, `tanstack-start`, and `bun`; verify help/source before using any other key.
+- `framework-supported-cli-deploy` - Current CLI source supports `nextjs`, `nuxt`, `astro`, `hono`, `tanstack-start`, and `bun`; verify installed help/source before relying on a key.
 - `framework-create-prisma-defaults-only` - `create-prisma` can provide generated defaults and `compute:deploy`, but it is not the general deploy surface for existing apps.
 - `framework-build-output` - Compute needs a server entrypoint or framework artifact, not only static output.
 
@@ -105,7 +111,15 @@ Use this skill for:
 - `runtime-match-http-port` - The app must listen on the deployed HTTP port: read `process.env.PORT` when possible, or pass the matching `--http-port`.
 - `runtime-readiness-port-only` - Compute readiness watches listening ports; a loopback-only listener can look ready while public ingress cannot reach it.
 
-### 4. Branch, Environment, and Database
+### 4. Typed Compute Config
+
+- `config-use-prisma-compute-ts` - Put reusable deploy defaults in `prisma.compute.ts` with `defineComputeConfig`, not in `prisma.config.ts` or legacy `prisma.app.json`.
+- `config-app-vs-apps` - Use `app` for a single deploy target and `apps` for monorepos or multi-app repos; define exactly one.
+- `config-targets` - In multi-app configs, `prisma-cli app deploy web` selects the `apps.web` target, while a bare deploy can deploy every target when the CLI supports deploy-all.
+- `config-no-project-branch-secrets` - Do not commit Workspace, Project, Branch, production intent, service tokens, or secret values in `prisma.compute.ts`; keep those in flags, `.prisma/local.json`, env storage, or CI secrets.
+- `config-flags-win` - Explicit deploy flags such as `--framework`, `--entry`, `--http-port`, and `--env` override matching config values.
+
+### 5. Branch, Environment, and Database
 
 - `env-do-not-leak-secrets` - Never print full `DATABASE_URL`, service tokens, or secret values.
 - `env-deploy-loads-dotenv` - The generated deploy script passes `--env .env`; ensure production values are present before deploy.
@@ -114,23 +128,23 @@ Use this skill for:
 - `env-branch-scope` - Branch deploys, branch env vars, and branch databases must use the same branch name; pass `--branch <git-name>` explicitly when targeting a preview branch.
 - `env-production-vs-preview` - Use `--role production` for production env, `--role preview` for preview template env, and `--branch <git-name>` for branch-specific overrides.
 
-### 5. Deploy Operations
+### 6. Deploy Operations
 
 - `deploy-prod-intent` - Use `--prod --yes` only when the user intends a production deploy.
 - `deploy-noninteractive-auth` - Non-interactive deploys need either stored CLI login or a supported service token env var; never print the token.
 - `deploy-json-for-agents` - Use `--json --no-interactive` for scripts and agent-readable output.
 
-### 6. SDK and API
+### 7. SDK and API
 
 - `sdk-use-cli-first` - Prefer `@prisma/cli app deploy` for app workflows; use `create-prisma` only to scaffold a new app unless the user is building lower-level automation.
 - `sdk-result-handling` - `@prisma/compute-sdk` returns `Result` values; check `isOk()`/`isErr()` instead of relying on exceptions.
 
 ## Preferred Workflow
 
-1. Inspect the project: package manager, template/framework, `package.json` scripts, Prisma version, Prisma client location, and existing `compute:deploy`.
+1. Inspect the project: package manager, template/framework, `package.json` scripts, Prisma version, Prisma client location, `prisma.compute.ts`, and existing `compute:deploy`.
 2. Verify CLI help output for the package actually being used, or run `scripts/verify-compute-surface.mjs` for the standard Compute surface check.
 3. Choose the path:
-   - existing app deploy: generated `compute:deploy` or `@prisma/cli app build/run/deploy`
+   - existing app deploy: `prisma.compute.ts` target, generated `compute:deploy`, or `@prisma/cli app build/run/deploy`
    - new app scaffold: `create-prisma`, then generated `compute:deploy` or `@prisma/cli app deploy`
    - low-level automation: `@prisma/compute-sdk` or Management API
 4. Check framework readiness plus host/port/env/runtime requirements, including project and branch scope.
@@ -142,6 +156,8 @@ Use this skill for:
 - Do not bury Compute deployment guidance in the generic `prisma-cli` skill.
 - Do not run `create-prisma` inside an existing app just to deploy it; use the generated `compute:deploy` script or `@prisma/cli app deploy`.
 - Do not tell users that every `create-prisma` template can auto-deploy.
+- Do not put Compute deploy defaults in `prisma.config.ts`; use `prisma.compute.ts` until the CLI ships a unified config shape.
+- Do not use legacy `prisma.app.json` for build settings; migrate custom build settings into `prisma.compute.ts`.
 - Do not deploy with placeholder `DATABASE_URL` values.
 - Do not assume `next start` is the Compute runtime path; Next.js deploys need standalone output.
 - Do not expose secret values from `.env`, CLI output, Management API responses, or logs.

prisma-compute/references/app-deploy-cli.md

@@ -22,6 +22,54 @@ pnpm dlx @prisma/cli@latest app deploy
 
 If a future Prisma ORM CLI exposes `prisma app deploy`, use the local project command after verifying `prisma app deploy --help`.
 
+## Typed Compute Config
+
+For reusable deploy defaults, prefer `prisma.compute.ts` over long command lines. Read [`compute-config.md`](compute-config.md) before creating or editing it.
+
+Minimal single-app config:
+
+```typescript
+import { defineComputeConfig } from "@prisma/compute-sdk/config";
+
+export default defineComputeConfig({
+  app: {
+    name: "api",
+    framework: "hono",
+    entry: "src/index.ts",
+    httpPort: 8080,
+    env: ".env",
+  },
+});
+```
+
+Monorepo config:
+
+```typescript
+import { defineComputeConfig } from "@prisma/compute-sdk/config";
+
+export default defineComputeConfig({
+  apps: {
+    web: { root: "apps/web", framework: "nextjs" },
+    api: {
+      root: "apps/api",
+      framework: "bun",
+      entry: "src/index.ts",
+      httpPort: 8080,
+      env: "apps/api/.env",
+    },
+  },
+});
+```
+
+Targeted deploys:
+
+```bash
+bunx @prisma/cli@latest app deploy web
+bunx @prisma/cli@latest app deploy api --branch feature/login --json
+```
+
+Config values are deploy defaults. Explicit flags such as `--framework`, `--entry`, `--http-port`, and `--env` override matching config values. `prisma.compute.ts` does not select Workspace, Project, Branch, database, or production scope; continue to use flags, project linking, env storage, and CI secrets for those.
+
 ## Auth and Project Binding
 
 Useful commands:
@@ -62,6 +110,12 @@ bunx @prisma/cli@latest project show --json
 bunx @prisma/cli@latest app deploy --project proj_123 --app my-api --branch feature/login --json
 ```
 
+If `prisma.compute.ts` defines a `name` or an `apps` key, that config can provide the app name. `--app` and `PRISMA_APP_ID` rank above the config value. `[app]` selects a target from `apps` when the installed CLI supports typed compute config:
+
+```bash
+bunx @prisma/cli@latest app deploy api --project proj_123 --branch feature/login --json
+```
+
 Branch scope must line up across deploys, databases, and env vars:
 
 - `app deploy --branch <git-name>` creates a deployment for that branch.
@@ -99,6 +153,8 @@ bunx @prisma/cli@latest project env remove STRIPE_KEY --role preview
 
 If the deploy should create and wire a Prisma Postgres database for the deploy target, current `app deploy` exposes `--db`; use `--no-db` to skip database setup. Treat any generated connection URL as a one-time secret.
 
+Database setup is not part of `prisma.compute.ts` in the current beta. Keep database intent explicit with `--db`, `--no-db`, `database create`, and project env commands.
+
 ## Build and Run Locally
 
 Before deploy, verify that the app can produce a Compute artifact:
@@ -115,6 +171,13 @@ bunx @prisma/cli@latest app build --build-type bun --entry src/index.ts
 bunx @prisma/cli@latest app run --build-type bun --entry src/index.ts --port 8080
 ```
 
+With a compute config, pass the target name instead of repeating framework/entry/port flags:
+
+```bash
+bunx @prisma/cli@latest app build api
+bunx @prisma/cli@latest app run api --port 8080
+```
+
 `app run --port` sets `PORT` for local development. It does not rewrite an app's explicit host binding, so a local run is not enough to prove the deployed server is reachable from ingress.
 
 ## Runtime Host and Port
@@ -209,6 +272,18 @@ bunx @prisma/cli@latest app deploy \
   --env .env
 ```
 
+Config-backed Bun-style app:
+
+```bash
+bunx @prisma/cli@latest app deploy api --prod --yes --env .env
+```
+
+Use config for stable app defaults, and flags for one-off project, branch, env, database, and production choices.
+
+## Legacy Config
+
+Do not create `prisma.app.json`. It is legacy and no longer the Compute app config path. If a project has custom build settings there, move them into the relevant `build` block in `prisma.compute.ts` and delete `prisma.app.json`.
+
 ## Operations
 
 Inspect and open: