@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.23.0 | Added createImportExpressions |
v7.21.0 | Added allowNewTargetOutsideFunction and annexB |
v7.16.0 | Added startColumn |
v7.15.0 | Added attachComment |
v7.7.0 | Added errorRecovery |
v7.5.0 | Added allowUndeclaredExports |
v7.2.0 | Added createParenthesizedExpressions |
-
allowImportExportEverywhere: By default,
import
andexport
declarations can only appear at a program's top level. Setting this option totrue
allows them anywhere where a statement is allowed. -
allowAwaitOutsideFunction: By default,
await
use is only allowed inside of an async function or, when thetopLevelAwait
plugin is enabled, in the top-level scope of modules. Set this totrue
to also accept it in the top-level scope of scripts. This option is discouraged in favor oftopLevelAwait
plugin. -
allowNewTargetOutsideFunction: By default,
new.target
use is not allowed outside of a function or class. Set this totrue
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 totrue
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 useattachComment: 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 totrue
,ImportExpression
AST nodes are created instead. This option will default totrue
in Babel 8. -
createParenthesizedExpressions: By default, the parser sets
extra.parenthesized
on the expression nodes. When this option is set totrue
,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 anerrors
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 ES6import
orexport
statements. Files with ES6import
s andexport
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 totrue
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 theFile
node
Output
The Babel parser generates AST according to Babel AST format. It is based on ESTree spec with the following deviations:
- Literal token is replaced with StringLiteral, NumericLiteral, BigIntLiteral, BooleanLiteral, NullLiteral, RegExpLiteral
- Property token is replaced with ObjectProperty and ObjectMethod
- MethodDefinition is replaced with ClassMethod and ClassPrivateMethod
- PropertyDefinition is replaced with ClassProperty and ClassPrivateProperty
- PrivateIdentifier is replaced with PrivateName
- Program and BlockStatement contain additional
directives
field with Directive and DirectiveLiteral - ClassMethod, ClassPrivateMethod, ObjectProperty, and ObjectMethod value property's properties in FunctionExpression is coerced/brought into the main method node.
- ChainExpression is replaced with OptionalMemberExpression and OptionalCallExpression
- ImportExpression is replaced with a CallExpression whose
callee
is an Import node. This change will be reversed in Babel 8. - ExportAllDeclaration with
exported
field is replaced with an ExportNamedDeclaration containing an ExportNamespaceSpecifier node.
The estree
plugin can revert these deviations. Use it only if you are passing Babel AST to other ESTree-compliant tools.
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) | var a: string = ""; |
flowComments (docs) | /*:: type Foo = {...}; */ |
jsx (repo) | <a attr="b">{s}</a> |
typescript (repo) | var a: string = ""; |
v8intrinsic | %DebugPrint(foo); |
ECMAScript proposals
Name | Code Example |
---|---|
asyncDoExpressions (proposal) | async do { await requestAPI().json() } |
decorators (proposal) decorators-legacy | @a class A {} |
decoratorAutoAccessors (proposal) | class Example { @reactive accessor myBool = false; } |
deferredImportEvaluation (proposal) | import defer * as ns from "dep"; |
destructuringPrivate (proposal) | class Example { #x = 1; method() { const { #x: x } = this; } } |
doExpressions (proposal) | var a = do { if (true) { 'hi'; } }; |
explicitResourceManagement (proposal) | using reader = getReader() |
exportDefaultFrom (proposal) | export v from "mod" |
functionBind (proposal) | a::b , ::console.log |
functionSent (proposal) | function.sent |
importAttributes (proposal) | import json from "./foo.json" with { type: "json" }; |
moduleBlocks (proposal) | let m = module { export let y = 1; }; |
optionalChainingAssign (proposal) | x?.prop = 2 |
partialApplication (proposal) | f(?, a) |
pipelineOperator (proposal) | a |> b |
recordAndTuple (proposal) | #{x: 1} , #[1, 2] |
sourcePhaseImports (proposal) | import source x from "./x" |
throwExpressions (proposal) | () => throw new Error("") |
Plugins options
History
Version | Changes |
---|---|
7.21.0 | The default behavior of the decorators ' decoratorsBeforeExport option is to allow decorators either before or after the export keyword. |
7.19.0 | The syntaxType option of the recordAndTuple plugin defaults to hash ; added allowCallParenthesized option for the decorators plugin. |
7.17.0 | Added @@ and ^^ to the topicToken option of the hack pipeline operator |
7.16.0 | Added disallowAmbiguousJSXLike for typescript plugin. Added ^ to the topicToken option of the hack pipeline operators |
7.14.0 | Added dts for typescript plugin |
When a plugin is specified multiple times, only the first options are considered.
-
importAttributes
:-
deprecatedAssertSyntax
(boolean
, defaults tofalse
)When
true
, allow parsing an old version of the import attributes, which used theassert
keyword instead ofwith
.This matches the syntax originally supported by the
importAssertions
parser plugin.
-
-
decorators
:-
allowCallParenthesized
(boolean
, defaults totrue
)When
false
, disallow decorators in the@(...)()
form in favor of@(...())
. The stage 3 decorators proposal usesallowCallParenthesized: 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.JavaScript// decoratorsBeforeExport: true
@dec
export class C {}
// decoratorsBeforeExport: false
export @dec class C {}cautionThis option is deprecated and will be removed in a future version. Code that is valid when this option is explicitly set to
true
orfalse
is also valid when this option is not set.
-
-
optionalChainingAssign
:version
(required, accepted values:2023-07
) This proposal is still at Stage 1, and thus it's likely that it will be affected by breaking changes. You must specify which version of the proposal you are using to ensure that Babel will continue to parse your code in a compatible way.
-
pipelineOperator
:-
proposal
(required, accepted values:minimal
,fsharp
,hack
,(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.smart
-
topicToken
(required whenproposal
ishack
, accepted values:%
,#
,^
,@@
,^^
) Thehack
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 withrecordAndTuple
withsyntaxType: "hash"
. See plugin-proposal-pipeline-operator for more information.
-
-
recordAndTuple
:syntaxType
(hash
orbar
, defaults tohash
) There are two syntax variants forrecordAndTuple
. 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 totrue
to always parse files as if// @flow
was specified.
-
typescript
dts
(boolean
, defaultfalse
) This option will enable parsing within a TypeScript ambient context, where certain syntax have different rules (like.d.ts
files and insidedeclare module
blocks). Please see https://www.typescriptlang.org/docs/handbook/declaration-files/introduction.html and https://basarat.gitbook.io/typescript/type-system/intro for more information about ambient contexts.disallowAmbiguousJSXLike
(boolean
, defaultfalse
) Even when thejsx
plugin is not enabled, this option disallows using syntax that would be ambiguous with JSX (<X> y
type assertions and<X>() => {}
type arguments). It matches thetsc
behavior when parsing.mts
and.mjs
files.
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
).
- Rough classification of errors (e.g.
reasonCode
- Detailed classification of errors (e.g.
MissingSemicolon
,VarRedeclaration
).
- Detailed classification of errors (e.g.
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);
},
},
],
};