Hydrogen v2026.4.0 : les deux breaking changes à ne pas ignorer avant le 30 juin

Si vous exploitez une boutique Hydrogen en production, le compte à rebours est lancé. Shopify a publié Hydrogen v2026.4.0 le 9 avril 2026, et cette release embarque deux breaking changes qui réécrivent discrètement la façon dont votre boutique gère le trafic API et le consentement client. L'un d'entre eux, la migration du consentement, a une date butoir ferme : le 30 juin 2026.

La plupart des équipes survoleront le changelog, verront « mineure », et passeront à autre chose. C'est une erreur. Si votre build reposait sur la désactivation de proxyStandardRoutes, ou si vous avez déjà écrit du code custom qui lit le cookie legacy _tracking_consent, votre boutique soit lève déjà des erreurs, soit s'appuie sur une infrastructure que Shopify est en train de retirer activement.

Voici exactement ce qui a changé, ce qui casse, qui est concerné, et ce qu'il faut faire.

Un mot rapide sur le versioning Hydrogen en 2026

Avant d'entrer dans le détail, une clarification que nos clients nous demandent en permanence : il n'existe pas de « Hydrogen 3.0 ». Shopify a migré Hydrogen vers un versioning calendaire en 2024. Les releases suivent désormais le pattern ANNÉE.TRIMESTRE.PATCH, aligné sur les versions de la Storefront API. Le rythme actuel est d'une release majeure par trimestre, avec des patches entre les deux.

Concrètement :

Si vous êtes encore sur v2025.x ou antérieur, vous n'avez pas juste du retard sur les fonctionnalités. Vous tournez sur une version de la Storefront API qui sera dépréciée, et sur une infrastructure de consentement que Shopify supprime en juin. (Si vous hésitez encore sur la stack elle-même, notre comparatif Hydrogen vs Next.js détaille les cas où chacun l'emporte.)

Breaking change n°1 : le proxy Storefront API devient obligatoire

Ce qui change

Dans v2026.1 et antérieures, la fonction createRequestHandler acceptait une option proxyStandardRoutes. Elle valait true par défaut, mais vous pouviez la désactiver. Si votre load context ne fournissait pas d'instance storefront, Hydrogen affichait un warning console et passait silencieusement le proxy.

Dans v2026.4.0, cette option a disparu. Le proxy est toujours actif, et une instance storefront manquante lève désormais une erreur dure au moment de la requête.

// Avant (v2026.1)
createRequestHandler({
  build,
  getLoadContext,
  proxyStandardRoutes: true, // optionnel, true par défaut
});
// storefront manquant dans le context => warning console, proxy ignoré silencieusement

// Après (v2026.4)
createRequestHandler({
  build,
  getLoadContext,
  // proxyStandardRoutes a disparu, le proxy est toujours actif
});
// storefront manquant dans le context => lève une Error, les requêtes échouent

Pourquoi Shopify a fait ça

Deux raisons, toutes deux légitimes, aucune n'est optionnelle désormais.

D'abord, la sécurité du token. Les appels directs navigateur vers Storefront API ont toujours été un risque de fuite. Votre token Storefront finit dans le bundle client. Avec le proxy obligatoire, ce token reste côté serveur, là où il doit être.

Ensuite, CORS et abus de bots. Alors que Shopify pivote vers l'agent commerce (un article à venir), ils ont besoin d'un unique point d'entrée contrôlé pour chaque requête de boutique. Le proxy est ce point.

Qui est exposé

Vous êtes concerné si l'un des points suivants s'applique :

• Vous définissez explicitement proxyStandardRoutes: false quelque part dans votre server entry.
• Vous avez écrit un getLoadContext custom qui ne renvoie pas toujours une instance storefront (par exemple, logique conditionnelle pour les routes healthcheck ou les chemins admin).
• Vous avez codé un wrapper fetch maison qui appelle shopify-storefront-api-XX.myshopify.com directement depuis le navigateur.
• Vous avez du scaffolding Hydrogen ancien qui précède createHydrogenContext() et construit le context à la main.

Si vous avez utilisé npx shopify hydrogen init récemment et que vous n'avez jamais touché le server entry, vous êtes probablement tranquille. createHydrogenContext() renvoie déjà une instance storefront à chaque requête, et le proxy était déjà actif par défaut.

Le fix

La migration est directe mais nécessite une vraie passe de tests :

1. Auditez votre server entry. Cherchez proxyStandardRoutes et createRequestHandler dans votre codebase. Supprimez tout argument proxyStandardRoutes explicite.
2. Vérifiez votre load context. Si vous utilisez createHydrogenContext(), c'est terminé. Si vous construisez le context manuellement, confirmez que storefront est toujours présent : routes d'erreur, handlers robots.txt, et tout middleware custom.
3. Auditez les fetchs client. Faites un grep sur les appels directs à myshopify.com/api/. Si vous en trouvez, faites-les passer par le proxy storefront via storefront.query().
4. Testez sous charge. Lancez un environnement de preview et tapez chaque type de route : PDP, PLP, mutations cart, customer account, et les routes que votre équipe oublie qu'elles existent.

Breaking change n°2 : le consentement passe côté serveur

Ce qui change

Hydrogen définit désormais window.Shopify.customerPrivacy.backendConsentEnabled = true avant le chargement du script Customer Privacy API. Ce flag indique à la librairie de consentement Shopify d'utiliser des cookies posés côté serveur via le proxy Storefront API, au lieu du cookie JavaScript legacy _tracking_consent.

Le flag est installé via un property interceptor sur window.Shopify qui survit au cycle de reset window.Shopify = {} du CDN, ce qui le rend lisible avant que l'API complète ne se charge.

Si vous utilisez le composant <ShopifyCustomerPrivacy /> de Hydrogen, ou le wrapper <Analytics.Provider /> qui l'inclut, tout se fait automatiquement. Aucune nouvelle configuration n'est requise.

La deadline qui compte

Qui est exposé

Moins évident que le changement de proxy, mais plus dangereux en pratique :

• Vous lisez ou écrivez _tracking_consent directement dans du code analytics custom.
• Vous avez forké ou remplacé le composant <ShopifyCustomerPrivacy /> de Hydrogen par une intégration CMP custom (OneTrust, Didomi, Axeptio) qui contourne le nouveau flow server-set.
• Vous envoyez des événements analytics (GA4, Meta CAPI, server-side tagging) conditionnés à un état de consentement lu depuis le cookie legacy.
• Vous êtes sur Hydrogen v2025.x ou antérieur sans plan de migration.

Le fix

Upgradez vers v2026.4.0 ou plus récent et assurez-vous d'utiliser les primitives analytics first-party de Hydrogen. Si vous tournez avec un CMP tiers, travaillez avec l'éditeur pour qu'il lise le consentement depuis le nouveau chemin de cookie server-set plutôt que depuis le cookie JS déprécié.

Pour les équipes opérant des boutiques en France ou en UE, ce n'est pas du ménage optionnel. C'est votre posture de conformité. Le passage au consentement server-side est aussi une bonne nouvelle à long terme : il survit aux bloqueurs de pubs, aux modes privacy des navigateurs, et à ITP, qui érodaient lentement la fiabilité de l'état de consentement client-side. Si votre stack mise déjà sur le tracking côté serveur sur Shopify, le nouveau flow de consentement s'y intègre proprement.

Autres changements à connaître

La release d'avril embarque quelques éléments plus discrets qui peuvent mordre si on les ignore :

• Limite de 128 KB sur les écritures de metafields JSON. Si vous stockez de gros configurateurs produit ou des exports PIM dans des metafields JSON, les écritures au-delà de 128 KB sont rejetées. Auditez vos plus gros payloads et envisagez de les découper ou de basculer vers du stockage fichier.
• Nouveau code d'erreur cart MERCHANDISE_LINE_TRANSFORMERS_RUN_ERROR. Si vous utilisez des cart line transformers via Shopify Functions, gérez ce code dans votre UI d'erreur panier pour que l'utilisateur voie autre chose qu'un échec silencieux.
• Correction des peer dependencies React Router. Une plage incorrecte précédente pouvait provoquer des galères de résolution npm install. Un clean install vaut le coup si vous combattez des warnings de peers.
• Cut-off ferme de Shopify Scripts. Ce n'est pas dans Hydrogen lui-même, mais c'est la même deadline du 30 juin 2026. Les Scripts legacy pour les discounts, le shipping et les paiements arrêtent de s'exécuter. Si ce n'est pas déjà fait, consultez notre playbook de migration Shopify Scripts vers Functions et lancez le chantier maintenant.

Un plan de migration pragmatique

Si vous opérez une boutique Hydrogen et que vous n'y avez pas touché depuis 2025, voici l'ordre dans lequel nous procéderions :

1. Verrouillez la pièce. Branchez depuis main, gelez les PR non liées pendant deux jours. C'est un upgrade focalisé, pas un sprint pour caser des features.
2. Lancez npx shopify hydrogen upgrade. Laissez le CLI faire les calculs de dépendances. Lisez chaque prompt.
3. Réglez d'abord les erreurs de compilation. Retirez proxyStandardRoutes, mettez à jour les peer deps React Router, régénérez les types.
4. Lancez la suite de tests complète. Surtout les flows cart et checkout. Le changement de proxy est l'endroit le plus probable pour une régression.
5. QA manuelle sur un déploiement preview. Testez le flow de la bannière de consentement avec cookies effacés, en navigation privée, et sur Safari avec ITP. Le consentement, c'est là que la casse silencieuse se cache.
6. Auditez vos écritures de metafields JSON. Faites un grep sur tout ce qui construit un payload JSON destiné à un metafield et confirmez qu'aucun ne dépasse 128 KB.
7. Livrez en staging, laissez décanter 48 heures. Surveillez le tracker d'erreurs pour toute hausse des 500 ou chute des analytics.
8. Déploiement production, monitoring 72 heures. Ayez un chemin de rollback prêt.

Pour la plupart des boutiques avec un codebase Hydrogen propre, c'est un exercice d'un à trois jours. Pour les boutiques qui portent de la dette technique, des analytics custom ou des CMP tiers, comptez une semaine complète.

Quand faire appel à un spécialiste

Vous devriez faire appel à un expert si l'un de ces points s'applique :

• Votre boutique est sur Hydrogen v2024.x ou antérieur et n'a pas été upgradée de façon incrémentale. Sauter plusieurs versions d'API empile les breaking changes les uns sur les autres.
• Vous utilisez un CMP custom et avez besoin de le brancher au nouveau chemin de cookie de consentement server-set.
• Vous avez un usage important de Shopify Scripts qui doivent aussi migrer vers Functions avant le 30 juin.
• Vous n'avez pas de couverture de tests claire sur les flows cart et checkout.
• Vous n'êtes pas sûr de savoir si votre boutique tourne bien sous Hydrogen, ou si vous êtes sur un setup hybride avec des proxies custom.

Chez Sentinu, nous travaillons exactement sur ce type de chantier Hydrogen et Shopify headless au quotidien. Si vous voulez un second regard sur votre migration v2026.4.0, ou un audit complet des points d'exposition de votre build headless, réservez un appel stratégique ou découvrez notre pratique Shopify headless.

FAQ

v2026.4.0 est-il obligatoire, ou peut-on rester sur v2026.1.0 ?

Vous pouvez techniquement rester sur v2026.1.0 quelque temps, mais la dépréciation du consentement au 30 juin 2026 est appliquée au niveau de la plateforme Shopify, pas au niveau du package Hydrogen. Même sans upgrade, le comportement sous-jacent du cookie _tracking_consent va changer. L'upgrade est la façon la plus propre de laisser Hydrogen gérer pour vous le nouveau flow de consentement server-set.

Que se passe-t-il si on rate la deadline du 30 juin ?

Le chemin du cookie _tracking_consent n'est plus honoré. Votre boutique continuera de se charger, mais l'état de consentement stocké uniquement dans le cookie legacy ne sera plus respecté par les analytics Shopify, le tracking publicitaire, ni l'API Customer Privacy. Pour les marchands en France ou en UE, cela devient immédiatement un problème RGPD et ePrivacy. Pour les autres, la qualité de vos données d'attribution de conversion baisse.

Cela affecte-t-il les boutiques Hydrogen qui ne sont pas hébergées sur Oxygen ?

Oui. Les breaking changes sont dans le package @shopify/hydrogen lui-même, pas dans Oxygen. Si vous self-hostez sur Vercel, Netlify, Cloudflare, ou votre propre infrastructure, vous devez quand même upgrader et vérifier que votre load context custom renvoie bien une instance storefront.

Nous utilisons un CMP tiers comme OneTrust ou Didomi. Sommes-nous concernés ?

Potentiellement oui. Si votre intégration CMP lit l'état de consentement directement depuis _tracking_consent, ou y écrit, ce chemin est déprécié. Travaillez avec votre éditeur CMP pour qu'il lise le nouveau chemin de cookie server-set. Certains CMP ont déjà livré des mises à jour, d'autres non.

Peut-on tester le changement de proxy sans casser la production ?

Oui. Déployez v2026.4.0 sur un environnement de preview, lancez la vérification du proxy en parcourant vos routes de boutique avec l'onglet réseau ouvert, et confirmez que tout le trafic Storefront API passe par votre propre domaine plutôt que directement par myshopify.com. Si vous voyez des appels directs, vous avez un wrapper fetch à migrer avant de livrer en production.