Railway Deployment Notes (Frontend Standard)

This document captures standards-relevant Railway considerations for Next.js frontends.

Internal/private service URLs (required)

Railway provides internal/private hostnames intended for service-to-service connectivity within a Railway project.

Standards requirements:

• The browser must never call internal/private service hostnames.
• Internal/private backend base URLs must be server-only env vars (not NEXT_PUBLIC_*).
• Next.js Route Handlers call the backend using the internal/private URL.

This aligns with the BFF architecture described in Frontend → Overview → Architecture.

Build-time vs runtime (required)

Avoid requiring backend connectivity during next build:

• Don’t fetch backend data in build-time execution paths unless you’re sure the backend is reachable then.
• Prefer runtime requests via Route Handlers (or runtime Server Component fetches).

Networking notes

If internal connectivity fails between services on Railway, verify:

• the backend service is listening on the correct interface for internal traffic (project-specific; document in the backend repo)

Reference

• Railway docs on service environment variables and connectivity patterns: https://docs.railway.com/guides/postgresql