5.9 - A missing NEXT_PUBLIC_API_URL silently targets the visitor's own machine

[determined-001]

Complexity: Trivial - 100 Points · type:dx

Milestone: M4 - Merchant surface

Band lever: none

Context
apps/web/lib/api.ts:76 reads
process.env.NEXT_PUBLIC_API_URL ?? "http://localhost:8787". The fallback is
right for local development and wrong everywhere else.

Problem
NEXT_PUBLIC_* values are baked at build time, so forgetting this variable on a
deployed build is not caught by anything at deploy time. Every dashboard request
then targets localhost:8787 in the visitor's browser — connection refused,
with no error message naming the real cause. docs/MAINNET.md already calls out
this exact class of footgun for NEXT_PUBLIC_STELLAR_NETWORK; this variable has
the same failure mode and no such note.

What needs to be done

1. Keep the localhost fallback only when process.env.NODE_ENV !== "production".
2. In a production build with the variable unset, fail loudly — throw at module
   load, or render a clear configuration error rather than issuing doomed
   requests.
3. Document the variable alongside NEXT_PUBLIC_STELLAR_NETWORK in
   docs/MAINNET.md and .env.public.example, with the same "rebuild after
   changing" warning.

Key files

• apps/web/lib/api.ts:76 — BROWSER_BASE
• docs/MAINNET.md — the existing NEXT_PUBLIC_* footgun section
• .env.public.example

Done when

• A production build with the variable unset fails with a message naming it.
• Local development is unaffected.

---

Tracked in ISSUES.md — issue 5.9.

[Mamavee001]

@Mamavee001 has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

I’d like to work on Issue #155 because a missing NEXT_PUBLIC_API_URL currently causes the frontend to silently send API requests to localhost:8787, which is useful for local development but incorrect and confusing in production.

I will first review apps/web/lib/api.ts, the existing environment-variable handling, and the related documentation in docs/MAINNET.md and .env.public.example.

I will update the BROWSER_BASE logic so the localhost fallback is available only outside production. In production, when NEXT_PUBLIC_API_URL is missing, the application will fail clearly with an error that explicitly names the missing variable instead of allowing requests to be sent to the visitor's own machine.

I will keep the local development experience unchanged, so developers can continue running the frontend against the default local API without additional configuration.

I will also document NEXT_PUBLIC_API_URL alongside NEXT_PUBLIC_STELLAR_NETWORK, including the build-time nature of NEXT_PUBLIC_* variables and the requirement to rebuild the application after changing the value.

Finally, I will add or update tests covering both scenarios: local development without the variable should continue to use the localhost fallback, while a production build without NEXT_PUBLIC_API_URL should fail deterministically with a clear configuration error.

My goal is to turn a silent production misconfiguration into an immediate, actionable failure while keeping local development exactly as convenient as it is today.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Mamavee001 to this issue.

[drips-wave]

Congratulations, @Mamavee001! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on August 31, 2026.

🧑‍💻 @Mamavee001: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊