Skip to content
    App Router...RoutingProject Organization

    Project Organization and File Colocation

    Apart from routing folder and file conventions, Next.js is unopinionated about how your project files are organized and colocated.

    This page shares default behavior and features you can use to organize your project.

    Safe colocation by default

    In the app directory, nested folder hierarchy defines route structure.

    Each folder represents a route segment that is mapped to a corresponding segment in a URL path.

    However, even though route structure is defined through folders, a route is not publically accessible until a page.js or route.js file is added to a route segment.

    A diagram showing how a route is not publically accessible until a page.js or route.js file is added to a route segment.

    And, even when a route is made publically accessible, only the content returned by page.js or route.js is sent to the client.

    A diagram showing how page.js and route.js files make routes publically accessible.

    This means that project files can be safely colocated inside route segments in the app directory without accidentally being routable.

    A diagram showing colocated project files are not routable even when a segment contains a page.js or route.js file.

    Good to know:

    • This is different from the pages directory, where any file in pages is considered a route.
    • While you can colocate your project files in app you don't have to. If you prefer, you can keep them outside the app directory.

    Project organization features

    Next.js provides several features to help you organize your project.

    Private Folders

    Private folders can be created by prefixing a folder with an underscore: _folderName.

    This indicates the folder is a private implementation detail and should not be considered by the routing system, opting the folder and all its subfolders out of routing.

    An example folder structure using private folders

    Since files in the app directory can be safely colocated by default, Private folders are not required for colocation. However, they can be useful for:

    • Separating UI logic from routing logic.
    • Consistently organizing internal files across a project and the Next.js ecosystem.
    • Sorting and grouping files in code editors.
    • Avoiding potential naming conflicts with future Next.js file conventions.

    Good to know

    • While not a framework convention, you might also consider marking files outside private folders as "private" using the same underscore pattern.
    • You can create URL segments that start with an underscore by prefixing the folder name with %5F (the URL-encoded form of an underscore): %5FfolderName.
    • If you don't use private folders, it would be helpful to know Next.js special file conventions to prevent unexpected naming conflicts.

    Route Groups

    In the app directory, nested folders are normally mapped to URL paths. However, you can break out of this behavior using Route groups.

    Route groups can be created by wrapping a folder in parenthesis: (folderName).

    This indicates the folder is for organizational purposes and should not be included in the route's URL path.

    An example folder structure using route groups

    Route groups are useful for:

    src Directory

    Next.js supports storing application code (including app) inside a src directory. This separates application code from project configuration files which mostly live in the root of a project.

    An example folder structure with the `src` directory

    Module Path Aliases

    Next.js supports Module Path Aliases which make it easier to read and maintain imports across deeply nested project files.

    app/dashboard/settings/analytics/page.js
    // before
    import { Button } from '../../../components/button';
     
    // after
    import { Button } from '@/components/button';

    Project organization strategies

    There is no "right" or "wrong" way when it comes to organizing your own files and folders in Next.js a project.

    The following section lists a very high-level overview of common strategies. The simplest takeaway is to choose a strategy that works for you and your team and be consistent across the project.

    Note: In our examples below, we're using components and lib folders as generalized placeholders, their naming has no special framework significance and your projects might use other folders like ui, utils, hooks, styles, etc.

    Keep project files outside of app

    This strategy keeps all application code in shared folders in the root of your project and keeps the app directory purely for routing purposes.

    An example folder structure with project files outside of app

    Keep all project files inside folders in app

    This strategy keeps all application code in shared folders in the root of the app directory.

    An example folder structure with project files inside app

    Split project files by feature or route

    This strategy keeps globally shared application code in the root app directory and splits more specific application code into the route segments that use them.

    An example folder structure with project files split by feature or route

    Was this helpful?