When I started using Node.js for building REST APIs on the server side, I struggled a lot with the same question over and over again: How should the folder structure look like? Obviously there’s not a perfect or 100% correct answer to this question but after reading some articles regarding this topic, I found a folder structure that fits my needs quite good. So today I’d like to show you how I structure my REST APIs. The APIs are mostly component based what makes it much easier to request only the data we really need. For example we have a component that contains all information about users. User One thing to mention is that I use as web-framework and as ORM. Let’s have a look at the structure. express.js TypeORM Directory: root nodejs-api-structure └───dist │ └───logs │ └───node_modules │ └───src │ │ md │ ... . README This structure is nothing special and shouldn’t be new to you. It’s actually a basic Node.js setup. The interesting part is the folder on which our focus lies. src So what do we have in here? nodejs-api-structure └───src │ └───config │ └───api │ │ │ └───components │ │ │ └───middleware │ │ │ │ routes │ │ server │ └───services │ index.ts .ts .ts From here on, we’ll always work from the top of the directory down and I explain each one. Let’s start with the directory. config Directory: src/config nodejs-api-structure └───src │ └───config │ globals │ logger │ permissions.ts .ts .ts This directory includes configuration files. This could be for example: global variables logger config ACL permission SMTP config Directory: src/api/components nodejs-api-structure └───src │ └───api │ └───components │ └───article │ └───auth │ └───country │ └─── .ts user │ index Here we have the heart of our component based API. Each component consists of its own , , and . routes controller model service Let’s deep into the component and take it as example. user Directory: src/api/components/user nodejs-api-structure └───src │ └───api │ └───components │ └───user │ controller │ model │ routes │ service.ts .ts .ts .ts As you can see a component consists of the files I mentioned before. Each file represents one class that is exported. Of course, you can add here more component specific stuff like config or test files. Since I have multiple components and their classes have the same structure most of the time, I also create interfaces that are implemented in the classes. This helps me to keep the components’ structure straight. controller.ts The controller class handles incoming requests, validates them and sends the response data back to the client. It uses the class to interact with the database. service model.ts The model represents the database model for its component. In my case it’s a TypeORM class. Mostly it’s used by the class. service routes.ts Here we define our API endpoints for the corresponding component and assign the methods to them. Moreover we can do things like authorization (e.g. JWT), permission validation (e.g. ACL) or add component specific middleware. controller service.ts The service class acts like a wrapper for the database. Here we read and write data to the database. Furthermore, we can implement caching for example. Directory: src/api/middleware/ └─── │ └─── │ └─── │ │ nodejs-api-structure src api middleware auth .ts compression .ts This folder includes all the API’s global middlewares like authentication, compression, request logging etc. File: src/api/routes.ts -api- └───src │ └───api │ routes.ts nodejs structure Here we register all component and middleware routes. File: src/api/server.ts -api- └───src │ └───api │ server.ts nodejs structure Here we declare everything required for our express server: import middlware / component routes error handling … Later on, we can import the class for unit tests as well. server Directory: src/services/ This directory contains global services we need for sending mails, authorization or helper methods for example. nodejs-api-structure └───src │ └───services │ auth │ helper │ mail.ts .ts .ts auth.ts Here we setup things like our passport strategies and define authorization methods. helper.ts The helper class contains helper methods for hashing, UUIDs and so on. mail.ts This service is used for sending mails and rendering their templates. File: src/index.ts This is the startup file of our application. It initializes the database connection and starts the express server. nodejs-api-structure └───src │ . index ts All together Last but not least a complete overview of the project structure: nodejs-api-structure └───src │ └───config │ │ globals │ │ logger │ │ permissions │ └───api │ │ │ └───components │ │ │ │ │ └─── │ │ │ │ │ └───user │ │ │ controller │ │ │ model │ │ │ routes │ │ │ service │ │ │ └───middleware │ │ │ auth │ │ │ compression │ │ │ │ routes │ │ server │ └───services │ index.ts .ts .ts .ts article .ts .ts .ts .ts .ts .ts .ts .ts That’s it! I hope this is a little help for people who struggled with the same question and didn’t know where or how to start. I think there are still many things you can do better or in a more efficient way. I’m currently working on a side project, where you can see this folder structure (in a small modified way) in action. Check it out. Previously published at https://medium.com/swlh/how-i-structure-my-node-js-rest-apis-4e8904ccd2fb
