Buttercups logo
·8 min read

Next App Router Project Structure Best Practices Explained

In the fast-evolving world of web development, building scalable applications often means staying updated with best practices, especially when using cutting-edge frameworks like Next.js. One of the key features of Next.js is its robust App Router, which has significantly changed how developers architect their projects. Embracing the right Next App Router project structure best practices can elevate maintainability, scalability, and performance. In this guide, we’ll unpack these best practices, offering actionable insights to help you design a reliable Next.js application that stands the test of time.

The Significance of Project Structure in Next.js

A thoughtfully designed project structure isn't just about keeping files tidy; it’s the backbone of a healthy codebase. For Next.js applications, which leverage fast server-side rendering and React’s flexibility, adhering to proven project organization principles becomes essential. As the Next.js App Router supports enhanced routing, layouts, and server components, its ecosystem rewards clarity in architecture with improved efficiency and developer velocity.

Core Principles of Next App Router Project Structure Best Practices

Understanding the philosophy behind an effective project framework can help you implement and adapt best practices that fit your development workflows. Below are the guiding principles for structuring Next.js projects based on community feedback and industry trends:

  • Separation of concerns: Group files by feature and function, not by type
  • Scalability: Plan for growth by enabling modular, incremental development
  • Maintainability: Simplify navigation and updates for teams of any size
  • Performance: Minimize unnecessary re-renders or bloated imports
  • Collaboration: Align with standard patterns to reduce friction and onboarding time

With the release of Next.js 13 and its App Router, the project structure has evolved to optimize routing and layouts further. Let’s break down the Next App Router project structure best practices at the folder level.

Root Directory Organization

A typical Next.js project using the App Router includes several key folders at the root. Here’s an example:

/app
/components
/lib
/styles
/public
/middleware.ts
/next.config.js
/package.json

/app

The new heart of your Next.js project. This directory defines all routes, layouts, and page-level logic. It’s recommended to structure the /app directory by feature or domain, not pure type or route, making scaling and collaboration smoother.

/components

Reusable, shared UI elements—buttons, modals, headers—should live in this directory, separated from route-specific or domain-specific logic.

/lib

For utility functions, API calls, and external integrations, the /lib folder provides an organized home. This prevents your /app directory from becoming cluttered with non-UI code.

/public

The place for static files like images, favicons, and robots.txt, accessible at the base URL.

/styles

Global and modular styles, including CSS, SCSS, Tailwind, or PostCSS files, are centralized here for consistency.

Inside the /app Directory

The decision to organize by route as nested folders is at the core of App Router’s innovation. Each directory under /app represents a route segment and can contain a page.tsx, layout.tsx, and even specialized files like loading.tsx or error.tsx.

Example Structure:

/app
  /dashboard
    /analytics
      page.tsx
      loading.tsx
    layout.tsx
    page.tsx
  /profile
    page.tsx
  layout.tsx
  global-error.tsx
  globals.css

Layouts and Routing

Next.js 13 introduced support for hierarchical and parallel layouts, allowing you to define persistent UI (e.g., navigation, sidebars) at any folder level. Always keep layouts as close to the relevant pages as possible, which aligns with Next App Router project structure best practices for clarity and maintainability.

Collocating Assets and Tests

Locating assets, tests, and even utilities near their consumer components and pages greatly enhances discoverability and reduces context switching.

/components
  /Button
    Button.tsx
    Button.test.tsx
    Button.module.css
    index.ts

Modularization: Feature-Based Organization

A popular and effective approach for growing applications is to modularize by feature or domain rather than by technical type (e.g., grouping all components together). This pattern can be extended into your /app directory:

/app
  /users
    page.tsx
    utils.ts
    UserList.tsx
    UserDetails.tsx
    /hooks
    /components
  /settings
    page.tsx
    SettingsForm.tsx

By deploying this modular system, you ensure updates and new features can be developed in isolation—bolstering the scalability and robustness of your codebase.

Leveraging Server and Client Components

The App Router allows for both server and client components—leveraging React’s Server Components for improved performance. Best practices include:

  • Default to server components: For data fetching, heavy computation, or operations not needing browser APIs.
  • Isolate client components: Only use the 'use client'; directive when browser interactivity is required—buttons, forms, or local state management.
  • Segregate wisely: Group client and server stacks to clarify intent and optimize bundling.

File Naming and Directives

Clearly name server and client components. For example:

  • UserList.server.tsx
  • UserForm.client.tsx

By following these conventions, there’s less ambiguity for contributors and tools alike, aligning with modern Next App Router project structure best practices.

Handling Shared and Global State

Many applications require shared context or state management. Place global providers or state logic high up in the /app/layout.tsx, enabling them only where they’re truly needed to reduce re-renders and bundle size.

Example:

// app/layout.tsx
import AuthProvider from '../contexts/AuthProvider';
 
export default function RootLayout({ children }) {
  return (
    <AuthProvider>
      {children}
    </AuthProvider>
  );
}

This ensures stateful logic is accessible app-wide without polluting individual feature directories.

Best Practices for API Routes and Data Fetching

Even with the App Router’s shift towards server components and fetch in React, API routes remain essential for custom endpoints. Keep API routes outside the /app directory in /pages/api, adhering to Next.js guidelines.

For data fetching:

  • Utilize the server component’s ability to run initial data gathering before the client sees the UI.
  • When using SWR or React Query, limit their presence to client components where dynamic client-driven data fetching is necessary.

Naming Conventions and Consistency

Industry leaders like Vercel and top open-source Next.js repositories underscore that clear, semantic file and folder naming is critical:

  • Use lowercase and kebab-case or camelCase consistently for files and directories
  • Prefix test files with .test or .spec: ProfileCard.test.tsx
  • Clearly distinguish layouts (layout.tsx) and pages (page.tsx)
  • Modularize CSS by component: Menu.module.css
  • Export only from directories using index.ts for simplified imports

Testing and Reliability

Integrate testing into your project structure from the beginning. Co-locate test files with source files as shown, and use modern frameworks like Jest and Testing Library, which have strong Next.js support.

Adopting robust testing reflects adherence to Next App Router project structure best practices, dramatically reducing bugs and onboarding time for new engineers.

Real-World Examples & Industry Trends

More organizations are sharing their implementations publicly. Major open-source projects and Vercel’s own starters embody many of the above Next App Router project structure best practices. Notably:

  • Vercel’s official Next.js examples: These repositories showcase modularization by feature, clear separation of server/client, and structured use of /app.
  • SaaS boilerplates: Most modern SaaS boilerplates using Next.js follow a similar pattern, prioritizing /app modularity and asset colocation.

This evolution aligns with wider industry trends favoring monorepo approaches, modularity-first architecture, and developer experience as a competitive advantage.

Common Mistakes to Avoid

Even experienced teams trip up when adapting to the App Router’s paradigms. Here are some pitfalls:

  • Mixing server/client logic indiscriminately: Know when to split components for SSR and browser-side needs.
  • Over-nesting routes: While deep structures can be powerful, excessive nesting creates complexity. Group by logical domains.
  • Neglecting context: Don’t hoist state and providers higher than necessary—this affects performance.
  • Scattering project-specific utilities: Centralize global helpers in /lib, not across routes or components.

Keeping Up with the Next.js Ecosystem

Staying current with Next App Router project structure best practices means monitoring updates in the Next.js documentation and participating in the community. The framework is under active development, and new features or recommendations can influence project organization frequently.

  • Subscribe to Next.js releases
  • Read Vercel’s blog and changelogs
  • Explore GitHub discussions and RFCs
  • Connect with other developers in Next.js-specific forums and Discords

Wrapping Up: Continuous Improvement

Optimizing your Next React application starts with architecting it the right way. Embracing Next App Router project structure best practices is not a one-time affair—project structures should evolve as your app’s needs change and the ecosystem matures. By organizing by domain, differentiating server and client responsibilities, collocating resources, and testing thoroughly, you enable your team to ship features faster and more reliably.

Remember, the next generation of highly scalable, robust Next.js applications value structure as much as code quality. As Next.js advances, keep reevaluating your approach, solicit feedback, and invest in a structure that facilitates growth and innovation.

Still hungry for inspiration? Dive into open-source projects and the Next.js repository itself to witness how top teams structure their codebases today—and start refining your own Next App Router project structure best practices for tomorrow’s challenges.