English version · Version Markdown, lisible par un agent · v0.3.0

Migrer depuis Vercel

Cette page déplace la configuration d'un projet Vercel vers Bastide : le vercel.json, les réglages de construction et les variables d'environnement. Le code se déploie comme n'importe quel dépôt (voir Créer un projet puis Déployer) ; l'importeur ne touche ni au dépôt ni au projet Vercel.

Ce qu'il faut avant de commencer

Un projet Bastide créé (project_create_with_backend), où vous tenez le rôle de mainteneur (maintainer) : c'est le rang que demandent l'acquittement et l'import des variables.
Le contenu de votre vercel.json.
Pour les variables seulement : un jeton d'API Vercel limité au projet. Un jeton de portée compte entier est refusé. Le jeton ne sert qu'en lecture, n'est jamais rangé et est effacé à la fin de l'appel.

1. Importer la configuration

L'opération vercel_import.create lit le vercel.json (redirections, réécritures, en-têtes, cleanUrls, trailingSlash, crons, fonctions) et les réglages de construction que vous fournissez. Elle n'écrit rien dans le projet : elle rend le glowsoft.json à versionner et un rapport à trois catégories, repris, adapté, sans équivalent.

glowsoft vercel_import create --project-id <prj_…> --vercel-json "$(cat vercel.json)"

L'outil MCP vercel_import_create prend les mêmes arguments. Rejouée avec la même clé d'idempotence (--idempotency-key), l'opération rend la première réponse.

La réponse porte importId (ivc_…), counts (kept, adapted, noEquivalent, pendingAcknowledgement), items (une ligne par élément, avec sa phrase et l'action à mener) et settings.rootDirectory, qui ne s'écrit pas dans le dépôt : appliquez-le par project.settings.write. Versionnez le glowsoft.json rendu à la racine du dépôt.

2. Importer les variables

Les variables ne s'écrivent jamais dans un fichier versionné. Une personne les importe avec le jeton de la source :

glowsoft vercel_import variables create --project-id <prj_…> --import-id <ivc_…> --token <jeton-vercel> --vercel-project-id <nom-ou-identifiant>

La correspondance des cibles : production va à production, preview à préproduction, preview d'une branche à l'environnement qui suit cette branche. Aucune valeur ne paraît dans la réponse ni dans le rapport. Si la source se tait ou refuse, interrupted dit ce qui a été écrit avant le reste. Chaque appel à la source est journalisé (calls). Cette opération n'a pas d'outil MCP : un jeton de compte tiers ne transite pas par un agent. Elle se mène par la ligne de commande ou l'API HTTP, sous un jeton personnel.

Ce que vous écrivez à la main se fait par env.write.*, et se défait par env.delete.*.

3. Acquitter ce qui n'a pas d'équivalent

Chaque ligne « sans équivalent » attend l'acquittement d'une personne identifiée ; la migration n'est validée (state: validated) qu'ensuite.

glowsoft vercel_import accept --project-id <prj_…> --import-id <ivc_…>

Sans ranks, toutes les lignes en attente sont acquittées. Un jeton de compte de service n'acquitte pas, et l'opération n'a pas d'outil MCP : un agent ne valide pas à la place de la personne. Relisez les lignes avant : un acquittement est une déclaration, il se relit, aucun jeton d'annulation n'est rendu.

4. Premier déploiement

Déployez ensuite une branche avec deployment_create, et lisez le journal de construction : la commande de construction n'est pas reprise, la plateforme la déduit du dépôt.

Incompatibilités connues

Le rapport de l'importeur les nomme une à une, avec l'action à mener. Voici celles que l'importeur sait classer « sans équivalent » ou « adapté ».

Les clés de vercel.json sans équivalent :

images : la configuration du transformateur d'images n'a pas encore d'équivalent déclaratif (TR-075). Gardez les tailles par défaut.
regions : la région d'exécution ne se déclare pas dans le dépôt, elle est celle du placement. Pour une exigence de résidence, dites-le au support.
functionFailoverRegions et passiveRegions : pas d'équivalent ; un service tient plusieurs exemplaires dans sa région.
env et build : jamais lus ni recopiés depuis un fichier versionné ; passez par l'import des variables ci-dessus.
routes : forme héritée, que Vercel interdit de mêler à redirects, rewrites et headers ; réécrivez-la en ces trois blocs, puis relancez l'import.
builds : forme héritée ; la construction est détectée.
git : pas d'équivalent direct ; déclarez dans glowsoft.json les branches qui déploient (branches.patterns).
github : raccordez le dépôt par l'application GitHub de la plateforme.
public : les journaux de construction restent privés.
bunVersion : la version de Bun est une décision de la plateforme.
fluid : un service est un conteneur, le mode d'exécution fluid n'a pas d'équivalent.

Les réglages de construction que la plateforme décide elle-même : buildCommand, installCommand et outputDirectory (les commandes admises forment un catalogue fermé, EX-BUILD-090), ignoreCommand (le saut se calcule sur les chemins touchés par le commit, includePaths du projet), devCommand (sans objet sur la plateforme). Si le plan détecté ne construit pas le projet, déclarez un script build dans package.json.

Les adaptations : une redirection qui porte permanent et statusCode garde le code, comme Vercel l'applique ; une réécriture avec statusCode perd ce code (la réponse garde celui de l'application) ; une réécriture avec transforms est entièrement sans équivalent, car la retirer servirait autre chose que ce que vous avez écrit. La durée maximale d'une fonction devient le délai de garde des requêtes du service, le plus long des motifs, avec un plancher de 30 s.

Les gestes que les agents ne mènent pas, d'après le rapport de parité : vercel_import.accept (validation humaine, EX-MIG-020) et vercel_import.variables.create (identité) sont fermés aux agents ; vercel_import.list, qui relit les imports, est fermée sans raison de sécurité (le catalogue MCP est plein) : lisez-la à la console, vercel_import.create rend déjà le rapport entier.

Les cent fichiers vercel.json réels rejoués sur les deux plateformes (EX-NET-460) restent à faire : les fichiers de l'épreuve sont fabriqués d'après la référence publiée.

Voir aussi : Migrer depuis Supabase, Sortir de Bastide.