Skip to content

Instantly share code, notes, and snippets.

What would you like to do?
Anatomy of a JavaScript/Node project.

Directory structure for JavaScript/Node Projects

While the following structure is not an absolute requirement or enforced by the tools, it is a recommendation based on what the JavaScript and in particular Node community at large have been following by convention.

Beyond a suggested structure, no tooling recommendations, or sub-module structure is outlined here.


  • lib/ is intended for code that can run as-is
  • src/ is intended for code that needs to be manipulated before it can be used
  • build/ is for any scripts or tooling needed to build your project
  • dist/ is for compiled modules that can be used with other systems.
  • bin/ is for any executable scripts, or compiled binaries used with, or built from your module.
  • test/ is for all of your project/module's test scripts
  • unit/ is a sub-directory for unit tests
  • integration/ is a sub-directory for integration tests
  • env/ is for any environment that's needed for testing

lib & src

The difference in using lib vs src should be:

  • lib if you can use node's require() directly
  • src if you can not, or the file must otherwise be manipulated before use

If you are committing copies of module/files that are from other systems, the use of (lib|src)/vendor/(vendor-name)/(project-name)/ is suggested.


If you have scripts/tools that are needed in order to build your project, they should reside in the build directory. Examples include scripts to fetch externally sourced data as part of your build process. Another example would be using build/tasks/ as a directory for separating tasks in a project.


If your project/module is to be built for use with other platforms (either directly in the browser), or in an AMD system (such as require.js), then these outputted files should reside under the dist directory.

It is recommended to use a (module)-(version).(platform).[min].js format for the files that output into this directory. For example foo-0.1.0.browser.min.js or foo-0.1.0.amd.js.


The bin folder is for any system modules your package will use and/or generate.

  • The compiled node_gyp output for your module's binary code.
  • Pre-compiled platform binaries
  • package.json/bin scripts for your module

This comment has been minimized.

Copy link

@oleg-koval oleg-koval commented Mar 8, 2018

nice point about lib & src


This comment has been minimized.

Copy link

@oddlots oddlots commented Mar 14, 2018

You might also add:

  • doc/ is intended for any documentation

This comment has been minimized.

Copy link

@zvchei zvchei commented Apr 19, 2018

Great document!
Do you, by any chance, know what is the history/origin of that convention?


This comment has been minimized.

Copy link

@gerardg-dev gerardg-dev commented May 22, 2018

What about the /api and /app directories. Where should we place them?


This comment has been minimized.

Copy link

@trigunam trigunam commented Jul 27, 2018

We may need new folders to support BDD.
features/ is where all of your features files in BDD Gherkin style
step_definitions/ is where all of your step definitions are available
page_objects/ is where all of your page objects are available


This comment has been minimized.

Copy link

@perak perak commented Jul 27, 2018

/example directory for example files (npm docs: )


This comment has been minimized.

Copy link

@jolleekin jolleekin commented Sep 5, 2018

What about other files such as CSS files and font files? Should they be under lib (lib/css, lib/fonts)?


This comment has been minimized.

Copy link

@rafael-g-depaulo rafael-g-depaulo commented Sep 24, 2018

Thank you for the information! i have a personal Node.js project I've been meaning to better organize and this has helped me greatly. I still have one question specific to my problem though. If anyone more experienced with organizing projects could help me, it'd be lovely.

This project is a bot for my personal Discord server, and it has a few files I'm not sure where to put. i have a "main" index.js file, that loads up the modules i made (all in lib/), reads a file with it's key to log on, the .json's with data from the users it's interacted with, connects to the server and waits for a message. After it receives one, it sends it to the appropriate module to deal with it, and sends back any response the module told it to.

I'm just not sure where to put 'index.js', the bot info file, and the folder that contains the .json's. Should index.js go with the modules in lib/ or someplace else? should i put all of this info about the bot and it's previous interactions in a data/ folder or something like that? I'm really not sure, and even though this is just for myself and my friends, i'd like to start to do things in a more professional, organized fashion.


This comment has been minimized.

Copy link

@JulianSoto JulianSoto commented Oct 1, 2018

Where should I put .bat/.cmd files that are created by me and are needed in my app? Is /bin intended for include these files?


This comment has been minimized.

Copy link

@limitlessloop limitlessloop commented Jul 31, 2019

Is there a practice around whether you should commit build files to your repo if they are just the output of running your npm?


This comment has been minimized.

Copy link
Owner Author

@tracker1 tracker1 commented Jul 31, 2019

Wow, sorry... don't even remember writing this, lol... been a long while.

When I wrote this, was mostly considering stand alone libraries. If you're writing an application, I tend to use ./src for the app's source code... keeping most of the other conventions... for stylesheets, I tend to favor them with the components they're used with, and globals with any higher level wrapper components.

For cmd/bat files, yeah, I'd put them largely in bin or build respectively. I tend to favor using the package.json scripts section with npm, and have the respective JS files where they belong. I use shelljs a lot for command scripts.

as to BDD, /src/feature/FEATURE_SECTION is what I tend to use for applications, stand alone libraries a bit different.


This comment has been minimized.

Copy link

@DanEdens DanEdens commented Dec 17, 2019

Really happy I found this, I was doing maybe 4 of them, just by accident or logic, the same way. Now I get it right and not wonder, this is great info.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment