#what is the best folder structure in next.js 16

1 messages · Page 1 of 1 (latest)

weary fossil
#

what is the best folder structure in next.js 16

viral ingotBOT
#

Hi @weary fossil. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:

#

There isn’t a single “best” folder structure in Next.js 16; the framework is intentionally unopinionated and gives you several recommended patterns. [Project structure]

Below are the main options, all supported and considered good practice:

1. Core top‑level structure

At minimum, a typical Next.js 16 project will have: [Project structure]

app/        # App Router (recommended for new apps)
public/     # Static assets
src/        # Optional: can contain app/ instead of root-level app/

Plus config files in the root (not inside app or src): package.json, next.config.js, tsconfig.json, .env*, etc. [Project structure]

2. App Router basics (recommended)

A minimal, clean App Router setup:

app/
  layout.tsx   # Root layout (required)
  page.tsx     # Home page (/)
  blog/
    page.tsx   # /blog
    [slug]/
      page.tsx # /blog/[slug]
  api/
    route.ts   # Example API route
public/

3. Where to put components, lib, etc.

Next.js suggests a few common strategies; you choose one and stay consistent. [Examples]

Common patterns:

A. Keep app mostly for routing

# 
app/
  layout.tsx
  page.tsx
components/
lib/
utils/
styles/

B. Put shared folders inside app

app/
  layout.tsx
  page.tsx
  components/
  lib/
  styles/

C. Split by feature/route

app/
  layout.tsx
  page.tsx
  blog/
    layout.tsx
    page.tsx
    _components/
    _lib/
  account/
    layout.tsx
    page.tsx
    _components/

Files in app are safe to colocate; they don’t become routes unless they use special names like page.tsx or route.ts. [Organizing your project]

4. Route groups and private folders

To organize without changing URLs: [Route groups]

app/
  (marketing)/
    layout.tsx
    page.tsx      # /
    about/
      page.tsx    # /about
  (shop)/
    layout.tsx
    cart/
      page.tsx    # /cart

To mark internal folders and keep them out of routing:

app/
  blog/
    page.tsx
    _components/
      PostCard.tsx
    _lib/
      data.ts

_folder is treated as private and ignored by the router. [Route groups & private]

5. Optional src folder

If you prefer to separate app code from config:

src/
  app/
    layout.tsx
    page.tsx
    ...
public/
package.json
next.config.js
tsconfig.json

src/app or src/pages is used instead of root-level app/pages. [App src folder]

Summary: Next.js 16 doesn’t enforce a single “best” structure. A widely used, future‑proof choice is:

src/
  app/
    layout.tsx
    page.tsx
    (marketing)/
    (app)/
    ...
  components/
  lib/
public/
config files in root
#

and then consistently use route groups, private folders, and colocation as your project grows.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@weary fossil Kapa.ai is still learning and improving, please let me know how I did by reacting below.

weary fossil
#

@viral ingot what is /lib for, and where should my actions files go (crud functions) for client and server, using react query

viral ingotBOT
#

Let me check the knowledge base for you again. Give me one moment! :books:

#

The knowledge sources don’t define a strict rule for a /lib folder or exactly where to put “actions” files for CRUD with React Query, but they do describe common patterns and how lib is typically used.

What /lib is for

Next.js treats lib as a convention, not a special folder. It’s commonly used for:

  • Shared utilities and helpers
  • Data access helpers (e.g. DB / API wrappers)
  • Code reused by pages, components, and API routes

Examples:

So /lib (or /data) is typically your internal library / data access layer, not directly tied to routing.

Where to put CRUD “actions” (server)

For server-side CRUD functions (e.g. DB or external API calls), the docs recommend:

  • A Data Access Layer that:
    • Runs only on the server
    • Performs authorization checks
    • Returns safe DTOs [Data access layer]

This DAL can live in a folder like:

lib/
  db/
  api/
data/
#

or similar; the exact name is up to you. Next.js is unopinionated about the folder name, only that this code is server-only and not exposed directly to the client. [Organizing your project]

For Server Actions (Next.js App Router):

  • You can define them in a shared file like app/lib/actions.ts or /lib/actions.ts with "use server" on the function or file. [Updating data]
  • Templates also use /lib/actions.ts for server actions such as tracking purchases. [Optimizely template]

Example from the docs:

// app/lib/actions.ts
export async function createPost(formData: FormData) {
  'use server'
  // Update data
  // Revalidate cache
}

[Updating data]

Where to put client-side “actions” (React Query)

The docs don’t mention React Query specifically, so this part is not explicitly covered. They do, however, show that:

  • Client components can import server actions from a "use server" file and call them via formAction or action props. [Updating data]
// app/actions.ts
'use server'
export async function createPost() {}

// app/ui/button.tsx
'use client'
import { createPost } from '@/app/actions'

export function Button() {
  return <button formAction={createPost}>Create</button>
}

[Updating data]

For React Query, a common pattern (not explicitly documented, but consistent with the examples) is:

#
  • Server-side CRUD: in /lib or /data (DAL) and/or server action files.
  • Client-side hooks that wrap React Query: in a hooks/ or lib/ subfolder (e.g. lib/queries/, hooks/), similar to how templates separate lib, queries, and utils. [WordPress example; Redis session template]

Practical recommendation (aligned with docs)

A structure consistent with the docs and templates could be:

src/
  app/
    ...routes...
  lib/
    dal/              # server-only data access (DB/API)
    actions.ts        # "use server" Server Actions that call DAL
  hooks/
    usePosts.ts       # React Query hooks calling API routes or actions
  • /lib (or /data) for server-only data access + server actions.
  • hooks/ (or lib/queries/) for client-side React Query hooks.

This matches how the official docs and templates use lib and a DAL, while keeping client and server concerns separated.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@weary fossil Kapa.ai is still learning and improving, please let me know how I did by reacting below.