Structuring a NodeJS API Project: Best Practices for Organization, Scalability, and Testability

Recently, in my capacity as the CTO of Renet Consulting, I endeavored to identify the best practices for structuring a NodeJS API project. I found that there are limited resources available detailing folder structures that optimize both maintainability and testability. Although AI recommendations suggested segregating source code and tests into separate directories, this approach could present difficulties for less experienced developers when attempting to create unit tests. To strike a balance between maintainability and ease of testing, I recommend adhering to the following folder structure:

project/
├── node_modules/
├── src/
│   ├── controllers/
│   │   ├── auth.controller.js
│   │   └── auth.controller.spec.js
│   ├── middleware/
│   ├── models/
│   ├── services/
│   └── routes/
├── .env
├── .gitignore
├── package.json
└── README.md

For a significantly large application, I recommend dividing it using the following structure:

project/
├── node_modules/
├── src/
│   ├── controllers/
│   │  └─ auth/
│   │     ├── auth.controller.js
│   │     └── auth.controller.spec.js
│   ├── middleware/
│   ├── models/
│   ├── services/
│   └── routes/
├── .env
├── .gitignore
├── package.json
└── README.md