Repository navigation
Add build-time validation for NEXT_PUBLIC_STELLAR_NETWORK and API URL config #26
Description
Problem
src/lib/config.ts reads NEXT_PUBLIC_API_URL and NEXT_PUBLIC_STELLAR_NETWORK as plain process.env accesses with a hardcoded fallback default (http://localhost:4000/api and TESTNET) and no validation. Because these are NEXT_PUBLIC_* vars, they're baked into the client bundle at build time. There is a realistic and dangerous misconfiguration scenario specific to this app's domain: a production build accidentally shipped with NEXT_PUBLIC_STELLAR_NETWORK unset or misspelled (e.g. "MAINNET" instead of the expected "PUBLIC") silently falls back to "TESTNET" per STELLAR_NETWORK's default — meaning wallet.ts#signTransaction's network-passphrase selection (STELLAR_NETWORK === "PUBLIC" ? ... : "Test SDF Network...") would sign transactions with the testnet passphrase in what's meant to be a production deployment handling real funds, or the inverse (a test/staging environment accidentally pointed at the real Stellar public network passphrase), either of which causes transactions to fail confusingly at the Soroban contract layer or, in the worse direction, could let a misconfigured staging environment attempt operations against real mainnet assets.
Why this is hard
- This requires understanding the actual deployment topology (production vs. staging vs. preview builds) which isn't documented in this repo — you'll need to infer or ask what env-var management looks like across Vercel/whatever hosting is used, since
NEXT_PUBLIC_*vars are baked in at build time, not runtime, meaning a "fix it after deploy" approach doesn't work; validation must happen at build time to be useful. - The silent-fallback-to-a-plausible-default pattern (
?? "TESTNET") is exactly the kind of bug that passes all normal testing (the app "works," just against the wrong network) and is only caught when a real signed transaction fails on-chain — you need to change the failure mode from "silently works against the wrong network" to "fails loudly at build time if misconfigured," which requires deciding whether a default should exist at all for the network variable in particular (arguably it shouldn't — network selection is too consequential to default silently) versus keeping a safe default forNEXT_PUBLIC_API_URL(localhost fallback is reasonable for local dev). - Must add this validation without breaking the documented
npm install && cp .env.example .env.local && npm run devlocal quickstart flow from the README, i.e. local dev with the.env.exampledefaults must still work with zero required extra configuration. - Should also validate
NEXT_PUBLIC_API_URL's shape (valid URL, not empty string, not accidentally pointing at production from a local.env.localcopy-paste mistake) to catch a related but distinct class of misconfiguration.
Scope
- Add build-time validation (e.g. in
next.config.tsor a dedicated validated-env module imported byconfig.ts) that fails the build loudly ifNEXT_PUBLIC_STELLAR_NETWORKis set to anything other than the two valid values, with no silent fallback for this specific variable in non-local builds. - Add URL-shape validation for
NEXT_PUBLIC_API_URL. - Update
.env.exampleand README if the validation changes required/optional variable semantics. - Add a visible, impossible-to-miss runtime indicator (e.g. in a corner of the UI, dev/staging builds only) showing which Stellar network the build is configured for, to catch misconfiguration that somehow still passes build-time checks (e.g. a correct-looking but wrong value at the account/environment level).
Acceptance criteria
- A build with an invalid
NEXT_PUBLIC_STELLAR_NETWORKvalue fails at build time with a clear error, not at runtime during a user's wallet signing attempt. - Local dev with the checked-in
.env.examplestill works with zero manual edits required. - A non-production build visibly indicates its configured network somewhere in the UI.
Activity
prodbycorne commentedon Jul 16, 2026
I can take ownership of this issue by replacing the current silent environment fallback behavior with explicit validation and safer configuration handling.
The first step would be auditing how
NEXT_PUBLIC_API_URLandNEXT_PUBLIC_STELLAR_NETWORKare loaded and consumed, especially around Next.js build-time variable injection. I'll add validation that fails early for invalid Stellar network values, validates API URL formatting, and preserves the existing local development flow using the checked-in environment defaults.I'll also update the relevant documentation/config examples and add a small development/staging indicator showing the configured Stellar network so incorrect deployments are easier to catch. The goal is to make misconfiguration fail loudly during development or deployment rather than during wallet signing or transaction execution. I have experience with Next.js applications, environment configuration, and blockchain-related frontend flows, and I can deliver this with focused changes and tests.
grantfox-oss commentedon Jul 16, 2026
🦊 GrantFox — @prodbycorne has been assigned to this issue as part of the Official Campaign | FWC26 campaign!
Next steps:
Closes #26)Good luck! Track your progress on GrantFox.
feat(env): add build-time validation for NEXT_PUBLIC_* config (#26)
feat(config): validate env at next.config.ts module-evaluation time (#26
feat(config): route config.ts's exports through the validated env (#26)
docs(env): add .env.example, exempted from the blanket .env* gitignore (
docs(readme): document the no-default network variable and fix API UR…
feat(ui): add a visible network indicator badge to the navbar (#26)
grantfox-oss commentedon Jul 19, 2026
🎉 This issue has been marked as completed on GrantFox as part of the Official Campaign | FWC26 campaign!
@prodbycorne's PR #66 was approved and merged by @chonilius.
🏆 @prodbycorne: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (131 total points). Track your full progress on GrantFox.
👏 Great work, @prodbycorne! Keep contributing to MergeFi.
test(env): add automated verification against real next build runs (#26)
ci: run env validation and set NEXT_PUBLIC_STELLAR_NETWORK for the bu…
ci: move NEXT_PUBLIC_STELLAR_NETWORK to job-level env (#26)