Structure of a NodeJS API Project

When starting developing a NodeJS project and learning the all the basic stuff, the first thing that comes to your mind (at least to me) was: “Now, how I structure a real project that solves a real problem?”. At this point, you have only wrote a couple of small projects that make some fun stuff but that don’t look anything like a “production ready” project.

Obviously, the answer to this require other basics questions that have to be answered before starting to think in how structure your project:

• What is the problem that you want to solve?
• Is NodeJS the right technology to use?
• What role has your NodeJS project?
• With what others components, apps, apis, databases the project will interactuate?

With this in mind, I will show you a starting point for you to define a structure for a NodeJS project, based in my recent experience of working with NodeJS for a year in a real project for a retail company.

The context

First thing you need to know is the context of the project. In this case, I will describe you a fictional situation. Let’s assume that you need to develop a solution that has the following responsibilities….

• It should storage basic transactions in a database.
• Has to integrate with some APIs (REST, SOAP) for some third parties logic.
• Other team will develop a web frontend and in the future it could have multiple “frontends”, for example, a mobile application.
• It must be scalable.
• “We need it ASAP” (Let’s say that we negotiate an MVP with the client)

In summary, you must develop a scalable headless service that must be accesible from multiple applications and it will integrate with some other software components.

The architecture

Now that we already have a context of what we need to develop, we can define an architecture.

In this case, for building the described application, the right choice is to use NodeJS, for the following reasons:

• It will not process a lot of data
• It will mostly be a Middleware. Others services will do the heavy lifting.
• Must handle a lot of request from multiple sources. (The async nature is a good thing to have here)
• MVP, you can code it very fast with Javascript :)

The representation of components of the project would be the following. The blue box is the API REST that we need to develop.

The NodeJS Modules

For the architecture defined, we will use the following basics NPM modules:

Express: This is a web framework for NodeJS that’s perfect for managing http request, creating middlewares, routing endpoints, etc. We will use it to expose the information of the application. http://expressjs.com/

Axios: A veeeery nice module that I love to use to communicate to other APIs is a very simple, promise based HTTP client called Axios. You can use it to make very simple requests (like, just GET or POST requests), and also, make more complex implementations that send specific custom headers, configure timeouts, authentication, proxys, etc. https://www.npmjs.com/package/axios

Sequalize: This is a promise based ORM for NodeJS that you can use to model and access data from different databases (MySQL, MSSQL, PostgreSQL, SQLite). So here you can manage migrations, queries, transactions, seeds and a lot more. http://docs.sequelizejs.com/

PM2: This tool helps you to manage Node apps processes in production environment. https://www.npmjs.com/package/pm2

ShipitJS: Deployment automation tool (a Capistrano alternative for NodeJS developers). https://github.com/shipitjs/shipit

Obviously, you can use more NPM modules, but for this example, I’m presenting you just a couple of modules that I think are very useful and that you can use from a very basic to an advanced project.

The Structure

NodeJS/Javascript have a characteristic that some people find usefull, but it can make you go deep in the wrong way, and this is the freedom of choose how you want to structure your project (Remember that NodeJS is not a framework like Rails or .Net). Only the experience working in different projects will let you define the best structure for every situation.

I suggest the following structure:

.
├── config                  # App configuration files
│   ├── sequalize.json        # Sequalize config
│   ├── serviceOne.json       # ServiceOne config
│   └── ...                 # Other configurations
├── routes                  
│   ├── controllers         # Request managers
│   ├── middlewares         # Request middlewares
│   └── routes.js           # Define routes and middlewares here
├── services                # External services implementation   
│   ├── serviceOne
│   └── serviceTwo
│   └── ...                 # Other services
├── db                      # Data access stuff  (Sequalize mostly)
│   ├── models              # Models
│   ├── migrations          # Migrations
│   ├── seeds               # Seeds
│   └── index.js            # Sequalize instantiation
├── core                    # Business logic implementation
│   ├── accounts.js         
│   ├── sales.js            
│   ├── comments.js              
│   └── ...                 # Other business logic implementations
├── utils                   # Util libs (formats, validation, etc)
├── tests                   # Testing
├── scripts                 # Standalone scripts for dev uses
├── pm2.js                  # pm2 init
├── shipitfile.js           # deployment automation file
├── package.json           
├── README.md         
└── app.js                  # App starting point

The conclusion

This folder structure follows the idea of making things simple. Don’t over engineer things, keep it simple! Maybe your project is simpler than what we are using as an example here, so go on and make it lighter :)

But what if the project gets bigger? You can modularize the structure grouping your core files into subfolders that represent different components of your application (like Users, Administration, Statistics, etc). Other way to modularize it is to create different projects and deploy each one as a different process or service, so you can have multiple independent projects (this is called Microservices).

And remember, when creating project structures, just pick the easiest thing that you could make and do it! don’t over engineer it and just do it!

Thank you for reading!, I hope to create a small project soon with this structure, so you can use it as a boilerplate or as an example that you can follow.

Regards!

Gonzalo.