Docs: How to Shift from Page.js and layout.js in app directory to index.js and _app.js in pages directory

[Faizan711]

What is the improvement or update you wish to see?

Update in Docs for setting up of NextJS project and what folders to create at starting stages of your project and what pages I can create and what I can remove. @shuding

Is there any context that might help us understand?

Recently I started building a Website using NextJS, but after setting up the project, I was provided with page.js and layout.js. There are instructions in the docs that I can also use _app.js and index.js inside Pages folder but it is not clear how. I created Index.js inside Pages folder, but that created an error showing "you can either use page.js or index.js", this should be mentioned in the docs and also after going through different projects of developers in Github, I came to understand I can remove layout.js and use only _app.js inside Pages folder, this should also be clearly mentioned in the docs. This will help a lot of new developers like me who are using NextJS for the first time.

Does the docs page already exist? Please link to it.

No response

_DX-1714

[shuding]

Thanks for the question! I think indeed we can make it better in the docs, but I'll also quickly explain it a bit here -

When creating a new Next.js project, you have these 2 folders to put your code:

• /pages/
• /app/

They're two "modes". Inside "pages", every file will map to a route, with some special files such as "_app". E.g. /pages/index.js → http://localhost:3000/, /pages/foo/bar.js → http://localhost:3000/foo/bar and so on.

And the "_app" file inside "pages" will be the global layout component that wraps everything inside "pages". So if you access http://localhost:3000/foo/bar it will render the content of _app.js AND /pages/foo/bar.js.

Then, inside the "app" folder, only "page.js" will be recognized as a page. For example /app/foo/page.js will be rendered on http://localhost:3000/foo. And then there's "layout.js" that wraps everything below that directory, similar to the "_app.js" inside "pages" (major difference is that you can have multiple "layout.js"). This is why inside "app" we can create nested layouts.

Keep in mind that you can have both "app" and "pages" using, when there's a conflict "app" will take priority. If you are just getting into Next.js, I recommend you to use just one of them but not both, to avoid confusion.

In our docs, there's a switcher:

[delbaoliveira]

Thank you for the answer @shuding, @Faizan711 here's a PR to update the manual installation instructions for pages. Feel free to provide further feedback on the PR.

It's also worth noting that when you use create-next-app, you will be prompted with a question on whether you'd like to use the app router. If you select no, then pages will be setup and that should save you some time :)

....
Would you like to use `src/` directory with this project? No / Yes
Use App Router (recommended)? No / Yes <--- Select **No** to use `pages`
Would you like to customize the default import alias? No / Yes
....

[Faizan711]

Thanks @shuding and @delbaoliveira for the clarification.
I wanted to use pages but didn't knew that at the time of creating next app, so I had chosen recommend app router, but now I have made the changes and removed page.js and layout.js and added _app.js and index.js in pages folder

Will this create any issue for me in production??

[delbaoliveira]

Gotcha, and no, it shouldn't create any issues in production.

[Faizan711]

Thanks @delbaoliveira for clarifying, If there is any help needed in updating docs, I would love to contribute.

[github-actions]

This closed issue has been automatically locked because it had no new activity for a month. If you are running into a similar issue, please create a new issue with the steps to reproduce. Thank you.