How Should You Organize your Nextjs Project

Here is project structure I found helpful and easy to use and understand for a nextjs project I was working on.

I`ll be using this structure going forward on all my projects as its simple, and also easy to understand and use.

Example Project and file structure.

Folders only

1📦playwright
2┣ 📂tests
3📦prisma
4┗ 📜schema.prisma
5📦src
6┣ 📂app
7┃ ┣ 📂(app)
8┃ ┣ 📂(marketing)
9┃ ┣ 📂api
10┃ ┣ 📂auth
11┣ 📂components
12┃ ┣ 📂ui
13┣ 📂lib
14┃ ┣ 📂API
15┃ ┃ ┣ 📂Database
16┃ ┃ ┗ 📂Services
17┃ ┣ 📂config
18┃ ┣ 📂types
19┃ ┗ 📂utils
20┣ 📂styles
21┗ 📜middleware.ts
22📦emails
23...configuration files
24

Folders and example Files

1📦playwright
2 ┣ 📂tests
3 ┃ ┣ 📜auth.setup.ts
4 ┃ ┣ 📜todo.spec.ts
5 ┣ 📜config.ts
6 ┣ 📜globalTeardown.ts
7 ┗ 📜utils.ts
8📦prisma
9┗ 📜schema.prisma
10📦src
11┣ 📂app
12┃ ┣ 📂(app)
13┃ ┣ 📂(marketing)
14┃ ┃ ┣ 📂pricing
15┃ ┃ ┃ ┗ 📜page.tsx
16┃ ┃ ┣ 📂_PageSections
17┃ ┃ ┃ ┣ 📜CTA.tsx
18┃ ┃ ┃ ┣ 📜Feature.tsx
19┃ ┃ ┃ ┣ 📜FeatureList.tsx
20┃ ┃ ┃ ┣ 📜Header.tsx
21┃ ┃ ┃ ┣ 📜Hero.tsx
22┃ ┃ ┣ 📜layout.tsx
23┃ ┃ ┗ 📜page.tsx
24┃ ┣ 📂api
25┃ ┃ ┣ 📂auth
26┃ ┃ ┃ ┗ 📂[...nextauth]
27┃ ┃ ┃ ┃ ┗ 📜route.ts
28┃ ┃ ┣ 📂payments
29┃ ┃ ┃ ┗ 📂webhook
30┃ ┃ ┃ ┃ ┗ 📜route.ts
31┃ ┣ 📂auth
32┃ ┃ ┣ 📂login
33┃ ┃ ┃ ┗ 📜page.tsx
34┃ ┃ ┣ 📂signup
35┃ ┃ ┃ ┗ 📜page.tsx
36┃ ┃ ┣ 📂_PageSections
37┃ ┃ ┃ ┗ 📜AuthForm.tsx
38┃ ┃ ┣ 📜error.tsx
39┃ ┃ ┗ 📜layout.tsx
40┃ ┣ 📜global-error.tsx
41┃ ┣ 📜layout.tsx
42┃ ┣ 📜loading.tsx
43┃ ┗ 📜not-found.tsx
44┣ 📂components
45┃ ┣ 📂ui
46┃ ┃ ┣ 📜Button.tsx
47┃ ┃ ┣ 📜Card.tsx
48┃ ┃ ┣ 📜Input.tsx
49┃ ┣ 📜Footer.tsx
50┃ ┣ 📜Form.tsx
51┣ 📂lib
52┃ ┣ 📂API
53┃ ┃ ┣ 📂Database
54┃ ┃ ┃ ┣ 📂subscription
55┃ ┃ ┃ ┃ ┣ 📜mutations.ts
56┃ ┃ ┃ ┃ ┗ 📜queries.ts
57┃ ┃ ┃ ┣ 📂todos
58┃ ┃ ┃ ┃ ┣ 📜mutations.ts
59┃ ┃ ┃ ┃ ┗ 📜queries.ts
60┃ ┃ ┃ ┗ 📂user
61┃ ┃ ┃ ┃ ┣ 📜mutations.ts
62┃ ┃ ┃ ┃ ┗ 📜queries.ts
63┃ ┃ ┗ 📂Services
64┃ ┃ ┃ ┣ 📂auth
65┃ ┃ ┃ ┃ ┣ 📜auth.ts
66┃ ┃ ┃ ┃ ┣ 📜login.ts
67┃ ┃ ┃ ┣ 📂init
68┃ ┃ ┃ ┃ ┣ 📜payments.ts
69┃ ┃ ┃ ┃ ┣ 📜prisma.ts
70┃ ┃ ┃ ┣ 📂payments
71┃ ┃ ┃ ┃ ┣ 📜subscription.ts
72┃ ┃ ┃ ┃ ┗ 📜webhook.ts
73┃ ┣ 📂config
74┃ ┃ ┣ 📜api.ts
75┃ ┃ ┣ 📜auth.ts
76┃ ┃ ┣ 📜dashboard.ts
77┃ ┃ ┣ 📜routes.ts
78┃ ┃ ┗ 📜site.ts
79┃ ┣ 📂types
80┃ ┃ ┣ 📜enums.ts
81┃ ┃ ┣ 📜types.ts
82┃ ┃ ┗ 📜validations.ts
83┃ ┗ 📂utils
84┃ ┃ ┣ 📜error.ts
85┃ ┃ ┣ 📜helpers.ts
86┃ ┃ ┣ 📜hooks.ts
87┣ 📂styles
88┃ ┣ 📜fonts.ts
89┃ ┣ 📜globals.css
90┃ ┗ 📜ThemeProvider.tsx
91┗ 📜middleware.ts
92📦emails
93...configuration files

src/app

This is the “main” directory and most of the UI code and a lot of business logic is kept here.

The organization of this directory will vary depending on the type of app being built.

But a general SAAS or webapp can be organized as following:

src/app/(marketing)

Contains the pages for the marketing site such as the landing page and pricing page.

src/app/auth

Contains the pages for authentication such as the login and signup pages.

src/app/(app)

Pages for the core of the application.

src/app/api

Used to define routes for third party libraries that need a public endpoint. If doing general fetching or mutating of data, server actions or server functions should be used instead.

src/components

very basic building block components that are shared across many pages are kept in components/ui directory.

More complex components that are shared across several pages

Components that are much more complex and only used by one or two pages are referred to as Page Sections.

Page Sections are usually made up of several components and UI-components and represent an entire area of a page rather than an isolated component.

A collection of Page Sections form a full page.

Page Section files are co-located in the same directory as their Parent page in the /app directory. As opposed to components and UI-components which are located in their own /component directory outside the /app directory.

This is because since they are usually only used by one page, its simpler just to keep them near their respective page. Having a Page Section located in a separate components directory would be overly complex, unnecessary and confusing.

The scale of complexity and building blocks is as follows.

UI-components (e.g button) -> Components (e.g Navbar) -> Page Sections (e.g Hero) -> Page (e.g. Landing)

src/lib

This directory will hold API calls, third party library SDKs, configuration files etc.

This directory will basically hold files, business logic and code that are reused in different App pages

src/lib/API

The API library can be used to hold both api requests to our own db and also third party library api requests.

src/lib/Database

This directory will hold the code for working with our database.

src/lib/Database/(db_model)

Each directory inside the /Database directory will be corresponding database model in the data schema

mutations.ts and queries.ts
Each data model can have queries or mutations, as per nextjs best practices mutations are setup as server actions and queries as regular server functions.

This allows queries to integrate into nextjs internal caching system.

Mutations don't need to be cached, so server actions are used.

src/lib/Services

Third party services. This will hold code for making API requests and working with third party libraries.

src/lib/Services/(service)

This directory will hold all the required code to work with the third party service or library.

For example src/lib/Services/stripe will hold files to setup the stripe SDK functions

src/lib/Services/init

The SDK for third party libraries can be initialized here and imported into other files as needed.

For example the stripe SDK can be initialized here with the stripe API key and imported into other files.

src/lib/config

Each file in this directory contains constant variables that are required for different parts of the app.

Defining them here allows consolidation of repeated variables and values. And allows for seamless modifications and updates.

src/lib/types

This directory holds reusable types, enums, third party library custom types, and Zod validations.

/types.ts

Misc types that may be used in multiple files are defined here. Its also acceptable to just define the types or interface in the file its used in.

/enums.ts

Enums are defined here.

/validations.ts

Zod validations and react hook form values are defined here.

src/lib/utils

Different utility files and helper functions can be defined here. Also react context and custom react hooks can be initialized here as well.

Any file or code that doesn't fit in other categories can be defined here as well.

/styles

Files for global styles, fonts and the nextjs Themeprovider are defined here.

Root Directories

Directories such as e2e testing with playwright and database prisma schema can be defined at top level because they generally function independent of the source code and there isn't much code sharing between them.