Next.js

Foundationv16.x

React framework for production — App Router, Server Components, and API routes power every Catalyst project.

Read this to understand how Catalyst uses Next.js patterns.
Useful when building pages, handling data, or configuring your app.

Why Next.js

Next.js is the React framework for production. It handles routing, rendering, data fetching, and deployment — so you can focus on building features instead of configuring infrastructure.

Catalyst uses Next.js 16 with the App Router, which provides Server Components by default, nested layouts, and a powerful routing system. AI agents understand Next.js well because of its extensive documentation and widespread adoption.

Key Concepts

The Next.js features Catalyst relies on:

App Router

File-based routing with layouts, loading states, and error boundaries built in.

Server Components

Render on the server by default. Less JavaScript shipped to the browser.

Server Actions

Mutate data with async functions that run on the server. No API routes needed.

Catalyst Patterns

How Catalyst organizes Next.js features:

Route Groups

Organize routes without affecting URLs

app/
├── (web)/      # Marketing pages → WebShell
├── (app)/      # Dashboard pages → AppShell
├── (docs)/     # Documentation → DocsShell
└── (auth)/     # Auth pages → minimal layout

Surface Layouts

Each route group has its own shell and styles

app/(app)/
├── layout.tsx    # Imports AppShell
├── app.css       # Surface-specific styles
└── _surface/     # Shell components
    └── app-shell.tsx

Server vs Client

Server by default, client when needed

// Server Component (default) — fetches data
export default async function Page() {
  const data = await fetchData()
  return <List items={data} />
}

// Client Component — needs interactivity
"use client"
export function Counter() {
  const [count, setCount] = useState(0)
  return <button onClick={() => setCount(c => c + 1)}>{count}</button>
}

Key Files

app/layout.tsx

Root layout — providers, fonts, global styles

app/globals.css

Global styles loaded on every page

next.config.ts

Next.js configuration

app/(group)/layout.tsx

Route group layout — surface-specific shell

app/api/**/route.ts

API routes for server endpoints

Common Tasks

Create a new page

  1. Add a folder with your route name in the appropriate route group
  2. Create page.tsx with a default export
  3. Server Component by default — add "use client" if you need interactivity

Fetch data

  1. Use async/await directly in Server Components
  2. Use Supabase client from lib/supabase/server
  3. Data is fetched at request time by default

Handle forms

  1. Create a Server Action in the same file or a separate actions.ts
  2. Use the action prop on <form> to submit
  3. Use useActionState for pending/error states

Tips

Server Components can't use hooks. If you need useState, useEffect, or event handlers, add "use client" at the top.

Colocate related files. Put components, actions, and utilities near the pages that use them.

Use loading.tsx for loading states. Next.js automatically shows this while the page loads.

Link prefetches by default. Be careful with Links to API routes — they may trigger on hover. Use prefetch={false} in dropdowns.

Learn More

Next.js DocumentationApp Router GuideData FetchingServer Actions

For AI Agents

Key rules:

  • New pages go in the appropriate route group (web, app, docs)
  • Use Server Components by default — only add "use client" when needed
  • Fetch data with await in Server Components, not useEffect
  • Use Server Actions for mutations, not API routes
  • Don't use Link for routes with side effects — use form POST instead
  • Add loading.tsx for loading states, error.tsx for error boundaries

Next Steps

Related foundation packages:

Tailwind CSS

Styling system used throughout Catalyst.

shadcn/ui

UI components built on Radix primitives.