Next Colocation Template

File Structure and Colocation Strategy

This folder structure follows a colocation-first approach consistent with the Next.js App Router. Related components, layouts, and logic are placed together inside their route segments to improve maintainability and clarity as your app grows.

For example, the auth/login route includes its own _components/ folder containing UI elements like login-form.tsx, which are specific to the login page. Since login-form.tsx handles interactive behavior such as state and events, it's marked with "use client", as recommended by Next.js for client-side logic at the leaf level. If a file doesn’t explicitly use "use client", it runs as a Server Component by default.

Shared components that are reused across multiple routes within the auth/ segment, such as GitHub sign-in buttons are placed in the parent route's _components/ folder (e.g., auth/_components/). This keeps reusable logic colocated at the appropriate scope, without polluting global folders.

Using colocated folders also improves developer experience in code editors, as you can work within a single folder for an entire route, reducing context switching and improving flow while building features.

You can view the file tree below to get a better understanding of how this setup is structured in practice.

Want to try this structure in your own project? Clone the repo and use it as a starting point. It comes with a starter dashboard page, as well as auth pages including login and register, and is built using TypeScript and Shadcn UI, so you can start prototyping with real components right away.

Using Private Folders (_components/)

Prefixing folders with an underscore, like _components, opts them out of the routing system. This follows the Next.js private folders convention, helping keep routing logic separate from UI components.

Although colocation is safe by default within the app/ directory, using private folders improves organization, editor navigation, and prevents conflicts with future Next.js features.

Tip: This pattern promotes clarity and consistency, especially in larger projects where structure matters.

💡 While optional, using the src/ directory is a common convention that keeps your project root clean and separates application logic from configuration files.

Top-Level Routing Groups

Route groups are optional folders that help organize routes without affecting the URL path. For example, this structure uses groups like (main) and (external) to separate core app logic from public-facing pages.

• (main), Core application logic.
• (external), Public-facing routes such as marketing pages or standalone forms.

These groups help keep your project organized while preserving clean URL structures.

Rationale

Colocating route-specific logic avoids cluttering a global components/ folder and reduces cognitive overhead. Shared utilities like hooks/, lib/, or constants/ remain at the top level inside src/, keeping them decoupled from specific routes.

This structure integrates well with nested layouts, enabling shared UI elements like sidebars or headers within each route group.

If needed, route-specific logic like schema validation (e.g., using Zod) or input types can also live alongside the route in a colocated schema.ts file. When such logic is reused across multiple routes, it’s better placed in a shared top-level folder like lib/ to maintain separation and avoid duplication.

It also streamlines onboarding and enforces consistent conventions across teams.

When to Use This Pattern

This structure is especially useful for medium to large-scale applications with dozens of routes, teams working in parallel, or projects where clear boundaries between server and client components are important. It supports better modularity, faster onboarding, and improved discoverability of related logic.

Traditional patterns like Atomic Design or feature folders can become difficult to scale, leading to bloated components/ trees and tight coupling. This approach keeps logic close to where it’s used while supporting global reuse where appropriate.