Skip to content

Latest commit

 

History

History
342 lines (265 loc) · 19.1 KB

parser.md

File metadata and controls

342 lines (265 loc) · 19.1 KB
Raw
Error in user YAML: (<unknown>): found character that cannot start any token while scanning for the next token at line 2 column 8
---
id: babel-parser
title: @babel/parser
---

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

  • The latest ECMAScript version enabled by default (ES2020).
  • Comment attachment.
  • Support for JSX, Flow, Typescript.
  • Support for experimental language proposals (accepting PRs for anything at least stage-0).

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

History | Version | Changes | | --- | --- | | `v7.7.0` | Added `errorRecovery` | | `v7.5.0` | Added `allowUndeclaredExports` | | `v7.2.0` | Added `createParenthesizedExpressions` |

  • 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.

  • 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.

  • 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 imports and exports 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.

  • startLine: By default, the first line of code parsed is treated as line 1. 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:

There is now an estree plugin which reverts these 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

Name Code Example
estree (repo) n/a

Language extensions

History | Version | Changes | | --- | --- | | `v7.6.0` | Added `v8intrinsic` |
| Name | Code Example | |------|--------------| | `flow` ([repo](https://github.com/facebook/flow)) | `var a: string = "";` | | `flowComments` ([docs](https://flow.org/en/docs/types/comments/)) | `/*:: type Foo = {...}; */` | | `jsx` ([repo](https://facebook.github.io/jsx/)) | `{s}` | | `typescript` ([repo](https://github.com/Microsoft/TypeScript)) | `var a: string = "";` | | `v8intrinsic` | `%DebugPrint(foo);` |

ECMAScript proposals

History | Version | Changes | | --- | --- | | `v7.14.0` | Added `asyncDoExpressions`. Moved `classProperties`, `classPrivateProperties`, `classPrivateMethods`, `moduleStringNames` to Latest ECMAScript features | | `v7.13.0` | Added `moduleBlocks` | | `v7.12.0` | Added `classStaticBlock`, `moduleStringNames` | | `v7.11.0` | Added `decimal` | | `v7.10.0` | Added `privateIn` | | `v7.9.0` | Added `recordAndTuple` | | `v7.7.0` | Added `topLevelAwait` | | `v7.4.0` | Added `partialApplication` | | `v7.2.0` | Added `classPrivateMethods` |
Name Code Example
asyncDoExpressions (proposal) async do { await requestAPI().json() }
classStaticBlock (proposal) class A { static {} }
decimal (proposal) 0.3m
decorators (proposal)
decorators-legacy		 @a class A {}
doExpressions (proposal) var a = do { if (true) { 'hi'; } };
exportDefaultFrom (proposal) export v from "mod"
functionBind (proposal) a::b, ::console.log
importAssertions (proposal) import json from "./foo.json" assert { type: "json" };
moduleBlocks (proposal) let m = module { export let y = 1; };
partialApplication (proposal) f(?, a)
pipelineOperator (proposal) a |> b
privateIn (proposal) #p in obj
recordAndTuple (proposal) #{x: 1}, #[1, 2]
throwExpressions (proposal) () => throw new Error("")
topLevelAwait (proposal) await promise in modules

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.

Name Code Example
asyncGenerators (proposal) async function*() {}, for await (let a of b) {}
bigInt (proposal) 100n
classProperties (proposal) class A { b = 1; }
classPrivateProperties (proposal) class A { #b = 1; }
classPrivateMethods (proposal) class A { #c() {} }
dynamicImport (proposal) import('./guy').then(a)
exportNamespaceFrom (proposal) export * as ns from "mod"
functionSent (proposal) function.sent
logicalAssignment (proposal) a &&= b
moduleStringNames (proposal) import { "😄" as smile } from "emoji";
nullishCoalescingOperator (proposal) a ?? b
numericSeparator (proposal) 1_000_000
objectRestSpread (proposal) var a = { b, ...c };
optionalCatchBinding (proposal) try {throw 0;} catch{do();}
optionalChaining (proposal) a?.b

Plugins options

History | Version | Changes | | --- | --- | | `7.14.0` | Added `dts` for `typescript` plugin |

NOTE: When a plugin is specified multiple times, only the first options are considered.

  • decorators:

    • decoratorsBeforeExport (boolean)

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

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

  • pipelineOperator:

  • recordAndtuple:

    • syntaxType (required, accepted values: hash, bar) There are two syntax variants for recordAndTuple. They share exactly same runtime semantics.
      SyntaxType Record Example Tuple Example
      "hash" #{ a: 1 } #[1, 2]
      "bar" {| a: 1 |} [|1, 2|]
      See Ergonomics of #{}/#[] for more information.

  • flow:

    • all (boolean, default: false) Some code has different meaning in Flow and in vanilla JavaScript. For example, foo<T>(x) is parsed as a call expression with a type argument in Flow, but as a comparison (foo < T > x) accordingly to the ECMAScript specification. By default, babel-parser parses those ambiguous constructs as Flow types only if the file starts with a // @flow pragma. Set this option to true to always parse files as if // @flow was specified.

  • typescript

Error codes

History | Version | Changes | | --- | --- | | `v7.14.0` | Added error codes |

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

There are two error codes, code and reasonCode.

  • code
    • Rough classification of errors (e.g. BABEL_PARSER_SYNTAX_ERROR, BABEL_PARSER_SOURCETYPE_MODULE_REQUIRED).
  • reasonCode
    • Detailed classification of errors (e.g. MissingSemicolon, VarRedeclaration).

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.

We currently aren't willing to commit to supporting the API for plugins or the resulting ecosystem (there is already enough work maintaining Babel's own plugin system). It's not clear how to make that API effective, and it would limit our ability to refactor and optimize the codebase.

Our current recommendation for those that want to create their own custom syntax is for users to fork the parser.

To consume your custom parser, you can add a plugin to your options to call the parser via its npm package name or require it if using JavaScript,

const parse = require("custom-fork-of-babel-parser-on-npm-here");

module.exports = {
  plugins: [
    {
      parserOverride(code, opts) {
        return parse(code, opts);
      },
    },
  ],
};