Next.js Best Practices Improvements

[engineering-props-to]

Summary

Audit of the codebase against Next.js 15+ best practices from vercel-labs/next-skills. Several improvement opportunities identified.

Areas for Improvement

1. Missing Error Boundaries (High Priority)

Issue: No error.tsx files in the app. Errors will bubble up to root or crash.

Fix: Add error.tsx to key route segments:

• apps/app/src/app/(dashboard)/error.tsx
• apps/app/src/app/(public)/error.tsx
• apps/app/src/app/global-error.tsx

'use client'
export default function Error({ error, reset }: { error: Error; reset: () => void }) {
  return (
    <div>
      <h2>Something went wrong!</h2>
      <button onClick={() => reset()}>Try again</button>
    </div>
  )
}

2. Missing Loading States (Medium Priority)

Issue: No loading.tsx files. Users see nothing during data fetching.

Fix: Add loading skeletons for dashboard pages:

• apps/app/src/app/(dashboard)/loading.tsx
• apps/app/src/app/(dashboard)/feedback/loading.tsx
• apps/app/src/app/(dashboard)/links/loading.tsx
• apps/app/src/app/(dashboard)/templates/loading.tsx

3. Missing Not Found Pages (Low Priority)

Issue: App uses notFound() but no custom not-found.tsx for better UX.

Fix: Add custom 404 pages:

• apps/app/src/app/(dashboard)/not-found.tsx
• apps/app/src/app/(public)/not-found.tsx

4. No Suspense Boundaries (Medium Priority)

Issue: Entire pages block on data. Could stream slower sections.

Opportunity: Dashboard page could show static shell immediately, stream in stats:

<Suspense fallback={<StatsSkeleton />}>
  <FeedbackStatsCards userId={userId} />
</Suspense>

5. No SEO Metadata (Medium Priority)

Issue: Pages missing generateMetadata or metadata exports.

Fix: Add metadata to public-facing pages:

• /[...slug]/page.tsx - dynamic titles for user profiles
• /templates/page.tsx - static metadata
• /links/page.tsx - static metadata

6. Caching Opportunities (Future - Next.js 16)

When upgrading to Next.js 16 with cacheComponents: true:

• Public templates list could use 'use cache'
• User profile pages (static parts) could be cached

What's Already Good ✅

• Async params/searchParams: Correctly typed as Promise<...> and awaited
• Server Components for reads: Data fetched directly, no unnecessary API layer
• Server Actions for mutations: Forms use actions correctly
• No navigation API in try-catch: redirect() and notFound() called correctly
• Proper RSC boundaries: Client components are minimal and correctly marked

Acceptance Criteria

• Add error.tsx to (dashboard) and (public) route groups
• Add global-error.tsx for root errors
• Add loading.tsx with skeletons for main dashboard pages
• Add not-found.tsx to route groups
• Add Suspense boundaries for dashboard stats
• Add generateMetadata to public pages

---

Reference: vercel-labs/next-skills (installed at .claude/skills/next-best-practices/)

[clack-agent]

Completed in PR #104. Added error.tsx, loading.tsx, global-error.tsx, not-found.tsx, Suspense boundaries, and metadata exports.

[clack-agent]

All acceptance criteria completed:

• ✅ error.tsx in (dashboard) and (public) route groups
• ✅ global-error.tsx for root errors
• ✅ loading.tsx with skeletons for dashboard pages
• ✅ not-found.tsx in route groups
• ✅ Suspense boundaries (PR feat: add Suspense boundaries for dashboard streaming #105, merged)
• ✅ generateMetadata in public pages

Refs: PRs #104, #105