+You can use [babel/babel-standalone](https://github.com/babel/babel-standalone#usage) as a precompiled version of babel or run a bundler on babel yourself. diff --git a/docs/editors.md b/docs/editors.md new file mode 100644 index 0000000000..c457e9a77f --- /dev/null +++ b/docs/editors.md @@ -0,0 +1,38 @@ +--- +layout: docs +title: Editors +description: Learn how to use Babel in your editor of choice +permalink: /docs/editors +--- + +## Syntax Highlighting + +These days, many popular editors support ES2015+ syntax highlighting +out of the box, while some require installing additional extensions. +This guide should help you get the syntax highlighting to work. + +If you're looking for more advanced integrations, you may want to +take a look at the [Setup](/docs/setup) guide. + +### Atom + +Install [language-babel](https://atom.io/packages/language-babel) package +and follow the [instructions](https://github.com/gandm/language-babel#installation). + +### Sublime Text 3 + +First, [install Package Control](https://packagecontrol.io/installation). +Then install [Babel](https://packagecontrol.io/packages/Babel) package +from the Package Control menu and follow +the [instructions](https://github.com/babel/babel-sublime#installation). + +### Visual Studio Code + +Install [Babel ES6/ES7](https://marketplace.visualstudio.com/items?itemName=dzannotti.vscode-babel-coloring) +extension and follow the instructions. + +### WebStorm + +Seems like WebStorm now ships with support for ES2015+ without requiring you +to install additional extensions. You might need to +[enable it](https://blog.jetbrains.com/webstorm/2015/05/ecmascript-6-in-webstorm-transpiling/) though. diff --git a/docs/setup.md b/docs/setup.md index 404d5eb7a8..5284f6f26e 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -7,6 +7,8 @@ redirect_from: - /docs/using-babel/ - /plugins.html - /docs/using-6to5/ + - /docs/usage/browser/ + - browser.html custom_js_with_timestamps: - tools.js --- diff --git a/docs/usage/api.md b/docs/usage/api.md index dc95e9150d..90bed99973 100644 --- a/docs/usage/api.md +++ b/docs/usage/api.md @@ -4,6 +4,8 @@ title: API description: How to use the Node.js API. permalink: /docs/usage/api/ package: babel-core +redirect_from: +- /docs/usage/options/ --- ```javascript @@ -12,7 +14,7 @@ import { transform } from 'babel-core'; import * as babel from 'babel-core'; ``` -## babel.transform(code: string, [options?](/docs/usage/options): Object) +## babel.transform(code: string, [options?](/docs/usage/api/#options): Object) Transforms the passed in `code`. Returning an object with the generated code, source map, and AST. @@ -30,7 +32,7 @@ result.map; result.ast; ``` -## babel.transformFile(filename: string, [options?](/docs/usage/options): Object, callback: Function) +## babel.transformFile(filename: string, [options?](/docs/usage/api/#options): Object, callback: Function) Asynchronously transforms the entire contents of a file. @@ -46,7 +48,7 @@ babel.transformFile("filename.js", options, function (err, result) { }); ``` -## babel.transformFileSync(filename: string, [options?](/docs/usage/options): Object) +## babel.transformFileSync(filename: string, [options?](/docs/usage/api/#options): Object) Synchronous version of `babel.transformFile`. Returns the transformed contents of the `filename`. @@ -61,7 +63,7 @@ babel.transformFileSync(filename, options) // => { code, map, ast } babel.transformFileSync("filename.js", options).code; ``` -## babel.transformFromAst(ast: Object, code?: string, [options?](/docs/usage/options): Object) +## babel.transformFromAst(ast: Object, code?: string, [options?](/docs/usage/api/#options): Object) Given, an [AST](https://astexplorer.net/), transform it. @@ -70,3 +72,51 @@ const code = "if (true) return;"; const ast = babylon.parse(code, { allowReturnOutsideFunction: true }); const { code, map, ast } = babel.transformFromAst(ast, code, options); ``` + +## Options + ++ +
++ Compiling in the browser has a fairly limited use case, so if you are + working on a production site you should be precompiling your scripts + server-side. See setup build systems + for more information. +
+
++ +Following is a table of the options you can use: + +| Option | Default | Description | +| ------------------------ | -------------------- | ------------------------------- | +| `filename` | `"unknown"` | Filename for use in errors etc. | +| `filenameRelative` | `(filename)` | Filename relative to `sourceRoot`. | +| `presets` | `[]` | List of [presets](/docs/plugins/#presets) (a set of plugins) to load and use. | +| `plugins` | `[]` | List of [plugins](/docs/plugins/) to load and use. | +| `parserOpts` | `{}` | An object containing the options to be passed down to the babel parser, babylon | +| `generatorOpts` | `{}` | An object containing the options to be passed down to the babel code generator, babel-generator | +| `highlightCode` | `true` | ANSI highlight syntax error code frames | +| `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. | +| `ignore` | `null` | Opposite to the `only` option. `ignore` is disregarded if `only` is specified. | +| `auxiliaryCommentBefore` | `null` | Attach a comment before all non-user injected code. | +| `auxiliaryCommentAfter` | `null` | Attach a comment after all non-user injected code. | +| `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. | +| `inputSourceMap` | `null` | A source map object that the output source map will be based on. | +| `sourceMapTarget` | `(filenameRelative)` | Set `file` on returned source map. | +| `sourceFileName` | `(filenameRelative)` | Set `sources[0]` on returned source map. | +| `sourceRoot` | `(moduleRoot)` | The root from which all sources are relative. | +| `moduleRoot` | `(sourceRoot)` | Optional prefix for the AMD module formatter that will be prepend to the filename on module definitions. | +| `moduleIds` | `false` | If truthy, insert an explicit id for modules. By default, all modules are anonymous. (Not available for `common` modules) | +| `moduleId` | `null` | Specify a custom name for module ids. | +| `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. | +| `resolveModuleSource` | `null` | Resolve a module source ie. `import "SOURCE";` to a custom value. Called as `resolveModuleSource(source, filename)`. | +| `code` | `true` | Enable code generation | +| `no-babelrc` | [CLI flag](http://babeljs.io/docs/usage/cli/#ignoring-babelrc) | Specify whether or not to use .babelrc and .babelignore files. Only available when using the CLI. | +| `ast` | `true` | Include the AST in the returned object | +| `compact` | `"auto"` | Do not include superfluous whitespace characters and line terminators. When set to `"auto"` compact is set to `true` on input sizes of >100KB. | +| `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) | +| `comments` | `true` | Output comments in generated output. | +| `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. | +| `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 enviroment variable `BABEL_ENV` is set to `"production"`. If `BABEL_ENV` isn't set then `NODE_ENV` will be used, if it's not set then it defaults to `"development"` | +| `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) | +| `extends` | `null` | A path to an `.babelrc` file to extend | diff --git a/docs/usage/babelrc.md b/docs/usage/babelrc.md index f0d74c2f1c..b16eaee86e 100644 --- a/docs/usage/babelrc.md +++ b/docs/usage/babelrc.md @@ -1,7 +1,7 @@ --- layout: docs -title: babelrc -description: How to use the babelrc +title: .babelrc +description: How to use the .babelrc permalink: /docs/usage/babelrc/ --- diff --git a/docs/usage/browser.md b/docs/usage/browser.md deleted file mode 100644 index d1f774d48f..0000000000 --- a/docs/usage/browser.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -layout: docs -title: Browser -description: How to compile in the browser. -permalink: /docs/usage/browser/ -redirect_from: /browser.html ---- - -Babel CLI
++ You can pass these options from the Babel CLI like so: +
++
+babel --name=value+
-- -## `babel-browser` has been removed. - -Use a bundler like [browserify](https://babeljs.io/docs/setup/#browserify)/[webpack](https://babeljs.io/docs/setup/#webpack) or just `require('babel-core')`. - -## [babel-standalone](https://github.com/Daniel15/babel-standalone) - -If you don't want to do it yourself, you can also use [babel-standalone](https://github.com/Daniel15/babel-standalone) which is a pre-built babel with all of the presets and is used in the [Babel REPL](https://babeljs.io/repl). - - diff --git a/docs/usage/cli.md b/docs/usage/cli.md index 63896ae6c2..4351feec15 100644 --- a/docs/usage/cli.md +++ b/docs/usage/cli.md @@ -118,7 +118,7 @@ babel --no-babelrc script.js --out-file script-compiled.js --presets=add-module- ### Advanced Usage -There are many more options available in the babel CLI, see [options](/docs/usage/options/), `babel --help` and other sections for more information. +There are many more options available in the babel CLI, see [options](/docs/usage/api/#options), `babel --help` and other sections for more information. ## babel-node diff --git a/docs/usage/options.md b/docs/usage/options.md deleted file mode 100644 index f2642ce537..0000000000 --- a/docs/usage/options.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -layout: docs -title: Options -description: Options for babel transpiling. -permalink: /docs/usage/options/ ---- - -## Usage - -```js -babel.transform(code, options); -``` - -```sh -babel --name=value -``` - -## Options - -| Option | Default | Description | -| ------------------------ | -------------------- | ------------------------------- | -| `filename` | `"unknown"` | Filename for use in errors etc. | -| `filenameRelative` | `(filename)` | Filename relative to `sourceRoot`. | -| `presets` | `[]` | List of [presets](/docs/plugins/#presets) (a set of plugins) to load and use. | -| `plugins` | `[]` | List of [plugins](/docs/plugins/) to load and use. | -| `parserOpts` | `{}` | An object containing the options to be passed down to the babel parser, babylon | -| `generatorOpts` | `{}` | An object containing the options to be passed down to the babel code generator, babel-generator | -| `highlightCode` | `true` | ANSI highlight syntax error code frames | -| `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. | -| `ignore` | `null` | Opposite to the `only` option. `ignore` is disregarded if `only` is specified. | -| `auxiliaryCommentBefore` | `null` | Attach a comment before all non-user injected code. | -| `auxiliaryCommentAfter` | `null` | Attach a comment after all non-user injected code. | -| `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. | -| `inputSourceMap` | `null` | A source map object that the output source map will be based on. | -| `sourceMapTarget` | `(filenameRelative)` | Set `file` on returned source map. | -| `sourceFileName` | `(filenameRelative)` | Set `sources[0]` on returned source map. | -| `sourceRoot` | `(moduleRoot)` | The root from which all sources are relative. | -| `moduleRoot` | `(sourceRoot)` | Optional prefix for the AMD module formatter that will be prepend to the filename on module definitions. | -| `moduleIds` | `false` | If truthy, insert an explicit id for modules. By default, all modules are anonymous. (Not available for `common` modules) | -| `moduleId` | `null` | Specify a custom name for module ids. | -| `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. | -| `resolveModuleSource` | `null` | Resolve a module source ie. `import "SOURCE";` to a custom value. Called as `resolveModuleSource(source, filename)`. | -| `code` | `true` | Enable code generation | -| `no-babelrc` | [CLI flag](http://babeljs.io/docs/usage/cli/#ignoring-babelrc) | Specify whether or not to use .babelrc and .babelignore files. Only available when using the CLI. | -| `ast` | `true` | Include the AST in the returned object | -| `compact` | `"auto"` | Do not include superfluous whitespace characters and line terminators. When set to `"auto"` compact is set to `true` on input sizes of >100KB. | -| `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) | -| `comments` | `true` | Output comments in generated output. | -| `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. | -| `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 enviroment variable `BABEL_ENV` is set to `"production"`. If `BABEL_ENV` isn't set then `NODE_ENV` will be used, if it's not set then it defaults to `"development"` | -| `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) | -| `extends` | `null` | A path to an `.babelrc` file to extend | diff --git a/docs/learn-es6.md b/learn-es2015.md similarity index 99% rename from docs/learn-es6.md rename to learn-es2015.md index 8ce4c4c1c0..eaecb3ef5a 100644 --- a/docs/learn-es6.md +++ b/learn-es2015.md @@ -2,9 +2,10 @@ layout: docs title: Learn ES2015 description: A detailed overview of ECMAScript 2015 features. Based on Luke Hoban's es6features repo. -permalink: /docs/learn-es2015/ +permalink: /learn-es2015/ redirect_from: - /docs/learn-es6/ + - /docs/learn-es2015/ - /features.html - /docs/tour/ --- @@ -45,7 +46,7 @@ for full specification of the ECMAScript 2015 language. Arrows are a function shorthand using the `=>` syntax. They are syntactically similar to the related feature in C#, Java 8 and CoffeeScript. They support both expression and statement bodies. Unlike functions, arrows share the same -lexical `this` as their surrounding code. If an arrow is inside another function, +lexical `this` as their surrounding code. If an arrow is inside another function, it shares the "arguments" variable of its parent function. ```js- -
-- Compiling in the browser has a fairly limited use case, so if you are - working on a production site you should be precompiling your scripts - server-side. See setup build systems - for more information. -
-