From b445b7973401e47b4acf5f97cd8280f8fc2919a8 Mon Sep 17 00:00:00 2001 From: Sven SAULEAU Date: Mon, 4 Jun 2018 16:32:39 +0200 Subject: [PATCH] Refactor move docs (#8108) * feat: [skip] generate readme script * docs: [skip ci] update READMEs * docs: [skip ci] fix code block type * chore: [skip ci] move generator script --- packages/babel-cli/README.md | 18 +- packages/babel-code-frame/README.md | 139 +- packages/babel-core/README.md | 251 +- packages/babel-generator/README.md | 77 +- .../babel-helper-annotate-as-pure/README.md | 45 +- .../babel-helper-bindify-decorators/README.md | 22 +- .../README.md | 18 +- .../babel-helper-builder-react-jsx/README.md | 33 +- packages/babel-helper-call-delegate/README.md | 18 +- packages/babel-helper-define-map/README.md | 18 +- .../README.md | 18 +- packages/babel-helper-explode-class/README.md | 18 +- packages/babel-helper-fixtures/README.md | 38 +- packages/babel-helper-function-name/README.md | 18 +- .../babel-helper-get-function-arity/README.md | 26 +- .../babel-helper-hoist-variables/README.md | 20 +- .../README.md | 80 +- .../babel-helper-module-imports/README.md | 80 +- .../babel-helper-module-transforms/README.md | 18 +- .../README.md | 18 +- .../babel-helper-plugin-test-runner/README.md | 22 +- packages/babel-helper-plugin-utils/README.md | 42 +- packages/babel-helper-regex/README.md | 18 +- .../README.md | 18 +- .../babel-helper-replace-supers/README.md | 18 +- packages/babel-helper-simple-access/README.md | 33 +- .../README.md | 28 +- .../README.md | 18 +- packages/babel-helper-wrap-function/README.md | 28 +- packages/babel-helpers/README.md | 55 +- packages/babel-highlight/README.md | 36 +- packages/babel-node/README.md | 18 +- packages/babel-parser/README.md | 187 +- .../babel-plugin-external-helpers/README.md | 34 +- .../README.md | 102 +- .../README.md | 144 +- .../README.md | 136 +- .../README.md | 113 +- .../README.md | 40 +- .../README.md | 40 +- .../README.md | 116 +- .../README.md | 61 +- .../README.md | 51 +- .../README.md | 58 +- .../README.md | 79 +- .../README.md | 109 +- .../README.md | 100 +- .../README.md | 55 +- .../README.md | 143 +- .../README.md | 34 +- .../README.md | 42 +- .../README.md | 57 +- .../README.md | 52 +- packages/babel-plugin-syntax-bigint/README.md | 33 +- .../README.md | 34 +- .../babel-plugin-syntax-decorators/README.md | 59 +- .../README.md | 34 +- .../README.md | 34 +- .../README.md | 34 +- .../README.md | 34 +- packages/babel-plugin-syntax-flow/README.md | 32 +- .../README.md | 34 +- .../README.md | 34 +- .../babel-plugin-syntax-import-meta/README.md | 34 +- .../README.md | 34 +- packages/babel-plugin-syntax-jsx/README.md | 34 +- .../README.md | 34 +- .../README.md | 34 +- .../README.md | 33 +- .../README.md | 34 +- .../README.md | 47 +- .../README.md | 34 +- .../README.md | 34 +- .../README.md | 37 +- .../babel-plugin-syntax-typescript/README.md | 34 +- .../README.md | 142 +- .../README.md | 82 +- .../README.md | 55 +- .../README.md | 96 +- .../babel-plugin-transform-classes/README.md | 120 +- .../README.md | 123 +- .../README.md | 97 +- .../README.md | 64 +- .../README.md | 56 +- .../README.md | 51 +- .../README.md | 66 +- .../README.md | 54 +- .../babel-plugin-transform-for-of/README.md | 147 +- .../README.md | 44 +- .../README.md | 57 +- .../babel-plugin-transform-jscript/README.md | 52 +- .../babel-plugin-transform-literals/README.md | 46 +- .../README.md | 42 +- .../README.md | 56 +- .../README.md | 158 +- .../README.md | 68 +- .../README.md | 209 +- .../README.md | 99 +- .../README.md | 55 +- .../README.md | 48 +- .../README.md | 66 +- .../README.md | 87 +- .../README.md | 46 +- .../README.md | 62 +- .../README.md | 75 +- .../README.md | 100 +- .../README.md | 50 +- .../README.md | 77 +- .../README.md | 48 +- .../README.md | 44 +- .../README.md | 44 +- .../README.md | 190 +- .../README.md | 82 +- .../README.md | 54 +- .../babel-plugin-transform-runtime/README.md | 353 +- .../README.md | 62 +- .../babel-plugin-transform-spread/README.md | 76 +- .../README.md | 42 +- .../README.md | 52 +- .../README.md | 78 +- .../README.md | 48 +- .../README.md | 67 +- .../README.md | 46 +- packages/babel-polyfill/README.md | 18 +- .../babel-preset-env-standalone/README.md | 43 +- packages/babel-preset-env/README.md | 593 +--- packages/babel-preset-es2015/README.md | 52 +- packages/babel-preset-es2016/README.md | 30 +- packages/babel-preset-es2017/README.md | 30 +- packages/babel-preset-flow/README.md | 46 +- packages/babel-preset-react/README.md | 126 +- packages/babel-preset-stage-0/README.md | 52 +- packages/babel-preset-stage-1/README.md | 64 +- packages/babel-preset-stage-2/README.md | 64 +- packages/babel-preset-stage-3/README.md | 58 +- packages/babel-preset-typescript/README.md | 58 +- packages/babel-register/README.md | 126 +- packages/babel-runtime/README.md | 18 +- packages/babel-standalone/README.md | 95 +- packages/babel-template/README.md | 169 +- packages/babel-traverse/README.md | 32 +- packages/babel-types/README.md | 3014 +---------------- scripts/generators/readmes.js | 55 + 143 files changed, 1286 insertions(+), 11238 deletions(-) create mode 100644 scripts/generators/readmes.js diff --git a/packages/babel-cli/README.md b/packages/babel-cli/README.md index 1c7b29fe05..1217b65614 100644 --- a/packages/babel-cli/README.md +++ b/packages/babel-cli/README.md @@ -2,20 +2,18 @@ > Babel command line. -In addition, various entry point scripts live in the top-level package at `@babel/cli/bin`. - -There is a shell-executable utility script, `babel-external-helpers.js`, and the main Babel cli script, `babel.js`. +See our website [@babel/cli](https://new.babeljs.io/docs/en/next/babel-cli.html) for more information. ## Install -```sh -npm install --save-dev @babel/core @babel/cli -``` - -## Usage +Using npm: ```sh -babel script.js +npm install --save @babel/cli ``` -For more in depth documentation see: http://babeljs.io/docs/usage/cli/ +or using yarn: + +```sh +yarn add --save @babel/cli +``` diff --git a/packages/babel-code-frame/README.md b/packages/babel-code-frame/README.md index 818b78a0ed..443a4bea65 100644 --- a/packages/babel-code-frame/README.md +++ b/packages/babel-code-frame/README.md @@ -2,141 +2,18 @@ > Generate errors that contain a code frame that point to source locations. +See our website [@babel/code-frame](https://new.babeljs.io/docs/en/next/babel-code-frame.html) for more information. + ## Install +Using npm: + ```sh -npm install --save-dev @babel/code-frame +npm install --save @babel/code-frame ``` -## Usage +or using yarn: -```js -import { codeFrameColumns } from '@babel/code-frame'; - -const rawLines = `class Foo { - constructor() -}`; -const location = { start: { line: 2, column: 16 } }; - -const result = codeFrameColumns(rawLines, location, { /* options */ }); - -console.log(result); -``` - -``` - 1 | class Foo { -> 2 | constructor() - | ^ - 3 | } -``` - -If the column number is not known, you may omit it. - -You can also pass an `end` hash in `location`. - -```js -import { codeFrameColumns } from '@babel/code-frame'; - -const rawLines = `class Foo { - constructor() { - console.log("hello"); - } -}`; -const location = { start: { line: 2, column: 17 }, end: { line: 4, column: 3 } }; - -const result = codeFrameColumns(rawLines, location, { /* options */ }); - -console.log(result); -``` - -``` - 1 | class Foo { -> 2 | constructor() { - | ^ -> 3 | console.log("hello"); - | ^^^^^^^^^^^^^^^^^^^^^^^^^ -> 4 | } - | ^^^ - 5 | }; -``` - -## Options - -### `highlightCode` - -`boolean`, defaults to `false`. - -Toggles syntax highlighting the code as JavaScript for terminals. - - -### `linesAbove` - -`number`, defaults to `2`. - -Adjust the number of lines to show above the error. - -### `linesBelow` - -`number`, defaults to `3`. - -Adjust the number of lines to show below the error. - -### `forceColor` - -`boolean`, defaults to `false`. - -Enable this to forcibly syntax highlight the code as JavaScript (for non-terminals); overrides `highlightCode`. - -### `message` - -`string`, otherwise nothing - -Pass in a string to be displayed inline (if possible) next to the highlighted -location in the code. If it can't be positioned inline, it will be placed above -the code frame. - -``` -1 | class Foo { -> 2 | constructor() - | ^ Missing { -3 | }; -``` - -## Upgrading from prior versions - -Prior to version 7, the only API exposed by this module was for a single line and optional column pointer. The old API will now log a deprecation warning. - -The new API takes a `location` object, similar to what is available in an AST. - -This is an example of the deprecated (but still available) API: - -```js -import codeFrame from '@babel/code-frame'; - -const rawLines = `class Foo { - constructor() -}`; -const lineNumber = 2; -const colNumber = 16; - -const result = codeFrame(rawLines, lineNumber, colNumber, { /* options */ }); - -console.log(result); -``` - -To get the same highlighting using the new API: - -```js -import { codeFrameColumns } from '@babel/code-frame'; - -const rawLines = `class Foo { - constructor() { - console.log("hello"); - } -}`; -const location = { start: { line: 2, column: 16 } }; - -const result = codeFrameColumns(rawLines, location, { /* options */ }); - -console.log(result); +```sh +yarn add --save @babel/code-frame ``` diff --git a/packages/babel-core/README.md b/packages/babel-core/README.md index a0e07daf99..156bbe7d28 100644 --- a/packages/babel-core/README.md +++ b/packages/babel-core/README.md @@ -2,249 +2,18 @@ > Babel compiler core. +See our website [@babel/core](https://new.babeljs.io/docs/en/next/babel-core.html) for more information. -```javascript -var babel = require("@babel/core"); -import { transform } from "@babel/core"; -import * as babel from "@babel/core"; +## Install + +Using npm: + +```sh +npm install --save @babel/core ``` -All transformations will use your local configuration files (`.babelrc` or in `package.json`). See [options](#options) to disable it. +or using yarn: - -## babel.transform(code: string, [options?](#options): Object, callback: Function) - -Transforms the passed in `code`. Calling a callback with an object with the generated code, -source map, and AST. - -```js -babel.transform(code, options, function(err, result) { - result; // => { code, map, ast } -}); +```sh +yarn add --save @babel/core ``` - -**Example** - -```js -babel.transform("code();", options, function(err, result) { - result.code; - result.map; - result.ast; -}); -``` - -### Compat Note: - -In Babel 6, this method was synchronous and `transformSync` did not exist. For backward-compatibility, -this function will behave synchronously if no callback is given. If you're starting with Babel 7 -and need synchronous behavior, please use `transformSync` since this backward-compat may be dropped in -future major versions of Babel. - - -## babel.transformSync(code: string, [options?](#options): Object) - -Transforms the passed in `code`. Returning an object with the generated code, -source map, and AST. - -```js -babel.transformSync(code, options) // => { code, map, ast } -``` - -**Example** - -```js -var result = babel.transformSync("code();", options); -result.code; -result.map; -result.ast; -``` - - -## babel.transformFile(filename: string, [options?](#options): Object, callback: Function) - -Asynchronously transforms the entire contents of a file. - -```js -babel.transformFile(filename, options, callback) -``` - -**Example** - -```js -babel.transformFile("filename.js", options, function (err, result) { - result; // => { code, map, ast } -}); -``` - - -## babel.transformFileSync(filename: string, [options?](#options): Object) - -Synchronous version of `babel.transformFile`. Returns the transformed contents of -the `filename`. - -```js -babel.transformFileSync(filename, options) // => { code, map, ast } -``` - -**Example** - -```js -babel.transformFileSync("filename.js", options).code; -``` - - -## babel.transformFromAst(ast: Object, code?: string, [options?](#options): Object, callback: Function): FileNode | null - -Given an [AST](https://astexplorer.net/), transform it. - -```js -const sourceCode = "if (true) return;"; -const parsedAst = babel.parse(sourceCode, { allowReturnOutsideFunction: true }); -babel.transformFromAst(parsedAst, sourceCode, options, function(err, result) { - const { code, map, ast } = result; -}); -``` - -### Compat Note: - -In Babel 6, this method was synchronous and `transformFromAstSync` did not exist. For backward-compatibility, -this function will behave synchronously if no callback is given. If you're starting with Babel 7 -and need synchronous behavior, please use `transformFromAstSync` since this backward-compat may be dropped in -future major versions of Babel. - - -## babel.transformFromAstSync(ast: Object, code?: string, [options?](#options): Object) - -Given an [AST](https://astexplorer.net/), transform it. - -```js -const sourceCode = "if (true) return;"; -const parsedAst = babel.parse(sourceCode, { allowReturnOutsideFunction: true }); -const { code, map, ast } = babel.transformFromAstSync(parsedAst, sourceCode, options); -``` - -## babel.parse(code: string, [options?](#options): Object) - -Given some code, parse it using Babel's standard behavior. Referenced presets and -plugins will be loaded such that optional syntax plugins are automatically -enabled. - - -## Advanced APIs - -Many systems that wrap Babel like to automatically inject plugins and presets, -or override options. To accomplish this goal, Babel exposes several functions -that aid in loading the configuration part-way without transforming. - -### babel.loadOptions([options?](#options): Object) - -Resolve Babel's options fully, resulting in an options object where: - -* `opts.plugins` is a full list of `Plugin` instances. -* `opts.presets` is empty and all presets are flattened into `opts`. -* It can be safely passed back to Babel. Fields like `babelrc` have been set to - false so that later calls to Babel will not make a second attempt to load - config files. - -`Plugin` instances aren't meant to be manipulated directly, but often -callers will serialize this `opts` to JSON to use it as a cache key representing -the options Babel has received. Caching on this isn't 100% guaranteed to -invalidate properly, but it is the best we have at the moment. - - -### babel.loadPartialConfig([options?](#options): Object): PartialConfig - -To allow systems to easily manipulate and validate a user's config, this function -resolves the plugins and presets and proceeds no further. The expectation is -that callers will take the config's `.options`, manipulate it as then see fit -and pass it back to Babel again. - -* `babelrc: string | void` - The path of the `.babelrc` file, if there was one. -* `babelignore: string | void` - The path of the `.babelignore` file, if there was one. -* `options: ValidatedOptions` - The partially resolved options, which can be manipulated and passed back to Babel again. - * `plugins: Array` - See below. - * `presets: Array` - See below. - * It can be safely passed back to Babel. Fields like `babelrc` have been set - to false so that later calls to Babel will not make a second attempt to - load config files. -* `hasFilesystemConfig(): boolean` - Check if the resolved config loaded any settings from the filesystem. - -[`ConfigItem`](#configitem-type) instances expose properties to introspect the values, but each -item should be treated as immutable. If changes are desired, the item should be -removed from the list and replaced with either a normal Babel config value, or -with a replacement item created by `babel.createConfigItem`. See that -function for information about `ConfigItem` fields. - - -### babel.createConfigItem(value: string | {} | Function | [string | {} | Function, {} | void], { dirname?: string, type?: "preset" | "plugin" }): ConfigItem - -Allows build tooling to create and cache config items up front. If this function -is called multiple times for a given plugin, Babel will call the plugin's function itself -multiple times. If you have a clear set of expected plugins and presets to -inject, pre-constructing the config items would be recommended. - - -### `ConfigItem` type - -Each `ConfigItem` exposes all of the information Babel knows. The fields are: - -* `value: {} | Function` - The resolved value of the plugin. -* `options: {} | void` - The options object passed to the plugin. -* `dirname: string` - The path that the options are relative to. -* `name: string | void` - The name that the user gave the plugin instance, e.g. `plugins: [ ['env', {}, 'my-env'] ]` -* `file: Object | void` - Information about the plugin's file, if Babel knows it. - * `request: string` - The file that the user requested, e.g. `"@babel/env"` - * `resolved: string` - The full path of the resolved file, e.g. `"/tmp/node_modules/@babel/preset-env/lib/index.js"` - - -## Options - -
-

Babel CLI

-

- You can pass these options from the Babel CLI like so: -

-

- babel --option-name=value -

-
- -Following is a table of the options you can use: - -| Option | Default | Description | -| ------------------------ | -------------------- | ------------------------------- | -| `ast` | `false` | Include the AST in the returned object | -| `auxiliaryCommentAfter` | `null` | Attach a comment after all non-user injected code | -| `auxiliaryCommentBefore` | `null` | Attach a comment before all non-user injected code | -| `root` | `"."` | Specify the "root" folder that defines the location to search for "babel.config.js", and the default folder to allow `.babelrc` files inside of.| -| `configFile` | `undefined` | The config file to load Babel's config from. Defaults to searching for "babel.config.js" inside the "root" folder. `false` will disable searching for config files.| -| `babelrc` | `true` | Specify whether or not to use .babelrc and .babelignore files. Not available when using the CLI, [use `--no-babelrc` instead](https://babeljs.io/docs/usage/cli/#babel-ignoring-babelrc) | -| `babelrcRoots` | `(root)` | Specify which packages should be search for .babelrc files when they are being compiled. `true` to _always_ search, or a path string or an array of paths to packages to search inside of. Defaults to only searching the "root" package. | -| `envName` | env vars | Defaults to environment variable `BABEL_ENV` if set, or else `NODE_ENV` if set, or else it defaults to `"development"` | -| `code` | `true` | Enable code generation | -| `comments` | `true` | Output comments in generated output | -| `compact` | `"auto"` | Do not include superfluous whitespace characters and line terminators. When set to `"auto"` compact is set to `true` on input sizes of >500KB | -| `env` | `{}` | This is an object of keys that represent different environments. For example, you may have: `{ env: { production: { /* specific options */ } } }` which will use those options when the `envName` is `production` | -| `extends` | `null` | A path to a `.babelrc` file to extend | -| `filename` | `"unknown"` | Filename for use in errors etc | -| `filenameRelative` | `(filename)` | Filename relative to `sourceRoot` | -| `generatorOpts` | `{}` | An object containing the options to be passed down to the babel code generator, @babel/generator | -| `getModuleId` | `null` | Specify a custom callback to generate a module id with. Called as `getModuleId(moduleName)`. If falsy value is returned then the generated module id is used | -| `highlightCode` | `true` | ANSI highlight syntax error code frames | -| `ignore` | `null` | Opposite to the `only` option. `ignore` is disregarded if `only` is specified | -| `inputSourceMap` | `null` | A source map object that the output source map will be based on | -| `minified` | `false` | Should the output be minified (not printing last semicolons in blocks, printing literal string values instead of escaped ones, stripping `()` from `new` when safe) | -| `moduleId` | `null` | Specify a custom name for module ids | -| `moduleIds` | `false` | If truthy, insert an explicit id for modules. By default, all modules are anonymous. (Not available for `common` modules) | -| `moduleRoot` | `(sourceRoot)` | Optional prefix for the AMD module formatter that will be prepend to the filename on module definitions | -| `only` | `null` | A [glob](https://github.com/isaacs/minimatch), regex, or mixed array of both, matching paths to **only** compile. Can also be an array of arrays containing paths to explicitly match. When attempting to compile a non-matching file it's returned verbatim | -| `parserOpts` | `{}` | An object containing the options to be passed down to the babel parser, @babel/parser | -| `plugins` | `[]` | List of [plugins](https://babeljs.io/docs/plugins/) to load and use | -| `presets` | `[]` | List of [presets](https://babeljs.io/docs/plugins/#presets) (a set of plugins) to load and use | -| `retainLines` | `false` | Retain line numbers. This will lead to wacky code but is handy for scenarios where you can't use source maps. (**NOTE:** This will not retain the columns) | -| `shouldPrintComment` | `null` | An optional callback that controls whether a comment should be output or not. Called as `shouldPrintComment(commentContents)`. **NOTE:** This overrides the `comment` option when used | -| `sourceFileName` | `(filenameRelative)` | Set `sources[0]` on returned source map | -| `sourceMaps` | `false` | If truthy, adds a `map` property to returned output. If set to `"inline"`, a comment with a sourceMappingURL directive is added to the bottom of the returned code. If set to `"both"` then a `map` property is returned as well as a source map comment appended. **This does not emit sourcemap files by itself!** To have sourcemaps emitted using the CLI, you must pass it the `--source-maps` option | -| `sourceRoot` | `(moduleRoot)` | The root from which all sources are relative | -| `sourceType` | `"module"` | Indicate the mode the code should be parsed in. Can be one of "script", "module", or "unambiguous". `"unambiguous"` will make Babel 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"`. | -| `wrapPluginVisitorMethod`| `null` | An optional callback that can be used to wrap visitor methods. **NOTE:** This is useful for things like introspection, and not really needed for implementing anything. Called as `wrapPluginVisitorMethod(pluginAlias, visitorType, callback)`. diff --git a/packages/babel-generator/README.md b/packages/babel-generator/README.md index 525e63ff20..750bfa9f42 100644 --- a/packages/babel-generator/README.md +++ b/packages/babel-generator/README.md @@ -1,78 +1,19 @@ # @babel/generator -> Turns the [babel AST](https://github.com/babel/babel/blob/master/packages/babel-parser/ast/spec.md) into code. +> Turns an AST into code. + +See our website [@babel/generator](https://new.babeljs.io/docs/en/next/babel-generator.html) for more information. ## Install +Using npm: + ```sh -npm install --save-dev @babel/generator +npm install --save @babel/generator ``` -## Usage +or using yarn: -```js -import {parse} from '@babel/parser'; -import generate from '@babel/generator'; - -const code = 'class Example {}'; -const ast = parse(code); - -const output = generate(ast, { /* options */ }, code); -``` - -## Options - -Options for formatting output: - -name | type | default | description ------------------------|----------|-----------------|-------------------------------------------------------------------------- -auxiliaryCommentBefore | string | | Optional string to add as a block comment at the start of the output file -auxiliaryCommentAfter | string | | Optional string to add as a block comment at the end of the output file -shouldPrintComment | function | `opts.comments` | Function that takes a comment (as a string) and returns `true` if the comment should be included in the output. By default, comments are included if `opts.comments` is `true` or if `opts.minifed` is `false` and the comment contains `@preserve` or `@license` -retainLines | boolean | `false` | Attempt to use the same line numbers in the output code as in the source code (helps preserve stack traces) -retainFunctionParens | boolean | `false` | Retain parens around function expressions (could be used to change engine parsing behavior) -comments | boolean | `true` | Should comments be included in output -compact | boolean or `'auto'` | `opts.minified` | Set to `true` to avoid adding whitespace for formatting -minified | boolean | `false` | Should the output be minified -concise | boolean | `false` | Set to `true` to reduce whitespace (but not as much as `opts.compact`) -filename | string | | Used in warning messages -jsonCompatibleStrings | boolean | `false` | Set to true to run `jsesc` with "json": true to print "\u00A9" vs. "©"; - -Options for source maps: - -name | type | default | description ------------------------|----------|-----------------|-------------------------------------------------------------------------- -sourceMaps | boolean | `false` | Enable generating source maps -sourceRoot | string | | A root for all relative URLs in the source map -sourceFileName | string | | The filename for the source code (i.e. the code in the `code` argument). This will only be used if `code` is a string. - -## AST from Multiple Sources - -In most cases, Babel does a 1:1 transformation of input-file to output-file. However, -you may be dealing with AST constructed from multiple sources - JS files, templates, etc. -If this is the case, and you want the sourcemaps to reflect the correct sources, you'll need -to pass an object to `generate` as the `code` parameter. Keys -should be the source filenames, and values should be the source content. - -Here's an example of what that might look like: - -```js -import {parse} from '@babel/parser'; -import generate from '@babel/generator'; - -const a = 'var a = 1;'; -const b = 'var b = 2;'; -const astA = parse(a, { sourceFilename: 'a.js' }); -const astB = parse(b, { sourceFilename: 'b.js' }); -const ast = { - type: 'Program', - body: [].concat(astA.program.body, astB.program.body) -}; - -const { code, map } = generate(ast, { sourceMaps: true }, { - 'a.js': a, - 'b.js': b -}); - -// Sourcemap will point to both a.js and b.js where appropriate. +```sh +yarn add --save @babel/generator ``` diff --git a/packages/babel-helper-annotate-as-pure/README.md b/packages/babel-helper-annotate-as-pure/README.md index 2e8d9642f7..6c3e2b7037 100644 --- a/packages/babel-helper-annotate-as-pure/README.md +++ b/packages/babel-helper-annotate-as-pure/README.md @@ -1,40 +1,19 @@ # @babel/helper-annotate-as-pure -## API +> Helper function to annotate paths and nodes with #__PURE__ comment -```js -declare export default annotateAsPure(nodeOrPath: Node | NodePath); +See our website [@babel/helper-annotate-as-pure](https://new.babeljs.io/docs/en/next/babel-helper-annotate-as-pure.html) for more information. + +## Install + +Using npm: + +```sh +npm install --save @babel/helper-annotate-as-pure ``` -## Usage +or using yarn: -```js -import traverse from "@babel/traverse"; -import annotateAsPure from "@babel/helper-annotate-as-pure"; - -// ... - -traverse(file, { - CallExpression(path) { - annotateAsPure(path); - }, -}); -``` - -## Caveat with UglifyJS pre v3.1.0 - -`@babel/helper-annotate-as-pure` will append any existing leading comments to the `#__PURE__` annotation. Versions of UglifyJS prior to v3.1.0 will **ignore** these annotations, as they only check the _last_ leading comment for the annotation. - -For example, using the `Usage` snippet above: - -**In** - -```js -const four = /* foo */ add(2, 2); -``` - -**Out** - -```js -const four = /* #__PURE__ */ /* foo */ add(2, 2); +```sh +yarn add --save @babel/helper-annotate-as-pure ``` diff --git a/packages/babel-helper-bindify-decorators/README.md b/packages/babel-helper-bindify-decorators/README.md index a8bbd11cd9..53088d34f7 100644 --- a/packages/babel-helper-bindify-decorators/README.md +++ b/packages/babel-helper-bindify-decorators/README.md @@ -1,9 +1,19 @@ # @babel/helper-bindify-decorators -## API -```javascript -declare export default bindifyDecorators(decorators: Array); -``` -## Usage +> Helper function to bindify decorators -TODO +See our website [@babel/helper-bindify-decorators](https://new.babeljs.io/docs/en/next/babel-helper-bindify-decorators.html) for more information. + +## Install + +Using npm: + +```sh +npm install --save @babel/helper-bindify-decorators +``` + +or using yarn: + +```sh +yarn add --save @babel/helper-bindify-decorators +``` diff --git a/packages/babel-helper-builder-binary-assignment-operator-visitor/README.md b/packages/babel-helper-builder-binary-assignment-operator-visitor/README.md index a5cde7a804..70faba8176 100644 --- a/packages/babel-helper-builder-binary-assignment-operator-visitor/README.md +++ b/packages/babel-helper-builder-binary-assignment-operator-visitor/README.md @@ -1,5 +1,19 @@ # @babel/helper-builder-binary-assignment-operator-visitor -## Usage +> Helper function to build binary assignment operator visitors -TODO +See our website [@babel/helper-builder-binary-assignment-operator-visitor](https://new.babeljs.io/docs/en/next/babel-helper-builder-binary-assignment-operator-visitor.html) for more information. + +## Install + +Using npm: + +```sh +npm install --save @babel/helper-builder-binary-assignment-operator-visitor +``` + +or using yarn: + +```sh +yarn add --save @babel/helper-builder-binary-assignment-operator-visitor +``` diff --git a/packages/babel-helper-builder-react-jsx/README.md b/packages/babel-helper-builder-react-jsx/README.md index 1701f15f51..95ab6f2306 100644 --- a/packages/babel-helper-builder-react-jsx/README.md +++ b/packages/babel-helper-builder-react-jsx/README.md @@ -1,28 +1,19 @@ # @babel/helper-builder-react-jsx -## Usage +> Helper function to build react jsx -```javascript -type ElementState = { - tagExpr: Object; // tag node - tagName: string; // raw string tag name - args: Array; // array of call arguments - call?: Object; // optional call property that can be set to override the call expression returned -}; +See our website [@babel/helper-builder-react-jsx](https://new.babeljs.io/docs/en/next/babel-helper-builder-react-jsx.html) for more information. -require("@babel/helper-builder-react-jsx")({ - filter: function (element: JSXElement) { - // if returns false, the element isn't transformed - }, +## Install - pre: function (state: ElementState) { - // function called with (state: ElementState) before building attribs - }, +Using npm: - post: function (state: ElementState) { - // function called with (state: ElementState) after building attribs - }, - - compat?: boolean // true if React is in compat mode -}); +```sh +npm install --save @babel/helper-builder-react-jsx +``` + +or using yarn: + +```sh +yarn add --save @babel/helper-builder-react-jsx ``` diff --git a/packages/babel-helper-call-delegate/README.md b/packages/babel-helper-call-delegate/README.md index decce1e1cd..d6c9f3021a 100644 --- a/packages/babel-helper-call-delegate/README.md +++ b/packages/babel-helper-call-delegate/README.md @@ -1,5 +1,19 @@ # @babel/helper-call-delegate -## Usage +> Helper function to call delegate -TODO +See our website [@babel/helper-call-delegate](https://new.babeljs.io/docs/en/next/babel-helper-call-delegate.html) for more information. + +## Install + +Using npm: + +```sh +npm install --save @babel/helper-call-delegate +``` + +or using yarn: + +```sh +yarn add --save @babel/helper-call-delegate +``` diff --git a/packages/babel-helper-define-map/README.md b/packages/babel-helper-define-map/README.md index 0bb310131e..0b078c66ba 100644 --- a/packages/babel-helper-define-map/README.md +++ b/packages/babel-helper-define-map/README.md @@ -1,5 +1,19 @@ # @babel/helper-define-map -## Usage +> Helper function to define a map -TODO +See our website [@babel/helper-define-map](https://new.babeljs.io/docs/en/next/babel-helper-define-map.html) for more information. + +## Install + +Using npm: + +```sh +npm install --save @babel/helper-define-map +``` + +or using yarn: + +```sh +yarn add --save @babel/helper-define-map +``` diff --git a/packages/babel-helper-explode-assignable-expression/README.md b/packages/babel-helper-explode-assignable-expression/README.md index 3229d3947c..8b9496eb29 100644 --- a/packages/babel-helper-explode-assignable-expression/README.md +++ b/packages/babel-helper-explode-assignable-expression/README.md @@ -1,5 +1,19 @@ # @babel/helper-explode-assignable-expression -## Usage +> Helper function to explode an assignable expression -TODO +See our website [@babel/helper-explode-assignable-expression](https://new.babeljs.io/docs/en/next/babel-helper-explode-assignable-expression.html) for more information. + +## Install + +Using npm: + +```sh +npm install --save @babel/helper-explode-assignable-expression +``` + +or using yarn: + +```sh +yarn add --save @babel/helper-explode-assignable-expression +``` diff --git a/packages/babel-helper-explode-class/README.md b/packages/babel-helper-explode-class/README.md index 6e1ab065f4..71f32729be 100644 --- a/packages/babel-helper-explode-class/README.md +++ b/packages/babel-helper-explode-class/README.md @@ -1,5 +1,19 @@ # @babel/helper-explode-class -## Usage +> Helper function to explode class -TODO +See our website [@babel/helper-explode-class](https://new.babeljs.io/docs/en/next/babel-helper-explode-class.html) for more information. + +## Install + +Using npm: + +```sh +npm install --save @babel/helper-explode-class +``` + +or using yarn: + +```sh +yarn add --save @babel/helper-explode-class +``` diff --git a/packages/babel-helper-fixtures/README.md b/packages/babel-helper-fixtures/README.md index 8f36c5d76f..b0980aa4c8 100644 --- a/packages/babel-helper-fixtures/README.md +++ b/packages/babel-helper-fixtures/README.md @@ -1,33 +1,19 @@ # @babel/helper-fixtures -**NOTE:** This is an internal Babel module and may not work outside. Use at your own risk. +> Helper function to support fixtures -## Usage +See our website [@babel/helper-fixtures](https://new.babeljs.io/docs/en/next/babel-helper-fixtures.html) for more information. -```javascript -import getFixtures from "@babel/helper-fixtures"; +## Install -type TestFile = { - loc: string; - code: string; - filename: string; -}; +Using npm: -type Test = { - title: string; - disabled: boolean; - options: Object; - exec: TestFile; - actual: TestFile; - expected: TestFile; -}; - -type Suite = { - options: Object; - tests: Array; - title: string; - filename: string; -}; - -let fixtures: Array = getFixtures("/User/sebmck/Projects/babel-something/test/fixtures"); +```sh +npm install --save @babel/helper-fixtures +``` + +or using yarn: + +```sh +yarn add --save @babel/helper-fixtures ``` diff --git a/packages/babel-helper-function-name/README.md b/packages/babel-helper-function-name/README.md index 97b5b4ded9..77d8a12edc 100644 --- a/packages/babel-helper-function-name/README.md +++ b/packages/babel-helper-function-name/README.md @@ -1,5 +1,19 @@ # @babel/helper-function-name -## Usage +> Helper function to change the property 'name' of every function -TODO +See our website [@babel/helper-function-name](https://new.babeljs.io/docs/en/next/babel-helper-function-name.html) for more information. + +## Install + +Using npm: + +```sh +npm install --save @babel/helper-function-name +``` + +or using yarn: + +```sh +yarn add --save @babel/helper-function-name +``` diff --git a/packages/babel-helper-get-function-arity/README.md b/packages/babel-helper-get-function-arity/README.md index d341c9ce35..7cc3d5a6f9 100644 --- a/packages/babel-helper-get-function-arity/README.md +++ b/packages/babel-helper-get-function-arity/README.md @@ -1,21 +1,19 @@ # @babel/helper-get-function-arity -Function that returns the number of arguments that a function takes. -* Examples of what is considered an argument can be found at [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/length) +> Helper function to get function arity -## Usage +See our website [@babel/helper-get-function-arity](https://new.babeljs.io/docs/en/next/babel-helper-get-function-arity.html) for more information. -```javascript -import getFunctionArity from "@babel/helper-get-function-arity"; +## Install -function wrap(state, method, id, scope) { - // ... - if (!t.isFunction(method)) { - return false; - } +Using npm: - const argumentsLength = getFunctionArity(method); - - // ... -} +```sh +npm install --save @babel/helper-get-function-arity +``` + +or using yarn: + +```sh +yarn add --save @babel/helper-get-function-arity ``` diff --git a/packages/babel-helper-hoist-variables/README.md b/packages/babel-helper-hoist-variables/README.md index a00b8559f6..b35e4ad7a2 100644 --- a/packages/babel-helper-hoist-variables/README.md +++ b/packages/babel-helper-hoist-variables/README.md @@ -1,17 +1,19 @@ # @babel/helper-hoist-variables -## Installation +> Helper function to hoist variables + +See our website [@babel/helper-hoist-variables](https://new.babeljs.io/docs/en/next/babel-helper-hoist-variables.html) for more information. + +## Install + +Using npm: ```sh -npm install @babel/helper-hoist-variables --save +npm install --save @babel/helper-hoist-variables ``` -## API +or using yarn: -```javascript -declare export default hoistVariables(path: NodePath, emit: Function, kind: "var" | "let" = "var"); +```sh +yarn add --save @babel/helper-hoist-variables ``` - -## Usage - -TODO diff --git a/packages/babel-helper-member-expression-to-functions/README.md b/packages/babel-helper-member-expression-to-functions/README.md index 7bc38cf6d5..610a023925 100644 --- a/packages/babel-helper-member-expression-to-functions/README.md +++ b/packages/babel-helper-member-expression-to-functions/README.md @@ -1,75 +1,19 @@ # @babel/helper-member-expression-to-functions -Helper function to replace certain member expressions with function calls +> Helper function to replace certain member expressions with function calls -## Usage +See our website [@babel/helper-member-expression-to-functions](https://new.babeljs.io/docs/en/next/babel-helper-member-expression-to-functions.html) for more information. -> Designed for internal Babel use. +## Install -Traverses the `path` using the supplied `visitor` and an augmented `state`. +Using npm: -```js -const visitor = { - MemberExpression(memberPath, state) { - - if (someCondition(memberPath)) { - - // The handle method is supplied by memberExpressionToFunctions. - // It should be called whenever a MemberExpression should be - // converted into the proper function calls. - state.handle(memberPath); - - } - - }, -}; - -// The helper requires three special methods on state: `get`, `set`, and -// `call`. -// Optionally, a special `memoise` method may be defined, which gets -// called if the member is in a self-referential update expression. -// Everything else will be passed through as normal. -const state = { - get(memberPath) { - // Return some AST that will get the member - return t.callExpression( - this.file.addHelper('superGet'), - [t.thisExpression(), memberPath.node.property] - ); - }, - - set(memberPath, value) { - // Return some AST that will set the member - return t.callExpression( - this.file.addHelper('superSet'), - [t.thisExpression(), memberPath.node.property, value] - ); - }, - - call(memberPath, args) { - // Return some AST that will call the member with the proper context - // and args - return t.callExpression( - t.memberExpression(this.get(memberPath), t.identifier("apply")), - [t.thisExpression(), t.arrayExpression(args)] - ); - }, - - memoise(memberPath) { - const { node } = memberPath; - if (node.computed) { - MEMOISED.set(node, ...); - } - }, - - // The handle method is provided by memberExpressionToFunctions. - // handle(memberPath) { ... } - - // Other state stuff is left untouched. - someState: new Set(), -}; - -// Replace all the special MemberExpressions in rootPath, as determined -// by our visitor, using the state methods. -memberExpressionToFunctions(rootPath, visitor, state); +```sh +npm install --save @babel/helper-member-expression-to-functions +``` + +or using yarn: + +```sh +yarn add --save @babel/helper-member-expression-to-functions ``` diff --git a/packages/babel-helper-module-imports/README.md b/packages/babel-helper-module-imports/README.md index 93c134d0fb..18574514e2 100644 --- a/packages/babel-helper-module-imports/README.md +++ b/packages/babel-helper-module-imports/README.md @@ -1,77 +1,19 @@ # @babel/helper-module-imports -## Installation +> Babel helper functions for inserting module loads + +See our website [@babel/helper-module-imports](https://new.babeljs.io/docs/en/next/babel-helper-module-imports.html) for more information. + +## Install + +Using npm: ```sh -npm install @babel/helper-module-imports --save +npm install --save @babel/helper-module-imports ``` -## Usage +or using yarn: -### `import "source"` - -```js -import { addSideEffect } from "@babel/helper-module-imports"; -addSideEffect(path, 'source'); -``` - -### `import { named } from "source"` - -```js -import { addNamed } from "@babel/helper-module-imports"; -addNamed(path, 'named', 'source'); -``` - -### `import { named as _hintedName } from "source"` - -```js -import { addNamed } from "@babel/helper-module-imports"; -addNamed(path, 'named', 'source', { nameHint: "hintedName" }); -``` - -### `import _default from "source"` - -```js -import { addDefault } from "@babel/helper-module-imports"; -addDefault(path, 'source'); -``` - -### `import hintedName from "source"` - -```js -import { addDefault } from "@babel/helper-module-imports"; -addDefault(path, 'source', { nameHint: "hintedName" }) -``` - -### `import * as _namespace from "source"` - -```js -import { addNamespace } from "@babel/helper-module-imports"; -addNamespace(path, 'source'); -``` - -## Examples - -### Adding a named import - -```js -import { addNamed } from "@babel/helper-module-imports"; - -export default function({ types: t }) { - return { - visitor: { - ReferencedIdentifier(path) { - let importName = this.importName; - if (importName) { - importName = t.cloneDeep(importName); - } else { - // require('bluebird').coroutine - importName = this.importName = addNamed(path, 'coroutine', 'bluebird'); - } - - path.replaceWith(importName); - } - }, - }; -} +```sh +yarn add --save @babel/helper-module-imports ``` diff --git a/packages/babel-helper-module-transforms/README.md b/packages/babel-helper-module-transforms/README.md index f828100ee5..bc1f72feaf 100644 --- a/packages/babel-helper-module-transforms/README.md +++ b/packages/babel-helper-module-transforms/README.md @@ -1,5 +1,19 @@ # @babel/helper-module-transforms -## Usage +> Babel helper functions for implementing ES6 module transformations -TODO +See our website [@babel/helper-module-transforms](https://new.babeljs.io/docs/en/next/babel-helper-module-transforms.html) for more information. + +## Install + +Using npm: + +```sh +npm install --save @babel/helper-module-transforms +``` + +or using yarn: + +```sh +yarn add --save @babel/helper-module-transforms +``` diff --git a/packages/babel-helper-optimise-call-expression/README.md b/packages/babel-helper-optimise-call-expression/README.md index 3a35872ec6..a554fe6f5a 100644 --- a/packages/babel-helper-optimise-call-expression/README.md +++ b/packages/babel-helper-optimise-call-expression/README.md @@ -1,5 +1,19 @@ # @babel/helper-optimise-call-expression -## Usage +> Helper function to optimise call expression -TODO +See our website [@babel/helper-optimise-call-expression](https://new.babeljs.io/docs/en/next/babel-helper-optimise-call-expression.html) for more information. + +## Install + +Using npm: + +```sh +npm install --save @babel/helper-optimise-call-expression +``` + +or using yarn: + +```sh +yarn add --save @babel/helper-optimise-call-expression +``` diff --git a/packages/babel-helper-plugin-test-runner/README.md b/packages/babel-helper-plugin-test-runner/README.md index 435725f12a..6828aba47a 100644 --- a/packages/babel-helper-plugin-test-runner/README.md +++ b/packages/babel-helper-plugin-test-runner/README.md @@ -1,17 +1,19 @@ # @babel/helper-plugin-test-runner -**NOTE:** This is an internal Babel module and may not work outside. Use at your own risk. +> Helper function to support test runner -## Usage: +See our website [@babel/helper-plugin-test-runner](https://new.babeljs.io/docs/en/next/babel-helper-plugin-test-runner.html) for more information. -> Check Babel for an example: https://github.com/babel/babel/tree/master/packages/babel-plugin-transform-exponentiation-operator/test +## Install -1. Inside a `/test` directory, add an `index.js` with the contents -```js -import runner from "@babel/helper-plugin-test-runner"; +Using npm: -runner(__dirname); +```sh +npm install --save @babel/helper-plugin-test-runner +``` + +or using yarn: + +```sh +yarn add --save @babel/helper-plugin-test-runner ``` -2. Inside `/test/fixtures`, create a folder for each suite (eg; one suite for each feature of your plugin). -3. Suite folders may contain files and folders. Files will be transformed and run; use `expect()` assertions to verify correct behavior. Folders may contain `input.js`, `output.js`, and/or `exec.js`. The output of transforming `input.js` will be checked to match the contents of `output.js`. `exec.js`, if it exists, will be transformed and run, as with a file in the suite folder. -3. To run a specific test, run `TEST_GREP=testName make test`. [Read more](https://github.com/babel/babel/blob/master/CONTRIBUTING.md#running-lintingtests). diff --git a/packages/babel-helper-plugin-utils/README.md b/packages/babel-helper-plugin-utils/README.md index 4079c2d4e6..afadd83fbc 100644 --- a/packages/babel-helper-plugin-utils/README.md +++ b/packages/babel-helper-plugin-utils/README.md @@ -1,41 +1,19 @@ # @babel/helper-plugin-utils -The intention of this module is to provide a place for us to expose a -standardized API layer over top of what Babel's core API provides on its own. +> General utilities for plugins to use -This is not aiming to implement APIs that are missing on a given Babel version, -but it is means to provide clear error messages if a plugin is run on a version -of Babel that doesn't have the APIs that the plugin is trying to use. +See our website [@babel/helper-plugin-utils](https://new.babeljs.io/docs/en/next/babel-helper-plugin-utils.html) for more information. -Every one of Babel's core plugins and presets will use this module, and ideally -because of that its size should be kept to a miminum because this may or may -not be deduplicated when installed. +## Install +Using npm: -## Usage - -```js -import { declare } from "@babel/helper-plugin-utils"; - -export default declare((api, options, dirname) => { - return {}; -}); +```sh +npm install --save @babel/helper-plugin-utils ``` +or using yarn: -## What this does - -Currently, this plugin provides a few services to ensure that plugins function -well-enough to throw useful errors. - -### `options` is always passed - -Babel 6 does not pass a second parameter. This frequently means that plugins -written for Babel 7 that use `options` will attempt to destructure options -out of an `undefined` value. By supplying the default, we avoid that risk. - -### `api.assertVersion` always exists - -Babel 6 and early betas of Babel 7 do not have `assertVersion`, so this -wrapper ensures that it exists and throws a useful error message when not -supplied by Babel itself. +```sh +yarn add --save @babel/helper-plugin-utils +``` diff --git a/packages/babel-helper-regex/README.md b/packages/babel-helper-regex/README.md index d66d094af9..308a5ac228 100644 --- a/packages/babel-helper-regex/README.md +++ b/packages/babel-helper-regex/README.md @@ -1,5 +1,19 @@ # @babel/helper-regex -## Usage +> Helper function to check for literal RegEx -TODO +See our website [@babel/helper-regex](https://new.babeljs.io/docs/en/next/babel-helper-regex.html) for more information. + +## Install + +Using npm: + +```sh +npm install --save @babel/helper-regex +``` + +or using yarn: + +```sh +yarn add --save @babel/helper-regex +``` diff --git a/packages/babel-helper-remap-async-to-generator/README.md b/packages/babel-helper-remap-async-to-generator/README.md index d1d6ca656f..cdf2d6e4fd 100644 --- a/packages/babel-helper-remap-async-to-generator/README.md +++ b/packages/babel-helper-remap-async-to-generator/README.md @@ -1,5 +1,19 @@ # @babel/helper-remap-async-to-generator -## Usage +> Helper function to remap async functions to generators -TODO +See our website [@babel/helper-remap-async-to-generator](https://new.babeljs.io/docs/en/next/babel-helper-remap-async-to-generator.html) for more information. + +## Install + +Using npm: + +```sh +npm install --save @babel/helper-remap-async-to-generator +``` + +or using yarn: + +```sh +yarn add --save @babel/helper-remap-async-to-generator +``` diff --git a/packages/babel-helper-replace-supers/README.md b/packages/babel-helper-replace-supers/README.md index 4c259e533d..af5798c138 100644 --- a/packages/babel-helper-replace-supers/README.md +++ b/packages/babel-helper-replace-supers/README.md @@ -1,5 +1,19 @@ # @babel/helper-replace-supers -## Usage +> Helper function to replace supers -TODO +See our website [@babel/helper-replace-supers](https://new.babeljs.io/docs/en/next/babel-helper-replace-supers.html) for more information. + +## Install + +Using npm: + +```sh +npm install --save @babel/helper-replace-supers +``` + +or using yarn: + +```sh +yarn add --save @babel/helper-replace-supers +``` diff --git a/packages/babel-helper-simple-access/README.md b/packages/babel-helper-simple-access/README.md index 81660daf75..0f5c57bb84 100644 --- a/packages/babel-helper-simple-access/README.md +++ b/packages/babel-helper-simple-access/README.md @@ -1,26 +1,19 @@ -# @babel/helper-simple-assignment +# @babel/helper-simple-access -There are many cases where it is hard to perform transformations because a -piece of code is using complex structures. Say you want to rewrite all accesses -to a given variable, and there are cases like +> Babel helper for ensuring that access to a given value is performed through simple accesses -``` -i += 1 ---i; +See our website [@babel/helper-simple-access](https://new.babeljs.io/docs/en/next/babel-helper-simple-access.html) for more information. + +## Install + +Using npm: + +```sh +npm install --save @babel/helper-simple-access ``` -It is difficult to work with. - -This helper can handle converting these to simple access patterns of standard -assignment. This plugin does _not_ handle +or using yarn: +```sh +yarn add --save @babel/helper-simple-access ``` -{ a } = foo; -``` - -so assignment to patterns still needs to be handled when you are processing -updates to values. - -## Usage - -TODO diff --git a/packages/babel-helper-split-export-declaration/README.md b/packages/babel-helper-split-export-declaration/README.md index 195f151e92..80d85be18f 100644 --- a/packages/babel-helper-split-export-declaration/README.md +++ b/packages/babel-helper-split-export-declaration/README.md @@ -1,23 +1,19 @@ # @babel/helper-split-export-declaration -## API +> -```js -declare export default splitExportDeclaration(path: NodePath); +See our website [@babel/helper-split-export-declaration](https://new.babeljs.io/docs/en/next/babel-helper-split-export-declaration.html) for more information. + +## Install + +Using npm: + +```sh +npm install --save @babel/helper-split-export-declaration ``` -## Usage +or using yarn: -```js -import traverse from "@babel/traverse"; -import splitExportDeclaration from "@babel/helper-split-export-declaration"; - -// ... - -traverse(file, { - ExportDefaultDeclaration(path) { - if (!path.get("declaration").isClassDeclaration()) return; - splitExportDeclaration(path); - }, -}); +```sh +yarn add --save @babel/helper-split-export-declaration ``` diff --git a/packages/babel-helper-transform-fixture-test-runner/README.md b/packages/babel-helper-transform-fixture-test-runner/README.md index 8fe2837e0e..d9c5df7ec8 100644 --- a/packages/babel-helper-transform-fixture-test-runner/README.md +++ b/packages/babel-helper-transform-fixture-test-runner/README.md @@ -1,11 +1,19 @@ # @babel/helper-transform-fixture-test-runner -**NOTE:** This is an internal Babel module and may not work outside. Use at your own risk. +> Transform test runner for @babel/helper-fixtures module -## Usage +See our website [@babel/helper-transform-fixture-test-runner](https://new.babeljs.io/docs/en/next/babel-helper-transform-fixture-test-runner.html) for more information. -```javascript -import runFixtures from "@babel/helper-transform-fixture-test-runner"; +## Install -runFixtures("/User/sebmck/Projects/babel-something/test/fixtures"); +Using npm: + +```sh +npm install --save @babel/helper-transform-fixture-test-runner +``` + +or using yarn: + +```sh +yarn add --save @babel/helper-transform-fixture-test-runner ``` diff --git a/packages/babel-helper-wrap-function/README.md b/packages/babel-helper-wrap-function/README.md index 25b7eaa25f..060262e38f 100644 --- a/packages/babel-helper-wrap-function/README.md +++ b/packages/babel-helper-wrap-function/README.md @@ -1,27 +1,19 @@ # @babel/helper-wrap-function -This helper wraps a function within a call expression. It works with any function: statements, expressions and methods; both named and anonymous. +> Helper to wrap functions inside a function call. -## Example +See our website [@babel/helper-wrap-function](https://new.babeljs.io/docs/en/next/babel-helper-wrap-function.html) for more information. -**In** +## Install -```js -(function () { -}()); +Using npm: + +```sh +npm install --save @babel/helper-wrap-function ``` -**Out** +or using yarn: -```js -_wrapper(function () { -})(); -``` - -## Usage - -```js -import wrapFunction from "@babel/helper-wrap-function"; - -wrapFunction(nodePathOfTheFunction, nodeWhichReferencesToTheWrapper); +```sh +yarn add --save @babel/helper-wrap-function ``` diff --git a/packages/babel-helpers/README.md b/packages/babel-helpers/README.md index 867a5c9cf6..b1515d7477 100644 --- a/packages/babel-helpers/README.md +++ b/packages/babel-helpers/README.md @@ -2,57 +2,18 @@ > Collection of helper functions used by Babel transforms. +See our website [@babel/helpers](https://new.babeljs.io/docs/en/next/babel-helpers.html) for more information. + ## Install +Using npm: + ```sh -npm install --save-dev @babel/helpers +npm install --save @babel/helpers ``` -## Usage +or using yarn: -Direct: - -```js -import * as helpers from '@babel/helpers'; -import * as t from '@babel/types'; - -const typeofHelper = helpers.get('typeof'); - -t.isExpressionStatement(typeofHelper); -// true -``` - -Inside a plugin: - -```js -export default { - visitor: { - UnaryExpression(path) { - // The .addHelper function adds, if needed, the helper to the file - // and returns an expression which references the helper - const typeofHelper = this.addHelper("typeof"); - t.isExpression(typeofHelper); // true - } -}; -``` - -## Defining Helpers - -> **NOTE**: This package is only meant to be used by the packages included in this repository. There is currently no way for third-party plugins to define a helper. - -Helpers are defined in the `src/helpers.js` file, and they must be valid modules which follow these guidelines: - - They must have a default export, which is their entry-point. - - They can import other helpers, exclusively by using default imports. - - They can't have named exports. - -```js -helpers.customHelper = defineHelper(` - import dep from "dependency"; - - const foo = 2; - - export default function getFooTimesDepPlusX(x) { - return foo * dep() + x; - } -`); +```sh +yarn add --save @babel/helpers ``` diff --git a/packages/babel-highlight/README.md b/packages/babel-highlight/README.md index 36143844eb..27623b84d6 100644 --- a/packages/babel-highlight/README.md +++ b/packages/babel-highlight/README.md @@ -2,40 +2,18 @@ > Syntax highlight JavaScript strings for output in terminals. +See our website [@babel/highlight](https://new.babeljs.io/docs/en/next/babel-highlight.html) for more information. + ## Install +Using npm: + ```sh npm install --save @babel/highlight ``` -## Usage +or using yarn: -```js -import highlight from "@babel/highlight"; - -const code = `class Foo { - constructor() -}`; - -const result = highlight(code); - -console.log(result); -``` - -```js -class Foo { - constructor() -} -``` - -By default, `highlight` will not highlight your code if your terminal does not support color. To force colors, pass `{ forceColor: true }` as the second argument to `highlight`. - -```js -import highlight from "@babel/highlight"; - -const code = `class Foo { - constructor() -}`; - -const result = highlight(code, { forceColor: true }); +```sh +yarn add --save @babel/highlight ``` diff --git a/packages/babel-node/README.md b/packages/babel-node/README.md index c0c903855e..e521ab52d4 100644 --- a/packages/babel-node/README.md +++ b/packages/babel-node/README.md @@ -1,17 +1,19 @@ # @babel/node -> A Babel-powered Node.js CLI +> Babel command line -babel-node is a CLI that works exactly the same as the Node.js CLI, with the added benefit of compiling with Babel presets and plugins before running it. +See our website [@babel/node](https://new.babeljs.io/docs/en/next/babel-node.html) for more information. ## Install -```sh -npm install --save-dev @babel/core @babel/node -``` - -## Usage +Using npm: ```sh -babel-node [options] [ -e script | script.js ] [arguments] +npm install --save @babel/node +``` + +or using yarn: + +```sh +yarn add --save @babel/node ``` diff --git a/packages/babel-parser/README.md b/packages/babel-parser/README.md index 663ed0875f..e4d2bda83f 100644 --- a/packages/babel-parser/README.md +++ b/packages/babel-parser/README.md @@ -1,186 +1,19 @@ -

- @babel/parser -

+# @babel/parser -

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

+> A JavaScript parser - - The latest ECMAScript version enabled by default (ES2017). - - Comment attachment. - - Support for JSX, Flow, Typescript. - - Support for experimental language proposals (accepting PRs for anything at least [stage-0](https://github.com/tc39/proposals/blob/master/stage-0-proposals.md)). +See our website [@babel/parser](https://new.babeljs.io/docs/en/next/babel-parser.html) for more information. -## Credits +## Install -Heavily based on [acorn](https://github.com/marijnh/acorn) and [acorn-jsx](https://github.com/RReverser/acorn-jsx), -thanks to the awesome work of [@RReverser](https://github.com/RReverser) and [@marijnh](https://github.com/marijnh). +Using npm: -## 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 not allowed - outside of an async function. 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**: TODO - -- **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. - -- **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. - -- **plugins**: Array containing the plugins that you want to enable. - -- **strictMode**: TODO - -- **ranges**: Adds a `ranges` 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 - -- [Literal][] token is replaced with [StringLiteral][], [NumericLiteral][], [BooleanLiteral][], [NullLiteral][], [RegExpLiteral][] -- [Property][] token is replaced with [ObjectProperty][] and [ObjectMethod][] -- [MethodDefinition][] is replaced with [ClassMethod][] -- [Program][] and [BlockStatement][] contain additional `directives` field with [Directive][] and [DirectiveLiteral][] -- [ClassMethod][], [ObjectProperty][], and [ObjectMethod][] value property's properties in [FunctionExpression][] is coerced/brought into the main method node. - -AST for JSX code is based on [Facebook JSX AST][]. - -[Babel AST format]: https://github.com/babel/babel/tree/master/packages/babel-parser/ast/spec.md -[ESTree spec]: https://github.com/estree/estree - -[Literal]: https://github.com/estree/estree/blob/master/es5.md#literal -[Property]: https://github.com/estree/estree/blob/master/es5.md#property -[MethodDefinition]: https://github.com/estree/estree/blob/master/es2015.md#methoddefinition - -[StringLiteral]: https://github.com/babel/babel/tree/master/packages/babel-parser/ast/spec.md#stringliteral -[NumericLiteral]: https://github.com/babel/babel/tree/master/packages/babel-parser/ast/spec.md#numericliteral -[BooleanLiteral]: https://github.com/babel/babel/tree/master/packages/babel-parser/ast/spec.md#booleanliteral -[NullLiteral]: https://github.com/babel/babel/tree/master/packages/babel-parser/ast/spec.md#nullliteral -[RegExpLiteral]: https://github.com/babel/babel/tree/master/packages/babel-parser/ast/spec.md#regexpliteral -[ObjectProperty]: https://github.com/babel/babel/tree/master/packages/babel-parser/ast/spec.md#objectproperty -[ObjectMethod]: https://github.com/babel/babel/tree/master/packages/babel-parser/ast/spec.md#objectmethod -[ClassMethod]: https://github.com/babel/babel/tree/master/packages/babel-parser/ast/spec.md#classmethod -[Program]: https://github.com/babel/babel/tree/master/packages/babel-parser/ast/spec.md#programs -[BlockStatement]: https://github.com/babel/babel/tree/master/packages/babel-parser/ast/spec.md#blockstatement -[Directive]: https://github.com/babel/babel/tree/master/packages/babel-parser/ast/spec.md#directive -[DirectiveLiteral]: https://github.com/babel/babel/tree/master/packages/babel-parser/ast/spec.md#directiveliteral -[FunctionExpression]: https://github.com/babel/babel/tree/master/packages/babel-parser/ast/spec.md#functionexpression - -[Facebook JSX AST]: https://github.com/facebook/jsx/blob/master/AST.md - -### 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](https://github.com/babel/babylon/pull/107) - multiple default exports per file. That would be considered a bug fix even though it would cause a build to fail. - -### Example - -```javascript -require("@babel/parser").parse("code", { - // parse in strict mode and allow module declarations - sourceType: "module", - - plugins: [ - // enable jsx and flow syntax - "jsx", - "flow" - ] -}); +```sh +npm install --save @babel/parser ``` -### Plugins +or using yarn: -| Name | Code Example | -|------|--------------| -| `estree` ([repo](https://github.com/estree/estree)) | n/a | -| `jsx` ([repo](https://facebook.github.io/jsx/)) | `{s}` | -| `flow` ([repo](https://github.com/facebook/flow)) | `var a: string = "";` | -| `flowComments` ([docs](https://flow.org/en/docs/types/comments/)) | `/*:: type Foo = {...}; */` | -| `typescript` ([repo](https://github.com/Microsoft/TypeScript)) | `var a: string = "";` | -| `doExpressions` | `var a = do { if (true) { 'hi'; } };` | -| `objectRestSpread` ([proposal](https://github.com/tc39/proposal-object-rest-spread)) | `var a = { b, ...c };` | -| `decorators` (Stage 2 [proposal](https://github.com/tc39/proposal-decorators)) and `decorators-legacy` (Stage 1) | `@a class A {}` | -| `classProperties` ([proposal](https://github.com/tc39/proposal-class-public-fields)) | `class A { b = 1; }` | -| `classPrivateProperties` ([proposal](https://github.com/tc39/proposal-private-fields)) | `class A { #b = 1; }` | -| `classPrivateMethods` ([proposal](https://github.com/tc39/proposal-private-methods)) | `class A { #c() {} }` | -| `exportDefaultFrom` ([proposal](https://github.com/leebyron/ecmascript-export-default-from)) | `export v from "mod"` | -| `exportNamespaceFrom` ([proposal](https://github.com/leebyron/ecmascript-export-ns-from)) | `export * as ns from "mod"` | -| `asyncGenerators` ([proposal](https://github.com/tc39/proposal-async-iteration)) | `async function*() {}`, `for await (let a of b) {}` | -| `functionBind` ([proposal](https://github.com/zenparsing/es-function-bind)) | `a::b`, `::console.log` | -| `functionSent` | `function.sent` | -| `dynamicImport` ([proposal](https://github.com/tc39/proposal-dynamic-import)) | `import('./guy').then(a)` | -| `numericSeparator` ([proposal](https://github.com/samuelgoto/proposal-numeric-separator)) | `1_000_000` | -| `optionalChaining` ([proposal](https://github.com/tc39/proposal-optional-chaining)) | `a?.b` | -| `importMeta` ([proposal](https://github.com/tc39/proposal-import-meta)) | `import.meta.url` | -| `bigInt` ([proposal](https://github.com/tc39/proposal-bigint)) | `100n` | -| `optionalCatchBinding` ([proposal](https://github.com/babel/proposals/issues/7)) | `try {throw 0;} catch{do();}` | -| `throwExpressions` ([proposal](https://github.com/babel/proposals/issues/23)) | `() => throw new Error("")` | -| `pipelineOperator` ([proposal](https://github.com/babel/proposals/issues/29)) | `a \|> b` | -| `nullishCoalescingOperator` ([proposal](https://github.com/babel/proposals/issues/14)) | `a ?? b` | - - -#### Plugins options - -> NOTE: When a plugin is specified multiple times, only the first options are considered. - -- `decorators`: - - `decoratorsBeforeExport` (`boolean`) - ```js - // decoratorsBeforeExport: true - @dec - export class C {} - - // decoratorsBeforeExport: false - export @dec class C {} - ``` -- `flow`: - - `all` (`boolean`) - - -### FAQ - -#### Will the Babel parser support a plugin system? - -Previous issues: [#1351](https://github.com/babel/babel/issues/1351), [#6694](https://github.com/babel/babel/issues/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 to your `.babelrc` via its npm package name or require it if using JavaScript, - -```json -{ - "parserOpts": { - "parser": "custom-fork-of-babel-parser-on-npm-here" - } -} +```sh +yarn add --save @babel/parser ``` diff --git a/packages/babel-plugin-external-helpers/README.md b/packages/babel-plugin-external-helpers/README.md index 251f5e7fe8..1d8c961f72 100644 --- a/packages/babel-plugin-external-helpers/README.md +++ b/packages/babel-plugin-external-helpers/README.md @@ -1,33 +1,19 @@ # @babel/plugin-external-helpers -## Installation +> This plugin contains helper functions that’ll be placed at the top of the generated code + +See our website [@babel/plugin-external-helpers](https://new.babeljs.io/docs/en/next/babel-plugin-external-helpers.html) for more information. + +## Install + +Using npm: ```sh -npm install --save-dev @babel/plugin-external-helpers +npm install --save @babel/plugin-external-helpers ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-external-helpers"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-external-helpers script.js -``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-external-helpers"] -}); +yarn add --save @babel/plugin-external-helpers ``` diff --git a/packages/babel-plugin-proposal-async-generator-functions/README.md b/packages/babel-plugin-proposal-async-generator-functions/README.md index 543d5bfc66..acba780c6f 100644 --- a/packages/babel-plugin-proposal-async-generator-functions/README.md +++ b/packages/babel-plugin-proposal-async-generator-functions/README.md @@ -1,107 +1,19 @@ # @babel/plugin-proposal-async-generator-functions -> Turn async generator functions and for-await statements to ES2015 generators +> Turn async generator functions into ES2015 generators -## Example +See our website [@babel/plugin-proposal-async-generator-functions](https://new.babeljs.io/docs/en/next/babel-plugin-proposal-async-generator-functions.html) for more information. -**In** +## Install -```javascript -async function* agf() { - await 1; - yield 2; -} -``` - -**Out** - -```javascript -var _asyncGenerator = ... - -let agf = (() => { - var _ref = _asyncGenerator.wrap(function* () { - yield _asyncGenerator.await(1); - yield 2; - }); - - return function agf() { - return _ref.apply(this, arguments); - }; -})(); -``` - -For await example - -```js -async function f() { - for await (let x of y) { - g(x); - } -} -``` - -**Example Usage** - -```js -async function* genAnswers() { - var stream = [ Promise.resolve(4), Promise.resolve(9), Promise.resolve(12) ]; - var total = 0; - for await (let val of stream) { - total += await val; - yield total; - } -} - -function forEach(ai, fn) { - return ai.next().then(function (r) { - if (!r.done) { - fn(r); - return forEach(ai, fn); - } - }); -} - -var output = 0; -forEach(genAnswers(), function(val) { output += val.value }) -.then(function () { - console.log(output); // 42 -}); -``` - -[Try it Out in the REPL](https://babeljs.io/repl/#?babili=false&evaluate=true&lineWrap=false&presets=stage-3&code=async%20function*%20genAnswers()%20%7B%0A%20%20var%20stream%20%3D%20%5B%20Promise.resolve(4)%2C%20Promise.resolve(9)%2C%20Promise.resolve(12)%20%5D%3B%0A%20%20var%20total%20%3D%200%3B%0A%20%20for%20await%20(let%20val%20of%20stream)%20%7B%0A%20%20%20%20total%20%2B%3D%20await%20val%3B%0A%20%20%20%20yield%20total%3B%0A%20%20%7D%0A%7D%0A%0Afunction%20forEach(ai%2C%20fn)%20%7B%0A%20%20return%20ai.next().then(function%20(r)%20%7B%0A%20%20%20%20if%20(!r.done)%20%7B%0A%20%20%20%20%20%20fn(r)%3B%0A%20%20%20%20%20%20return%20forEach(ai%2C%20fn)%3B%0A%20%20%20%20%7D%0A%20%20%7D)%3B%0A%7D%0A%0Avar%20output%20%3D%200%3B%0AforEach(genAnswers()%2C%20function(val)%20%7B%20output%20%2B%3D%20val.value%20%7D)%0A.then(function%20()%20%7B%0A%20%20console.log(output)%3B%20%2F%2F%2042%0A%7D)%3B&experimental=true&loose=false&spec=false&playground=true&stage=0) - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-proposal-async-generator-functions +npm install --save @babel/plugin-proposal-async-generator-functions ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-proposal-async-generator-functions"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-proposal-async-generator-functions script.js +yarn add --save @babel/plugin-proposal-async-generator-functions ``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-proposal-async-generator-functions"] -}); -``` - -## References - -* [Proposal: Asynchronous iteration for ECMAScript](https://github.com/tc39/proposal-async-iteration) diff --git a/packages/babel-plugin-proposal-class-properties/README.md b/packages/babel-plugin-proposal-class-properties/README.md index dee62c852e..277f10b1bf 100644 --- a/packages/babel-plugin-proposal-class-properties/README.md +++ b/packages/babel-plugin-proposal-class-properties/README.md @@ -1,149 +1,19 @@ # @babel/plugin-proposal-class-properties -> This plugin transforms class properties +> This plugin transforms static class properties as well as properties declared with the property initializer syntax -## Example +See our website [@babel/plugin-proposal-class-properties](https://new.babeljs.io/docs/en/next/babel-plugin-proposal-class-properties.html) for more information. -Below is a class with four class properties which will be transformed. +## Install -```js - class Bork { - //Property initializer syntax - instanceProperty = "bork"; - boundFunction = () => { - return this.instanceProperty; - }; - - //Static class properties - static staticProperty = "babelIsCool"; - static staticFunction = function() { - return Bork.staticProperty; - }; - } - - let myBork = new Bork; - - //Property initializers are not on the prototype. - console.log(myBork.__proto__.boundFunction); // > undefined - - //Bound functions are bound to the class instance. - console.log(myBork.boundFunction.call(undefined)); // > "bork" - - //Static function exists on the class. - console.log(Bork.staticFunction()); // > "babelIsCool" -``` - - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-proposal-class-properties +npm install --save @babel/plugin-proposal-class-properties ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -Without options: - -```json -{ - "plugins": ["@babel/plugin-proposal-class-properties"] -} -``` - -With options: - -```json -{ - "plugins": [ - ["@babel/plugin-proposal-class-properties", { "loose": true }] - ] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-proposal-class-properties script.js +yarn add --save @babel/plugin-proposal-class-properties ``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-proposal-class-properties"] -}); -``` - -## Options - -### `loose` - -`boolean`, defaults to `false`. - -When `true`, class properties are compiled to use an assignment expression instead of `Object.defineProperty`. - -#### Example - -```js - class Bork { - static a = 'foo'; - static b; - - x = 'bar'; - y; - } -``` - -Without `{ "loose": true }`, the above code will compile to the following, using `Object.defineProperty`: - -```js -var Bork = function Bork() { - babelHelpers.classCallCheck(this, Bork); - Object.defineProperty(this, "x", { - configurable: true, - enumerable: true, - writable: true, - value: 'bar' - }); - Object.defineProperty(this, "y", { - configurable: true, - enumerable: true, - writable: true, - value: void 0 - }); -}; - -Object.defineProperty(Bork, "a", { - configurable: true, - enumerable: true, - writable: true, - value: 'foo' -}); -Object.defineProperty(Bork, "b", { - configurable: true, - enumerable: true, - writable: true, - value: void 0 -}); -``` - -However, with `{ "loose": true }`, it will compile using assignment expressions: - -```js -var Bork = function Bork() { - babelHelpers.classCallCheck(this, Bork); - this.x = 'bar'; - this.y = void 0; -}; - -Bork.a = 'foo'; -Bork.b = void 0; -``` - -## References - -* [Proposal: ES Class Fields & Static Properties](https://github.com/jeffmo/es-class-static-properties-and-fields) diff --git a/packages/babel-plugin-proposal-decorators/README.md b/packages/babel-plugin-proposal-decorators/README.md index 3411b3708d..4c024b4708 100644 --- a/packages/babel-plugin-proposal-decorators/README.md +++ b/packages/babel-plugin-proposal-decorators/README.md @@ -2,142 +2,18 @@ > Compile class and object decorators to ES5 -## Example +See our website [@babel/plugin-proposal-decorators](https://new.babeljs.io/docs/en/next/babel-plugin-proposal-decorators.html) for more information. -(examples are from proposal) +## Install -### Simple class decorator - -```js -@annotation -class MyClass { } - -function annotation(target) { - target.annotated = true; -} -``` - -### Class decorator - -```js -@isTestable(true) -class MyClass { } - -function isTestable(value) { - return function decorator(target) { - target.isTestable = value; - } -} -``` - -### Class function decorator - -```js -class C { - @enumerable(false) - method() { } -} - -function enumerable(value) { - return function (target, key, descriptor) { - descriptor.enumerable = value; - return descriptor; - } -} -``` - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-proposal-decorators +npm install --save @babel/plugin-proposal-decorators ``` -## Usage - -Add the following line to your .babelrc file: - -```json -{ - "plugins": ["@babel/plugin-proposal-decorators"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-proposal-decorators script.js +yarn add --save @babel/plugin-proposal-decorators ``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-proposal-decorators"] -}); -``` - -## Options - -### `decoratorsBeforeExport` - -`boolean`, defaults to `true`. - -```js -// decoratorsBeforeExport: true -@decorator -export class Foo {} - -// decoratorsBeforeExport: false -export @decorator class Bar {} -``` - -This option was added to help tc39 collect feedback from the community by allowing experimentation with both possible syntaxes. - -For more information, check out: [tc39/proposal-decorators#69](https://github.com/tc39/proposal-decorators/issues/69). - -### `legacy` - -`boolean`, defaults to `false`. - -Use the legacy (stage 1) decorators syntax and behavior. - -#### NOTE: Compatibility with `@babel/plugin-proposal-class-properties` - -If you are including your plugins manually and using `@babel/plugin-proposal-class-properties`, make sure that `@babel/plugin-proposal-decorators` comes *before* `@babel/plugin-proposal-class-properties`. - -When using the `legacy: true` mode, `@babel/plugin-proposal-class-properties` must be used in `loose` mode to support the `@babel/plugin-proposal-decorators`. - -Wrong: - -```json -{ - "plugins": [ - "@babel/plugin-proposal-class-properties", - "@babel/plugin-proposal-decorators" - ] -} -``` - -Right: - -```json -{ - "plugins": [ - "@babel/plugin-proposal-decorators", - "@babel/plugin-proposal-class-properties" - ] -} -``` - -```json -{ - "plugins": [ - ["@babel/plugin-proposal-decorators", { "legacy": true }], - ["@babel/plugin-proposal-class-properties", { "loose" : true }] - ] -} -``` - -## References - -* [Proposal: JavaScript Decorators](https://github.com/wycats/javascript-decorators/blob/master/README.md) diff --git a/packages/babel-plugin-proposal-do-expressions/README.md b/packages/babel-plugin-proposal-do-expressions/README.md index 177c9dc22e..744735880f 100644 --- a/packages/babel-plugin-proposal-do-expressions/README.md +++ b/packages/babel-plugin-proposal-do-expressions/README.md @@ -1,118 +1,19 @@ # @babel/plugin-proposal-do-expressions -> Compile `do` expressions to ES5 +> Compile do expressions to ES5 -## Detail +See our website [@babel/plugin-proposal-do-expressions](https://new.babeljs.io/docs/en/next/babel-plugin-proposal-do-expressions.html) for more information. -> The `do { .. }` expression executes a block (with one or many statements in it), and the final statement completion value inside the block becomes the completion value of the do expression. +## Install -from [You Don't Know JS](https://github.com/getify/You-Dont-Know-JS/blob/master/types%20%26%20grammar/ch5.md#statement-completion-values) - -It can be seen as a complex version of the [ternary operator](http://mdn.io/ternary): - -```js -let a = do { - if(x > 10) { - 'big'; - } else { - 'small'; - } -}; -// is equivalent to: -let a = x > 10 ? 'big' : 'small'; -``` - - -This example is not the best usage because it is too simple and using a ternary operator is a better option but you can have a much more complex condition in the `do { ... }` expression with several `if ... else` chains: - -```js -let x = 100; -let y = 20; - -let a = do { - if(x > 10) { - if(y > 20) { - 'big x, big y'; - } else { - 'big x, small y'; - } - } else { - if(y > 10) { - 'small x, big y'; - } else { - 'small x, small y'; - } - } -}; -``` - -## Example - -### In JSX -One of the most useful usage of the `do` expression is inside JSX. If we want to conditionally display a component we usually have to call another function which would implement the condition and return the correct value, for example: - -```js -const getColoredComponent = color => { - if(color === 'blue') { return ; } - if(color === 'red') { return ; } - if(color === 'green') { return ; } -} - -const Component = props => -
- {getColoredComponent()} -
-; -``` - -Using a do expression you can add logic inside JSX: - -```js -const Component = props => -
- {do { - if(color === 'blue') { ; } - else if(color === 'red') { ; } - else if(color === 'green') { ; } - }} -
-; -``` - - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-proposal-do-expressions +npm install --save @babel/plugin-proposal-do-expressions ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-proposal-do-expressions"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-proposal-do-expressions script.js +yarn add --save @babel/plugin-proposal-do-expressions ``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-proposal-do-expressions"] -}); -``` - -## References -- [Proposal](https://github.com/tc39/proposal-do-expressions) -- [You Don't Know JS](https://github.com/getify/You-Dont-Know-JS/blob/master/types%20%26%20grammar/ch5.md#statement-completion-values) -- Very handy for conditions inside JSX: [reactjs/react-future#35](https://github.com/reactjs/react-future/issues/35#issuecomment-120009203) diff --git a/packages/babel-plugin-proposal-export-default-from/README.md b/packages/babel-plugin-proposal-export-default-from/README.md index 6670c14ee6..280e20bdcb 100644 --- a/packages/babel-plugin-proposal-export-default-from/README.md +++ b/packages/babel-plugin-proposal-export-default-from/README.md @@ -1,45 +1,19 @@ # @babel/plugin-proposal-export-default-from -> Compile export-default-from statements to ES2015 +> Compile export default to ES2015 -## Example +See our website [@babel/plugin-proposal-export-default-from](https://new.babeljs.io/docs/en/next/babel-plugin-proposal-export-default-from.html) for more information. -```js -export v from 'mod'; -``` +## Install -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-proposal-export-default-from +npm install --save @babel/plugin-proposal-export-default-from ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-proposal-export-default-from"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-proposal-export-default-from script.js +yarn add --save @babel/plugin-proposal-export-default-from ``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-proposal-export-default-from"] -}); -``` -## References - -* ~~[Proposal: Additional export-from statements in ES7](https://github.com/leebyron/ecmascript-more-export-from)~~ (Withdrawn) -* [ECMAScript Proposal: export default from](https://github.com/leebyron/ecmascript-export-default-from) diff --git a/packages/babel-plugin-proposal-export-namespace-from/README.md b/packages/babel-plugin-proposal-export-namespace-from/README.md index bb4ff7890e..402b34b7bb 100644 --- a/packages/babel-plugin-proposal-export-namespace-from/README.md +++ b/packages/babel-plugin-proposal-export-namespace-from/README.md @@ -1,45 +1,19 @@ # @babel/plugin-proposal-export-namespace-from -> Compile export-ns-from statements to ES2015 +> Compile export namespace to ES2015 -## Example +See our website [@babel/plugin-proposal-export-namespace-from](https://new.babeljs.io/docs/en/next/babel-plugin-proposal-export-namespace-from.html) for more information. -```js -export * as ns from 'mod'; -``` +## Install -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-proposal-export-namespace-from +npm install --save @babel/plugin-proposal-export-namespace-from ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-proposal-export-namespace-from"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-proposal-export-namespace-from script.js +yarn add --save @babel/plugin-proposal-export-namespace-from ``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-proposal-export-namespace-from"] -}); -``` -## References - -* ~~[Proposal: Additional export-from statements in ES7](https://github.com/leebyron/ecmascript-more-export-from)~~ (Withdrawn) -* [ECMAScript Proposal: export ns from](https://github.com/leebyron/ecmascript-export-ns-from) diff --git a/packages/babel-plugin-proposal-function-bind/README.md b/packages/babel-plugin-proposal-function-bind/README.md index 15552e68f6..e7f2301e1c 100644 --- a/packages/babel-plugin-proposal-function-bind/README.md +++ b/packages/babel-plugin-proposal-function-bind/README.md @@ -1,121 +1,19 @@ # @babel/plugin-proposal-function-bind -> Compile the new function bind operator `::` to ES5. +> Compile function bind operator to ES5 -## Detail +See our website [@babel/plugin-proposal-function-bind](https://new.babeljs.io/docs/en/next/babel-plugin-proposal-function-bind.html) for more information. -```js -obj::func -// is equivalent to: -func.bind(obj) +## Install -::obj.func -// is equivalent to: -obj.func.bind(obj) - -obj::func(val) -// is equivalent to: -func.call(obj, val) - -::obj.func(val) -// is equivalent to: -obj.func.call(obj, val) -``` - - -## Example - -### Basic - -```js -const box = { - weight: 2, - getWeight() { return this.weight; }, -}; - -const { getWeight } = box; - -console.log(box.getWeight()); // prints '2' - -const bigBox = { weight: 10 }; -console.log(bigBox::getWeight()); // prints '10' - -// Can be chained: -function add(val) { return this + val; } - -console.log(bigBox::getWeight()::add(5)); // prints '15' -``` - - -### Using with `document.querySelectorAll` - -It can be very handy when used with `document.querySelectorAll`: - -```js -const { map, filter } = Array.prototype; - -let sslUrls = document.querySelectorAll('a') - ::map(node => node.href) - ::filter(href => href.substring(0, 5) === 'https'); - -console.log(sslUrls); -``` - - -`document.querySelectorAll` returns a `NodeList` element which is not a plain array, so you normally can't use the `map` function on it, and have to use it this way: `Array.prototype.map.call(document.querySelectorAll(...), node => { ... })`. The above code using the `::` will work because it is equivalent to: - -```js -const { map, filter } = Array.prototype; - -let sslUrls = document.querySelectorAll('a'); -sslUrls = map.call(sslUrls, node => node.href); -sslUrls = filter.call(sslUrls, href => href.substring(0, 5) === 'https'); - -console.log(sslUrls); -``` - -### Auto self binding -When nothing is specified before the `::` operator, the function is bound to its object: - -```js -$('.some-link').on('click', ::view.reset); -// is equivalent to: -$('.some-link').on('click', view.reset.bind(view)); -``` - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-proposal-function-bind +npm install --save @babel/plugin-proposal-function-bind ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-proposal-function-bind"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-proposal-function-bind script.js +yarn add --save @babel/plugin-proposal-function-bind ``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-proposal-function-bind"] -}); -``` - -## References - -* [Proposal](https://github.com/zenparsing/es-function-bind) -* [Babel Blog: Function Bind Syntax](/blog/2015/05/14/function-bind) diff --git a/packages/babel-plugin-proposal-function-sent/README.md b/packages/babel-plugin-proposal-function-sent/README.md index 9c4984919d..06a6a59607 100644 --- a/packages/babel-plugin-proposal-function-sent/README.md +++ b/packages/babel-plugin-proposal-function-sent/README.md @@ -1,66 +1,19 @@ # @babel/plugin-proposal-function-sent -> Compile the `function.sent` meta property, used inside generator functions, to valid ES2015 code. +> Compile the function.sent meta propety to valid ES2015 code -## Example +See our website [@babel/plugin-proposal-function-sent](https://new.babeljs.io/docs/en/next/babel-plugin-proposal-function-sent.html) for more information. -```js -function* generator() { - console.log("Sent", function.sent); - console.log("Yield", yield); -} +## Install -const iterator = generator(); -iterator.next(1); // Logs "Sent 1" -iterator.next(2); // Logs "Yield 2" -``` - -Is compiled roughly to - -```js -let generator = _skipFirstGeneratorNext(function* () { - const _functionSent = yield; - console.log("Sent", _functionSent); - console.log("Yield", yield); -}); - -const iterator = generator(); -iterator.next(1); // Logs "Sent 1" -iterator.next(2); // Logs "Yield 1" -``` - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-proposal-function-sent +npm install --save @babel/plugin-proposal-function-sent ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-proposal-function-sent"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-proposal-function-sent script.js +yarn add --save @babel/plugin-proposal-function-sent ``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-proposal-function-sent"] -}); -``` - -## References - -* [Proposal](https://github.com/allenwb/ESideas/blob/master/Generator%20metaproperty.md) diff --git a/packages/babel-plugin-proposal-json-strings/README.md b/packages/babel-plugin-proposal-json-strings/README.md index 4fc0a7fc09..30120c868e 100644 --- a/packages/babel-plugin-proposal-json-strings/README.md +++ b/packages/babel-plugin-proposal-json-strings/README.md @@ -1,54 +1,19 @@ -# @babel/plugin-syntax-json-strings +# @babel/plugin-proposal-json-strings -Allow parsing of the U+2028 LINE SEPARATOR and U+2029 PARAGRAPH SEPARATOR in JS strings +> Escape U+2028 LINE SEPARATOR and U+2029 PARAGRAPH SEPARATOR in JS strings -## Examples +See our website [@babel/plugin-proposal-json-strings](https://new.babeljs.io/docs/en/next/babel-plugin-proposal-json-strings.html) for more information. -**In** +## Install -```js -const ex = "before
after"; -// ^ There's a U+2028 char between 'before' and 'after' -``` - -**Out** - -```js -const ex = "before\u2028after"; -// ^ There's a U+2028 char between 'before' and 'after' -``` - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-proposal-json-strings +npm install --save @babel/plugin-proposal-json-strings ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-proposal-json-strings"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-proposal-json-strings script.js +yarn add --save @babel/plugin-proposal-json-strings ``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-proposal-json-strings"] -}); -``` - -## References -- [Proposal: Optional Catch Binding for ECMAScript](https://github.com/babel/proposals/issues/7) diff --git a/packages/babel-plugin-proposal-logical-assignment-operators/README.md b/packages/babel-plugin-proposal-logical-assignment-operators/README.md index 26fbaddfb7..70e8c4612a 100644 --- a/packages/babel-plugin-proposal-logical-assignment-operators/README.md +++ b/packages/babel-plugin-proposal-logical-assignment-operators/README.md @@ -1,63 +1,19 @@ -# @babel/plugin-proposal-logical-assignment-operator +# @babel/plugin-proposal-logical-assignment-operators > Transforms logical assignment operators into short-circuited assignments -## Example +See our website [@babel/plugin-proposal-logical-assignment-operators](https://new.babeljs.io/docs/en/next/babel-plugin-proposal-logical-assignment-operators.html) for more information. -**In** +## Install -```javascript -a ||= b; -obj.a.b ||= c; - -a &&= b; -obj.a.b &&= c; -``` - -**Out** - -```javascript -var _obj$a, _obj$a2; - -a || (a = b); -(_obj$a = obj.a).b || (_obj$a.b = c); - -a && (a = b); -(_obj$a2 = obj.a).b && (_obj$a2.b = c); -``` - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-proposal-logical-assignment-operators +npm install --save @babel/plugin-proposal-logical-assignment-operators ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-proposal-logical-assignment-operators"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-proposal-logical-assignment-operators script.js +yarn add --save @babel/plugin-proposal-logical-assignment-operators ``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-proposal-logical-assignment-operators"] -}); -``` - -## References - -* [Proposal: Logical Assignment Operators](https://github.com/jridgewell/proposal-logical-assignment-operators) diff --git a/packages/babel-plugin-proposal-nullish-coalescing-operator/README.md b/packages/babel-plugin-proposal-nullish-coalescing-operator/README.md index 2b01b5f2a8..690ed09f7d 100644 --- a/packages/babel-plugin-proposal-nullish-coalescing-operator/README.md +++ b/packages/babel-plugin-proposal-nullish-coalescing-operator/README.md @@ -1,84 +1,19 @@ # @babel/plugin-proposal-nullish-coalescing-operator -> Replace `??` with an inline helper. +> Remove nullish coalescing operator -## Example +See our website [@babel/plugin-proposal-nullish-coalescing-operator](https://new.babeljs.io/docs/en/next/babel-plugin-proposal-nullish-coalescing-operator.html) for more information. -**In** +## Install -```javascript -var foo = object.foo ?? "default"; -``` - -**Out** - -```javascript -var _object$foo; - -var foo = (_object$foo = object.foo) !== null && _object$foo !== void 0 ? _object$foo : "default"; -``` - -> **NOTE:** We cannot use `!= null` here because `document.all == null` and -> `document.all` has been deemed not "nullish". - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-proposal-nullish-coalescing-operator +npm install --save @babel/plugin-proposal-nullish-coalescing-operator ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-proposal-nullish-coalescing-operator"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-proposal-nullish-coalescing-operator script.js +yarn add --save @babel/plugin-proposal-nullish-coalescing-operator ``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-proposal-nullish-coalescing-operator"] -}); -``` - -## Options - -### `loose` - -`boolean`, defaults to `false`. - -When `true`, this transform will pretend `document.all` does not exist, -and perform loose equality checks with `null` instead of strict equality checks -against both `null` and `undefined`. - -#### Example - -**In** - -```javascript -var foo = object.foo ?? "default"; -``` - -**Out** - -```javascript -var _object$foo; - -var foo = (_object$foo = object.foo) != null ? _object$foo : "default"; -``` - -## References - -* [Proposal: Nullish Coalescing](https://github.com/tc39-transfer/proposal-nullish-coalescing) diff --git a/packages/babel-plugin-proposal-numeric-separator/README.md b/packages/babel-plugin-proposal-numeric-separator/README.md index 4dcde02319..38a3c6385d 100644 --- a/packages/babel-plugin-proposal-numeric-separator/README.md +++ b/packages/babel-plugin-proposal-numeric-separator/README.md @@ -1,114 +1,19 @@ # @babel/plugin-proposal-numeric-separator -> This plugin allows Babel to transform Decimal, Binary, Hex and Octal literals containing Numeric Literal Separator to their non-separated form. +> Remove numeric separators from Decimal, Binary, Hex and Octal literals -## Example +See our website [@babel/plugin-proposal-numeric-separator](https://new.babeljs.io/docs/en/next/babel-plugin-proposal-numeric-separator.html) for more information. -### Decimal Literals +## Install -```js -let budget = 1_000_000_000_000; - -// What is the value of `budget`? It's 1 trillion! -// -// Let's confirm: -console.log(budget === 10 ** 12); // true -``` - -### Binary Literals - -```js -let nibbles = 0b1010_0001_1000_0101; - -// Is bit 7 on? It sure is! -// 0b1010_0001_1000_0101 -// ^ -// -// We can double check: -console.log(!!(nibbles & (1 << 7))); // true -``` - -### Hex Literal - -```js -// Messages are sent as 24 bit values, but should be -// treated as 3 distinct bytes: -let message = 0xA0_B0_C0; - -// What's the value of the upper most byte? It's A0, or 160. -// We can confirm that: -let a = (message >> 16) & 0xFF; -console.log(a.toString(16), a); // a0, 160 - -// What's the value of the middle byte? It's B0, or 176. -// Let's just make sure... -let b = (message >> 8) & 0xFF; -console.log(b.toString(16), b); // b0, 176 - -// What's the value of the lower most byte? It's C0, or 192. -// Again, let's prove that: -let c = message & 0xFF; -console.log(c.toString(16), b); // c0, 192 -``` - -### Octal Literal - -*hand wave emoji* - -Octals are great for permissions, but also look better when represented in `0o0000` form. No real benefit with separators here. - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-proposal-numeric-separator +npm install --save @babel/plugin-proposal-numeric-separator ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-proposal-numeric-separator"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-proposal-numeric-separator script.js +yarn add --save @babel/plugin-proposal-numeric-separator ``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-proposal-numeric-separator"] -}); -``` - -## Additional Information - -If you need to further compile ES2015 Decimal, Binary, Hex and Octal number representations to their pre-ES2015 numeric literal form, add the [`"@babel/plugin-transform-literals"`](http://babeljs.io/docs/plugins/transform-literals/) plugin: - -> `@babel/plugin-transform-literals` is already included in [@babel/preset-env](https://github.com/babel/babel/tree/master/packages/babel-preset-env) and @babel/preset-es2015. - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "presets": ["@babel/preset-env"], - "plugins": ["@babel/plugin-proposal-numeric-separator"] -} -{ - "plugins": ["@babel/plugin-proposal-numeric-separator", "@babel/plugin-transform-literals"] -} -``` - -## References - -* [Proposal: Numeric Separators](https://github.com/samuelgoto/proposal-numeric-separator) diff --git a/packages/babel-plugin-proposal-object-rest-spread/README.md b/packages/babel-plugin-proposal-object-rest-spread/README.md index 9c1b785b94..d3f5c42cf3 100644 --- a/packages/babel-plugin-proposal-object-rest-spread/README.md +++ b/packages/babel-plugin-proposal-object-rest-spread/README.md @@ -1,105 +1,19 @@ # @babel/plugin-proposal-object-rest-spread -> This plugin allows Babel to transform rest properties for object destructuring assignment and spread properties for object literals. +> Compile object rest and spread to ES5 -## Example +See our website [@babel/plugin-proposal-object-rest-spread](https://new.babeljs.io/docs/en/next/babel-plugin-proposal-object-rest-spread.html) for more information. -### Rest Properties +## Install -```js -let { x, y, ...z } = { x: 1, y: 2, a: 3, b: 4 }; -console.log(x); // 1 -console.log(y); // 2 -console.log(z); // { a: 3, b: 4 } -``` - -### Spread Properties - -```js -let n = { x, y, ...z }; -console.log(n); // { x: 1, y: 2, a: 3, b: 4 } -``` - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-proposal-object-rest-spread +npm install --save @babel/plugin-proposal-object-rest-spread ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-proposal-object-rest-spread"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-proposal-object-rest-spread script.js +yarn add --save @babel/plugin-proposal-object-rest-spread ``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-proposal-object-rest-spread"] -}); -``` - -## Options - -By default, this plugin will produce spec compliant code by using Babel's `objectSpread` helper. - -### `loose` - -`boolean`, defaults to `false`. - -Enabling this option will use Babel's `extends` helper, which is basically the same as `Object.assign` (see `useBuiltIns` below to use it directly). - -:warning: Please keep in mind that even if they're almost equivalent, there's an important difference between spread and `Object.assign`: **spread _defines_ new properties, while `Object.assign()` _sets_ them**, so using this mode might produce unexpected results in some cases. - -For detailed information please check out [Spread VS. Object.assign](http://2ality.com/2016/10/rest-spread-properties.html#spreading-objects-versus-objectassign) and [Assigning VS. defining properties](http://exploringjs.com/es6/ch_oop-besides-classes.html#sec_assigning-vs-defining-properties). - - -### `useBuiltIns` - -`boolean`, defaults to `false`. - -Enabling this option will use `Object.assign` directly instead of the Babel's `extends` helper. - -##### Example - -**.babelrc** - -```json -{ - "plugins": [ - ["@babel/plugin-proposal-object-rest-spread", { "loose": true, "useBuiltIns": true }] - ] -} -``` - -**In** - -```js -z = { x, ...y }; -``` - -**Out** - -```js -z = Object.assign({ x }, y); -``` - -## References - -* [Proposal: Object Rest/Spread Properties for ECMAScript](https://github.com/sebmarkbage/ecmascript-rest-spread) -* [Spec](http://sebmarkbage.github.io/ecmascript-rest-spread) -* [Spread VS. Object.assign](http://2ality.com/2016/10/rest-spread-properties.html#spreading-objects-versus-objectassign) -* [Assigning VS. defining properties](http://exploringjs.com/es6/ch_oop-besides-classes.html#sec_assigning-vs-defining-properties) diff --git a/packages/babel-plugin-proposal-optional-catch-binding/README.md b/packages/babel-plugin-proposal-optional-catch-binding/README.md index e06eb65d4d..b64a4e480e 100644 --- a/packages/babel-plugin-proposal-optional-catch-binding/README.md +++ b/packages/babel-plugin-proposal-optional-catch-binding/README.md @@ -1,60 +1,19 @@ # @babel/plugin-proposal-optional-catch-binding -> Optional catch binding enables the catch block to execute whether or not an argument is passed to the catch statement (CatchClause). +> Compile optional catch bindings +See our website [@babel/plugin-proposal-optional-catch-binding](https://new.babeljs.io/docs/en/next/babel-plugin-proposal-optional-catch-binding.html) for more information. -## Examples +## Install -```js -try { - throw 0; -} catch { - doSomethingWhichDoesntCareAboutTheValueThrown(); -} -``` - -```js -try { - throw 0; -} catch { - doSomethingWhichDoesntCareAboutTheValueThrown(); -} finally { - doSomeCleanup(); -} -``` - - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-proposal-optional-catch-binding +npm install --save @babel/plugin-proposal-optional-catch-binding ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-proposal-optional-catch-binding"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-proposal-optional-catch-binding script.js +yarn add --save @babel/plugin-proposal-optional-catch-binding ``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-proposal-optional-catch-binding"] -}); -``` - -## References -- [Proposal: Optional Catch Binding for ECMAScript](https://github.com/babel/proposals/issues/7) diff --git a/packages/babel-plugin-proposal-optional-chaining/README.md b/packages/babel-plugin-proposal-optional-chaining/README.md index b3338262c7..55ab5d775e 100644 --- a/packages/babel-plugin-proposal-optional-chaining/README.md +++ b/packages/babel-plugin-proposal-optional-chaining/README.md @@ -1,148 +1,19 @@ # @babel/plugin-proposal-optional-chaining -The Optional Chaining Operator allows you to handle properties of deeply nested -objects without worrying about undefined intermediate objects. +> Transform optional chaining operators into a series of nil checks -## Example +See our website [@babel/plugin-proposal-optional-chaining](https://new.babeljs.io/docs/en/next/babel-plugin-proposal-optional-chaining.html) for more information. -### Accessing deeply nested properties +## Install -```js -const obj = { - foo: { - bar: { - baz: 42, - }, - }, -}; - -const baz = obj?.foo?.bar?.baz; // 42 - -const safe = obj?.qux?.baz; // undefined - -// Optional chaining and normal chaining can be intermixed -obj?.foo.bar?.baz; // Only access `foo` if `obj` exists, and `baz` if - // `bar` exists -``` - -### Calling deeply nested functions - -```js -const obj = { - foo: { - bar: { - baz() { - return 42; - }, - }, - }, -}; - -const baz = obj?.foo?.bar?.baz(); // 42 - -const safe = obj?.qux?.baz(); // undefined -const safe2 = obj?.foo.bar.qux?.(); // undefined - -const willThrow = obj?.foo.bar.qux(); // Error: not a function - -// Top function can be called directly, too. -function test() { - return 42; -} -test?.(); // 42 - -exists?.(); // undefined -``` - -### Constructing deeply nested classes - -```js -const obj = { - foo: { - bar: { - baz: class { - }, - }, - }, -}; - -const baz = new obj?.foo?.bar?.baz(); // baz instance - -const safe = new obj?.qux?.baz(); // undefined -const safe2 = new obj?.foo.bar.qux?.(); // undefined - -const willThrow = new obj?.foo.bar.qux(); // Error: not a constructor - -// Top classes can be called directly, too. -class Test { -} -new Test?.(); // test instance - -new exists?.(); // undefined -``` - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-proposal-optional-chaining +npm install --save @babel/plugin-proposal-optional-chaining ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-proposal-optional-chaining"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-proposal-optional-chaining script.js +yarn add --save @babel/plugin-proposal-optional-chaining ``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-proposal-optional-chaining"] -}); -``` - -## Options - -### `loose` - -`boolean`, defaults to `false`. - -When `true`, this transform will pretend `document.all` does not exist, -and perform loose equality checks with `null` instead of string equality checks -against both `null` and `undefined`. - -#### Example - -In - -```javascript -foo?.bar; -``` - -Out (`loose === true`) - -```javascript -foo == null ? void 0 : foo.bar; -``` - -Out (`loose === false`) - -```javascript -foo === null || foo === void 0 ? void 0 : foo.bar; -``` - -## References - -* [Proposal: Optional Chaining](https://github.com/tc39/proposal-optional-chaining) diff --git a/packages/babel-plugin-proposal-pipeline-operator/README.md b/packages/babel-plugin-proposal-pipeline-operator/README.md index 9295d099ee..d23f56ad8a 100644 --- a/packages/babel-plugin-proposal-pipeline-operator/README.md +++ b/packages/babel-plugin-proposal-pipeline-operator/README.md @@ -1,35 +1,19 @@ # @babel/plugin-proposal-pipeline-operator -Transform pipeline operator `|>` into call expressions. See [the proposal](https://github.com/tc39/proposal-pipeline-operator) for details. +> Transform pipeline operator into call expressions -## Installation +See our website [@babel/plugin-proposal-pipeline-operator](https://new.babeljs.io/docs/en/next/babel-plugin-proposal-pipeline-operator.html) for more information. + +## Install + +Using npm: ```sh -$ npm install @babel/plugin-proposal-pipeline-operator +npm install --save @babel/plugin-proposal-pipeline-operator ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-proposal-pipeline-operator"] -} -``` - -### Via CLI +or using yarn: ```sh -$ babel --plugins @babel/plugin-proposal-pipeline-operator script.js -``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-proposal-pipeline-operator"] -}); +yarn add --save @babel/plugin-proposal-pipeline-operator ``` diff --git a/packages/babel-plugin-proposal-throw-expressions/README.md b/packages/babel-plugin-proposal-throw-expressions/README.md index 5ffb4de615..f4e54c3d40 100644 --- a/packages/babel-plugin-proposal-throw-expressions/README.md +++ b/packages/babel-plugin-proposal-throw-expressions/README.md @@ -1,47 +1,19 @@ # @babel/plugin-proposal-throw-expressions -This plugin transforms Throw Expressions into an IIFE. +> Wraps Throw Expressions in an IIFE -## Example +See our website [@babel/plugin-proposal-throw-expressions](https://new.babeljs.io/docs/en/next/babel-plugin-proposal-throw-expressions.html) for more information. -```js -function test(param = throw new Error('required!')) { - const test = param === true || throw new Error('Falsey!'); -} -``` +## Install -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-proposal-throw-expressions +npm install --save @babel/plugin-proposal-throw-expressions ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-proposal-throw-expressions"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-proposal-throw-expressions script.js +yarn add --save @babel/plugin-proposal-throw-expressions ``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-proposal-throw-expressions"] -}); -``` - -## References - -* [Proposal: ECMAScript throw expressions](https://github.com/tc39/proposal-throw-expressions) diff --git a/packages/babel-plugin-proposal-unicode-property-regex/README.md b/packages/babel-plugin-proposal-unicode-property-regex/README.md index 00a8cbd6bd..d2ce055d9c 100644 --- a/packages/babel-plugin-proposal-unicode-property-regex/README.md +++ b/packages/babel-plugin-proposal-unicode-property-regex/README.md @@ -1,60 +1,19 @@ # @babel/plugin-proposal-unicode-property-regex -Compile [Unicode property escapes](https://github.com/mathiasbynens/regexpu-core/blob/master/property-escapes.md) (`\p{…}` and `\P{…}`) in Unicode regular expressions to ES5 or ES6 that works in today’s environments. +> Compile Unicode property escapes in Unicode regular expressions to ES5. -[Here’s an online demo.](https://mothereff.in/regexpu#input=var+regex+%3D+/%5Cp%7BScript_Extensions%3DGreek%7D/u%3B&unicodePropertyEscape=1) +See our website [@babel/plugin-proposal-unicode-property-regex](https://new.babeljs.io/docs/en/next/babel-plugin-proposal-unicode-property-regex.html) for more information. -## Installation +## Install + +Using npm: ```sh -npm install --save-dev @babel/plugin-proposal-unicode-property-regex +npm install --save @babel/plugin-proposal-unicode-property-regex ``` -## Usage - -### Via `.babelrc` (recommended) - -`.babelrc` - -```json -{ - "plugins": ["@babel/plugin-proposal-unicode-property-regex"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/@babel/plugin-proposal-unicode-property-regex script.js +yarn add --save @babel/plugin-proposal-unicode-property-regex ``` - -### Via Node.js API - -```js -require("@babel/core").transform(code, { - "plugins": ["@babel/plugin-proposal-unicode-property-regex"] -}); -``` - -To transpile to ES6/ES2015: - -```js -require("@babel/core").transform(code, { - "plugins": [ - ["@babel/plugin-proposal-unicode-property-regex", { "useUnicodeFlag": false }] - ] -}); -``` - -## Options - -* `useUnicodeFlag` (defaults to `true`) - -When disabled with `false`, the transform converts Unicode regexes to -non-Unicode regexes for wider support, removing the `u` flag. See https://github.com/mathiasbynens/regexpu-core#useunicodeflag-default-false for more information. - -## Author - -| [![twitter/mathias](https://gravatar.com/avatar/24e08a9ea84deb17ae121074d0f17125?s=70)](https://twitter.com/mathias "Follow @mathias on Twitter") | -|---| -| [Mathias Bynens](https://mathiasbynens.be/) | diff --git a/packages/babel-plugin-syntax-async-generators/README.md b/packages/babel-plugin-syntax-async-generators/README.md index b8f9e7cdbb..1e6a4e64e9 100644 --- a/packages/babel-plugin-syntax-async-generators/README.md +++ b/packages/babel-plugin-syntax-async-generators/README.md @@ -1,57 +1,19 @@ # @babel/plugin-syntax-async-generators -> Allow parsing of async generator functions. +> Allow parsing of async generator functions -## Example +See our website [@babel/plugin-syntax-async-generators](https://new.babeljs.io/docs/en/next/babel-plugin-syntax-async-generators.html) for more information. -**Syntax** +## Install -```javascript -async function* agf() { - await 1; -} -``` - -```js -async function f() { - for await (let x of y) { - g(x); - } -} -``` - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-syntax-async-generators +npm install --save @babel/plugin-syntax-async-generators ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-syntax-async-generators"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-syntax-async-generators script.js +yarn add --save @babel/plugin-syntax-async-generators ``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-syntax-async-generators"] -}); -``` - -## References - -* [Proposal: Asynchronous iteration for ECMAScript](https://github.com/tc39/proposal-async-iteration) diff --git a/packages/babel-plugin-syntax-bigint/README.md b/packages/babel-plugin-syntax-bigint/README.md index f4e1484e39..92fecf61c9 100644 --- a/packages/babel-plugin-syntax-bigint/README.md +++ b/packages/babel-plugin-syntax-bigint/README.md @@ -1,36 +1,19 @@ # @babel/plugin-syntax-bigint -> Allow parsing of BigInt literals. +> Allow parsing of BigInt literals +See our website [@babel/plugin-syntax-bigint](https://new.babeljs.io/docs/en/next/babel-plugin-syntax-bigint.html) for more information. -## Installation +## Install + +Using npm: ```sh -npm install --save-dev @babel/plugin-syntax-bigint +npm install --save @babel/plugin-syntax-bigint ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-syntax-bigint"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-syntax-bigint script.js -``` - -### Via Node API - -```javascript -require("babel-core").transform("code", { - plugins: ["@babel/plugin-syntax-bigint"] -}); +yarn add --save @babel/plugin-syntax-bigint ``` diff --git a/packages/babel-plugin-syntax-class-properties/README.md b/packages/babel-plugin-syntax-class-properties/README.md index fddd0b4d7a..2e4229110f 100644 --- a/packages/babel-plugin-syntax-class-properties/README.md +++ b/packages/babel-plugin-syntax-class-properties/README.md @@ -1,35 +1,19 @@ # @babel/plugin-syntax-class-properties -> Allow parsing of class properties. +> Allow parsing of class properties -## Installation +See our website [@babel/plugin-syntax-class-properties](https://new.babeljs.io/docs/en/next/babel-plugin-syntax-class-properties.html) for more information. + +## Install + +Using npm: ```sh -npm install --save-dev @babel/plugin-syntax-class-properties +npm install --save @babel/plugin-syntax-class-properties ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-syntax-class-properties"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-syntax-class-properties script.js -``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-syntax-class-properties"] -}); +yarn add --save @babel/plugin-syntax-class-properties ``` diff --git a/packages/babel-plugin-syntax-decorators/README.md b/packages/babel-plugin-syntax-decorators/README.md index a5a5191b38..cda5f079c9 100644 --- a/packages/babel-plugin-syntax-decorators/README.md +++ b/packages/babel-plugin-syntax-decorators/README.md @@ -1,60 +1,19 @@ # @babel/plugin-syntax-decorators -> Allow parsing of decorators. +> Allow parsing of decorators -## Installation +See our website [@babel/plugin-syntax-decorators](https://new.babeljs.io/docs/en/next/babel-plugin-syntax-decorators.html) for more information. + +## Install + +Using npm: ```sh -npm install --save-dev @babel/plugin-syntax-decorators +npm install --save @babel/plugin-syntax-decorators ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-syntax-decorators"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-syntax-decorators script.js +yarn add --save @babel/plugin-syntax-decorators ``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-syntax-decorators"] -}); -``` - -## Options - -### `legacy` - -`boolean`, defaults to `false`. - -Use the legacy (stage 1) decorators syntax. - -### `decoratorsBeforeExport` - -`boolean`, defaults to `true`. - -```js -// decoratorsBeforeExport: true -@decorator -export class Foo {} - -// decoratorsBeforeExport: false -export @decorator class Bar {} -``` - -This option was added to help tc39 collect feedback from the community by allowing experimentation with both possible syntaxes. - -For more information, check out: [tc39/proposal-decorators#69](https://github.com/tc39/proposal-decorators/issues/69) diff --git a/packages/babel-plugin-syntax-do-expressions/README.md b/packages/babel-plugin-syntax-do-expressions/README.md index 36689ddd53..84f68b9dd5 100644 --- a/packages/babel-plugin-syntax-do-expressions/README.md +++ b/packages/babel-plugin-syntax-do-expressions/README.md @@ -1,35 +1,19 @@ # @babel/plugin-syntax-do-expressions -> Allow parsing of do expressions. +> Allow parsing of do expressions -## Installation +See our website [@babel/plugin-syntax-do-expressions](https://new.babeljs.io/docs/en/next/babel-plugin-syntax-do-expressions.html) for more information. + +## Install + +Using npm: ```sh -npm install --save-dev @babel/plugin-syntax-do-expressions +npm install --save @babel/plugin-syntax-do-expressions ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-syntax-do-expressions"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-syntax-do-expressions script.js -``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-syntax-do-expressions"] -}); +yarn add --save @babel/plugin-syntax-do-expressions ``` diff --git a/packages/babel-plugin-syntax-dynamic-import/README.md b/packages/babel-plugin-syntax-dynamic-import/README.md index 4705c75ec5..f62aae235d 100644 --- a/packages/babel-plugin-syntax-dynamic-import/README.md +++ b/packages/babel-plugin-syntax-dynamic-import/README.md @@ -1,35 +1,19 @@ # @babel/plugin-syntax-dynamic-import -> Allow parsing of `import()`. +> Allow parsing of import() -## Installation +See our website [@babel/plugin-syntax-dynamic-import](https://new.babeljs.io/docs/en/next/babel-plugin-syntax-dynamic-import.html) for more information. + +## Install + +Using npm: ```sh -npm install --save-dev @babel/plugin-syntax-dynamic-import +npm install --save @babel/plugin-syntax-dynamic-import ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-syntax-dynamic-import"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-syntax-dynamic-import script.js -``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-syntax-dynamic-import"] -}); +yarn add --save @babel/plugin-syntax-dynamic-import ``` diff --git a/packages/babel-plugin-syntax-export-default-from/README.md b/packages/babel-plugin-syntax-export-default-from/README.md index 42c0bca8f6..8d25555328 100644 --- a/packages/babel-plugin-syntax-export-default-from/README.md +++ b/packages/babel-plugin-syntax-export-default-from/README.md @@ -1,35 +1,19 @@ # @babel/plugin-syntax-export-default-from -> Allow parsing of `export default from`. +> Allow parsing of export default from -## Installation +See our website [@babel/plugin-syntax-export-default-from](https://new.babeljs.io/docs/en/next/babel-plugin-syntax-export-default-from.html) for more information. + +## Install + +Using npm: ```sh -npm install --save-dev @babel/plugin-syntax-export-default-from +npm install --save @babel/plugin-syntax-export-default-from ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-syntax-export-default-from"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-syntax-export-default-from script.js -``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-syntax-export-default-from"] -}); +yarn add --save @babel/plugin-syntax-export-default-from ``` diff --git a/packages/babel-plugin-syntax-export-namespace-from/README.md b/packages/babel-plugin-syntax-export-namespace-from/README.md index 6e358a2e3d..7656aff21a 100644 --- a/packages/babel-plugin-syntax-export-namespace-from/README.md +++ b/packages/babel-plugin-syntax-export-namespace-from/README.md @@ -1,35 +1,19 @@ # @babel/plugin-syntax-export-namespace-from -> Allow parsing of `export * as namespace from`. +> Allow parsing of export namespace from -## Installation +See our website [@babel/plugin-syntax-export-namespace-from](https://new.babeljs.io/docs/en/next/babel-plugin-syntax-export-namespace-from.html) for more information. + +## Install + +Using npm: ```sh -npm install --save-dev @babel/plugin-syntax-export-namespace-from +npm install --save @babel/plugin-syntax-export-namespace-from ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-syntax-export-namespace-from"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-syntax-export-namespace-from script.js -``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-syntax-export-namespace-from"] -}); +yarn add --save @babel/plugin-syntax-export-namespace-from ``` diff --git a/packages/babel-plugin-syntax-flow/README.md b/packages/babel-plugin-syntax-flow/README.md index bcb5b7404d..a6cf42dd5a 100644 --- a/packages/babel-plugin-syntax-flow/README.md +++ b/packages/babel-plugin-syntax-flow/README.md @@ -1,35 +1,19 @@ # @babel/plugin-syntax-flow +> Allow parsing of the flow syntax +See our website [@babel/plugin-syntax-flow](https://new.babeljs.io/docs/en/next/babel-plugin-syntax-flow.html) for more information. -## Installation +## Install + +Using npm: ```sh -npm install --save-dev @babel/plugin-syntax-flow +npm install --save @babel/plugin-syntax-flow ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-syntax-flow"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-syntax-flow script.js -``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-syntax-flow"] -}); +yarn add --save @babel/plugin-syntax-flow ``` diff --git a/packages/babel-plugin-syntax-function-bind/README.md b/packages/babel-plugin-syntax-function-bind/README.md index a90f394f54..353dd0a1db 100644 --- a/packages/babel-plugin-syntax-function-bind/README.md +++ b/packages/babel-plugin-syntax-function-bind/README.md @@ -1,35 +1,19 @@ # @babel/plugin-syntax-function-bind -> Allow parsing of function bind. +> Allow parsing of function bind -## Installation +See our website [@babel/plugin-syntax-function-bind](https://new.babeljs.io/docs/en/next/babel-plugin-syntax-function-bind.html) for more information. + +## Install + +Using npm: ```sh -npm install --save-dev @babel/plugin-syntax-function-bind +npm install --save @babel/plugin-syntax-function-bind ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-syntax-function-bind"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-syntax-function-bind script.js -``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-syntax-function-bind"] -}); +yarn add --save @babel/plugin-syntax-function-bind ``` diff --git a/packages/babel-plugin-syntax-function-sent/README.md b/packages/babel-plugin-syntax-function-sent/README.md index e8aa25401d..41ff10c6d6 100644 --- a/packages/babel-plugin-syntax-function-sent/README.md +++ b/packages/babel-plugin-syntax-function-sent/README.md @@ -1,35 +1,19 @@ # @babel/plugin-syntax-function-sent -> Allow parsing of the `function.sent` meta property. +> Allow parsing of the function.sent meta property -## Installation +See our website [@babel/plugin-syntax-function-sent](https://new.babeljs.io/docs/en/next/babel-plugin-syntax-function-sent.html) for more information. + +## Install + +Using npm: ```sh -npm install --save-dev @babel/plugin-syntax-function-sent +npm install --save @babel/plugin-syntax-function-sent ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-syntax-function-sent"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-syntax-function-sent script.js -``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-syntax-function-sent"] -}); +yarn add --save @babel/plugin-syntax-function-sent ``` diff --git a/packages/babel-plugin-syntax-import-meta/README.md b/packages/babel-plugin-syntax-import-meta/README.md index 20c5fc4736..12f3fbba03 100644 --- a/packages/babel-plugin-syntax-import-meta/README.md +++ b/packages/babel-plugin-syntax-import-meta/README.md @@ -1,35 +1,19 @@ # @babel/plugin-syntax-import-meta -> Allow parsing of `import.meta`. +> Allow parsing of import.meta -## Installation +See our website [@babel/plugin-syntax-import-meta](https://new.babeljs.io/docs/en/next/babel-plugin-syntax-import-meta.html) for more information. + +## Install + +Using npm: ```sh -npm install --save-dev @babel/plugin-syntax-import-meta +npm install --save @babel/plugin-syntax-import-meta ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-syntax-import-meta"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-syntax-import-meta script.js -``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-syntax-import-meta"] -}); +yarn add --save @babel/plugin-syntax-import-meta ``` diff --git a/packages/babel-plugin-syntax-json-strings/README.md b/packages/babel-plugin-syntax-json-strings/README.md index ba92be5713..561c89f70d 100644 --- a/packages/babel-plugin-syntax-json-strings/README.md +++ b/packages/babel-plugin-syntax-json-strings/README.md @@ -1,35 +1,19 @@ # @babel/plugin-syntax-json-strings -Allow parsing of the U+2028 LINE SEPARATOR and U+2029 PARAGRAPH SEPARATOR in JS strings +> Allow parsing of the U+2028 LINE SEPARATOR and U+2029 PARAGRAPH SEPARATOR in JS strings -## Installation +See our website [@babel/plugin-syntax-json-strings](https://new.babeljs.io/docs/en/next/babel-plugin-syntax-json-strings.html) for more information. + +## Install + +Using npm: ```sh -npm install --save-dev @babel/plugin-syntax-json-strings +npm install --save @babel/plugin-syntax-json-strings ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-syntax-json-strings"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-syntax-json-strings script.js -``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-syntax-json-strings"] -}); +yarn add --save @babel/plugin-syntax-json-strings ``` diff --git a/packages/babel-plugin-syntax-jsx/README.md b/packages/babel-plugin-syntax-jsx/README.md index 41096c527f..d7c88d6d6b 100644 --- a/packages/babel-plugin-syntax-jsx/README.md +++ b/packages/babel-plugin-syntax-jsx/README.md @@ -1,35 +1,19 @@ # @babel/plugin-syntax-jsx -> Allow parsing of JSX +> Allow parsing of jsx -## Installation +See our website [@babel/plugin-syntax-jsx](https://new.babeljs.io/docs/en/next/babel-plugin-syntax-jsx.html) for more information. + +## Install + +Using npm: ```sh -npm install --save-dev @babel/plugin-syntax-jsx +npm install --save @babel/plugin-syntax-jsx ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-syntax-jsx"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-syntax-jsx script.js -``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-syntax-jsx"] -}); +yarn add --save @babel/plugin-syntax-jsx ``` diff --git a/packages/babel-plugin-syntax-logical-assignment-operators/README.md b/packages/babel-plugin-syntax-logical-assignment-operators/README.md index 07c5371cc3..67cf4d6f77 100644 --- a/packages/babel-plugin-syntax-logical-assignment-operators/README.md +++ b/packages/babel-plugin-syntax-logical-assignment-operators/README.md @@ -1,35 +1,19 @@ # @babel/plugin-syntax-logical-assignment-operators -> Allow parsing of the logical assignment operators. +> Allow parsing of the logical assignment operators -## Installation +See our website [@babel/plugin-syntax-logical-assignment-operators](https://new.babeljs.io/docs/en/next/babel-plugin-syntax-logical-assignment-operators.html) for more information. + +## Install + +Using npm: ```sh -npm install --save-dev @babel/plugin-syntax-logical-assignment-operators +npm install --save @babel/plugin-syntax-logical-assignment-operators ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-syntax-logical-assignment-operators"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-syntax-logical-assignment-operators script.js -``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-syntax-logical-assignment-operators"] -}); +yarn add --save @babel/plugin-syntax-logical-assignment-operators ``` diff --git a/packages/babel-plugin-syntax-nullish-coalescing-operator/README.md b/packages/babel-plugin-syntax-nullish-coalescing-operator/README.md index 9e8bf04769..9b712ea233 100644 --- a/packages/babel-plugin-syntax-nullish-coalescing-operator/README.md +++ b/packages/babel-plugin-syntax-nullish-coalescing-operator/README.md @@ -1,35 +1,19 @@ # @babel/plugin-syntax-nullish-coalescing-operator -> Allow parsing of the nullish-coalescing operator. +> Allow parsing of the nullish-coalescing operator -## Installation +See our website [@babel/plugin-syntax-nullish-coalescing-operator](https://new.babeljs.io/docs/en/next/babel-plugin-syntax-nullish-coalescing-operator.html) for more information. + +## Install + +Using npm: ```sh -npm install --save-dev @babel/plugin-syntax-nullish-coalescing-operator +npm install --save @babel/plugin-syntax-nullish-coalescing-operator ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-syntax-nullish-coalescing-operator"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-syntax-nullish-coalescing-operator script.js -``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-syntax-nullish-coalescing-operator"] -}); +yarn add --save @babel/plugin-syntax-nullish-coalescing-operator ``` diff --git a/packages/babel-plugin-syntax-numeric-separator/README.md b/packages/babel-plugin-syntax-numeric-separator/README.md index 3976234f96..9d7184daed 100644 --- a/packages/babel-plugin-syntax-numeric-separator/README.md +++ b/packages/babel-plugin-syntax-numeric-separator/README.md @@ -1,36 +1,19 @@ # @babel/plugin-syntax-numeric-separator -> Allow parsing of Numeric Literals (Decimal, Binary, Hex and Octal) that contain a _NumericLiteralSeparator_. +> Allow parsing of Decimal, Binary, Hex and Octal literals that contain a Numeric Literal Separator +See our website [@babel/plugin-syntax-numeric-separator](https://new.babeljs.io/docs/en/next/babel-plugin-syntax-numeric-separator.html) for more information. -## Installation +## Install + +Using npm: ```sh -npm install --save-dev @babel/plugin-syntax-numeric-separator +npm install --save @babel/plugin-syntax-numeric-separator ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-syntax-numeric-separator"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-syntax-numeric-separator script.js -``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-syntax-numeric-separator"] -}); +yarn add --save @babel/plugin-syntax-numeric-separator ``` diff --git a/packages/babel-plugin-syntax-object-rest-spread/README.md b/packages/babel-plugin-syntax-object-rest-spread/README.md index 1633833f50..5b03eafd6c 100644 --- a/packages/babel-plugin-syntax-object-rest-spread/README.md +++ b/packages/babel-plugin-syntax-object-rest-spread/README.md @@ -1,35 +1,19 @@ # @babel/plugin-syntax-object-rest-spread -> Allow parsing of object rest/spread. +> Allow parsing of object rest/spread -## Installation +See our website [@babel/plugin-syntax-object-rest-spread](https://new.babeljs.io/docs/en/next/babel-plugin-syntax-object-rest-spread.html) for more information. + +## Install + +Using npm: ```sh -npm install --save-dev @babel/plugin-syntax-object-rest-spread +npm install --save @babel/plugin-syntax-object-rest-spread ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-syntax-object-rest-spread"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-syntax-object-rest-spread script.js -``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-syntax-object-rest-spread"] -}); +yarn add --save @babel/plugin-syntax-object-rest-spread ``` diff --git a/packages/babel-plugin-syntax-optional-catch-binding/README.md b/packages/babel-plugin-syntax-optional-catch-binding/README.md index 3d4fd8f303..4f7fbe9432 100644 --- a/packages/babel-plugin-syntax-optional-catch-binding/README.md +++ b/packages/babel-plugin-syntax-optional-catch-binding/README.md @@ -1,52 +1,19 @@ # @babel/plugin-syntax-optional-catch-binding -> This plugin allows Babel to parse optional catch bindings. +> Allow parsing of optional catch bindings -## Example +See our website [@babel/plugin-syntax-optional-catch-binding](https://new.babeljs.io/docs/en/next/babel-plugin-syntax-optional-catch-binding.html) for more information. -**Syntax** +## Install -```javascript -try { - throw 0; -} catch { - doSomethingWhichDoesntCareAboutTheValueThrown(); - console.log("Yay, code executes!"); -} -``` - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-syntax-optional-catch-binding +npm install --save @babel/plugin-syntax-optional-catch-binding ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-syntax-optional-catch-binding"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-syntax-optional-catch-binding script.js +yarn add --save @babel/plugin-syntax-optional-catch-binding ``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-syntax-optional-catch-binding"] -}); -``` - -## References - -* [Proposal: Optional Catch Binding for ECMAScript](https://github.com/babel/proposals/issues/7) diff --git a/packages/babel-plugin-syntax-optional-chaining/README.md b/packages/babel-plugin-syntax-optional-chaining/README.md index 0e571d750b..bc73f8e4fd 100644 --- a/packages/babel-plugin-syntax-optional-chaining/README.md +++ b/packages/babel-plugin-syntax-optional-chaining/README.md @@ -1,35 +1,19 @@ # @babel/plugin-syntax-optional-chaining -Allow parsing of optional properties. +> Allow parsing of optional properties -## Installation +See our website [@babel/plugin-syntax-optional-chaining](https://new.babeljs.io/docs/en/next/babel-plugin-syntax-optional-chaining.html) for more information. + +## Install + +Using npm: ```sh -npm install --save-dev @babel/plugin-syntax-optional-chaining +npm install --save @babel/plugin-syntax-optional-chaining ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-syntax-optional-chaining"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-syntax-optional-chaining script.js -``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-syntax-optional-chaining"] -}); +yarn add --save @babel/plugin-syntax-optional-chaining ``` diff --git a/packages/babel-plugin-syntax-pipeline-operator/README.md b/packages/babel-plugin-syntax-pipeline-operator/README.md index 2bdd5b929b..3e9a329d69 100644 --- a/packages/babel-plugin-syntax-pipeline-operator/README.md +++ b/packages/babel-plugin-syntax-pipeline-operator/README.md @@ -1,35 +1,19 @@ # @babel/plugin-syntax-pipeline-operator -Allow parsing of the pipeline operator `|>`. See [the proposal](https://github.com/tc39/proposal-pipeline-operator) for details. +> Allow parsing of the pipeline operator -## Installation +See our website [@babel/plugin-syntax-pipeline-operator](https://new.babeljs.io/docs/en/next/babel-plugin-syntax-pipeline-operator.html) for more information. + +## Install + +Using npm: ```sh -$ npm install @babel/plugin-syntax-pipeline-operator +npm install --save @babel/plugin-syntax-pipeline-operator ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-syntax-pipeline-operator"] -} -``` - -### Via CLI +or using yarn: ```sh -$ babel --plugins @babel/plugin-syntax-pipeline-operator script.js -``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-syntax-pipeline-operator"] -}); +yarn add --save @babel/plugin-syntax-pipeline-operator ``` diff --git a/packages/babel-plugin-syntax-throw-expressions/README.md b/packages/babel-plugin-syntax-throw-expressions/README.md index 9aa7f87807..2804b4546b 100644 --- a/packages/babel-plugin-syntax-throw-expressions/README.md +++ b/packages/babel-plugin-syntax-throw-expressions/README.md @@ -1,42 +1,19 @@ # @babel/plugin-syntax-throw-expressions -Allow parsing of Throw Expressions: +> Allow parsing of Throw Expressions -```js -function test(param = throw new Error('required!')) { - const test = param === true || throw new Error('Falsey!'); -} -``` +See our website [@babel/plugin-syntax-throw-expressions](https://new.babeljs.io/docs/en/next/babel-plugin-syntax-throw-expressions.html) for more information. +## Install -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-syntax-throw-expressions +npm install --save @babel/plugin-syntax-throw-expressions ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-syntax-throw-expressions"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-syntax-throw-expressions script.js -``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-syntax-throw-expressions"] -}); +yarn add --save @babel/plugin-syntax-throw-expressions ``` diff --git a/packages/babel-plugin-syntax-typescript/README.md b/packages/babel-plugin-syntax-typescript/README.md index e24f1b6cfe..a175ce5c12 100644 --- a/packages/babel-plugin-syntax-typescript/README.md +++ b/packages/babel-plugin-syntax-typescript/README.md @@ -1,33 +1,19 @@ # @babel/plugin-syntax-typescript -## Installation +> Allow parsing of TypeScript syntax + +See our website [@babel/plugin-syntax-typescript](https://new.babeljs.io/docs/en/next/babel-plugin-syntax-typescript.html) for more information. + +## Install + +Using npm: ```sh -npm install --save-dev @babel/plugin-syntax-typescript +npm install --save @babel/plugin-syntax-typescript ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-syntax-typescript"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-syntax-typescript script.js -``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-syntax-typescript"] -}); +yarn add --save @babel/plugin-syntax-typescript ``` diff --git a/packages/babel-plugin-transform-arrow-functions/README.md b/packages/babel-plugin-transform-arrow-functions/README.md index 3cccc15aec..cf02c86d39 100644 --- a/packages/babel-plugin-transform-arrow-functions/README.md +++ b/packages/babel-plugin-transform-arrow-functions/README.md @@ -2,148 +2,18 @@ > Compile ES2015 arrow functions to ES5 -## Example +See our website [@babel/plugin-transform-arrow-functions](https://new.babeljs.io/docs/en/next/babel-plugin-transform-arrow-functions.html) for more information. -**In** +## Install -```javascript -var a = () => {}; -var a = (b) => b; - -const double = [1,2,3].map((num) => num * 2); -console.log(double); // [2,4,6] - -var bob = { - _name: "Bob", - _friends: ["Sally", "Tom"], - printFriends() { - this._friends.forEach(f => - console.log(this._name + " knows " + f)); - } -}; -console.log(bob.printFriends()); -``` - -**Out** - -```javascript -var a = function () {}; -var a = function (b) { - return b; -}; - -const double = [1, 2, 3].map(function (num) { - return num * 2; -}); -console.log(double); // [2,4,6] - -var bob = { - _name: "Bob", - _friends: ["Sally", "Tom"], - printFriends() { - var _this = this; - - this._friends.forEach(function (f) { - return console.log(_this._name + " knows " + f); - }); - } -}; -console.log(bob.printFriends()); -``` - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-transform-arrow-functions +npm install --save @babel/plugin-transform-arrow-functions ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -Without options: - -```json -{ - "plugins": ["@babel/plugin-transform-arrow-functions"] -} -``` - -With options: - -```json -{ - "plugins": [ - ["@babel/plugin-transform-arrow-functions", { "spec": true }] - ] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-transform-arrow-functions script.js +yarn add --save @babel/plugin-transform-arrow-functions ``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-transform-arrow-functions"] -}); -``` - -## Options - -### `spec` - -`boolean`, defaults to `false`. - -

- Example - - Using spec mode with the above example produces: - - ```js - var _this = this; - - var a = function a() { - babelHelpers.newArrowCheck(this, _this); - }.bind(this); - var a = function a(b) { - babelHelpers.newArrowCheck(this, _this); - return b; - }.bind(this); - - const double = [1, 2, 3].map(function (num) { - babelHelpers.newArrowCheck(this, _this); - return num * 2; - }.bind(this)); - console.log(double); // [2,4,6] - - var bob = { - _name: "Bob", - _friends: ["Sally", "Tom"], - printFriends() { - var _this2 = this; - - this._friends.forEach(function (f) { - babelHelpers.newArrowCheck(this, _this2); - return console.log(this._name + " knows " + f); - }.bind(this)); - } - }; - console.log(bob.printFriends()); - ``` -

- -This option enables the following: - - - Wrap the generated function in `.bind(this)` and keeps uses of `this` inside - the function as-is, instead of using a renamed `this`. - - - Add a runtime check to ensure the functions are not instantiated. - - - Add names to arrow functions. diff --git a/packages/babel-plugin-transform-async-to-generator/README.md b/packages/babel-plugin-transform-async-to-generator/README.md index 8065bc8e3d..b114534581 100644 --- a/packages/babel-plugin-transform-async-to-generator/README.md +++ b/packages/babel-plugin-transform-async-to-generator/README.md @@ -2,88 +2,18 @@ > Turn async functions into ES2015 generators -> In Babel 7, `transform-async-to-module-method` was merged into this plugin +See our website [@babel/plugin-transform-async-to-generator](https://new.babeljs.io/docs/en/next/babel-plugin-transform-async-to-generator.html) for more information. -## Example +## Install -**In** - -```javascript -async function foo() { - await bar(); -} -``` - -**Out** - -```javascript -var _asyncToGenerator = function (fn) { - ... -}; -var foo = _asyncToGenerator(function* () { - yield bar(); -}); -``` - -**Out with options** - -> Turn async functions into a Bluebird coroutine - -```javascript -var Bluebird = require("bluebird"); - -var foo = Bluebird.coroutine(function* () { - yield bar(); -}); -``` - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-transform-async-to-generator +npm install --save @babel/plugin-transform-async-to-generator ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -Without options: - -```json -{ - "plugins": ["@babel/plugin-transform-async-to-generator"] -} -``` - -With options: - -```json -{ - "plugins": [ - ["@babel/plugin-transform-async-to-generator", { - "module": "bluebird", - "method": "coroutine" - }] - ] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-transform-async-to-generator script.js +yarn add --save @babel/plugin-transform-async-to-generator ``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-transform-async-to-generator"] -}); -``` - -## References - -* [Proposal: Async Functions for ECMAScript](https://github.com/tc39/ecmascript-asyncawait) diff --git a/packages/babel-plugin-transform-block-scoped-functions/README.md b/packages/babel-plugin-transform-block-scoped-functions/README.md index 95985cf600..fc0b09ac49 100644 --- a/packages/babel-plugin-transform-block-scoped-functions/README.md +++ b/packages/babel-plugin-transform-block-scoped-functions/README.md @@ -1,60 +1,19 @@ # @babel/plugin-transform-block-scoped-functions -> Babel plugin to ensure function declarations at the block level are block scoped. +> Babel plugin to ensure function declarations at the block level are block scoped -## Examples +See our website [@babel/plugin-transform-block-scoped-functions](https://new.babeljs.io/docs/en/next/babel-plugin-transform-block-scoped-functions.html) for more information. -**In** +## Install -```javascript -{ - function name (n) { - return n; - } -} - -name("Steve"); -``` - -**Out** - -```javascript -{ - let name = function (n) { - return n; - }; -} -name("Steve"); -``` - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-transform-block-scoped-functions +npm install --save @babel/plugin-transform-block-scoped-functions ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-transform-block-scoped-functions"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-transform-block-scoped-functions script.js -``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-transform-block-scoped-functions"] -}); +yarn add --save @babel/plugin-transform-block-scoped-functions ``` diff --git a/packages/babel-plugin-transform-block-scoping/README.md b/packages/babel-plugin-transform-block-scoping/README.md index 7c174e506f..0079437cf1 100644 --- a/packages/babel-plugin-transform-block-scoping/README.md +++ b/packages/babel-plugin-transform-block-scoping/README.md @@ -2,102 +2,18 @@ > Compile ES2015 block scoping (const and let) to ES5 -## Examples +See our website [@babel/plugin-transform-block-scoping](https://new.babeljs.io/docs/en/next/babel-plugin-transform-block-scoping.html) for more information. -**In** +## Install -```javascript -{ - let a = 3 -} - -let a = 3 -``` - -**Out** - -```javascript -{ - var _a = 3; -} - -var a = 3; -``` - -## Constant checks - -This plugin also validates all `const` variables. -Reassignment of constants is a runtime error and it will insert the necessary error code for those. - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-transform-block-scoping +npm install --save @babel/plugin-transform-block-scoping ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -Without options: - -```json -{ - "plugins": ["@babel/plugin-transform-block-scoping"] -} -``` - -With options: - -```json -{ - "plugins": [ - ["@babel/plugin-transform-block-scoping", { - "throwIfClosureRequired": true - }] - ] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-transform-block-scoping script.js +yarn add --save @babel/plugin-transform-block-scoping ``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-transform-block-scoping"] -}); -``` - -## Options - -### `throwIfClosureRequired` -`boolean`, defaults to `false`. - -In cases such as the following it's impossible to rewrite let/const without adding an additional function and closure while transforming: - -```javascript -for (let i = 0; i < 5; i++) { - setTimeout(() => console.log(i), 1); -} -``` - -In extremely performance-sensitive code, this can be undesirable. If `"throwIfClosureRequired": true` is set, Babel throws when transforming these patterns instead of automatically adding an additional function. - -### `tdz` -`boolean`, defaults to `false`. - -By default this plugin will ignore the *temporal dead zone (TDZ)* for block-scoped variables. The following code will **not throw an error when transpiled with Babel, which is not spec compliant**: - -```javascript -i -let i; -``` - -If you need these errors you can tell Babel to try and find them by setting `"tdz": true` for this plugin. However, the current implementation might not get all edge cases right and its best to just avoid code like this in the first place. diff --git a/packages/babel-plugin-transform-classes/README.md b/packages/babel-plugin-transform-classes/README.md index b0f5130791..bca766cb5a 100644 --- a/packages/babel-plugin-transform-classes/README.md +++ b/packages/babel-plugin-transform-classes/README.md @@ -2,126 +2,18 @@ > Compile ES2015 classes to ES5 -## Caveats +See our website [@babel/plugin-transform-classes](https://new.babeljs.io/docs/en/next/babel-plugin-transform-classes.html) for more information. -When extending a native class (e.g., `class extends Array {}`), the super class -needs to be wrapped. This is needed to workaround two problems: -- Babel transpiles classes using `SuperClass.apply(/* ... */)`, but native - classes aren't callable and thus throw in this case. -- Some built-in functions (like `Array`) always return a new object. Instead of - returning it, Babel should treat it as the new `this`. +## Install -The wrapper works on IE11 and every other browser with `Object.setPrototypeOf` or `__proto__` as fallback. -There is **NO IE <= 10 support**. If you need IE <= 10 it's recommended that you don't extend natives. - -## Examples - -**In** - -```javascript -class Test { - constructor(name) { - this.name = name; - } - - logger () { - console.log("Hello", this.name); - } -} -``` - -**Out** - -```javascript -function _classCallCheck(instance, Constructor) { if (!(instance instanceof Constructor)) { throw new TypeError("Cannot call a class as a function"); } } - -var Test = function () { - function Test(name) { - _classCallCheck(this, Test); - - this.name = name; - } - - Test.prototype.logger = function logger() { - console.log("Hello", this.name); - }; - - return Test; -}(); -``` - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-transform-classes +npm install --save @babel/plugin-transform-classes ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```js -// without options -{ - "plugins": ["@babel/plugin-transform-classes"] -} - -// with options -{ - "plugins": [ - ["@babel/plugin-transform-classes", { - "loose": true - }] - ] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-transform-classes script.js +yarn add --save @babel/plugin-transform-classes ``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-transform-classes"] -}); -``` - -## Options - -### `loose` - -`boolean`, defaults to `false`. - -#### Method enumerability - -Please note that in loose mode class methods **are** enumerable. This is not in line -with the spec and you may run into issues. - -#### Method assignment - -Under loose mode, methods are defined on the class prototype with simple assignments -instead of being defined. This can result in the following not working: - -```javascript -class Foo { - set bar() { - throw new Error("foo!"); - } -} - -class Bar extends Foo { - bar() { - // will throw an error when this method is defined - } -} -``` - -When `Bar.prototype.foo` is defined it triggers the setter on `Foo`. This is a -case that is very unlikely to appear in production code however it's something -to keep in mind. diff --git a/packages/babel-plugin-transform-computed-properties/README.md b/packages/babel-plugin-transform-computed-properties/README.md index 0a420ba051..8d923ec444 100644 --- a/packages/babel-plugin-transform-computed-properties/README.md +++ b/packages/babel-plugin-transform-computed-properties/README.md @@ -2,129 +2,18 @@ > Compile ES2015 computed properties to ES5 -## Example +See our website [@babel/plugin-transform-computed-properties](https://new.babeljs.io/docs/en/next/babel-plugin-transform-computed-properties.html) for more information. -**In** +## Install -```js -var obj = { - ["x" + foo]: "heh", - ["y" + bar]: "noo", - foo: "foo", - bar: "bar" -}; -``` - -**Out** - -```js -var _obj; - -function _defineProperty(obj, key, value) { - if (key in obj) { - Object.defineProperty(obj, key, { - value: value, - enumerable: true, - configurable: true, - writable: true - }); - } else { - obj[key] = value; - } - - return obj; -} - -var obj = ( - _obj = {}, - _defineProperty(_obj, "x" + foo, "heh"), - _defineProperty(_obj, "y" + bar, "noo"), - _defineProperty(_obj, "foo", "foo"), - _defineProperty(_obj, "bar", "bar"), - _obj -); -``` - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-transform-computed-properties +npm install --save @babel/plugin-transform-computed-properties ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -Without options: - -```json -{ - "plugins": ["@babel/plugin-transform-computed-properties"] -} -``` - -With options: - -```json -{ - "plugins": [ - ["@babel/plugin-transform-computed-properties", { - "loose": true - }] - ] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-transform-computed-properties script.js -``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-transform-computed-properties"] -}); -``` - -## Options - -### `loose` - -`boolean`, defaults to `false` - -Just like method assignment in classes, in loose mode, computed property names -use simple assignments instead of being defined. This is unlikely to be an issue -in production code. - -#### Example - -***In*** - -```js -var obj = { - ["x" + foo]: "heh", - ["y" + bar]: "noo", - foo: "foo", - bar: "bar" -}; -``` - -***Out*** - -```js -var _obj; - -var obj = ( - _obj = {}, - _obj["x" + foo] = "heh", - _obj["y" + bar] = "noo", - _obj.foo = "foo", - _obj.bar = "bar", - _obj -); +yarn add --save @babel/plugin-transform-computed-properties ``` diff --git a/packages/babel-plugin-transform-destructuring/README.md b/packages/babel-plugin-transform-destructuring/README.md index d31e0e206e..a38288bbd5 100644 --- a/packages/babel-plugin-transform-destructuring/README.md +++ b/packages/babel-plugin-transform-destructuring/README.md @@ -2,103 +2,18 @@ > Compile ES2015 destructuring to ES5 -## Examples +See our website [@babel/plugin-transform-destructuring](https://new.babeljs.io/docs/en/next/babel-plugin-transform-destructuring.html) for more information. -**In** +## Install -```javascript -let {x, y} = obj; - -let [a, b, ...rest] = arr; -``` - -**Out** - -```javascript -function _toArray(arr) { ... } - -let _obj = obj, - x = _obj.x, - y = _obj.y; - -let _arr = arr, - _arr2 = _toArray(_arr), - a = _arr2[0], - b = _arr2[1], - rest = _arr2.slice(2); -``` - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-transform-destructuring +npm install --save @babel/plugin-transform-destructuring ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-transform-destructuring"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-transform-destructuring script.js +yarn add --save @babel/plugin-transform-destructuring ``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-transform-destructuring"] -}); -``` - -## Options - -### `loose` - -`boolean`, defaults to `false`. - -Enabling this option will assume that what you want to destructure is an array and won't use `Array.from` on other iterables. - -### `useBuiltIns` - -`boolean`, defaults to `false`. - -Enabling this option will use `Object.assign` directly instead of the Babel's `extends` helper. - -##### Example - -**.babelrc** - -```json -{ - "plugins": [ - ["@babel/plugin-transform-destructuring", { "useBuiltIns": true }] - ] -} -``` - -**In** - -```js -var { ...x } = z; -``` - -**Out** - -```js -var _z = z, - x = Object.assign({}, _z); -``` - -## References - -* [MDN: Destructuring assignment](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment) diff --git a/packages/babel-plugin-transform-dotall-regex/README.md b/packages/babel-plugin-transform-dotall-regex/README.md index d180193c86..72965883ea 100644 --- a/packages/babel-plugin-transform-dotall-regex/README.md +++ b/packages/babel-plugin-transform-dotall-regex/README.md @@ -1,69 +1,19 @@ # @babel/plugin-transform-dotall-regex -> Compile regular expressions using [the `s` (`dotAll`) flag](https://github.com/tc39/proposal-regexp-dotall-flag) to ES5 that works in today’s environments. +> Compile regular expressions using the `s` (`dotAll`) flag to ES5. -## Example +See our website [@babel/plugin-transform-dotall-regex](https://new.babeljs.io/docs/en/next/babel-plugin-transform-dotall-regex.html) for more information. -**In** +## Install -```js -/./s -``` - -**Out** - -```js -/[\0-\uFFFF]/ -``` - -**In** - -```js -/./su -``` - -**Out** - -```js -/[\0-\u{10FFFF}]/u -``` - -[Here’s an online demo.](https://mothereff.in/regexpu#input=const+regex+%3D+/foo.bar/s%3B%0Aconsole.log%28%0A++regex.test%28%27foo%5Cnbar%27%29%0A%29%3B%0A//+%E2%86%92+true&dotAllFlag=1) - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-transform-dotall-regex +npm install --save @babel/plugin-transform-dotall-regex ``` -## Usage - -### Via `.babelrc` (recommended) - -`.babelrc` - -```json -{ - "plugins": ["@babel/plugin-transform-dotall-regex"] -} -``` - -### Via CLI +or using yarn: ```sh -$ babel --plugins @babel/plugin-transform-dotall-regex script.js +yarn add --save @babel/plugin-transform-dotall-regex ``` - -### Via Node.js API - -```js -require('@babel/core').transform(code, { - 'plugins': ['@babel/plugin-transform-dotall-regex'] -}); -``` - -## Author - -| [![twitter/mathias](https://gravatar.com/avatar/24e08a9ea84deb17ae121074d0f17125?s=70)](https://twitter.com/mathias "Follow @mathias on Twitter") | -|---| -| [Mathias Bynens](https://mathiasbynens.be/) | diff --git a/packages/babel-plugin-transform-duplicate-keys/README.md b/packages/babel-plugin-transform-duplicate-keys/README.md index a64bac733e..276cc50fe7 100644 --- a/packages/babel-plugin-transform-duplicate-keys/README.md +++ b/packages/babel-plugin-transform-duplicate-keys/README.md @@ -1,61 +1,19 @@ # @babel/plugin-transform-duplicate-keys -> Compile objects with duplicate keys to valid strict ES5. +> Compile objects with duplicate keys to valid strict ES5 -This plugin actually converts duplicate keys in objects to be computed properties, which then must be handled by the [@babel/plugin-transform-computed-properties](http://babeljs.io/docs/plugins/transform-computed-properties) plugin. The final result won't contain any object literals with duplicate keys. +See our website [@babel/plugin-transform-duplicate-keys](https://new.babeljs.io/docs/en/next/babel-plugin-transform-duplicate-keys.html) for more information. -## Example +## Install -**In** - -```javascript -var x = { a: 5, a: 6 }; -var y = { - get a() {}, - set a(x) {}, - a: 3 -}; -``` - -**Out** - -```javascript -var x = { a: 5, ["a"]: 6 }; -var y = { - get a() {}, - set a(x) {}, - ["a"]: 3 -}; -``` - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-transform-duplicate-keys +npm install --save @babel/plugin-transform-duplicate-keys ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-transform-duplicate-keys"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-transform-duplicate-keys script.js -``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-transform-duplicate-keys"] -}); +yarn add --save @babel/plugin-transform-duplicate-keys ``` diff --git a/packages/babel-plugin-transform-exponentiation-operator/README.md b/packages/babel-plugin-transform-exponentiation-operator/README.md index 92d1d3ca1e..939bfbde7f 100644 --- a/packages/babel-plugin-transform-exponentiation-operator/README.md +++ b/packages/babel-plugin-transform-exponentiation-operator/README.md @@ -2,57 +2,18 @@ > Compile exponentiation operator to ES5 -## Example +See our website [@babel/plugin-transform-exponentiation-operator](https://new.babeljs.io/docs/en/next/babel-plugin-transform-exponentiation-operator.html) for more information. -**In** +## Install -```javascript -let x = 10 ** 2; - -x **= 3; -``` - -**Out** - -```javascript -let x = Math.pow(10, 2); - -x = Math.pow(x, 3); -``` - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-transform-exponentiation-operator +npm install --save @babel/plugin-transform-exponentiation-operator ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-transform-exponentiation-operator"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-transform-exponentiation-operator script.js +yarn add --save @babel/plugin-transform-exponentiation-operator ``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-transform-exponentiation-operator"] -}); -``` - -## References - -* [Proposal: Exponentiation Operator](https://github.com/rwaldron/exponentiation-operator) -* [Spec: Exponential Operator](https://rwaldron.github.io/exponentiation-operator/) diff --git a/packages/babel-plugin-transform-flow-comments/README.md b/packages/babel-plugin-transform-flow-comments/README.md index df969692ac..72ac1a9c64 100644 --- a/packages/babel-plugin-transform-flow-comments/README.md +++ b/packages/babel-plugin-transform-flow-comments/README.md @@ -1,71 +1,19 @@ # @babel/plugin-transform-flow-comments -> Turn flow type annotations into comments. +> Turn flow type annotations into comments -You should be able to use this plugin instead of `@babel/plugin-flow-strip-types` to preserve the `/* @flow */` directive and still use flow. +See our website [@babel/plugin-transform-flow-comments](https://new.babeljs.io/docs/en/next/babel-plugin-transform-flow-comments.html) for more information. -[Flow Comments Blog Post](http://flowtype.org/blog/2015/02/20/Flow-Comments.html) +## Install -## Example - -**In** - -```javascript -function foo(bar?) {} -function foo2(bar?: string) {} -function foo(x: number): string {} -type B = { - name: string; -}; -export type GraphQLFormattedError = number; -import type A, { B, C } from './types'; -import typeof D, { E, F } from './types'; -``` - -**Out** - -```javascript -"use strict"; - -function foo(bar /*:: ?*/) {} -function foo2(bar /*:: ?: string*/) {} -function foo(x /*: number*/) /*: string*/ {} -/*:: type B = { - name: string; -};*/ -/*:: export type GraphQLFormattedError = number;*/ -/*:: import type A, { B, C } from './types';*/ -/*:: import typeof D, { E, F } from './types';*/ -``` - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-transform-flow-comments +npm install --save @babel/plugin-transform-flow-comments ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-transform-flow-comments"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-transform-flow-comments script.js -``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-transform-flow-comments"] -}); +yarn add --save @babel/plugin-transform-flow-comments ``` diff --git a/packages/babel-plugin-transform-flow-strip-types/README.md b/packages/babel-plugin-transform-flow-strip-types/README.md index 01b7634e4f..564e2537de 100644 --- a/packages/babel-plugin-transform-flow-strip-types/README.md +++ b/packages/babel-plugin-transform-flow-strip-types/README.md @@ -1,59 +1,19 @@ # @babel/plugin-transform-flow-strip-types -> Strip all [flow](http://flowtype.org) type annotations and declarations from your output code. +> Strip flow type annotations from your output code. -## Example +See our website [@babel/plugin-transform-flow-strip-types](https://new.babeljs.io/docs/en/next/babel-plugin-transform-flow-strip-types.html) for more information. -**In** +## Install -```javascript -function foo(one: any, two: number, three?): string {} -``` - -**Out** - -```javascript -function foo(one, two, three) {} -``` - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-transform-flow-strip-types +npm install --save @babel/plugin-transform-flow-strip-types ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-transform-flow-strip-types"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-transform-flow-strip-types script.js +yarn add --save @babel/plugin-transform-flow-strip-types ``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-transform-flow-strip-types"] -}); -``` - -## Options - -### `requireDirective` - -`boolean`, defaults to `false`. - -Setting this to true will only strip annotations and declarations from files -that contain the `// @flow` directive. It will also throw errors for any Flow -annotations found in files without the directive. diff --git a/packages/babel-plugin-transform-for-of/README.md b/packages/babel-plugin-transform-for-of/README.md index 4a8c5263fe..b9bfd843d8 100644 --- a/packages/babel-plugin-transform-for-of/README.md +++ b/packages/babel-plugin-transform-for-of/README.md @@ -2,153 +2,18 @@ > Compile ES2015 for...of to ES5 -## Example +See our website [@babel/plugin-transform-for-of](https://new.babeljs.io/docs/en/next/babel-plugin-transform-for-of.html) for more information. -**In** +## Install -```js -for (var i of foo) {} -``` - -**Out** - -```js -var _iteratorNormalCompletion = true; -var _didIteratorError = false; -var _iteratorError = undefined; - -try { - for (var _iterator = foo[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true) { - var i = _step.value; - } -} catch (err) { - _didIteratorError = true; - _iteratorError = err; -} finally { - try { - if (!_iteratorNormalCompletion && _iterator.return != null) { - _iterator.return(); - } - } finally { - if (_didIteratorError) { - throw _iteratorError; - } - } -} -``` - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-transform-for-of +npm install --save @babel/plugin-transform-for-of ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -Without options: - -```js -{ - "plugins": ["@babel/plugin-transform-for-of"] -} -``` - -With options: - -```js -{ - "plugins": [ - ["@babel/plugin-transform-for-of", { - "loose": true, // defaults to false - "assumeArray": true // defaults to false - }] - ] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-transform-for-of script.js -``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-transform-for-of"] -}); -``` - -## Options - -### `loose` - -`boolean`, defaults to `false` - -In loose mode, arrays are put in a fast path, thus heavily increasing performance. -All other iterables will continue to work fine. - -#### Example - -**In** - -```js -for (var i of foo) {} -``` - -**Out** - -```js -for (var _iterator = foo, _isArray = Array.isArray(_iterator), _i = 0, _iterator = _isArray ? _iterator : _iterator[Symbol.iterator]();;) { - var _ref; - - if (_isArray) { - if (_i >= _iterator.length) break; - _ref = _iterator[_i++]; - } else { - _i = _iterator.next(); - if (_i.done) break; - _ref = _i.value; - } - - var i = _ref; -} -``` - -#### Abrupt completions - -In loose mode an iterator's `return` method will not be called on abrupt completions caused by thrown errors. - -Please see [google/traceur-compiler#1773](https://github.com/google/traceur-compiler/issues/1773) and -[babel/babel#838](https://github.com/babel/babel/issues/838) for more information. - -### `assumeArray` -`boolean`, defaults to `false` - -This will apply the optimization shown below to all for-of loops by assuming that _all_ loops are arrays. - -Can be useful when you just want a for-of loop to represent a basic for loop over an array. - -### Optimization - -If a basic array is used, Babel will compile the for-of loop down to a regular for loop. - -**In** - -```js -for (let a of [1,2,3]) {} -``` - -**Out** - -```js -var _arr = [1, 2, 3]; -for (var _i = 0; _i < _arr.length; _i++) { - var a = _arr[_i]; -} +yarn add --save @babel/plugin-transform-for-of ``` diff --git a/packages/babel-plugin-transform-function-name/README.md b/packages/babel-plugin-transform-function-name/README.md index 71c63f72d5..6ce60dddae 100644 --- a/packages/babel-plugin-transform-function-name/README.md +++ b/packages/babel-plugin-transform-function-name/README.md @@ -2,50 +2,18 @@ > Apply ES2015 function.name semantics to all functions -## Examples +See our website [@babel/plugin-transform-function-name](https://new.babeljs.io/docs/en/next/babel-plugin-transform-function-name.html) for more information. -**In** +## Install -```javascript -let number = (x) => x -``` - -**Out** - -```javascript -var number = function number(x) { - return x; -}; -``` - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-transform-function-name +npm install --save @babel/plugin-transform-function-name ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-transform-function-name"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-transform-function-name script.js -``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-transform-function-name"] -}); +yarn add --save @babel/plugin-transform-function-name ``` diff --git a/packages/babel-plugin-transform-instanceof/README.md b/packages/babel-plugin-transform-instanceof/README.md index 6b2a13e5e2..5bc08787e8 100644 --- a/packages/babel-plugin-transform-instanceof/README.md +++ b/packages/babel-plugin-transform-instanceof/README.md @@ -1,62 +1,19 @@ # @babel/plugin-transform-instanceof -> Wraps `instanceof` expressions to allow constructors to customize the logic with a `Symbol.hasInstance` method +> This plugin transforms all the ES2015 'instanceof' methods -## Example +See our website [@babel/plugin-transform-instanceof](https://new.babeljs.io/docs/en/next/babel-plugin-transform-instanceof.html) for more information. -**In** +## Install -```javascript -foo instanceof Bar; -``` - -**Out** - -```javascript -function _instanceof(left, right) { - if (right != null && typeof Symbol !== "undefined" && right[Symbol.hasInstance]) { - return right[Symbol.hasInstance](left); - } else { - return left instanceof right; - } -} - -_instanceof(foo, Bar); -``` - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-transform-instanceof +npm install --save @babel/plugin-transform-instanceof ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-transform-instanceof"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-transform-instanceof script.js +yarn add --save @babel/plugin-transform-instanceof ``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-transform-instanceof"] -}); -``` - -## References - -* [ES6 Spec: InstanceOf Operator Semantics](https://www.ecma-international.org/ecma-262/6.0/#sec-instanceofoperator) -* [MDN: Symbol.hasInstance](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/hasInstance) diff --git a/packages/babel-plugin-transform-jscript/README.md b/packages/babel-plugin-transform-jscript/README.md index fb90287123..cc86cadab9 100644 --- a/packages/babel-plugin-transform-jscript/README.md +++ b/packages/babel-plugin-transform-jscript/README.md @@ -1,57 +1,19 @@ # @babel/plugin-transform-jscript -> This plugin allows Babel to transform named function expressions into function declarations to get around some [particularly nasty JScript bugs](https://kangax.github.io/nfe/#jscript-bugs) related to name function expressions. +> Babel plugin to fix buggy JScript named function expressions -## Example +See our website [@babel/plugin-transform-jscript](https://new.babeljs.io/docs/en/next/babel-plugin-transform-jscript.html) for more information. -**In** +## Install -```javascript -var foo = function bar() { - -}; -``` - -**Out** - -```javascript -"use strict"; - -var foo = (function () { - function bar() {} - - return bar; -})(); -``` - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-transform-jscript +npm install --save @babel/plugin-transform-jscript ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-transform-jscript"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-transform-jscript script.js -``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-transform-jscript"] -}); +yarn add --save @babel/plugin-transform-jscript ``` diff --git a/packages/babel-plugin-transform-literals/README.md b/packages/babel-plugin-transform-literals/README.md index adc5c3abfb..a323bbf6e3 100644 --- a/packages/babel-plugin-transform-literals/README.md +++ b/packages/babel-plugin-transform-literals/README.md @@ -2,52 +2,18 @@ > Compile ES2015 unicode string and number literals to ES5 -## Example +See our website [@babel/plugin-transform-literals](https://new.babeljs.io/docs/en/next/babel-plugin-transform-literals.html) for more information. -**In** +## Install -```js -var b = 0b11; // binary integer literal -var o = 0o7; // octal integer literal -const u = 'Hello\u{000A}\u{0009}!'; // unicode string literals, newline and tab -``` - -**Out** - -```js -var b = 3; // binary integer literal -var o = 7; // octal integer literal -const u = 'Hello\n\t!'; // unicode string literals, newline and tab -``` - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-transform-literals +npm install --save @babel/plugin-transform-literals ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-transform-literals"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-transform-literals script.js -``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-transform-literals"] -}); +yarn add --save @babel/plugin-transform-literals ``` diff --git a/packages/babel-plugin-transform-member-expression-literals/README.md b/packages/babel-plugin-transform-member-expression-literals/README.md index 4703fef0a5..0054b8c9c0 100644 --- a/packages/babel-plugin-transform-member-expression-literals/README.md +++ b/packages/babel-plugin-transform-member-expression-literals/README.md @@ -2,48 +2,18 @@ > Ensure that reserved words are quoted in property accesses -## Example +See our website [@babel/plugin-transform-member-expression-literals](https://new.babeljs.io/docs/en/next/babel-plugin-transform-member-expression-literals.html) for more information. -**In** +## Install -```javascript -foo.catch; -``` - -**Out** - -```javascript -foo["catch"]; -``` - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-transform-member-expression-literals +npm install --save @babel/plugin-transform-member-expression-literals ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-transform-member-expression-literals"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-transform-member-expression-literals script.js -``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-transform-member-expression-literals"] -}); +yarn add --save @babel/plugin-transform-member-expression-literals ``` diff --git a/packages/babel-plugin-transform-modules-amd/README.md b/packages/babel-plugin-transform-modules-amd/README.md index eecd35da2d..48a5e0fbd2 100644 --- a/packages/babel-plugin-transform-modules-amd/README.md +++ b/packages/babel-plugin-transform-modules-amd/README.md @@ -1,61 +1,19 @@ # @babel/plugin-transform-modules-amd -> This plugin transforms ES2015 modules to [Asynchronous Module Definition (AMD)](https://github.com/amdjs/amdjs-api). +> This plugin transforms ES2015 modules to AMD -## Example +See our website [@babel/plugin-transform-modules-amd](https://new.babeljs.io/docs/en/next/babel-plugin-transform-modules-amd.html) for more information. -**In** +## Install -```javascript -export default 42; -``` - -**Out** - -```javascript -define(["exports"], function (exports) { - "use strict"; - - Object.defineProperty(exports, "__esModule", { - value: true - }); - - exports.default = 42; -}); -``` - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-transform-modules-amd +npm install --save @babel/plugin-transform-modules-amd ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-transform-modules-amd"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-transform-modules-amd script.js +yarn add --save @babel/plugin-transform-modules-amd ``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-transform-modules-amd"] -}); -``` - -### Options - -See options for `@babel/plugin-transform-modules-commonjs`. diff --git a/packages/babel-plugin-transform-modules-commonjs/README.md b/packages/babel-plugin-transform-modules-commonjs/README.md index 96c1a2b832..70c93ba517 100644 --- a/packages/babel-plugin-transform-modules-commonjs/README.md +++ b/packages/babel-plugin-transform-modules-commonjs/README.md @@ -1,163 +1,19 @@ # @babel/plugin-transform-modules-commonjs -> This plugin transforms ES2015 modules to [CommonJS](http://wiki.commonjs.org/wiki/Modules/1.1). +> This plugin transforms ES2015 modules to CommonJS -## Example +See our website [@babel/plugin-transform-modules-commonjs](https://new.babeljs.io/docs/en/next/babel-plugin-transform-modules-commonjs.html) for more information. -**In** +## Install -```javascript -export default 42; -``` - -**Out** - -```javascript -Object.defineProperty(exports, "__esModule", { - value: true -}); - -exports.default = 42; -``` - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-transform-modules-commonjs +npm install --save @babel/plugin-transform-modules-commonjs ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```js -// without options -{ - "plugins": ["@babel/plugin-transform-modules-commonjs"] -} - -// with options -{ - "plugins": [ - ["@babel/plugin-transform-modules-commonjs", { - "allowTopLevelThis": true - }] - ] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-transform-modules-commonjs script.js +yarn add --save @babel/plugin-transform-modules-commonjs ``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-transform-modules-commonjs"] -}); -``` - -## Options - -### `loose` - -`boolean`, defaults to `false`. - -By default, when using exports with babel a non-enumerable `__esModule` property -is exported. - -```javascript -var foo = exports.foo = 5; - -Object.defineProperty(exports, "__esModule", { - value: true -}); -``` - -In environments that don't support this you can enable loose mode on `@babel/plugin-transform-modules-commonjs` -and instead of using `Object.defineProperty` an assignment will be used instead. - -```javascript -var foo = exports.foo = 5; -exports.__esModule = true; -``` - -### `strict` - -`boolean`, defaults to `false` - -By default, when using exports with babel a non-enumerable `__esModule` property -is exported. In some cases this property is used to determine if the import _is_ the -default export or if it _contains_ the default export. - -```javascript -var foo = exports.foo = 5; - -Object.defineProperty(exports, "__esModule", { - value: true -}); -``` - -In order to prevent the `__esModule` property from being exported, you can set -the `strict` option to `true`. - -### `noInterop` - -`boolean`, defaults to `false` - -By default, when using exports with babel a non-enumerable `__esModule` property -is exported. This property is then used to determine if the import _is_ the default -export or if it _contains_ the default export. - -```javascript -"use strict"; - -var _foo = _interopRequireDefault(require("foo")); - -function _interopRequireDefault(obj) { - return obj && obj.__esModule ? obj : { default: obj }; -} -``` - -In cases where the auto-unwrapping of `default` is not needed, you can set the -`noInterop` option to `true` to avoid the usage of the `interopRequireDefault` -helper (shown in inline form above). - -### `lazy` - -`boolean`, `Array`, or `(string) => boolean`, defaults to `false` - -Changes Babel's compiled `import` statements to be lazily evaluated when their -imported bindings are used for the first time. - -This can improve initial load time of your module because evaluating -dependencies up front is sometimes entirely un-necessary. This is especially -the case when implementing a library module. - -The value of `lazy` has a few possible effects: - -* `false` - No lazy initialization of any imported module. -* `true` - Do not lazy-initialize local `./foo` imports, but lazy-init `foo` dependencies. - - Local paths are much more likely to have circular dependencies, which may break if loaded lazily, - so they are not lazy by default, whereas dependencies between independent modules are rarely cyclical. - -* `Array` - Lazy-initialize all imports with source matching one of the given strings. -* `(string) => boolean` - Pass a callback that will be called to decide if a given source string should be lazy-loaded. - -The two cases where imports can never be lazy are: - -* `import "foo";` - - Side-effect imports are automatically non-lazy since their very existence means - that there is no binding to later kick off initialization. - -* `export * from "foo"` - - Re-exporting all names requires up-front execution because otherwise there is no - way to know what names need to be exported. diff --git a/packages/babel-plugin-transform-modules-systemjs/README.md b/packages/babel-plugin-transform-modules-systemjs/README.md index 23c27bd3b3..8918a0d770 100644 --- a/packages/babel-plugin-transform-modules-systemjs/README.md +++ b/packages/babel-plugin-transform-modules-systemjs/README.md @@ -1,73 +1,19 @@ # @babel/plugin-transform-modules-systemjs -> This plugin transforms ES2015 modules to [SystemJS](https://github.com/systemjs/systemjs). +> This plugin transforms ES2015 modules to SystemJS -## Example +See our website [@babel/plugin-transform-modules-systemjs](https://new.babeljs.io/docs/en/next/babel-plugin-transform-modules-systemjs.html) for more information. -**In** +## Install -```javascript -export default 42; -``` - -**Out** - -```javascript -System.register([], function (_export, _context) { - return { - setters: [], - execute: function () { - _export("default", 42); - } - }; -}); -``` - -For dynamic import support (`import('./lazy.js').then(m => ...)`), enable the [@babel/plugin-syntax-dynamic-import](https://babeljs.io/docs/plugins/syntax-dynamic-import/) plugin before this one. - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-transform-modules-systemjs +npm install --save @babel/plugin-transform-modules-systemjs ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -Without options: - -```json -{ - "plugins": ["@babel/plugin-transform-modules-systemjs"] -} -``` - -With options: - -```json -{ - "plugins": [ - ["@babel/plugin-transform-modules-systemjs", { - // outputs SystemJS.register(...) - "systemGlobal": "SystemJS" - }] - ] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-transform-modules-systemjs script.js -``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-transform-modules-systemjs"] -}); +yarn add --save @babel/plugin-transform-modules-systemjs ``` diff --git a/packages/babel-plugin-transform-modules-umd/README.md b/packages/babel-plugin-transform-modules-umd/README.md index a8a919adf2..7dd7762ab1 100644 --- a/packages/babel-plugin-transform-modules-umd/README.md +++ b/packages/babel-plugin-transform-modules-umd/README.md @@ -1,214 +1,19 @@ # @babel/plugin-transform-modules-umd -> This plugin transforms ES2015 modules to [Universal Module Definition (UMD)](https://github.com/umdjs/umd). +> This plugin transforms ES2015 modules to UMD -## Example +See our website [@babel/plugin-transform-modules-umd](https://new.babeljs.io/docs/en/next/babel-plugin-transform-modules-umd.html) for more information. -**In** +## Install -```javascript -export default 42; -``` - -**Out** - -```javascript -(function (global, factory) { - if (typeof define === "function" && define.amd) { - define(["exports"], factory); - } else if (typeof exports !== "undefined") { - factory(exports); - } else { - var mod = { - exports: {} - }; - factory(mod.exports); - global.actual = mod.exports; - } -})(this, function (exports) { - "use strict"; - - Object.defineProperty(exports, "__esModule", { - value: true - }); - - exports.default = 42; -}); -``` - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-transform-modules-umd +npm install --save @babel/plugin-transform-modules-umd ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-transform-modules-umd"] -} -``` - -You can also override the names of particular libraries when this module is -running in the browser. For example the `es6-promise` library exposes itself -as `global.Promise` rather than `global.es6Promise`. This can be accommodated by: - -```json -{ - "plugins": [ - ["@babel/plugin-transform-modules-umd", { - "globals": { - "es6-promise": "Promise" - } - }] - ] -} -``` - -#### Default semantics - -There are a few things to note about the default semantics. - -_First_, this transform uses the -[basename](https://en.wikipedia.org/wiki/Basename) of each import to generate -the global names in the UMD output. This means that if you're importing -multiple modules with the same basename, like: - -```js -import fooBar1 from "foo-bar"; -import fooBar2 from "./mylib/foo-bar"; -``` - -it will transpile into two references to the same browser global: - -```js -factory(global.fooBar, global.fooBar); -``` - -If you set the plugin options to: - -```json -{ - "globals": { - "foo-bar": "fooBAR", - "./mylib/foo-bar": "mylib.fooBar" - } -} -``` - -it will still transpile both to one browser global: - -```js -factory(global.fooBAR, global.fooBAR); -``` - -because again the transform is only using the basename of the import. - -_Second_, the specified override will still be passed to the `toIdentifier` -function in [babel-types/src/converters](https://github.com/babel/babel/blob/master/packages/babel-types/src/converters.js). -This means that if you specify an override as a member expression like: - -```json -{ - "globals": { - "fizzbuzz": "fizz.buzz" - } -} -``` - -this will _not_ transpile to `factory(global.fizz.buzz)`. Instead, it will -transpile to `factory(global.fizzBuzz)` based on the logic in `toIdentifier`. - -_Third_, you cannot override the exported global name. - -#### More flexible semantics with `exactGlobals: true` - -All of these behaviors can limit the flexibility of the `globals` map. To -remove these limitations, you can set the `exactGlobals` option to `true`. -Doing this instructs the plugin to: - -1. always use the full import string instead of the basename when generating -the global names -2. skip passing `globals` overrides to the `toIdentifier` function. Instead, -they are used exactly as written, so you will get errors if you do not use -valid identifiers or valid uncomputed (dot) member expressions. -3. allow the exported global name to be overridden via the `globals` map. Any -override must again be a valid identifier or valid member expression. - -Thus, if you set `exactGlobals` to `true` and do not pass any overrides, the -first example of: - -```js -import fooBar1 from "foo-bar"; -import fooBar2 from "./mylib/foo-bar"; -``` - -will transpile to: - -```js -factory(global.fooBar, global.mylibFooBar); -``` - -And if you set the plugin options to: - -```json -{ - "globals": { - "foo-bar": "fooBAR", - "./mylib/foo-bar": "mylib.fooBar" - }, - "exactGlobals": true -} -``` - -then it'll transpile to: - -```js -factory(global.fooBAR, global.mylib.fooBar) -``` - -Finally, with the plugin options set to: - -```json -{ - "plugins": [ - "@babel/plugin-external-helpers", - ["@babel/plugin-transform-modules-umd", { - "globals": { - "my/custom/module/name": "My.Custom.Module.Name" - }, - "exactGlobals": true - }] - ], - "moduleId": "my/custom/module/name" -} -``` - -it will transpile to: - -```js -factory(mod.exports); -global.My = global.My || {}; -global.My.Custom = global.My.Custom || {}; -global.My.Custom.Module = global.My.Custom.Module || {}; -global.My.Custom.Module.Name = mod.exports; -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-transform-modules-umd script.js -``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-transform-modules-umd"] -}); +yarn add --save @babel/plugin-transform-modules-umd ``` diff --git a/packages/babel-plugin-transform-new-target/README.md b/packages/babel-plugin-transform-new-target/README.md index ccd5b4a407..d8cb31587d 100644 --- a/packages/babel-plugin-transform-new-target/README.md +++ b/packages/babel-plugin-transform-new-target/README.md @@ -1,104 +1,19 @@ # @babel/plugin-transform-new-target -This plugins allows babel to transform `new.target` meta property into a -(correct in most cases) `this.constructor` expression. +> Transforms new.target meta property -## Example +See our website [@babel/plugin-transform-new-target](https://new.babeljs.io/docs/en/next/babel-plugin-transform-new-target.html) for more information. -```js -function Foo() { - console.log(new.target); -} +## Install -Foo(); // => undefined -new Foo(); // => Foo -``` - -```js -class Foo { - constructor() { - console.log(new.target); - } -} - -class Bar extends Foo { -} - -new Foo(); // => Foo -new Bar(); // => Bar -``` - -### Caveats - -This plugin relies on `this.constructor`, which means `super` must -already have been called when using untransformed classes. - -```js -class Foo {} - -class Bar extends Foo { - constructor() { - // This will be a problem if classes aren't transformed to ES5 - new.target; - super(); - } -} -``` - -Additionally, this plugin cannot transform all `Reflect.construct` cases -when using `newTarget` with ES5 function classes (transformed ES6 classes). - -```js -function Foo() { - console.log(new.target); -} - -// Bar extends Foo in ES5 -function Bar() { - Foo.call(this); -} -Bar.prototype = Object.create(Foo.prototype); -Bar.prototype.constructor = Bar; - -// Baz does not extend Foo -function Baz() {} - -Reflect.construct(Foo, []); // => Foo (correct) -Reflect.construct(Foo, [], Bar); // => Bar (correct) - -Reflect.construct(Bar, []); // => Bar (incorrect, though this is how ES5 - // inheritience is commonly implemented.) -Reflect.construct(Foo, [], Baz); // => undefined (incorrect) -``` - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-transform-new-target +npm install --save @babel/plugin-transform-new-target ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-transform-new-target"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-transform-new-target script.js -``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-transform-new-target"] -}); +yarn add --save @babel/plugin-transform-new-target ``` diff --git a/packages/babel-plugin-transform-object-assign/README.md b/packages/babel-plugin-transform-object-assign/README.md index d083e38939..58d94f77b2 100644 --- a/packages/babel-plugin-transform-object-assign/README.md +++ b/packages/babel-plugin-transform-object-assign/README.md @@ -1,60 +1,19 @@ # @babel/plugin-transform-object-assign -> Replace `Object.assign` with an inline helper. If you are authoring an application, rather than a library, it is recommended that you use the `Object.assign` polyfill instead. +> Replace Object.assign with an inline helper -## Example +See our website [@babel/plugin-transform-object-assign](https://new.babeljs.io/docs/en/next/babel-plugin-transform-object-assign.html) for more information. -**In** +## Install -```javascript -Object.assign(a, b); -``` - -**Out** - -```javascript -var _extends = ...; - -_extends(a, b); -``` - -## Caveats - -- Will only work with code of the form `Object.assign` or `Object['assign']`. The following patterns are not supported: - - ```javascript - var { assign } = Object; - var assign = Object.assign; - ``` - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-transform-object-assign +npm install --save @babel/plugin-transform-object-assign ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-transform-object-assign"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-transform-object-assign script.js -``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-transform-object-assign"] -}); +yarn add --save @babel/plugin-transform-object-assign ``` diff --git a/packages/babel-plugin-transform-object-set-prototype-of-to-assign/README.md b/packages/babel-plugin-transform-object-set-prototype-of-to-assign/README.md index deb10e1f4e..a7500ccd3b 100644 --- a/packages/babel-plugin-transform-object-set-prototype-of-to-assign/README.md +++ b/packages/babel-plugin-transform-object-set-prototype-of-to-assign/README.md @@ -1,53 +1,19 @@ # @babel/plugin-transform-object-set-prototype-of-to-assign -> This plugin will transform all `Object.setPrototypeOf` calls to a method that will do a shallow defaults of all properties. +> Turn Object.setPrototypeOf to assignments -**NOTE:** There are some caveats when using this plugin, see the [`@babel/plugin-transform-proto-to-assign` README](https://github.com/babel/babel/tree/master/packages/babel-plugin-transform-proto-to-assign) for more information. +See our website [@babel/plugin-transform-object-set-prototype-of-to-assign](https://new.babeljs.io/docs/en/next/babel-plugin-transform-object-set-prototype-of-to-assign.html) for more information. -## Example +## Install -**In** - -```javascript -Object.setPrototypeOf(bar, foo); -``` - -**Out** - -```javascript -var _defaults = ...; - -_defaults(bar, foo); -``` - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-transform-object-set-prototype-of-to-assign +npm install --save @babel/plugin-transform-object-set-prototype-of-to-assign ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-transform-object-set-prototype-of-to-assign"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-transform-object-set-prototype-of-to-assign script.js -``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-transform-object-set-prototype-of-to-assign"] -}); +yarn add --save @babel/plugin-transform-object-set-prototype-of-to-assign ``` diff --git a/packages/babel-plugin-transform-object-super/README.md b/packages/babel-plugin-transform-object-super/README.md index 8fa757cfef..3f7eff9519 100644 --- a/packages/babel-plugin-transform-object-super/README.md +++ b/packages/babel-plugin-transform-object-super/README.md @@ -2,72 +2,18 @@ > Compile ES2015 object super to ES5 -## Examples +See our website [@babel/plugin-transform-object-super](https://new.babeljs.io/docs/en/next/babel-plugin-transform-object-super.html) for more information. -**In** +## Install -```javascript -let obj = { - say () { - return "Hello" - } -} - -let obj2 = { - say () { - return super.say() + "World!" - } -} -``` - -**Out** - -```javascript -var _obj; - -var _get = function get(object, property, receiver) { if (object === null) object = Function.prototype; var desc = Object.getOwnPropertyDescriptor(object, property); if (desc === undefined) { var parent = Object.getPrototypeOf(object); if (parent === null) { return undefined; } else { return get(parent, property, receiver); } } else if ("value" in desc) { return desc.value; } else { var getter = desc.get; if (getter === undefined) { return undefined; } return getter.call(receiver); } }; - -var obj = { - say: function say() { - return "Hello"; - } -}; - -var obj2 = _obj = { - say: function say() { - return _get(_obj.__proto__ || Object.getPrototypeOf(_obj), "say", this).call(this) + "World!"; - } -}; -``` - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-transform-object-super +npm install --save @babel/plugin-transform-object-super ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-transform-object-super"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-transform-object-super script.js -``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-transform-object-super"] -}); +yarn add --save @babel/plugin-transform-object-super ``` diff --git a/packages/babel-plugin-transform-parameters/README.md b/packages/babel-plugin-transform-parameters/README.md index 1c96bceee5..c51028faa4 100644 --- a/packages/babel-plugin-transform-parameters/README.md +++ b/packages/babel-plugin-transform-parameters/README.md @@ -2,93 +2,18 @@ > Compile ES2015 default and rest parameters to ES5 -This plugin transforms ES2015 parameters to ES5, this includes: +See our website [@babel/plugin-transform-parameters](https://new.babeljs.io/docs/en/next/babel-plugin-transform-parameters.html) for more information. -- Destructuring parameters -- Default parameters -- Rest parameters +## Install -## Examples - -**In** - -```javascript -function test(x = "hello", { a, b }, ...args) { - console.log(x, a, b, args); -} -``` - -**Out** - -```javascript -function test() { - var x = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : "hello"; - var _ref = arguments[1]; - var a = _ref.a, - b = _ref.b; - - for (var _len = arguments.length, args = Array(_len > 2 ? _len - 2 : 0), _key = 2; _key < _len; _key++) { - args[_key - 2] = arguments[_key]; - } - - console.log(x, a, b, args); -} -``` - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-transform-parameters +npm install --save @babel/plugin-transform-parameters ``` -## Caveats - -Default parameters desugar into `let` declarations to retain proper semantics. If this is -not supported in your environment then you'll need the -[@babel/plugin-transform-block-scoping](http://babeljs.io/docs/plugins/transform-block-scoping) plugin. - -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-transform-parameters"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-transform-parameters script.js -``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-transform-parameters"] -}); -``` - -## Options - -### `loose` - -`boolean`, defaults to `false`. - -In loose mode, parameters with default values will be counted into the arity of the function. This is not spec behavior where these parameters do not add to function arity. - -The `loose` implementation is a more performant solution as JavaScript engines will fully optimize a function that doesn't reference `arguments`. Please do your own benchmarking and determine if this option is the right fit for your application. - -```javascript -// Spec behavior -function bar1 (arg1 = 1) {} -bar1.length // 0 - -// Loose mode -function bar1 (arg1 = 1) {} -bar1.length // 1 +yarn add --save @babel/plugin-transform-parameters ``` diff --git a/packages/babel-plugin-transform-property-literals/README.md b/packages/babel-plugin-transform-property-literals/README.md index 3513c3372a..50c6ac77ec 100644 --- a/packages/babel-plugin-transform-property-literals/README.md +++ b/packages/babel-plugin-transform-property-literals/README.md @@ -2,52 +2,18 @@ > Ensure that reserved words are quoted in object property keys -## Example +See our website [@babel/plugin-transform-property-literals](https://new.babeljs.io/docs/en/next/babel-plugin-transform-property-literals.html) for more information. -**In** +## Install -```javascript -var foo = { - catch: function () {} -}; -``` - -**Out** - -```javascript -var foo = { - "catch": function () {} -}; -``` - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-transform-property-literals +npm install --save @babel/plugin-transform-property-literals ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-transform-property-literals"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-transform-property-literals script.js -``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-transform-property-literals"] -}); +yarn add --save @babel/plugin-transform-property-literals ``` diff --git a/packages/babel-plugin-transform-property-mutators/README.md b/packages/babel-plugin-transform-property-mutators/README.md index ca5b9cd52e..994a0e8fec 100644 --- a/packages/babel-plugin-transform-property-mutators/README.md +++ b/packages/babel-plugin-transform-property-mutators/README.md @@ -1,67 +1,19 @@ # @babel/plugin-transform-property-mutators -> This plugin allows Babel to transform [object initializer mutators](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Object_initializer#Method_definitions) into `Object.defineProperties`. +> Compile ES5 property mutator shorthand syntax to Object.defineProperty -## Example +See our website [@babel/plugin-transform-property-mutators](https://new.babeljs.io/docs/en/next/babel-plugin-transform-property-mutators.html) for more information. -**In** +## Install -```javascript -var foo = { - get bar() { - return this._bar; - }, - set bar(value) { - this._bar = value; - } -}; -``` - -**Out** - -```javascript -var foo = Object.defineProperties({}, { - bar: { - get: function () { - return this._bar; - }, - set: function (value) { - this._bar = value; - }, - configurable: true, - enumerable: true - } -}); -``` - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-transform-property-mutators +npm install --save @babel/plugin-transform-property-mutators ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-transform-property-mutators"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-transform-property-mutators script.js -``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-transform-property-mutators"] -}); +yarn add --save @babel/plugin-transform-property-mutators ``` diff --git a/packages/babel-plugin-transform-proto-to-assign/README.md b/packages/babel-plugin-transform-proto-to-assign/README.md index ab3f5c1b80..b3dfb37f04 100644 --- a/packages/babel-plugin-transform-proto-to-assign/README.md +++ b/packages/babel-plugin-transform-proto-to-assign/README.md @@ -1,80 +1,19 @@ # @babel/plugin-transform-proto-to-assign -> This plugin allows Babel to transform all `__proto__` assignments to a method that will do a shallow copy of all properties. +> Babel plugin for turning __proto__ into a shallow property clone -## Detail +See our website [@babel/plugin-transform-proto-to-assign](https://new.babeljs.io/docs/en/next/babel-plugin-transform-proto-to-assign.html) for more information. -This means that the following **will** work: +## Install -```javascript -var foo = { a: 1 }; -var bar = { b: 2 }; -bar.__proto__ = foo; -bar.a; // 1 -bar.b; // 2 -``` - -however the following **will not**: - -```javascript -var foo = { a: 1 }; -var bar = { b: 2 }; -bar.__proto__ = foo; -bar.a; // 1 -foo.a = 2; -bar.a; // 1 - should be 2 but remember that nothing is bound and it's a straight copy -``` - -This is a case that you have to be aware of if you intend to use this plugin. - -## Example - -**In** - -```javascript -bar.__proto__ = foo; -``` - -**Out** - -```javascript -function _defaults(obj, defaults) { ... } - -_defaults(bar, foo); -``` - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-transform-proto-to-assign +npm install --save @babel/plugin-transform-proto-to-assign ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-transform-proto-to-assign"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-transform-proto-to-assign script.js +yarn add --save @babel/plugin-transform-proto-to-assign ``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-transform-proto-to-assign"] -}); -``` - -## References - -* [MDN: Object.prototype.\_\_proto\_\_](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/proto) diff --git a/packages/babel-plugin-transform-react-constant-elements/README.md b/packages/babel-plugin-transform-react-constant-elements/README.md index 8bec894bad..106b3b489c 100644 --- a/packages/babel-plugin-transform-react-constant-elements/README.md +++ b/packages/babel-plugin-transform-react-constant-elements/README.md @@ -1,105 +1,19 @@ # @babel/plugin-transform-react-constant-elements -> Treat React JSX elements as value types and hoist them to the highest scope. +> Treat React JSX elements as value types and hoist them to the highest scope -This plugin can speed up reconciliation and reduce garbage collection pressure by hoisting -React elements to the highest possible scope, preventing multiple unnecessary reinstantiations. +See our website [@babel/plugin-transform-react-constant-elements](https://new.babeljs.io/docs/en/next/babel-plugin-transform-react-constant-elements.html) for more information. -## Example +## Install -**In** - -```jsx -const Hr = () => { - return
; -}; -``` - -**Out** - -```jsx -const _ref =
; - -const Hr = () => { - return _ref; -}; -``` - -**Deopts** - -- **Spread Operator** - - ```jsx -
- ``` - -- **Refs** - - ```jsx -
-
this.node = node} /> - ``` - -- **Mutable Properties** - -> See https://github.com/facebook/react/issues/3226 for more on this - - ```js -
- ``` - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-transform-react-constant-elements +npm install --save @babel/plugin-transform-react-constant-elements ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-transform-react-constant-elements"] -} -``` - -## Options - -### `allowMutablePropsOnTags` - -`Array`, defaults to `[]` - -If you are using a particular library (like react-intl) that uses object properties, and you are sure -that the element won't modify its own props, you can whitelist the element so that objects are allowed. - -This will skip the `Mutable Properties` deopt. - -```json -{ - "plugins": [ - ["@babel/plugin-transform-react-constant-elements", {"allowMutablePropsOnTags": ["FormattedMessage"]}], - ] -} - -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-transform-react-constant-elements script.js +yarn add --save @babel/plugin-transform-react-constant-elements ``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-transform-react-constant-elements"] -}); -``` - -## References - -* [[facebook/react#3226] Optimizing Compiler: Reuse Constant Value Types like ReactElement](https://github.com/facebook/react/issues/3226) diff --git a/packages/babel-plugin-transform-react-display-name/README.md b/packages/babel-plugin-transform-react-display-name/README.md index 53e8e4f6ad..34c4c55fe1 100644 --- a/packages/babel-plugin-transform-react-display-name/README.md +++ b/packages/babel-plugin-transform-react-display-name/README.md @@ -1,55 +1,19 @@ # @babel/plugin-transform-react-display-name -> Add displayName to `createReactClass` (and `React.createClass`) calls +> Add displayName to React.createClass calls -## Example +See our website [@babel/plugin-transform-react-display-name](https://new.babeljs.io/docs/en/next/babel-plugin-transform-react-display-name.html) for more information. -**In** +## Install -```js -var foo = React.createClass({}); // React <= 15 -var bar = createReactClass({}); // React 16+ -``` - -**Out** - -```js -var foo = React.createClass({ - displayName: "foo" -}); // React <= 15 -var bar = createReactClass({ - displayName: "bar" -}); // React 16+ -``` - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-transform-react-display-name +npm install --save @babel/plugin-transform-react-display-name ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-transform-react-display-name"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-transform-react-display-name script.js -``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-transform-react-display-name"] -}); +yarn add --save @babel/plugin-transform-react-display-name ``` diff --git a/packages/babel-plugin-transform-react-inline-elements/README.md b/packages/babel-plugin-transform-react-inline-elements/README.md index dc614f25e5..d015d7a344 100644 --- a/packages/babel-plugin-transform-react-inline-elements/README.md +++ b/packages/babel-plugin-transform-react-inline-elements/README.md @@ -1,82 +1,19 @@ # @babel/plugin-transform-react-inline-elements -> Replaces the `React.createElement` function with one that is more optimized for production: `babelHelpers.jsx`. +> Turn JSX elements into exploded React objects -## Note +See our website [@babel/plugin-transform-react-inline-elements](https://new.babeljs.io/docs/en/next/babel-plugin-transform-react-inline-elements.html) for more information. -When used alongside `@babel/plugin-transform-runtime`, polyfills (by default including `Symbol`) are specifically scoped to not pollute the global scope. This breaks usage with React, as it won't have access to that polyfill and will cause your application to fail in legacy browsers. +## Install -Even if `['@babel/plugin-transform-runtime', { helpers: true, polyfill: false }]` is specified, it might still break, since `helpers` come precompiled. - -In this case, we recommend importing/requiring `@babel/polyfill` in the entry point of your application and using `@babel/preset-env` with the `useBuiltIns` option to only include the polyfills your targets need. Alternatively, you can also import/require `core-js/modules/es6.symbol` by itself. - -This transform **should be enabled only in production** (e.g., just before minifying your code) because, although it improves runtime performance, it makes warning messages more cryptic and skips important checks that happen in development mode, including propTypes. - -## Example - -**In** - -```javascript -; -``` - -**Out** - -```javascript -babelHelpers.jsx(Baz, { - foo: "bar" -}, "1"); - -/** - * Instead of - * - * React.createElement(Baz, { - * foo: "bar", - * key: "1", - * }); - */ -``` - -**Deopt** - -```js -// The plugin will still use React.createElement when `ref` or `object rest spread` is used - - -``` - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-transform-react-inline-elements +npm install --save @babel/plugin-transform-react-inline-elements ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-transform-react-inline-elements"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-transform-react-inline-elements script.js +yarn add --save @babel/plugin-transform-react-inline-elements ``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-transform-react-inline-elements"] -}); -``` - -## References - -* [[facebook/react#3228] Optimizing Compiler: Inline React Elements](https://github.com/facebook/react/issues/3228) diff --git a/packages/babel-plugin-transform-react-jsx-compat/README.md b/packages/babel-plugin-transform-react-jsx-compat/README.md index 1c84d9c6a9..e970e4d287 100644 --- a/packages/babel-plugin-transform-react-jsx-compat/README.md +++ b/packages/babel-plugin-transform-react-jsx-compat/README.md @@ -2,54 +2,18 @@ > Turn JSX into React Pre-0.12 function calls -## Example +See our website [@babel/plugin-transform-react-jsx-compat](https://new.babeljs.io/docs/en/next/babel-plugin-transform-react-jsx-compat.html) for more information. -**In** +## Install -```javascript -var profile =
- -

{[user.firstName, user.lastName].join(' ')}

-
; -``` - -**Out** - -```javascript -var profile = React.DOM.div(null, - React.DOM.img({ src: "avatar.png", "class": "profile" }), - React.DOM.h3(null, [user.firstName, user.lastName].join(" ")) -); -``` - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-transform-react-jsx-compat +npm install --save @babel/plugin-transform-react-jsx-compat ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-transform-react-jsx-compat"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-transform-react-jsx-compat script.js -``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-transform-react-jsx-compat"] -}); +yarn add --save @babel/plugin-transform-react-jsx-compat ``` diff --git a/packages/babel-plugin-transform-react-jsx-self/README.md b/packages/babel-plugin-transform-react-jsx-self/README.md index 9b6d78f44b..844bdd835a 100644 --- a/packages/babel-plugin-transform-react-jsx-self/README.md +++ b/packages/babel-plugin-transform-react-jsx-self/README.md @@ -1,49 +1,19 @@ # @babel/plugin-transform-react-jsx-self -> Adds `__self` prop to JSX elements, which React will use to generate some runtime warnings. All React users should enable this transform in dev mode. +> Add a __self prop to all JSX Elements -## Example +See our website [@babel/plugin-transform-react-jsx-self](https://new.babeljs.io/docs/en/next/babel-plugin-transform-react-jsx-self.html) for more information. -**In** +## Install -``` - -``` - -**Out** - -``` - -``` - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-transform-react-jsx-self +npm install --save @babel/plugin-transform-react-jsx-self ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-transform-react-jsx-self"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-transform-react-jsx-self script.js -``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-transform-react-jsx-self"] -}); +yarn add --save @babel/plugin-transform-react-jsx-self ``` diff --git a/packages/babel-plugin-transform-react-jsx-source/README.md b/packages/babel-plugin-transform-react-jsx-source/README.md index 705d8feeca..aa7fda57ca 100644 --- a/packages/babel-plugin-transform-react-jsx-source/README.md +++ b/packages/babel-plugin-transform-react-jsx-source/README.md @@ -1,49 +1,19 @@ # @babel/plugin-transform-react-jsx-source -> Adds source file and line number to JSX elements. +> Add a __source prop to all JSX Elements -## Example +See our website [@babel/plugin-transform-react-jsx-source](https://new.babeljs.io/docs/en/next/babel-plugin-transform-react-jsx-source.html) for more information. -**In** +## Install -``` - -``` - -**Out** - -``` - -``` - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-transform-react-jsx-source +npm install --save @babel/plugin-transform-react-jsx-source ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-transform-react-jsx-source"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-transform-react-jsx-source script.js -``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-transform-react-jsx-source"] -}); +yarn add --save @babel/plugin-transform-react-jsx-source ``` diff --git a/packages/babel-plugin-transform-react-jsx/README.md b/packages/babel-plugin-transform-react-jsx/README.md index b840cdcc46..91f7161f29 100644 --- a/packages/babel-plugin-transform-react-jsx/README.md +++ b/packages/babel-plugin-transform-react-jsx/README.md @@ -2,196 +2,18 @@ > Turn JSX into React function calls -## Example +See our website [@babel/plugin-transform-react-jsx](https://new.babeljs.io/docs/en/next/babel-plugin-transform-react-jsx.html) for more information. -### React +## Install -**In** - -```javascript -var profile =
- -

{[user.firstName, user.lastName].join(' ')}

-
; -``` - -**Out** - -```javascript -var profile = React.createElement("div", null, - React.createElement("img", { src: "avatar.png", className: "profile" }), - React.createElement("h3", null, [user.firstName, user.lastName].join(" ")) -); -``` - -### Custom - -**In** - -```javascript -/** @jsx dom */ - -var { dom } = require("deku"); - -var profile =
- -

{[user.firstName, user.lastName].join(' ')}

-
; -``` - -**Out** - -```javascript -/** @jsx dom */ - -var dom = require("deku").dom; - -var profile = dom("div", null, - dom("img", { src: "avatar.png", className: "profile" }), - dom("h3", null, [user.firstName, user.lastName].join(" ")) -); -``` - -### Fragments - -Fragments are a feature available in React 16.2.0+. - -#### React - -**In** - -```javascript -var descriptions = items.map(item => ( - <> -
{item.name}
-
{item.value}
- -)); -``` - -**Out** - -```javascript -var descriptions = items.map(item => React.createElement( - React.Fragment, - null, - React.createElement("dt", null, item.name), - React.createElement("dd", null, item.value) -)); -``` - -#### Custom - -**In** - -```javascript -/** @jsx dom */ -/** @jsxFrag DomFrag */ - -var { dom, DomFrag } = require("deku"); // DomFrag is fictional! - -var descriptions = items.map(item => ( - <> -
{item.name}
-
{item.value}
- -)); -``` - -**Out** - -```javascript -/** @jsx dom */ -/** @jsxFrag DomFrag */ - -var { dom, DomFrag } = require("deku"); // DomFrag is fictional! - -var descriptions = items.map(item => dom( - DomFrag, - null, - dom("dt", null, item.name), - dom("dd", null, item.value) -)); -``` - -Note that if a custom pragma is specified, then a custom fragment pragma must also be specified if the `<>` is used. Otherwise, an error will be thrown. - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-transform-react-jsx +npm install --save @babel/plugin-transform-react-jsx ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -Without options: - -```json -{ - "plugins": ["@babel/plugin-transform-react-jsx"] -} -``` - -With options: - -```json -{ - "plugins": [ - ["@babel/plugin-transform-react-jsx", { - "pragma": "dom", // default pragma is React.createElement - "pragmaFrag": "DomFrag", // default is React.Fragment - "throwIfNamespace": false // defaults to true - }] - ] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-transform-react-jsx script.js +yarn add --save @babel/plugin-transform-react-jsx ``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-transform-react-jsx"] -}); -``` - -## Options - -### `pragma` - -`string`, defaults to `React.createElement`. - -Replace the function used when compiling JSX expressions. - -Note that the `@jsx React.DOM` pragma has been deprecated as of React v0.12 - -### `pragmaFrag` - -`string`, defaults to `React.Fragment`. - -Replace the component used when compiling JSX fragments. - -### `useBuiltIns` - -`boolean`, defaults to `false`. - -When spreading props, use `Object.assign` directly instead of Babel's extend helper. - -### `throwIfNamespace` - -`boolean`, defaults to `true`. - -Toggles whether or not to throw an error if a XML namespaced tag name is used. For example: - - - -Though the JSX spec allows this, it is disabled by default since React's JSX does not currently have support for it. diff --git a/packages/babel-plugin-transform-regenerator/README.md b/packages/babel-plugin-transform-regenerator/README.md index 47b192a917..415bf53a40 100644 --- a/packages/babel-plugin-transform-regenerator/README.md +++ b/packages/babel-plugin-transform-regenerator/README.md @@ -1,87 +1,19 @@ # @babel/plugin-transform-regenerator -> Transform async/generator functions with [regenerator](https://github.com/facebook/regenerator) +> Explode async and generator functions into a state machine. -## Example +See our website [@babel/plugin-transform-regenerator](https://new.babeljs.io/docs/en/next/babel-plugin-transform-regenerator.html) for more information. -**In** +## Install -```javascript -function* a() { - yield 1; -} -``` - -**Out** - -```javascript -var _marked = [a].map(regeneratorRuntime.mark); - -function a() { - return regeneratorRuntime.wrap(function a$(_context) { - while (1) { - switch (_context.prev = _context.next) { - case 0: - _context.next = 2; - return 1; - - case 2: - case "end": - return _context.stop(); - } - } - }, _marked[0], this); -} -``` - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-transform-regenerator +npm install --save @babel/plugin-transform-regenerator ``` -## Usage - -### Via `.babelrc` (Recommended) - -Without options: - -```json -{ - "plugins": ["@babel/plugin-transform-regenerator"] -} -``` - -With options: - -|name|default value| -|---|---| -|asyncGenerators|true| -|generators|true| -|async|true| - -```json -{ - "plugins": [ - ["@babel/plugin-transform-regenerator", { - "asyncGenerators": false, - "generators": false, - "async": false - }] - ] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-transform-regenerator script.js -``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-transform-regenerator"] -}); +yarn add --save @babel/plugin-transform-regenerator ``` diff --git a/packages/babel-plugin-transform-reserved-words/README.md b/packages/babel-plugin-transform-reserved-words/README.md index 8d8df07531..e42072032b 100644 --- a/packages/babel-plugin-transform-reserved-words/README.md +++ b/packages/babel-plugin-transform-reserved-words/README.md @@ -1,59 +1,19 @@ # @babel/plugin-transform-reserved-words -> Renames variables that are reserved words in ES3 but not ES5+ +> Ensure that no reserved words are used. -Some words were reserved in ES3 as potential future keywords but were not -reserved in ES5 and later. This plugin, to be used when targeting ES3 -environments, renames variables from that set of words. +See our website [@babel/plugin-transform-reserved-words](https://new.babeljs.io/docs/en/next/babel-plugin-transform-reserved-words.html) for more information. -## Example +## Install -**In** - -```javascript -var abstract = 1; -var x = abstract + 1; -``` - -**Out** - -```javascript -var _abstract = 1; -var x = _abstract + 1; -``` - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-transform-reserved-words +npm install --save @babel/plugin-transform-reserved-words ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-transform-reserved-words"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-transform-reserved-words script.js +yarn add --save @babel/plugin-transform-reserved-words ``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-transform-reserved-words"] -}); -``` - -## References - -* [ES3 Spec: Future Reserved Words](http://www.ecma-international.org/publications/files/ECMA-ST-ARCH/ECMA-262,%203rd%20edition,%20December%201999.pdf#page=26) diff --git a/packages/babel-plugin-transform-runtime/README.md b/packages/babel-plugin-transform-runtime/README.md index 7b39101fd7..19538eb9a0 100644 --- a/packages/babel-plugin-transform-runtime/README.md +++ b/packages/babel-plugin-transform-runtime/README.md @@ -1,358 +1,19 @@ # @babel/plugin-transform-runtime -> Externalise references to helpers and built-ins, automatically polyfilling your code without polluting globals. (This plugin is recommended in a library/tool) +> Externalise references to helpers and builtins, automatically polyfilling your code without polluting globals -NOTE: Instance methods such as `"foobar".includes("foo")` will not work since that would require modification of existing built-ins (Use [`@babel/polyfill`](http://babeljs.io/docs/usage/polyfill) for that). +See our website [@babel/plugin-transform-runtime](https://new.babeljs.io/docs/en/next/babel-plugin-transform-runtime.html) for more information. -## Why? +## Install -Babel uses very small helpers for common functions such as `_extend`. By default this will be added to every file that requires it. This duplication is sometimes unnecessary, especially when your application is spread out over multiple files. - -This is where the `@babel/plugin-transform-runtime` plugin comes in: all of the helpers will reference the module `@babel/runtime` to avoid duplication across your compiled output. The runtime will be compiled into your build. - -Another purpose of this transformer is to create a sandboxed environment for your code. If you use [@babel/polyfill](http://babeljs.io/docs/usage/polyfill/) and the built-ins it provides such as `Promise`, `Set` and `Map`, those will pollute the global scope. While this might be ok for an app or a command line tool, it becomes a problem if your code is a library which you intend to publish for others to use or if you can't exactly control the environment in which your code will run. - -The transformer will alias these built-ins to `core-js` so you can use them seamlessly without having to require the polyfill. - -See the [technical details](#technical-details) section for more information on how this works and the types of transformations that occur. - -## Installation - -**NOTE - Production vs. development dependencies** - -In most cases, you should install `@babel/plugin-transform-runtime` as a development dependency (with `--save-dev`). +Using npm: ```sh -npm install --save-dev @babel/plugin-transform-runtime +npm install --save @babel/plugin-transform-runtime ``` -and `@babel/runtime` as a production dependency (with `--save`). +or using yarn: ```sh -npm install --save @babel/runtime -``` - -The transformation plugin is typically used only in development, but the runtime itself will be depended on by your deployed/published code. See the examples below for more details. - -## Usage - -### Via `.babelrc` (Recommended) - -Add the following line to your `.babelrc` file: - -Without options: - -```json -{ - "plugins": ["@babel/plugin-transform-runtime"] -} -``` - -With options: - -```json -{ - "plugins": [ - ["@babel/plugin-transform-runtime", { - "helpers": false, - "polyfill": false, - "regenerator": true, - "moduleName": "@babel/runtime" - }] - ] -} -``` - -### Via CLI - -```sh -babel --plugins @babel/plugin-transform-runtime script.js -``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-transform-runtime"] -}); -``` - -## Options - -### `helpers` - -`boolean`, defaults to `true`. - -Toggles whether or not inlined Babel helpers (`classCallCheck`, `extends`, etc.) are replaced with calls to `moduleName`. - -For more information, see [Helper aliasing](#helper-aliasing). - -### `polyfill` - -`boolean`, defaults to `true`. - -Toggles whether or not new built-ins (`Promise`, `Set`, `Map`, etc.) are transformed to use a non-global polluting polyfill. - -For more information, see [`core-js` aliasing](#core-js-aliasing). - -### `regenerator` - -`boolean`, defaults to `true`. - -Toggles whether or not generator functions are transformed to use a regenerator runtime that does not pollute the global scope. - -For more information, see [Regenerator aliasing](#regenerator-aliasing). - -### `moduleName` - -`string`, defaults to `"@babel/runtime"`. - -Sets the name/path of the module used when importing helpers. - -Example: - -```json -{ - "moduleName": "flavortown/runtime" -} -``` - -```js -import extends from 'flavortown/runtime/helpers/extends'; -``` - -### `useBuiltIns` - -`boolean`, defaults to `false`. - -When enabled, the transform will use helpers that do not use _any_ polyfills -from `core-js`. - -For example, here is the `instance` helper with `useBuiltIns` disabled: - -```js -exports.__esModule = true; - -var _hasInstance = require("../core-js/symbol/has-instance"); - -var _hasInstance2 = _interopRequireDefault(_hasInstance); - -var _symbol = require("../core-js/symbol"); - -var _symbol2 = _interopRequireDefault(_symbol); - -exports.default = function (left, right) { - if (right != null && typeof _symbol2.default !== "undefined" && right[_hasInstance2.default]) { - return right[_hasInstance2.default](left); - } else { - return left instanceof right; - } -}; - -function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; } -``` - -And, with it enabled: - -```js -exports.__esModule = true; - -exports.default = function (left, right) { - if (right != null && typeof Symbol !== "undefined" && right[Symbol.hasInstance]) { - return right[Symbol.hasInstance](left); - } else { - return left instanceof right; - } -}; -``` - -### `useESModules` - -`boolean`, defaults to `false`. - -When enabled, the transform will use helpers that do not get run through -`@babel/plugin-transform-modules-commonjs`. This allows for smaller builds in module -systems like webpack, since it doesn't need to preserve commonjs semantics. - -For example, here is the `classCallCheck` helper with `useESModules` disabled: - -```js -exports.__esModule = true; - -exports.default = function (instance, Constructor) { - if (!(instance instanceof Constructor)) { - throw new TypeError("Cannot call a class as a function"); - } -}; -``` - -And, with it enabled: - -```js -export default function (instance, Constructor) { - if (!(instance instanceof Constructor)) { - throw new TypeError("Cannot call a class as a function"); - } -} -``` - -## Technical details - -The `runtime` transformer plugin does three things: - -* Automatically requires `@babel/runtime/regenerator` when you use generators/async functions. -* Automatically requires `@babel/runtime/core-js` and maps ES6 static methods and built-ins. -* Removes the inline Babel helpers and uses the module `@babel/runtime/helpers` instead. - -What does this actually mean though? Basically, you can use built-ins such as `Promise`, `Set`, `Symbol`, etc., as well use all the Babel features that require a polyfill seamlessly, without global pollution, making it extremely suitable for libraries. - -Make sure you include `@babel/runtime` as a dependency. - -### Regenerator aliasing - -Whenever you use a generator function or async function: - -```javascript -function* foo() { - -} -``` - -the following is generated: - -```javascript -"use strict"; - -var _marked = [foo].map(regeneratorRuntime.mark); - -function foo() { - return regeneratorRuntime.wrap(function foo$(_context) { - while (1) { - switch (_context.prev = _context.next) { - case 0: - case "end": - return _context.stop(); - } - } - }, _marked[0], this); -} -``` - -This isn't ideal since it relies on the regenerator runtime being included, which -pollutes the global scope. - -With the `runtime` transformer, however, it is compiled to: - -```javascript -"use strict"; - -var _regenerator = require("@babel/runtime/regenerator"); - -var _regenerator2 = _interopRequireDefault(_regenerator); - -function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; } - -var _marked = [foo].map(_regenerator2.default.mark); - -function foo() { - return _regenerator2.default.wrap(function foo$(_context) { - while (1) { - switch (_context.prev = _context.next) { - case 0: - case "end": - return _context.stop(); - } - } - }, _marked[0], this); -} -``` - -This means that you can use the regenerator runtime without polluting your current environment. - -### `core-js` aliasing - -Sometimes you may want to use new built-ins such as `Map`, `Set`, `Promise` etc. Your only way -to use these is usually to include a globally polluting polyfill. - -What the `runtime` transformer does is transform the following: - -```javascript -var sym = Symbol(); - -var promise = new Promise; - -console.log(arr[Symbol.iterator]()); -``` - -into the following: - -```javascript -"use strict"; - -var _getIterator2 = require("@babel/runtime/core-js/get-iterator"); - -var _getIterator3 = _interopRequireDefault(_getIterator2); - -var _promise = require("@babel/runtime/core-js/promise"); - -var _promise2 = _interopRequireDefault(_promise); - -var _symbol = require("@babel/runtime/core-js/symbol"); - -var _symbol2 = _interopRequireDefault(_symbol); - -function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; } - -var sym = (0, _symbol2.default)(); - -var promise = new _promise2.default(); - -console.log((0, _getIterator3.default)(arr)); -``` - -This means is that you can seamlessly use these native built-ins and static methods -without worrying about where they come from. - -**NOTE:** Instance methods such as `"foobar".includes("foo")` will **not** work. - -### Helper aliasing - -Usually Babel will place helpers at the top of your file to do common tasks to avoid -duplicating the code around in the current file. Sometimes these helpers can get a -little bulky and add unnecessary duplication across files. The `runtime` -transformer replaces all the helper calls to a module. - -That means that the following code: - -```javascript -class Person { -} -``` - -usually turns into: - -```javascript -"use strict"; - -function _classCallCheck(instance, Constructor) { if (!(instance instanceof Constructor)) { throw new TypeError("Cannot call a class as a function"); } } - -var Person = function Person() { - _classCallCheck(this, Person); -}; -``` - -the `runtime` transformer however turns this into: - -```javascript -"use strict"; - -var _classCallCheck2 = require("@babel/runtime/helpers/classCallCheck"); - -var _classCallCheck3 = _interopRequireDefault(_classCallCheck2); - -function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; } - -var Person = function Person() { - (0, _classCallCheck3.default)(this, Person); -}; +yarn add --save @babel/plugin-transform-runtime ``` diff --git a/packages/babel-plugin-transform-shorthand-properties/README.md b/packages/babel-plugin-transform-shorthand-properties/README.md index 917c783fd0..c625e6fd26 100644 --- a/packages/babel-plugin-transform-shorthand-properties/README.md +++ b/packages/babel-plugin-transform-shorthand-properties/README.md @@ -2,68 +2,18 @@ > Compile ES2015 shorthand properties to ES5 -## Example +See our website [@babel/plugin-transform-shorthand-properties](https://new.babeljs.io/docs/en/next/babel-plugin-transform-shorthand-properties.html) for more information. -**In** +## Install -```js -var o = { a, b, c }; -``` - -**Out** - -```js -var o = { a: a, b: b, c: c }; -``` - -**In** - -```js -var cat = { - getName() { - return name; - } -}; -``` - -**Out** - -```js -var cat = { - getName: function () { - return name; - } -}; -``` - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-transform-shorthand-properties +npm install --save @babel/plugin-transform-shorthand-properties ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-transform-shorthand-properties"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-transform-shorthand-properties script.js -``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-transform-shorthand-properties"] -}); +yarn add --save @babel/plugin-transform-shorthand-properties ``` diff --git a/packages/babel-plugin-transform-spread/README.md b/packages/babel-plugin-transform-spread/README.md index 75f2fcc170..79661a9b41 100644 --- a/packages/babel-plugin-transform-spread/README.md +++ b/packages/babel-plugin-transform-spread/README.md @@ -2,82 +2,18 @@ > Compile ES2015 spread to ES5 -## Example +See our website [@babel/plugin-transform-spread](https://new.babeljs.io/docs/en/next/babel-plugin-transform-spread.html) for more information. -**In** +## Install -```js -var a = ['a', 'b', 'c']; - -var b = [...a, 'foo']; - -var c = foo(...a); -``` - -**Out** - -```js -var a = ['a', 'b', 'c']; - -var b = a.concat(['foo']); - -var c = foo.apply(void 0, a); -``` - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-transform-spread +npm install --save @babel/plugin-transform-spread ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -Without options: - -```json -{ - "plugins": ["@babel/plugin-transform-spread"] -} -``` - -With options: - -```json -{ - "plugins": [ - ["@babel/plugin-transform-spread", { - "loose": true - }] - ] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-transform-spread script.js +yarn add --save @babel/plugin-transform-spread ``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-transform-spread"] -}); -``` - -## Options - -### `loose` - -`boolean`, defaults to `false`. - -In loose mode, **all** iterables are assumed to be arrays. - -## References - -* [MDN: Spread syntax](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax) diff --git a/packages/babel-plugin-transform-sticky-regex/README.md b/packages/babel-plugin-transform-sticky-regex/README.md index 8c1bb2f82d..ee3557dfe6 100644 --- a/packages/babel-plugin-transform-sticky-regex/README.md +++ b/packages/babel-plugin-transform-sticky-regex/README.md @@ -2,48 +2,18 @@ > Compile ES2015 sticky regex to an ES5 RegExp constructor -## Examples +See our website [@babel/plugin-transform-sticky-regex](https://new.babeljs.io/docs/en/next/babel-plugin-transform-sticky-regex.html) for more information. -**In** +## Install -```javascript -const a = /o+/y; -``` - -**Out** - -```javascript -var a = new RegExp("o+", "y"); -``` - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-transform-sticky-regex +npm install --save @babel/plugin-transform-sticky-regex ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-transform-sticky-regex"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-transform-sticky-regex script.js -``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-transform-sticky-regex"] -}); +yarn add --save @babel/plugin-transform-sticky-regex ``` diff --git a/packages/babel-plugin-transform-strict-mode/README.md b/packages/babel-plugin-transform-strict-mode/README.md index 483143958b..14d9a29347 100644 --- a/packages/babel-plugin-transform-strict-mode/README.md +++ b/packages/babel-plugin-transform-strict-mode/README.md @@ -1,57 +1,19 @@ # @babel/plugin-transform-strict-mode -> This plugin places a `"use strict";` directive at the top of all files to enable [strict mode](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Strict_mode). +> This plugin places a 'use strict'; directive at the top of all files to enable strict mode -This plugin may be enabled via `@babel/plugin-transform-modules-commonjs`. -If you wish to disable it you can either turn `strict` off or pass -`strictMode: false` as an option to the commonjs transform. +See our website [@babel/plugin-transform-strict-mode](https://new.babeljs.io/docs/en/next/babel-plugin-transform-strict-mode.html) for more information. -## Example +## Install -**In** - -```javascript -foo(); -``` - -**Out** - -```javascript -"use strict"; - -foo(); -``` - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-transform-strict-mode +npm install --save @babel/plugin-transform-strict-mode ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - - -```json -{ - "plugins": ["@babel/plugin-transform-strict-mode"] -} -``` - - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-transform-strict-mode script.js -``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-transform-strict-mode"] -}); +yarn add --save @babel/plugin-transform-strict-mode ``` diff --git a/packages/babel-plugin-transform-template-literals/README.md b/packages/babel-plugin-transform-template-literals/README.md index d22f3b9209..5b2f9b8467 100644 --- a/packages/babel-plugin-transform-template-literals/README.md +++ b/packages/babel-plugin-transform-template-literals/README.md @@ -2,84 +2,18 @@ > Compile ES2015 template literals to ES5 -## Example +See our website [@babel/plugin-transform-template-literals](https://new.babeljs.io/docs/en/next/babel-plugin-transform-template-literals.html) for more information. -**In** +## Install -```javascript -`foo${bar}`; -``` - -**Out** - -```javascript -"foo".concat(bar); -``` - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-transform-template-literals +npm install --save @babel/plugin-transform-template-literals ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -Without options: - -```json -{ - "plugins": ["@babel/plugin-transform-template-literals"] -} -``` - -With options: - -```json -{ - "plugins": [ - ["@babel/plugin-transform-template-literals", { - "loose": true - }] - ] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-transform-template-literals script.js -``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-transform-template-literals"] -}); -``` - -## Options - -### `loose` - -`boolean`, defaults to `false`. - -When `true`, tagged template literal objects aren't frozen. All template literal expressions and quasis are combined with the `+` operator instead of with `String.prototype.concat`. - -When `false` or not set, all template literal expressions and quasis are combined with `String.prototype.concat`. It will handle cases with `Symbol.toPrimitive` correctly and throw correctly if template literal expression is a `Symbol()`. See [babel/babel#5791](https://github.com/babel/babel/pull/5791). - -**In** - -```javascript -`foo${bar}`; -``` - -**Out** - -```javascript -"foo" + bar; +yarn add --save @babel/plugin-transform-template-literals ``` diff --git a/packages/babel-plugin-transform-typeof-symbol/README.md b/packages/babel-plugin-transform-typeof-symbol/README.md index 03aa17040b..57ba11b67b 100644 --- a/packages/babel-plugin-transform-typeof-symbol/README.md +++ b/packages/babel-plugin-transform-typeof-symbol/README.md @@ -1,53 +1,19 @@ # @babel/plugin-transform-typeof-symbol -> ES6 introduces a new native type called [symbols](https://babeljs.io/learn-es2015/#ecmascript-2015-features-symbols). This transformer wraps all `typeof` expressions with a method that replicates native behaviour. (ie. returning "symbol" for symbols) +> This transformer wraps all typeof expressions with a method that replicates native behaviour. (ie. returning “symbol” for symbols) -## Example +See our website [@babel/plugin-transform-typeof-symbol](https://new.babeljs.io/docs/en/next/babel-plugin-transform-typeof-symbol.html) for more information. -**In** +## Install -```javascript -typeof Symbol() === "symbol"; -``` - -**Out** - -```javascript -var _typeof = function (obj) { - return obj && obj.constructor === Symbol ? "symbol" : typeof obj; -}; - -_typeof(Symbol()) === "symbol"; -``` - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-transform-typeof-symbol +npm install --save @babel/plugin-transform-typeof-symbol ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-transform-typeof-symbol"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-transform-typeof-symbol script.js -``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-transform-typeof-symbol"] -}); +yarn add --save @babel/plugin-transform-typeof-symbol ``` diff --git a/packages/babel-plugin-transform-typescript/README.md b/packages/babel-plugin-transform-typescript/README.md index 6cc77d1e22..a005cd4b8c 100644 --- a/packages/babel-plugin-transform-typescript/README.md +++ b/packages/babel-plugin-transform-typescript/README.md @@ -1,72 +1,19 @@ # @babel/plugin-transform-typescript -> Transform [TypeScript](https://github.com/Microsoft/TypeScript) into ES.next. +> Transform TypeScript into ES.next -Does not type-check its input. For that, you will need to install and set up TypeScript. +See our website [@babel/plugin-transform-typescript](https://new.babeljs.io/docs/en/next/babel-plugin-transform-typescript.html) for more information. -## Caveats +## Install -* Does not support [`namespace`][namespace]s. **Workaround**: Move to using [file exports][fm], or migrate to using the `module { }` syntax instead. -* Does not support [`const enum`][const_enum]s because those require type information to compile. -**Workaround**: Remove the `const`, which makes it available at runtime. -* Does not support [`export =`][exin] and [`import =`][exin], because those cannot be compile to ES.next. **Workaround**: Convert to using `export default` and `export const`, and `import x, {y} from "z"`. - -## Example - -**In** - -```javascript -const x: number = 0; -``` - -**Out** - -```javascript -const x = 0; -``` - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-transform-typescript +npm install --save @babel/plugin-transform-typescript ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-transform-typescript"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-transform-typescript script.js +yarn add --save @babel/plugin-transform-typescript ``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-transform-typescript"] -}); -``` -## Options - -### `jsxPragma` - -`string` - -Replace the function used when compiling JSX expressions. - -This is so that we know that the import is not a type import, and should not be removed - -[const_enum]: https://www.typescriptlang.org/docs/handbook/enums.html#const-enums -[namespace]: https://www.typescriptlang.org/docs/handbook/namespaces.html -[exin]: https://www.typescriptlang.org/docs/handbook/modules.html#export--and-import--require -[fm]: https://github.com/Microsoft/dtslint/blob/master/docs/no-single-declare-module.md diff --git a/packages/babel-plugin-transform-unicode-regex/README.md b/packages/babel-plugin-transform-unicode-regex/README.md index a6d79cf77b..22b583099c 100644 --- a/packages/babel-plugin-transform-unicode-regex/README.md +++ b/packages/babel-plugin-transform-unicode-regex/README.md @@ -1,51 +1,19 @@ # @babel/plugin-transform-unicode-regex -> Compile ES2015 unicode regex to ES5 +> Compile ES2015 Unicode regex to ES5 -## Example +See our website [@babel/plugin-transform-unicode-regex](https://new.babeljs.io/docs/en/next/babel-plugin-transform-unicode-regex.html) for more information. -**In** +## Install -```js -var string = "foo💩bar"; -var match = string.match(/foo(.)bar/u); -``` - -**Out** - -```js -var string = "foo💩bar"; -var match = string.match(/foo((?:[\0-\t\x0B\f\x0E-\u2027\u202A-\uD7FF\uE000-\uFFFF]|[\uD800-\uDBFF][\uDC00-\uDFFF]|[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?:[^\uD800-\uDBFF]|^)[\uDC00-\uDFFF]))bar/); -``` - -## Installation +Using npm: ```sh -npm install --save-dev @babel/plugin-transform-unicode-regex +npm install --save @babel/plugin-transform-unicode-regex ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "plugins": ["@babel/plugin-transform-unicode-regex"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --plugins @babel/plugin-transform-unicode-regex script.js -``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - plugins: ["@babel/plugin-transform-unicode-regex"] -}); +yarn add --save @babel/plugin-transform-unicode-regex ``` diff --git a/packages/babel-polyfill/README.md b/packages/babel-polyfill/README.md index d0d0983f17..eeb9c8c418 100644 --- a/packages/babel-polyfill/README.md +++ b/packages/babel-polyfill/README.md @@ -1,5 +1,19 @@ # @babel/polyfill -## Usage +> Provides polyfills necessary for a full ES2015+ environment -TODO +See our website [@babel/polyfill](https://new.babeljs.io/docs/en/next/babel-polyfill.html) for more information. + +## Install + +Using npm: + +```sh +npm install --save @babel/polyfill +``` + +or using yarn: + +```sh +yarn add --save @babel/polyfill +``` diff --git a/packages/babel-preset-env-standalone/README.md b/packages/babel-preset-env-standalone/README.md index 9bbad9b076..4da61246aa 100644 --- a/packages/babel-preset-env-standalone/README.md +++ b/packages/babel-preset-env-standalone/README.md @@ -1,36 +1,19 @@ -@babel/preset-env-standalone -================= +# @babel/preset-env-standalone -@babel/preset-env-standalone is a standalone build of [@babel/preset-env](https://babeljs.io/docs/plugins/preset-env) for use in non-Node.js environments, including browsers. +> Standalone build of babel-prest-env for use in non-Node.js environments. -Installation -============ +See our website [@babel/preset-env-standalone](https://new.babeljs.io/docs/en/next/babel-preset-env-standalone.html) for more information. -There are several ways to use @babel/preset-env-standalone. Pick whichever one you like: +## Install -- Use it via UNPKG: https://unpkg.com/@babel/preset-env-standalone@7/babel-preset-env.min.js. This is a simple way to embed it on a webpage without having to do any other setup. -- Install via NPM: `npm install --save @babel/preset-env-standalone` -- Manually grab `babel-preset-env.js` and/or `babel-preset-env.min.js`: - * Download archived source code from the [GitHub releases page](https://github.com/babel/babel/releases). - * Unpack it. - * Grab `babel-preset-env.js` and/or `babel-preset-env.min.js` from `packages/babel-preset-env-standalone`. +Using npm: -Usage -===== - -Load `babel-preset-env.js` or `babel-preset-env.min.js` in your environment, **along with babel-standalone**. This is important: You need to load Babel too! It will be registered as an available preset of the @babel/standalone. - -Then, just use it like any other preset: - -```js -Babel.transform(code, { - presets: [ - ["@babel/preset-env", { - "targets": { - "browsers": "last 1 safari version" - }, - useBuiltIns: "usage" - }] - ] -}); +```sh +npm install --save @babel/preset-env-standalone +``` + +or using yarn: + +```sh +yarn add --save @babel/preset-env-standalone ``` diff --git a/packages/babel-preset-env/README.md b/packages/babel-preset-env/README.md index 5d21a5e7d9..df551e33a2 100644 --- a/packages/babel-preset-env/README.md +++ b/packages/babel-preset-env/README.md @@ -1,598 +1,19 @@ -# @babel/preset-env [![npm](https://img.shields.io/npm/v/babel-preset-env.svg)](https://www.npmjs.com/package/babel-preset-env) [![travis](https://img.shields.io/travis/babel/babel-preset-env/master.svg)](https://travis-ci.org/babel/babel-preset-env) [![npm-downloads](https://img.shields.io/npm/dm/babel-preset-env.svg)](https://www.npmjs.com/package/babel-preset-env) [![codecov](https://img.shields.io/codecov/c/github/babel/babel-preset-env/master.svg?maxAge=43200)](https://codecov.io/github/babel/babel-preset-env) +# @babel/preset-env -> A Babel preset that compiles [ES2015+](https://github.com/tc39/proposals/blob/master/finished-proposals.md) down to ES5 by automatically determining the Babel plugins and polyfills you need based on your targeted browser or runtime environments. +> A Babel preset for each environment. -```sh -npm install @babel/preset-env --save-dev -``` - -Without any configuration options, `@babel/preset-env` behaves exactly the same as [`@babel/preset-es2015`](https://github.com/babel/babel/tree/master/packages/babel-preset-es2015), [`@babel/preset-es2016`](https://github.com/babel/babel/tree/master/packages/babel-preset-es2016) and [`@babel/preset-es2017`](https://github.com/babel/babel/tree/master/packages/babel-preset-es2017) together (or the deprecated `babel-preset-latest`). - -> We don't recommend using `preset-env` this way because it doesn't take advantage of its ability to target specific browsers. - -```json -{ - "presets": ["@babel/preset-env"] -} -``` - -You can also configure it to only include the polyfills and transforms needed for the browsers you support. Compiling only what's needed can make your bundles smaller and your life easier. - -If you want to specify target browsers, we recommend using a [`.browserslistrc`](https://github.com/browserslist/browserslist) config, which is also used by many tools including Autoprefixer. - -For example, to only include polyfills and code transforms needed for users whose browsers have >0.25% market share (ignoring browsers without security updates like IE 10 and BlackBerry): - -``` -> 0.25% -not dead -``` - -The full list of queries could be found in [Browserslist docs](https://github.com/browserslist/browserslist#queries). - -If you need to use different browsers for Babel, you can also specify Browserslist queries in the [targets.browsers option](https://github.com/babel/babel/tree/master/packages/babel-preset-env#targetsbrowsers) in your Babel config. - -You may also target browsers supporting ES Modules (https://www.ecma-international.org/ecma-262/6.0/#sec-modules). When specifying this option, the browsers field will be ignored. You can use this approach in combination with `` to conditionally serve smaller scripts to users (https://jakearchibald.com/2017/es-modules-in-browsers/#nomodule-for-backwards-compatibility). - -*Please note*: when specifying the esmodules target, browsers targets will be ignored. - -```json -{ - "presets": [ - ["@babel/preset-env", { - "targets": { - "esmodules": true - } - }] - ] -} -``` - -Similarly, if you're targeting Node.js instead of the browser, you can configure `@babel/preset-env` to only include the polyfills and transforms necessary for a particular version: - -```json -{ - "presets": [ - ["@babel/preset-env", { - "targets": { - "node": "6.10" - } - }] - ] -} -``` - -For convenience, you can use `"node": "current"` to only include the necessary polyfills and transforms for the Node.js version that you use to run Babel: - -```json -{ - "presets": [ - ["@babel/preset-env", { - "targets": { - "node": "current" - } - }] - ] -} -``` - -- [How it Works](#how-it-works) -- [Install](#install) -- [Usage](#usage) -- [Options](#options) -- [Examples](#examples) -- [Issues](#issues) - -## How it Works - -### Determine environment support for ECMAScript features - -Use external data such as [`compat-table`](https://github.com/kangax/compat-table) to determine browser support. (We should create PRs there when necessary) - -![](https://cloud.githubusercontent.com/assets/588473/19214029/58deebce-8d48-11e6-9004-ee3fbcb75d8b.png) - -We can periodically run [build-data.js](https://github.com/babel/babel/blob/master/packages/babel-preset-env/scripts/build-data.js) which generates [plugins.json](https://github.com/babel/babel/blob/master/packages/babel-preset-env/data/plugins.json). - -Ref: [#7](https://github.com/babel/babel-preset-env/issues/7) - -### Maintain a mapping between JavaScript features and Babel plugins - -> Currently located at [plugin-features.js](https://github.com/babel/babel/blob/master/packages/babel-preset-env/data/plugin-features.js). - -This should be straightforward to do in most cases. There might be cases where plugins should be split up more or certain plugins aren't standalone enough (or impossible to do). - -### Support all plugins in Babel that are considered `latest` - -> Default behavior without options is the same as `@babel/preset-latest`. - -It won't include `stage-x` plugins. env will support all plugins in what we consider the latest version of JavaScript (by matching what we do in [`@babel/preset-latest`](http://babeljs.io/docs/plugins/preset-latest/)). - -Ref: [#14](https://github.com/babel/babel-preset-env/issues/14) - -### Determine the lowest common denominator of plugins to be included in the preset - -If you are targeting IE 8 and Chrome 55 it will include all plugins required by IE 8 since you would need to support both still. - -### Support a target option `"node": "current"` to compile for the currently running node version. - -For example, if you are building on Node 6, arrow functions won't be converted, but they will if you build on Node 0.12. - -### Support a `browsers` option like autoprefixer. - -Use [browserslist](https://github.com/ai/browserslist) to declare supported environments by performing queries like `> 1%, last 2 versions`. - -Ref: [#19](https://github.com/babel/babel-preset-env/pull/19) - -### Browserslist support. - -[Browserslist](https://github.com/ai/browserslist) is a library used to share a supported list of browsers between different front-end tools like [autoprefixer](https://github.com/postcss/autoprefixer), [stylelint](https://stylelint.io/), [eslint-plugin-compat](https://github.com/amilajack/eslint-plugin-compat) and many others. - -By default, @babel/preset-env will use [browserslist config sources](https://github.com/ai/browserslist#queries). - -For example, to enable only the polyfills and plugins needed for a project targeting *last 2 versions* and *IE10*: - -**.babelrc** -```json -{ - "presets": [ - ["@babel/preset-env", { - "useBuiltIns": "entry" - }] - ] -} -``` - -**browserslist** -``` -Last 2 versions -IE 10 -``` - -or - -**package.json** -``` -"browserslist": "last 2 versions, ie 10" -``` - -Browserslist config will be ignored if: 1) `targets.browsers` was specified 2) or with `ignoreBrowserslistConfig: true` option ([see more](#ignoreBrowserslistConfig)): - -#### Targets merging. - -1. If [targets.browsers](#targetsbrowsers) is defined - the browserslist config will be ignored. The browsers specified in `targets` will be merged with [any other explicitly defined targets](#targets). If merged, targets defined explicitly will override the same targets received from `targets.browsers`. - -2. If [targets.browsers](#targetsbrowsers) is _not_ defined - the program will search browserslist file or `package.json` with `browserslist` field. The search will start from the working directory of the process or from the path specified by the `configPath` option, and go up to the system root. If both a browserslist file and configuration inside a `package.json` are found, an exception will be thrown. - -3. If a browserslist config was found and other targets are defined (but not [targets.browsers](#targetsbrowsers)), the targets will be merged in the same way as `targets` defined explicitly with `targets.browsers`. +See our website [@babel/preset-env](https://new.babeljs.io/docs/en/next/babel-preset-env.html) for more information. ## Install -With [npm](https://www.npmjs.com): +Using npm: ```sh -npm install --save-dev @babel/preset-env +npm install --save @babel/preset-env ``` -Or [yarn](https://yarnpkg.com): +or using yarn: ```sh -yarn add @babel/preset-env --dev +yarn add --save @babel/preset-env ``` - -## Usage - -The default behavior without options runs all transforms (behaves the same as [@babel/preset-latest](https://babeljs.io/docs/plugins/preset-latest/)). - -```json -{ - "presets": ["@babel/preset-env"] -} -``` - -## Options - -For more information on setting options for a preset, refer to the [plugin/preset options](http://babeljs.io/docs/plugins/#plugin-preset-options) documentation. - -### `targets` - -`{ [string]: number | string }`, defaults to `{}`. - -Takes an object of environment versions to support. - -Each target environment takes a number or a string (we recommend using a string when specifying minor versions like `node: "6.10"`). You can also specify `tp` (technology preview) version for Safari. - -Example environments: `chrome`, `opera`, `edge`, `firefox`, `safari`, `ie`, `ios`, `android`, `node`, `electron`. - -The [data](https://github.com/babel/babel/blob/master/packages/babel-preset-env/data/plugins.json) for this is generated by running the [build-data script](https://github.com/babel/babel/blob/master/packages/babel-preset-env/scripts/build-data.js) which pulls in data from [compat-table](https://kangax.github.io/compat-table). - -### `targets.node` - -`number | string | "current" | true` - -If you want to compile against the current node version, you can specify `"node": true` or `"node": "current"`, which would be the same as `"node": process.versions.node`. - -### `targets.browsers` - -`Array | string` - -A query to select browsers (ex: last 2 versions, > 5%, safari tp) using [browserslist](https://github.com/ai/browserslist). - -Note, browsers' results are overridden by explicit items from `targets`. - -### `spec` - -`boolean`, defaults to `false`. - -Enable more spec compliant, but potentially slower, transformations for any plugins in this preset that support them. - -### `loose` - -`boolean`, defaults to `false`. - -Enable ["loose" transformations](http://2ality.com/2015/12/babel6-loose-mode.html) for any plugins in this preset that allow them. - -### `modules` - -`"amd" | "umd" | "systemjs" | "commonjs" | "cjs" | false`, defaults to `"commonjs"`. - -Enable transformation of ES6 module syntax to another module type. - -Setting this to `false` will not transform modules. - -### `debug` - -`boolean`, defaults to `false`. - -Outputs the targets/plugins used and the version specified in [plugin data version](https://github.com/babel/babel/blob/master/packages/babel-preset-env/data/plugins.json) to `console.log`. - -### `include` - -`Array`, defaults to `[]`. - -An array of plugins to always include. - -Valid options include any: - -- [Babel plugins](https://github.com/babel/babel/blob/master/packages/babel-preset-env/data/plugin-features.js) - both with (`@babel/plugin-transform-spread`) and without prefix (`plugin-transform-spread`) are supported. - -- [Built-ins](https://github.com/babel/babel/blob/master/packages/babel-preset-env/data/built-in-features.js), such as `es6.map`, `es6.set`, or `es6.object.assign`. - -Plugin names can be fully or partially specified (or using `RegExp`). - -Acceptable inputs: - -- Full name (`string`): `"es6.math.sign"` -- Partial name (`string`): `"es6.math.*"` (resolves to all plugins with `es6.math` prefix) -- `RegExp` Object: `/^transform-.*$/` or `new RegExp("^transform-modules-.*")` - -Note that the above `.` is the `RegExp` equivalent to match any character, and not the actual `'.'` character. Also note that to match any character `.*` is used in `RegExp` as opposed to `*` in `glob` format. - -This option is useful if there is a bug in a native implementation, or a combination of a non-supported feature + a supported one doesn't work. - -For example, Node 4 supports native classes but not spread. If `super` is used with a spread argument, then the `@babel/plugin-transform-classes` transform needs to be `include`d, as it is not possible to transpile a spread with `super` otherwise. - -> NOTE: The `include` and `exclude` options _only_ work with the [plugins included with this preset](https://github.com/babel/babel/blob/master/packages/babel-preset-env/data/plugin-features.js); so, for example, including `@babel/plugin-proposal-do-expressions` or excluding `@babel/plugin-proposal-function-bind` will throw errors. To use a plugin _not_ included with this preset, add them to your [config](https://babeljs.io/docs/usage/babelrc/) directly. - -### `exclude` - -`Array`, defaults to `[]`. - -An array of plugins to always exclude/remove. - -The possible options are the same as the `include` option. - -This option is useful for "blacklisting" a transform like `@babel/plugin-transform-regenerator` if you don't use generators and don't want to include `regeneratorRuntime` (when using `useBuiltIns`) or for using another plugin like [fast-async](https://github.com/MatAtBread/fast-async) instead of [Babel's async-to-gen](http://babeljs.io/docs/plugins/proposal-async-generator-functions/). - -### `useBuiltIns` - -`"usage"` | `"entry"` | `false`, defaults to `false`. - -A way to apply `@babel/preset-env` for polyfills (via `@babel/polyfill`). - -```sh -npm install @babel/polyfill --save -``` - -#### `useBuiltIns: 'usage'` - -Adds specific imports for polyfills when they are used in each file. We take advantage of the fact that a bundler will load the same polyfill only once. - -**In** - -a.js - -```js -var a = new Promise(); -``` - -b.js - -```js -var b = new Map(); -``` - -**Out (if environment doesn't support it)** - -```js -import "core-js/modules/es6.promise"; -var a = new Promise(); -``` - -```js -import "core-js/modules/es6.map"; -var b = new Map(); -``` - -**Out (if environment supports it)** - -```js -var a = new Promise(); -``` - -```js -var b = new Map(); -``` - -#### `useBuiltIns: 'entry'` - -> NOTE: Only use `require("@babel/polyfill");` once in your whole app. -> Multiple imports or requires of `@babel/polyfill` will throw an error since it can cause global collisions and other issues that are hard to trace. -> We recommend creating a single entry file that only contains the `require` statement. - -This option enables a new plugin that replaces the statement `import "@babel/polyfill"` or `require("@babel/polyfill")` with individual requires for `@babel/polyfill` based on environment. - -**In** - -```js -import "@babel/polyfill"; -``` - -**Out (different based on environment)** - -```js -import "core-js/modules/es7.string.pad-start"; -import "core-js/modules/es7.string.pad-end"; -``` - -This will also work for `core-js` directly (`import "core-js";` or `require('core-js');`) - -#### `useBuiltIns: false` - -Don't add polyfills automatically per file, or transform `import "@babel/polyfill"` to individual polyfills. - -### `forceAllTransforms` - -`boolean`, defaults to `false`. - -

- Example - - With Babel 7's .babelrc.js support, you can force all transforms to be run if env is set to `production`. - - ```js - module.exports = { - presets: [ - ["@babel/preset-env", { - targets: { - chrome: 59, - edge: 13, - firefox: 50, - }, - // for uglifyjs... - forceAllTransforms: process.env === "production" - }], - ], - }; - ``` -

- - -> NOTE: `targets.uglify` is deprecated and will be removed in the next major in -favor of this. - -By default, this preset will run all the transforms needed for the targeted -environment(s). Enable this option if you want to force running _all_ -transforms, which is useful if the output will be run through UglifyJS or an -environment that only supports ES5. - -> NOTE: Uglify has a work-in-progress "Harmony" branch to address the lack of -ES6 support, but it is not yet stable. You can follow its progress in -[UglifyJS2 issue #448](https://github.com/mishoo/UglifyJS2/issues/448). If you -require an alternative minifier which _does_ support ES6 syntax, we recommend -using [babel-minify](https://github.com/babel/minify). - -### `configPath` - -`string`, defaults to `process.cwd()` - -The starting point where the config search for browserslist will start, and ascend to the system root until found. - -### `ignoreBrowserslistConfig` - -`boolean`, defaults to `false` - -Toggles whether or not [browserslist config sources](https://github.com/ai/browserslist#queries) are used, which includes searching for any browserslist files or referencing the browserslist key inside package.json. This is useful for projects that use a browserslist config for files that won't be compiled with Babel. - -### `shippedProposals` - -`boolean`, defaults to `false` - -Toggles enabling support for builtin/feature proposals that have shipped in browsers. If your target environments have native support for a feature proposal, its matching parser syntax plugin is enabled instead of performing any transform. Note that this _does not_ enable the same transformations as [`@babel/preset-stage-3`](https://babeljs.io/docs/plugins/preset-stage-3/), since proposals can continue to change before landing in browsers. - -The following are currently supported: - -**Builtins** - -- None - -**Features** - -- [Optional catch binding](https://github.com/tc39/proposal-optional-catch-binding) - ---- - -## Examples - -### Export with various targets - -```js -export class A {} -``` - -#### Target only Chrome 52 - -**.babelrc** - -```json -{ - "presets": [ - ["@babel/preset-env", { - "targets": { - "chrome": 52 - } - }] - ] -} -``` - -**Out** - -```js -class A {} -exports.A = A; -``` - -#### Target Chrome 52 with webpack 2/rollup and loose mode - -**.babelrc** - -```json -{ - "presets": [ - ["@babel/preset-env", { - "targets": { - "chrome": 52 - }, - "modules": false, - "loose": true - }] - ] -} -``` - -**Out** - -```js -export class A {} -``` - -#### Target specific browsers via browserslist - -**.babelrc** - -```json -{ - "presets": [ - ["@babel/preset-env", { - "targets": { - "chrome": 52, - "browsers": ["last 2 versions", "safari 7"] - } - }] - ] -} -``` - -**Out** - -```js -export var A = function A() { - _classCallCheck(this, A); -}; -``` - -#### Target latest node via `node: true` or `node: "current"` - -**.babelrc** - -```json -{ - "presets": [ - ["@babel/preset-env", { - "targets": { - "node": "current" - } - }] - ] -} -``` - -**Out** - -```js -class A {} -exports.A = A; -``` - -### Show debug output - -**.babelrc** - -```json -{ - "presets": [ - ["@babel/preset-env", { - "targets": { - "safari": 10 - }, - "modules": false, - "useBuiltIns": "entry", - "debug": true - }] - ] -} -``` - -**stdout** - -```sh -Using targets: -{ - "safari": 10 -} - -Modules transform: false - -Using plugins: - @babel/plugin-transform-exponentiation-operator {} - @babel/plugin-transform-async-to-generator {} - -Using polyfills: - es7.object.values {} - es7.object.entries {} - es7.object.get-own-property-descriptors {} - web.timers {} - web.immediate {} - web.dom.iterable {} -``` - -### Include and exclude specific plugins/built-ins - -> always include arrow functions, explicitly exclude generators - -```json -{ - "presets": [ - ["@babel/preset-env", { - "targets": { - "browsers": ["last 2 versions", "safari >= 7"] - }, - "include": ["transform-arrow-functions", "es6.map"], - "exclude": ["transform-regenerator", "es6.set"] - }] - ] -} -``` - -## Issues - -If you get a `SyntaxError: Unexpected token ...` error when using the [object-rest-spread](https://github.com/babel/babel/tree/master/packages/babel-plugin-proposal-object-rest-spread) transform then make sure the plugin has been updated to, at least, `v6.19.0`. diff --git a/packages/babel-preset-es2015/README.md b/packages/babel-preset-es2015/README.md index e02eb7a937..ea57825176 100644 --- a/packages/babel-preset-es2015/README.md +++ b/packages/babel-preset-es2015/README.md @@ -2,56 +2,18 @@ > Babel preset for all es2015 plugins. +See our website [@babel/preset-es2015](https://new.babeljs.io/docs/en/next/babel-preset-es2015.html) for more information. + ## Install -```sh -npm install --save-dev @babel/preset-es2015 -``` - -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "presets": ["@babel/preset-es2015"] -} -``` - -### Via CLI +Using npm: ```sh -babel script.js --presets @babel/preset-es2015 +npm install --save @babel/preset-es2015 ``` -### Via Node API +or using yarn: -```javascript -require("@babel/core").transform("code", { - presets: ["@babel/preset-es2015"] -}); +```sh +yarn add --save @babel/preset-es2015 ``` - -## Options - -### `loose` - -`boolean`, defaults to `false`. - -Enable "loose" transformations for any plugins in this preset that allow them. - -### `modules` - -`"amd" | "umd" | "systemjs" | "commonjs" | "cjs" | false`, defaults to `"commonjs"`. - -Enable transformation of ES6 module syntax to another module type. - -Setting this to `false` will not transform modules. - -### `spec` - -`boolean`, defaults to `false`. - -Enable "spec" transformations for any plugins in this preset that allow them. diff --git a/packages/babel-preset-es2016/README.md b/packages/babel-preset-es2016/README.md index 117ee42462..a0a3455b0e 100644 --- a/packages/babel-preset-es2016/README.md +++ b/packages/babel-preset-es2016/README.md @@ -2,34 +2,18 @@ > Babel preset for all es2016 plugins. +See our website [@babel/preset-es2016](https://new.babeljs.io/docs/en/next/babel-preset-es2016.html) for more information. + ## Install -```sh -npm install --save-dev @babel/preset-es2016 -``` - -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "presets": ["@babel/preset-es2016"] -} -``` - -### Via CLI +Using npm: ```sh -babel script.js --presets @babel/preset-es2016 +npm install --save @babel/preset-es2016 ``` -### Via Node API +or using yarn: -```javascript -require("@babel/core").transform("code", { - presets: ["@babel/preset-es2016"] -}); +```sh +yarn add --save @babel/preset-es2016 ``` diff --git a/packages/babel-preset-es2017/README.md b/packages/babel-preset-es2017/README.md index 78eeefb7ca..213c518b86 100644 --- a/packages/babel-preset-es2017/README.md +++ b/packages/babel-preset-es2017/README.md @@ -2,34 +2,18 @@ > Babel preset for all es2017 plugins. +See our website [@babel/preset-es2017](https://new.babeljs.io/docs/en/next/babel-preset-es2017.html) for more information. + ## Install -```sh -npm install --save-dev @babel/preset-es2017 -``` - -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "presets": ["@babel/preset-es2017"] -} -``` - -### Via CLI +Using npm: ```sh -babel script.js --presets @babel/preset-es2017 +npm install --save @babel/preset-es2017 ``` -### Via Node API +or using yarn: -```javascript -require("@babel/core").transform("code", { - presets: ["@babel/preset-es2017"] -}); +```sh +yarn add --save @babel/preset-es2017 ``` diff --git a/packages/babel-preset-flow/README.md b/packages/babel-preset-flow/README.md index 91fba20510..7b86a77712 100644 --- a/packages/babel-preset-flow/README.md +++ b/packages/babel-preset-flow/README.md @@ -2,52 +2,18 @@ > Babel preset for all Flow plugins. -This preset includes the following plugins: +See our website [@babel/preset-flow](https://new.babeljs.io/docs/en/next/babel-preset-flow.html) for more information. -- [@babel/plugin-transform-flow-strip-types](https://babeljs.io/docs/plugins/transform-flow-strip-types/) +## Install -## Example - -**In** - -```javascript -function foo(one: any, two: number, three?): string {} -``` - -**Out** - -```javascript -function foo(one, two, three) {} -``` - -## Installation +Using npm: ```sh -npm install --save-dev @babel/preset-flow +npm install --save @babel/preset-flow ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "presets": ["@babel/preset-flow"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --presets @babel/preset-flow script.js -``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - presets: ["@babel/preset-flow"] -}); +yarn add --save @babel/preset-flow ``` diff --git a/packages/babel-preset-react/README.md b/packages/babel-preset-react/README.md index fcb7b58117..1522842528 100644 --- a/packages/babel-preset-react/README.md +++ b/packages/babel-preset-react/README.md @@ -2,132 +2,18 @@ > Babel preset for all React plugins. -This preset always includes the following plugins: +See our website [@babel/preset-react](https://new.babeljs.io/docs/en/next/babel-preset-react.html) for more information. -- [@babel/plugin-syntax-jsx](https://babeljs.io/docs/plugins/syntax-jsx/) -- [@babel/plugin-transform-react-jsx](https://babeljs.io/docs/plugins/transform-react-jsx/) -- [@babel/plugin-transform-react-display-name](https://babeljs.io/docs/plugins/transform-react-display-name/) +## Install -And with the `development` option: - -- [@babel/plugin-transform-react-jsx-self](https://babeljs.io/docs/plugins/transform-react-jsx-self/) -- [@babel/plugin-transform-react-jsx-source](https://babeljs.io/docs/plugins/transform-react-jsx-source/) - -> Note: Flow syntax support is no longer enabled in v7. For that, you will need to add the [Flow preset](https://babeljs.io/docs/plugins/preset-flow/). - -## Installation - -> You can also check out the React [Getting Started page](https://facebook.github.io/react/docs/hello-world.html) +Using npm: ```sh -npm install --save-dev @babel/preset-react +npm install --save @babel/preset-react ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -Without options: - -```json -{ - "presets": ["@babel/preset-react"] -} -``` - -With options: - -```json -{ - "presets": [ - ["@babel/preset-react", { - "pragma": "dom", // default pragma is React.createElement - "pragmaFrag": "DomFrag", // default is React.Fragment - "throwIfNamespace": false // defaults to true - }] - ] -} -``` - -### Via CLI +or using yarn: ```sh -babel --presets @babel/preset-react script.js -``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - presets: ["@babel/preset-react"] -}); -``` - -## Options - -### `pragma` - -`string`, defaults to `React.createElement`. - -Replace the function used when compiling JSX expressions. - -### `pragmaFrag` - -`string`, defaults to `React.Fragment`. - -Replace the component used when compiling JSX fragments. - -### `useBuiltIns` - -`boolean`, defaults to `false`. - -Will use the native built-in instead of trying to polyfill behavior for any plugins that require one. - -### `development` - -`boolean`, defaults to `false`. - -Toggles plugins that aid in development, such as [`@babel/plugin-transform-react-jsx-self`](https://babeljs.io/docs/plugins/transform-react-jsx-self/) and [`@babel/plugin-transform-react-jsx-source`](https://babeljs.io/docs/plugins/transform-react-jsx-source/). - -This is useful when combined with either a `babelrc.js` or [env option in a .babelrc](https://babeljs.io/docs/usage/babelrc/#env-option) configuration: - -### `throwIfNamespace` - -`boolean`, defaults to `true`. - -Toggles whether or not to throw an error if a XML namespaced tag name is used. For example: - - - -Though the JSX spec allows this, it is disabled by default since React's JSX does not currently have support for it. - -#### babelrc.js - -```js -module.exports = { - presets: [ - ["@babel/preset-react", { - development: process.env.BABEL_ENV === "development", - }], - ], -} -``` - -#### .babelrc - -> Note: the `env` option will likely get deprecated soon - -```json -{ - "presets": ["@babel/preset-react"], - "env": { - "development": { - "presets": [ - ["@babel/preset-react", { "development": true }] - ] - } - } -} +yarn add --save @babel/preset-react ``` diff --git a/packages/babel-preset-stage-0/README.md b/packages/babel-preset-stage-0/README.md index 42d1db872d..b5baaac301 100644 --- a/packages/babel-preset-stage-0/README.md +++ b/packages/babel-preset-stage-0/README.md @@ -1,55 +1,19 @@ # @babel/preset-stage-0 -> Babel preset for stage 0 plugins. +> Babel preset for stage 0 plugins + +See our website [@babel/preset-stage-0](https://new.babeljs.io/docs/en/next/babel-preset-stage-0.html) for more information. ## Install -```sh -npm install --save-dev @babel/preset-stage-0 -``` - -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "presets": ["@babel/preset-stage-0"] -} -``` - -### Via CLI +Using npm: ```sh -babel script.js --presets @babel/preset-stage-0 +npm install --save @babel/preset-stage-0 ``` -### Via Node API +or using yarn: -```javascript -require("@babel/core").transform("code", { - presets: ["@babel/preset-stage-0"] -}); +```sh +yarn add --save @babel/preset-stage-0 ``` - -## Options - -### `loose` - -`boolean`, defaults to `false`. - -Enable "loose" transformations for any plugins in this preset that allow them. - -### `useBuiltIns` - -`boolean`, defaults to `false`. - -Will use the native built-in instead of trying to polyfill behavior for any plugins that require one. - -### `decoratorsLegacy` - -`boolean`, defaults to `false`. - -Use the legacy (stage 1) decorators syntax and behavior. diff --git a/packages/babel-preset-stage-1/README.md b/packages/babel-preset-stage-1/README.md index 0166562289..42d1e1a4d9 100644 --- a/packages/babel-preset-stage-1/README.md +++ b/packages/babel-preset-stage-1/README.md @@ -1,69 +1,19 @@ # @babel/preset-stage-1 -> Babel preset for stage 1 plugins. +> Babel preset for stage 1 plugins -The gist of Stage 1 is: - -> **Stage 1**: proposal -> -> **What is it?** A formal proposal for the feature. -> -> **What’s required?** A so-called champion must be identified who is responsible for the proposal. Either the champion or a co-champion must be a member of TC39 (source). The problem solved by the proposal must be described in prose. The solution must be described via examples, an API and a discussion of semantics and algorithms. Lastly, potential obstacles for the proposal must be identified, such as interactions with other features and implementation challenges. Implementation-wise, polyfills and demos are needed. -> -> **What’s next?** By accepting a proposal for stage 1, TC39 declares its willingness to examine, discuss and contribute to the proposal. Going forward, major changes to the proposal are expected +See our website [@babel/preset-stage-1](https://new.babeljs.io/docs/en/next/babel-preset-stage-1.html) for more information. ## Install -```sh -npm install --save-dev @babel/preset-stage-1 -``` - -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "presets": ["@babel/preset-stage-1"] -} -``` - -### Via CLI +Using npm: ```sh -babel script.js --presets @babel/preset-stage-1 +npm install --save @babel/preset-stage-1 ``` -### Via Node API +or using yarn: -```javascript -require("@babel/core").transform("code", { - presets: ["@babel/preset-stage-1"] -}); +```sh +yarn add --save @babel/preset-stage-1 ``` - -## Options - -### `loose` - -`boolean`, defaults to `false`. - -Enable "loose" transformations for any plugins in this preset that allow them. - -### `useBuiltIns` - -`boolean`, defaults to `false`. - -Will use the native built-in instead of trying to polyfill behavior for any plugins that require one. - -### `decoratorsLegacy` - -`boolean`, defaults to `false`. - -Use the legacy (stage 1) decorators syntax and behavior. - -## References - -- Chapter "[The TC39 process for ECMAScript features](http://exploringjs.com/es2016-es2017/ch_tc39-process.html)" in "Exploring ES2016 and ES2017" by Axel Rauschmayer diff --git a/packages/babel-preset-stage-2/README.md b/packages/babel-preset-stage-2/README.md index 10342ad4db..3bd192c712 100644 --- a/packages/babel-preset-stage-2/README.md +++ b/packages/babel-preset-stage-2/README.md @@ -1,69 +1,19 @@ # @babel/preset-stage-2 -> Babel preset for stage 2 plugins. +> Babel preset for stage 2 plugins -The gist of Stage 2 is: - -> **Stage 2:** draft -> -> **What is it?** A first version of what will be in the specification. At this point, an eventual inclusion of the feature in the standard is likely. -> -> **What’s required?** The proposal must now additionally have a formal description of the syntax and semantics of the feature (using the formal language of the ECMAScript specification). The description should be as complete as possible, but can contain todos and placeholders. Two experimental implementations of the feature are needed, but one of them can be in a transpiler such as Babel. -> -> **What’s next?** Only incremental changes are expected from now on. +See our website [@babel/preset-stage-2](https://new.babeljs.io/docs/en/next/babel-preset-stage-2.html) for more information. ## Install -```sh -npm install --save-dev @babel/preset-stage-2 -``` - -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "presets": ["@babel/preset-stage-2"] -} -``` - -### Via CLI +Using npm: ```sh -babel script.js --presets @babel/preset-stage-2 +npm install --save @babel/preset-stage-2 ``` -### Via Node API +or using yarn: -```javascript -require("@babel/core").transform("code", { - presets: ["@babel/preset-stage-2"] -}); +```sh +yarn add --save @babel/preset-stage-2 ``` - -## Options - -### `loose` - -`boolean`, defaults to `false`. - -Enable "loose" transformations for any plugins in this preset that allow them. - -### `useBuiltIns` - -`boolean`, defaults to `false`. - -Will use the native built-in instead of trying to polyfill behavior for any plugins that require one. - -### `decoratorsLegacy` - -`boolean`, defaults to `false`. - -Use the legacy (stage 1) decorators syntax and behavior. - -## References - -- Chapter "[The TC39 process for ECMAScript features](http://exploringjs.com/es2016-es2017/ch_tc39-process.html)" in "Exploring ES2016 and ES2017" by Axel Rauschmayer diff --git a/packages/babel-preset-stage-3/README.md b/packages/babel-preset-stage-3/README.md index ea52dedcb7..a89310e81f 100644 --- a/packages/babel-preset-stage-3/README.md +++ b/packages/babel-preset-stage-3/README.md @@ -1,63 +1,19 @@ # @babel/preset-stage-3 -> Babel preset for stage 3 plugins. +> Babel preset for stage 3 plugins -The gist of Stage 3 is: - -> **Stage 3**: candidate -> -> **What is it?** The proposal is mostly finished and now needs feedback from implementations and users to progress further. - -> **What’s required?** The spec text must be complete. Designated reviewers (appointed by TC39, not by the champion) and the ECMAScript spec editor must sign off on the spec text. There must be at least two spec-compliant implementations (which don’t have to be enabled by default). -> -> **What’s next?** Henceforth, changes should only be made in response to critical issues raised by the implementations and their use. +See our website [@babel/preset-stage-3](https://new.babeljs.io/docs/en/next/babel-preset-stage-3.html) for more information. ## Install -```sh -npm install --save-dev @babel/preset-stage-3 -``` - -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "presets": ["@babel/preset-stage-3"] -} -``` - -### Via CLI +Using npm: ```sh -babel script.js --presets @babel/preset-stage-3 +npm install --save @babel/preset-stage-3 ``` -### Via Node API +or using yarn: -```javascript -require("@babel/core").transform("code", { - presets: ["@babel/preset-stage-3"] -}); +```sh +yarn add --save @babel/preset-stage-3 ``` - -## Options - -### `loose` - -`boolean`, defaults to `false`. - -Enable "loose" transformations for any plugins in this preset that allow them. - -### `useBuiltIns` - -`boolean`, defaults to `false`. - -Will use the native built-in instead of trying to polyfill behavior for any plugins that require one. - -## References - -- Chapter "[The TC39 process for ECMAScript features](http://exploringjs.com/es2016-es2017/ch_tc39-process.html)" in "Exploring ES2016 and ES2017" by Axel Rauschmayer diff --git a/packages/babel-preset-typescript/README.md b/packages/babel-preset-typescript/README.md index c10cf72df8..a993c95959 100644 --- a/packages/babel-preset-typescript/README.md +++ b/packages/babel-preset-typescript/README.md @@ -2,64 +2,18 @@ > Babel preset for TypeScript. -This preset includes the following plugins: +See our website [@babel/preset-typescript](https://new.babeljs.io/docs/en/next/babel-preset-typescript.html) for more information. -- [@babel/plugin-transform-typescript](https://github.com/babel/babel/tree/master/packages/babel-plugin-transform-typescript) +## Install -> You will need to specify `--extensions ".ts"` for `@babel/cli` & `@babel/node` cli's to handle `.ts` files. - -## Example - -**In** - -```javascript -const x: number = 0; -``` - -**Out** - -```javascript -const x = 0; -``` - -## Installation +Using npm: ```sh -npm install --save-dev @babel/preset-typescript +npm install --save @babel/preset-typescript ``` -## Usage - -### Via `.babelrc` (Recommended) - -**.babelrc** - -```json -{ - "presets": ["@babel/preset-typescript"] -} -``` - -### Via CLI +or using yarn: ```sh -babel --presets @babel/preset-typescript script.ts +yarn add --save @babel/preset-typescript ``` - -### Via Node API - -```javascript -require("@babel/core").transform("code", { - presets: ["@babel/preset-typescript"] -}); -``` - -## Options - -### `jsxPragma` - -`string` - -Replace the function used when compiling JSX expressions. - -This is so that we know that the import is not a type import, and should not be removed diff --git a/packages/babel-register/README.md b/packages/babel-register/README.md index dc8a475ef5..40c434d9ff 100644 --- a/packages/babel-register/README.md +++ b/packages/babel-register/README.md @@ -1,133 +1,19 @@ # @babel/register -> The require hook will bind itself to node's require and automatically compile files on the fly. +> babel require hook -One of the ways you can use Babel is through the require hook. The require hook -will bind itself to node's `require` and automatically compile files on the -fly. This is equivalent to CoffeeScript's -[coffee-script/register](http://coffeescript.org/v2/annotated-source/register.html). +See our website [@babel/register](https://new.babeljs.io/docs/en/next/babel-register.html) for more information. ## Install -```sh -npm install @babel/core @babel/register --save-dev -``` - -## Usage - -```js -require("@babel/register"); -``` - -All subsequent files required by node with the extensions `.es6`, `.es`, `.jsx`, -`.mjs`, and `.js` will be transformed by Babel. - -
-

Polyfill not included

-

- You must include the polyfill separately - when using features that require it, like generators. -

-
- -### Ignores `node_modules` by default - -**NOTE:** By default all requires to `node_modules` will be ignored. You can -override this by passing an ignore regex via: - -```js -require("@babel/register")({ - // This will override `node_modules` ignoring - you can alternatively pass - // an array of strings to be explicitly matched or a regex / glob - ignore: [] -}); -``` - -## Specifying options - -```javascript -require("@babel/register")({ - // Array of ignore conditions, either a regex or a function. (Optional) - ignore: [ - // When a file path matches this regex then it is **not** compiled - /regex/, - - // The file's path is also passed to any ignore functions. It will - // **not** be compiled if `true` is returned. - function (filepath) { - return filepath !== "/path/to/es6-file.js"; - } - ], - - // Optional only regex - if any filenames **don't** match this regex then they - // aren't compiled - only: /my_es6_folder/, - - // Setting this will remove the currently hooked extensions of `.es6`, `.es`, `.jsx`, `.mjs` - // and .js so you'll have to add them back if you want them to be used again. - extensions: [".es6", ".es", ".jsx", ".js", ".mjs"], - - // Setting this to false will disable the cache. - cache: true -}); -``` - -You can pass in all other [options](https://babeljs.io/docs/usage/api/#options) as well, -including `plugins` and `presets`. But note that the closest [`.babelrc`](https://babeljs.io/docs/usage/babelrc/) -to each file still applies, and takes precedence over any options you pass in here. - -## Environment variables - -By default `@babel/node` cli and `@babel/register` will save to a json cache in your -temporary directory. - -This will heavily improve with the startup and compilation of your files. There -are however scenarios where you want to change this behaviour and there are -environment variables exposed to allow you to do this. - -### BABEL_CACHE_PATH - -Specify a different cache location. +Using npm: ```sh -BABEL_CACHE_PATH=/foo/my-cache.json babel-node script.js +npm install --save @babel/register ``` -### BABEL_DISABLE_CACHE - -Disable the cache. +or using yarn: ```sh -BABEL_DISABLE_CACHE=1 babel-node script.js +yarn add --save @babel/register ``` - -## Compiling plugins and presets on the fly - -`@babel/register` uses Node's `require()` hook system to compile files -on the fly when they are loaded. While this is quite helpful overall, it means -that there can be confusing cases where code within a `require()` hook causes -_more_ calls to `require`, causing a dependency cycle. In Babel's case for -instance, this could mean that in the process of Babel trying to compile a -user's file, Babel could end up trying to compile itself _as it is loading_. - -To avoid this problem, this module explicitly disallows re-entrant compilation, -e.g. Babel's own compilation logic explicitly cannot trigger further compilation -of any other files on the fly. The downside of this is that if you want to -define a plugin or preset that is itself live-compiled, the process is -complicated. - -The crux of it is that your own code needs to load the plugin/preset first. -Assuming the plugin/preset loads all of its dependencies up front, what you'll -want to do is: - -``` -require("@babel/register")({ - // ... -}); - -require("./my-plugin"); -``` - -Because it is your own code that triggered the load, and not the logic within -`@babel/register` itself, this should successfully compile any plugin/preset -that that loads synchronously. diff --git a/packages/babel-runtime/README.md b/packages/babel-runtime/README.md index b1dce5a653..2ef39c3c62 100644 --- a/packages/babel-runtime/README.md +++ b/packages/babel-runtime/README.md @@ -1,5 +1,19 @@ # @babel/runtime -## Usage +> babel selfContained runtime -TODO +See our website [@babel/runtime](https://new.babeljs.io/docs/en/next/babel-runtime.html) for more information. + +## Install + +Using npm: + +```sh +npm install --save @babel/runtime +``` + +or using yarn: + +```sh +yarn add --save @babel/runtime +``` diff --git a/packages/babel-standalone/README.md b/packages/babel-standalone/README.md index 16a6851e6d..69f0319943 100644 --- a/packages/babel-standalone/README.md +++ b/packages/babel-standalone/README.md @@ -1,92 +1,19 @@ -@babel/standalone -================ +# @babel/standalone -@babel/standalone is a standalone build of Babel for use in non-Node.js environments, including browsers. It's bundled with all the standard Babel plugins and presets, and [a build of babili (babel-minify)](http://dl.vc/babili-standalone) is optionally available too. +> Standalone build of Babel for use in non-Node.js environments. -But why?! -========= +See our website [@babel/standalone](https://new.babeljs.io/docs/en/next/babel-standalone.html) for more information. -It's true that using Babel through Webpack, Browserify or Gulp should be sufficient for most use cases. However, there are some valid use cases for @babel/standalone: +## Install - - Sites like [JSFiddle](https://jsfiddle.net/), [JS Bin](https://jsbin.com/), the [REPL on the Babel site](http://babeljs.io/repl/), etc. These sites compile user-provided JavaScript in real-time. - - Apps that embed a JavaScript engine such as V8 directly, and want to use Babel for compilation - - Apps that want to use JavaScript as a scripting language for extending the app itself, including all the goodies that ES2015 provides. - - Integration of Babel into a non-Node.js environment ([ReactJS.NET](http://reactjs.net/), [ruby-babel-transpiler](https://github.com/babel/ruby-babel-transpiler), [php-babel-transpiler](https://github.com/talyssonoc/php-babel-transpiler), etc). +Using npm: -Installation -============ - -There are several ways to get a copy of @babel/standalone. Pick whichever one you like: - -- Use it via UNPKG: https://unpkg.com/@babel/standalone/babel.min.js. This is a simple way to embed it on a webpage without having to do any other setup. -- Install via NPM: `npm install --save @babel/standalone` -- Manually grab `babel.js` and/or `babel.min.js` from the [GitHub releases page](https://github.com/Daniel15/babel-standalone/releases). Every release includes these files. -- Install it via Git: You can use the repo at https://github.com/Daniel15/babel-standalone-bower to pull a prebuilt version from Git. Note that this is generally only advised for systems that *must* pull artifacts from Git, such as Bower. - -Usage -===== - -Load `babel.js` or `babel.min.js` in your environment. This will expose [Babel's API](http://babeljs.io/docs/usage/api/) in a `Babel` object: - -```js -var input = 'const getMessage = () => "Hello World";'; -var output = Babel.transform(input, { presets: ['es2015'] }).code; +```sh +npm install --save @babel/standalone ``` -When loaded in a browser, @babel/standalone will automatically compile and execute all script tags with type `text/babel` or `text/jsx`: -```html -
- - - - -``` - -You can use the `data-plugins` and `data-presets` attributes to specify the Babel plugins/presets to use: -```html - -``` - -Note that `.babelrc` doesn't work in @babel/standalone, as no file system access is available. The presets and/or plugins to use **must** be specified in the options passed to `Babel.transform`. - -Customisation -============= -Custom plugins and presets can be added using the `registerPlugin` and `registerPreset` methods respectively: - -```js -// Simple plugin that converts every identifier to "LOL" -function lolizer() { - return { - visitor: { - Identifier(path) { - path.node.name = 'LOL'; - } - } - } -} -Babel.registerPlugin('lolizer', lolizer); -``` - -Once registered, just use the name of the plugin: - -```js -var output = Babel.transform( - 'function helloWorld() { alert(hello); }', - {plugins: ['lolizer']} -); -// Returns "function LOL() { LOL(LOL); }" -``` - -Custom plugins also work for inline `