@justia/babel-preset

A Babel preset for transforming your JavaScript for Justia

Currently contains transforms for all stage 4 (ES2018) and stage 3 syntax that is permitted in the [Justia Style Guide].

Install

npm install --save-dev @justia/babel-preset

Usage

Via .babelrc or package.json (Recommended)

.babelrc

{
  "presets": [
    "@justia/babel-preset"
  ]
}

Via CLI

babel script.js --presets @justia/babel-preset

Via Node API

require('@babel/core').transform('code', {
    presets: ['@justia/babel-preset']
});

Configure @babel/preset-env

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

targets

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

For a list of browsers please see browserslist.

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

{
  "presets": [
    [
      "@justia/babel-preset",
      {
        "targets": {
          "chrome": 50,
          "ie": 11,
          "firefox": 45
        }
      }
    ]
  ]
}

The following transpiles only for Node v6.

{
  "presets": [
    [
      "@justia/babel-preset",
      {
        "targets": {
          "node": 6
        }
      }
    ]
  ]
}

debug

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

{
  "presets": [
    [
      "@justia/babel-preset",
      {
        "debug": true
      }
    ]
  ]
}

Outputs to console.log the polyfills and transform plugins enabled by @babel/preset-env and, if applicable, which one of your targets that needed it.

useBuiltIns

Use the useBuiltIns key to configure how @babel/preset-env handles polyfills. This defaults to "entry" to allow importing core-js in entrypoint and use browserslist to select polyfills.

{
  "presets": [
    [
      "@justia/babel-preset",
      {
        "useBuiltIns": "usage"
      }
    ]
  ]
}

When either the "usage" or "entry" options are used, @babel/preset-env will add direct references to core-js modules as bare imports (or requires). This means core-js will be resolved relative to the file itself and needs to be accessible.

Since @babel/polyfill was deprecated in 7.4.0, we recommend directly adding core-js and setting the version via the corejs option.

npm install core-js@3 --save

Read more info about the specific details of each option in the @babel/preset-env official page.

corejs

This option only has an effect when used alongside "useBuiltIns": "usage" or "useBuiltIns": "entry", and ensures @babel/preset-env injects the correct imports for your core-js version. The valid values for this are 2, 3 or { version: 2 | 3, proposals: boolean }, defaults to 3.

By default, only polyfills for stable ECMAScript features are injected: if you want to polyfill them, you have three different options:

• when using useBuiltIns: "entry", you can directly import a proposal polyfill: import "core-js/proposals/string-replace-all".
• when using useBuiltIns: "usage" you have two different alternatives:
  • Set the shippedProposals option to true. This will enable polyfills and transforms for proposal which have already been shipped in browsers for a while.
  • use "corejs": { "version": 3, "proposals": true }. This will enable polyfill-ing of every proposal supported by core-js.

{
  "presets": [
    [
      "@justia/babel-preset",
      {
        "corejs": 3
      }
    ]
  ]
}

include

Please refer to @babel/preset-env#include for a list of available options.

You may define an array of plugins to always include using the include key.

{
  "presets": [
    [
      "@justia/babel-preset",
      {
        "include": [
          "plugin-transform-spread",
          "es.map",
          "es.set",
          "or es.object.assign"
        ]
      }
    ]
  ]
}

exclude

Please refer to @babel/preset-env#exclude for a list of available options.

You may define an array of plugins to always exclude/remove using the exclude key.

{
  "presets": [
    [
      "@justia/babel-preset",
      {
        "include": [
          "transform-async-to-generator",
          "transform-template-literals",
          "transform-regenerator"
        ]
      }
    ]
  ]
}

React Development Mode

When process.env.NODE_ENV is 'development', the development mode will be set for @babel/preset-react.

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

{
  "presets": [
    [
      "@justia/babel-preset",
      {
        "development": false
      }
    ]
  ]
}

Classes loose mode

By default, this preset will compile classes in normal mode. This is safer, but comes with a bundle size and runtime overhead. To compile classes in loose mode, set the looseClasses option to true:

{
  "presets": [
    [
      "@justia/babel-preset",
      {
        "looseClasses": true
      }
    ]
  ]
}

The risks of enabling loose classes are outlined in the Babel docs.

Note that this will result in a runtime breakage if the version passed into the airbnb preset is newer than the version of the babel runtime actually being used at build time.

Disabling plugin-transform-runtime

You can use the transformRuntime option to disable @babel/plugin-transform-runtime. Specifying false will disable the plugin. This option defaults to true.

Specifying module transforms

You can use the modules option to enable transformation of modules given to this preset:

{
  "presets": [
    [
      "@justia/babel-preset",
      {
        "modules": "auto"
      }
    ]
  ]
}

Both true and the option default auto will not transform modules if ES6 module syntax is already supported by the environment, or "commonjs" otherwise. false will not transform modules.

You can use the runtimeHelpersUseESModules option to prevent transformation of runtime helpers to CommonJS modules.

{
  "presets": [
    [
      "@justia/babel-preset",
      {
        "runtimeHelpersUseESModules": true
      }
    ]
  ]
}

true will not transform runtime helpers to CommonJS modules. false will transform runtime helpers to CommonJS modules. The option defaults to true if modules is set to false, and false otherwise.

Usage with TypeScript

You can enable this option with the typescript key. Make sure you have a tsconfig.json file at the root directory.

{
  "presets": [
    [
      "@justia/babel-preset",
      {
        "typescript": true
      }
    ]
  ]
}