85

What are some good ways to organize large Node.js projects?

For example, an app making use of both express.js and socket.io? This would include both application logical structure as well as filesystem.

Currently, I'm finding myself shoving a ton of code into a single master js file and placing code into a giant global object, and it feels naughty.

4
  • 2
    Got time to read a book?
    – Straseus
    Mar 22, 2012 at 23:35
  • I might have to buy this book, thanks! Mar 23, 2012 at 2:10
  • Google "JavaScript Modules" or "Modular JavaScript" :-)
    – Sri
    Mar 23, 2012 at 6:09
  • 1
    I've read the book suggested by Straseus, and it gives a lot of good advice and analysis, but I'm afraid that not much transfers well to structuring a Node.js application with express. PuerkitoBio's answer below links to some suggestions of a good starting file structure; I plan to build on that structure as needed.
    – Aaron
    Aug 2, 2012 at 21:51

6 Answers 6

100

A Beginners Example

I like the originally checked from @david-ellis and you should study it in depth to understand it as it is a good one. However, I would have liked it more simplified for the beginners wanting to see a straight forward example. Here's what I would have liked to have seen someone show me.

Let's give a typical scenario where you are using express and you have a lot of routes listed on your app.js file. Its contents would look something like this:

app.js

// ... startup code omitted above

app.get('/', function(req, res) {
  res.render('index', { title : 'home' });
});
app.get('/contactus', function(req, res) {
  res.render('contactus', { title : 'contact us' });
});
app.get('/anotherpage', function(req, res) {
  res.render('anotherpage', { title : 'another page' });
});
// and so on...

You can imagine if you have 50 routes, this file can get quite out of hand. It would be nice to remove some of this clutter out of the app.js file.

What you would do is create a "controllers" folder in your app so your structure would now look like this:

app.js
/controllers

Create a file within "/controllers" named "index.js" then put the following code.

/controllers/index.js

module.exports.set = function(app) {
   // copy your routes listed in your app.js directly into here
}

Cut and paste your route listings from your "app.js" file and place them into the "/controllers/index.js" file.

On your app.js file, remove your routes and in place of them do the following.

app.js

// remove your routes and replace with this code
var controllers = require('./controllers');
controllers.set(app);

Now if you wanted to have your "/controllers/index.js" file also be split up, let's add one more example so you can see how Node.js really acts like a Russian Doll in how its code can be organized.

Within "/controllers" add one more file "accounts.js" and place the following within it.

/controllers/account.js

module.exports.set = function(app) {
    // put more app route listings here
}

Now within your "/controllers/index.js file, put a reference to "account.js"

/controllers/index.js

var account = require('./account.js');

module.exports.set = function(app) {
   // your routes here

   // let "account.js" set other routes
   account.set(app);
}

As you can imagine, you can keep breaking things up into smaller and smaller parts and put more folders within folders and reference with "require" if you like. You can use the same concept for "/lib" or library files. "node_modules" is already doing this.

That is just one of many reasons node.js is very enjoyable to program with.

Manageable Express 4 Routing example

Here's another post I responded to about express 4 routes that relates to this.

Rest with Express.js nested router

5
  • IMHO it was better before the update, you can avoid having to give a name for every controller by implementing an aliasing mechanism, where one route routes into another, this also helps with canonical URL's May 1, 2014 at 18:50
  • Don't mind the canonical URLs part, it was an afterthought. By canonical URL I meant adding a canonical <link> to something like /example/path when a user enters /example/path/ in the address bar (or the other way around). May 1, 2014 at 19:16
  • You know, as a programmer its natural to want this type of organized hierarchy, but it does not lend itself well in practical terms when opening a file, or reading a checkin. You'll end up with a large number of "index.js" which quickly becomes painful to work with. Jan 12, 2015 at 17:41
  • A year later, a valuable post for me. I am just starting node.js to use for a weekend project.
    – masfenix
    Feb 7, 2015 at 0:19
  • @JasonSebring There is so much information and I am so new! I am very lost right now. As a grad student in math I do a lot of matlab/R/mathematica BUT the last time I touched a web/desktop framework was back in the .net 2.0 days.
    – masfenix
    Feb 7, 2015 at 0:43
10

I wrote a blog post about this very subject a few days ago, and although the article is in French, I set up a GitHub repo (in English) to show a working example of the structure I use.

Obviously, there is no definitive answer to this question, but it's interesting to see what others are doing, and I am all ears for other opinions on the subject (which was also discussed here, where you can see a summary of what I suggest).

2
  • Thanks for that link, it was a good read (with the help of Google Translate), and I'm sure I'll follow some of your suggestions in designing the organization of the project I'm currently working on.
    – Aaron
    Aug 2, 2012 at 21:48
  • Can you fix the link? May 7, 2018 at 8:46
2

Similar to the other blog post, I wrote one specifically about organizing Express applications. It's the method I've been using for about a year and a half. Basically, organize your applications around your data entities or any other core elements. Place logic for each of those elements in their own directories. I tried to borrow a lot from Python.

http://rycole.com/2013/01/28/organizing-nodejs-express.html

1

His Articles are no longer online, but Eric Satterwhite's node series recommended a structure as listed below.

# Project 
. 
|-- packages/
|   |-- project-core
|   |   |-- lib/
|   |   |-- commands/
|   |   |-- startup/
|   |   |-- conf/
|   |   |-- test/
|   |   |-- package.json
|   |   |-- README.md
|   |   |-- events.js
|   |   |-- .npmignore
|   |   `-- index.js
|-- package.json
`-- index.js

With the packages/ folder turning into your source for modularity.

0

If you are a beginner in this area, I suggest you take a look at existing projects that are loved by developers. Some of them are:

  • Sails.js - 18k stars. You can take a look how they organized APP structure at the link I provided. A great website has an explanation for each folder in the structure.

  • Express.js generator - 800 stars. There is the great and simple template to start working with Express.js. Here you can notice how they split routes from the app.

By the way, so many developers did your case before, and you can just fork it and upgrade.

  • Kioska. Look how they separate events into different files at the events/ folder.

  • Ballons.io 2.3k stars. Unfortunately, they have the whole socket server in one file but you can learn the whole structure of the app with node.js and socket.io

0

If you don't mind, you can always learn typescript and go for https://nestjs.com/

If you want to stick with JS I strongly recommend to use onion architecture. The best practice is to keep separated business logic, controllers, even libraries (they should be wrapped inside of some classes / helpers) - just in case, if you will have to migrate to another library (different CSV parser etc.).

With onion architecture, you don't care from where requests comes from, there won't be a lot of changes to add even some message broker.

Also try this one https://en.wikipedia.org/wiki/Domain-driven_design

ESLint may help with proper project organization.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.