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 — 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?
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.
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 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.
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 can’t even start, then a build-time crash is the correct behavior.
This isn’t just about Stripe. It’s about how serverless functions, edge runtimes, and modern build tooling conspire to create environments where build-time checks can be too strict, masking runtime realities. The Proxy pattern offers a graceful decoupling of immediate execution from deferred necessity. It’s a small patch, but it highlights a larger architectural tension between compile-time certainty and runtime flexibility that we’ll likely see more of.
Why Does This Matter for Developers?
This problem, while seemingly niche, points to a fundamental tension in modern JavaScript development: the blurring lines between build-time analysis and runtime execution. Frameworks like Next.js, in their quest for optimization and performance, aggressively analyze and even execute parts of your code during the build phase. This is great for tasks like code splitting and tree-shaking, but it breaks spectacularly when external dependencies—like SDKs that aggressively validate API keys in their constructors—are involved. These SDKs, designed for fail-fast behavior in production, become brittle liabilities in the constrained, often incomplete, environments of CI/preview builds. The fifteen-line Proxy solution isn’t just a workaround; it’s an architectural pattern for dealing with SDKs that enforce strict checks before they’re actually needed, ensuring that your CI pipeline doesn’t choke on environmental differences.
Is This Proxy Pattern a Silver Bullet?
No. The Proxy pattern, while elegant, isn’t a universal panacea for all SDK integration issues. Its effectiveness hinges on the specific behavior of the SDK. If an SDK’s internal logic relies heavily on immediate client instantiation for critical, non-delegable setup—or if its methods are incompatible with Proxy delegation due to complex this contexts or internal state management beyond simple property access—then this pattern might not work or could introduce subtle bugs. Furthermore, it’s a band-aid, not a cure. The ideal solution would involve SDKs offering more flexible initialization options or build tools providing more granular control over module execution during compilation. But for many common cases, particularly those involving environment-variable-dependent SDKs, it’s a pragmatic and remarkably concise fix that keeps your CI green.
🧬 Related Insights
- Read more: React Native’s New Architecture: It’s Live!
- Read more: How FOSS Force Is Staying Alive on $34 a Day—and What That Says About Independent Tech Journalism
Frequently Asked Questions
What does STRIPE_SECRET_KEY missing mean?
It means the Stripe SDK tried to initialize itself, expecting a secret API key to be available in your environment variables, but it couldn’t find one. This usually happens during a build process when environment variables aren’t fully configured.
Will this fix break my existing Stripe integration?
No, the provided Proxy code is designed to be a drop-in replacement. It exports an object named stripe with the same Stripe type, so existing calls like stripe.checkout.sessions.create() should continue to work without modification.
Can I use this for other SDKs that have similar issues?
Yes, the pattern is generalizable. If another SDK validates credentials or performs critical setup in its constructor and causes build failures in certain environments, you can adapt this Proxy pattern to defer its initialization until it’s actually needed.
