Folder structure for a Node.js project

Question

I notice that Node.js projects often include folders like these:

/libs, /vendor, /support, /spec, /tests

What exactly do these mean? What's the different between them, and where should I include referenced code?

Answer 1

Concerning the folders you mentioned:

• /libs is usually used for custom classes/functions/modules
• /vendor or /support contains 3rd party libraries (added as git sub-module when using git as source control)
• /spec contains specifications for BDD tests.
• /tests contains the unit-tests for an application (using a testing framework, see here)

NOTE: both /vendor and /support are deprecated since NPM introduced a clean package management. It's recommended to handle all 3rd-party dependencies using NPM and a package.json file

When building a rather large application, I recommend the following additional folders (especially if you are using some kind of MVC- / ORM-Framework like express or mongoose):

• /models contains all your ORM models (called Schemas in mongoose)
• /views contains your view-templates (using any templating language supported in express)
• /public contains all static content (images, style-sheets, client-side JavaScript)
  • /assets/images contains image files
  • /assets/pdf contains static pdf files
  • /css contains style sheets (or compiled output by a css engine)
  • /js contains client side JavaScript
• /controllers contain all your express routes, separated by module/area of your application (note: when using the bootstrapping functionality of express, this folder is called /routes)

I got used to organize my projects this way and i think it works out pretty well.

Update for CoffeeScript-based Express applications (using connect-assets):

• /app contains your compiled JavaScript
• /assets/ contains all client-side assets that require compilation
  • /assets/js contains your client-side CoffeeScript files
  • /assets/css contains all your LESS/Stylus style-sheets
• /public/(js|css|img) contains your static files that are not handled by any compilers
• /src contains all your server-side specific CoffeeScript files
• /test contains all unit testing scripts (implemented using a testing-framework of your choice)
• /views contains all your express views (be it jade, ejs or any other templating engine)

Answer 2

There is a discussion on GitHub because of a question similar to this one: https://gist.github.com/1398757

You can use other projects for guidance, search in GitHub for:

• ThreeNodes.js - in my opinion, seems to have a specific structure not suitable for every project;
• lighter - an more simple structure, but lacks a bit of organization;

And finally, in a book (http://shop.oreilly.com/product/0636920025344.do) suggests this structure:

├── index.html
├── js/
│   ├── main.js
│   ├── models/
│   ├── views/
│   ├── collections/
│   ├── templates/
│   └── libs/
│       ├── backbone/
│       ├── underscore/
│       └── ...
├── css/
└── ...

Answer 3

More example from my project architecture you can see here:

├── Dockerfile
├── README.md
├── config
│   └── production.json
├── package.json
├── schema
│   ├── create-db.sh
│   ├── db.sql
├── scripts
│   └── deploy-production.sh 
├── src
│   ├── app -> Containes API routes
│   ├── db -> DB Models (ORM)
│   └── server.js -> the Server initlializer.
└── test

Basically, the logical app separated to DB and APP folders inside the SRC dir.

Answer 4

Assuming we are talking about web applications and building APIs:

One approach is to categorize files by feature. To illustrate:

---

We are developing a library application. In the first version of the application, a user can:

• Search for books and see metadata of books
• Search for authors and see their books

In a second version, users can also:

• Create an account and log in
• Loan/borrow books

In a third version, users can also:

• Save a list of books they want to read/mark favorites

---

First we have the following structure:

books
  └─ entities
  │   └─ book.js
  │   └─ author.js
  │
  └─ services
  │   └─ booksService.js
  │   └─ authorsService.js
  │
  └─ repositories
  │   └─ booksRepository.js
  │   └─ authorsRepository.js
  │
  └─ controllers
  │   └─ booksController.js
  │   └─ authorsController.js
  │
  └─ tests
      └─ ...

We then add on the user and loan features:

user
  └─ controllers
  └─ entities
  └─ services
  └─ ...

loan
  └─ controllers
  └─ ...

And then the favorites functionality:

favorites
  └─ controllers
  └─ entities
  └─ ...

For any new developer that gets handed the task to add on that the books search should also return information if any book have been marked as favorite, it's really easy to see where in the code he/she should look.

Then when the product owner sweeps in and exclaims that the favorites feature should be removed completely, it's easy to remove it.

Answer 5

It's important to note that there's no consensus on what's the best approach and related frameworks in general do not enforce nor reward certain structures.

I find this to be a frustrating and huge overhead but equally important. It is sort of a downplayed version (but IMO more important) of the style guide issue. I like to point this out because the answer is the same: it doesn't matter what structure you use as long as it's well defined and coherent.

So I'd propose to look for a comprehensive guide that you like and make it clear that the project is based on this.

It's not easy, especially if you're new to this! Expect to spend hours researching. You'll find most guides recommending an MVC-like structure. While several years ago that might have been a solid choice, nowadays that's not necessarily the case. For example here's another approach.

Answer 6

This is indirect answer, on the folder structure itself, very related.

A few years ago I had same question, took a folder structure but had to do a lot directory moving later on, because the folder was meant for a different purpose than that I have read on internet, that is, what a particular folder does has different meanings for different people on some folders.

Now, having done multiple projects, in addition to explanation in all other answers, on the folder structure itself, I would strongly suggest to follow the structure of Node.js itself, which can be seen at: https://github.com/nodejs/node. It has great detail on all, say linters and others, what file and folder structure they have and where. Some folders have a README that explains what is in that folder.

Starting in above structure is good because some day a new requirement comes in and but you will have a scope to improve as it is already followed by Node.js itself which is maintained over many years now.

Answer 7

Just clone the repo from GitHub

https://github.com/abhinavkallungal/Express-Folder-Structure

This is a basic structure of a node.js express.js project with already setup MongoDB as database, hbs as view engine, nodemon also, so you can easily set up node js express project

Step 1: download or clone the repo
Step 2: Open in any code editor
Step 3: Open the terminal on the folder path
Step 4: run the comment in terminal npm start
Step 5: start coding