Calling a Separate Backend

// A. The browser calls the backend directly
//    browser -> api.aicancode.org (FastAPI on Fly)
//    + one hop, no Next server involved
//    - CORS applies, the token must be reachable by JS or the cookie
//      must be same-site, and nothing is server-rendered
NEXT_PUBLIC_API_URL=https://api.aicancode.org

// B. The Next server calls the backend, then renders
//    browser -> Next (Vercel) -> api.aicancode.org
//    + no CORS at all (server to server), the token never reaches the
//      browser, HTML arrives ready to read, SEO works
//    - an extra hop, and Vercel and Fly should be in the same region
//      or you pay for the distance twice
API_URL=https://api.aicancode.org          // server-only, no NEXT_PUBLIC_

// Most apps use both: B for the initial render and anything secret,
// A for interactive updates after the page is live.

// A third option worth knowing — proxy through Next so the browser
// only ever sees one origin:
// next.config.js
async rewrites() {
  return [{ source: '/api/:path*', destination: `${process.env.API_URL}/:path*` }]
}
// Cookies become first-party and CORS disappears, at the cost of
// routing traffic through Vercel.

// A server component has no browser attached, so nothing is sent
// automatically. This call is ANONYMOUS:
const res = await fetch(`${process.env.API_URL}/me`)      // 401

// Forward the cookie explicitly:
import { cookies } from 'next/headers'

export async function apiFetch(path: string, init: RequestInit = {}) {
  const res = await fetch(`${process.env.API_URL}${path}`, {
    ...init,
    headers: {
      ...init.headers,
      cookie: cookies().toString(),          // the user's session
      'X-Request-Id': crypto.randomUUID(),   // correlate the logs
    },
    cache: 'no-store',                        // per-user: never cache
  })
  if (!res.ok) throw new ApiError(res.status, await res.text())
  return res.json()
}

// Two things this makes true at once:
//   - calling cookies() makes the route dynamic, which is correct for
//     per-user data
//   - 'no-store' keeps one user's response out of another's page

// For service-to-service calls with no user, send a service token
// instead — and never a NEXT_PUBLIC_ one:
headers: { Authorization: `Bearer ${process.env.SERVICE_TOKEN}` }

# Generate the client types from the backend's OpenAPI schema
npx openapi-typescript $API_URL/openapi.json -o src/generated/api.ts
# and fail CI on drift, so a renamed field breaks the build rather
# than production. (The Full-Stack Integration track covers the why.)

// Timeouts: the Next server calling a slow backend will hold a
// serverless function open and eventually hit the platform limit.
// Always bound it:
fetch(url, { signal: AbortSignal.timeout(8000) })
// and budget downward: browser 10s > Next 8s > backend 5s.

// A backend outage should degrade, not blank the page:
try {
  const stats = await apiFetch('/stats')
  return <Stats data={stats} />
} catch {
  return <StatsUnavailable />        // the rest of the page survives
}
// Or let it throw and let error.tsx contain it to that segment.

// Cold starts compound: Vercel wakes, then Fly wakes. Keep
// min_machines_running = 1 on the backend for anything user-facing,
// or the first visitor after a quiet period waits for both.