Conceptos centrales de Prisma Composer
Una App Prisma es un árbol de declaraciones tipadas compuestas en TypeScript y entregadas a la CLI prisma, que tiene dos comandos de Composer: prisma deploy y prisma dev. El derribo y los logs no son comandos; son las operaciones destroy y log de @prisma/composer/control, llamadas desde un script. Este archivo cubre estructuras, jerarquías, relaciones y flujos de trabajo: los conceptos que no se pueden observar desde el código o la ayuda de la CLI. No es una referencia de la CLI; descubre las banderas de cada comando con prisma <command> --help en lugar de inferirlas. La plataforma Prisma avanza rápido, así que trata este archivo como el núcleo conceptual estable y encuentra la documentación actual y completa en https://www.prisma.io/docs. Para código funcional, lee examples/ en el repositorio prisma/composer.
Dos principios lo gobiernan todo y son vinculantes
(docs/design/01-principles/):
- Tu código nunca lee su entorno. Las dependencias, la configuración, las credenciales y el puerto llegan a través del nodo de servicio, tipado.
process.envnunca es la respuesta. - Composer nunca empaqueta ni transforma tu código. Tú construyes con tu propio empaquetador; el framework ensambla la salida construida mediante pasos deterministas y la entrega al destino de despliegue configurado.
Las declaraciones son datos
Todo lo que escribes es una declaración: datos simples que describen una pieza de la aplicación, que no ejecutan nada al importarse. Existen tres tipos de nodos:
| Tipo | Se declara con | Propósito |
|---|---|---|
| Servicio | compute() | Una unidad de código en ejecución; atómica, Composer solo ve sus puertos |
| Recurso | rawPostgres(), bucket() | Una dependencia gestionada con estado |
| Módulo | module() | Un límite de agrupación; no ejecuta código propio, expone puertos tipados |
Los nodos se conectan a través de puertos: deps declara lo que un nodo requiere, expose declara lo que ofrece. El cableado ocurre en el constructor de un Módulo mediante provision(), y el Módulo raíz, entregado a la CLI, es la App:
// module.ts
import { module } from '@prisma/composer';
export default module('store', ({ provision }) => {
const catalog = provision(catalogModule);
provision(storefrontService, { deps: { catalog: catalog.rpc } });
});
Como los puertos están tipados, el compilador verifica cada cable. Una dependencia conectada al productor incorrecto, un manejador RPC faltante, un valor de entrada literal con la forma incorrecta: todo falla en tsc, no en el despliegue. La entrada vinculada al entorno es la excepción: esos valores existen solo en el despliegue, por lo que los desajustes de enlace secreto y las variables de plataforma faltantes aparecen como rechazos tempranos en el despliegue (ver Dos canales a continuación). Verifica tipos, luego construye, luego despliega; no uses la nube para descubrir si el cableado es correcto.
Composer en sí mismo es independiente del destino: @prisma/composer lleva la autoría, las pruebas y la CLI, sin acoplarse a ninguna plataforma. Un destino de despliegue es una extensión registrada en la configuración de despliegue; @prisma/composer-prisma-cloud es el destino Prisma Cloud y el que asumen las secciones de despliegue de esta skill. Sus exportaciones raíz son compute, rawPostgres, bucket, envSecret y envParam; el vocabulario ORM (postgres, dataContract) vive bajo la subruta /orm, junto con los módulos compartidos /cron, /storage, /streams, /auth y /email. Estos son los únicos dos paquetes de Composer que necesita una app básica de Prisma Cloud, y nada los instala por ti: un proyecto nuevo comienza sin ninguno, así que agrega ambos como dependencias primero. Una extensión agrega su propio paquete prisma-composer-* junto a ellos. Compón un Módulo existente antes de implementar una capacidad tú mismo; cablear uno son un par de líneas.
Dentro del grafo de entrada (todo lo alcanzable desde module.ts), escribe importaciones relativas con extensiones .ts explícitas (./service.ts, con allowImportingTsExtensions en tsconfig): esa forma se resuelve en todas partes. prisma deploy y prisma dev también asignan ./service.js y ./service sin extensión a la fuente .ts, pero otras herramientas pueden no hacerlo.
El nodo de servicio es la única puerta de entrada
Tu código en tiempo de ejecución recibe todo desde la declaración de servicio que importa:
service.load(): dependencias (clientes RPC tipados, enlaces de base de datos).service.input(): toda la entrada como un objeto validado por esquema; las credenciales en él son cajasSecretStringque se redactan.service.port(): el puerto reservado para enlazar (por defecto 3000).
Una declaración de servicio son datos puros; el punto de entrada del servidor es lo que tu compilación produce y la plataforma arranca:
// service.ts
export default compute({
name: 'auth',
deps: { db: rawPostgres() },
build: node({ module: import.meta.url, entry: '../dist/server.mjs' }),
expose: { rpc: authContract },
});
// server.ts
const { db } = service.load(); // { url }: construyes tu propio cliente
const handler = serve(service, {
rpc: { verify: async ({ token }) => ({ ok: token.length > 0 }) },
});
Bun.serve({ port: service.port(), hostname: '0.0.0.0', fetch: handler });
El consumidor declara deps: { auth: rpc(authContract) } y obtiene un cliente tipado de load().
Dos canales: dependencias y entrada
| El valor es… | Declara | Proporciona | Lee |
|---|---|---|---|
| producido por otro nodo | deps: { db: rawPostgres() } | cablea en provision() | load() |
| cualquier otra cosa (configuración o credencial) | un campo del esquema input | enlaza en provision(): literal, envParam() o envSecret() | input() |
El servicio declara toda su configuración entrante, valores simples y credenciales juntos, como un Standard Schema (arktype es la elección de la casa). Una credencial es un campo tipado como secretString() de @prisma/composer/arktype; la legalidad condicional ("sin clave de stripe a menos que la facturación esté activa") es una unión de esquema ordinaria. El enlace en provision() refleja la forma del esquema; envSecret('NAME') nombra la variable de plataforma y nunca lleva el valor.
Reglas que muerden:
- El secreto se aplica mediante validación. Un literal enlazado donde el esquema espera
SecretStringfalla el despliegue;envSecretenlazado a un campo de cadena simple falla de la misma manera. - Los valores de
envParamllegan como cadenas sin procesar; enlázalos a campos de cadena. La variable de plataforma del stage es el almacén; el shell de despliegue solo siembra un nombre faltante (y el despliegue falla temprano, nombrando la variable, cuando ambos faltan). Cambiar el valor de la plataforma necesita un redespliegue. - La ausencia es decisión del esquema. Un campo vinculado al entorno cuya variable no está establecida o está vacía se resuelve como clave omitida, lo cual es legal solo si el esquema lo permite (campo opcional, rama de unión). El informe de despliegue imprime el documento de entrada serializado (los secretos viajan como punteros
{"$secret":"VAR"}) y cada clave que se resolvió ausente. - El
portreservado está fuera del esquema. Léelo a través deservice.port(), nunca deprocess.env. El framework también exportaPORTpara Next.js standalone, que lo enlaza por sí mismo. - Un Módulo reenvía una necesidad secreta sin conocer el nombre de la plataforma. Declara
secrets: { signingKey: secret() }en el límite del Módulo y pasa la referencia reenviada como una hoja de enlace; el padre enlaza la fuente real. input.apiKey.expose()es la única forma de acceder al valor de un secreto; la caja redacta en todos los demás lugares (logs, JSON, errores).
Contratos y RPC
Un contrato es la interfaz tipada a través de la cual se comunican los servicios. Vive con el servicio que lo posee, tipado por cualquier validador Standard Schema, y tanto el proveedor (serve(), exhaustivo sobre los métodos del contrato en tiempo de compilación) como el consumidor (rpc(contract)) referencian el mismo valor. Las llamadas viajan como RPC sobre HTTP. Dos comportamientos se aprovisionan por ti y no deben ser reimplementados:
- Claves de servicio. En el despliegue, Composer acuña una clave única e inescrutable por enlace consumidor→proveedor;
serve()devuelve401a cualquier otra cosa antes de que el manejador se ejecute. Nada en tu código lo declara. Consecuencias: no construyas tu propia autenticación servicio a servicio, y no hagascurla un/rpc/<method>desplegado para verificar que funciona. Un llamador no cableado siempre obtiene401, que parece un despliegue roto y no lo es. Depura a través de un consumidor, o localmente, donde no se aplica nada. Las claves son por enlace (una fuga no puede hacerse pasar por otro consumidor), con ámbito de servicio (cualquier clave válida alcanza todos los métodos; divide los servicios para controlar por separado), se rotan solo eliminando el enlace o destruyendo el stack y redeployando, y se almacenan en variablesCOMPOSER_*propiedad del despliegue que nunca editas a mano. - Idempotencia y reintentos. Cada llamada de cliente generado lleva una
Idempotency-Key; las llamadas descartadas se reintentan con backoff, yserve()ejecuta una llamada por clave, repitiendo la respuesta completada a reintentos tardíos. Por lo tanto, cada método es seguramente reintentable y ningún contrato declara nada al respecto (no hay una bandera "es idempotente"; no inventes una). Un manejador puede tomar un tercer argumento opcional(input, deps, ctx)y leerctx.idempotencyKey(string | undefined) si necesita exactamente-una-vez más allá de la memoria de una instancia; la mayoría no lo necesita. Localmente y en pruebas no se aprovisiona nada, así queserve()pasa cada llamada: nunca proporciones una clave en las entradas de prueba.
Los builds son tuyos
Tú construyes, el framework ensambla. Para un proceso de servidor simple, entry debe apuntar a un único archivo ESM autocontenido: todo inline excepto los built-ins del runtime (bun, bun:*, node:*). El despliegue copia ese único archivo y nunca envía node_modules, así que cualquier cosa que quede sin inline falla en el arranque, no en el despliegue. Reglas que muerden:
- Dos servicios en un mismo paquete significan dos builds separados, uno por entrada. Un build de múltiples entradas divide el código compartido en un chunk que ninguna salida contiene.
- Un build de directorio usa
dir+entry(dirrelativo al módulo de servicio,entryun archivo dentro dedir;../es un error). El árbol se copia textualmente, así que el servidor debe resolver los hermanos contraimport.meta.url, no el directorio de trabajo. El árbol no debe contener symlinks: el empaquetador los rechaza, nombra el enlace y el ensamblaje falla. - Next.js:
next buildconoutput: 'standalone'es todo el build;nextjs({ module, appDir })nombra la raíz de la app. Cualquier página o acción que llame aload()necesitaexport const dynamic = 'force-dynamic', porque el entorno de ejecución no existe en tiempo de build y Next ignora el entorno de ejecución para rutas prerenderizadas. - Siempre construye antes de
deployodev. Ninguno construye por ti.
La configuración de despliegue es la sección composer de prisma.config.ts, y nada más. Registra extensiones (prismaCloud(), nodeBuild(), nextjsBuild() cuando la app tiene un servicio Next.js) y el backend de estado de despliegue (prismaState()):
// prisma.config.ts
import { defineConfig as composer } from '@prisma/composer/config';
import { nodeBuild } from '@prisma/composer/node/control';
import { prismaCloud, prismaState } from '@prisma/composer-prisma-cloud/control';
import { definePrismaConfig } from 'prisma/config';
export default definePrismaConfig({
composer: composer({ extensions: [prismaCloud(), nodeBuild()], state: prismaState() }),
});
Los comandos encuentran prisma.config.ts desde el directorio en el que se ejecutan, subiendo hasta la raíz del repositorio; el archivo más cercano que declara composer gana, y su sección se usa completa, nunca fusionada clave por clave. Solo se permiten extensions y state; cualquier otra clave es un error. El código de la app nunca importa el archivo.
Un prisma-composer.config.ts separado ya no se lee, y la configuración antigua es rechazada, nunca ignorada silenciosamente: CONFIG.SECTION_MISSING cuando ningún prisma.config.ts cargado declara una sección composer, CONFIG.FIELD_RETIRED cuando la sección todavía tiene configPath, CONFIG.FILE_RETIRED cuando un prisma-composer.config.* se encuentra junto al prisma.config.ts declarante; los tres bajo el CLI.CONFIG_SECTION_INVALID de la CLI. La solución para los tres es mover las extensions y state del archivo antiguo a la sección y eliminar el archivo antiguo. @prisma/composer-cli/family ya no exporta ComposerSection; el tipo de la sección es PrismaAppConfig de @prisma/composer/config.
Bases de datos y migraciones
Dos tipos de dependencia Postgres:
rawPostgres(): el enlace es{ url }y la app posee su cliente.postgres(...): una base de datos tipada por Prisma ORM. El enlace es{ url, client }(ADR-0040): la URL de conexión sin procesar más el cliente tipado que Composer construye desde tu contrato de datos, de forma perezosa en el primer acceso, así que las consultas van a través debinding.clienty se verifican en tiempo de compilación. TantopostgrescomodataContractse importan de@prisma/composer-prisma-cloud/orm, no de la raíz del paquete. Un valor envuelto pordataContract(emitido desdecontract.prismaporprisma contract emit) es referenciado tanto por el extremo de dependencia (deps: { db: postgres(catalogData) }) como por el extremo del recurso, que también nombra la ruta deprisma.config.tspara que el paso de migración del despliegue pueda recargar elcontract.jsonemitido y encontrarmigrations/.
Los despliegues son solo-reproducción: aplican las migraciones confirmadas bajo migrations/ y nunca crean esquema por sí mismos. Cada cambio de esquema, incluido el primer esquema de una nueva base de datos, sigue un bucle:
- Edita
contract.prisma. prisma contract emitregeneracontract.json+contract.d.ts.prisma migration plan --name <slug>autoriza la migración (en un grafo vacío, esto autoriza la línea base).- Confirma
migrations/con el cambio, luego despliega. Una base de datos nueva reproduce toda la ruta desde vacía.
Cada servicio que usa la base de datos se despliega solo después de que su migración se completa: una migración fallida significa que el nuevo código no se envía. El código antiguo sirve contra el nuevo esquema hasta que el nuevo despliegue esté activo, así que mantén cada migración compatible con el código que reemplaza.
Si ninguna ruta autorizada alcanza el contrato objetivo, el despliegue (y dev contra una base de datos local desactualizada) se niega con MIGRATION_PATH_NO
…
[truncado para traducción]