prisma/prisma-compute

Prisma Compute

Guía a los agentes a través de la creación, despliegue, operación y preparación para frameworks específicos de aplicaciones Prisma Compute.

Superficie CLI de Prisma Compute

Usa la CLI de la Plataforma Prisma para los flujos de trabajo de aplicaciones Compute:

bunx @prisma/cli@latest app deploy --help
bunx @prisma/cli@latest app --help
bunx @prisma/cli@latest build logs --help
bunx create-prisma@latest --help

Usa @prisma/cli@latest para el despliegue de aplicaciones Compute. Usa create-prisma@latest para el andamiaje de nuevos proyectos.

Enviar Comentarios y Reportar Problemas de la CLI

La CLI tiene un canal de comentarios incorporado. Úsalo cada vez que un comando falle (UNEXPECTED_ERROR), un error persista después de solucionar problemas, o el usuario solicite enviar comentarios al equipo de Prisma:

bunx @prisma/cli@latest feedback "app deploy crashed: <primera línea de error>"
bunx @prisma/cli@latest feedback "me encanta el flujo de despliegue" --email [email protected]

La salida de un fallo señala esto por sí misma: los sobres de fallo --json llevan el comando exacto pre-llenado como una entrada recover en nextActions (ejecútalo textualmente), y la salida de fallo legible termina con una sugerencia Cuéntanos qué pasó:. Los comentarios son anónimos a menos que se pase --email y adjunta solo la versión de la CLI, la versión de Node y la plataforma/arquitectura del SO. Nunca incluyas secretos, URLs de conexión o datos de usuario en el mensaje.

Orden de Fuentes de Verdad

Usa la evidencia en este orden al decidir qué editar o ejecutar:

1. Los scripts generados y la configuración del proyecto, especialmente prisma.compute.ts, compute:deploy, la configuración del framework y package.json.
2. La salida de ayuda de la CLI de create-prisma y @prisma/cli.
3. El código del paquete instalado localmente, los artefactos generados y las definiciones de tipos.
4. Documentación oficial.

Cuándo Aplicar

Usa esta habilidad para:

• Crear una nueva aplicación que pueda desplegarse en Prisma Compute
• Desplegar una aplicación TypeScript existente en Prisma Compute
• Crear o actualizar una configuración de despliegue tipada prisma.compute.ts
• Decidir si un framework está listo para Compute
• Depurar create-prisma --deploy, compute:deploy o app deploy
• Gestionar registros, despliegues, variables de entorno y dominios de aplicaciones Compute, y listar ramas de la plataforma (branch list; no hay comandos de crear/eliminar ramas)
• Inspeccionar registros de compilación de GitHub/Consola y el estado de push-to-deploy de GitHub
• Ejecutar despliegues no interactivos con autenticación de navegador, múltiples espacios de trabajo almacenados o tokens de servicio de Prisma
• Cambiar, seleccionar, listar o cerrar sesión de espacios de trabajo locales de la Plataforma Prisma para @prisma/cli
• Enviar comentarios sobre un fallo irresoluble de la CLI de Compute con @prisma/cli feedback
• Despliegues programáticos con @prisma/compute-sdk o integraciones con la API de Gestión

Árbol de Decisión

1. Despliegue o redespliegue de un proyecto existente: Lee references/app-deploy-cli.md.

2. Configuración tipada de Compute, monorepos, destinos de despliegue, raíces de aplicación o valores predeterminados de compilación/entorno: Lee references/compute-config.md.

3. Trabajo de compilación/ejecución específico de un framework: Lee references/frameworks.md.

4. Nuevo proyecto desde una plantilla: Lee references/create-prisma.md.

5. Despliegue programático, SDKs, APIs o conceptos de bajo nivel de Aplicación/Despliegue: Lee references/sdk-api.md.

6. Fallos de compilación, autenticación, entorno, despliegue o ejecución: Lee references/troubleshooting.md.

Reglas por Prioridad

Prioridad	Categoría	Impacto	Prefijo
1	Verificación de comandos	CRÍTICO	verify-
2	Autenticación y selección de espacio de trabajo	CRÍTICO	auth-
3	Preparación del framework	CRÍTICO	framework-
4	Enlace de puerto y host en tiempo de ejecución	CRÍTICO	runtime-
5	Configuración tipada de Compute	ALTA	config-
6	Conexión de rama, entorno y base de datos	ALTA	env-
7	Operaciones de despliegue	ALTA	deploy-
8	Automatización con SDK y API	MEDIA	sdk-

Reglas Rápidas

1. Verificación de Comandos

• verify-help-first - Usa la salida de ayuda de la CLI para confirmar la sintaxis del comando mientras trabajas.
• verify-prisma-vs-platform-cli - No asumas que prisma app deploy existe en la CLI de ORM; verifica si la tarea debe usar @prisma/cli.
• verify-generated-scripts - Prefiere el script generado compute:deploy cuando un proyecto ya tiene uno.
• verify-public-url - Después de un despliegue real, solicita la URL de despliegue pública en lugar de confiar en comprobaciones locales o solo de preparación.
• verify-config-support - Trata prisma.compute.ts como la configuración tipada de Compute; inspecciona la configuración del proyecto y los scripts generados antes de editar o desplegar.
• verify-auth-workspace-support - Usa los comandos @prisma/cli auth workspace para los flujos de lista/uso/cierre de sesión del espacio de trabajo local.

2. Autenticación y Selección de Espacio de Trabajo

• auth-source-precedence - Un PRISMA_SERVICE_TOKEN no vacío es la fuente de autenticación activa para los comandos y los espacios de trabajo OAuth locales se ignoran para la ejecución. Si está configurado pero vacío, la CLI debería fallar en lugar de recurrir a OAuth almacenado.
• auth-multi-workspace - auth login puede almacenar sesiones OAuth para múltiples espacios de trabajo en la misma máquina. El puntero del espacio de trabajo activo selecciona qué concesión OAuth almacenada usan los comandos normales.
• auth-list-before-switch - Usa auth workspace list --json para inspeccionar las sesiones locales. Los agentes deberían preferir los ids de espacio de trabajo del JSON sobre los nombres porque los nombres pueden ser ambiguos.
• auth-switch-explicitly - Usa auth workspace use <id-o-nombre> para cambios no interactivos. Usa auth workspace use sin argumentos solo para un selector interactivo o cuando exista exactamente un espacio de trabajo OAuth local.
• auth-no-fallthrough - Si el espacio de trabajo OAuth activo cierra sesión o falla la actualización, la CLI no debe recurrir silenciosamente a otro espacio de trabajo en caché. Ejecuta auth workspace use <id> para elegir el siguiente espacio de trabajo.
• auth-single-workspace-logout - Usa auth workspace logout <id-o-nombre> o auth logout --workspace <id-o-nombre> para eliminar una sesión de espacio de trabajo OAuth local. auth logout simple elimina todas las sesiones de espacio de trabajo OAuth local.
• auth-service-token-switching - Mientras PRISMA_SERVICE_TOKEN esté configurado, auth workspace use no está disponible porque el token de servicio es la fuente de autenticación activa; desconfigura la variable de entorno para cambiar de espacios de trabajo OAuth locales. El cierre de sesión del espacio de trabajo solo limpia el estado OAuth local.
• auth-storage-awareness - Las credenciales OAuth locales residen en el archivo de autenticación de la plataforma, con metadatos del espacio de trabajo en un archivo de contexto secundario. Los pines del proyecto residen en .prisma/local.json, y el estado de la aplicación/proyecto de la CLI reside en .prisma/cli/state.json cerca de prisma.compute.ts cuando está presente.

3. Preparación del Framework

• framework-cli-first - Evalúa la preparación para el despliegue contra @prisma/cli app deploy, no contra lo que create-prisma puede andamiar.
• framework-supported-cli-deploy - El despliegue Compute soporta nextjs, nuxt, astro, hono, nestjs, tanstack-start, custom y bun.
• framework-create-prisma-defaults-only - create-prisma puede proporcionar valores predeterminados generados y compute:deploy, pero no es la superficie de despliegue general para aplicaciones existentes.
• framework-build-output - Compute necesita un punto de entrada de servidor o artefacto del framework, no solo una salida estática.

4. Enlace de Puerto y Host en Tiempo de Ejecución

• runtime-bind-all-interfaces - Los servidores desplegados deben enlazarse en todas las interfaces (0.0.0.0 o el equivalente del framework), no en localhost o 127.0.0.1 codificados.
• runtime-match-http-port - La aplicación debe escuchar en el puerto HTTP desplegado: lee process.env.PORT cuando sea posible, o pasa el --http-port coincidente.
• runtime-readiness-port-only - La verificación de preparación de Compute observa los puertos de escucha; un listener solo de bucle de retroceso puede parecer listo mientras que la entrada pública no puede alcanzarlo.
• runtime-respond-within-60s - La entrada da a una aplicación 60 segundos para comenzar a responder, luego devuelve 504 Gateway Time-out y cancela la solicitud. Diseña los manejadores para que respondan primero y ejecuten trabajos más largos bajo waitUntil o desde una cola, nunca dentro de la solicitud.

5. Configuración Tipada de Compute

• config-optional-simple-app - prisma.compute.ts no es necesario para desplegar una aplicación simple normal; usa banderas cuando no haya una configuración duradera.
• config-init-formalizer - Genera una nueva configuración con bunx @prisma/cli@latest init: detecta el framework, fija nombre/framework/httpPort (más entrada para Bun/Hono), y ofrece el enlace del Proyecto. --format json escribe un prisma.compute.json sin dependencias. init se niega cuando ya existe alguna configuración, nunca andamia código y nunca despliega.
• config-use-prisma-compute-ts - Pon los valores predeterminados de despliegue reutilizables en prisma.compute.ts con defineComputeConfig, no en prisma.config.ts.
• config-app-vs-apps - Usa app para un único destino de despliegue y apps para monorepos o repositorios multi-aplicación; define exactamente uno.
• config-monorepo-roots - Para monorepos, usa prisma.compute.ts para declarar destinos de aplicación, raíces, valores predeterminados del framework, puntos de entrada, puertos y entradas de entorno.
• config-targets - En configuraciones multi-aplicación, @prisma/cli app deploy web selecciona el destino apps.web. Sin [app], los comandos pueden inferir el destino del directorio actual; de lo contrario, el despliegue puede ejecutar todos los destinos mientras que build/run requieren uno.
• config-region-new-app-only - Una region de configuración es solo un valor predeterminado para aplicaciones recién creadas; los despliegues en aplicaciones existentes mantienen la región actual de la aplicación.
• config-custom-artifact - Usa framework: "custom" con build.outputDirectory y build.entrypoint para artefactos preconstruidos o construidos a medida.
• config-no-project-branch-secrets - No confirmes Espacio de Trabajo, Proyecto, Rama, intención de producción, tokens de servicio o valores secretos en prisma.compute.ts; mantenlos en banderas, .prisma/local.json, almacenamiento de entorno o secretos de CI. Los valores predeterminados a nivel de aplicación como region, root, framework, entry, httpPort y rutas de archivos de entorno no secretos pertenecen a la configuración.
• config-flags-win - Las banderas de despliegue explícitas como --framework, --entry, --http-port, --region y --env anulan los valores de configuración coincidentes.

6. Rama, Entorno y Base de Datos

• env-do-not-leak-secrets - Nunca imprimas la DATABASE_URL completa, tokens de servicio o valores secretos.
• env-deploy-loads-dotenv - Los scripts de despliegue generados pueden cargar el entorno a través de prisma.compute.ts o --env .env; inspecciona el script/configuración real antes de redesplegar.
• env-migrations-separate - Los scripts de redespliegue no ejecutan migraciones ni datos de siembra. Ejecuta los scripts de base de datos de Prisma apropiados por separado.
• env-cli-token-name - @prisma/cli usa PRISMA_SERVICE_TOKEN para la autenticación de token de servicio.
• env-branch-scope - Los despliegues de rama, las variables de entorno de rama y las bases de datos de rama deben usar el mismo nombre de rama; pasa --branch <nombre-git> explícitamente al apuntar a una rama de vista previa.
• env-production-vs-preview - Usa --role production para el entorno de producción, --role preview para el entorno de plantilla de vista previa y --branch <nombre-git> para anulaciones específicas de la rama.
• env-db-explicit - Mantén la base de datos y la conexión de entorno explícitas a través de comandos de base de datos y entorno del proyecto; los ejemplos de despliegue no deben agregar configuración de base de datos, y los despliegues no ejecutan migraciones, datos de siembra ni crean una base de datos por aplicación automáticamente.

7. Operaciones de Despliegue

• deploy-prod-intent - Usa --prod --yes solo cuando el usuario pretenda un despliegue de producción. El primer despliegue de producción de una aplicación se promociona automáticamente sin --prod; la bandera controla los despliegues posteriores de la rama de producción.
• deploy-no-promote - Usa app deploy --no-promote para construir y luego verificar: construye un candidato accesible en su propia URL sin tocar el despliegue activo, promocionado más tarde con app promote <id-despliegue>.
• deploy-github-default-branch - Cuando una aplicación Compute está conectada a GitHub push-to-deploy, una fusión a la rama predeterminada es la ruta de despliegue de producción; verifica los registros de despliegue o las ejecuciones de verificación de GitHub en lugar de indicar a los usuarios que redesplieguen la rama PR fusionada o ejecuten un despliegue de vista previa de la rama predeterminada.
• deploy-build-logs - Usa @prisma/cli build logs <id-compilación> para la salida de compilación de GitHub/Consola. Usa app logs para los registros de despliegue en tiempo de ejecución; los dos ids son diferentes.
• deploy-noninteractive-auth - Los despliegues no interactivos necesitan el espacio de trabajo OAuth almacenado activo correcto o una variable de entorno de token de servicio compatible; nunca imprimas el token.
• deploy-json-for-agents - Usa --json --no-interactive para scripts y salida legible por agentes.
• deploy-create-project - Usa --create-project <nombre> solo cuando el usuario quiera que el despliegue cree y enlace un nuevo proyecto; entra en conflicto con --project y PRISMA_PROJECT_ID.
• deploy-ops-targets - Los comandos de mostrar/abrir/registros/listar-despliegues/promocionar/revertir/eliminar aplicación y dominio también pueden aceptar destinos [app] de prisma.compute.ts.
• deploy-report-cli-bugs - En UNEXPECTED_ERROR o un fallo irresoluble, repórtalo con el comando de comentarios; consulta "Enviar Comentarios y Reportar Problemas de la CLI" arriba.

8. SDK y API

• sdk-use-cli-first - Prefiere @prisma/cli app deploy para flujos de trabajo de aplicaciones; usa create-prisma solo para andamiar una nueva aplicación a menos que el usuario esté construyendo automatización de bajo nivel.
• sdk-result-handling - @prisma/compute-sdk devuelve valores Result; comprueba isOk()/isErr() en lugar de confiar en excepciones.
• sdk-snapshot-detection - Usa detectComputeApp para instantáneas de repositorio que no están verificadas en disco; enumera los espacios de trabajo tú mismo y llámalo una vez por raíz de aplicación candidata.

Flujo de Trabajo Preferido

1. Inspecciona el proyecto: gestor de paquetes, plantilla/framework, scripts de package.json, versión de Prisma, ubicación del cliente de Prisma, prisma.compute.ts y compute:deploy existente.
2. Verifica la salida de ayuda de la CLI para el paquete que realmente se está usando.
3. Verifica el contexto de autenticación antes de las mutaciones de proyecto/aplicación: auth whoami --json, y cuando puedan existir múltiples sesiones locales, auth workspace list --json.
4. Elige la ruta:
   • despliegue de aplicación existente: destino respaldado por configuración cuando esté presente, compute:deploy generado, o banderas @prisma/cli app build/run/deploy
   • nuevo andamiaje de aplicación: create-prisma, luego compute:deploy generado o @prisma/cli app deploy
   • bajo nivel: @prisma/compute-sdk o