From 28521cc9ed5919f8a39b8fcd050bd50bbeb6e100 Mon Sep 17 00:00:00 2001 From: Gabriel Kaszewski Date: Sat, 16 May 2026 02:03:52 +0200 Subject: [PATCH] docs: suspense + streaming implementation plan --- .../plans/2026-05-16-suspense-streaming.md | 579 ++++++++++++++++++ 1 file changed, 579 insertions(+) create mode 100644 docs/superpowers/plans/2026-05-16-suspense-streaming.md diff --git a/docs/superpowers/plans/2026-05-16-suspense-streaming.md b/docs/superpowers/plans/2026-05-16-suspense-streaming.md new file mode 100644 index 0000000..7c6c526 --- /dev/null +++ b/docs/superpowers/plans/2026-05-16-suspense-streaming.md @@ -0,0 +1,579 @@ +# Suspense Boundaries & Streaming Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Stream the feed page immediately while sidebar widgets load independently, and fix the N+1 top-friends profile fetch by having the backend return full user objects in one query. + +**Architecture:** The `TopFriendRepository::list_for_user` already JOINs users — the backend just discards the user data and returns only usernames. We fix the handler to return `Vec`. Frontend: `TopFriends` becomes self-contained (fetches its own data via cookies, no props from page), wrapped in ``. `app/page.tsx` drops all sidebar awaits, reducing critical-path work to two parallel calls. + +**Tech Stack:** Rust/Axum (backend), Next.js 15 App Router, React 19 Suspense, Tailwind CSS, shadcn/ui + +--- + +## Key Facts + +- `TopFriendRepository::list_for_user` already returns `Vec<(TopFriend, User)>` — the JOIN with the users table is done. The handler just discards the `User` data. +- `to_user_response(u: &User) -> UserResponse` lives in `crates/presentation/src/handlers/auth.rs` as `pub fn` — import it where needed. +- Auth token in frontend server components: `(await cookies()).get("auth_token")?.value ?? null` via `next/headers`. +- Baseline test suite: `cargo test` (148 tests) in the backend; `npx tsc --noEmit` in `thoughts-frontend/`. + +--- + +## File Map + +| File | Change | +|---|---| +| `crates/api-types/src/responses.rs` | Add `TopFriendsResponse { top_friends: Vec }` | +| `crates/presentation/src/handlers/social.rs` | Return `TopFriendsResponse` instead of `{ topFriends: usernames }` | +| `thoughts-frontend/lib/api.ts` | Update `getTopFriends` schema to `z.array(UserSchema)` | +| `thoughts-frontend/components/loading-skeleton.tsx` | Add `TagsSkeleton`, `CountSkeleton` | +| `thoughts-frontend/components/top-friends.tsx` | Self-contained: fetches own data, no `usernames` prop | +| `thoughts-frontend/app/page.tsx` | Strip `getFriends`/`getTopFriends`/`shouldDisplayTopFriends`; add Suspense | +| `thoughts-frontend/app/loading.tsx` | New — feed page skeleton | +| `thoughts-frontend/app/tags/[tagName]/loading.tsx` | New | +| `thoughts-frontend/app/search/loading.tsx` | New | +| `thoughts-frontend/app/thoughts/[thoughtId]/loading.tsx` | New | + +--- + +## Task 1: Add `TopFriendsResponse` to api-types + +**Files:** +- Modify: `crates/api-types/src/responses.rs` + +- [ ] **Step 1: Add the response struct** + +In `crates/api-types/src/responses.rs`, after the `NotificationResponse` block, add: + +```rust +#[derive(Serialize, utoipa::ToSchema)] +#[serde(rename_all = "camelCase")] +pub struct TopFriendsResponse { + pub top_friends: Vec, +} +``` + +- [ ] **Step 2: Verify it compiles** + +```bash +cargo build -p api-types +``` + +Expected: Compiles with no errors. + +- [ ] **Step 3: Commit** + +```bash +git add crates/api-types/src/responses.rs +git commit -m "feat(api-types): TopFriendsResponse with Vec" +``` + +--- + +## Task 2: Update `get_top_friends_handler` to return full user objects + +**Files:** +- Modify: `crates/presentation/src/handlers/social.rs` + +- [ ] **Step 1: Read the current handler** + +Current code (around line 159–167 in `social.rs`): + +```rust +pub async fn get_top_friends_handler( + Deps(d): Deps, + Path(username): Path, +) -> Result, ApiError> { + let user = get_user_by_username(&*d.users, &username).await?; + let friends = get_top_friends(&*d.top_friends, &user.id).await?; + let usernames: Vec<&str> = friends.iter().map(|(_, u)| u.username.as_str()).collect(); + Ok(Json(serde_json::json!({ "topFriends": usernames }))) +} +``` + +`friends` is already `Vec<(TopFriend, User)>` — the user data is there. + +- [ ] **Step 2: Add import and update the handler** + +Add to the imports at the top of `social.rs`: +```rust +use api_types::responses::TopFriendsResponse; +use crate::handlers::auth::to_user_response; +``` + +Replace the handler body: + +```rust +#[utoipa::path(get, path = "/users/{username}/top-friends", + params(("username" = String, Path, description = "Username")), + responses((status = 200, description = "Top friends list", body = TopFriendsResponse)))] +pub async fn get_top_friends_handler( + Deps(d): Deps, + Path(username): Path, +) -> Result, ApiError> { + let user = get_user_by_username(&*d.users, &username).await?; + let friends = get_top_friends(&*d.top_friends, &user.id).await?; + let top_friends = friends.iter().map(|(_, u)| to_user_response(u)).collect(); + Ok(Json(TopFriendsResponse { top_friends })) +} +``` + +- [ ] **Step 3: Run backend tests** + +```bash +cargo test +``` + +Expected: 148 tests pass (same as before — no test exercises the response shape directly). + +- [ ] **Step 4: Smoke-test the endpoint manually (optional)** + +```bash +curl -s -H "Authorization: Bearer " http://localhost:3001/users/me/top-friends | python3 -m json.tool +``` + +Expected: `{ "topFriends": [ { "id": "...", "username": "...", "avatarUrl": "...", ... } ] }` + +- [ ] **Step 5: Commit** + +```bash +git add crates/presentation/src/handlers/social.rs +git commit -m "fix(api): top-friends endpoint returns full UserResponse — eliminates frontend N+1" +``` + +--- + +## Task 3: Update frontend `getTopFriends` Zod schema + +**Files:** +- Modify: `thoughts-frontend/lib/api.ts` + +- [ ] **Step 1: Find and update `getTopFriends`** + +In `lib/api.ts`, find `getTopFriends` (around line 232). Current: + +```ts +export const getTopFriends = (username: string, token: string | null) => + apiFetch( + `/users/${username}/top-friends`, + { next: { tags: [`profile:${username}`] } }, + z.object({ topFriends: z.array(z.string()) }), + token + ); +``` + +Replace with: + +```ts +export const getTopFriends = (username: string, token: string | null) => + apiFetch( + `/users/${username}/top-friends`, + { next: { tags: [`profile:${username}`] } }, + z.object({ topFriends: z.array(UserSchema) }), + token + ); +``` + +`UserSchema` is already defined in the same file — no new import needed. + +- [ ] **Step 2: Type-check** + +```bash +cd thoughts-frontend && npx tsc --noEmit +``` + +Expected: 0 errors. (TypeScript will flag call sites that use `getTopFriends` and expect `string[]` — these are fixed in Task 4.) + +If errors: note them, they'll be resolved in Task 4. + +- [ ] **Step 3: Commit** + +```bash +git add thoughts-frontend/lib/api.ts +git commit -m "fix(frontend): getTopFriends schema returns UserSchema[] not string[]" +``` + +--- + +## Task 4: Add `TagsSkeleton` and `CountSkeleton` to loading-skeleton.tsx + +**Files:** +- Modify: `thoughts-frontend/components/loading-skeleton.tsx` + +- [ ] **Step 1: Add the two new exports** + +In `thoughts-frontend/components/loading-skeleton.tsx`, append after the existing exports: + +```tsx +export function TagsSkeleton() { + return ( + + + + {[...Array(5)].map((_, i) => ( + + ))} + + + ) +} + +export function CountSkeleton() { + return ( + + + + + + ) +} +``` + +`Card`, `CardContent`, and `Skeleton` are already imported in the file. + +- [ ] **Step 2: Type-check** + +```bash +cd thoughts-frontend && npx tsc --noEmit +``` + +Expected: 0 errors. + +- [ ] **Step 3: Commit** + +```bash +git add thoughts-frontend/components/loading-skeleton.tsx +git commit -m "feat(frontend): TagsSkeleton and CountSkeleton for sidebar Suspense fallbacks" +``` + +--- + +## Task 5: Rewrite `TopFriends` to be self-contained + +**Files:** +- Modify: `thoughts-frontend/components/top-friends.tsx` + +- [ ] **Step 1: Replace the component** + +Replace the entire file with: + +```tsx +import Link from "next/link"; +import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card"; +import { UserAvatar } from "./user-avatar"; +import { getTopFriends } from "@/lib/api"; +import { cookies } from "next/headers"; + +interface TopFriendsProps { + username: string; +} + +export async function TopFriends({ username }: TopFriendsProps) { + const token = (await cookies()).get("auth_token")?.value ?? null; + const data = await getTopFriends(username, token).catch(() => ({ topFriends: [] })); + const friends = data.topFriends; + + if (friends.length === 0) return null; + + return ( + + + + Top Friends + + + + {friends.map((friend) => ( + + + + {friend.displayName || friend.username} + + + ))} + + + ); +} +``` + +Changes from old component: +- Props: was `{ mode, usernames: string[] }`, now `{ username: string }` — fetches its own data +- No more N+1 `getUserProfile` calls — renders `data.topFriends` (already `User[]`) directly +- `mode` prop removed — always shows "Top Friends" title (the "friends fallback" mode is dropped) +- Returns `null` if no top friends (sidebar just hides the widget) + +- [ ] **Step 2: Type-check** + +```bash +cd thoughts-frontend && npx tsc --noEmit +``` + +Expected: Errors at `app/page.tsx` call sites (still pass old props) — will be fixed in Task 6. + +- [ ] **Step 3: Commit (even with type errors from call sites)** + +```bash +git add thoughts-frontend/components/top-friends.tsx +git commit -m "refactor(frontend): TopFriends self-contained — fetches own data, no N+1" +``` + +--- + +## Task 6: Update `app/page.tsx` — strip blocking awaits + add Suspense + +**Files:** +- Modify: `thoughts-frontend/app/page.tsx` + +- [ ] **Step 1: Update imports** + +Replace the current import block at the top of `app/page.tsx`: + +```ts +import type { Metadata } from "next"; +import { cookies } from "next/headers"; +import { getFeed, getMe, Me } from "@/lib/api"; +import { ThoughtForm } from "@/components/thought-form"; +import { EmptyState } from "@/components/empty-state"; +import { Button } from "@/components/ui/button"; +import Link from "next/link"; +import { PopularTags } from "@/components/popular-tags"; +import { ThoughtThread } from "@/components/thought-thread"; +import { buildThoughtThreads } from "@/lib/utils"; +import { TopFriends } from "@/components/top-friends"; +import { UsersCount } from "@/components/users-count"; +import { PaginationNav } from "@/components/pagination-nav"; +import { redirect } from "next/navigation"; +import { Suspense } from "react"; +import { ProfileSkeleton, TagsSkeleton, CountSkeleton } from "@/components/loading-skeleton"; +``` + +(Removed: `getFriends`, `getTopFriends`, `User`) + +- [ ] **Step 2: Replace `FeedPage` function** + +```tsx +async function FeedPage({ + token, + searchParams, +}: { + token: string; + searchParams: { page?: string }; +}) { + const page = parseInt(searchParams.page ?? "1", 10); + + const [feedData, me] = await Promise.all([ + getFeed(token, page).catch(() => null), + getMe(token).catch(() => null) as Promise, + ]); + + if (!feedData || !me) { + redirect("/login"); + } + + const { items: allThoughts, totalPages } = feedData!; + const thoughtThreads = buildThoughtThreads(allThoughts); + + const sidebar = ( + <> + }> + + + }> + + + }> + + + + ); + + return ( +
+
+ + +
+
+

Your Feed

+
+ + +
+ {sidebar} +
+ +
+ {thoughtThreads.map((thought) => ( + + ))} + {thoughtThreads.length === 0 && ( + + )} +
+ `/?page=${p}`} + /> +
+ + +
+
+ ); +} +``` + +- [ ] **Step 3: Type-check** + +```bash +cd thoughts-frontend && npx tsc --noEmit +``` + +Expected: 0 errors. + +- [ ] **Step 4: Commit** + +```bash +git add thoughts-frontend/app/page.tsx +git commit -m "perf(frontend): stream sidebar via Suspense — feed renders immediately, sidebar loads async" +``` + +--- + +## Task 7: Add `loading.tsx` files for pages missing them + +**Files:** +- Create: `thoughts-frontend/app/loading.tsx` +- Create: `thoughts-frontend/app/tags/[tagName]/loading.tsx` +- Create: `thoughts-frontend/app/search/loading.tsx` +- Create: `thoughts-frontend/app/thoughts/[thoughtId]/loading.tsx` + +- [ ] **Step 1: Create `thoughts-frontend/app/loading.tsx`** + +This matches the feed page layout (3-column grid with feed column visible): + +```tsx +import { ThoughtSkeleton } from "@/components/loading-skeleton"; + +export default function FeedLoading() { + return ( +
+
+
+
+ ); +} +``` + +- [ ] **Step 2: Create `thoughts-frontend/app/tags/[tagName]/loading.tsx`** + +```tsx +import { ThoughtSkeleton } from "@/components/loading-skeleton"; + +export default function TagLoading() { + return ( +
+
+ + + +
+ ); +} +``` + +- [ ] **Step 3: Create `thoughts-frontend/app/search/loading.tsx`** + +```tsx +import { ThoughtSkeleton } from "@/components/loading-skeleton"; + +export default function SearchLoading() { + return ( +
+
+ + + +
+ ); +} +``` + +- [ ] **Step 4: Create `thoughts-frontend/app/thoughts/[thoughtId]/loading.tsx`** + +```tsx +import { ThoughtSkeleton } from "@/components/loading-skeleton"; + +export default function ThoughtLoading() { + return ( +
+ +
+ + +
+
+ ); +} +``` + +- [ ] **Step 5: Type-check** + +```bash +cd thoughts-frontend && npx tsc --noEmit +``` + +Expected: 0 errors. + +- [ ] **Step 6: Commit** + +```bash +git add thoughts-frontend/app/loading.tsx \ + thoughts-frontend/app/tags \ + thoughts-frontend/app/search/loading.tsx \ + thoughts-frontend/app/thoughts +git commit -m "feat(frontend): loading.tsx skeletons for feed, tags, search, and thread pages" +``` + +--- + +## Final Verification + +- [ ] `cargo test` — 148 tests pass +- [ ] `cd thoughts-frontend && npx tsc --noEmit` — 0 errors +- [ ] `grep -r "usernames" thoughts-frontend/components/top-friends.tsx` — 0 results (old prop gone) +- [ ] `grep -r "getFriends\|getTopFriends\|shouldDisplayTopFriends" thoughts-frontend/app/page.tsx` — 0 results +- [ ] `grep -r "Suspense" thoughts-frontend/app/page.tsx` — 3+ results (one per sidebar widget)