The Friday Vercel refused my merge

Friday April 10th, late afternoon. I merge to main a Stripe integration that opens a payment webhook endpoint. Vercel pushes the preview build automatically, and three minutes later the icon turns red. I click. Build-time stack trace:

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

Production works, it has the env var. The preview doesn't have the Stripe secret — I had forgotten to push it into the Vercel preview env. Operator error on my side, fine. But one question remains: why does next build crash at module load on a module that's never supposed to run during a static build?

Why next build runs the top level of my modules

The answer fits in one line in the Next.js docs, and it's easy to miss. The Next.js compiler doesn't just transform TypeScript into JavaScript. To analyze API routes, tree-shake, and prepare the serverless runtime, it runs the top level of every imported module. Concretely, my lib/stripe.ts looked like this at the time:

import Stripe from 'stripe'

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

new Stripe(...) is an immediately-evaluated expression. The Stripe SDK validates the key in its constructor and throws if it's undefined. That validation therefore fires during next build, before any real request exists. My webhook endpoint was never called, but the mere fact that app/api/webhooks/stripe/route.ts imports lib/stripe.ts is enough to trigger module execution — and the crash.

The Stripe SDK is right to validate its key early. The fail-fast principle (Shore, 2004) says that a system should fail as close as possible to the cause of the error. In production that's exactly what I want: a missing secret should crash on startup, not three days later on a rare call. The problem is that fail fast becomes fail at build in an architecture where the build is a strict environment, distinct from the runtime environment.

The trap is not Stripe

I dug a bit through the repo after that Friday. The same trap awaits every SDK that validates its credentials in the constructor. The list is longer than you'd think: Twilio, certain official OpenAI and Anthropic clients depending on version, several Google Cloud SDKs, the Brevo client in strict mode. Each has its equivalent of throw new Error('XXX_API_KEY missing') in the constructor, and each will break your build the same way as soon as you import it from a route Next.js compiles.

The symptom typically shows up on preview builds. Production has every secret, local dev has a complete .env.local, but CI and previews carry subsets of env vars depending on team policy. A recent route runs through CI for the first time, and the build falls over.

The pattern: Proxy plus lazy getter

The fix fits in fifteen lines. The principle: never create the SDK client at the top level. Instead, expose a Proxy object that, on every property access, instantiates the client if needed and delegates. A missing-credentials error surfaces only on the first real API call.

// 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 missing')
  _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
  },
})

Three things to note in this code. First, the Proxy is exported with the same name and the same type as the previous export — stripe: Stripe. Every existing caller doing stripe.checkout.sessions.create(...) keeps working without a single change. That's the main reason to choose Proxy over an exported getStripe() you'd have to call everywhere: you avoid touching 30 or 40 files that consume the SDK's public API.

Second, the bind(client) on methods is necessary because Stripe SDK methods use this internally. Without bind, you lose context across the Proxy hop and you get TypeError: Cannot read properties of undefined.

Third, the _stripe cache isn't a performance detail — it's a consistency guarantee. Without it, every property access would create a new client, which would break stateful behaviors (the SDK's internal rate limiters, for example) and multiply HTTP keep-alive connections.

When to apply the pattern, and when not to

The pattern pays off whenever an SDK is consumed by a rarely-exercised route — webhooks, admin endpoints, cron jobs that only run via Vercel scheduled — and the secret isn't systematically present in every build environment. That's exactly the Stripe webhook case for me: one caller, one environment (production) with the key.

Conversely, if the SDK is consumed everywhere in the app and its absence at build means your app cannot function, the Proxy only protects you symbolically. You're just shifting the crash from build to first-render of the first page, which is rarely an improvement. In that case, put the secret everywhere and don't invent a pattern.

A small middle ground: if the SDK has a dry-run mode or a mock client, instantiate that client when the secret is missing instead of throwing. It's more surgical, but it assumes the SDK provides the option — and few do.

What you can copy

The code above is fully copyable, modulo the SDK name and the env variable name. Three common adaptations:

// 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
  },
})

The pattern isn't a revolution, and it isn't new — it's just rarely formulated this way by SDK docs, which push you toward the new Client(...) top-level that was the right reflex pre-serverless. In the era of compiled builds and multi-env previews, the top-level constructor has become a silent trap, and these fifteen lines neutralize it.

My question for you: how many top-level SDK imports do you currently have in a module that an API route imports? On Rembrandt I had four — I migrated the other three after the Stripe incident, in anticipation of the day one of their secrets would disappear from a build environment.

Companion code: rembrandt-samples/lazy-sdk-proxy/ — lazy-Proxy pattern on Stripe + Twilio + Anthropic SDKs, MIT, copy-pastable.