Best Practice for Node.js Folder Structure

Jacob Mitchell
4 min readApr 5, 2023
Node.js Backend development Frontend development JavaScript Express.js MongoDB REST APIs GraphQL React.js Vue.js Angular.js Testing Mocha Jest Chai Deployment AWS Azure Google Cloud Docker Kubernetes OWASP Authentication Authorization JSON Web Tokens (JWT) OAuth Passport.js Security.
Best Practice for Node.js Folder Structure

Node.js has become one of the most popular technologies in recent years. It’s an open-source, cross-platform, JavaScript runtime environment that allows developers to build scalable and high-performance applications. When starting a new Node.js project, one of the most important things to consider is the folder structure. A good folder structure makes it easier to organize your code, find files, and maintain the project over time. In this article, we’ll explore the best practices for Node.js folder structure and provide some examples.

Why is folder structure important?

A well-organized folder structure is essential for any project, regardless of the technology used. In the case of Node.js, it’s even more important because of the modular nature of the platform. Node.js applications typically consist of multiple modules that work together to achieve a common goal. A well-designed folder structure can help you:

  • Keep your code organized and easy to navigate
  • Reduce complexity and make it easier to maintain the project
  • Promote code reuse by separating code into reusable modules
  • Improve collaboration by making it easier for team members to understand the project’s structure

Basic folder structure

Let’s start with a basic folder structure that you can use for most Node.js projects:

project-name/
├── src/
│ ├── app.js
│ ├── routes/
│ ├── controllers/
│ ├── models/
│ ├── views/
│ └── public/
├── test/
├── node_modules/
├── package.json
└── README.md

This folder structure separates your project into four main directories: src, test, node_modules, and the project root. Here's what each directory does:

  • src: This directory contains all the source code for your project, including the main application file (app.js), route definitions, controller functions, database models, views, and public assets like CSS and images.
  • test: This directory contains all the test code for your project. Tests should be organized in a way that mirrors the folder structure of your source code.
  • node_modules: This directory is created by Node.js when you install dependencies for your project using npm install. It contains all the packages that your project depends on.
  • project root: This directory contains the package.json file, which specifies the project's dependencies and other metadata, as well as the README.md file, which provides an overview of the project.

Detailed folder structure

While the basic folder structure works for most Node.js projects, larger and more complex projects may require a more detailed folder structure. Here’s an example of a more detailed folder structure that you can use for larger projects:

project-name/
├── src/
│ ├── app.js
│ ├── config/
│ ├── controllers/
│ ├── db/
│ ├── middleware/
│ ├── models/
│ ├── routes/
│ ├── services/
│ ├── utils/
│ ├── views/
│ └── public/
├── test/
├── node_modules/
├── package.json
└── README.md

This folder structure expands on the basic structure by adding more directories that are specific to different parts of your application. Here’s what each directory does:

  • config: This directory contains configuration files for your application, such as environment variables, database credentials, and API keys.
  • controllers: This directory contains the controller functions that handle requests and responses.
  • db: This directory contains all the code related to database operations, including schema definitions, migrations, and seeds.
  • middleware: This directory contains middleware functions that run between the request and response stages of your application.
  • models: This directory contains the database models

for your application. Each model represents a table or collection in your database and defines the structure of the data.

  • routes: This directory contains the route definitions for your application. Each route maps a URL to a specific controller function.
  • services: This directory contains code for services that your application provides, such as email sending, data scraping, or file uploading.
  • utils: This directory contains utility functions that can be used throughout your application, such as date formatting or string manipulation.
  • views: This directory contains the views for your application, which are typically written in HTML or a template language like Handlebars or EJS.
  • public: This directory contains static assets that are served directly to the client, such as CSS, images, or client-side JavaScript.

Tips for organizing your code

Now that you have a good idea of how to structure your folders, here are some tips for organizing your code within each directory:

  • Keep files small and focused: Each file should contain only the code that is related to a specific functionality or feature. For example, a users.js file in the controllers directory should contain only controller functions related to user management, such as creating a user, updating a user, or deleting a user.
  • Use descriptive file names: File names should be descriptive and indicate the purpose of the file. For example, a file that contains utility functions for date formatting could be called date-utils.js.
  • Group related files together: Files that are related to each other should be grouped together in the same directory. For example, all the models related to a specific database table should be placed in the same models subdirectory.
  • Use subdirectories as needed: If a directory becomes too cluttered with files, consider creating subdirectories to group related files together. For example, if you have many middleware functions, you might create a subdirectory called middleware/auth to group together all the middleware functions related to authentication.
  • Follow naming conventions: Use naming conventions that are consistent with the language or framework you are using. For example, in Express.js, routes are typically named after the HTTP verb and the resource, such as GET /users or POST /login.

Conclusion

A good folder structure is essential for any Node.js project. It can help you organize your code, reduce complexity, promote code reuse, and improve collaboration. When designing your folder structure, keep in mind the basic principles of organization, clarity, and maintainability. With a well-organized folder structure, you’ll be able to develop and maintain your Node.js application with greater ease and efficiency.

--

--

Jacob Mitchell

Software engineer, Technical writer, writing about software development </>