Check JavaScript files ES version against a specified ES version 🏆

ES Check checks JavaScript files against a specified version of ECMAScript (ES) with a shell command. If a specified file's ES version doesn't match the ES version argument passed in the ES Check command, ES Check will throw an error and log the files that didn't match the check.

Ensuring that JavaScript files can pass ES Check is important in a modular and bundled world. Read more about why.

ES Check version 9 is a major release update that can enforce actual ES version specific features checks, implements intitial browserslist integration, basic (naive) polyfill detection, and supports an allowlist. To enable ecmaVersion specific checks, pass the --checkFeatures flag. To enable browserslist integration, pass the --checkBrowser flag. To enable polyfill detection, pass the --checkForPolyfills flag. There is also more config file support. Besides this, there are other feature updates based on user feedback. This version should not break any existing scripts. Please report any issues!

es-check es6 './dist/**/*.js' --checkFeatures

Get Started   Why ES Check?   Usage   Walk Through   API   Debugging   Contributing   Issues

Install

npm i es-check --save-dev   # locally
npm i es-check -g           # or globally

Check if an array or glob of files matches a specified ES version.

• Note: adds quotation around globs. Globs are patterns like so, <something>/*.js.

es-check es5 './vendor/js/*.js' './dist/**/*.js'

• The ES Check script (above) checks /dist/*.js files to see if they're ES5. It throws an error and logs files are that do not pass the check.

In modern JavaScript builds, files are bundled up so they can be served in an optimized manner in the browsers. It is assumed by developers that future JavaScript—like ES8 will be transpiled (changed from future JavaScript to current JavaScript) appropriately by a tool like Babel. Sometimes there is an issue where files are not transpiled. There was no efficient way to test for files that weren't transpiled—until now. That's what ES Check does.

ES Check checks syntax out of the box—to protect against breaking errors going to production. Additionally, by adding the --checkFeatures flag, ES Check will check for actual ES version specific features. This ensures that your code is syntactically correct and only using features that are available in the specified ES version. Look here to view/add features that ES Check checks for with the --checkFeatures flag!

The images below demonstrate command line scripts and their corresponding logged results.

Pass

Fail

ES Check is run above with node commands. It can also be run within npm scripts, ci tools, or testing suites.

ES Check provides the necessities. It accepts its place as a JavaScript matcher/tester.

# USAGE

es-check <ecmaVersion> [files...]

Usage: index [options] [ecmaVersion] [files...]

Arguments:
  ecmaVersion                         ecmaVersion to check files against. Can be: es3, es4, es5, es6/es2015, es7/es2016, es8/es2017, es9/es2018, es10/es2019, es11/es2020, es12/es2021,
                                      es13/es2022, es14/es2023
  files                               a glob of files to to test the EcmaScript version against

Here's a comprehensive list of all available options:

Using ES modules:

es-check es6 './dist/**/*.js' --module

Checking files with hash bang:

es-check es6 './bin/*.js' --allowHashBang

Skipping specific files or directories:

es-check es5 './dist/**/*.js' --not=./dist/vendor,./dist/polyfills

Using the files option instead of arguments:

es-check es6 --files=./dist/main.js,./dist/utils.js

⚠️ NOTE: Setting both the [...files] argument and --files flag is an error.

Using loose glob matching:

es-check es5 './dist/**/*.js' './optional/**/*.js' --looseGlobMatching

Checking for ES version specific features:

es-check es6 './dist/**/*.js' --checkFeatures

Considering polyfills when checking features:

es-check es2022 './dist/**/*.js' --checkFeatures --checkForPolyfills

Using a custom config file:

es-check --config=./configs/production.escheckrc.json

ES Check is a shell command CLI. It is run in shell tool like Terminal, ITerm, or Hyper. It takes in two arguments: an ECMAScript version (<ECMAScript version>) and files ([files]) in globs.

Here are some example of es check scripts that could be run:

# globs
es-check ./js/*.js

# array of arguments
es-check ./js/*.js ./dist/*.js

If you're using a consistent configuration, you can create a .escheckrc file in JSON format with the ecmaVersion and files arguments so you can conveniently run es-check standalone from the command line.

Here's an example of what an .escheckrc file will look like:

{
  "ecmaVersion": "es6",
  "module": false,
  "files": "./dist/**/*.js",
  "not": ["./dist/skip/*.js"],
  "allowHashBang": false,
  "looseGlobMatching": false,
  "checkFeatures": true,
  "checkForPolyfills": true,
  "ignore": ["ErrorCause", "TopLevelAwait"],
  "allowList": ["ArrayToSorted", "ObjectHasOwn"],
  "checkBrowser": false,
  "browserslistPath": "./config/.browserslistrc",
  "browserslistEnv": "production"
}

For projects with multiple bundle types (like UMD, CJS, and ESM), you can specify different configurations using an array:

[
  {
    "ecmaVersion": "es6",
    "module": false,
    "files": "{cjs,umd}/index.{cjs,js}"
  },
  {
    "ecmaVersion": "es2020",
    "module": true,
    "files": "esm/index.mjs",
    "checkFeatures": true
  },
  {
    "files": "legacy/*.js",
    "checkBrowser": true,
    "browserslistEnv": "legacy"
  }
]

⚠️ NOTE: Using command line arguments while there is an .escheckrc file in the project directory will override all configurations in .escheckrc.

You can also specify a custom config file path using the --config option:

es-check --config=./configs/my-custom-config.json

This is useful for projects that need different configurations for different environments or test scenarios.

As of ES-Check version 2.0.2, a better debugging interface is provided. When a file errors, An error object will be logged with:

• the erroring file
• the error
• the error stack

⚠️ NOTE: Error logs are from the Acorn parser while parsing JavaScript related to specific versions of ECMAScript. This means error messaging is not specific to ECMAScript version. It still offers context into parsing issues!

Sometimes you may need to temporarily ignore certain feature detections while working on fixes. ES Check provides two ways to ignore features:

1. Via command line:

es-check es6 './dist/**/*.js' --checkFeatures --ignore="ErrorCause,TopLevelAwait"

1. Via ignore file:

es-check es6 './dist/**/*.js' --checkFeatures --ignoreFile=".escheckignore"

Example .escheckignore file:

{
  "features": [
    "ErrorCause",
    "TopLevelAwait"
  ]
}

⚠️ NOTE: The ignore feature is intended as a temporary solution while working on fixes. It's recommended to remove ignored features once the underlying issues are resolved.

When using polyfills like core-js to add support for modern JavaScript features in older environments, you might encounter false positives with the --checkFeatures flag. ES Check provides the --checkForPolyfills option to handle this scenario:

es-check es2022 './dist/**/*.js' --checkFeatures --checkForPolyfills

This option tells ES Check to look for common polyfill patterns in your code and avoid flagging features that have been polyfilled. Currently, it supports detection of:

• Core-js polyfills (both direct usage and imports)
• Common polyfill patterns for Array, String, Object, Promise, and RegExp methods

ES Check provides three ways to handle polyfilled features:

1. --checkForPolyfills: Automatically detects polyfills in your code

   es-check es2022 './dist/**/*.js' --checkFeatures --checkForPolyfills

2. --allowList: Explicitly specify features to allow regardless of ES version

   es-check es2022 './dist/**/*.js' --checkFeatures --allowList="ArrayToSorted,ObjectHasOwn"

3. --ignore: Completely ignore specific features during checking

   es-check es2022 './dist/**/*.js' --checkFeatures --ignore="ArrayToSorted,ObjectHasOwn"

• Use --checkForPolyfills when you have a standard polyfill setup (like core-js) and want automatic detection
• Use --allowList when you have custom polyfills or want to be explicit about which features are allowed
• Use --ignore as a temporary solution when you're working on fixes

⚠️ NOTE: The polyfill detection is not exhaustive and may not catch all polyfill patterns. For complex polyfill setups, you might need to combine it with --allowList.

ES-Check can use your project's browserslist configuration to automatically determine which ES version to check against:

es-check --checkBrowser ./dist/**/*.js

This will read your browserslist configuration (from .browserslistrc, package.json, etc.) and determine the appropriate ES version based on your targeted browsers.

Using a custom browserslist path:

es-check --checkBrowser --browserslistPath="./config/.browserslistrc" ./dist/**/*.js

Using a specific browserslist environment:

es-check --checkBrowser --browserslistEnv="production" ./dist/**/*.js

Combining with feature checking:

es-check --checkBrowser --checkFeatures ./dist/**/*.js

ES Check is a small utility using powerful tools that Isaac Z. Schlueter, Marijn Haverbeke, and Matthias Etienne built. ES Checker by Ruan YiFeng checks the JavaScript version supported within a browser at run time. ES Check offers similar feedback to ES Checker but at build time and is specific to the product that is using it. ES Check was started after reading this post about [deploying es2015 code to production today] by Philip Walton.

ES Check has 7 dependencies: acorn and acorn-walk, fast-glob, supports-color, winston, browserslist, and commander. To contribute, file an issue or submit a pull request.

To update es versions, check out these lines of code here and here (in acorn.js).

To update es feature detection, update these files here and here as enabled feature testing using acorn walk.

tests to go with new version and/or feature detection updates are great to have!

• Jeff Wainwright
• Brian Gonzalez
• Jon Ong
• Suhas Karanth
• Ben Junya
• Jeff Barczewski
• Brandon Casey