How Do I Organize a Sustainable Next.js Project?

[Viễn Đinh]

Challenge

Bad Next.js project organization can lead to problems, such as poor performance, unscalable, unmaintainable, hard to navigate between files, etc. So, in this article, I will share with you how I organize a sustainable Next.js project to improve the development experience.

Solution

I have built a Shopify theme from scratch. I love the clear and maintainable project structure from it. It influences me on how to organize my projects. And just like a Shopify theme, I have several folders like these:

• Pages: Each page has a layout. Each page can have many sections as needed. For example, a product detail page can have three sections: A product information section, a related products section, and a recommended products section.
• Layouts: A layout is a reusable component. We can use a layout on many pages. A layout can have a header, a footer, and many child sections.
• Sections: To me, a section is very important. A section file has its UI component and its data fetching function. So we can reuse a section on many pages without rewriting data fetching code. I also created an npm package called @maxvien/next to handle typesafe modular data fetching in Next.js.
• Snippets: A snippet is a reusable atomic component. We can use a snippet in pages, layouts, and sections.
• Assets: The assets folder contains static resources like CSS files, images, fonts, etc.
• Utilities: The utilities folder includes reusable functions, hooks, services, types, etc.

Now, you have an overview of how I organize a Next.js project. In the next section, I am going to show you in detail.

Project Folders

Look at the folder structure below, you can see that I have src in the root level of the project. So I can separate the source code from the other parts of the project.

• src
  • assets
  • layouts
  • pages
  • sections
  • snippets
  • utilities

Wrapping the other folders into one src folder makes the project less chaotic. You can look at a real folder structure here: https://github.com/maxvien/next-shopify-storefront/tree/v3/src

Absolute Imports

Using relative imports like this import mod from '../../../mod.ts' makes it hard to identify the locations of the imported files. So, using absolute imports is a better choice. And these are what absolute imports look like.

import '@site/assets/style.css';

import { StoreLayout } from '@site/layouts/StoreLayout';

import { ProductListSection, fetchProductListSection } from '@site/sections/ProductListSection';

import { Button } from '@site/snippets/Button';

import { DataProps, useVariantSelector } from '@site/utilities/deps';

To enable absolute imports, you must create Next.js projects with TypeScript.

npx create-next-app@latest --typescript

Next, in the tsconfig.json file, I will add these lines in the compiler options.

{
  "compiler options": {
    ...
    "baseUrl": ".",
    "paths": {
      "@site/*": ["./src/*"]
    }
  },
 ...
}

You can also take a look at the full file here: https://github.com/maxvien/next-shopify-storefront/blob/v3/tsconfig.json

Conclusion

Good Next.js project organization should be scalable, maintainable, easy to navigate between files, etc. I hope my little solution can improve your development experience. Thank you for reading!