Folder structure for a Node.js project

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)

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/
└── ...

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.

Assuming we are talking about web applications and building APIs:

One approach is to categorize files by feature, much like what a micro service architecture would look like. The biggest win in my opinion is that it is super easy to see which files relate to a feature of the application.

The best way to illustrate is through an example:

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
  ├─ controllers
  │   ├─ booksController.js
  │   └─ authorsController.js
  │
  └─ entities
      ├─ book.js
      └─ author.js

We then add on the user and loan features:

user
  ├─ controllers
  │   └─ userController.js
  ├─ entities
  │   └─ user.js
  └─ middleware
       └─ authentication.js
loan
  ├─ controllers
  │   └─ loanController.js
  └─ entities
      └─ loan.js

And then the favorites functionality:

favorites
  ├─ controllers
  │   └─ favoritesController.js
  └─ entities
      └─ favorite.js

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.

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.