Skip to content

Frontend variant (blocked): SSR meta-frameworks — Next.js / Nuxt / SvelteKit #159

Open

Description

@kamkie

Status: BLOCKED — blocked: architecture-conflict

Proposed and deliberately not accepted as-is. This issue documents the analysis so it is not re-litigated, and records exactly what a future contract decision would have to change to unblock it.

Covers the SSR meta-frameworks as one record because they share an identical block reason:

  • Next.js (React)
  • Nuxt (Vue)
  • SvelteKit (Svelte)

Why it is blocked

The frontend contract (frontends/README.md, docs/ARCHITECTURE.md) fixes the frontend as:

  • a static SPA, whose production image is a long-running static-file server on internal port 8080 with SPA fallback, reached only through the gateway;
  • a component that holds no auth state — not even a token — and makes same-origin /api/v{n} JSON calls, asking GET /auth/session who is logged in.

The gateway already supports two delivery mechanisms: proxy an upstream through FRONTEND_URL, or serve a local static build through SPA_ROOT. FRONTEND_URL can technically point at a long-running dynamic server, so hosting a Node process behind the gateway is not itself the blocker. Both documented modes currently serve the static-SPA frontend contract.

True SSR still conflicts with that contract on three points:

  1. Frontend contract. Headline-mode SSR runs a per-request rendering server with server loaders/route handlers, rather than shipping a static SPA from the standard frontend image.
  2. Identity boundary. Every current gateway strips the browser's Cookie header before proxying frontend traffic. The renderer receives neither the opaque stackverse_session key nor an access token, so it cannot render authenticated bookmarks or call /api on the user's behalf. This is deliberate: browser cookies and tokens are gateway-only state.
  3. New cross-gateway protocol. Personalized SSR therefore needs a trusted gateway → renderer identity/data-relay contract implemented consistently by every gateway. FRONTEND_URL alone does not provide that contract.

Run purely client-side (Next output: 'export', Nuxt ssr: false, SvelteKit adapter-static + SPA fallback), each collapses back to plain React/Vue/Svelte — redundant with existing frontends and it undersells the framework (its reason to exist is SSR). So the low-risk form adds ~no comparison value, and the high-value form changes the architectural axis.

How an implementation could look

A. CSR-only (technically unblocked today, but low value):

  • Next → next build with output: 'export'; Nuxt → nuxt generate with ssr:false; SvelteKit → @sveltejs/adapter-static with a fallback: index.html.
  • Serve the emitted static bundle on port 8080 with SPA fallback; load spec/design/*.css verbatim; consume /api JSON; /auth/session, XSRF-TOKEN → X-XSRF-TOKEN, i18n bundle — identical to the other frontends.
  • Verdict: this is "React/Vue/Svelte again," so it would not earn a matrix row on its own.

B. True SSR (requires a contract decision — see below):

  • A per-frontend Node SSR server sits behind the gateway on FRONTEND_URL; the browser still has one public origin and talks only to the gateway.
  • Under the current contract the gateway removes cookies before forwarding that request, so the renderer can only produce anonymous/public HTML or defer personalized loading to client-side code.
  • An extended architecture would define a trusted identity/data relay from gateway to renderer and the renderer's server-to-server path back to /api, while keeping access tokens at the gateway.
  • This is effectively a two-hop, server-rendered BFF — a genuinely different architecture, not a drop-in frontend variant.

What would unblock it

A deliberate docs/ARCHITECTURE.md + docs/INTENT.md + frontends/README.md decision to support a server-rendered frontend tier, replace the static-image requirement for that tier, and specify a gateway → renderer identity/data-relay protocol that keeps tokens at the edge. Because this changes the shared gateway contract, every gateway would need the same behavior and acceptance coverage. Per AGENTS.md ground rules this is assumed rejected by default. Until then, blocked.

References

Activity

  1. added
    enhancementNew feature or request
    priority: lowBacklog — revisit when the matrix grows
    blocked: architecture-conflictConflicts with a core Stackverse invariant (static SPA, session at edge); non-goal per INTENT.md.
    on Jul 5, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    blocked: architecture-conflictConflicts with a core Stackverse invariant (static SPA, session at edge); non-goal per INTENT.md.enhancementNew feature or requestpriority: lowBacklog — revisit when the matrix grows

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions