Skip to content
    Getting StartedProject Structure

    Next.js Project Structure

    This page provides an overview of the file and folder structure of a Next.js project. It covers top-level files and folders, configuration files, and routing conventions within the app and pages directories.

    Top-level files

    next.config.jsConfiguration file for Next.js
    middleware.tsNext.js request middleware
    .envEnvironment variables
    .env.localLocal environment variables
    .env.productionProduction environment variables
    .env.developmentDevelopment environment variables
    .next-env.d.tsTypeScript declaration file for Next.js
    package.jsonProject dependencies and scripts
    .gitignoreGit files and folders to ignore
    tsconfig.jsonConfiguration file for TypeScript
    jsconfig.jsonConfiguration file for JavaScript
    .eslintrc.jsonConfiguration file for ESLint

    Top-level folders

    appApp Router
    pagesPages Router
    publicStatic assets to be served
    srcOptional application source folder

    app Routing Conventions

    Routing Files

    layout.js .jsx .tsxLayout
    page.js .jsx .tsxPage
    loading.js .jsx .tsxLoading UI
    not-found.js .jsx .tsxNot found UI
    error.js .jsx .tsxError UI
    global-error.js .jsx .tsxGlobal error UI
    route.js .tsAPI endpoint
    template.js .jsx .tsxRe-rendered layout
    default.js .jsx .tsxParallel route fallback page

    Nested Routes

    folderRoute segment
    folder/folderNested route segment

    Dynamic Routes

    [folder]Dynamic route segment
    [...folder]Catch-all segments
    [[...folder]]Optional catch-all segments

    Route Groups and Private Folders

    (folder)Group routes without affecting routing
    _folderOpt folder and all child segments out of routing

    Parallel and Intercepted Routes

    @folderNamed slot
    (.)folderIntercept same level
    (..)folderIntercept one level above
    (..)(..)folderIntercept two levels above
    (...)folderIntercept from root

    Metadata File Conventions

    App Icons

    favicon.icoFavicon file
    icon.png .svgApp Icon file
    icon.ico .jpg .jpeg .png .svgGenerated App Icon
    apple-icon.jpg .jpeg, .pngApple App Icon file
    apple-icon.js .ts .tsxGenerated Apple App Icon

    Open Graph and Twitter Images

    opengraph-image.jpg .jpeg .png .gifOpen Graph image file
    opengraph-image.js .ts .tsxGenerated Open Graph image
    twitter-image.jpg .jpeg .png .gifTwitter image file
    twitter-image.js .ts .tsxGenerated Twitter image


    sitemap.xmlSitemap file
    sitemap.js .tsGenerated Sitemap
    robots.txtRobots file
    robots.js .tsGenerated Robots file

    pages Routing Conventions

    Special Files

    _app.js .jsx .tsxCustom App
    _document.js .jsx .tsxCustom Document
    _error.js .jsx .tsxCustom Error Page
    404.js .jsx .tsx404 Error Page
    500.js .jsx .tsx500 Error Page


    Folder convention
    index.js .jsx .tsxHome page
    folder/index.js .jsx .tsxNested page
    File convention
    index.js .jsx .tsxHome page
    file.js .jsx .tsxNested page

    Dynamic Routes

    Folder convention
    [folder]/index.js .jsx .tsxDynamic route segment
    [...folder]/index.js .jsx .tsxCatch-all segments
    [[...folder]]/index.js .jsx .tsxOptional catch-all segments
    File convention
    [file].js .jsx .tsxDynamic route segment
    [...file].js .jsx .tsxCatch-all segments
    [[...file]].js .jsx .tsxOptional catch-all segments

    Was this helpful?