prisma/prisma-compute

Prisma Compute

Guide les agents à travers la création, le déploiement, les opérations et la préparation au déploiement spécifique aux frameworks des applications Prisma Compute.

Surface CLI de Prisma Compute

Utilisez l'interface CLI de la plateforme Prisma pour les workflows d'applications 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

Utilisez @prisma/cli@latest pour le déploiement d'applications Compute. Utilisez create-prisma@latest pour l'échafaudage de nouveaux projets.

Envoyer des commentaires et signaler des problèmes CLI

La CLI dispose d'un canal de commentaires intégré. Utilisez-le chaque fois qu'une commande plante (UNEXPECTED_ERROR), qu'un échec persiste après le dépannage, ou que l'utilisateur demande à envoyer des commentaires à l'équipe Prisma :

bunx @prisma/cli@latest feedback "app deploy a planté : <première ligne d'erreur>"
bunx @prisma/cli@latest feedback "j'adore le flux de déploiement" --email [email protected]

Les sorties de plantage pointent ici d'elles-mêmes : les enveloppes de plantage --json contiennent la commande pré-remplie exacte comme entrée recover dans nextActions (exécutez-la textuellement), et les sorties de plantage humaines se terminent par un indicateur Dites-nous ce qui s'est passé :. Les commentaires sont anonymes sauf si --email est passé et n'attachent que la version CLI, la version de Node et la plateforme/architecture OS. N'incluez jamais de secrets, d'URLs de connexion ou de données utilisateur dans le message.

Ordre de la source de vérité

Utilisez les preuves dans cet ordre pour décider quoi éditer ou exécuter :

1. Les scripts et configurations générés du projet, en particulier prisma.compute.ts, compute:deploy, la configuration du framework et package.json.
2. La sortie d'aide de la CLI de create-prisma et @prisma/cli.
3. Le code du paquet installé localement, les artefacts générés et les définitions de types.
4. La documentation officielle.

Quand appliquer

Utilisez cette compétence pour :

• Créer une nouvelle application pouvant être déployée sur Prisma Compute
• Déployer une application TypeScript existante sur Prisma Compute
• Créer ou mettre à jour une configuration de déploiement typée prisma.compute.ts
• Décider si un framework est prêt pour Compute
• Déboguer create-prisma --deploy, compute:deploy ou app deploy
• Gérer les logs, déploiements, variables d'environnement et domaines des applications Compute, et lister les branches de la plateforme (branch list ; il n'y a pas de commandes de création/suppression de branches)
• Inspecter les logs de construction GitHub/Console et le statut push-to-deploy GitHub
• Effectuer des déploiements non interactifs avec authentification navigateur, plusieurs espaces de travail stockés ou jetons de service Prisma
• Changer, sélectionner, lister ou se déconnecter des espaces de travail locaux de la plateforme Prisma pour @prisma/cli
• Envoyer des commentaires sur un échec CLI Compute non résoluble avec @prisma/cli feedback
• Déploiements programmatiques avec @prisma/compute-sdk ou des intégrations API de gestion

Arbre de décision

1. Déploiement ou redéploiement de projet existant : Lisez references/app-deploy-cli.md.

2. Configuration Compute typée, monorepos, cibles de déploiement, racines d'application ou valeurs par défaut de construction/environnement : Lisez references/compute-config.md.

3. Travail de construction/exécution spécifique au framework : Lisez references/frameworks.md.

4. Nouveau projet à partir d'un échafaudage : Lisez references/create-prisma.md.

5. Déploiement programmatique, SDK, API ou concepts de base d'application/déploiement : Lisez references/sdk-api.md.

6. Échecs de construction, d'authentification, d'environnement, de déploiement ou d'exécution : Lisez references/troubleshooting.md.

Règles par priorité

Priorité	Catégorie	Impact	Préfixe
1	Vérification de commande	CRITIQUE	verify-
2	Authentification et sélection d'espace de travail	CRITIQUE	auth-
3	Préparation du framework	CRITIQUE	framework-
4	Hôte d'exécution et liaison de port	CRITIQUE	runtime-
5	Configuration Compute typée	ÉLEVÉ	config-
6	Branche, environnement et câblage de base de données	ÉLEVÉ	env-
7	Opérations de déploiement	ÉLEVÉ	deploy-
8	Automatisation SDK et API	MOYEN	sdk-

Règles rapides

1. Vérification de commande

• verify-help-first - Utilisez la sortie d'aide de la CLI pour confirmer la syntaxe des commandes pendant le travail.
• verify-prisma-vs-platform-cli - Ne supposez pas que prisma app deploy existe dans la CLI ORM ; vérifiez si la tâche doit utiliser @prisma/cli.
• verify-generated-scripts - Préférez le script compute:deploy généré lorsqu'un projet en possède déjà un.
• verify-public-url - Après un vrai déploiement, demandez l'URL de déploiement publique au lieu de vous fier à des vérifications locales ou de préparation uniquement.
• verify-config-support - Traitez prisma.compute.ts comme la configuration Compute typée ; inspectez la configuration et les scripts générés du projet avant d'éditer ou de déployer.
• verify-auth-workspace-support - Utilisez les commandes @prisma/cli auth workspace pour les flux locaux de liste/utilisation/déconnexion d'espace de travail.

2. Authentification et sélection d'espace de travail

• auth-source-precedence - Un PRISMA_SERVICE_TOKEN non vide est la source d'authentification active pour les commandes et les espaces de travail OAuth locaux sont ignorés pour l'exécution. S'il est défini mais vide, la CLI doit échouer au lieu de revenir à OAuth stocké.
• auth-multi-workspace - auth login peut stocker des sessions OAuth pour plusieurs espaces de travail sur la même machine. Le pointeur d'espace de travail actif sélectionne quelle autorisation OAuth stockée les commandes normales utilisent.
• auth-list-before-switch - Utilisez auth workspace list --json pour inspecter les sessions locales. Les agents doivent préférer les identifiants d'espace de travail du JSON aux noms car les noms peuvent être ambigus.
• auth-switch-explicitly - Utilisez auth workspace use <id-or-name> pour un changement non interactif. Utilisez auth workspace use sans argument uniquement pour un sélecteur interactif ou lorsqu'exactement un espace de travail OAuth local existe.
• auth-no-fallthrough - Si l'espace de travail OAuth actif est déconnecté ou échoue à l'actualisation, la CLI ne doit pas revenir silencieusement à un autre espace de travail en cache. Exécutez auth workspace use <id> pour choisir l'espace de travail suivant.
• auth-single-workspace-logout - Utilisez auth workspace logout <id-or-name> ou auth logout --workspace <id-or-name> pour supprimer une session d'espace de travail OAuth locale. auth logout simple efface toutes les sessions d'espace de travail OAuth locales.
• auth-service-token-switching - Tant que PRISMA_SERVICE_TOKEN est défini, auth workspace use est indisponible car le jeton de service est la source d'authentification active ; désactivez la variable d'environnement pour changer d'espace de travail OAuth local. La déconnexion d'espace de travail nettoie toujours uniquement l'état OAuth local.
• auth-storage-awareness - Les informations d'identification OAuth locales résident dans le fichier d'authentification de la plateforme, avec les métadonnées d'espace de travail dans un fichier de contexte sidecar. Les épingles de projet résident dans .prisma/local.json, et l'état CLI de l'application/projet réside dans .prisma/cli/state.json près de prisma.compute.ts lorsqu'il est présent.

3. Préparation du framework

• framework-cli-first - Évaluez la préparation au déploiement par rapport à @prisma/cli app deploy, pas par rapport à ce que create-prisma peut échafauder.
• framework-supported-cli-deploy - Le déploiement Compute prend en charge nextjs, nuxt, astro, hono, nestjs, tanstack-start, custom et bun.
• framework-create-prisma-defaults-only - create-prisma peut fournir des valeurs par défaut générées et compute:deploy, mais ce n'est pas la surface de déploiement générale pour les applications existantes.
• framework-build-output - Compute a besoin d'un point d'entrée serveur ou d'un artefact du framework, pas seulement d'une sortie statique.

4. Hôte d'exécution et liaison de port

• runtime-bind-all-interfaces - Les serveurs déployés doivent se lier à toutes les interfaces (0.0.0.0 ou l'équivalent du framework), pas à localhost ou 127.0.0.1 codés en dur.
• runtime-match-http-port - L'application doit écouter sur le port HTTP déployé : lisez process.env.PORT lorsque c'est possible, ou passez le --http-port correspondant.
• runtime-readiness-port-only - La préparation Compute surveille les ports d'écoute ; un écouteur en boucle locale peut sembler prêt alors que l'entrée publique ne peut pas l'atteindre.
• runtime-respond-within-60s - L'entrée donne à une application 60 secondes pour commencer à répondre, puis renvoie 504 Gateway Time-out et annule la requête. Concevez les gestionnaires pour répondre d'abord et exécuter un travail plus long sous waitUntil ou à partir d'une file d'attente, jamais à l'intérieur de la requête.

5. Configuration Compute typée

• config-optional-simple-app - prisma.compute.ts n'est pas requis pour déployer une application unique normale ; utilisez des indicateurs lorsqu'il n'y a pas de configuration durable.
• config-init-formalizer - Générez une nouvelle configuration avec bunx @prisma/cli@latest init : il détecte le framework, épingle le nom/framework/httpPort (plus l'entrée pour Bun/Hono) et propose le lien du projet. --format json écrit un prisma.compute.json sans dépendances à la place. init refuse lorsqu'une configuration existe déjà, n'échafaude jamais de code et ne déploie jamais.
• config-use-prisma-compute-ts - Placez les valeurs par défaut de déploiement réutilisables dans prisma.compute.ts avec defineComputeConfig, pas dans prisma.config.ts.
• config-app-vs-apps - Utilisez app pour une seule cible de déploiement et apps pour les monorepos ou les dépôts multi-applications ; définissez-en exactement un.
• config-monorepo-roots - Pour les monorepos, utilisez prisma.compute.ts pour déclarer les cibles d'application, les racines, les valeurs par défaut du framework, les points d'entrée, les ports et les entrées d'environnement.
• config-targets - Dans les configurations multi-applications, @prisma/cli app deploy web sélectionne la cible apps.web. Sans [app], les commandes peuvent déduire la cible du répertoire courant ; sinon, le déploiement peut exécuter toutes les cibles tandis que la construction/exécution en nécessite une.
• config-region-new-app-only - Une region de configuration n'est qu'une valeur par défaut pour les applications nouvellement créées ; les déploiements vers des applications existantes conservent la région actuelle de l'application.
• config-custom-artifact - Utilisez framework: "custom" avec build.outputDirectory et build.entrypoint pour les artefacts préconstruits ou personnalisés.
• config-no-project-branch-secrets - Ne validez pas les secrets d'Espace de travail, Projet, Branche, intention de production, jetons de service ou valeurs secrètes dans prisma.compute.ts ; conservez-les dans les indicateurs, .prisma/local.json, le stockage d'environnement ou les secrets CI. Les valeurs par défaut au niveau de l'application telles que region, root, framework, entry, httpPort et les chemins de fichiers d'environnement non secrets appartiennent à la configuration.
• config-flags-win - Les indicateurs de déploiement explicites tels que --framework, --entry, --http-port, --region et --env remplacent les valeurs de configuration correspondantes.

6. Branche, environnement et base de données

• env-do-not-leak-secrets - N'affichez jamais la DATABASE_URL complète, les jetons de service ou les valeurs secrètes.
• env-deploy-loads-dotenv - Les scripts de déploiement générés peuvent charger l'environnement via prisma.compute.ts ou --env .env ; inspectez le script/la configuration réelle avant de redéployer.
• env-migrations-separate - Les scripts de redéploiement n'exécutent pas les migrations ni les données d'initialisation. Exécutez les scripts de base de données Prisma appropriés séparément.
• env-cli-token-name - @prisma/cli utilise PRISMA_SERVICE_TOKEN pour l'authentification par jeton de service.
• env-branch-scope - Les déploiements de branche, les variables d'environnement de branche et les bases de données de branche doivent utiliser le même nom de branche ; passez --branch <git-name> explicitement lors du ciblage d'une branche de prévisualisation.
• env-production-vs-preview - Utilisez --role production pour l'environnement de production, --role preview pour l'environnement modèle de prévisualisation, et --branch <git-name> pour les remplacements spécifiques à la branche.
• env-db-explicit - Gardez le câblage de la base de données et de l'environnement explicite via la base de données et les commandes d'environnement du projet ; les exemples de déploiement ne doivent pas ajouter de configuration de base de données, et les déploiements n'exécutent pas de migrations, de données d'initialisation ou ne créent pas automatiquement une base de données par application.

7. Opérations de déploiement

• deploy-prod-intent - Utilisez --prod --yes uniquement lorsque l'utilisateur a l'intention d'un déploiement de production. Le premier déploiement de production d'une application s'auto-promotionne sans --prod ; l'indicateur verrouille les déploiements ultérieurs de la branche de production.
• deploy-no-promote - Utilisez app deploy --no-promote pour construire-puis-vérifier : cela construit un candidat accessible à sa propre URL sans toucher au déploiement en direct, promu plus tard avec app promote <deployment-id>.
• deploy-github-default-branch - Lorsqu'une application Compute est connectée à GitHub push-to-deploy, une fusion vers la branche par défaut est le chemin de déploiement de production ; vérifiez les enregistrements de déploiement ou les exécutions de vérification GitHub au lieu de dire aux utilisateurs de redéployer la branche PR fusionnée ou d'exécuter un déploiement de prévisualisation de branche par défaut.
• deploy-build-logs - Utilisez @prisma/cli build logs <build-id> pour la sortie de construction GitHub/Console. Utilisez app logs pour les logs de déploiement d'exécution ; les deux identifiants sont différents.
• deploy-noninteractive-auth - Les déploiements non interactifs nécessitent soit l'espace de travail OAuth stocké actif correct, soit une variable d'environnement de jeton de service prise en charge ; n'affichez jamais le jeton.
• deploy-json-for-agents - Utilisez --json --no-interactive pour les scripts et la sortie lisible par agent.
• deploy-create-project - Utilisez --create-project <name> uniquement lorsque l'utilisateur souhaite que le déploiement crée et lie un nouveau projet ; cela entre en conflit avec --project et PRISMA_PROJECT_ID.
• deploy-ops-targets - Les commandes d'affichage/ouverture/logs/liste-déploiements/promotion/retour-arrière/suppression d'application et de domaine peuvent également accepter des cibles [app] de prisma.compute.ts.
• deploy-report-cli-bugs - En cas de UNEXPECTED_ERROR ou d'un échec non résoluble, signalez-le avec la commande de commentaires ; voir "Envoyer des commentaires et signaler des problèmes CLI" ci-dessus.

8. SDK et API

• sdk-use-cli-first - Préférez @prisma/cli app deploy pour les workflows d'application ; utilisez create-prisma uniquement pour échafauder une nouvelle application sauf si l'utilisateur construit une automatisation de plus bas niveau.
• sdk-result-handling - @prisma/compute-sdk renvoie des valeurs Result ; vérifiez isOk()/isErr() au lieu de vous fier aux exceptions.
• sdk-snapshot-detection - Utilisez detectComputeApp pour les instantanés de dépôt qui ne sont pas extraits sur le disque ; énumérez vous-même les espaces de travail et appelez-le une fois par racine d'application candidate.

Workflow préféré

1. Inspectez le projet : gestionnaire de paquets, modèle/framework, scripts package.json, version Prisma, emplacement du client Prisma, prisma.compute.ts et compute:deploy existant.
2. Vérifiez la sortie d'aide de la CLI pour le paquet réellement utilisé.
3. Vérifiez le contexte d'authentification avant les mutations de projet/application : auth whoami --json, et lorsque plusieurs sessions locales peuvent exister, auth workspace list --json.
4. Choisissez le chemin :
   • déploiement d'application existante : cible basée sur la configuration lorsqu'elle est présente, compute:deploy généré, ou indicateurs @prisma/cli app build/run/deploy
   • échafaudage de nouvelle application : create-prisma, puis compute:deploy généré ou @prisma/cli app deploy
   • intégration de bas niveau : SDK Compute, API de gestion ou commandes CLI autonomes