Skip to content

[Draft] Add initial Next.js server-side Convex data path #64

@BASIC-BIT

Description

@BASIC-BIT

Problem

After the first client-side Next.js -> Convex runtime path lands, VRDex still needs a documented and working baseline for server-side data access.

The app will eventually need both reactive client reads and server-side reads, but we should add the first server-side pattern intentionally instead of mixing it into the initial wiring issue.

Why now

  • the product direction already assumes frontend/server rendering can use internal server-side data paths where convenient
  • early App Router decisions tend to stick, so the first server-side pattern should be explicit and easy to copy
  • separating this from the first client-side integration keeps #55 narrow while still capturing the next architectural step

Scope

  • add one minimal server-side Next.js read path to the existing Convex backend
  • choose and document the initial pattern for server components and any preload/hydration handoff used in the app router
  • keep the pattern compatible with the existing client-side provider path instead of replacing it
  • show where server-side Convex reads belong versus reactive client reads
  • keep the implementation small and friendly to later auth, caching, and domain-schema work

Non-goals

  • broad migration of the app to server-side-only data access
  • auth-aware personalization
  • production caching strategy
  • complex suspense/loading architecture
  • adding multiple competing server data patterns in the same issue
  • introducing billing, deployment, or schema-heavy product work

Acceptance criteria

  • the repo has one working server-side Next.js read path into Convex
  • the chosen pattern is documented clearly enough for follow-on app work
  • the relationship between server-side reads and client-side reactive reads is explicit
  • the implementation stays compatible with later auth and deployment work
  • the issue leaves the app with a small, copyable baseline instead of experimental complexity

Current recommendation

  • keep #55 limited to the first client runtime path
  • use this issue for the first server component or preload-oriented Convex integration once the client path is stable
  • prefer one obvious baseline pattern over a menu of alternatives

Likely dependencies

  • #54 Bootstrap initial Convex backend
  • #55 Wire initial Next.js app to Convex backend

Likely follow-on dependents

  • auth-aware app-shell work
  • public profile page implementation
  • search/result pages that benefit from server-rendered first paint
  • hosted deployment hardening once environment and caching expectations are clearer

Docs to update

  • README.md
  • docs/backend/convex-bootstrap.md
  • docs/planning/engineering-strategy.md
  • any app/backend integration doc added during implementation

Suggested labels

  • phase:v0.5
  • area:web
  • area:backend
  • area:docs

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions