diff --git a/.npmignore b/.npmignore index 79fa07bb98..488e0ca9e5 100644 --- a/.npmignore +++ b/.npmignore @@ -8,4 +8,4 @@ Makefile .* dist tests.json -!README.md +CHANGELOG.md diff --git a/README.md b/README.md index fef8b04e3a..46af132052 100644 --- a/README.md +++ b/README.md @@ -26,497 +26,4 @@ **6to5** turns ES6 code into vanilla ES5, so you can use ES6 features **today.** - - **Readable** - formatting is retained if possible so your generated code is as similar as possible. - - **Extensible** - with a large range of [plugins](#plugins) and **browser support**. - - **Lossless** - **source map support** so you can debug your compiled code with ease. - - **Compact** - maps directly to the equivalent ES5 with **no runtime**[\*](#generators). - -## Installation - -It's as easy as: - - $ npm install -g 6to5 - -## Table of Contents - -- [Features](#features) -- [Usage](#usage) - - [Plugins](#plugins) - - [CLI](#cli) - - [Node](#node-1) - - [Browser](#browser) -- [Modules](#modules) -- [Caveats](#caveats) -- [Polyfill](#polyfill) -- [Optional runtime](#optional-runtime) -- [React/JSX](#reactjsx) -- [Differences](#differences) - -## [Features](FEATURES.md) - - - [Array comprehension](FEATURES.md#array-comprehension) - - [Async functions](FEATURES.md#async-functions) via [regenerator](https://github.com/facebook/regenerator) - - [Arrow functions](FEATURES.md#arrow-functions) - - [Classes](FEATURES.md#classes) - - [Computed property names](FEATURES.md#computed-property-names) - - [Constants](FEATURES.md#constants) - - [Default parameters](FEATURES.md#default-parameters) - - [Destructuring](FEATURES.md#destructuring) - - [For-of](FEATURES.md#for-of) - - [Generators](FEATURES.md#generators) via [regenerator](https://github.com/facebook/regenerator) - - [Generator comprehension](FEATURES.md#generator-comprehension) - - [Let scoping](FEATURES.md#let-scoping) - - [Modules](FEATURES.md#modules) - - [Numeric literals](FEATURES.md#numeric-literals) - - [Property method assignment](FEATURES.md#property-method-assignment) - - [Property name shorthand](FEATURES.md#property-name-shorthand) - - [React/JSX](#reactjsx) - - [Rest parameters](FEATURES.md#rest-parameters) - - [Spread](FEATURES.md#spread) - - [Template literals](FEATURES.md#template-literals) - - [Unicode regex](FEATURES.md#unicode-regex) - -## Usage - -### Plugins - - - [Broccoli](https://github.com/very-geek/broccoli-6to5-transpiler) - - [Browserify](https://github.com/6to5/6to5-browserify) - - [Brunch](https://github.com/es128/6to5-brunch) - - [Duo](https://github.com/bdo-labs/duo6to5) - - [Connect](https://github.com/6to5/6to5-connect) - - [Gulp](https://github.com/sindresorhus/gulp-6to5) - - [Grunt](https://github.com/sindresorhus/grunt-6to5) - - [Jade](https://github.com/Apoxx/jade-6to5) - - [Jest](https://github.com/6to5/6to5-jest) - - [Karma](https://github.com/shuhei/karma-6to5-preprocessor) - - [Mocha](https://github.com/6to5/6to5-mocha) - - [Rails](https://github.com/6to5/6to5-rails) - - [webpack](https://github.com/Couto/6to5-loader) - -### CLI - -Compile the file `script.js` and output it to stdout. - - $ 6to5 script.js - -Compile the file `script.js` and output it to `script-compiled.js`. - - $ 6to5 script.js --out-file script-compiled.js - -Compile the file `script.js` and output it to `script-compiled.js` and save a -source map to `script-compiled.js.map`. - - $ 6to5 script.js --source-maps --out-file script-compiled.js - -Compile the file `script.js` and output it to `script-compiled.js` with a source -map embedded in a comment at the bottom. - - $ 6to5 script.js --source-maps-inline --out-file script-compiled.js - -Compile the entire `src` directory and output it to the `lib` directory. - - $ 6to5 src --out-dir lib - -Compile the entire `src` directory and output it to the one concatenated file. - - $ 6to5 src --out-file script-compiled.js - -Pipe a file in via stdin and output it to `script-compiled.js` - - $ 6to5 --out-file script-compiled.js < script.js - -#### Node - -Launch a repl. - - $ 6to5-node - -Evaluate code. - - $ 6to5-node -e "class Test { }" - -Compile and run `test.js`. - - $ 6to5-node test - -### Node - -```javascript -var to5 = require("6to5"); - -var result = to5.transform("code();", options); -result.code; -result.map; -result.ast; - -to5.transformFileSync("filename.js", options).code; - -to5.transformFile("filename.js", options, function (err, result) { - -}); -``` - -##### Options - -```javascript -{ - // Filename for use in errors etc. - // Default: "unknown" - filename: "filename", - - // List of transformers to EXCLUDE. - // Run `6to5 --help` to see a full list of transformers. - blacklist: [], - - // List of transformers to ONLY use. - // Run `6to5 --help` to see a full list of transformers. - whitelist: [], - - // Module formatter to use - // Run `6to5 --help` to see a full list of module formatters. - // Default: "common" - modules: "common", - - // 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. - // Default: false - sourceMap: true, - - // Set `file` on returned source map. - // Default: `filename` option. - sourceMapName: "filename", - - // Set `sources[0]` on returned source map. - // Default: `filename` option. - sourceFileName: "filename", - - // Optionally replace all 6to5 helper declarations with a referenece to this - // variable. If set to `true` then the default namespace is used "to5Runtime". - // Default: false - runtime: true -} -``` - -#### Require hook - -All subsequent files required by node with the extensions `.es6` and `.js` will -be transformed by 6to5. The polyfill specified in [Polyfill](#polyfill) is also -required. - -```javascript -require("6to5/register"); -``` - -**NOTE:** By default all requires to `node_modules` will be ignored. You can -override this by passing an ignore regex via: - -```javascript -require("6to5/register")({ - // This will override `node_modules` ignoring - you can alternatively pass - // a regex - ignore: false -}); -``` - -##### Options - -```javascript -require("6to5/register")({ - // Optional ignore regex - if any filenames **do** match this regex then they - // aren't compiled - ignore: /regex/, - - // Optional only regex - if any filenames **don't** match this regex then they - // aren't compiled - only: /my_es6_folder/, - - // See options above for usage - whitelist: [], - blacklist: [], - - // This will remove the currently hooked extensions of .es6 and .js so you'll - // have to add them back if you want them to be used again. - extensions: [".js", ".es6"] -}); -``` - -### Browser - -A browser version of 6to5 is available from `browser.js` inside the 6to5 -directory in an npm release. - -#### Scripts - -While it's not recommended for serious use, when the browser version is included -all scripts with the type `text/ecmascript-6` and `text/6to5` are automatically -compiled and ran. - -For example: - -```html - - -``` - -#### Build - -You can build a browser version of the compiler by running the following in the -6to5 directory: - - $ make build - -This will output the files `dist/6to5.js` and `dist/6to5.min.js`. - -#### API - -```javascript -to5.transform("class Test {}").code; -``` - -#### Test - -To test 6to5 in your browser run: - - $ make test-browser - -And open `test/browser.html` in your browser if it doesn't open automatically. - -## [Modules](MODULES.md) - -See [Modules - Common](MODULES.md#common-default) for documentation on the -default module formatting. - -Alternatively see [Modules](MODULES.md) for all other supported module formatting types. - -## Caveats - -### For-of - -A polyfill is required for for-of functionality that implements `Symbol` and -adds `prototype[Symbol.iterator]` behaviour to built-ins. Using the polyfills -specified in [polyfill](#polyfill) suffices. - -### Classes - -Built-in classes such as `Date`, `Array` and `DOM` cannot be subclassed due to -limitations in ES5 implementations. - -If you're inheriting from a class then static properties are inherited from it -via [\_\_proto\_\_](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/proto), -this is widely supported but you may run into problems with much older browsers. - -**NOTE:** `__proto__` is not supported on IE <= 9 so static properties -**will not** be inherited. A possible workaround is to use `super();`: - -```javascript -class Foo { - static foo() { - - } -} - -class Bar extends Foo { - static foo() { - super(); - } -} -``` - -### Spread - -An [ES6 polyfill](#polyfill) is required in order for spread to work. More -specifically a polyfill for `Array.from`. - -### Generators - -The [regenerator runtime](https://github.com/facebook/regenerator/blob/master/runtime.js) -and an [ES6 polyfill](#polyfill) are required in order for generators to work. - -## Polyfill - -6to5 includes a polyfill that includes the -[regenerator runtime](https://github.com/facebook/regenerator/blob/master/runtime.js) and the -[es6-shim](https://github.com/paulmillr/es6-shim) and -[es6-symbol](https://github.com/medikoo/es6-symbol) polyfills. - -### Node - -```javascript -require("6to5/polyfill"); -``` - -### Browser - -Available from the `browser-polyfill.js` file within the 6to5 directory of an -npm release. - -## Optional runtime - -6to5 has a few helper functions that'll be placed at the top of the generated -code if needed so it's not inlined multiple times throughout that file. This may -become an issue if you have multiple files, especially when you're sending them -to the browser. gzip alleviates most of this concern but it's still not ideal. - -You can tell 6to5 to not place any declarations at the top of your files and -instead just point them to a reference contained within the runtime. - -Simply use the following option if you're using the [Node API](#node-1): - -```javascript -{ - runtime: true -} -``` - -or the following flag if you're using the [CLI](#cli): - - $ 6to5 --runtime - -Then just include the runtime before your generated code. - -### Getting the runtime - -You can get the runtime via either: - - $ 6to5-runtime - -or - -```javascript -require("6to5").runtime(); -``` - -or from an npm release in `runtime.js` from the 6to5 directory. - -### Customising namespace - -You can also customise the runtime namespace by passing an optional namespace -argument: - -```javascript -require("6to5").runtime("myCustomNamespace"); -``` - - $ 6to5-runtime myCustomNamespace - -See [Options - runtime](#options) for documentation on changing the reference in -generated code. - -## React/JSX - -6to5 has built-in support for React v0.12. Tags are automatically transformed to -their equivalent `React.createElement(...)` and `displayName` is automatically -inferred and added to all `React.createClass` calls. - -To disable this behaviour add `react` to your blacklist. - -## Differences - -### Philosophy - -The fundamental concept behind 6to5 is that the generated code must be close as -possible to the original, retaining all the same formatting and readability. - -Many other transpilers are just concerned with making the code work while 6to5 -is concerned with making sure it works **and** is readable at the same time. - -For example, given the following array comprehension: - -```javascript -var seattlers = [for (c of customers) if (c.city == "Seattle") { name: c.name, age: c.age }]; -``` - -is generated to the following with 6to5: - -```javascript -var seattlers = customers.filter(function (c) { - return c.city == "Seattle"; -}).map(function (c) { - return { - name: c.name, - age: c.age - }; -}); -``` - -The following is what Traceur generates: - -```javascript -var seattlers = (function() { - var c; - var $__20 = 0, - $__21 = []; - for (var $__22 = customers[$traceurRuntime.toProperty(Symbol.iterator)](), - $__23; !($__23 = $__22.next()).done; ) { - c = $__23.value; - if (c.city == "Seattle") - $traceurRuntime.setProperty($__21, $__20++, { - name: c.name, - age: c.age - }); - } - return $__21; -}()); -``` - -As you can tell, it's not very pretty, unreadable even. Instead of mapping -directly to a runtime, like other transpilers, 6to5 maps directly to the -equivalent ES5. - -I'm not saying 6to5 is for everyone or even suited for everything. Traceur is -better suited if you'd like a full ES6 environment with polyfills and all. - -### Comparison to other transpilers - -| | 6to5 | Traceur | esnext | es6now | es6-transpiler | jstransform | -| ---------------------------- | ---- | ------- | ------ | ------ | -------------- | ----------- | -| No runtime | ✓ | | | | ✓ | ✓ | -| Source maps | ✓ | ✓ | ✓ | | ✓ | ✓ | -| No compiler global pollution | ✓ | | ✓ | | ✓ | ✓ | -| Arrow functions | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Classes | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Computed property names | ✓ | ✓ | ✓ | ✓ | ✓ | | -| Constants | ✓ | ✓ | | | ✓ | | -| Default parameters | ✓ | ✓ | ✓ | ✓ | ✓ | | -| Destructuring | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| For-of | ✓ | ✓ | ✓ | ✓ | ✓ | | -| Generators | ✓ | ✓ | ✓ | | | | -| Let scoping | ✓ | ✓ | | | ✓ | | -| Modules | ✓ | ✓ | | ✓ | | | -| Property method assignment | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Property name shorthand | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Rest parameters | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Spread | ✓ | ✓ | ✓ | ✓ | ✓ | | -| Template literals | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Unicode regex | ✓ | ✓ | | | ✓ | | - -#### [Traceur](https://github.com/google/traceur-compiler) - -Traceur requires quite a bulky runtime (~75KB) and produces quite verbose code. -While this can be trimmed down by selectively building the runtime, it's an -unneccesary step when a runtime can be eliminated entirely. - -#### [es6now](https://github.com/zenparsing/es6now) - -es6now doesn't output sourcemaps. This is cited as a positive as line-to-line -mapping is the goal. This however obviously doesn't retain column mapping -resulting in the output code not being very pleasant. - -#### [es6-transpiler](https://github.com/termi/es6-transpiler) - -The es6-transpiler compiler requires shims to operate which pollutes the global -scope resulting in possible collisions. - -es6-transpiler maps line-by-line, just like es6now, this results in the same -issues such as lack of column information and unpleasant code output. +For more information view the [documentation](https://github.com/6to5/6to5/tree/master/doc). diff --git a/doc/browser.md b/doc/browser.md new file mode 100644 index 0000000000..3f55b52097 --- /dev/null +++ b/doc/browser.md @@ -0,0 +1,49 @@ +# Browser + +A browser version of 6to5 is available from `browser.js` inside the 6to5 +directory in an npm release. + +## API + +```javascript +to5.transform("class Test {}").code; +``` + +## Scripts + +While it's not recommended for serious use, when the browser version is included +all scripts with the type `text/ecmascript-6` and `text/6to5` are automatically +compiled and ran. + +For example: + +```html + + +``` + +## Build + +You can build a browser version of the compiler by running the following in the +6to5 directory: + + $ make build + +This will output the files `dist/6to5.js` and `dist/6to5.min.js`. + +## Test + +To test 6to5 in your browser run: + + $ make test-browser + +And open `test/browser.html` in your browser if it doesn't open automatically. diff --git a/doc/caveats.md b/doc/caveats.md new file mode 100644 index 0000000000..3c56ac72bf --- /dev/null +++ b/doc/caveats.md @@ -0,0 +1,43 @@ +# Caveats + +## Classes + +Built-in classes such as `Date`, `Array` and `DOM` cannot be subclassed due to +limitations in ES5 implementations. + +If you're inheriting from a class then static properties are inherited from it +via [\_\_proto\_\_](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/proto), +this is widely supported but you may run into problems with much older browsers. + +**NOTE:** `__proto__` is not supported on IE <= 9 so static properties +**will not** be inherited. A possible workaround is to use `super();`: + +```javascript +class Foo { + static foo() { + + } +} + +class Bar extends Foo { + static foo() { + super(); + } +} +``` + +## For-of + +A polyfill is required for for-of functionality that implements `Symbol` and +adds `prototype[Symbol.iterator]` behaviour to built-ins. Using the polyfills +specified in [polyfill](polyfill.md) suffices. + +## Generators + +The [regenerator runtime](https://github.com/facebook/regenerator/blob/master/runtime.js) +and an [ES6 polyfill](polyfill.md) are required in order for generators to work. + +## Spread + +An [ES6 polyfill](polyfill.md) is required in order for spread to work. More +specifically a polyfill for `Array.from`. diff --git a/doc/differences.md b/doc/differences.md new file mode 100644 index 0000000000..360231ba8d --- /dev/null +++ b/doc/differences.md @@ -0,0 +1,99 @@ +# Differences + +## Philosophy + +The fundamental concept behind 6to5 is that the generated code must be close as +possible to the original, retaining all the same formatting and readability. + +Many other transpilers are just concerned with making the code work while 6to5 +is concerned with making sure it works **and** is readable at the same time. + +For example, given the following array comprehension: + +```javascript +var seattlers = [for (c of customers) if (c.city == "Seattle") { name: c.name, age: c.age }]; +``` + +is generated to the following with 6to5: + +```javascript +var seattlers = customers.filter(function (c) { + return c.city == "Seattle"; +}).map(function (c) { + return { + name: c.name, + age: c.age + }; +}); +``` + +The following is what Traceur generates: + +```javascript +var seattlers = (function() { + var c; + var $__20 = 0, + $__21 = []; + for (var $__22 = customers[$traceurRuntime.toProperty(Symbol.iterator)](), + $__23; !($__23 = $__22.next()).done; ) { + c = $__23.value; + if (c.city == "Seattle") + $traceurRuntime.setProperty($__21, $__20++, { + name: c.name, + age: c.age + }); + } + return $__21; +}()); +``` + +As you can tell, it's not very pretty, unreadable even. Instead of mapping +directly to a runtime, like other transpilers, 6to5 maps directly to the +equivalent ES5. + +I'm not saying 6to5 is for everyone or even suited for everything. Traceur is +better suited if you'd like a full ES6 environment with polyfills and all. + +## Comparison to other transpilers + +| | 6to5 | Traceur | esnext | es6now | es6-transpiler | jstransform | +| ---------------------------- | ---- | ------- | ------ | ------ | -------------- | ----------- | +| No runtime | ✓ | | | | ✓ | ✓ | +| Source maps | ✓ | ✓ | ✓ | | ✓ | ✓ | +| No compiler global pollution | ✓ | | ✓ | | ✓ | ✓ | +| Arrow functions | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| Classes | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| Computed property names | ✓ | ✓ | ✓ | ✓ | ✓ | | +| Constants | ✓ | ✓ | | | ✓ | | +| Default parameters | ✓ | ✓ | ✓ | ✓ | ✓ | | +| Destructuring | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| For-of | ✓ | ✓ | ✓ | ✓ | ✓ | | +| Generators | ✓ | ✓ | ✓ | | | | +| Let scoping | ✓ | ✓ | | | ✓ | | +| Modules | ✓ | ✓ | | ✓ | | | +| Property method assignment | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| Property name shorthand | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| Rest parameters | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| Spread | ✓ | ✓ | ✓ | ✓ | ✓ | | +| Template literals | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| Unicode regex | ✓ | ✓ | | | ✓ | | + +### [Traceur](https://github.com/google/traceur-compiler) + +Traceur requires quite a bulky runtime (~75KB) and produces quite verbose code. +While this can be trimmed down by selectively building the runtime, it's an +unneccesary step when a runtime can be eliminated entirely. + +### [es6now](https://github.com/zenparsing/es6now) + +es6now doesn't output sourcemaps. This is cited as a positive as line-to-line +mapping is the goal. This however obviously doesn't retain column mapping +resulting in the output code not being very pleasant. + +### [es6-transpiler](https://github.com/termi/es6-transpiler) + +The es6-transpiler compiler requires shims to operate which pollutes the global +scope resulting in possible collisions. + +es6-transpiler maps line-by-line, just like es6now, this results in the same +issues such as lack of column information and unpleasant code output. diff --git a/FEATURES.md b/doc/features.md similarity index 100% rename from FEATURES.md rename to doc/features.md diff --git a/doc/index.md b/doc/index.md new file mode 100644 index 0000000000..b64ad02273 --- /dev/null +++ b/doc/index.md @@ -0,0 +1,36 @@ +**6to5** turns ES6 code into vanilla ES5, so you can use ES6 features **today.** + + - **Readable** - formatting is retained if possible so your generated code is as similar as possible. + - **Extensible** - with a large range of [plugins](plugins.md) and **browser support**. + - **Lossless** - **source map support** so you can debug your compiled code with ease. + - **Compact** - maps directly to the equivalent ES5 with **no runtime**[\*](caveats.md#generators). + +## Installation + +It's as easy as: + + $ npm install -g 6to5 + +## [Features](features.md) + + - [Array comprehension](features.md#array-comprehension) + - [Async functions](features.md#async-functions) via [regenerator](https://github.com/facebook/regenerator) + - [Arrow functions](features.md#arrow-functions) + - [Classes](features.md#classes) + - [Computed property names](features.md#computed-property-names) + - [Constants](features.md#constants) + - [Default parameters](features.md#default-parameters) + - [Destructuring](features.md#destructuring) + - [For-of](features.md#for-of) + - [Generators](features.md#generators) via [regenerator](https://github.com/facebook/regenerator) + - [Generator comprehension](features.md#generator-comprehension) + - [Let scoping](features.md#let-scoping) + - [Modules](features.md#modules) + - [Numeric literals](features.md#numeric-literals) + - [Property method assignment](features.md#property-method-assignment) + - [Property name shorthand](features.md#property-name-shorthand) + - [React/JSX](react.md) + - [Rest parameters](features.md#rest-parameters) + - [Spread](features.md#spread) + - [Template literals](features.md#template-literals) + - [Unicode regex](features.md#unicode-regex) diff --git a/MODULES.md b/doc/modules.md similarity index 100% rename from MODULES.md rename to doc/modules.md diff --git a/doc/optional-runtime.md b/doc/optional-runtime.md new file mode 100644 index 0000000000..6dd1ca61de --- /dev/null +++ b/doc/optional-runtime.md @@ -0,0 +1,51 @@ +# Optional runtime + +6to5 has a few helper functions that'll be placed at the top of the generated +code if needed so it's not inlined multiple times throughout that file. This may +become an issue if you have multiple files, especially when you're sending them +to the browser. gzip alleviates most of this concern but it's still not ideal. + +You can tell 6to5 to not place any declarations at the top of your files and +instead just point them to a reference contained within the runtime. + +Simply use the following option if you're using the [Node API](usage.md#node): + +```javascript +{ + runtime: true +} +``` + +or the following flag if you're using the [CLI](usage.md#cli): + + $ 6to5 --runtime + +Then just include the runtime before your generated code. + +## Getting the runtime + +You can get the runtime via either: + + $ 6to5-runtime + +or + +```javascript +require("6to5").runtime(); +``` + +or from an npm release in `runtime.js` from the 6to5 directory. + +## Customising namespace + +You can also customise the runtime namespace by passing an optional namespace +argument: + +```javascript +require("6to5").runtime("myCustomNamespace"); +``` + + $ 6to5-runtime myCustomNamespace + +See [Options - runtime](usage.md#options) for documentation on changing the +reference in generated code. diff --git a/doc/plugins.md b/doc/plugins.md new file mode 100644 index 0000000000..da79f7e52e --- /dev/null +++ b/doc/plugins.md @@ -0,0 +1,15 @@ +# Plugins + + - [Broccoli](https://github.com/very-geek/broccoli-6to5-transpiler) + - [Browserify](https://github.com/6to5/6to5-browserify) + - [Brunch](https://github.com/es128/6to5-brunch) + - [Duo](https://github.com/bdo-labs/duo6to5) + - [Connect](https://github.com/6to5/6to5-connect) + - [Gulp](https://github.com/sindresorhus/gulp-6to5) + - [Grunt](https://github.com/sindresorhus/grunt-6to5) + - [Jade](https://github.com/Apoxx/jade-6to5) + - [Jest](https://github.com/6to5/6to5-jest) + - [Karma](https://github.com/shuhei/karma-6to5-preprocessor) + - [Mocha](https://github.com/6to5/6to5-mocha) + - [Rails](https://github.com/6to5/6to5-rails) + - [webpack](https://github.com/Couto/6to5-loader) diff --git a/doc/polyfill.md b/doc/polyfill.md new file mode 100644 index 0000000000..6ae32ef7e4 --- /dev/null +++ b/doc/polyfill.md @@ -0,0 +1,17 @@ +# Polyfill + +6to5 includes a polyfill that includes the +[regenerator runtime](https://github.com/facebook/regenerator/blob/master/runtime.js) and the +[es6-shim](https://github.com/paulmillr/es6-shim) and +[es6-symbol](https://github.com/medikoo/es6-symbol) polyfills. + +## Node + +```javascript +require("6to5/polyfill"); +``` + +## Browser + +Available from the `browser-polyfill.js` file within the 6to5 directory of an +npm release. diff --git a/doc/react.md b/doc/react.md new file mode 100644 index 0000000000..302ce6ccba --- /dev/null +++ b/doc/react.md @@ -0,0 +1,16 @@ +# React/JSX + +6to5 has built-in support for React v0.12. Tags are automatically transformed to +their equivalent `React.createElement(...)` and `displayName` is automatically +inferred and added to all `React.createClass` calls. + +## Blacklist + +To disable this behaviour add `react` to your blacklist: + +```javascript +to5.transform("code", { blacklist: ["react"] }); +``` + + + $ 6to5 --blacklist react diff --git a/doc/usage.md b/doc/usage.md new file mode 100644 index 0000000000..f693262979 --- /dev/null +++ b/doc/usage.md @@ -0,0 +1,149 @@ +# Usage + +## CLI + +Compile the file `script.js` and output it to stdout. + + $ 6to5 script.js + +Compile the file `script.js` and output it to `script-compiled.js`. + + $ 6to5 script.js --out-file script-compiled.js + +Compile the file `script.js` and output it to `script-compiled.js` and save a +source map to `script-compiled.js.map`. + + $ 6to5 script.js --source-maps --out-file script-compiled.js + +Compile the file `script.js` and output it to `script-compiled.js` with a source +map embedded in a comment at the bottom. + + $ 6to5 script.js --source-maps-inline --out-file script-compiled.js + +Compile the entire `src` directory and output it to the `lib` directory. + + $ 6to5 src --out-dir lib + +Compile the entire `src` directory and output it to the one concatenated file. + + $ 6to5 src --out-file script-compiled.js + +Pipe a file in via stdin and output it to `script-compiled.js` + + $ 6to5 --out-file script-compiled.js < script.js + +### Node + +Launch a repl. + + $ 6to5-node + +Evaluate code. + + $ 6to5-node -e "class Test { }" + +Compile and run `test.js`. + + $ 6to5-node test + +## Node + +```javascript +var to5 = require("6to5"); + +var result = to5.transform("code();", options); +result.code; +result.map; +result.ast; + +to5.transformFileSync("filename.js", options).code; + +to5.transformFile("filename.js", options, function (err, result) { + +}); +``` + +#### Options + +```javascript +{ + // Filename for use in errors etc. + // Default: "unknown" + filename: "filename", + + // List of transformers to EXCLUDE. + // Run `6to5 --help` to see a full list of transformers. + blacklist: [], + + // List of transformers to ONLY use. + // Run `6to5 --help` to see a full list of transformers. + whitelist: [], + + // Module formatter to use + // Run `6to5 --help` to see a full list of module formatters. + // Default: "common" + modules: "common", + + // 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. + // Default: false + sourceMap: true, + + // Set `file` on returned source map. + // Default: `filename` option. + sourceMapName: "filename", + + // Set `sources[0]` on returned source map. + // Default: `filename` option. + sourceFileName: "filename", + + // Optionally replace all 6to5 helper declarations with a referenece to this + // variable. If set to `true` then the default namespace is used "to5Runtime". + // Default: false + runtime: true +} +``` + +### Require hook + +All subsequent files required by node with the extensions `.es6` and `.js` will +be transformed by 6to5. The polyfill specified in [Polyfill](polyfill.md) is +also required. + +```javascript +require("6to5/register"); +``` + +**NOTE:** By default all requires to `node_modules` will be ignored. You can +override this by passing an ignore regex via: + +```javascript +require("6to5/register")({ + // This will override `node_modules` ignoring - you can alternatively pass + // a regex + ignore: false +}); +``` + +#### Options + +```javascript +require("6to5/register")({ + // Optional ignore regex - if any filenames **do** match this regex then they + // aren't compiled + ignore: /regex/, + + // Optional only regex - if any filenames **don't** match this regex then they + // aren't compiled + only: /my_es6_folder/, + + // See options above for usage + whitelist: [], + blacklist: [], + + // This will remove the currently hooked extensions of .es6 and .js so you'll + // have to add them back if you want them to be used again. + extensions: [".js", ".es6"] +}); +```