babel-preset-zillow

A Babel preset for transpiling JavaScript following our code conventions

Currently contains transforms for all stage 4 (ES2018) and stage 3 syntax that is permitted in the Zillow Style Guide. Please note that if usage of a stage 3 proposal is not explicitly mentioned in the Zillow Style Guide, then it will not be enabled here. Additionally, stage 4 syntax that is excluded is as follows:

• generators: regenerator-runtime is too heavyweight for our use.
• SIMD: this is a performance feature, so is pretty pointless to polyfill/transpile.
• lifted template literal restrictions: we do not use tagged template literals, nor implement custom DSLs, otherwise we would enable this.

Additionally, we also transpile the following:

• async/await
• class properties
• lodash
• styled-components

Install

npm install --save-dev babel-preset-zillow

Usage

Via .babelrc (Recommended)

.babelrc

{
  "presets": ["babel-preset-zillow"]
}

Via CLI

babel script.js --presets zillow

Via Node API

require("babel-core").transform("code", {
  presets: ["babel-preset-zillow"]
});

Targeting Environments

This module uses @babel/preset-env to target specific environments.

Please refer to babel-preset-env#targets for a list of available options.

For a list of browsers please see browserlist.

You may override our default list of targets by providing your own targets key.

{
  "presets": [["babel-preset-zillow", {
    "targets": {
      "chrome": 50,
      "explorer": 11,
      "firefox": 45
    }
  }]]
}

The following transpiles only for Node v8.

{
  "presets": [["babel-preset-zillow", {
    "targets": {
      "node": 8
    }
  }]]
}

If you wish, you can also inherit our default list of browsers and extend them using additionalTargets.

{
  "presets": [["babel-preset-zillow", {
    "additionalTargets": {
      "chrome": 42,
      "explorer": 8
    }
  }]]
}

Configuring Polyfills

This preset also supports passing additional options directly to @babel/preset-env:

• useBuiltIns
• corejs

These options are best suited for applications, not libraries, as they require additional dependencies (like core-js) that are not recommended for libraries.

For example, the following config would provide all global polyfills necessary for IE11 in an application, based on usage:

{
  "presets": [["babel-preset-zillow", {
    "useBuiltIns": "usage",
    "corejs": 3
  }]]
}

For more examples, please consult the core-js docs.

Advanced Plugin Exclusions

In some rare cases, it is necessary to explicitly exclude certain transforms that would otherwise be included by @babel/preset-env.

To accomplish this goal, this preset's default exclusions can be extended with the additionalExcludes array.

{
  "presets": [["babel-preset-zillow", {
    "additionalExcludes": [
      "@babel/plugin-transform-classes"
    ]
  }]]
}

You should always pass the fully-qualified transform name, not the shorthand. When targets.node is configured no exclusions are allowed, as they are generally not necessary anyway.

Nested Configuration Overrides

For advanced use cases, configuration for many of the presets and plugins employed by this module can be passed as sub-keys of the top-level options object. These configuration objects are spread into the internal configuration objects, overriding any keys already set. The currently supported preset option keys are:

• preset-env
• preset-react
• styled-components
• object-rest-spread

{
  "presets": [["babel-preset-zillow", {
    "preset-env": {
      "loose": true
    },
    "preset-react": {
      "runtime": "automatic"
    },
    "styled-components": {
      "pure": true
    },
    "object-rest-spread": {
      "useBuiltIns": false
    }
  }]]
}

Note: Any options passed under the preset-env key will override top-level options such as modules, additionalExcludes or additionalTargets (as both of the "additional" keys are extending the non-prefixed option name). For the time being, you should use one or the other configuration patterns, not both.

Debugging

You may override our default debug option by providing your own debug key.

{
  "presets": [["babel-preset-zillow", {
    "debug": true
  }]]
}

React Optimizations

By default, this preset will remove data-testid attributes from JSX elements in non-test builds and remove propTypes definitions (via wrapping) from React components in production builds. To explicitly customize this behavior, either pass false (to disable) or a config object.

Disable both optimizations:

{
  "presets": [["babel-preset-zillow", {
    "removeDataTestId": false,
    "removePropTypes": false
  }]]
}

Replace the attributes targeted by remove-data-test-id:

{
  "presets": [["babel-preset-zillow", {
    "removeDataTestId": {
      "attributes": ["data-selenium-id"]
    }
  }]]
}

Change the mode option of remove-prop-types:

{
  "presets": [["babel-preset-zillow", {
    "removePropTypes": {
      "mode": "remove",
      "removeImport": true
    }
  }]]
}

Selective Loose Modes

By default, this preset will compile as many modules as possible in loose mode. Normal mode is safer, but adds to bundle size and runtime overhead. We have options to selectively opt out of loose mode for applicable features. These options are:

• classes: looseClasses
• computed properties: looseComputedProperties
• parameters: looseParameters
• template literals: looseTemplateLiterals

For example, disable all loose compilation options:

{
  "presets": [["babel-preset-zillow", {
    "looseClasses": false,
    "looseComputedProperties": false,
    "looseParameters": false,
    "looseTemplateLiterals": false
  }]]
}