Mettre en production un site construit par agent, sans surprise

Un agent vous dira que le site fonctionne, et il dira vrai pour la machine sur laquelle il a tourné. La production est une autre machine, avec d'autres variables d'environnement, une étape de build que votre serveur de développement n'exécute jamais, et un cache qui survit à votre session. La plupart des défauts que nous avons livrés sur des sites construits par agent n'étaient pas des erreurs de code. C'était l'écart entre tourner et être en ligne, et chacun est évitable avec une liste de contrôle.

Décidez du déclencheur de déploiement avant le premier commit

Il y a deux dispositions saines et une mauvaise. Les saines: un push sur la branche principale qui déploie en production, ou un push qui déploie en préversion avec une promotion manuelle. La mauvaise: un agent qui lance la commande de déploiement directement, car ce qui décide alors de ce qui est en ligne est une phrase dans une fenêtre de chat, non un commit que vous pouvez montrer. Reliez le dépôt à l'hébergeur, comme l'expliquent la documentation de déploiement Vercel et le guide de déploiement Next.js, et laissez git déclencher.

Cela vous donne aussi l'artefact qui rend tout le reste possible. Chaque déploiement a un commit, chaque commit a un diff, et quand quelque chose casse à seize heures vous lisez ce qui a changé au lieu de reconstituer une conversation.

Sur un site à framework, les URL absolues de vos métadonnées viennent d'une URL de base définie une fois, en général dans une variable d'environnement. Mal réglée, les pages s'affichent, le build passe, et chaque balise canonical et chaque aperçu social pointent vers le mauvais hôte. Rien dans votre session ne vous le dira, car en local la valeur est correcte.

Vérifiez-la sur la page déployée, pas dans le fichier. Récupérez le HTML d'une URL de production et lisez les balises canonical et Open Graph réellement renvoyées. Pendant que vous y êtes, prenez une route enfant plutôt que l'accueil: les métadonnées fusionnent depuis le parent de façons qui conservent silencieusement l'URL du parent, le piège pour lequel cet article sur l'héritage des métadonnées a été écrit. La référence des métadonnées du framework documente la fusion.

Ce que le build attrape, et ce qu'il n'attrapera jamais

Un build de production est le meilleur contrôle unique dont vous disposez, et il est plus étroit qu'on ne le croit. Il attrape les erreurs de types, les imports manquants, les données invalides que vos propres validateurs rejettent, et les routes qui ne s'affichent pas du tout. Il n'attrape pas une page qui affiche le mauvais contenu, un titre visuellement coupé, un lien qui mène à un endroit valide mais faux, ni une comparaison de dates qui se comporte autrement dans un autre fuseau.

La dernière mérite sa propre phrase, car elle mord spécifiquement les sites générés statiquement. Si votre contenu porte des dates de publication et que vous les comparez à l'heure courante, la comparaison tourne au build sur un serveur dont l'horloge est en UTC. Un article daté d'aujourd'hui se publie ou non selon un fuseau auquel vous n'avez jamais pensé. Le nôtre est comparé à UTC délibérément, pour exactement cette raison.

Images: le cache survit à votre session

Si votre hébergeur optimise les images, il les met en cache par chemin source. Remplacez un fichier sur place en gardant le nom, et l'ancienne image continue d'être servie. La documentation d'optimisation d'images de Vercel décrit la mise en cache; ce qui piège, c'est l'échec partiel. Remplacez trois images, une seule se met à jour, et cela se lit comme un bug d'affichage plutôt qu'un cache, ce qui vous envoie chercher au mauvais endroit une heure durant.

Deux règles le referment. Changez le nom du fichier quand vous changez l'image, et videz le cache d'images local avant de juger un remplacement. Rien d'astucieux dans l'un ni l'autre; les deux font la différence entre une correction de dix secondes et un après-midi.

La préversion est la revue

Une capture issue d'un serveur de développement local est une preuve faible. Elle a été prise avant la stabilisation des polices, ou dans un moteur qui ne composite pas comme un navigateur, ou à une largeur que personne n'utilise. Une préversion est la chose réelle à une URL réelle: vous pouvez récupérer son HTML, lancer un audit de page dessus et la regarder dans le navigateur que votre client utilisera.

L'ordre qui marche chez nous: construire en local, pousser vers une préversion, auditer la préversion, puis promouvoir. L'audit tient en trois requêtes et un passage navigateur, et il attrape la classe de défauts qu'aucune vérification locale n'atteint. C'est l'argument de l'article sur la vérification, appliqué au seul environnement qui compte.

Le rollback est une fonctionnalité, servez-vous-en

Quand un déploiement est mauvais, l'instinct est de corriger en avant avec l'agent, dans l'urgence, sur un site en ligne. Ne le faites pas. Promouvez le déploiement précédent, ce qui prend quelques secondes et ne coûte rien, puis corrigez à vitesse normale. Si cela compte davantage sur du travail fait par agent que sur du travail écrit à la main, c'est qu'une session d'agent pressée produit des changements plus larges qu'une personne pressée: corriger en avant sous pression, c'est ainsi qu'une page cassée en devient quatre.

La liste, dans l'ordre

Rien de tout cela n'est exotique, et c'est le point. Le mode de défaillance des sites construits par agent n'est pas le bug sophistiqué. C'est du code compétent déployé dans un environnement que personne n'a vérifié, et six contrôles de routine en referment presque tout. Si vous voulez ces barrières automatisées plutôt que mémorisées, l'article sur les hooks s'en charge, et la liste SEO couvre ce qu'il faut vérifier une fois le site vraiment en ligne. Vous pouvez aussi voir les sites que nous avons livrés ainsi.