d

[brewblue]

Routing System

Nextjs is a fullstack app solution. There are two categories of routing

• Restful API routing
• Page routing

Next.js App Directory File Naming Patterns

Essential file naming conventions in Next.js 14+ app directory.

checklist

File	Description
page.tsx	Default React Server Component for route segments. Defines unique UI and data fetching. Automatically accessible at route's URL.
layout.tsx	Shared UI wrapper for route segments. Persists across route changes. Receives children prop for nested components.
loading.tsx	Instant loading state using React Suspense. Automatically wraps route segments. Shows while page components are streaming.
error.tsx	React Error Boundary wrapper. Catches runtime errors in nested routes. Isolates errors to affected segments.
not-found.tsx	Custom 404 error handling. Invoked by notFound() function. Handles non-existent routes and intentional not-found states.
route.tsx	Route Handlers for API functionality. Supports HTTP methods (GET, POST, etc.). Direct access to Next.js's Edge Runtime.
middleware.ts	Global route and request interception. JWT validation, authentication, and rewriting. Executes before matching routes.
route.ts	API Route Handler defining endpoints with HTTP methods (GET, POST, etc.). Creates API routes at the segment's URL path. Must be placed in app directory.
default.tsx	app/@modal/default.tsx , Fallback UI when parallel route isn't active
template.tsx	app/blog/template.tsx, New instance per navigation, useful for animations

Deep dive in.

• template, page and layout

app/
  ├─ layout.tsx (root)
  └─ products/
      ├─ layout.tsx 
      ├─ template.tsx
      ├─ page.tsx
      └─ [id]/
          └─ page.tsx

So these UI layers wrapped like onion, root layout waps the products page layout, the products page layout wraps the template, then template wraps the further page.tsx.

The final effect is like an onion

• Folder structure

[brewblue]

Next.js App Directory Folder Naming Patterns

Checklist

Pattern	Example	Description
folder/	app/dashboard/	Creates /dashboard route
[param]	app/blog/[slug]/	Dynamic routes like /blog/post-1, /blog/post-2
[...slug]	app/docs/[...slug]/	Matches /docs/a, /docs/a/b, /docs/a/b/c
[[...slug]]	app/[[...filter]]/	Optional catch-all: matches /, /products, /products/clothes
(group)	app/(shop)/checkout/	Groups /checkout without adding "shop" to URL
_folder	app/_lib/utils.ts	Private code, components, or utilities - not routable
@modal	app/@modal/login/	Parallel UI: shows login modal while keeping current page
api/	app/api/users/route.ts	API routes with full Edge Runtime support

Strategic Benefits Using Grouping Folder

Route grouping with (folder) serves three main purposes:

1. Organization: Group related routes (e.g., all auth pages) without URL impact

app/
├── (auth)/
│   ├── login/
│   ├── register/
│   └── forgot-password/

2. Layout isolation: Different layouts for different sections

app/
├── (shop)/
│   ├── layout.tsx  # E-commerce layout
│   └── products/
└── (marketing)/
    ├── layout.tsx  # Marketing site layout
    └── about/

[brewblue]

Next.js API Routes - Core Concepts And My Practices

Basic Route Handler

// app/api/route.ts
export async function GET(request: Request) {
  return Response.json({ data: 'Hello' })
}

export async function POST(request: Request) {
  const data = await request.json()
  return Response.json({ received: data })
}

Key Features

• HTTP Methods: GET, POST, PUT, PATCH, DELETE
• Response Types: JSON, Streams, Files, Redirects
• Runtime: export const runtime = 'edge' | 'nodejs'
• Dynamic Routes: [id] or [...slug]

  • Example

    

Error Handling

• Fundamental Logic

return Response.json(
  { error: 'Not found' },
  { status: 404 }
)

• How to handle it professionally

import { NextResponse } from 'next/server';

export default class APIError extends Error {
  public readonly name: string = 'APIError';

  constructor(
    message: string,
    public readonly statusCode: number = 500,
    public readonly details?: Record<string, unknown>
  ) {
    super(message);

    Object.setPrototypeOf(this, APIError.prototype);
    Error.captureStackTrace(this, APIError);
  }

  toJSON() {
    return {
      name: this.name,
      message: this.message,
      statusCode: this.statusCode,
      details: this.details,
      stack: this.stack
    };
  }
}

export function createErrorResponse(error: unknown) {
  if (error instanceof APIError) {
    return NextResponse.json(
      { error: error.message, details: error.details },
      { status: error.statusCode }
    );
  }

  const msg = error instanceof Error
    ? error.message
    : 'Internal server error';

  return NextResponse.json({ error: msg }, { status: 500 });
}

[brewblue]

Data Flow in Next.js Part I: Data Flow

Nextjs Application Data Flow Diagram

High Level Diagram

• How Client and Server Side state work together

• View From User Perspective using Layer Analysis

Explain The Diagram Using Code

• Sample app folder structure

app/
├── layout.tsx                 # Root layout
├── page.tsx                   # Home page
└── todos/
    ├── page.tsx              # Todo list page (Server Component)
    ├── loading.tsx           # Loading UI
    ├── error.tsx             # Error boundary
    ├── actions.ts            # Server actions
    ├── types.ts              # Type definitions
    ├── lib/
    │   └── db.ts            # Database utilities
    └── _components/
        ├── TodoList.tsx      # Client component
        ├── TodoItem.tsx      # Client component
        ├── AddTodoForm.tsx   # Client component
        └── ui/               # Shared UI components
            ├── Button.tsx
            └── Input.tsx

prisma/
├── schema.prisma            # Database schema
└── migrations/              # Database migrations

public/
└── assets/                 # Static assets

.env                        # Environment variables
.env.local                 # Local environment variables

• sample app source code

// app/todos/page.tsx
// Server Component
async function TodoPage() {
  const todos = await prisma.todo.findMany();
  
  return (
    <div>
      <TodoList initialTodos={todos} />
      <AddTodoForm />
    </div>
  );
}

// app/todos/actions.ts
// Server Actions
export async function addTodo(formData: FormData) {
  'use server'
  
  const title = formData.get('title');
  const newTodo = await prisma.todo.create({
    data: { title, completed: false }
  });
  
  revalidatePath('/todos');
  return newTodo;
}

export async function toggleTodo(id: string) {
  'use server'
  
  const todo = await prisma.todo.findUnique({ where: { id } });
  await prisma.todo.update({
    where: { id },
    data: { completed: !todo?.completed }
  });
  
  revalidatePath('/todos');
}

// app/todos/components/TodoList.tsx
// Client Component with State Management
'use client'
import { useOptimistic, useState } from 'react';

interface Todo {
  id: string;
  title: string;
  completed: boolean;
}

export function TodoList({ initialTodos }: { initialTodos: Todo[] }) {
  // Local React State
  const [todos, setTodos] = useState(initialTodos);
  
  // Optimistic Updates
  const [optimisticTodos, addOptimisticTodo] = useOptimistic(
    todos,
    (state, newTodo: Todo) => [...state, newTodo]
  );

  return (
    <ul>
      {optimisticTodos.map(todo => (
        <TodoItem 
          key={todo.id}
          todo={todo}
          onToggle={toggleTodo}
        />
      ))}
    </ul>
  );
}

// app/todos/components/AddTodoForm.tsx
'use client'
import { useTransition } from 'react';
import { addTodo } from '../actions';

export function AddTodoForm() {
  const [pending, startTransition] = useTransition();
  
  async function action(formData: FormData) {
    startTransition(async () => {
      // Server Action Call
      const newTodo = await addTodo(formData);
      // Route Cache gets revalidated
      // Server Components re-render
      // Props flow down to Client Components
    });
  }
  
  return (
    <form action={action}>
      <input name="title" required />
      <button type="submit" disabled={pending}>
        Add Todo
      </button>
    </form>
  );
}

// Data Flow Sequence:
// 1. User submits form → Client Component calls Server Action
// 2. Server Action mutates database
// 3. Server Action triggers revalidation
// 4. Route Cache invalidates
// 5. Server Components re-fetch data
// 6. New props flow to Client Components
// 7. Client Components re-render with new data
// 8. Optimistic UI updates show immediate feedback

[brewblue]

Data Flow in Next.js Part I: Data Flow

Nextjs Application Data Flow Diagram

High Level Diagram

• How Client and Server Side state work together

• View From User Perspective using Layer Analysis

Explain The Diagram Using Code

• Sample app folder structure

app/
├── layout.tsx                 # Root layout
├── page.tsx                   # Home page
└── todos/
    ├── page.tsx              # Todo list page (Server Component)
    ├── loading.tsx           # Loading UI
    ├── error.tsx             # Error boundary
    ├── actions.ts            # Server actions
    ├── types.ts              # Type definitions
    ├── lib/
    │   └── db.ts            # Database utilities
    └── _components/
        ├── TodoList.tsx      # Client component
        ├── TodoItem.tsx      # Client component
        ├── AddTodoForm.tsx   # Client component
        └── ui/               # Shared UI components
            ├── Button.tsx
            └── Input.tsx

prisma/
├── schema.prisma            # Database schema
└── migrations/              # Database migrations

public/
└── assets/                 # Static assets

.env                        # Environment variables
.env.local                 # Local environment variables

• sample app source code

// app/todos/page.tsx
// Server Component
async function TodoPage() {
  const todos = await prisma.todo.findMany();
  
  return (
    <div>
      <TodoList initialTodos={todos} />
      <AddTodoForm />
    </div>
  );
}

// app/todos/actions.ts
// Server Actions
export async function addTodo(formData: FormData) {
  'use server'
  
  const title = formData.get('title');
  const newTodo = await prisma.todo.create({
    data: { title, completed: false }
  });
  
  revalidatePath('/todos');
  return newTodo;
}

export async function toggleTodo(id: string) {
  'use server'
  
  const todo = await prisma.todo.findUnique({ where: { id } });
  await prisma.todo.update({
    where: { id },
    data: { completed: !todo?.completed }
  });
  
  revalidatePath('/todos');
}

// app/todos/components/TodoList.tsx
// Client Component with State Management
'use client'
import { useOptimistic, useState } from 'react';

interface Todo {
  id: string;
  title: string;
  completed: boolean;
}

export function TodoList({ initialTodos }: { initialTodos: Todo[] }) {
  // Local React State
  const [todos, setTodos] = useState(initialTodos);
  
  // Optimistic Updates
  const [optimisticTodos, addOptimisticTodo] = useOptimistic(
    todos,
    (state, newTodo: Todo) => [...state, newTodo]
  );

  return (
    <ul>
      {optimisticTodos.map(todo => (
        <TodoItem 
          key={todo.id}
          todo={todo}
          onToggle={toggleTodo}
        />
      ))}
    </ul>
  );
}

// app/todos/components/AddTodoForm.tsx
'use client'
import { useTransition } from 'react';
import { addTodo } from '../actions';

export function AddTodoForm() {
  const [pending, startTransition] = useTransition();
  
  async function action(formData: FormData) {
    startTransition(async () => {
      // Server Action Call
      const newTodo = await addTodo(formData);
      // Route Cache gets revalidated
      // Server Components re-render
      // Props flow down to Client Components
    });
  }
  
  return (
    <form action={action}>
      <input name="title" required />
      <button type="submit" disabled={pending}>
        Add Todo
      </button>
    </form>
  );
}

// Data Flow Sequence:
// 1. User submits form → Client Component calls Server Action
// 2. Server Action mutates database
// 3. Server Action triggers revalidation
// 4. Route Cache invalidates
// 5. Server Components re-fetch data
// 6. New props flow to Client Components
// 7. Client Components re-render with new data
// 8. Optimistic UI updates show immediate feedback

[brewblue]

Data Flow in Next.js App Part II: Cache Mechanism

Cache Mechanism in Next.js

Mechanism	Where	What's Cached	When Caching Occurs	Duration	Revalidation
Router Cache	Browser	- RSC payload - Layouts - Loading states	- Navigation - Prefetching	- Session-based - 5 min static routes - Pages not cached by default	- router.refresh() - cookies.set/delete (Server Actions) - revalidateTag/Path (Server Actions) - Auto-invalidation
Data Cache	Server	- Fetch results - API responses - DB query results	- First request - After revalidation	- Persistent across deployments - Until revalidated	- Time-based (next.revalidate) - revalidateTag/Path (Server Actions)
Route Cache	Server	- HTML - RSC payload - Static routes	- Build time - First request for dynamic	- Until deployment - Until invalidation - Bypassed by dynamic routes	- New deployment - Data Cache revalidation - Dynamic rendering opts out

Jump Into Details

• for page segments specifically (like orders/[id]/page.tsx):

  1. Not cached by default in Router Cache
  2. Only reused during browser back/forward navigation
  3. Exception: Will be cached for 5 minutes if explicitly using:
     • prefetch={true} on Link
     • router.prefetch()

Layouts and loading states are still cached, just not the page components themselves. This changed in Next.js 15 to optimize memory usage.

(Server Side) Data Cache Control

• High Level Diagram

• Sample Code

// 1. Route Cache Control
export default async function Page() {
  // Force cache
  const data1 = await fetch(url, { cache: 'force-cache' });
  
  // No cache
  const data2 = await fetch(url, { cache: 'no-store' });
  
  // Time-based revalidation
  const data3 = await fetch(url, { next: { revalidate: 3600 } });
}

// 2. Data Cache Control
async function updateData() {
  'use server'
  await db.update();
  
  // Revalidate specific path
  revalidatePath('/items');
  
  // Revalidate by tag
  revalidateTag('items');
}

// 3. Full Route Cache Control
export const dynamic = 'force-dynamic'  // Disable caching
// or
export const revalidate = 3600  // Time-based revalidation