How I structure my Next.js projects
A walkthrough of the folder structure, conventions, and decisions I've settled on after building multiple Next.js apps.
After building several Next.js projects — from a medical platform to a game trading app — I've settled on a structure that scales well and keeps things sane.
The folder layout
app/
(routes)/
layout.tsx
page.tsx
components/
ui/ ← shadcn or raw primitives
sections/ ← page-level sections (Hero, About, etc.)
shared/ ← reusable across sections
lib/
utils.ts
data.ts ← static data lives here, not in components
hooks/
public/Key decisions
Colocate data with the feature, not the component. Static arrays (nav items, project data, blog posts) live in `lib/data.ts` or `lib/blog-data.ts` — not inline inside the JSX. Components stay clean and readable.
Sections over pages. For a portfolio, everything lives on one page but is broken into section components under `components/sections/`. Each section owns its animation logic and refs.
`(routes)` group for future pages. Parenthesized route groups let you share a layout without it affecting the URL. Blog pages, project detail pages — they all share the root layout without being nested in the URL.
What I'd do differently
Early on I mixed data and markup inside the same file. By the time a project grows past two pages that becomes painful. Separating concerns early costs almost nothing and pays off fast.