Skip to content

Instantly share code, notes, and snippets.

@tkissing

tkissing/01-directory-structure.md

Forked from tracker1/01-directory-structure.md
Last active June 28, 2016 03:36
Show Gist options
  • Star 1 You must be signed in to star a gist
  • Fork 1 You must be signed in to fork a gist
  • Save tkissing/776d13fa7fd7005d48c82460bee29264 to your computer and use it in GitHub Desktop.
Save tkissing/776d13fa7fd7005d48c82460bee29264 to your computer and use it in GitHub Desktop.
Download ZIP
Anatomy of a JavaScript/Node project.
Raw
01-directory-structure.md

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 mostly 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.

Directories

  • src/ is for the code you write manually independent of the module format
  • lib/ is for modules compiled from src/ into a format compatible with standard require in the node versions indicated by engines in your package.json (UMD, CommonJS)
  • dist/ is for modules or scripts compiled from src/ into formats not compatible with standard require in the node versions indicated by engines in your package.json (AMD, browser globals/IIFE)
  • build/ is for any scripts or tooling needed to build your project
  • 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 (tests/ is also permissable, but discouraged for new projects)
  • env/ is for any environment that's needed for testing

src vs lib vs dist

Files in dist/ and lib/ are always the result of an automated build process. Only files in src/ are edited manually. Files in lib/ are intended for consumption in node environments or by packaging tools like Browserify or Webpack. Files in dist/ are intended for consumption in environments other than node.

Please keep in mind that changing filenames is always SemVer major, changing module format almost always is (with few exceptions when the new format is some flavor of UMD that includes the previous format)

lib and dist

It is not recommended to include version numbers in the file name, as that would either require you to include all previous versions in every new build or turn every version into SemVer major because consumers need to change the file name they reference.

Unless you intend for your code to be consumed via bower, lib/ and dist/ should not be committed to git.

At any given time it should be possible to re-create lib/ and dist/ from src/ by running a single npm script from package.json

bin

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

build

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.

vendor

It is strongly recommended to pull in all dependencies via package managers (npm, bower). Manually downloading files into vendor/ comes at a significant long-term cost. If a dependency provides sufficient value and is not available via package managers, it should - license permitting - be forked and published to a private repository.

Under no circumstances should files in a vendor/ folder be edited manually.

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