Node.js project naming conventions for files & folders

Question

What are the naming conventions for files and folders in a large Node.js project?

Should I capitalize, camelCase, or under-score?

Ie. is this considered valid?

project-name
    app
        controllers
            someThings.js
            users.js
        models
                someThing.js
                user.js
        views
            some-things
                index.jade
            users
                logIn.jade
                signUp.jade
    ...

Solution 1

After some years with node, I can say that there are no conventions for the directory/file structure. However most (professional) express applications use a setup like:

/
  /bin - scripts, helpers, binaries
  /lib - your application
  /config - your configuration
  /public - your public files
  /test - your tests

An example which uses this setup is nodejs-starter.

I personally changed this setup to:

/
  /etc - contains configuration
  /app - front-end javascript files
    /config - loads config
    /models - loads models
  /bin - helper scripts
  /lib - back-end express files
    /config - loads config to app.settings
    /models - loads mongoose models
    /routes - sets up app.get('..')...
  /srv - contains public files
  /usr - contains templates
  /test - contains test files

In my opinion, the latter matches better with the Unix-style directory structure (whereas the former mixes this up a bit).

I also like this pattern to separate files:

lib/index.js

var http = require('http');
var express = require('express');

var app = express();

app.server = http.createServer(app);

require('./config')(app);

require('./models')(app);

require('./routes')(app);

app.server.listen(app.settings.port);

module.exports = app;

lib/static/index.js

var express = require('express');

module.exports = function(app) {

  app.use(express.static(app.settings.static.path));

};

This allows decoupling neatly all source code without having to bother dependencies. A really good solution for fighting nasty Javascript. A real-world example is nearby which uses this setup.

Update (filenames):

Regarding filenames most common are short, lowercase filenames. If your file can only be described with two words most JavaScript projects use an underscore as the delimiter.

Update (variables):

Regarding variables, the same "rules" apply as for filenames. Prototypes or classes, however, should use camelCase.

Update (styleguides):

• https://github.com/feross/standard
• https://github.com/airbnb/javascript

Solution 2

Use kebab-case for all package, folder and file names.

Why?

You should imagine that any folder or file might be extracted to its own package some day. Packages cannot contain uppercase letters.

New packages must not have uppercase letters in the name. https://docs.npmjs.com/files/package.json#name

Therefore, camelCase should never be used. This leaves snake_case and kebab-case.

kebab-case is by far the most common convention today. The only use of underscores is for internal node packages, and this is simply a convention from the early days.

Solution 3

There are no conventions. There are some logical structure.

The only one thing that I can say: Never use camelCase file and directory names. Why? It works but on Mac and Windows there are no different between someAction and some action. I met this problem, and not once. I require'd a file like this:

var isHidden = require('./lib/isHidden');

But sadly I created a file with full of lowercase: lib/ishidden.js. It worked for me on mac. It worked fine on mac of my co-worker. Tests run without errors. After deploy we got a huge error:

Error: Cannot find module './lib/isHidden'

Oh yeah. It's a linux box. So camelCase directory structure could be dangerous. It's enough for a colleague who is developing on Windows or Mac.

So use underscore (_) or dash (-) separator if you need.

Solution 4

Based on 'Google JavaScript Style Guide'

File names must be all lowercase and may include underscores (_) or dashes (-), but no additional punctuation. Follow the convention that your project uses. Filenames’ extension must be .js.

Solution 5

Node.js doesn't enforce any file naming conventions (except index.js). And the Javascript language in general doesn't either. You can find dozens of threads here which suggest camelCase, hyphens and underscores, any of which work perfectly well. So its up to you. Choose one and stick with it.

View more solutions

Comments

[Chad]

Highly subjective, your directory structure is your own. Personally I like to camelCase since that is what I do in JS

[Rudiger]

@Chad - in Node.js, require takes the directory string as a parameter, which is why it's not entirely your own. ie. require('../app/controllers/someThings');

[Jonathan Lonowski]

Node doesn't specify any suggestions or standards for naming modules, just as long as they're valid file/directory names and don't try to override core module names. For its own modules, it uses a mixture of abbreviated (fs), single-word (events), underscored (child_process), and lowercase (querystring).

[Chad]

@Rudiger So? You can specify whatever string you want, and directory structure you want you can have (provided your names are valid file names of course).

[Charles Ferentchak]

From what I can tell from poking around the more keystone projects like mocha file names like captain-awesome-file.js seem to be common enough. That's what I am going to use at least!

[moka]

It is not actually what node 'enforces', please read this: nodejs.org/api/modules.html#modules_folders_as_modules

[Mathieu Amiot]

Some projects, such as Locomotive.js are using camelCase for controller files. :-) Just depends. I tend to use PascalCase for class-like files.

[gumaflux]

@yitsushi seems to raise quite a concern with camel (and pascal) case naming, if you want to create portable modules camel case surely seems a bad idea?

[Tronix117]

How interesting and well done is your answer, it's off topic, the topic creator specifically asked for naming convention not for directory structures. When we get to this topic, we expect to know if files are better named with dashes, underscores or camelCase. I will upvote, if this is added to this answer.

[bodokaiser]

@Tronix117 what is the problem? The question asks for "project naming conventions for files & folders?" and naming is not limited to the file name as it also includes the complete path name.

[Tronix117]

of course, but the author specifically ask "Should I capitalize, camelCase, or under-score?". When he write his exemple, he explicitly put 'someThings' and 'some-things' just to know if it can be considered as valid. When I went to this topic I was expecting to have the answer to this specific question, and to know what is usually used as file naming. I don't say your answer is wrong, it's perfect for its purpose, but incomplete in my mind because he doesn't really answer the main question.

[bodokaiser]

Then don't complain at me but at the title of this question. He marked my answer as correct and did not ask for more details so I see that his question details are wrong. What you do is in my opinion just spreading hate :) - thanks for the down vote

[Tronix117]

I think you misunderstood me ;). I was just looking for something that I didn't found on the accepted answer, but was specifically asked, not spreading hate in any kind, you're going a bit far on this one. I just wanted you to add some informations about that on the answer, so that people who will look for that in the future will not get in a dead-end.

[max]

+1, add the fact that renaming case-sensitive folders in git on a non-cs system is a real hassle.

[Mike]

I don't really understand the problem with camelCase here. Wouldn't the issue be resolved by naming the file correctly in the first place (lib/isHidden.js)?

[tempranova]

Hey Mike, the point is that camelCase is going to break on deployment on some systems. I was confused about why my directories were all getting 404s when I deployed from Mac onto a Linux box with a package named "groupPages". I had to change to group-pages to fix things.

[L0LN1NJ4]

Worse yet: create a camelcase version of a file name and have a careless colleague create a lowercase version in the same directory. Now do a check out in a non-case-sensitive os, and try to figure out why the hell your application isn't working. And yes, this happened.

[Swivel]

@Tronix117 Actually, this is specifically why I found myself on this page reading this answer. I was hoping for not only directory structure, but more importantly name conventions (dashes, underscores, camelCase, TitleCase, etc...). Unfortunately, the answer still does not contain it, and it seems bodokaiser is taking things too personally for me to jump in and request that his opinion regarding this be added to his answer (as the OP initially asked in their question) (cough cough).

[bodokaiser]

@Swivel is this better?

[Swivel]

@bodokaiser Yes. Thank you!

[jayrue]

Hi, I just want to say I found this answer very helpful and it has pushed me in the right direction. I have started my own project tonight using this format and appreciate the additional links. I am somewhat confused about the /lib/static/index.js however... Could someone please help me understand what its doing? I googled node decoupling but its putting me on to some package called broadway... Any insight appreciated and thanks again to @bodokaiser :)

[bodokaiser]

@jayrue thank you for your feedback! I place the static file serving middleware at /lib/static/index.js but feel free to place it somewhere else if it is just a one-lines like app.use(static()).

[jayrue]

Thanks so much for the response! So basically is the idea for all the middleware to live in config/index.js and then static/index.js just loads it all in? What exactly is the advantage to doing it like this, is it just for reasons of modularization? This is my first Node project ever and I would really like to follow best practices. Thanks again for your reply. Also, should I put a require in lib/index.js for static/index.js

[bodokaiser]

@jayrue Not directly. Best you checkout one of my example repositories github.com/bodokaiser/nearby/blob/master/lib/index.js good luck!

[ctrlplusb]

For the lazy, quick link the AirBnB style guide section relating to naming (the file naming conventions are towards the end of the section) - github.com/airbnb/javascript#naming-conventions

[DiPix]

What about jade files? Also under-score.jade ?

[Dragan Nikolic]

I like this answer, however I want to point that dash (-) may have some problems too. For example, using Nighwatch test framework I created a page object named admin-login.js. Then I tried to access it from the test script using const loginPage = browser.page.admin-login(). I got error ReferenceError: login is not defined. Using underscore (_) for the file name solved the problem. I can also imagine that using filenames with dash character in command line can also lead to some problems. Therefore, I'd say that underscore is safest separator for file names in general.

[Nick]

As pedantic as I am, I choose to use all lowercase for file names so that I don't run into issues like these. Also, at times I waste time trying to recall if a conjunction was lowercase or camelcase, etc. In addition, it helps with larger teams. The other option is to name the file the same as the class name, but it's hard to prevent inconsistencies there.

[Carsten Führmann]

I think the recommendation for variable names should be removed from the answer, not so much because it wasn't asked in the question, but because even the Node.js documentation uses lower camel case for variables.

[Jamie Pate]

const loginPage = browser.page['admin-login']() obviously for corner cases where you have to reference the filename directly as an object property

[Roee]

you forgot dot? like socket.io

[xdevs23]

The problem isn't really camelCase by itself but rather that on Windows (and on macOS depending on how your filesystem is set up) file names are case-insensitive which means you can use either case and it will still find the file. On case-sensitive file systems like the ones commonly used for Linux distributions (and other un*x systems in general) like ext4 you have to use the exact file name as it is on the file system.

[rob2d]

.2c, could do a simple automation from kebab-case to kebabCase in any script or app in any language using regex -- do it all the time 🙃

[Rong.l]

I had met this problem before either. Errors occured when we migrated app with folder named by camelCase from CentOS to Windows Server. After that point, I always use lowercase for folder's name.

[Manohar Reddy Poreddy]

For test file names, use *.test.js (preferred), or *.spec.js or *.test.txt (if text file). I will upvote after you add the files names like this too.

[dustytrash]

node_modules is the reason I'll stick with snake case.

[wongz]

@bodokaiser do you have any guidance on route names. Say there's a GET POST DELETE route of the same name user for example. How would you name those files differently?

[ban_javascript]

@bodokaiser Wow, I really love this directory structure, and I've been using it in my projects. Is there anywhere you would put user-submitted data, or logs?

[Spenhouet]

@dustytrash There are other common files which use the kebab-case like package-lock.json or service-worker.ts.

[onuriltan]

Exactly, the only thing I do not like about kebab case is when I edit the file name, if I double click, it does not select all the file name, so maybe snake case is good, all about preference ofcourse

[khaki]

@onuriltan You can use ctrl+a to select the whole file name

[onuriltan]

@khaki Yes, thats a good tip!

[conny]

This idea of multiple dots is worth taking a closer look at: since we do not need to specify the file ending for require("something"), we can create our own app- or framework-specific naming convention for what to put after the first period: in the example const login = require("login.view") can emphasize that the default export of that file is probably a View-shaped object. I like this, perhaps it can save a few levels of subdirectories too.