Project Folder Structure

[kevinsshikuku]

Description

I would like to suggest a folder structure that is easy to comprehend and hierarchical.

Solution description

Project files should be placed in categorized folders based on what they do.

Additional information

No response

[lekipising]

I agree with this.

I would like to propose the following structure.

components - This folder will contain all the components used in the project. We can also group components inside of this folder by the related sections.

pages - Default and provided by Next JS

public - Default and provided by Next JS

styles - This folder will be used to hold any global custom styles for the project

util - This folder will be used to hold any helper functions, methods, utilities, etc that support the project.

mock - This folder will be used to hold any mock data we will need to use in the project. E.g hold sample data for the UI before any API is ready to provide data.

tests - This folder will have folders containing different types of tests. Eg a folder for e2e tests, unit tests and integration tests.

Anyone is welcome to comment, give feedback and suggest improvements and/or provide alternatives.

[lekipising]

The structure looks good.

[kevinsshikuku]

external styling should be minimal (suggestion) as we already have a library . Tailwind can do most

This seems reasonable, we can adopt this

[orama254]

Hey There...I've converted this issue into a discussion. I believe the folder structure will be essential before the projects grows in complexity

cc @kevinsshikuku, @lekipising, @dmuyah

[antosan]

I would like to suggest a structure similar to "Delightful React File/Directory Structure" by Josh W. Comeau https://www.joshwcomeau.com/react/file-structure/. The code is organized by function and broken down into small sub-parts with related concerns co-located together. This results in a codebase that is easy to refactor, extend, search, change and understand. I recommend checking the article as he goes into length to explain the thinking behind the decisions.

Basic example

├── README.md
├── e2e
│   └── example.spec.ts
├── next.config.js
├── package-lock.json
├── package.json
├── public
│   ├── favicon.ico
│   └── vercel.svg
├── src
│   ├── components
│   │   ├── Button
│   │   │   ├── Button.spec.tsx
│   │   │   ├── Button.stories.tsx
│   │   │   ├── Button.tsx
│   │   │   └── index.tsx
│   │   └── Navbar
│   │       ├── NavBar.stories.tsx
│   │       ├── Navbar.tsx
│   │       └── index.tsx
│   ├── pages
│   │   ├── _app.page.tsx
│   │   ├── about
│   │   │   ├── about.spec.tsx
│   │   │   ├── about.stories.tsx
│   │   │   └── index.page.tsx
│   │   ├── api
│   │   │   ├── hello
│   │   │   │   └── index.api.ts
│   │   │   ├── utils.test.ts
│   │   │   └── utils.ts
│   │   └── index.page.tsx
│   └── styles
│       └── globals.css
└── tailwind.config.js

I made a quick-and-dirty POC repo with this folder structure in order to be certain that what I am talking about here is not pure nonsense. I also set up tests and stories to see how well all this works together. Feel free to check it out here: https://github.com/antosan/next-file-structure

Motivation

Most React projects start with an src folder

It has become a common convention in the React ecosystem to locate the source files of a React project in a folder at the root of the project named src and only leave configuration files and folders for code that are not part of the business logic at the root of the project.

Next.js requires that pages be located in a pages folder at the root of the project. Pages can also be added under src/pages as an alternative to the root pages directory https://nextjs.org/docs/advanced-features/src-directory.

Organizing the project by function makes it easy to think about

Different features of the project will normally overlap and might need to be shared around the app. It is easier to think of code in terms of what functionality it helps to solve as opposed to which feature it belongs to. In this structure, a project will normally have different sub folders inside the src folder. These will vary depending on the scope of the project and may include folders such as components, pages, hooks, context, api, services, actions, reducers, hooks, utils, helpers e.t.c.

This structure makes it easy to onboard new contributors to the project since the decision of where to place a new file is relatively straightforward and the project ends up with a relatively flat structure which makes it easy to contribute and refactor.

Co-locating associated files helps enforce best practices

If a project makes it easy to have a .test file or a .stories file next to a component, then it is easy to remember to write tests after completing a feature, or add a Storybook story for that new component. It is also easy to remember to update related files when making a change when they are located in the same folder.

Detailed design

Configuring custom page extensions

In order to support co-locating test files, storybook files and the like in the src/pages folder, we need to prefix the page files with a custom extension and configure Next.js to load these files and ignore all the other files https://nextjs.org/docs/api-reference/next.config.js/custom-page-extensions#including-non-page-files-in-the-pages-directory. This is done in the next.config.js file.

module.exports = {
  pageExtensions: ['page.tsx', 'api.ts'],
};

With a configuration like this, we can rename our pages to have a file extension that includes .page (ex. rename about.tsx to about.page.tsx) and our API routes to have a file extension that includes .api (ex. rename hello.ts to hello.api.ts). We also need to rename _app.tsx to _app.page.tsx and _document.tsx to _document.page.tsx.

NOTE: I have used TypeScript here but everything should be similar in JavaScript.

---

Looking forward to seeing other alternatives.

[orama254]

We can do a poll on the most preferred folder structure for the project going forward

We will use the 🎉 for THIS SUGGESTTION
We will use the ❤ for THIS SUGGESTTION

I'll be collecting feedback on this as we progress...

cc @kevinsshikuku, @lekipising, @dmuyah, @antosan

[orama254]

Thanks to everyone who participated in this discussion which was successfully implemented via #66