Next.js 13: App Router, Layouts, and Streaming

Introduction

Next.js 13's App Router represents the most significant architectural overhaul in the framework's history. Introduced as an opt-in beta in October 2022, the App Router replaces the pages/ directory with a new app/ directory that enables file-based layouts, nested routing, React Server Components by default, streaming with Suspense, and a simplified data fetching model. This isn't a minor version bump—it's a new way of building React applications that leverages React 18's concurrent features to their fullest extent.

The motivation behind the App Router is clear: the pages/ directory had accumulated years of conventions and workarounds (getServerSideProps, getStaticProps, _app.tsx, _document.tsx) that were increasingly misaligned with React's evolving direction. The App Router provides a clean slate where layouts compose naturally, data fetching happens at the component level, and streaming is the default rendering strategy. For teams starting new projects or planning migrations, understanding the App Router is essential for building modern Next.js applications.

Understanding the App Router: Core Concepts

The App Router introduces a file-system based routing convention where each folder in the app/ directory represents a route segment. Special file names within these folders define the UI for that segment:

page.tsx — The unique UI for a route, making it publicly accessible
layout.tsx — Shared UI that wraps child layouts and pages, preserving state across navigations
loading.tsx — Instant loading UI shown while route content streams in
error.tsx — Error boundary for catching runtime errors in that segment
not-found.tsx — UI for 404 pages within that segment
template.tsx — Similar to layout but re-renders on every navigation
default.tsx — Fallback UI for parallel routes

This convention eliminates the need for _app.tsx and _document.tsx. The root app/layout.tsx serves the same purpose as _app.tsx (wrapping all pages), while the root app/template.tsx can replace _document.tsx for custom HTML structure.

File-Based Route Resolution

The App Router resolves routes using folder names, with dynamic segments using [param] syntax and catch-all segments using [...param]:

app/
├── layout.tsx          → Root layout (wraps everything)
├── page.tsx            → / (homepage)
├── about/
│   └── page.tsx        → /about
├── blog/
│   ├── page.tsx        → /blog (listing)
│   └── [slug]/
│       └── page.tsx    → /blog/my-post (dynamic)
├── dashboard/
│   ├── layout.tsx      → Dashboard layout (sidebar, nav)
│   ├── page.tsx        → /dashboard
│   ├── settings/
│   │   └── page.tsx    → /dashboard/settings
│   └── [teamId]/
│       └── page.tsx    → /dashboard/team-123
└── [...catchAll]/
    └── page.tsx        → Catch-all route

Layouts: Persistent UI Across Navigations

Layouts are the cornerstone feature of the App Router. Unlike the pages/ directory where _app.tsx re-renders on every navigation, App Router layouts preserve their state across navigations. This means sidebar scroll position, form inputs in a layout-level search, and WebSocket connections survive route changes.

// app/dashboard/layout.tsx
import { Sidebar } from '@/components/sidebar'
import { Header } from '@/components/header'
 
export default function DashboardLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <div className="flex h-screen">
      <Sidebar />
      <div className="flex-1 flex flex-col overflow-hidden">
        <Header />
        <main className="flex-1 overflow-auto p-6">
          {children}
        </main>
      </div>
    </div>
  )
}

Nested Layout Composition

Layouts compose naturally through nesting. The root app/layout.tsx wraps all routes, and each subdirectory can define its own layout that wraps its children. This eliminates the need for layout patterns like getLayout in the pages/ directory.

// app/layout.tsx - Root layout
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body className="bg-gray-50 text-gray-900 antialiased">
        <AuthProvider>
          {children}
        </AuthProvider>
      </body>
    </html>
  )
}
 
// app/dashboard/layout.tsx - Dashboard layout
export default function DashboardLayout({ children }: { children: React.ReactNode }) {
  return (
    <div className="flex">
      <DashboardSidebar />
      <div className="flex-1">{children}</div>
    </div>
  )
}
 
// app/dashboard/analytics/layout.tsx - Analytics sub-layout
export default function AnalyticsLayout({ children }: { children: React.ReactNode }) {
  return (
    <div>
      <AnalyticsTabs />
      {children}
    </div>
  )
}

The composition means a page at /dashboard/analytics/overview is wrapped by all three layouts: Root → Dashboard → Analytics.

Streaming with Suspense

The App Router enables streaming by default. When a Server Component fetches data, Next.js doesn't wait for all data to resolve before sending HTML. Instead, it streams the page shell immediately and fills in Suspense boundaries as their content becomes available.

// app/dashboard/page.tsx
import { Suspense } from 'react'
import { RevenueChart } from '@/components/revenue-chart'
import { LatestInvoices } from '@/components/latest-invoices'
import { Cards } from '@/components/cards'
 
export default function DashboardPage() {
  return (
    <main>
      <h1>Dashboard</h1>
      <div className="grid grid-cols-3 gap-4">
        <Suspense fallback={<CardSkeleton />}>
          <Cards />
        </Suspense>
      </div>
      <div className="grid grid-cols-2 gap-4 mt-6">
        <Suspense fallback={<ChartSkeleton />}>
          <RevenueChart />
        </Suspense>
        <Suspense fallback={<InvoiceSkeleton />}>
          <LatestInvoices />
        </Suspense>
      </div>
    </main>
  )
}
 
// components/revenue-chart.tsx - Server Component
export async function RevenueChart() {
  const revenue = await fetch('https://api.example.com/revenue', {
    next: { revalidate: 3600 } // Revalidate every hour
  })
  const data = await revenue.json()
 
  return <Chart data={data} />
}

The browser receives the page structure (heading, skeleton cards, skeleton charts) in the first chunk. As each fetch resolves, Next.js streams the replacement HTML into the corresponding Suspense boundary using React's streaming protocol.

The loading.tsx Convention

For route-level loading states, the App Router provides loading.tsx as syntactic sugar for a Suspense boundary wrapping the page:

// app/dashboard/loading.tsx
export default function Loading() {
  return (
    <div className="animate-pulse">
      <div className="h-8 w-48 bg-gray-200 rounded mb-6" />
      <div className="grid grid-cols-3 gap-4">
        {[1, 2, 3].map(i => (
          <div key={i} className="h-32 bg-gray-200 rounded" />
        ))}
      </div>
    </div>
  )
}

This is equivalent to wrapping app/dashboard/page.tsx in a Suspense boundary with Loading as the fallback, but it's more ergonomic and keeps the loading state co-located with the route.

Data Fetching in the App Router

The App Router fundamentally changes data fetching by moving it from page-level functions (getServerSideProps, getStaticProps) to component-level async functions. Server Components can directly await data fetches, and Next.js extends the fetch API with caching and revalidation options.

// Fetch with different caching strategies
 
// 1. Cached (default) - equivalent to getStaticProps
const data = await fetch('https://api.example.com/data')
 
// 2. Cached with revalidation - equivalent to ISR
const data = await fetch('https://api.example.com/data', {
  next: { revalidate: 3600 }
})
 
// 3. Not cached - equivalent to getServerSideProps
const data = await fetch('https://api.example.com/data', {
  cache: 'no-store'
})
 
// 4. Tag-based revalidation
const data = await fetch('https://api.example.com/data', {
  next: { tags: ['data'] }
})
// Then revalidate via API route:
// revalidateTag('data')

Database Access in Server Components

Server Components can directly query databases without API routes:

import { db } from '@/lib/db'
 
export default async function UsersPage() {
  const users = await db.user.findMany({
    where: { active: true },
    include: { profile: true },
    orderBy: { createdAt: 'desc' },
    take: 50,
  })
 
  return (
    <ul>
      {users.map(user => (
        <li key={user.id}>
          {user.name} — {user.profile.bio}
        </li>
      ))}
    </ul>
  )
}

This pattern eliminates the API route layer entirely. The database query runs on the server, and only the rendered HTML reaches the client. There's no JSON.stringify → fetch → JSON.parse overhead—the data flows directly from database to React component.

Step-by-Step Implementation

Migrating from pages/ to app/ requires a systematic approach:

// Step 1: Create the app directory structure
// app/
// ├── layout.tsx
// ├── page.tsx
// └── globals.css
 
// Step 2: Root layout (replaces _app.tsx and _document.tsx)
// app/layout.tsx
import './globals.css'
import { Inter } from 'next/font/google'
 
const inter = Inter({ subsets: ['latin'] })
 
export const metadata = {
  title: 'My App',
  description: 'Built with App Router',
}
 
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" className={inter.className}>
      <body>{children}</body>
    </html>
  )
}
 
// Step 3: Convert pages to Server Components
// pages/users.tsx (old)
export async function getServerSideProps() {
  const users = await db.user.findMany()
  return { props: { users } }
}
export default function UsersPage({ users }) {
  return <UserList users={users} />
}
 
// app/users/page.tsx (new)
export default async function UsersPage() {
  const users = await db.user.findMany()
  return <UserList users={users} />
}
 
// Step 4: Add loading and error states
// app/users/loading.tsx
export default function Loading() {
  return <UserListSkeleton />
}
 
// app/users/error.tsx
'use client'
export default function Error({ error, reset }) {
  return (
    <div>
      <h2>Something went wrong</h2>
      <button onClick={reset}>Try again</button>
    </div>
  )
}

Real-World Use Cases

Use Case 1: SaaS Dashboard with Nested Layouts

A project management SaaS used the App Router to implement a three-level layout hierarchy: root (auth + theme), workspace (sidebar + nav bar), and project (project nav + tab bar). The workspace layout maintains a WebSocket connection for real-time notifications—because layouts persist across navigations, the connection survives when users move between project pages. This eliminated the previous pattern of storing WebSocket instances in a global context that survived page transitions through careful memo management.

Use Case 2: E-Commerce with Streaming Product Pages

An e-commerce platform migrated product pages to streaming SSR. The product page has four independent data dependencies: product details, inventory status, reviews, and recommendations. With the App Router, each section streams in independently. Product details arrive in 150ms, inventory in 200ms, reviews in 400ms, and recommendations in 800ms. Users see and can interact with product details 650ms faster than the previous approach that waited for all data.

Use Case 3: Documentation Site with Parallel Routes

A developer documentation site uses parallel routes to display the current page content alongside a table of contents and a search panel. The @toc and @search slots render independently, allowing the main content to stream in while the ToC loads from a cached source. The search panel uses a default.tsx fallback that shows nothing, but clicking the search icon triggers a modal that overlays the content.

Best Practices for Production

Use Server Components by default: Only add 'use client' when a component needs interactivity, browser APIs, or React hooks. The directive is a boundary—everything below it in the tree becomes a client component.
Co-locate data fetching with components: Instead of fetching all data at the top level and passing props down, let each component fetch what it needs. This enables independent streaming and caching.
Use loading.tsx for route-level loading: It's cleaner than wrapping every page in Suspense. Reserve explicit Suspense for sub-sections within a page.
Implement error.tsx at strategic levels: Place error boundaries where partial failures are acceptable. A failing recommendations section shouldn't crash the entire product page.
Leverage generateStaticParams: For dynamic routes with known slugs (blog posts, product pages), export this function to pre-render pages at build time.
Use revalidate over no-store: Default caching with revalidation is faster than no caching. Only use no-store for truly real-time data.
Test with streaming in mind: Verify that Suspense fallbacks provide meaningful loading states and that the page is usable before all data arrives.
Migrate incrementally: The App Router coexists with the pages/ directory. Migrate one route at a time, starting with less critical pages.

Common Pitfalls and Solutions

Pitfall	Impact	Solution
Adding 'use client' to layout	All child components become client components	Only add the directive to leaf components that need interactivity
Fetching data in layout without Suspense	Layout blocks rendering until data resolves	Wrap data-dependent layout sections in `Suspense` or use `loading.tsx`
Using `useState` in Server Components	Runtime error—Server Components have no hooks	Move state to a Client Component child
Nested layouts not preserving state	Unexpected re-renders during navigation	Ensure layout hierarchy is correct; use `template.tsx` only when re-rendering is desired
Forgetting `export default` in page.tsx	Route returns 404	Each `page.tsx` must have a default export
Client Component importing Server Component	Works but the Server Component renders on the server and is sent as serialized data	This is correct behavior—Server Components can be children of Client Components

Performance Optimization

// Parallel data fetching with Promise.all
export default async function DashboardPage() {
  // Fetch in parallel instead of sequentially
  const [revenue, users, products] = await Promise.all([
    fetchRevenue(),
    fetchUsers(),
    fetchProducts(),
  ])
 
  return (
    <div>
      <RevenueCards data={revenue} />
      <UserTable data={users} />
      <ProductGrid data={products} />
    </div>
  )
}
 
// Component-level caching with unstable_cache
import { unstable_cache } from 'next/cache'
 
const getCachedProducts = unstable_cache(
  async (category: string) => {
    return db.product.findMany({
      where: { category },
      orderBy: { createdAt: 'desc' },
    })
  },
  ['products-by-category'],
  { revalidate: 3600, tags: ['products'] }
)

Comparison with Alternatives

Feature	App Router	Pages Router	Remix	Gatsby
Layouts	Nested, persistent	`_app.tsx` (global)	Nested	Plugin-based
Data Fetching	Component-level	Page-level functions	Loader functions	GraphQL
Streaming SSR	Default	Not available	Built-in	Not available
React Server Components	Native	Not available	Partial	Not available
Error Boundaries	File-based	Custom implementation	Built-in	Plugin-based
Caching	fetch + tags	`getStaticProps`/ISR	HTTP cache	GraphQL cache

Advanced Patterns

Parallel Routes

Parallel routes allow rendering multiple pages in the same layout simultaneously using named slots:

// app/dashboard/layout.tsx
export default function Layout({
  children,
  analytics,
  notifications,
}: {
  children: React.ReactNode
  analytics: React.ReactNode
  notifications: React.ReactNode
}) {
  return (
    <div className="grid grid-cols-3 gap-4">
      <div className="col-span-2">{children}</div>
      <div>{analytics}</div>
      <div className="col-span-3">{notifications}</div>
    </div>
  )
}
 
// app/dashboard/@analytics/page.tsx
export default async function AnalyticsSlot() {
  const stats = await fetchAnalytics()
  return <AnalyticsPanel stats={stats} />
}

Testing Strategies

// Testing App Router components
import { render, screen } from '@testing-library/react'
import { UserList } from './user-list'
 
// Mock fetch for Server Components
jest.mock('next/headers', () => ({
  headers: () => new Headers(),
  cookies: () => ({ get: () => null }),
}))
 
describe('UserList', () => {
  it('renders user names', async () => {
    const users = [
      { id: '1', name: 'Alice' },
      { id: '2', name: 'Bob' },
    ]
 
    // Server Components are async—await the render
    render(await UserList({ users }))
 
    expect(screen.getByText('Alice')).toBeInTheDocument()
    expect(screen.getByText('Bob')).toBeInTheDocument()
  })
})

Future Outlook

The App Router is the foundation for Next.js's future direction. React Server Components, streaming, and the 'use client' boundary model are here to stay. The pages/ directory will continue to receive maintenance updates but won't gain new features. All major Next.js improvements—Partial Prerendering, Server Actions, and improved caching—are built on the App Router's architecture.

Conclusion

Next.js 13's App Router redefines how React applications are structured. File-based layouts eliminate global layout patterns and preserve state across navigations. Streaming with Suspense enables progressive page loading that improves perceived performance. Component-level data fetching replaces page-level functions, allowing more granular caching and parallel data resolution.

Key takeaways:

Layouts compose through nesting and persist state across navigations—use them for shared UI like sidebars and nav bars
loading.tsx provides route-level loading states as syntactic sugar for Suspense boundaries
Server Components can directly query databases and fetch APIs without an intermediate API route layer
The 'use client' directive creates a boundary—minimize its placement to keep client bundles small
Migrate incrementally by running App Router alongside the pages/ directory

For deeper exploration, consult the Next.js App Router documentation, React Server Components RFC, and Vercel's App Router migration guide.

Minh Vo

Slaying code & making it lit fr fr 🔥 tagline