@babel/parser

The Babel parser (previously Babylon) is a JavaScript parser used in Babel .

Credits ​

Heavily based on acorn and acorn-jsx , thanks to the awesome work of @RReverser and @marijnh .

API ​

babelParser.parse(code, [options]) ​

babelParser.parseExpression(code, [options]) ​

parse() parses the provided code as an entire ECMAScript program, while parseExpression() tries to parse a single Expression with performance in mind. When in doubt, use .parse() .

Options ​

allowImportExportEverywhere : By default, import and export declarations can only appear at a program's top level. Setting this option to true allows them anywhere where a statement is allowed.

allowAwaitOutsideFunction : By default, await use is only allowed inside of an async function or, when the topLevelAwait plugin is enabled, in the top-level scope of modules. Set this to true to also accept it in the top-level scope of scripts. This option is discouraged in favor of topLevelAwait plugin.

allowNewTargetOutsideFunction : By default, new.target use is not allowed outside of a function or class. Set this to true to accept such code.

allowReturnOutsideFunction : By default, a return statement at the top level raises an error. Set this to true to accept such code.

allowSuperOutsideMethod : By default, super use is not allowed outside of class and object methods. Set this to true to accept such code.

allowUndeclaredExports : By default, exporting an identifier that was not declared in the current module scope will raise an error. While this behavior is required by the ECMAScript modules specification, Babel's parser cannot anticipate transforms later in the plugin pipeline that might insert the appropriate declarations, so it is sometimes important to set this option to true to prevent the parser from prematurely complaining about undeclared exports that will be added later.

attachComment : By default, Babel attaches comments to adjacent AST nodes. When this option is set to false , comments are not attached. It can provide up to 30% performance improvement when the input code has many comments. @babel/eslint-parser will set it for you. It is not recommended to use attachComment: false with Babel transform, as doing so removes all the comments in output code, and renders annotations such as /* istanbul ignore next */ nonfunctional.

annexb : By default, Babel parses JavaScript according to ECMAScript's Annex B " Additional ECMAScript Features for Web Browsers " syntax. When this option is set to false , Babel will parse syntax without the extensions specific to Annex B.

createImportExpressions : By default, the parser parses dynamic import import() as call expression nodes. When this option is set to true , ImportExpression AST nodes are created instead. This option will default to true in Babel 8.

createParenthesizedExpressions : By default, the parser sets extra.parenthesized on the expression nodes. When this option is set to true , ParenthesizedExpression AST nodes are created instead.

errorRecovery : By default, Babel always throws an error when it finds some invalid code. When this option is set to true , it will store the parsing error and try to continue parsing the invalid input file. The resulting AST will have an errors property representing an array of all the parsing errors. Note that even when this option is enabled, @babel/parser could throw for unrecoverable errors.

plugins : Array containing the plugins that you want to enable.

sourceType : Indicate the mode the code should be parsed in. Can be one of "script" , "module" , or "unambiguous" . Defaults to "script" . "unambiguous" will make @babel/parser attempt to guess , based on the presence of ES6 import or export statements. Files with ES6 import s and export s are considered "module" and are otherwise "script" .

sourceFilename : Correlate output AST nodes with their source filename. Useful when generating code and source maps from the ASTs of multiple input files.

startColumn : By default, the parsed code is treated as if it starts from line 1, column 0. You can provide a column number to alternatively start with. Useful for integration with other source tools.

startLine : By default, the parsed code is treated as if it starts from line 1, column 0. You can provide a line number to alternatively start with. Useful for integration with other source tools.

strictMode : By default, ECMAScript code is parsed as strict only if a "use strict"; directive is present or if the parsed file is an ECMAScript module. Set this option to true to always parse files in strict mode.

ranges : Adds a range property to each node: [node.start, node.end]

tokens : Adds all parsed tokens to a tokens property on the File node

Output ​

The Babel parser generates AST according to Babel AST format . It is based on ESTree spec with the following deviations:

AST for JSX code is based on Facebook JSX AST .

Semver ​

The Babel Parser follows semver in most situations. The only thing to note is that some spec-compliancy bug fixes may be released under patch versions.

For example: We push a fix to early error on something like #107 - multiple default exports per file. That would be considered a bug fix even though it would cause a build to fail.

Example ​

require("@babel/parser").parse("code", {
  // parse in strict mode and allow module declarations
  sourceType: "module",

  plugins: [
    // enable jsx and flow syntax
    "jsx",
    "flow",
  ],
});

Plugins ​

Miscellaneous ​

Language extensions ​

ECMAScript proposals ​

Latest ECMAScript features ​

The following features are already enabled on the latest version of @babel/parser , and cannot be disabled because they are part of the language. You should enable these features only if you are using an older version.

Plugins options ​

importAttributes :

deprecatedAssertSyntax ( boolean , defaults to false )

When true , allow parsing import attributes using the deprecated assert keyword. This matches the syntax originally supported by the importAssertions parser plugin.

allowCallParenthesized ( boolean , defaults to true )

When false , disallow decorators in the @(...)() form in favor of @(...()) . The stage 3 decorators proposal uses allowCallParenthesized: false .

decoratorsBeforeExport ( boolean )

By default decorators on exported classes can be placed either before or after the export keyword. When this option is set, decorators will only be allowed in the specified position.

// decoratorsBeforeExport: true
@dec
export class C {}

// decoratorsBeforeExport: false
export @dec class C {}

This option is deprecated and will be removed in a future version. Code that is valid when this option is explicitly set to true or false is also valid when this option is not set.

optionalChainingAssign :

pipelineOperator :

proposal (required, accepted values: minimal , fsharp , hack , smart (deprecated)) There are several different proposals for the pipeline operator. This option chooses which proposal to use. See plugin-proposal-pipeline-operator for more information, including a table comparing their behavior.

topicToken (required when proposal is hack , accepted values: % , # , ^ , @@ , ^^ ) The hack proposal uses a “topic” placeholder in its pipe. There are two different choices for this topic placeholder. This option chooses what token to use to refer to the topic. topicToken: "#" is incompatible with recordAndTuple with syntaxType: "hash" . See plugin-proposal-pipeline-operator for more information.

typescript

Error codes ​

Error codes are useful for handling the errors thrown by @babel/parser .

There are two error codes, code and reasonCode .

Example of using error codes with errorRecovery :

const { parse } = require("@babel/parser");

const ast = parse(`a b`, { errorRecovery: true });

console.log(ast.errors[0].code); // BABEL_PARSER_SYNTAX_ERROR
console.log(ast.errors[0].reasonCode); // MissingSemicolon

FAQ ​

Will the Babel parser support a plugin system? ​

Previous issues: #1351 , #6694 .