# Naming

Files and directories use the kebab-case convention (e.g. this-is-the-kebab-case-convention) when it's possible and not in contradiction with another globally used convention (e.g. .circleci directory or README.md file).

# Directory structure

While the following structure is not an absolute requirement, 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.

Directory Description
src For code that needs to be manipulated before it can be used
lib For code that can run as-is
public For static assets that can be served as-is
bin For any executable scripts, or compiled binaries used with, or built from your module
dist For compiled modules that can be used with other systems
build For any scripts or tooling needed to build your project
test For all of your project/module's test scripts
env For any environment that's needed for testing
docs For any documentation
examples For any example

# src or lib directory

The difference in using src versus lib should be:

  • src if you cannot use node's require() directly, or the file must otherwise be manipulated before use
  • lib if you can use node's require() directly and the file don't need to 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.

# public directory

The public directory contain only static assets that don't need to be manipulated and that are not the result of manipulation from the src directory (e.g. bootstrap.min.css). This directory is mostly only used for HTTP servers that can serve static content via an HTTP GET request.

If you need to manipulate the assets (e.g. postCSS to css; multiple images to sprite), those "source assets" should be into the src directory and their results into the dist directory. On the build process, public directory content will be imported into the dist directory.

# bin directory

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

# build directory

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.

# dist directory

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.

# Files

# Index files

When possible, do not use index files. The name of the file should represent the content of the file and not be generic.

# Files encoding

Source files are encoded in UTF-8.

# Files extensions

Files extensions must be all lowercase, when it's possible and not in contradiction with another globally used convention.

Some file type can have more than one possible extension. To avoid use of different file extension for the same file type, use the permitted files extensions below.

File type Permitted extension
HTML .html
JPEG .jpg
JSON .json
Markdown .md
Postcss .pcss
Pug .pug
Sass .scss
TIFF .tiff
YAML .yml

# Off-side rule

Even when the language permit it, don't use off-side rule (opens new window) syntax and always use the free-form syntax. Free-form syntax prevent hard to find errors, made the auto-formating more efficiant without having to doubt about the quality of the outputed code and are easy to understand event for a junior developer.

Example in JavaScript

// bad
// Common error
if (a > b) doSomething();
doSomethingElse(); // This will be excuted even if a <= b

// good
if (a > b) {

Example in Stylus

// bad
  font: 12px Helvetica, Arial, sans-serif

  border-radius: 5px

// good
body {
  font: 12px Helvetica, Arial, sans-serif;
a.button {
  border-radius: 5px;

# Data serialization formats

When a data file can be written in multiple formats (e.g. .prettierrc can be written in JSON, YAML or TOML), always prefer the format to use in this availability order;

  1. JSON
  2. YAML
  3. TOML
  4. CSON
  5. XML

Also, if the file permit to use a special extension or none extension as well as the standardized extension, always prefer the standardized extension.

// bad - no standardized extension

// bad - must use JSON since it's available

// good

# Code formatting

Use Prettier (opens new window) for the code formatting. Prettier is an opinionated code formatter that support many languages and work with most of the code editors.

Despite the fact that Prettier offer some configuration, you must avoid at all cost to change the configuration (e.g. change the indentation rule). The only acceptable, and last resort, reason to change the configuration is for compatibility reasons.

As a developer, your time and energy are precious and better to be expensed on real problems resolving than the infinite discussion about tabulation versus space for code indentation. So, no more on-going debates over styles. 💅

# JavaScript

Follow the JavaScript Coding Guide.