Next.js knowledge system (for app folder)

[reboottime]

Overview

A Quick Reference Guide for Experienced Nextjs Developers to warm up to making Nextjs using app directory architecture.

In Next.js App folder architecture, there are three essential parts as below:

• Routing System
  • File Naming Conventions
  • Next.js App Directory Folder Naming Conventions
  • Middleware
  • Making Restful API using Nextjs
• Data Flow
• Cache Mechanism

Other common considering aspects are

• Security Consideration
• Performance Implication

[reboottime]

Routing System

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

• restful API routing: the API routing system enables backend functionality directly within the Next.js application
• page routing: handles the frontend presentation layer

The Nextjs app directory implements a file-system based routing system where:

• Folders define route segments
• Special files (page.js, layout.js, template.js, error.js, loading.js) serve specific purposes in the routing lifecycle
• The hierarchy of folders directly creates URL paths
• Route groups ((folderName)) allow logical organization without affecting URL paths ( for frontend presentation layer)
• Parallel routes (@folderName) enable showing multiple pages simultaneously ( for frontend presentation layer)

[reboottime]

File Naming Conventions in Routing System

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

Naming Conventions 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

Learn from Examples

• template, page and layout

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

Next.js UI renders in nested layers, the final effect is like an layered box

• Folder structure

[reboottime]

Next.js Folder Naming Conventions in Routing System

Naming Conventions 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/

[reboottime]

middleware.[ts|js] in next.js routing system

What is it in Nextjs

Middleware in Next.js is a server-side function that intercepts and processes HTTP requests before they reach their destination route. It runs at the edge, enabling request modification, redirection, or early response generation without reaching the route handler or page. Middleware runs before the caching as the caching happens on routing time.

See diagram below to understand the which layer the middleware works in next.js app visually.

Use Cases

• Authentication & Authorization: see example about how to add authentication check in nextjs app using supabase
• Request/Response Manipulation: Setting custom headers, rewriting URLs, and redirecting requests to different destinations before they reach your page components
• Localization/Internationalization: Detecting user location by IP or headers and redirecting to language-specific versions of your site
• Logging & Analytics: Recording request information, tracking user behavior, and monitoring application performance Codeparrot.
• Security: Rate limiting to prevent DDoS attacks, bot detection, and implementing protective measures against malicious requests Codeparrot.

[reboottime]

Routing System: 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 });
}

[reboottime]

Data Flow in Next.js app

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

[reboottime]

Cache Mechanism in Nextjs app

Checklist

Mechanism	Where	What's Cached	When Caching Occurs	Duration	Revalidation
Router Cache	Browser	- RSC payload - Layouts - Loading states	- Navigation - Prefetching	- Session-based - 5 min for static routes - 30 sec for dynamic routes	- router.refresh() - cookies.set/delete - revalidateTag/Path - 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) - On-demand (revalidateTag/Path)
Full Route Cache	Server	- HTML - RSC payload - Static routes	- Build time - First request for dynamic routes	- Persistent until invalidated - 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

• Checklist for fetch option configuration

Option	Description	Caching Behavior
force-cache	Default behavior for fetch in Pages Router	Data is cached in the Data Cache
no-store	Opt out of caching	Data is fetched fresh on each request
revalidate: N	Time-based revalidation	Data is cached but refreshed after N seconds

• 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

[reboottime]

References for you to read