Must-Know Next.js App Router Patterns: Full Guide to Folder Naming Conventions

Next.js’s App Router uses a file-system-based routing pattern. In short, your folder structure directly determines your website’s URL structure. By using different bracket combinations, you can implement everything from basic pages to extremely complex dynamic logic.

Here is a detailed guide to folder naming conventions:

1. Basic Folders (No Brackets)

This is the most common form. Folder names map directly to the URL path.

• Rule: Every folder containing a page.js (or .tsx) file becomes a public route.
• Example:
  • app/about/page.js ➡️ /about
  • app/contact/page.js ➡️ /contact

2. Dynamic Routes (Square Brackets [])

Use square brackets when you don’t know the exact path name (e.g., post ID, username).

• Usage: [slug] or [id].
• Function: Acts as a placeholder, capturing the corresponding part of the URL as parameters passed to the component.
• Example:
  • Structure: app/blog/[id]/page.js
  • Matches: /blog/123 or /blog/hello-world
  • Accessing Params: Accessible via params.id within the page.

Extension: Catch-all Routes ([...folder])

• Usage: Add three dots inside the brackets, e.g., [...slug].
• Function: Matches all subsequent levels under that path.
• Example: app/shop/[...docs]/page.js will match /shop/clothes, /shop/clothes/tops/t-shirts, etc.

3. Route Groups (Parentheses ())

Sometimes you want to organize folder structure without having the folder name appear in the URL.

• Usage: (folderName).

• Function: Skips that level; it does not affect the URL. Often used to apply different layout.js (layouts) to different sections.

• Example:

  • Structure: app/(marketing)/about/page.js
  • URL: /about ((marketing) is ignored)

• Core Use Case: For large projects, you can put “Login/Signup” in an (auth) group using one layout, while putting “Dashboard” in a (dashboard) group using another.

4. Private Folders (Underscore _)

If you want to place utility functions, components, or test files in the app directory but don’t want them accidentally becoming routes.

• Usage: _folderName.
• Function: Excludes the folder and all its subfolders from the routing system.
• Example: app/_utils/format.js will not generate any routes.

Summary Table

Advanced Suggestions: Parallel & Intercepting Routes

Beyond basic conventions, Next.js also supports @folder (Parallel Routes) or (.)folder (Intercepting Routes). These are used for building complex UI like dashboards with multiple independent sections or modal dialogs that change the URL without navigating away from the current context.

By mastering these directory naming conventions, your Next.js project structure will remain clean, and your development experience will be much more efficient.