Le vendredi où Vercel a refusé mon merge

Vendredi 10 avril, fin d'après-midi. Je merge sur main une intégration Stripe pour ouvrir un endpoint webhook paiement. Vercel pousse le preview build automatiquement, et trois minutes plus tard l'icône passe au rouge. Je clique. Stack trace au build :

Error: STRIPE_SECRET_KEY manquant
    at Object.<anonymous> (/.next/server/chunks/lib_stripe.js:9:11)
    at Module._compile (node:internal/modules/cjs/loader:1376:14)

La prod marche, elle a la variable d'environnement. La preview n'a pas le secret Stripe — j'avais oublié de le pousser dans la preview env Vercel. Erreur opératoire de ma part, OK. Mais une question me reste : pourquoi next build plante-t-il au chargement d'un module qui n'est jamais censé tourner pendant le build statique ?

Pourquoi next build exécute le top-level de mes modules

La réponse tient en une ligne dans la doc Next.js, et elle est facile à manquer. Le compilateur de Next.js ne se contente pas de transformer le TypeScript en JavaScript. Pour analyser les routes API, le tree-shaker, et préparer le runtime serverless, il exécute le top-level de chaque module importé. Concrètement, mon lib/stripe.ts contenait à ce moment-là :

import Stripe from 'stripe'

export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: '2026-03-25.dahlia',
})

new Stripe(...) est une expression d'évaluation immédiate. Le SDK Stripe vérifie la clé dans son constructeur et throw si elle est undefined. Cette vérification arrive donc pendant next build, avant qu'aucune requête réelle n'existe. Mon endpoint webhook n'a jamais été appelé, mais le simple fait que app/api/webhooks/stripe/route.ts importe lib/stripe.ts suffit à déclencher l'exécution du module — et le crash.

Le SDK Stripe a parfaitement raison de valider sa clé tôt. Le principe fail fast (Shore 2004) dit qu'un système doit échouer le plus près possible de la cause de l'erreur. En production, c'est exactement ce que je veux : un secret manquant doit faire planter au démarrage, pas trois jours plus tard sur un appel rare. Le problème, c'est que fail fast devient fail at build dans une architecture où le build est un environnement strict, distinct de l'environnement d'exécution.

Le piège n'est pas Stripe

J'ai un peu cherché dans le repo après ce vendredi. Le même piège attend chaque SDK qui valide ses credentials au constructeur. La liste est plus longue qu'on ne croit : Twilio, certains clients officiels OpenAI et Anthropic selon la version, plusieurs SDK Google Cloud, le client Brevo en mode strict. Chacun a son équivalent du throw new Error('XXX_API_KEY missing') au constructeur, et chacun cassera ton build de la même manière dès que tu l'importeras dans une route que Next.js compile.

Le symptôme se manifeste typiquement sur les preview builds. La prod a tous les secrets, le dev local a un .env.local complet, mais la CI et les previews ont des sous-ensembles d'env vars selon la politique de l'équipe. Une route récente qui passe sa première CI, et le build tombe.

Le pattern : Proxy plus getter paresseux

La correction tient en quinze lignes. Le principe : on ne crée jamais le client SDK au top-level. On expose à la place un objet Proxy qui, à chaque accès de propriété, instancie le client si besoin et délègue. L'erreur de credentials manquantes ne remonte plus qu'au premier appel réel de l'API.

// lib/stripe.ts
import Stripe from 'stripe'

let _stripe: Stripe | null = null

function getStripe(): Stripe {
  if (_stripe) return _stripe
  const key = process.env.STRIPE_SECRET_KEY
  if (!key) throw new Error('STRIPE_SECRET_KEY manquant')
  _stripe = new Stripe(key, { apiVersion: '2026-03-25.dahlia' })
  return _stripe
}

export const stripe = new Proxy({} as Stripe, {
  get(_target, prop, receiver) {
    const client = getStripe()
    const value = Reflect.get(client, prop, receiver)
    return typeof value === 'function' ? value.bind(client) : value
  },
})

Trois choses à noter dans ce code. Premièrement, le Proxy est exporté avec le même nom et le même type que l'ancien export — stripe: Stripe. Tous les appelants existants qui faisaient stripe.checkout.sessions.create(...) continuent à fonctionner sans la moindre modification. C'est la raison principale de choisir Proxy plutôt qu'un export getStripe() qu'il faudrait appeler partout : on évite de toucher à 30 ou 40 fichiers qui consomment l'API publique du SDK.

Deuxièmement, le bind(client) sur les méthodes est nécessaire parce que les méthodes du SDK Stripe utilisent this en interne. Sans le bind, on perd le contexte au passage Proxy et on récupère des TypeError: Cannot read properties of undefined.

Troisièmement, le cache _stripe n'est pas un détail de performance — c'est une garantie de cohérence. Sans lui, chaque accès de propriété créerait un nouveau client, ce qui briserait les comportements stateful (les rate limiters internes du SDK, par exemple) et multiplierait les connexions HTTP keep-alive.

Quand appliquer le pattern, et quand ne pas le faire

Le pattern paie chaque fois qu'un SDK est consommé par une route rarement exercée — webhooks, endpoints administrateur, jobs cron qui ne tournent que sur Vercel scheduled — et que le secret n'est pas systématiquement présent dans tous les environnements de build. C'est exactement le cas Stripe webhook chez moi : un seul appelant, un seul environnement (prod) qui a la clé.

À l'inverse, si le SDK est consommé partout dans l'app et que son absence en build veut dire que ton app ne peut pas fonctionner, le Proxy ne te protège que symboliquement. Tu déplaces juste le crash du build vers le premier render de la première page, ce qui est rarement une amélioration. Dans ce cas-là, mets le secret partout et n'invente pas de pattern.

Petit cadre intermédiaire : si le SDK a un mode dry-run ou un client mock, instancie ce client en l'absence de secret plutôt que throw. C'est plus chirurgical, mais ça suppose que le SDK fournisse l'option — ce que peu font.

Ce que tu peux copier

Le bout de code ci-dessus est intégralement copiable, modulo le nom du SDK et le nom de la variable d'env. Trois adaptations courantes :

// Twilio
import twilio from 'twilio'
let _client: ReturnType<typeof twilio> | null = null
function getClient() {
  if (_client) return _client
  const sid = process.env.TWILIO_ACCOUNT_SID
  const token = process.env.TWILIO_AUTH_TOKEN
  if (!sid || !token) throw new Error('TWILIO credentials missing')
  _client = twilio(sid, token)
  return _client
}
export const twilioClient = new Proxy({} as ReturnType<typeof twilio>, {
  get(_t, prop, r) {
    const c = getClient()
    const v = Reflect.get(c, prop, r)
    return typeof v === 'function' ? v.bind(c) : v
  },
})

Le pattern n'est pas une révolution, et il n'est pas nouveau — c'est juste qu'il est rarement formulé en ces termes par les docs SDK, qui te poussent vers le new Client(...) top-level qui était le bon réflexe pre-serverless. À l'ère des builds compilés et des previews multi-env, le constructeur top-level est devenu un piège silencieux, et ces quinze lignes le neutralisent.

Ma question pour toi : combien d'imports SDK as-tu actuellement au top-level d'un module qu'une route API importe ? Sur Rembrandt, j'en avais quatre — j'ai migré les trois autres après l'incident Stripe, en prévision du jour où l'un de leurs secrets disparaîtrait d'un environnement de build.

Code compagnon : rembrandt-samples/lazy-sdk-proxy/ — pattern Proxy sur Stripe + Twilio + Anthropic, MIT, prêt à copier.