Notebook 📒

📜 Project Structure

6 min read

Introduction

In this essay I will explain all default files and folders, that come when creating a Next.js project. Its important to know what each file does even though most of them can be ignored at the beginning. Besides that I will talk about the Structure strategy I learned in my online course and link some more of the Next.js Documentation.

Overview
Top Level Files are mostly config files
Structure strategy that helps me keep the overview of my project
Example Structure of the Road to Next
Conclusion

Top Level Files

Most of the top level files are configuration files or auto generated files. While its not necessarily to know all details about each of them, it’s still good to know what files serves wich purpose. In the following diagram there is a overview about all default files that come out of the box when creating a new Next.js project. I will talk about some of the relevant files in the next chapters but won’t mention the files wich are marked with (a) since they are the ones who get auto-generated.

.
├── .next/               (a) # Build output & cache generated by Next.js (auto-generated, do not edit)
├── node_modules/        (a) # Installed npm dependencies (auto-generated)
├── public/                  # Static assets (images, fonts, etc.) served directly
├── src/
│   └── app/                 # App Router root (Next.js routing system)
├── .gitignore               # Files/folders Git should not track
├── eslint.config.mjs        # ESLint configuration (code quality & linting rules)
├── next-env.d.ts        (a) # Next.js TypeScript type definitions (auto-generated)
├── next.config.ts           # Next.js configuration file
├── package-lock.json    (a) # Locked versions of dependencies (auto-generated by npm)
├── package.json             # Project metadata, dependencies, and scripts
├── postcss.config.mjs       # PostCSS configuration (used for CSS processing)
├── README.md                # Project documentation
└── tsconfig.json            # TypeScript configuration
Source
📄 Next.js Documentation > Project structure and organization

public

One use case of the public folder is for adding all kinds of custom icons (svg) or favicon. Another is to add a robot.txt file (a file thats used to tell the search engine how to crawl your website). But you can even add html file or pdf files (according to chatgpt - should probably double check that). The public folder is great because it works just like your root folder. All assets inside it can be directly accessed with /.

For example, this file

public/avatars/me.png

can be accessed with

/avatars/me.png

But there are also some dangers hidden. One being the issue with caching. Next.js won’t be able to cache anything inside the public folder, since these assets might change. And the second being the potential problem of having two identical paths. Like in this example, where both files are accessible with the same url, wich of course will break the application.

public/
  hello
src/app/hello
  page.tsx

both are reachable with

/hello
Source
📄 Next.js Documentation > public-folder

src

While src is technically an optional folder, I like to add it because it stores most of my code within one common place. I will explore the techniques of structuring the project inside the src folder more in a later chapter.

Good to know

  • src/app or src/pages will be ignored if app or pages are present in the root directory.
  • If you’re using src, you’ll probably also move other application folders such as /components or /lib.
Source
📄 Next.js Documentation > src-folder

eslint.config.mjs

This config file is used for configuring eslint and defining the preferred linting rules. I happend to find a great template of a community member of the Road to Next.

next.config.ts

This config file is the place where I can define Next.js itself. Here I can tell how it should behave for example when building the application. So far I happend to use this config file for experimenting with the react complier or for telling Next to use typed routes. futureLink🖇️ ⇒ look config in R2N App

package.json

This config file is where all my custom scripts are defined. And its also the place where all dependencies for the dev and prod environment are defined.

postcss.config.mjs

This config file is mainly used for supporting the Tailwind CSS features if enabled during the project setup. But besides that I haven’t had any contact with this file but im sure it can do way more - should explore it another time more deeply.

tsconfig.json

This files purpose is to tell typescript how to type-check my code an how strict it should be. So far I haven touched it and just kept the default.

Structure strategy

There is no correct way on how to structure the projects. With that said, I will just go with the one learned in the Road to Next. But its still worth to have a look at the examples of next.js.

src/app

The app folder will contain all pages that should get their own route. The only thing thats required is a page.tsx file within the folder. Be aware that only pages defined within the app folder can become a route, all other locations are invisible for the App Router.

So for example this page

src/app/users/page.tsx

will have this route

/users

and this url

http://localhost:3000/users

src/component

The component folder is the perfect place for adding components that can be shared across different projects. It’s also the place where shadcn will save its components:

src/components/ui

So fare I happend to use the components folder for

src/features

The features folder is the place where I can store all components that are explicitly created for this project and won’t work in other projects. This is often the case for database queries, actions or project specific components.

src/path.ts

This file is the perfect place for storing all app routes in one place. This enables a better overview and easier handling of routes. futureLink🖇️

src/data.ts

The place I can store my test data.

Example Structure of the Road to Next

src/                              
├── app/                           # App Router with all routes
│   ├── tickets/
│   │   └── page.tsx
│   │
│   ├── globals.css
│   ├── layout.tsx
│   └── page.tsx
│
├── components/                    # Shared components across projects   
│   ├── form/
│   │   ├── hooks/
│   │   │   └── use-action-feedback.ts
│   │   │
│   │   ├── utils/
│   │   │   └── to-action-state.ts
│   │   │
│   │   ├── field-error.tsx
│   │   ├── form.tsx
│   │   └── submit-button.tsx
│   │
│   ├── theme/
│   │   ├── theme-provider.tsx
│   │   └── theme-switcher.tsx
│   │
│   └── ui/                         # Shadcn only
│       ├── card-compact.tsx
│       ├── header.tsx
│       ├── heading.tsx
│       ├── placeholder.tsx
│       └── spinner.tsx
│
├── features/                       # Project specific features
│   └── ticket/
│       ├── actions/
│       │   ├── delete-ticket.ts
│       │   └── upsert-ticket.ts
│       │
│       ├── components/
│       │   ├── ticket-item.tsx
│       │   ├── ticket-list.tsx
│       │   └── ticket-upsert-form.tsx
│       │
│       ├── queries/
│       │   ├── get-ticket.ts
│       │   └── get-tickets.ts
│       │
│       └── constants.tsx
│
├── paths.ts                         # All router paths
└── data.ts                          # Dummy data

Conclusion

Creating the perfect Project Structure might be impossible. But the good thing is, its not even necessarily. I think what matters is to just choose one that fits my needs and stick with it for a while. Sooner or later I will see its strength and weaknesses and can adopt it further.

Graph View

Backlinks