Awesome

import JavaScript from 'Shopify'

This repository contains everything you should need for writing JavaScript at Shopify. In it you’ll find such things as our linting configs, custom linting rules, and project generators. Below, you’ll find the most important thing: a living styleguide documenting how and why we write JavaScript the way we do.

Why? All code in any code-base should look like a single person typed it, no matter how many people contributed. If we all follow along with the rules detailed below, we can focus our efforts on more meaningful problems.

Table of contents

1. Using this guide
2. Naming
3. Punctuation
4. Whitespace
5. References
6. Control flow
7. Objects
8. Arrays
9. Strings
10. Functions
11. Types and casting
12. ESNext features
13. Project structure
14. Resources

In addition to the above, we have created a specific guide for the tools and conventions surrounding JavaScript testing: our Testing styleguide. There are also a few additional guides for libraries commonly used at Shopify:

• jQuery styleguide
• React styleguide

Have a legacy codebase? Can’t use ESNext? Our legacy styleguide is available in this repo just for you. We also have a dedicated CoffeeScript styleguide for projects that are still using CoffeeScript (new projects should use ESNext, though!).

Using this guide

Many of the following rules are enforced by our shared ESLint config/plugin, which you can use in most editors and CI environments. To use it, you will need to have Node.js >=5.7.0 and Yarn installed. As an alternative to Yarn, you can use npm which ships with Node.js.

Once these are installed, you must then install ESLint and the Shopify plugin:

With Yarn

yarn add --dev eslint eslint-plugin-shopify

With npm

npm install eslint eslint-plugin-shopify --save-dev

Once these are installed, you will need to add an ESLint configuration in your project’s package.json.

{
  "eslintConfig": {
    // or "plugin:shopify/es5" for the ES5 config, "plugin:shopify/react" for the React config.
    "extends": "plugin:shopify/esnext",
    // choose your environments: http://eslint.org/docs/user-guide/configuring.html#specifying-environments
    "env": {}
  }
}

Note: you can also provide an array of configurations, if you want to have linting rules for tools like lodash. See the eslint-plugin-shopify repo for details.

You can now use ESLint. The easiest way to do this is by adding a linting script to your package.json:

{
  "scripts": {
    "lint": "eslint . --max-warnings 0"
  }
}

And, finally, run your new script:

With Yarn

yarn run lint

With npm

npm run lint

Naming

• 2.1 <a name="2.1"></a> Use camelCase when naming functions, objects, and instances. Snake case is acceptable when interacting with an external API that provides objects with snake-cased keys, like Rails.

  ESLint rule: camelcase

  // bad
  const bad_snake_name = 'Larry';
  const BADname = 'this';
  const badObject = {some_prop: 'some-value'};
  
  // good
  const goodSnakeName = 'Basilisk';
  const prettyName = 'this';
  const goodObject = {someProp: 'some-value'};
  
  // not ideal, but sometimes necessary and acceptable
  const objectProvidedByRails = {some_rails_provided_prop: 'some-value'};
  

• 2.2 <a name="2.2"></a> Use PascalCase when naming classes, factories, enumerations, or singletons (cases of enums are written in screaming snake case).

  ESLint rule: new-cap

  // bad
  class badClass {}
  const bad = new badClass();
  
  const badType = {
    Water: 0,
    Fire: 1,
    Ghost: 2,
  };
  
  // good
  class GoodClass {}
  const good = new GoodClass();
  
  const Type = {
    WATER: 0,
    FIRE: 1,
    GHOST: 2,
  };
  

• 2.3 <a name="2.3"></a> Use a leading underscore when naming "private" properties. Functions and variables in scope should be named normally.

  Why? The leading underscore sends a signal to other developers that these methods should not be called or relied upon. Some tools can also obfuscate methods with leading underscores to ensure that they are not called by outside objects. Items in scope but not exported are completely private, so no signaling is required for these.

  Note: Use these underscore-prefixed members as a last resort. Prefer moving them to be functions/ variables in scope or making them part of the public API over using this naming convention.

  ESLint rule: no-underscore-dangle

  // bad
  export const bad = {
    __privateOne__: 0,
    privateTwo_: 1,
  };
  
  function _badPrivateFunctionInScope() {}
  
  // good
  export const good = {
    _private: 0,
  };
  
  function goodPrivateFunctionInScope() {}
  

• 2.4 <a name="2.4"></a> Avoid single letter names; be descriptive with the names you choose. Note that exceptions can be made for common one-letter identifiers, particularly for use as properties (x, y, i, j, _).

  ESLint rule: id-length

  // bad
  const b = 'BAD';
  
  // good
  const good = 'GOOD';
  const point = {
    x: 10,
    y: 20,
  };
  

• 2.5 <a name="2.5"></a> Don’t save references to this. Use an arrow function (preferred) or function#bind instead.

  // bad
  const badObject = {
    logSelfAfterTimeout() {
      const that = this;
      setTimeout(function() {
        console.log(that);
      }, 500);
    }
  }
  
  // better
  const betterObject = {
    logSelfAfterTimeout() {
      setTimeout(function() {
        console.log(this);
      }.bind(this), 500);
    }
  }
  
  // best
  const bestObject = {
    logSelfAfterTimeout() {
      setTimeout(() => console.log(this), 500);
    }
  }
  

• 2.6 <a name="2.6"></a> When naming an event object, use evt (as opposed to e or event).

  // bad
  function badHandleClickOne(e) {}
  function badHandleClickTwo(event) {}
  
  // good
  function goodHandleClick(evt) {}
  

↑ scrollTo('#table-of-contents')

Punctuation

• 3.1 <a name="3.1"></a> Always use semicolons.

  ESLint rules: semi and class-property-semi

  // bad
  function bad() {
    const badChoice = 'No semicolons'
    return badChoice
  }
  
  // good
  function good() {
    const goodChoice = 'Semicolons';
    return goodChoice;
  }
  

• 3.2 <a name="3.2"></a> Do not use leading commas.

  Why? It’s difficult to interpret and format, and trailing commas are a better solution to the same problems.

  ESLint rule: comma-style

  // bad
  const badOne = {
      one: 1
    , two: 2
    , three: 3
  };
  
  const badTwo = [
      1
    , 2
    , 3
  ];
  
  // good
  const goodOne = {
    one: 1,
    two: 2,
    three: 3,
  };
  
  const goodTwo = [
    1,
    2,
    3,
  ];
  

• 3.3 <a name="3.3"></a> Objects and arrays should use trailing commas, unless they are on a single line. Commas should always be followed by a space, but never preceded by one.

  Why? Trailing commas allow you to add and remove a given property of an object without also editing the surrounding lines, which keeps the change isolated to the property in question.

  Note: trailing commas are not permitted in JSON, so be sure to omit them.

  ESLint rules: comma-dangle, comma-spacing

  // bad
  const badOne = {
    foo: 1,
    bar: 2
  };
  
  const badTwo = {foo: 1, bar: 2,};
  
  const badThree = [
    1,
    2
  ];
  
  const badFour = [1,2];
  
  // good
  const good = {
    foo: 1,
    bar: 2,
  };
  
  const goodTwo = {foo: 1, bar: 2};
  
  const goodThree = [
    1,
    2,
  ];
  
  const goodFour = [1, 2];
  

• 3.4 <a name="3.4"></a> Never use commas to separate multiple statements.

  ESLint rule: no-sequences

  let a;
  
  // bad
  while (a = something(), a != null && a.length !== 0) {
    // do something
  }
  
  // good
  while (a = something()) {
    if (a.length === 0) { break; }
  }
  

↑ scrollTo('#table-of-contents')

Whitespace

• 4.1 <a name="4.1"></a> In general, add whitespace to improve legibility of code and to group statements together in a way that will produce a more coherent “story” for the next developer to look at code. Never optimize for code size: minifiers will do a much better job than you ever could.

• 4.2 <a name="4.2"></a> Use two spaces for indentation.

  ESLint rule: indent

  // bad
  function badOne() {
  ∙∙∙∙return true;
  }
  
  function badTwo() {
  ∙return true;
  }
  
  // good
  function good() {
  ∙∙return true;
  }
  

• 4.3 <a name="4.3"></a> Use braces for all blocks, including those that are on a single line.

  Why? Requiring braces prevents issues when a second statement is added to a single-line block.

  ESLint rule: curly

  const condition = true;
  
  // bad
  if (condition) doSomething();
  if (condition)
    doSomething();
    doSomethingElse(); // will run even if condition is false!
  
  // good
  if (condition) { doSomething(); }
  if (condition) {
    doSomething();
    doSomethingElse();
  }
  

• 4.4 <a name="4.4"></a> Place one space before a leading brace. When using if-else and try-catch constructs, the second part starts on the same line as the closing brace of the first, with a single space between them.

  ESLint rules: brace-style, space-before-blocks

  // bad
  function bad()
  {
    doSomething();
  }
  
  if (condition){ doSomething(); }
  
  if (otherCondition) {
    doSomething();
  }
  else {
    doSomethingElse();
  }
  
  // good
  function good() {
    doSomething();
  }
  
  if (condition) { doSomething(); }
  
  if (otherCondition) {
    doSomething();
  } else {
    doSomethingElse();
  }
  

• 4.5 <a name="4.5"></a> Place one space before the opening parenthesis in control statements (if, while, etc). Place no space between the function name and argument list in function calls and declarations.

  ESLint rule: keyword-spacing

  // bad
  if(condition) {
    doSomething ();
  }
  
  function doSomething () {}
  
  // good
  if (condition) {
    doSomething();
  }
  
  function doSomething() {}
  

• 4.6 <a name="4.6"></a> All operators should be surrounded by spaces.

  ESLint rule: space-infix-ops

  // bad
  const bad=34+32;
  
  // good
  const good = 1 + 2;
  

• 4.7 <a name="4.7"></a> End files with a single newline character. Avoid any end-of-line whitespace.

  ESLint rules: eol-last, no-trailing-spaces

  // bad-one.js
  const bad = true;
  

  // bad-two.js
  const bad = true;↵
  ↵
  

  // bad-three.js
  const bad = true;∙∙↵
  

  // good.js
  const good = true;↵
  

• 4.8 <a name="4.8"></a> Use indentation when dealing with long method chains. Use a leading dot on each new line.

  Why? Breaking a method chain across lines improves readability. The leading dot clearly emphasizes that this is a method call, not a new statement.

  ESLint rules: dot-location, newline-per-chained-call

  const result = [1, 2, 3, 4, 5].filter((x) => x > 2).map((x) => x * x * x).reduce((total, x) => total + x, 0);
  
  // good
  const result = [1, 2, 3, 4, 5]
    .filter((x) => x > 2)
    .map((x) => x * x * x)
    .reduce((total, x) => total + x, 0);
  

• 4.9 <a name="4.9"></a> Do not include extra space inside parentheses, brackets, or curly braces that define an object literal. Include spaces for curly braces that define a single-line function.

  ESLint rules: space-in-parens, array-bracket-spacing, object-curly-spacing

  // bad
  function badFunction( arg ) {return true;}
  
  const badObject = { isBad: true };
  badObject[ 'isBad' ];
  
  const badArray = [ 1, 2, 3 ];
  
  // good
  function goodFunction(arg) { return true; }
  
  const goodObject = {isGood: true};
  goodObject['isGood'];
  
  const goodArray = [1, 2, 3];
  

• 4.10 <a name="4.10"></a> Limit the number of statements on a single line to improve readability.

  ESLint rule: max-statements-per-line

  // bad
  function bad() { dont = 'do this'; return please; }
  
  // good
  function good() {
    doThis = true;
    return thanks;
  }
  
  // fine as well, as long as there is only one, short statement.
  function fine() { return 'but don’t push it!'; }
  

• 4.11 <a name="4.11"></a> Line comments should appear above the line they are commenting, rather than at the end of the line or below it.

  Why? End-of-line comments can be harder to read since they lead to longer lines. Comments above the line you are documenting provides a more natural experience when reading the code, as it follows how we typically read other forms of text.

  ESLint rule: line-comment-position

↑ scrollTo('#table-of-contents')

References

• 5.1 <a name="5.1"></a> Always use let or const (as described in the following rule) to declare variables. Forgetting to do so will result in global variables, which is bad news.

  ESLint rule: no-undef

  // bad
  bad = BadChoice();
  
  // good
  const good = GoodChoice()
  

• 5.2 <a name="5.2"></a> Use const for all references that do not need to be re-assigned. Use let only for references that will be re-assigned. Never use var.

  Why? const and let are block scoped, rather than being function-scoped like var. const indicates that a given reference will always refer to the same object or primitive throughout the current scope, which makes code easier to reason about.

  ESLint rules: prefer-const, no-const-assign, no-var

  // bad
  var CONSTANT_VALUE = 1;
  var count = 0;
  if (true) {
    count += 1;
  }
  
  // good
  const someUnchangingReference = 1;
  let count = 0;
  if (true) {
    count += 1;
  }
  

• 5.3 <a name="5.3"></a> Initialize variables on declaration as often as possible. If a variable has no value until a later point (for example, it is calculated inside a complex conditional expression, or it is a variable in scope that is redeclared for each unit test), you can declare a variable without initialization.

  ESLint rule: init-declarations

  // bad
  let bad = null;
  // ...
  bad = 'bad';
  
  // good
  const goodOne = 'good';
  
  // or, if you can't provide a value immediately:
  let goodTwo;
  // ...
  goodTwo = 'good';
  

• 5.4 <a name="5.4"></a> don’t refer a reference before it is defined. The only exception to this rule is for functions; use the hoisting feature of functions liberally to allow the primary export of a file to appear first (and any helper or utility functions it uses to appear afterwards).

  ESLint rule: no-use-before-define

  // bad
  function bad() {
    return badVar;
  }
  
  const badVar = true;
  
  // good
  const goodVar = true;
  
  function good() {
    return goodVar;
  }
  

• 5.5 <a name="5.5"></a> Use screaming snake case for file-level constants to make it clear to users that they can’t be modified.

  // bad
  const constantValue = 1;
  
  // good
  const CONSTANT_VALUE = 1;
  

• 5.6 <a name="5.6"></a> Declare each variable on its own line; never comma-separate your variables on a single line.

  Why? Listing all variables on a single line makes it harder to scan, and encourages creating too many local variables.

  ESLint rule: one-var.

  // bad
  const badFooOne = 'bar', badBazOne = 'qux';
  const badFooTwo = 'bar',
      badBazTwo = 'qux';
  
  // good
  const goodFoo = 'bar';
  const goodBaz = 'qux';
  

• 5.7 <a name="5.7"></a> Never shadow variable names from outer scopes. Avoid shadowing of names with special meaning, like arguments.

  Why? It makes the code harder to reason about because the purpose of a given variable changes with the scope, and introduces the opportunity for subtle bugs by assigning to the variable when you meant to redeclare it.

  ESLint rules: no-shadow, no-shadow-restricted-names

  // bad
  function bad() {
    const arguments = [];
    const foo = true;
  
    runCallback(() => {
      const foo = false;
      return true;
    });
  
    // what is `foo`?
  }
  
  // good
  function good() {
    const args = [];
    const foo = true;
  
    runCallback(() => {
      const callbackFoo = false;
      return false;
    });
  }
  

• 5.8 <a name="5.8"></a> For a given section of code for which you are defining variables (typically, at the top of a block), group all const declarations that apply to that entire scope, then group all let declarations that apply to the entire scope.

  Why? It is easier to see all variables that are used, and whether they are able to be re-assigned or not.

  // bad
  let i = 0;
  const FOO = true;
  const bar = 'bar';
  someUnrelatedCall();
  const BAZ = false;
  
  // good
  const FOO = true;
  const BAZ = false;
  const bar = 'bar';
  let i = 0;
  
  someUnrelatedCall();
  

• 5.9 <a name="5.9"></a> Assign variables at the point that you actually need them; that is, variables need not all be declared at the top of a given scope.

  // bad
  function checkName(hasName) {
    const name = getName(); // unnecessary function call if `hasName` is `false`
    if (!hasName) { return false; }
    return name.length > 0;
  }
  
  // good
  function checkName(hasName) {
    if (!hasName) { return false; }
    const name = getName();
    return name.length > 0;
  }
  

↑ scrollTo('#table-of-contents')

Control flow

• 6.1 <a name="6.1"></a> Never allow fallthrough in switch statements.

  ESLint rule: no-fallthrough

  // bad
  switch (badVar) {
  case 1:
    doSomething();
  case 2:
    doSomethingElse();
  }
  
  // good
  switch (goodVar) {
  case 1:
    doSomething();
    break;
  case 2:
    doSomethingElse();
    break;
  }
  

• 6.2 <a name="6.2"></a> Never use labels or the with statement.

  ESLint rules: no-labels, no-with

  Why? Using labels is generally indicative of code that is overly complex. The with statement makes it difficult for the reader to determine whether a given binding exists and, if it exists, in which scope or object it will be found. It is also not allowed in strict mode.

• 6.3 <a name="6.3"></a> Never perform assignment in a condition.

  Why? It can easily create confusion as to whether this was intended or was meant to be a comparison operation.

  ESLint rule: no-cond-assign

  
  // bad (did you mean `==`/ `===`?)
  let myVar;
  if (myVar = doSomething()) {}
  
  // good
  const myVar = doSomething();
  if (myVar) {}
  

• 6.4 <a name="6.4"></a> Never have only a single if block within an else block; combine these into an else if block (or, if returning in the if block, as another if block).

  ESLint rule: no-lonely-if

  // bad
  if (conditionOne) {
    return 'Matched One!';
  } else {
    if (conditionTwo) {
      return 'Matched Two!';
    }
  }
  
  // better
  if (conditionOne) {
    return 'Matched One!';
  } else if (conditionTwo) {
    return 'Matched Two!';
  }
  
  // best
  if (conditionOne) {
    return 'Matched One!';
  }
  
  if (conditionTwo) {
    return 'Matched Two!';
  }
  

• 6.5 <a name="6.5"></a> Never nest ternary expressions. When such a complex calculation exists, it is usually best to break it into steps or to use a helper function to calculate the value.

  Why? They produce incredibly hard to read code.

  ESLint rule: no-nested-ternary

  // bad
  const bad = someCondition ? (someOtherCondition ? 'foo' : 'bar') : (someFinalCondition ? 'baz' : 'qux');
  
  // good
  function calculateGood(someCondition, someOtherCondition, someFinalCondition) {
    if (someCondition) {
      return someOtherCondition ? 'foo' : 'bar';
    } else {
      return someFinalCondition ? 'baz' : 'qux';
    }
  }
  
  const good = calculateGood(someCondition, someOtherCondition, someFinalCondition);
  

• 6.6 <a name="6.6"></a> Don’t nest an entire function body inside a conditional. Instead, return early using the opposite of the conditional.

  Why? This reduces indentation and makes the code easier to read.

  ESLint rule: prefer-early-return

  // bad
  function badFunc() {
    if (something) {
      doThis();
      andThat();
    }
  }
  
  // good
  function goodFunc() {
    if (!something) { return; }
    doThis();
    doThat();
  }
  

↑ scrollTo('#table-of-contents')

Objects

• 7.1 <a name="7.1"></a> Use object literal syntax for object creation. Use Object.create in order to define objects with more complex property descriptors, or to set the object’s prototype.

  ESLint rule: no-new-object.

  // bad
  const badOne = new Object();
  
  const badTwo = {};
  Object.setPrototypeOf(badTwo, badOne);
  
  const badThree = {};
  Object.defineProperty(badThree, 'prop', {value: 10, enumerable: false});
  
  // good
  const goodOne = {};
  const goodTwo = Object.create(goodOne);
  const goodThree = Object.create({}, {
    value: 10,
    enumerable: false,
  });
  

• 7.2 <a name="7.2"></a> Never include spaces before the colon in an object literal property declaration. Use one space after the colon or, if it improves readability to align values, indent the fewest number of spaces after the colon to align the values.

  // bad
  const badOne = {
    foo : 1,
    bar:   2,
  };
  
  const badTwo = {
    short        : 3,
    longProperty : 4,
  };
  
  // good
  const goodOne = {
    foo: 1,
    bar: 2,
  };
  
  const goodTwo = {
    short:        3,
    longProperty: 4,
  };
  

• 7.3 <a name="7.3"></a> Objects that span multiple lines should have one property per line with each property indented by one level. The closing brace should be on its own line, aligned with the column of the line on which the opening brace appeared.

  ESLint rules: indent and object-curly-newline

  // bad
  const badOne = {
    foo: 1, bar: 2,
  };
  
  const badTwo = {
      baz: 3, }
  
  // good
  
  const goodOne = {
    foo: 1,
    bar: 2,
  };
  
  const goodTwo = {
    baz: 3,
  };
  

• 7.4 <a name="7.4"></a> Single-line object literals are permissible, but beware objects with more than a few, short keys: they can quickly become unreadable. Object literals on a single line should not have any spaces after the opening brace or before the closing brace.

  Why? Objects on a single line use no interior spaces to differentiate them from functions (particular arrow functions) on a single line (which should have interior spaces between braces, if present).

  ESLint rules: object-curly-spacing, brace-style

  // bad
  const badOne = { foo: 1 };
  const badTwo = {bar: 2, baz: 3, qux: 4, manyMoreKeys: 5, evenMoreNowItGetsHardToRead: 6};
  
  // good
  const goodOne = {foo: 1};
  const goodTwo = {
    bar: 2,
    baz: 3,
    qux: 4,
    manyMoreKeys: 5,
    evenMoreNowItGetsHardToRead: 6,
  };
  

• 7.5 <a name="7.5"></a> Use object method and property shorthands.

  Why? It is shorter and removes visual noise for objects with many properties and methods.

  ESLint rule: object-shorthand

  const name = 'Fido';
  
  // bad
  const bad = {
    name: name,
    action: function() {
      return 'bite';
    },
  }
  
  // good
  const good = {
    name,
    action() {
      return "bark";
    },
  };
  

• 7.6 <a name="7.6"></a> Use computed property names (unless using Flow, which does not support these yet).

  Why? It allows you to define all properties in one place, and mirrors the way you would access those properties.

  const propertyName = 'foo';
  
  // bad
  const bad = {};
  bad[propertyName] = true;
  
  // good
  const good = {
    [propertyName]: true,
  };
  

• 7.7 <a name="7.7"></a> Use dot notation when possible. Use subscript notations ([]) only when your key is not a valid identifier or the key is stored in a variable.

  const obj = {fooBar: 1, 'baz-qux': 2};
  
  // bad
  const fooBar = obj['fooBar'];
  
  // good
  const fooBar = obj.fooBar;
  const bazQux = obj['baz-qux'];
  
  const bazKey = 'baz-qux'
  const altBazQux = obj[bazKey];
  

• 7.8 <a name="7.8"></a> When using object literals, place computed properties first, non-function properties second, and function properties third.

  Why? It’s easier to see which properties are using shorthand, and will generally result in increasing line length of property declarations (which is easier to scan than random line lengths).

  const propertyOne = 1;
  function propertyTwo() {};
  
  // bad
  const bad = {
    doSomethingWithProperties() {},
    propertyOne,
    propertyThree: 3,
    propertyTwo,
  };
  
  // good
  const good = {
    propertyOne,
    propertyTwo,
    propertyThree: 3,
    doSomethingWithProperties() {},
  }
  

• 7.9 <a name="7.9"></a> Only quote properties that are invalid identifiers.

  Why? It’s easier to read properties, matches well to how we encourage Ruby hashes with symbols to be written, and encourages you use camelCased, valid identifiers.

  ESLint rule: quote-props

  // bad
  const bad = {
    'foo': 1,
    'bar': 2,
    'some-invalid-identifier': 3,
  };
  
  // good
  const good = {
    foo: 1,
    bar: 2,
    'some-invalid-identifier': 3,
  };
  

↑ scrollTo('#table-of-contents')

Arrays

• 8.1 <a name="8.1"></a> Always use literal syntax for array creation.

  ESLint rule: no-array-constructor

  // bad
  const bad = new Array();
  
  // good
  const good = [];
  

• 8.2 <a name="8.2"></a> Do not insert spaces on the inside of array literals on a single line. Indent every item of an array literal that spans multiple lines by two spaces, and align the closing bracket to the column of the line that contains the opening bracket. If your array spans multiple lines, place only one item per line.

  Why? These stylistic choices make array and object literal declarations visually consistent with one another.

  ESLint rule: array-bracket-spacing

  // bad
  const badOne = [ 1, 2 ];
  const badTwo = [
    3,
    4, 5,
    ]
  
  // good
  const goodOne = [1, 2];
  const goodTwo = [
    3,
    4,
    5,
  ];
  

• 8.3 <a name="8.3"></a> Use Array#push instead of direct assignment to add items to an array.

  const myArray = [];
  
  // bad
  myArray[myArray.length] = 'bad';
  
  // good
  myArray.push('good');
  

• 8.4 <a name="8.4"></a> Use the spread syntax (...) to copy arrays, rather than iterating over the array or using Array#slice. If you need subsections of the array, continue to use Array#slice.

  const originalArray = [1, 2, 3];
  
  // bad
  const badNewArray = [];
  originalArray.forEach((item) => badNewArray.push(item));
  const otherBadNewArray = originalArray.slice();
  
  // good
  const goodNewArray = [...originalArray];
  

• 8.5 <a name="8.5"></a> To convert from an object that is iterable to an array (for example, a NodeList returned by document.querySelectorAll, or a jQuery object), use the spread syntax (...). For objects without an iteration protocol, continue to use Array.from.

  const nodes = document.querySelectorAll('.my-nodes');
  
  // bad
  const badNodesArray = Array.from(nodes);
  
  // good
  const goodNodesArray = [...nodes];
  

↑ scrollTo('#table-of-contents')

Strings

• 9.1 <a name="9.1"></a> Use single quotes for strings. Using double quotes is acceptable only to avoid escaping contained single quotes.

  Why? We don’t want to argue about this. Like, ever. Please use single quotes!

  ESLint rule: quotes

  // bad
  const badOne = "Sorry not sorry";
  const badTwo = `No interpolation, no need`;
  const badThree = 'Escaping is \'no good\'';
  
  // good
  const goodOne = 'Nice and clean';
  const goodTwo = 'No interpolation, no backticks';
  const goodThree = "Double quotes are 'fine' in this case.";
  

• 9.2 <a name="9.2"></a> Avoid long strings if possible. If you must include a long string, you can include multiline strings in code using backticks (`). If the whitespace of multiline strings is unacceptable, you can use multiline string concatenation or an array of reasonable-length strings joined together.

  // bad
  const badString = 'The path of the righteous man is beset on all sides by the iniquities of the selfish and the tyranny of evil men. Blessed is he who, in the name of charity and good will, shepherds the weak through the valley of darkness'
  
  // fine, if newlines are acceptable
  const fineString = `
    The path of the righteous man is beset on all sides by the iniquities of the selfish and the tyranny of evil men.
    Blessed is he who, in the name of charity and good will, shepherds the weak through the valley of darkness
  `;
  
  // good
  const goodString = 'The path of the righteous man is beset on all sides ' +
    'by the iniquities of the selfish and the tyranny of evil men. ' +
    'Blessed is he who, in the name of charity and good will, ' +
    'shepherds the weak through the valley of darkness';
  

• 9.3 <a name="9.3"></a> Use template strings instead of concatenation. When embedding expressions in the template strings, never include spaces within the curly braces.

  Why? The template string syntax is easier to read and consistent with how we build strings programatically in other languages.

  ESLint rules: prefer-template, template-curly-spacing

  const name = 'Chris';
  
  // bad
  const badOne = 'DO NOT do it this way, ' + name + '!';
  const badTwo = ['And definitely not this way, either, ', name, '!'].join('');
  const badThree = `So close, ${ name }, but so far!`;
  
  // good
  const goodOne = `Much better, ${name}!`;
  

↑ scrollTo('#table-of-contents')

Functions

• 10.1 <a name="10.1"></a> Never use the Function constructor to create a new function. Similarly, never use eval.

  Why? Creating a function in this way evaluates the string as-is, allowing for vulnerabilities and making code harder to test.

  ESLint rules: no-new-func, no-eval, no-implied-eval

  // bad
  const add = new Function('a', 'b', 'return a + b');
  

• 10.2 <a name="10.2"></a> Use function declarations instead of function expressions.

  Why? Function declarations are named, so they’re easier to identify in call stacks. Also, the whole body of a function declaration is hoisted, whereas only the reference of a function expression is hoisted. This rule makes it possible to always use Arrow Functions in place of function expressions.

  ESLint rule: func-style

  // bad
  const bad = function() {}
  
  // good
  function good() {}
  
  // also good
  const alsoGood = () => {}
  

• 10.3 <a name="10.3"></a> When using IIFEs, always wrap the function parentheses, with dangling parentheses for the function call.

  Note: If using modules, the module (file) itself serves as a private scope for variables. As such, IIFEs are rarely needed in this case. Additionally, when using const/ let, you can create a private scope simply by using an unnamed block.

  ESLint rule: wrap-iife

  // bad
  ;function() {
    const privateMember = 'foo';
  }()
  
  (function() {
    const privateMember = 'foo';
  }())
  
  // good
  (function() {
    const privateMember = 'foo';
  })()
  

• 10.4 <a name="10.4"></a> Anonymous functions leave no space between the function keyword and the parentheses. All functions have no spaces around their list of parameters, and a single space between the closing paren of the parameter list and the opening curly brace.

  Why? Because consistency is good!

  ESLint rules: space-before-blocks, space-before-function-paren, space-in-parens

  // bad
  function badOne(){}
  function badTwo () {}
  function badThree( arg1, arg2 ) {}
  
  // good
  function goodOne() {}
  function goodTwo() {}
  function goodThree(arg1, arg2) {}
  

• 10.5 <a name="10.5"></a> Never declare a function in a non-function block (if, while, etc). Assign the function to a variable instead.

  Why? ECMA-262 defines a block as a list of statements. A function declaration is not a statement. As such, declaring a function in a block is not spec-compliant, and can be interpreted differently depending on the environment.

  ESLint rule: no-loop-func

  // bad
  if (true) {
    function bad() {
      console.log('Please avoid this!');
    }
  }
  
  // good
  let test;
  if (true) {
    test = () => console.log('This is better!');
  }
  

• 10.6 <a name="10.6"></a> Functions should either always return a value, or never return a value. If a function optionally returns something, return null in the case where the relevant conditions were not met.

  ESLint rule: consistent-return

  // bad
  function badFunction(condition) {
    if (!condition) { return; }
    return 'Condition met!';
  }
  
  // good
  function goodFunction(condition) {
    if (!condition) { return null; }
    return 'Condition met!';
  }
  

• 10.7 <a name="10.7"></a> Instead of using function#apply() to call a function with an array of arguments, use the spread syntax.

  Why? It reduces redundancy since you don’t have to specify the object to apply against, and it mirrors the rest syntax when declaring variadic functions.

  ESLint rule: prefer-spread

  const numbers = [1, 2, 3, 4, 5];
  
  // bad
  const max = Math.max.apply(Math, numbers);
  
  // good
  const max = Math.max(...numbers);
  

Arrow Functions

• 10.8 <a name="10.8"></a> When you must use a function expression (for example, as an anonymous function in a callback), use arrow function notation.

  Why? The function will execute without binding this, so it can use the this of its defining scope, which is usually what you want. It is also a more concise syntax, particularly for chained methods that take callbacks.

  ESLint rule: prefer-arrow-callback

  function takesCallback(callback) {
    callback();
  }
  
  // bad
  takesCallback(function() {
    console.log('This is no good!');
  });
  
  
  // good
  takesCallback(() => {
    console.log('Much better!');
  });
  

• 10.9 <a name="10.9"></a> Always leave one space on either side of the arrow.

  ESLint rule: arrow-spacing

  // bad
  (bad)=>{}
  (bad)=> {}
  (bad) =>{}
  (bad) =>'terrible'
  
  // good
  (good) => {}
  (good) => 'fabulous'
  

• 10.10 <a name="10.10"></a> If the body of your arrow function takes only a single expression, you can omit the braces and make use of the implicit return. If your function’s body has more than one expression, it returns an object, or it returns something that spans multiple lines, you can use braces and an explicit return.

  ESLint rule: arrow-body-style

  // bad
  const result = [1, 2, 3]
    .map((x) => {
      return (x * x) + 1;
    })
    .filter((x) => {
      return x < 6;
    });
  
  // doesn't return an object with `foo` key, actually returns nothing!
  runCallback((foo) => {foo});
  
  // good
  const result = [1, 2, 3]
    .map((x) => (x * x) + 1)
    .filter((x) => x < 6);
  
  runCallback((foo) => {
    return {foo};
  });
  

• 10.11 <a name="10.11"></a> Always include parentheses around the arguments of an arrow function.

  Why? Even though you can omit the parentheses around an arrow function with a single argument, it is better to maintain consistency with the zero-argument and multiple-argument cases for arrow functions, which require parentheses.

  ESLint rule: arrow-parens

  // bad
  [1, 2, 3].map(x => x * x);
  
  // good
  [1, 2, 3].map((x) => x * x);
  

Parameters

• 10.12 <a name="10.12"></a> Never use the implicitly defined arguments array-like object provided by functions. Instead, use rest syntax (...) to describe variadic arguments.

  ESLint rule: prefer-rest-params

  Why? ... is explicit in which arguments you want pulled, and covers the boilerplate of assigning parameters out of arguments. It also provides an actual array, so all array prototype methods are available.

  // bad
  function allThe() {
    const bads = Array.from(arguments);
    return bads.map((bad) => `${bad} is bad!`);
  }
  
  // good
  function allThe(...goods) {
    return goods.map((good) => `${good} is good!`);
  }
  

• 10.13 <a name="10.13"></a> Use default arguments rather than mutating function arguments.

  Why? The syntax makes it clear what you are trying to do, and you avoid the subtle bugs that can be introduced by checking whether a parameter was provided.

  // bad
  function badOne(options) {
    {}; // might not be what you want for falsey `options`
  }
  
  function badTwo(options) {
    options = (options == null) ? {} : options;
  }
  
  // good
  function good(options = {}) {}
  

• 10.14 <a name="10.14"></a> Avoid side effects or complex default parameters.

  Why? They can be difficult to reason about and typically indicate that your function is doing too much.

  let a = 1;
  
  // bad
  function badOne(b = a++) {}
  function badTwo(arg = [1, 2, 3].map((val) => val * 3)) {}
  
  // good
  function goodOne(b) {}
  goodOne(a++);
  
  function createDefaultParameter() {}
  function goodTwo(arg = createDefaultParameter()) {}
  

• 10.15 <a name="10.15"></a> Always put default parameters last.

  // bad
  function bad(options = {}, name) {}
  
  // good
  function good(name, options = {}) {}
  

• 10.16 <a name="10.16"></a> Be careful not to overcomplicate function declarations using new object parameter-related features. While you can destructure, use the rest operator, provide default parameter values, provide a default argument, and provide different local names for parameters, limit your use of these such that your code remains readable. In general, avoid providing a complex default hash in addition to default parameter values.

  // bad (parameter list is complex to reason about)
  function bad({
    foo: myFoo = 2,
    bar = 10000,
    ...otherOptions,
  } = {foo: 'foo', qux: true}) {}
  
  // good (this is probably the most complex structure that's acceptable)
  function good({foo = 2, bar = 10000, ...otherOptions} = {}) {}
  

↑ scrollTo('#table-of-contents')

Types and casting

• 11.1 <a name="11.1"></a> Use the String function to convert a value to a string.

  ESLint rules: no-implicit-coercion, no-new-wrappers

  const number = 15;
  
  // bad
  const badStringNumOne = number + '';
  const badStringNumTwo = new String(number);
  
  // good
  const goodStringNum = String(number);
  

• 11.2 <a name="11.2"></a> Use the Number function for type casting and Number.parseInt for parsing strings. Always include the radix parameter when using Number.parseInt.

  Why? Forgetting to include the radix when your string starts with 0 or 0x will result in it being parsed as an octal or hexadecimal number, respectively (which is not usually what you want). Providing a radix forces you to specify the way in which the string is parsed.

  ESLint rules: radix, no-implicit-coercion, no-new-wrappers

  const input = '43';
  
  // bad
  const badOne = new Number(input);
  const badTwo = +input;
  const badThree = input >> 0;
  const badFour = Number.parseInt(input);
  const badFive = parseInt(input);
  
  // good
  const goodOne = Number(input);
  const goodTwo = Number.parseInt(input, 10);
  

• 11.3 <a name="11.3"></a> Use the Boolean function for casting to a boolean value (or the relevant comparison operators, where possible). Never use double negation (!!), the Boolean constructor, or other “clever” techniques for getting a boolean value.

  ESLint rules: no-implicit-coercion, no-new-wrappers, no-extra-boolean-cast

  const collection = [];
  
  // bad
  const badOne = !!collection;
  const badTwo = new Boolean(collection);
  const badThree = ~collection.indexOf('foo');
  
  // good
  const goodOne = Boolean(collection);
  const goodTwo = collection.indexOf('foo') >= 0
  

• 11.4 <a name="11.4"></a> Use === and !== over == and !=. The only exception to this rule is == null, which is allowed in order to check whether a reference is either null or undefined.

  Why? == and != perform type coercion, which can result in some unexpected comparions (for example, [] == false and 3 == '03' evaluate to true). === and !== test for strict equality, which is almost always what you want.

  ESLint rule: eqeqeq

  // bad
  if (badValue == 3) {}
  
  // good
  if (goodValue === 3) {}
  

• 11.5 <a name="11.5"></a> Don’t use shorthand boolean comparisons.

  Note: remember that false, undefined, null, '', 0, and NaN evaluate to false, and all other values evaluate to true.

  Why? Using the shorthands relies on JavaScript’s questionable cooercion rules, which allow more values than you might expect to be treated as false. Using the explicit boolean check makes your code clearer to future readers.

  const name = '';
  const collection = [];
  
  // bad
  if (name) {}
  if (collection.length) {}
  
  // good
  if (name !== '') {}
  if (name.length !== 0) {}
  if (collection.length > 0) {}
  

• 11.6 <a name="11.6"></a> Use the following patterns for type checking:

  // String
  typeof something === 'string';
  
  // Number
  typeof something === 'number';
  
  // Boolean
  typeof something === 'boolean';
  
  // Object
  something != null && typeof something === 'object';
  
  // Array
  Array.isArray(something);
  
  // Null
  something === null;
  
  // Undefined
  something === undefined;
  
  // Null or Undefined
  something == null;
  

↑ scrollTo('#table-of-contents')

ESNext Features

• 12.1 <a name="12.1"></a> When using features that are not natively supported in some target environments (typically, browsers), use core-js to provide polyfills. Do not include the entire core-js shim; core-js is extremely modular and allows you to be selective of what polyfills you want to include based on the features you need and your target environments' feature support.

• 12.2 <a name="12.2"></a> Limit use of generators and proxies, as these don’t transpile well (or at all) to ES5.

• 12.3 <a name="12.3"></a> Prefer binary, octal, and hexadecimal literals over using parseInt.

  ESLint rule: prefer-numeric-literals

  // bad
  const twoSixtyFiveInHex = parseInt('1F7', 16);
  
  // good
  const twoSixtyFiveInHex = 0x1F7;
  

• 12.4 <a name="12.4"></a> Always provide a description when creating a Symbol.

  Why? You will get a more descriptive representation of that symbol in most developer tools.

  ESLint rule: symbol-description

  // bad
  const badSymbol = Symbol();
  
  // good
  const goodSymbol = Symbol('Good!');
  

Destructuring

• 12.5 <a name="12.5"></a> Use object destructuring to retrieve multiple properties from an object.

  Why? Destructuring removes a lot of boilerplate and encourages you to refer to properties by the same name everywhere they are referenced.

  // bad
  function fullNameForUser(user) {
    const firstName = user.firstName;
    const lastName = user.lastName;
  
    return `${firstName} ${lastName}`;
  }
  
  // good
  function fullNameForUser(user) {
    const {firstName, lastName} = user;
    return `${firstName} ${lastName}`;
  }
  
  // best
  function fullNameForUser({firstName, lastName}) {
    return `${firstName} ${lastName}`;
  }
  

• 12.6 <a name="12.6"></a> Use array destructuring rather than manually accessing items by their index. If your array has more than a few entries, and you are selecting only a small number of them, continue to use index notation.

  const array = [1, 2];
  const longArray = [1, 2, 3, 4, 5];
  
  // bad
  const first = array[0];
  const second = array[1];
  
  const [secondLong,,,, fifthLong] = longArray;
  
  // good
  const [first, second] = array;
  
  const secondLong = longArray[1];
  const fifthLong = longArray[4];
  

• 12.7 <a name="12.7"></a> If you need to return multiple values from a function, return them using an object rather than an array.

  Why? Call sites that use destructuring to access your return values need to care about the ordering when returning an array, making them fragile to change.

  // bad
  function positionForNode(node) {
    // figure stuff out
    return [left, right, top, bottom];
  }
  
  const [left, _, top] = positionForNode(node);
  
  // good
  function positionForNode(node) {
    // figure stuff out
    return {left, right, top, bottom};
  }
  
  const {left, top} = positionForNode(node);
  

• 12.8 <a name="12.8"></a> You can create highly readable functions by using one positional argument, followed by a destructured object. You can even provide different local names for the destructured arguments to have both an expressive external API and concise internal references.

  // fine, but too many positional arguments, so it's hard for call sites to know what to do
  function horizontalPosition(node, container, offset) {
    return container.offsetLeft + node.offsetLeft + offset.left;
  }
  
  horizontalPosition(node, node.parentNode, offset);
  
  // good: arguments are explicit
  function horizontalPositionForNode(node, {inContainer, withOffset}) {
    return inContainer.offsetLeft + node.offsetLeft + withOffset.left;
  }
  
  horizontalPositionForNode(node, {inContainer: node.parentNode, withOffset: offset});
  
  // also good: more concise internal names, same external API
  function horizontalPositionForNode(node, {inContainer: container, withOffset: offset}) {
    return container.offsetLeft + node.offsetLeft + offset.left;
  }
  
  horizontalPositionForNode(node, {inContainer: node.parentNode, withOffset: offset});
  

Classes

• 12.9 <a name="12.9"></a> Use classes with care: they do not behave in exactly the way you would expect in other languages, and JavaScript provides many mechanisms (closures, simple objects, etc) that solve problems for which you might use a class in another language. The rule of thumb is: use the right tool for the job!

  // bad
  // all static members, no need for a class
  class BadSingleton {
    static singletonProp = 'foo';
    static singletonMethod() {
      return 'bar';
    }
  }
  
  // good
  const GoodSingleton = {
    singletonProp: 'foo',
    singletonMethod() {
      return 'bar';
    },
  };
  
  // bad
  // needlessly using a class to encapsulate data that could be passed to a function
  class BadChoice {
    constructor(first, second) {
      this.first = first;
      this.second = second;
    }
  
    takeAction() {
      return `The first: ${this.first}, the second: ${this.second}`;
    }
  }
  
  const result = new BadChoice('foo', 'bar').takeAction();
  
  // good
  function takeAction({first, second}) {
    return `The first: ${first}, the second: ${second}`;
  }
  
  const result = takeAction({first: 'foo', second: 'bar'});
  

• 12.10 <a name="12.10"></a> If you want to use constructor functions, use class syntax. Avoid creating them by manually updating the prototype.

  Why? class syntax is more concise and will be more familiar for developers trained in other languages.

  // bad
  function BadClass() {
    this.isNotIdeal = true;
  }
  
  BadClass.prototype.shouldIDoThis = function() {
    return 'Definitely not';
  }
  
  // good
  class GoodClass {
    ideal = true;
  
    shouldIDoThis() {
      return 'Yes!';
    }
  }
  

• 12.11 <a name="12.11"></a> If you are subclassing, your subclass’s constructor should always call super before referencing this.

  Why? If your forget to call super in your subclass constructor, your object will be uninitialized and calling this will result in an exception.

  ESLint rule: no-this-before-super

  class Base {}
  
  // bad
  class BadClass extends Base {
    constructor() {
      this.bad = bad();
      super('I am bad :(');
    }
  }
  
  // good
  class GoodClass extends Base {
    constructor() {
      super('I am good :)');
      this.good = good();
    }
  }
  

• 12.12 <a name="12.12"></a> When declaring static members or properties, prefer the static keyword to direct assignment to the class object. Put static members at the top of your class definition.

  Why? Using the static keyword is more expressive and keeps the entire class definition in one place.

  // bad
  class BadClass {
    constructor() {}
    instanceMethod() {}
  }
  
  BadClass.staticProperty = 'foo';
  BadClass.staticMethod = function() {}
  
  // good
  class GoodClass {
    static staticProperty = 'foo';
    static staticMethod() {}
  
    constructor() {}
    instanceMethod() {}
  }
  

• 12.13 <a name="12.13"></a> Instance methods that don’t refer to this don’t necessarily need to be instance methods. These can often be turned into utility functions (if their behaviour is generic) or static methods (if they relate to the class but aren't instance-specific).

  // bad
  class BadClass {
    badMethod(string) {
      console.log(string.toUpperCase());
    }
  
    anotherMethod() {
      return this.badMethod('oops!');
    }
  }
  
  // good
  function goodFunction(string) {
    console.log(string.toUpperCase());
  }
  
  class GoodClass {
    anotherMethod() {
      return goodFunction('oops!');
    }
  }
  

Modules

• 12.14 <a name="12.14"></a> Always use modules (import/ export) with named exports over a different/non-standard module system (CommonJS being the most popular of these).

  Modules are the future, so let’s get a head start. You can always transpile to a preferred module system.

  Avoid using default exports, consistently using named exports helps to keep naming and import style consistent across our repos.

  // bad
  const BadImport = require('./BadImport');
  module.exports = BadImport.feelBadAboutIt();
  export default BadImport;
  
  // good
  export {feelGoodAboutIt, GoodImport} from './GoodImport';
  export otherExport;
  

• 12.15 <a name="12.15"></a> Avoid complex relative import paths. It is usually fairly easy and much clearer to add the root of your project to the load path.

  Why? Relative paths are fragile and hard to parse for humans.

  // bad
  export feelBadAboutIt from '../../../lib/BadImport';
  
  // good (with some path additions)
  import feelGoodAboutIt from 'lib/GoodImport';
  

↑ scrollTo('#table-of-contents')

Project structure

• 13.1 <a name="13.1"></a> Prefer dash-/kebab-case for file names. Pascal case is acceptable for naming files that export React components. For projects that are transitioning from CoffeeScript to JavaScript, it is also acceptable to use snake case for the file names in order to retain consistency.

• 13.2 <a name="13.2"></a> Most tools, including Babel, ESLint, and Stylelint, allow you to specify your configuration in dotfiles at the root of your project, or as special keys in your package.json. Where possible, prefer placing this configuration in package.json. Where not possible (for example, when providing a custom ESLint configuration for a subdirectory), prefer the JavaScript version of the configuration over the dotfile version. Use dotfiles only when you have no other option.

  Why? Placing configuration in package.json means that any developer can see all configuration in a single file, and cleans up the root of a directory.

  // bad (my-project/.babelrc)
  {
    "plugins": ["shopify"]
  }
  
  // good (my-project/package.json)
  {
    "babel": {
      "plugins": ["shopify"]
    }
  }
  
  // bad (my-project/test/.eslintrc)
  {
    "env": {"mocha": true}
  }
  
  // good (my-project/test/.eslintrc.js)
  module.exports = {
    env: {mocha: true},
  };
  

↑ scrollTo('#table-of-contents')

Resources

Performance

Writing performant JavaScript is our top priority. No amount of well-structured, clean JavaScript can compensate for the end user having a bad experience. You can find a collection of great performance-related resources on the FED resources page.

Tools

• ES6 Compatibility Table (shows browser, platform, and transpiler ES2015+ feature support)
• ES6 Katas (learn ES6 by fixing tests)
• Mocha, Chai, and Sinon, our preferred testing tools
• Editor Linting Plugins
  • SublimeLinter-eslint
  • linter-eslint for Atom
  • ESLint for IntelliJ IDEs

Books

• JavaScript: The Good Parts by Douglas Crockford
• You Don’t Know JS Book Series by Kyle Simpson
• Eloquent JavaScript by Marijn Haverbeke
• Exploring ES6 by Dr. Axel Rauschmayer
• Learning JavaScript Design Patterns by Addy Osmani
• JavaScript Testing Recipes by James Coglan

Blogs

• JavaScript Weekly
• Addy Osmani
• Pony Foo
• 2ality
• Getify
• Rebecca Murphy

Articles

• Promises: We have a problem with Promises by Nolan Lawson
• Testing: Writing testable JavaScript by Rebecca Murphey

Podcasts

• Javascript Air
• JavaScript Jabber

Other

• Understanding Chrome DevTools
• ECMAScript current proposals, including the stage 0 proposals

↑ scrollTo('#table-of-contents')