Next.js directory organization best practices

Shivan M.

The Problem

When you are building an application using Next.js 13 and the app directory, you might wonder about the best practices for structuring your application components, routes, and functionality. Although there is no standard for doing this, there are a couple of guidelines that can help you have a more maintainable directory structure for your codebase.

The Solution

In Next.js 13, nested folder hierarchy defines the route structure for your application. Each folder in the app directory represents a route that is mapped to a corresponding URL segment.

Although each folder is mapped to a route, the route is not accessible until there is a page.js or route.js file in the folder.

This allows us to co-locate other project components in the /app directory safely.

Outside of route definitions, the main decision to make regarding folder structure pertains to project files (i.e. files that aren’t route definitions).

Directory Organization Strategies

There are three main organizational strategies for folder structure in Next.js that can serve as guidelines for your project.

Store All Project Files in Top-level Folders Inside app

Below is an example of a folder structure that you can use for your Next.js project where all project files are stored as top-level directories in the app directory.

In this example, there is a route for a dashboard page, which contains two nested routes called profile and billing. Additionally, the dashboard page returns a default page defined by app/dasboard/page.js. Lastly, the project has a components directory where we can safely co-locate components, as shown by the button.js component.

app/
├─ components/
│  ├─ button.js
├─ dashboard/
│  ├─ billing/
│  │  ├─ page.js
│  ├─ page.js
│  ├─ profile/
│  │  ├─ page.js
├─ page.js
├─ layout.js

Store Project Files Outside of the app Directory

A different approach would be to store all non-routing code outside of the app directory:

app/
├─ dashboard/
components/
├─ ...
lib/
├─ ...

Split Project Files by Route

In this scenario, globally shared code is stored at the root of the app directory, but context-specific application code is co-located within the directories of the route segments it applies to:

app/
├─ dashboard/
│  ├─ components/
│  ├─ _lib/
├─ components/
│  ├─ ...
├─ _lib/
│  ├─ ...

Directory Organizational Features

Next.js 13 offers several project organization features that can make maintaining and managing your codebase easier.

Private Folders

In Next.js 13 you can mark a folder as a private folder by prefixing the folder name with an underscore: _folderName. This opts the folder and all its sub-folders out of routing. This can be useful when you want to cleanly separate UI logic from routing logic, or when you are trying to consistently organize internal library code in your codebase.

Below is an example of a _lib directory that remains private even though it exists within the app directory:

app/
├─ components/
│  ├─ button.js
├─ dashboard/
│  ├─ billing/
│  │  ├─ page.js
│  ├─ page.js
│  ├─ profile/
│  │  ├─ page.js
├─ page.js
├─ layout.js
├─ _lib/
│  ├─ format-date.js

Route Groups

You can wrap the name of a folder in parentheses in the app directory: (folderName). This will indicate that the folder should not be included in the route’s URL path. This is useful for organizational purposes. The following example illustrates this pattern, where routes for the dashboard are organized under the dashboard route group:

app/
├─ (dashboard)/
│  ├─ components/
│  ├─ _lib/
│  ├─ profile/
│  ├─ billing/
├─ components/
│  ├─ ...
├─ _lib/
│  ├─ ...

Additional Reading

Next.js has extensive documentation about project organization, including the functional elements related to routing.

• Routing: Project Organisation