nextjs-app-router

Use when next.js App Router with layouts, loading states, and streaming. Use when building modern Next.js 13+ applications.

Jump to install

Repository: TheBushidoCollective/han
Last source activity: February 11, 2026 at 17:47
Detected SKILL.md language: English
Stars: 189
Forks: 20

Install options

The review-first prompt is selected by default. You can switch to a direct command or download a local copy.

Review the source files

Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.

Back to search Back to installation

name	nextjs-app-router
user-invocable	false
description	Use when next.js App Router with layouts, loading states, and streaming. Use when building modern Next.js 13+ applications.
allowed-tools	["Bash","Read"]

Next.js App Router

Master the Next.js App Router for building modern, performant web applications with server components and advanced routing.

App Directory Structure

The app directory uses file-system based routing with special files:

app/
  layout.tsx       # Root layout (required)
  page.tsx         # Home page
  loading.tsx      # Loading UI
  error.tsx        # Error UI
  not-found.tsx    # 404 UI
  template.tsx     # Re-rendered layout
  about/
    page.tsx       # /about
  blog/
    layout.tsx     # Blog-specific layout
    page.tsx       # /blog
    loading.tsx    # Blog loading state
    [slug]/
      page.tsx     # /blog/[slug]
  dashboard/
    (auth)/        # Route group (doesn't affect URL)
      layout.tsx   # Layout for auth routes
      settings/
        page.tsx   # /dashboard/settings
      profile/
        page.tsx   # /dashboard/profile

// app/layout.tsx - Root layout (required)
export default function RootLayout({
  children
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>
        <header>
          <Navigation />
        </header>
        <main>{children}</main>
        <footer>
          <Footer />
        </footer>
      </body>
    </html>
  );
}

Layouts: Root, Nested, and Templates

// app/layout.tsx - Root Layout (wraps entire app)
import { Inter } from 'next/font/google';
import './globals.css';

const inter = Inter({ subsets: ['latin'] });

export const metadata = {
  title: 'My App',
  description: 'Built with Next.js App Router'
};

export default function RootLayout({
  children
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body className={inter.className}>
        <Providers>
          <Navigation />
          {children}
        </Providers>
      </body>
    </html>
  );
}

// app/dashboard/layout.tsx - Nested Layout
export default function DashboardLayout({
  children
}: {
  children: React.ReactNode
}) {
  return (
    <div className="dashboard">
      
        
      
      {children}
    
  );
}



   () {
  
   ;
}

Dynamic Routes and generateStaticParams

// app/blog/[slug]/page.tsx
interface PageProps {
  params: { slug: string };
  searchParams: { [key: string]: string | string[] | undefined };
}

export default async function BlogPost({ params }: PageProps) {
  const post = await getPost(params.slug);

  return (
    <article>
      <h1>{post.title}</h1>
      <p>{post.content}</p>
    </article>
  );
}

// Generate static paths at build time (SSG)
export async function generateStaticParams() {
  const posts = await getPosts();

  return posts.map((post) => ({
    slug: post.slug
  }));
}

// Generate metadata dynamically
export async  () {
   post =  (params.);

   {
    : post.,
    : post.,
    : {
      : post.,
      : post.,
      : [{ : post. }]
    }
  };
}


    () {
   product =  (params., params.);
   ;
}

   () {
   products =  ();

   products.( ({
    : product.,
    : product.
  }));
}


   () {
  
   path = params..();
   ;
}

Loading UI and Streaming

// app/blog/loading.tsx - Automatic loading UI
export default function Loading() {
  return (
    <div className="loading">
      <Skeleton />
      <Skeleton />
      <Skeleton />
    </div>
  );
}

// app/blog/page.tsx - Server component with streaming
import { Suspense } from 'react';

export default function BlogPage() {
  return (
    <div>
      <h1>Blog</h1>

      {/* Stream this component independently */}
      <Suspense fallback={<PostsSkeleton />}>
        <BlogPosts />
      </Suspense>

      {/* Stream this separately */}
      <Suspense fallback={<CommentsSkeleton />}>
        <RecentComments />
      </Suspense>
    </>
  );
}


  () {
   posts =  (); 

   (
    
  );
}

  () {
   comments =  ();

   (
    
  );
}

Error Boundaries and Error Handling

// app/blog/error.tsx - Error boundary
'use client'; // Error components must be Client Components

import { useEffect } from 'react';

export default function Error({
  error,
  reset
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  useEffect(() => {
    // Log error to error reporting service
    console.error('Blog error:', error);
  }, [error]);

  return (
    <div className="error-container">
      <h2>Something went wrong!</h2>
      <p>{error.message}</p>
      <button onClick={() => reset()}>Try again</button>
    </div>
  );
}

// app/global-error.tsx - Global error boundary
'use client';

export default function GlobalError({
  error,
  reset
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
   (
    
  );
}


   ;

   () {
   (
    
  );
}


 { notFound }  ;

    () {
   post =  (params.);

   (!post) {
    (); 
  }

   ;
}

Route Groups for Organization

// Route groups don't affect URL structure
app/
  (marketing)/        # Group routes without affecting URLs
    layout.tsx        # Marketing layout
    page.tsx          # / (homepage)
    about/
      page.tsx        # /about
    contact/
      page.tsx        # /contact
  (shop)/
    layout.tsx        # Shop layout
    products/
      page.tsx        # /products
    cart/
      page.tsx        # /cart
  (auth)/
    layout.tsx        # Auth layout
    login/
      page.tsx        # /login
    register/
      page.tsx        # /register

// app/(marketing)/layout.tsx
export default function MarketingLayout({
  children
}: {
  children: React.ReactNode
}) {
  return (
    <>
      <MarketingHeader />
      {children}
      <MarketingFooter />
    </>
  );
}

// app/(shop)/layout.tsx
export default function ShopLayout({
  children
}: {
  children: React.ReactNode
}) {
  return (
    <>
      <ShopHeader />
      <ShopNav />
      {children}
    </>
  );
}

Parallel Routes

// Use parallel routes to render multiple pages in the same layout
app/
  dashboard/
    @analytics/
      page.tsx
    @team/
      page.tsx
    @user/
      page.tsx
    layout.tsx
    page.tsx

// app/dashboard/layout.tsx
export default function DashboardLayout({
  children,
  analytics,
  team,
  user
}: {
  children: React.ReactNode;
  analytics: React.ReactNode;
  team: React.ReactNode;
  user: React.ReactNode;
}) {
  return (
    <div className="dashboard-grid">
      <div className="main">{children}</div>
      <div className="analytics">{analytics}</div>
      <div className="team">{team}</div>
      <div className="user">{user}</div>
    </div>
  );
}

// Conditional rendering with parallel routes
export default function Layout({ user, admin }: {
  user: React.ReactNode;
  admin: React.ReactNode;
}) {
   session =  ();

   session. ? admin : user;
}

Intercepting Routes

// Intercept routes to show modals or overlays
app/
  feed/
    page.tsx
    @modal/
      (.)photo/
        [id]/
          page.tsx
  photo/
    [id]/
      page.tsx

// app/feed/@modal/(.)photo/[id]/page.tsx
// Intercepts /photo/[id] when navigating from /feed
export default function PhotoModal({ params }: { params: { id: string } }) {
  return (
    <Modal>
      <Photo id={params.id} />
    </Modal>
  );
}

// app/photo/[id]/page.tsx
// Direct navigation to /photo/[id] shows full page
export default function PhotoPage({ params }: { params: { id: string } }) {
  return (
    <div className="photo-page">
      <Photo id={params.id} />
    </div>
  );
}

// Intercepting patterns:
// (.) matches same level
// (..) matches one level up
// (..)(..) matches two levels up
// (...) matches from root

Metadata API for SEO

// app/layout.tsx - Static metadata
import type { Metadata } from 'next';

export const metadata: Metadata = {
  title: {
    default: 'My App',
    template: '%s | My App' // Used by child pages
  },
  description: 'My awesome Next.js app',
  keywords: ['nextjs', 'react', 'typescript'],
  authors: [{ name: 'John Doe' }],
  openGraph: {
    title: 'My App',
    description: 'My awesome Next.js app',
    url: 'https://myapp.com',
    siteName: 'My App',
    images: [
      {
        url: 'https://myapp.com/og.png',
        width: 1200,
        height: 630
      }
    ],
    locale: 'en_US',
    type: 'website'
  },
  twitter: {
    card: 'summary_large_image',
    title: 'My App',
    description: 'My awesome Next.js app',
    : []
  },
  : {
    : ,
    : ,
    : {
      : ,
      : ,
      : -,
      : ,
      : -
    }
  }
};


   (): <> {
   post =  (params.);

   {
    : post.,
    : post.,
    : [{ : post. }],
    : {
      : post.,
      : post.,
      : [post.],
      : post.,
      : [post.]
    }
  };
}


   () {
   post = (params.);

   jsonLd = {
    : ,
    : ,
    : post.,
    : post.,
    : {
      : ,
      : post.
    }
  };

   (
    
  );
}

Route Handlers (API Routes)

// app/api/users/route.ts
import { NextRequest, NextResponse } from 'next/server';

// GET /api/users
export async function GET(request: NextRequest) {
  const searchParams = request.nextUrl.searchParams;
  const query = searchParams.get('query');

  const users = await getUsers(query);

  return NextResponse.json(users);
}

// POST /api/users
export async function POST(request: NextRequest) {
  const body = await request.json();

  const user = await createUser(body);

  return NextResponse.json(user, { status: 201 });
}

// app/api/users/[id]/route.ts
// GET /api/users/:id
export async function GET(
  : ,
  { params }: { params: { id:  } }
) {
   user =  (params.);

   (!user) {
     .({ :  }, { :  });
  }

   .(user);
}


   () {
   (params.);

    (, { :  });
}


   () {
   session =  (request);

   (!session) {
     .({ :  }, { :  });
  }

   data =  (session.);

   .(data);
}

Middleware

// middleware.ts (at root level)
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export function middleware(request: NextRequest) {
  // Check authentication
  const token = request.cookies.get('token');

  if (!token && request.nextUrl.pathname.startsWith('/dashboard')) {
    return NextResponse.redirect(new URL('/login', request.url));
  }

  // Add custom header
  const response = NextResponse.next();
  response.headers.set('x-custom-header', 'value');

  return response;
}

// Configure which routes use middleware
export const config = {
  matcher: [
    '/dashboard/:path*',
    '/api/:path*',
    '/((?!_next/static|_next/image|favicon.ico).*)'
  ]
};

// Advanced middleware with rewrites
  () {
  
   bucket = .() <  ?  : ;
  request..(, bucket);

   (bucket === ) {
     .( (, request.));
  }

   .();
}

When to Use This Skill

Use nextjs-app-router when you need to:

Build modern Next.js 13+ applications
Implement complex routing with layouts
Use server and client components effectively
Create loading and error boundaries
Optimize performance with streaming
Build SEO-friendly applications
Implement dynamic and static routes
Use parallel and intercepting routes
Build scalable Next.js applications
Implement advanced routing patterns
Create type-safe API routes
Optimize metadata for social sharing

Best Practices

Use server components by default - Only mark components with 'use client' when they need interactivity or browser APIs.
Implement proper loading states - Use loading.tsx files and Suspense boundaries for better UX during data fetching.
Create granular error boundaries - Place error.tsx files at appropriate levels to handle errors gracefully.
Leverage static generation - Use generateStaticParams for dynamic routes that can be pre-rendered at build time.
Organize with route groups - Use route groups to organize code without affecting URL structure.
Optimize metadata - Implement both static and dynamic metadata for better SEO and social sharing.
Stream content strategically - Use Suspense to stream independent UI sections as they load.
Keep client-side JavaScript minimal - Maximize server components to reduce bundle size and improve performance.
Use middleware wisely - Apply middleware for authentication, redirects, and request modifications.
Test routing behavior - Verify navigation, loading states, and error handling across different routes.

Common Pitfalls

Using client components unnecessarily - Marking components with 'use client' when they don't need browser APIs increases bundle size.
Not implementing loading states - Missing loading.tsx files lead to poor UX during navigation and data fetching.
Forgetting error boundaries - Without error.tsx files, errors crash the entire application instead of failing gracefully.
Mixing server and client code incorrectly - Importing server-only code in client components or vice versa causes errors.
Not optimizing for static generation - Missing generateStaticParams means pages render on-demand instead of at build time.
Overusing dynamic routes - Too many dynamic segments can make routing complex and hard to maintain.
Not handling route parameters properly - Failing to validate or sanitize route parameters can cause errors or security issues.
Ignoring SEO considerations - Missing or incomplete metadata hurts search engine rankings and social sharing.
Not testing edge cases - Skipping tests for 404s, errors, and loading states leads to poor user experience.
Misunderstanding file conventions - Naming files incorrectly (e.g., using Loading.tsx instead of loading.tsx) breaks conventions.

Resources