diff --git a/docs/standalone.md b/docs/standalone.md index 4fd01dd3dc..e0122284b6 100644 --- a/docs/standalone.md +++ b/docs/standalone.md @@ -4,16 +4,20 @@ title: @babel/standalone sidebar_label: standalone --- +@babel/standalone provides a standalone build of Babel for use in browsers and other non-Node.js environments. -But why?! -========= +When (not) to use @babel/standalone +=================================== -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: +If you're using Babel in production, you should normally not use @babel/standalone. Instead, you should use a build system running on Node.js, such as Webpack, Rollup, or Parcel, to transpile your JS ahead of time. - - Sites like [JSFiddle](https://jsfiddle.net/), [JS Bin](https://jsbin.com/), the [REPL on the Babel site](http://babeljs.io/repl/), [JSitor](https://jsitor.com), 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). +However, there are some valid use cases for @babel/standalone: + +- It provides an easy, convenient way to prototype with Babel. Using @babel/standalone, you can get started using Babel with just a simple script tag in your HTML. +- Sites that compile user-provided JavaScript in real-time, like [JSFiddle](https://jsfiddle.net/), [JS Bin](https://jsbin.com/), the [REPL on the Babel site](http://babeljs.io/repl/), [JSitor](https://jsitor.com), etc. +- 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. +- Other non-Node.js environments ([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). Installation ============ @@ -25,17 +29,11 @@ There are several ways to get a copy of @babel/standalone. Pick whichever one yo - 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: ['env'] }).code; -``` +Script Tags +=========== When loaded in a browser, @babel/standalone will automatically compile and execute all script tags with type `text/babel` or `text/jsx`: + ```html
@@ -47,16 +45,40 @@ document.getElementById('output').innerHTML = getMessage(); ``` +If you want to use your browser's native support for ES Modules, you'd normally need to set a `type="module"` attribute on your script tag. With @babel/standalone, set a `data-type="module"` attribute instead, like this: + +```html + ``` +You can also set the `async` attribute for external scripts. + +```html + +``` + +API +=== + +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: ['env'] }).code; +``` + Note that [config files](config-files.md) don'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 @@ -77,7 +99,13 @@ function lolizer() { Babel.registerPlugin('lolizer', lolizer); ``` -Once registered, just use the name of the plugin: +Once registered, you can either use the custom plugin in an inline script: + +```html +