Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

add 6.x versioned docs #1574

Merged
merged 1 commit into from
Feb 13, 2018
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 28 additions & 0 deletions website/pages/en/versions.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
const React = require("react");

const CompLibrary = require("../../core/CompLibrary.js");
const Container = CompLibrary.Container;

const CWD = process.cwd();
const siteConfig = require(CWD + "/siteConfig.js");
// const versions = require(CWD + "/versions.json");

class Versions extends React.Component {
render() {
return (
<div className="pageContainer">
<Container className="mainContainer">
<h1>Babel Versions</h1>
<div><a href={`${siteConfig.baseUrl}docs/en/next/index.html`}>Master Docs</a></div>
<div><a href={`${siteConfig.baseUrl}docs/en/index.html`}>6.x Docs</a></div>
</Container>
</div>
);
}
}

Versions.defaultProps = {
language: "en",
};

module.exports = Versions;
10 changes: 10 additions & 0 deletions website/versioned_docs/version-6.x/babel.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
---
# Don't edit this file directly, it was copied using scripts/download-readmes.js:
id: version-6.x-babel
title: babel
sidebar_label: babel
original_id: babel
---

Currently unused in 6.x. You probably meant to use `babel-cli`.

94 changes: 94 additions & 0 deletions website/versioned_docs/version-6.x/babelrc.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,94 @@
---
layout: docs
title: .babelrc
description: How to use the .babelrc
permalink: /docs/usage/babelrc/
:
id: version-6.x-babelrc
original_id: babelrc
---

All Babel API [options](api.md) except the callbacks are allowed (because `.babelrc` files are serialized as [JSON5](https://github.com/json5/json5)).

**Example:**

```json
{
"plugins": ["transform-react-jsx"],
"ignore": [
"foo.js",
"bar/**/*.js"
]
}
```

## Use via `package.json`

You can alternatively choose to specify your `.babelrc` config from within `package.json` like so:

```json
{
"name": "my-package",
"version": "1.0.0",
"babel": {
// my babel config here
}
}
```

## `env` option

You can use the `env` option to set specific options when in a certain environment:

```json
{
"env": {
"production": {
"plugins": ["transform-react-constant-elements"]
}
}
}
```

Options specific to a certain environment are merged into and overwrite non-env specific options.

The `env` key will be taken from `process.env.BABEL_ENV`, when this is not available then it uses
`process.env.NODE_ENV` if even that is not available then it defaults to `"development"`.

You can set this environment variable with the following:

**Unix**

At the start of a command:

```sh
BABEL_ENV=production YOUR_COMMAND_HERE
```

Or as a separate command:

```sh
export BABEL_ENV=production
```

```sh
YOUR_COMMAND_HERE
```

**Windows**

```sh
SET BABEL_ENV=production
```

```sh
YOUR_COMMAND_HERE
```

> If you want your command to work across platforms, you can use [`cross-env`](https://www.npmjs.com/package/cross-env)

## Lookup behavior

Babel will look for a `.babelrc` in the current directory of the file being transpiled. If one does not exist, it will travel up the directory tree until it finds either a `.babelrc`, or a `package.json` with a `"babel": {}` hash within.

Use `"babelrc": false` in [options](api.md#options) to stop lookup behavior, or provide the [`--no-babelrc` CLI flag](babel-cli.md#babel-ignoring-babelrc).
139 changes: 139 additions & 0 deletions website/versioned_docs/version-6.x/babylon.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,139 @@
---
# Don't edit this file directly, it was copied using scripts/download-readmes.js:
id: version-6.x-babylon
title: babylon
sidebar_label: babylon
original_id: babylon
---

<p align="center">
Babylon is a JavaScript parser used in <a href="https://github.com/babel/babel">Babel</a>.
</p>

<p align="center">
<a href="https://travis-ci.org/babel/babylon"><img alt="Travis Status" src="https://img.shields.io/travis/babel/babylon/master.svg?style=flat&label=travis"></a>
<a href="https://codecov.io/gh/babel/babylon"><img alt="Codecov Status" src="https://img.shields.io/codecov/c/github/babel/babylon/master.svg?style=flat"></a>
</p>

- The latest ECMAScript version enabled by default (ES2017).
- Comment attachment.
- Support for JSX and Flow.
- Support for experimental language proposals (accepting PRs for anything at least [stage-0](https://github.com/tc39/proposals/blob/master/stage-0-proposals.md)).

## Credits

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).

Significant diversions are expected to occur in the future such as streaming, EBNF definitions, sweet.js integration, interspatial parsing and more.

## API

### `babylon.parse(code, [options])`

### `babylon.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.

- **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
either `"script"` or `"module"`.

- **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

### Output

Babylon 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][] with the addition of one node type:

- `JSXText`

[Babel AST format]: https://github.com/babel/babylon/blob/master/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/babylon/blob/master/ast/spec.md#stringliteral
[NumericLiteral]: https://github.com/babel/babylon/blob/master/ast/spec.md#numericliteral
[BooleanLiteral]: https://github.com/babel/babylon/blob/master/ast/spec.md#booleanliteral
[NullLiteral]: https://github.com/babel/babylon/blob/master/ast/spec.md#nullliteral
[RegExpLiteral]: https://github.com/babel/babylon/blob/master/ast/spec.md#regexpliteral
[ObjectProperty]: https://github.com/babel/babylon/blob/master/ast/spec.md#objectproperty
[ObjectMethod]: https://github.com/babel/babylon/blob/master/ast/spec.md#objectmethod
[ClassMethod]: https://github.com/babel/babylon/blob/master/ast/spec.md#classmethod
[Program]: https://github.com/babel/babylon/blob/master/ast/spec.md#programs
[BlockStatement]: https://github.com/babel/babylon/blob/master/ast/spec.md#blockstatement
[Directive]: https://github.com/babel/babylon/blob/master/ast/spec.md#directive
[DirectiveLiteral]: https://github.com/babel/babylon/blob/master/ast/spec.md#directiveliteral
[FunctionExpression]: https://github.com/babel/babylon/blob/master/ast/spec.md#functionexpression

[Facebook JSX AST]: https://github.com/facebook/jsx/blob/master/AST.md

### Semver

Babylon 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("babylon").parse("code", {
// parse in strict mode and allow module declarations
sourceType: "module",

plugins: [
// enable jsx and flow syntax
"jsx",
"flow"
]
});
```

### Plugins

- `estree`
- `jsx`
- `flow`
- `doExpressions`
- `objectRestSpread`
- `decorators` (Based on an outdated version of the Decorators proposal. Will be removed in a future version of `Babylon`)
- `classProperties`
- `exportExtensions`
- `asyncGenerators`
- `functionBind`
- `functionSent`
- `dynamicImport`
- `templateInvalidEscapes`

67 changes: 67 additions & 0 deletions website/versioned_docs/version-6.x/caveats.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
---
layout: docs
title: Caveats
description: Just some things to keep in mind when using Babel.
permalink: /docs/usage/caveats/
:
id: version-6.x-caveats
original_id: caveats
---

## Polyfills

In order for certain features to work they require certain polyfills. You can satisfy **all**
Babel feature requirements by using [babel-polyfill](polyfill.md).

You may alternatively/selectively include what you need:

| Feature | Requirements |
| --------------------------- | ------------------------------------------------------------------------------------- |
| Async functions, Generators | [regenerator runtime](https://github.com/facebook/regenerator/tree/master/packages/regenerator-runtime) |
| Array destructuring, For Of | `Symbol`, `prototype[Symbol.iterator]` |
| Spread | `Array.from` |

There is also the `loose` option for some of these plugins.

## Classes

Built-in classes such as `Date`, `Array`, `DOM` etc cannot be properly subclassed
due to limitations in ES5 (for the [es2015-classes](plugin-transform-es2015-classes.md) plugin).
You can try to use [babel-plugin-transform-builtin-extend](https://github.com/loganfsmyth/babel-plugin-transform-builtin-extend) based on `Object.setPrototypeOf` and `Reflect.construct`, but it also has some limitations.

## ES5

Since Babel assumes that your code will run in an ES5 environment it uses ES5
functions. So if you're using an environment that has limited or no support for
ES5 such as lower versions of IE then using [babel-polyfill](polyfill.md) will add support for these methods.

## Internet Explorer

### Classes (10 and below)

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 <= 10 so static properties
**will not** be inherited. See the
[protoToAssign](plugin-transform-proto-to-assign.md) for a possible work
around.

For classes that have `super`s, the super class won't resolve correctly. You can
get around this by enabling the `loose` option in the [es2015-classes](plugin-transform-es2015-classes.md) plugin.

### Getters/setters (8 and below)

In IE8 `Object.defineProperty` can only be used on DOM objects. This is
unfortunate as it's required to set getters and setters. Due to this if
you plan on supporting IE8 or below then the usage of getters and setters
isn't recommended.

**Reference**: [MDN](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Object/defineProperty#Internet_Explorer_8_specific_notes).

#### Modules

By default, when using modules with Babel a non-enumerable `__esModule` property
is exported. This is done through the use of `Object.defineProperty` which is
unsupported in IE8 and below. A workaround for this is to enable the `loose` option in your corresponding module plugin.
Loading