Next.js src Folder
By default, Next.js expects your app (or pages) directory to sit directly at your project root, alongside package.json, next.config.js, and every other piece of project configuration. Plenty of teams would rather keep application code and configuration visually and structurally separate — a preference common enough across the broader JavaScript ecosystem that Next.js supports it as a first-class, officially recognized alternative: the src folder convention.
The Convention Itself
Moving to this layout is genuinely just moving a folder: relocate app to src/app (or pages to src/pages), and Next.js picks up the change automatically. There's no config flag to flip, no explicit opt-in — Next.js checks for src/app or src/pages and uses them if the root-level equivalents aren't present.
That "aren't present" clause matters: src/app or src/pages will be ignored if app or pages exist directly in the root directory instead. You can't have both simultaneously and expect Next.js to merge them — it's one location or the other, and root-level takes precedence if both happen to exist.
What Stays at the Root, Regardless
This is the detail most worth getting right the first time, since getting it wrong produces confusing, hard-to-diagnose failures rather than an obvious error. Several things are not meant to move into src alongside your routes:
/public— stays at the project root, full stop. It's not part of theapp/pagesrouter structure to begin with.- Config files —
package.json,next.config.js,tsconfig.json, and similar project-level configuration remain at the root, where every tool in your build pipeline expects to find them. .env.*files — also stay at the root.
What Else Typically Moves
If you're adopting src, you'll almost certainly want to bring other application-code folders along with it — /components, /lib, and anything else that's conceptually part of your application rather than project-level tooling configuration. The goal of the src convention is a clean separation between "code" and "config," so half-measures (routes in src, but shared components still sitting at the root) tend to undermine the entire reason for adopting the pattern in the first place.
Three Integration Points You Have to Update Yourself
Moving directories doesn't automatically update every tool that has an opinion about where your code lives. Three specific integrations need manual attention:
Proxy. If you're using proxy.ts/proxy.js, it must be placed inside the src folder alongside app — not left at the root. This is easy to miss since Proxy historically sat at the project root before the src convention became common, and an old habit of leaving it there will simply mean it's never invoked.
Tailwind CSS. Tailwind's content configuration (in tailwind.config.js) tells the framework which files to scan for class names — if that config still points at root-level paths after you've moved everything into src, Tailwind will scan an empty or wrong set of files and silently produce a stylesheet missing most of your actual utility classes. You need to add the /src prefix to your content globs explicitly.
TypeScript path aliases. If you're using import aliases like @/* (a very common Next.js convention), the paths object in tsconfig.json needs to be updated to include the src/ prefix in its mapped path — otherwise your alias will resolve to a location that no longer contains anything, since the actual files moved but the alias mapping didn't follow them.
Key Takeaways
| Rule | Detail |
|---|---|
| How to adopt | Move app or pages to src/app or src/pages — no config flag required |
| Precedence | Root-level app/pages wins if both root and src versions exist |
| Stays at root | /public, package.json, next.config.js, tsconfig.json, .env.* files |
| Also typically moves | /components, /lib, and other application-code folders |
| Proxy | Must live inside src, not at the root, once you adopt this convention |
| Tailwind CSS | Update the content config to include the /src prefix |
| TypeScript aliases | Update tsconfig.json's paths to include src/ in the mapped location |
The src folder convention itself is a one-line change — move a folder — but its real cost lives in the handful of tools that have their own opinions about file locations and won't automatically follow along. Budget for updating Proxy's location, your Tailwind content globs, and your TypeScript path aliases as part of the migration, not as an afterthought you discover only once something silently stops working.
