When creating a Next.js project with create-next-app, the default folder structure puts the pages directory at the root of your project. The problem with this approach is that as you add additional directories such as components, utils, and config files, the root directory of your repo will become cluttered and difficult to navigate.
The simple solution is to create a src directory and move your pages directory inside of src to solve this problem.
In Next.js, the src directory is an optional way that you can use to organize your project's source code. By placing your source files inside a src folder, you can keep your project structure clean and maintainable.
Update: Next.js - would you like to use src/ directory with this project?
As of January 9, 2023, a Pull Request was merged from GitHub user ijjk that adds the following prompt when installing next.js via the create-next-app CLI that asks the user: "would you like to use the src/ directory with this project?" By responding yes, the pages directory (and app directory if used) will be placed inside of a src directory. This is recommended as it creates a better organizational structure for your app.
If you missed the prompt or are updating an existing Next.js project that has already been initialized, please follow the instructions below.
Here's how to use the src directory in a Next.js project:
- Create a
srcdirectory in your project's root folder:
mkdir src
- Move the
pagesfolder into thesrcdirectory:
mv pages src/
Your project structure should now look like this:
my-next-app/
├─ src/
│ ├─ pages/
│ │ ├─ api/
│ │ │ └─ hello.js
│ │ ├─ _app.js
│ │ └─ index.js
├─ .gitignore
├─ package.json
└─ README.md
Next.js will automatically detect the src/pages folder and use it for your application's pages.
- If you're using custom components, create a
componentsfolder inside thesrcdirectory to store your components:
mkdir src/components
- If you have a custom
_document.jsfile or want to add global CSS, create asrc/_document.jsfile or asrc/_app.jsfile and import your CSS there. Next.js will automatically detect these files. - You can also create other folders inside the
srcdirectory to organize your utility functions, hooks, or any other code you want to keep separate from thepagesandcomponentsfolders.
The final structure might look like this:
my-next-app/
├─ src/
│ ├─ components/
│ │ └─ MyComponent.js
│ ├─ pages/
│ │ ├─ api/
│ │ │ └─ hello.js
│ │ ├─ _app.js
│ │ ├─ _document.js
│ │ └─ index.js
│ └─ utils/
│ └─ myUtility.js
├─ public/
│ └─ favicon.ico
├─ .gitignore
├─ package.json
└─ README.md
By using the src directory in Next.js, you can maintain a clean project structure, making it easier to manage and navigate your codebase.
Can you use the src directory with the experimental Next.js 13 app directory?
Yes. In the same way that Next.js supports putting the pages directory inside of the src directory, you can also nest the app directory as src/app. You can even use both. Just remember that if you have a pages or app directory at the root of your project, then the respective directory under src will be ignored.