Prisma Composer Agent Skill

Writing apps with Prisma Composer

A Prisma App is a tree of Modules composed in TypeScript. The leaves

are services (compute()) and resources (postgres()); the root

module wires them together by their typed ports. Your code receives everything

from exactly one place — the service node:

• service.load() — dependencies (typed RPC clients, database bindings)
• service.input() — the service's whole input, one schema-validated typed

object; credentials in it are redacting SecretString boxes

• service.port() — the reserved port to bind (default 3000), typed; never

process.env

The framework never bundles or transforms your code. You build your app with

whatever bundler you like (bun build, next build); prisma-composer deploy

assembles the built output and provisions it on Prisma Cloud (Compute + Prisma

Postgres).

Two things make building here fast and hard to get wrong — lean on both:

• Compose before you write. Reach for an existing Module (below) before

implementing a capability yourself; wiring one in is a couple of lines.

• The compiler checks the wiring. A dependency wired to the wrong

producer, a missing RPC handler, a config value of the wrong shape — all of

it fails tsc, not the deploy. Typecheck, then build, then deploy; don't

reach for the cloud to find out whether the app is correct.

Two packages, and only two, appear in your package.json:

| Package | Provides |

| --- | --- |

| @prisma/composer | Core authoring: module, secret, isSecretString, /arktype (the secretString() schema leaf), /rpc, /node, /nextjs, /config, /testing, the prisma-composer CLI |

| @prisma/composer-prisma-cloud | The Prisma Cloud target: compute, postgres, envSecret, envParam, /control, /testing, and the shared /cron, /storage, /streams, /prisma-next modules |

Anatomy of a service

A service is four small files. Worked example: an auth service that owns a

Postgres database and serves an RPC contract, consumed by a storefront

Next.js app.

The contract lives with the service that owns it. Any Standard Schema

validator types the messages; arktype is the house choice:

// auth/src/contract.ts
import { contract, rpc } from '@prisma/composer/service-rpc';
import { type } from 'arktype';

export const authContract = contract({
  verify: rpc({ input: type({ token: 'string' }), output: type({ ok: 'boolean' }) }),
});

The service declaration is pure data — name, dependencies, build, exposed

ports. No behavior, no platform keys:

// auth/src/service.ts
import node from '@prisma/composer/node';
import { compute, postgres } from '@prisma/composer-prisma-cloud';
import { authContract } from './contract.ts';

export default compute({
  name: 'auth',
  deps: { db: postgres() },
  build: node({ module: import.meta.url, entry: '../dist/server.mjs' }),
  expose: { rpc: authContract },
});

The server entry is what your build produces and the platform boots. It

reads its dependencies through load() and serves the contract with

serve() — the handler map is keyed by the expose port's name and is

exhaustive at compile time:

// auth/src/server.ts
import { serve } from '@prisma/composer/service-rpc';
import { SQL } from 'bun';
import service from './service.ts';

const { db } = service.load(); // { url } — you build your own client
const port = service.port();   // the reserved port, resolved (default 3000)

const sql = new SQL({ url: db.url, max: 1, idleTimeout: 10 });

const handler = serve(service, {
  rpc: {
    verify: async ({ token }) => ({ ok: token.length > 0 }),
  },
});
export default handler;

// Bind all interfaces — Compute routes external HTTP to the VM; a
// loopback-only listener is unreachable.
Bun.serve({ port, hostname: '0.0.0.0', fetch: handler });

The consumer declares the dependency as rpc(contract) and gets a typed

client back from load():

// storefront/src/service.ts
import nextjs from '@prisma/composer/nextjs';
import { rpc } from '@prisma/composer/service-rpc';
import { compute } from '@prisma/composer-prisma-cloud';
import { authContract } from '@my-app/auth/contract';

export default compute({
  name: 'storefront',
  deps: { auth: rpc(authContract) },
  build: nextjs({ module: import.meta.url, appDir: '..' }),
});

// storefront/app/page.tsx
import service from '../src/service.ts';

// load() reads the runtime environment, which doesn't exist at build time —
// render per request instead of prerendering.
export const dynamic = 'force-dynamic';

export default async function Home() {
  const { auth } = service.load();
  const { ok } = await auth.verify({ token: 'demo-token' });
  return <p>Signed in: {String(ok)}</p>;
}

Service-to-service calls are authenticated for you. At deploy the

framework mints a distinct, unguessable service key per consumer→provider

binding: the consumer's client sends it on every call, and serve() returns

401 to anything else *before* the handler runs. Nothing declares it — no key

in the contract, the service, the module, or the app's code.

Two rules follow for you specifically: **don't build your own

service-to-service auth on top of this, and don't tell a user to curl a

deployed /rpc/<method> to check it works** — an unwired caller always gets

401, which looks like a broken deploy and isn't. Debug through a consumer,

or locally.

Calls carry an idempotency key and retry safely for you. Every call the

generated client makes carries an Idempotency-Key; a call dropped while the

target cold-starts is retried with a backoff, and serve() runs one call per

key — a retry that arrives after the first completed replays that answer

instead of re-running the handler. So every method is safely retryable and no

contract declares anything about it (do not add an "is this idempotent" flag —

the framework does not have one). Two consequences for you: a handler may take

an optional third argument (input, deps, ctx) and read ctx.idempotencyKey

(string | undefined — it's absent for a keyless caller) if it needs exactly-once

beyond one instance's memory (most don't); and a request without the header is

served once without deduplication rather than rejected, so a hand-rolled probe

works but gets no retry safety.

| | |

| --- | --- |

| Locally / in tests | nothing is provisioned, so serve() passes every call through — never supply a key in inputs |

| Per binding | two consumers of one provider hold different keys, so one leaking can't impersonate the other |

| Scope | service-level — any valid key reaches every method that service exposes; split into two services to gate separately |

| Rotation | remove the binding (or destroy the stack) and redeploy — a plain redeploy is a no-op, not a rotation |

| Storage | COMPOSER_* variables the deploy owns and rewrites; never hand-edit one |

It's a capability token ("I'm a service this app wired to you"), not a secret,

and its value lives in deploy state — deliberately unlike secret(), whose

value the framework never holds. docs/design/90-decisions/ADR-0030… in the

prisma/composer repo carries the reasoning.

The root module

The root module provisions the pieces and wires exposed ports into dependency

slots. It is the app — prisma-composer deploy loads its default export:

// module.ts
import { module } from '@prisma/composer';
import authModule from '@my-app/auth';
import storefrontService from '@my-app/storefront';

export default module('my-app', ({ provision }) => {
  const auth = provision(authModule);
  provision(storefrontService, { deps: { auth: auth.rpc } });
});

provision(node, opts?) accepts id (defaults to the node's own name),

deps (wire each declared dependency to a provisioned ref or exposed port),

input (the service's input binding — required exactly when it declares an

input schema, see § Service input), and secrets (bind a module boundary's

forwarded secret needs).

Builds are yours

The framework assembles only what you built — users build, the framework

assembles. For a plain server process, entry must point at a single

self-contained ESM file: everything inlined except runtime built-ins (bun,

bun:*, node:*), which the deploy VM provides. Deploy copies that one file

and never ships node_modules, so anything left un-inlined fails at boot. Any

bundler that produces such a file works. With bun:

bun build src/server.ts --target=bun --outfile dist/server.mjs

Two services in one package means two separate builds, one per entry — not one

multi-entry build, which would split shared code into a chunk neither output

contains.

If the build emits a directory rather than one file — a server plus the client

bundle, CSS and images it serves, as Bun's HTML import produces — name the

directory with dir and the booting file inside it with entry:

build: node({ module: import.meta.url, dir: '../dist/server', entry: 'server.js' })

dir resolves relative to the service module; entry resolves inside dir

and may be nested. Deploy copies the tree verbatim and boots the named file,

so the server must resolve its siblings against import.meta.url, not the

working directory. Nothing is inferred, and two rules bite: the tree must

contain no symlinks (the packager rejects them — assembly fails and names the

link), and entry must be a file inside dir (../ is an error, not an

escape). Omit dir for the single-file form.

For Next.js, next build with output: 'standalone' is the whole build;

nextjs({ module, appDir }) tells the deploy where the app root is.

Always build before deploying — prisma-composer deploy does not build for

you.

Deploy config

prisma-composer.config.ts sits next to module.ts. It is read only by

prisma-composer deploy/destroy, never imported by app code:

// prisma-composer.config.ts
import { defineConfig } from '@prisma/composer/config';
import { nodeBuild } from '@prisma/composer/node/control';
import { prismaCloud, prismaState } from '@prisma/composer-prisma-cloud/control';

export default defineConfig({
  extensions: [prismaCloud(), nodeBuild()],
  state: () => prismaState(), // deploy state, in its own database on the stage's branch
});

Add nextjsBuild() from @prisma/composer/nextjs/control to extensions

when the app contains a Next.js service.

Databases

Two kinds of Postgres dependency:

postgres() — the binding is { url } and the app owns its client.

Construct it in your server entry, as in the auth example above.

pnPostgres(...) — a Prisma Next-typed database: load()

returns the typed client the framework constructs from your data contract, so

queries like db.orm.public.Product.all() are compile-time checked. The

contract is emitted from contract.prisma by prisma-next contract emit and

wrapped once, referenced by both ends:

// src/data.ts — the ONE value both ends reference
import { pnContract } from '@prisma/composer-prisma-cloud/prisma-next';
import type { Contract } from '../contract.d.ts';
import contractJson from '../contract.json' with { type: 'json' };

export const catalogData = pnContract<Contract>(contractJson);

The dependency end is deps: { db: pnPostgres(catalogData) }. The resource

end (inside the module that owns the database) also names the

prisma-next.config.ts path, which the deploy's migration step loads to find

migrations/ — migrations are applied at deploy, before the service starts:

const db = provision(
  pnPostgres({ name: 'database', contract: catalogData, config: './prisma-next.config.ts' }),
);

(pnPostgres is both ends: the contract alone is the dependency end; the

options object is the resource end.)

See examples/store/modules/catalog in the prisma/composer repo for the

complete pattern.

Object Storage

bucket is a raw S3-compatible object-store bucket, imported alongside postgres:

import { bucket, compute } from '@prisma/composer-prisma-cloud';

// service.ts — dependency end: receives { url, bucket, accessKeyId, secretAccessKey }
export default compute({ name: 'uploads', deps: { store: bucket() } });

// module.ts — resource end: provisions the bucket and mints a keypair
const store = provision(bucket({ name: 'uploads' }));
provision(uploadsService, { deps: { store } });

Use any S3-compatible client with the binding: the shape matches the standard S3

config and is also compatible with the s3() dependency from /storage, so any

service wired to s3() can be rewired to a bucket resource without changing

the service declaration.

Reusable Modules

A Module is the unit of reuse: it owns its internals (its database, its

services) and exposes only typed ports. Declare the boundary in the second

argument; wire internals in the builder; return the exposed ports:

// auth/src/module.ts — a Module that owns its own Postgres
import { module, secret } from '@prisma/composer';
import { postgres } from '@prisma/composer-prisma-cloud';
import { authContract } from './contract.ts';
import authService from './service.ts';

export default module(
  'auth',
  { secrets: { signingKey: secret() }, expose: { rpc: authContract } },
  ({ secrets, provision }) => {
    const db = provision(postgres({ name: 'database' }));
    const service = provision(authService, {
      id: 'service',
      deps: { db },
      input: { signingKey: secrets.signingKey }, // forwarded ref as a binding leaf
    });
    return { rpc: service.rpc };
  },
);

Naming rules that bite: a provision id shorter than 3 characters is rejected

by the platform (name the database 'database', not 'db'), and a service

whose name equals its enclosing module's reads as auth.auth unless you give

it an explicit id.

A module can also declare boundary deps — inputs the parent wires exactly as

it would wire a service's. The consumer never sees the module's internals.

The building blocks you can compose

Modules are the building blocks: provision one, wire its exposed port, and

you're done — you never reimplement what a Module already owns. The

first-party set ships inside @prisma/composer-prisma-cloud. It's small, and

growing:

| Import | What it provisions | Exposes |

| --- | --- | --- |

| cron from /cron | An always-on scheduler firing your schedule at your runner service | nothing |

| storage from /storage | An S3-backed blob store (own Postgres + minted credentials) | store |

| streams from /streams | Durable append-only event streams over a store | streams |

Finding more. A Composer extension — a package that brings its own

Modules, resources, or deploy target — is published on npm under the name

prisma-composer-*. That name is the convention, so it's how you look for

one. The ecosystem is new: today the blocks above plus the app Modules you

write are the whole set, so don't reach for a prisma-composer-* package

without checking that it actually exists on npm first.

Cron end to end — the schedule is one source of truth; serveSchedule is

exhaustive over its job ids at compile time:

// service.ts
import { defineSchedule, triggerContract } from '@prisma/composer-prisma-cloud/cron';
export const schedule = defineSchedule({ tick: '60s' });
// the runner service exposes { trigger: triggerContract }

// server.ts
import { serveSchedule } from '@prisma/composer-prisma-cloud/cron';
const handler = serveSchedule(service, schedule, {
  tick: (deps) => deps.worker.tick({}),
});

// module.ts — the cron module's boundary deps mirror the runner's own
provision(cron({ schedule, runner: runnerService }), { deps: { worker: worker.rpc } });

Service input

Choosing the channel is most of the decision:

| The value is… | Declare | Provide | Read |

| --- | --- | --- | --- |

| produced by another node | deps: { db: postgres() } | wire at provision() | load() |

| anything else — config or credential | one field of the input schema | bind at provision(): literal, envParam(), or envSecret() | input() |

The service declares its whole incoming configuration — plain values and

credentials together — as **one

Standard Schema** (arktype is the house

choice). A credential is a field typed as the redacting SecretString box;

conditional legality ("no stripe key unless billing is on") is an ordinary

schema union:

// service.ts — the shapes that are legal
import { secretString } from '@prisma/composer/arktype';
import { type } from 'arktype';

compute({
  name: 'scheduler',
  input: type({
    jobs: type({ jobId: 'string', every: 'string' }).array(),
    'region?': 'string',
    apiKey: secretString(),
  }),
  // ...
});

// module.ts — where each value comes from; the binding mirrors the schema's shape
import { envParam, envSecret } from '@prisma/composer-prisma-cloud';
provision(scheduler, {
  input: {
    jobs: [{ jobId: 'tick', every: '60s' }],   // a literal
    region: envParam('REGION'),                 // a per-stage platform variable
    apiKey: envSecret('SCHEDULER_API_KEY'),     // a credential — name only, never the value
  },
});

// server.ts — one call, one validated typed object
const input = service.input();
input.apiKey.expose(); // the only way to a secret's value; the box redacts everywhere else

Rules that bite:

• Secretness is enforced by validation: a literal bound where the schema

expects SecretString fails the deploy, and envSecret bound to a plain

string field fails the same way. Don't put credentials in plain fields.

• envParam values arrive as raw strings — bind them to string fields.

The stage's platform variable is the store; the deploying shell only seeds

it (preflight copies a missing name up from the shell, and fails early,

naming the variable, when both lack it). Changing the platform value needs

a redeploy.

• Absence is the schema's call: an env-bound field whose variable is

unset (or empty) resolves to *key omitted* — legal only if the schema says

so (optional field, union arm). The deploy report prints the serialized

input document (secret-free: secrets ride as {"$secret":"VAR"} pointers)

and every key that resolved absent.

• The reserved port (default 3000) is outside the schema — read it

through service.port() (a sibling of service.origin()), never

process.env. The framework also exports PORT for Next.js standalone,

which binds it itself.

• A module forwards a secret need without learning the platform name

(the auth Module above); the forwarded ref is a binding leaf.

examples/env-param and examples/storefront-auth in the prisma/composer

repo are the working versions.

Testing

You test by deciding what load() gives the code, never by editing the code

under test:

| You want to… | Use | From |

| --- | --- | --- |

| Test a page / action / handler in isolation | mockService | @prisma/composer/testing |

| Run the real boot + request path against a fake dependency | bootstrapService | @prisma/composer-prisma-cloud/testing |

Unit — mockService. Returns a copy of the service whose load() yields

your doubles (type-checked against the declared deps) and whose input()

yields the object you pass under the reserved input key, in one flat

object (required exactly when the service declares an input schema; handed

over as-is, not validated). Wiring the module substitution is your runner's

job (vi.mock in Vitest, mock.module in bun test):

// page.test.tsx
import { mockService } from '@prisma/composer/testing';
import realService from '../src/service.ts';

vi.mock('../src/service.ts', () => ({
  default: mockService(realService, {
    auth: { verify: async () => ({ ok: true }) }, // wrong shape = compile error
  }),
}));

import Page from './page.tsx';
expect(renderToString(await Page())).toContain('Signed in: true');

Integration — bootstrapService. Boots the service's real built entry

in-process against a config you choose, exactly as a deployed boot would;

drive it over real HTTP. Run under bun test:

import { bootstrapService } from '@prisma/composer-prisma-cloud/testing';
import fakeAuth from '@my-app/auth/fake'; // in-memory handler, no db
import storefront from '../src/service.ts';

const fake = Bun.serve({ port: 0, fetch: fakeAuth });

const app = await bootstrapService(storefront, {
  service: { port: 4310 },
  inputs: { auth: { url: fake.url.href } },
});

const res = await app.fetch(new Request(app.url));

• service.port must be concrete — the entry self-listens; no OS-assigned

port is reported back.

• No close() — run each integration-test file in its own process (bun

test does).

• Next.js services take a third argument, a boot thunk, because the built

entry lives in Next's standalone output — resolve it with

standaloneServerPath from @prisma/composer/nextjs/control.

bootstrapService exports the resolved port as process.env.PORT before

booting, which is what Next's standalone server binds.

• A service with an input schema takes input in the config — a binding

exactly like provision()'s, run through the real serialize/read path, so

input() in the booted entry sees what a deploy would produce.

The fake you pass. A dependency's type is its contract, so any value of

that shape is a valid double: a bare object (fastest), the real client over an

in-memory handler, or a real local server (what bootstrapService drives).

Ship a dependency's fake from its own package as a /fake entry point,

outside src/, so the fake and the real service always share one contract.

Running locally

prisma-composer dev module.ts runs the whole app on this machine — every

service, its Postgres and buckets, wired as they deploy — with **no cloud

credentials** (no PRISMA_*). It runs the same pipeline as deploy against

local emulators, so build first, exactly like deploy:

turbo run build && prisma-composer dev module.ts

It prints each service's local URL (the "front door"), watches built output

and restarts a service when its build changes, and runs until Ctrl-C. Ctrl-C

stops the app's processes but leaves the local databases, buckets, and their

data up, so the next dev is a warm start; --fresh wipes this app's local

instances and data first.

dev does not print service logs — that would bury the front door once

several services run. Logs are their own command:

| You want to… | Run |

| --- | --- |

| Run the app locally | prisma-composer dev module.ts |

| Start clean (wipe local data) | prisma-composer dev module.ts --fresh |

| Tail every service's logs | prisma-composer log module.ts |

| Tail one service | prisma-composer log module.ts <address> |

| Show more history first | prisma-composer log module.ts --tail <n> |

prisma-composer log follows the merged logs of the already-running app, each

line prefixed with its service ([catalog.service] …); pass a dotted address

to narrow to one. It only reads — it never builds, provisions, starts, or

stops anything. --tail <n> sets how much recent history to show before live

output (default 20; 0 for live-only). An unset secret doesn't block a local

run: it becomes a placeholder plus a warning, and only the code path that

spends it fails, at the real external service it calls. Windows isn't

supported yet.

Deploying

Requires exactly two environment variables: PRISMA_SERVICE_TOKEN and

PRISMA_WORKSPACE_ID. The target environment — a stage — is chosen on the

command line, never in code:

| You want to… | Run |

| --- | --- |

| Deploy to production | prisma-composer deploy module.ts |

| Deploy an isolated environment | prisma-composer deploy module.ts --stage <name> |

| Override the app name for one run | prisma-composer deploy module.ts --name demo-42 |

| Tear down an isolated environment | prisma-composer destroy module.ts --stage <name> |

| Tear down production's resources | prisma-composer destroy module.ts --production |

A Prisma App is one Project; a stage is a Branch of it — its

own compute, its own empty database, its own configuration. Deploys are

idempotent: re-deploying a stage updates the resources inside it. A stage name

must be a valid git ref name; an invalid name is a hard error.

Destroy always requires an explicit target — a bare prisma-composer destroy

is an error, and --stage with --production is too. Destroying a stage

deletes its Branch after removing its resources; the production Branch itself

is never deleted, only the resources inside it. Destroying production also

deletes the Project itself once it's empty, so hand-run stacks don't leave

behind empty Projects — but a Project still holding another stage's resources

is kept. Destroy never creates anything: destroying a never-deployed stage

fails rather than standing one up.

turbo run build && prisma-composer deploy module.ts --stage pr-42

What a deploy prints

A deploy ends by printing the app's own topology — authored names, the

platform resource each became, and public URLs. The tree is the module

structure (auth.api is the api service inside the auth module):

storefront-auth
├─ auth
│  └─ api   compute-service cps_abc123
│           https://xyz.ewr.prisma.build
├─ db       postgres-database db_def456
└─ web      compute-service cps_ghi789
            https://uvw.ewr.prisma.build

Read ids out of this rather than telling the user to go hunting in the

Console. A URL appears only where the address is genuinely public — a compute

service prints one, a database never does (it has a connection string, not a

public endpoint), and a node whose product is secret material (an

s3-credentials keypair) reports no resource line at all. A node that

published nothing reportable still appears, marked (no entities reported).

Older deploys ended with a raw { outputs: {} } blob from the deploy engine —

always empty, never about the app. It is gone; nothing configured it and

nothing consumed it.

The connection contract is checked at deploy

A connection declares the values it needs by name, and the producer on the

other end must supply them. A producer that omits one fails the deploy, naming

the edge, the param, and what the producer did supply:

Connection input "auth.db" declares param "url", but its producer "db" did not
supply it — the producer's outputs carry [host].

Fix it at whichever end is wrong: add the name to the outputs the producer

returns from its lowering, or mark the param optional on the connection if absent is

genuinely legal (the consumer then reads undefined).

This is a deploy-time refusal, not a broken deploy — and it can appear on an

app whose code didn't change. The gap used to pass silently: the value reached

the consumer as undefined, went into its environment, and crashed *that*

service at boot, blaming the reader instead of the supplier. Don't route around

it by making the param optional unless absent really is valid; that reinstates

the silent undefined.

Only reachable if you authored the connection or the extension on one side —

every shipped block supplies what it declares.

Production pitfalls

• Scale-to-zero closes idle database connections. A persistent client

crashes into a 502 restart loop unless you keep the pool small and

reconnect-friendly (new SQL({ url, max: 1, idleTimeout: 10 }) for Bun) and

log uncaughtException/unhandledRejection instead of dying.

• Bind 0.0.0.0, not loopback — Compute routes external HTTP to the VM.
• **Next.js pages that call load() need `export const dynamic =

'force-dynamic'`** — the runtime environment doesn't exist at build time,

and Next ignores runtime env for prerendered routes.

• A deployed /rpc/<method> returns 401 to anything but a wired peer.

Every RPC binding carries an auto-provisioned service key, so a hand-rolled

curl is never authorized, and a provider with no wired consumers rejects

everything. Not a broken deploy — reach it through a consumer, or run it

locally where nothing is enforced.

• Cold starts reset service-to-service connections. A call into a

scaled-to-zero service can get ECONNRESET; retry it.

• **Every prisma-composer command stops at start-up on an effect version

conflict** (Dependency conflict: alchemy resolves effect@...). Another

dependency floated a newer effect and the package manager hoisted it over

Composer's pin. Do what the error says: add

"overrides": { "effect": "<required>" } to the app's package.json

(yarn: resolutions; pnpm: pnpm.overrides) and reinstall.

• The ingress buffers streaming responses. An open SSE tail delivers

nothing and times out at 60s — don't build on streamed HTTP responses.

What Composer doesn't do yet

Name the gap instead of inventing an API:

• No interactive auth. Deploys authenticate only via a static

PRISMA_SERVICE_TOKEN; there is no login flow.

• No in-memory contract bindings. A dependency can't yet be wired to a

co-located handler without HTTP; use bootstrapService with a loopback

fake.

• RPC over HTTP is the only contract kind. No gRPC, WebSocket, or

streaming contracts.

For anything else missing, check the examples and design docs in the

prisma/composer repo (examples/, docs/design/10-domains/,

docs/design/90-decisions/), then file an issue there rather than guessing.