diff --git a/docs/parser.md b/docs/parser.md index 888bfb0592..a40b7ebc4f 100644 --- a/docs/parser.md +++ b/docs/parser.md @@ -34,9 +34,10 @@ mind. When in doubt, use `.parse()`. 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 not allowed - outside of an async function. Set this to `true` to accept such - code. +- **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. - **allowReturnOutsideFunction**: By default, a return statement at the top level raises an error. Set this to `true` to accept such @@ -174,6 +175,7 @@ require("@babel/parser").parse("code", { | `partialApplication` ([proposal](https://github.com/babel/proposals/issues/32)) | `f(?, a)` | | `pipelineOperator` ([proposal](https://github.com/babel/proposals/issues/29)) | a |> b | | `throwExpressions` ([proposal](https://github.com/babel/proposals/issues/23)) | `() => throw new Error("")` | +| `topLevelAwait` ([proposal])(https://github.com/tc39/proposal-top-level-await/) | `await promise` in modules | #### Plugins options diff --git a/docs/plugin-syntax-top-level-await.md b/docs/plugin-syntax-top-level-await.md new file mode 100644 index 0000000000..d7ba1e4d9d --- /dev/null +++ b/docs/plugin-syntax-top-level-await.md @@ -0,0 +1,49 @@ +--- +id: babel-plugin-syntax-top-level-await +title: @babel/plugin-syntax-top-level-await +sidebar_label: syntax-top-level-await +--- + +> #### Syntax only +> +> This plugin only enables parsing of this feature. Babel doesn't support transforming +> top-level await, but you can use Rollup's `experimentalTopLevelAwait` or webpack@5's +> `experiments.topLevelAwait` options. + +```js +const val = await promise; + +export { val }; +``` + +## Installation + +```sh +npm install --save-dev @babel/plugin-syntax-top-level-await +``` + +## Usage + +### Via `.babelrc` (Recommended) + +**.babelrc** + +```json +{ + "plugins": ["@babel/plugin-syntax-top-level-await"] +} +``` + +### Via CLI + +```sh +babel --plugins @babel/plugin-syntax-top-level-await script.js +``` + +### Via Node API + +```javascript +require("@babel/core").transform(code, { + plugins: ["@babel/plugin-syntax-top-level-await"], +}); +```