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

docs: setting up babel, fixes regeneratorRuntime not defined #7701

Merged
merged 11 commits into from Jan 26, 2019
1 change: 1 addition & 0 deletions CHANGELOG.md
Expand Up @@ -171,6 +171,7 @@
- `[diff-sequences]` Add performance benchmark to package ([#7603](https://github.com/facebook/jest/pull/7603))
- `[*]` Replace as many `Object.assign` with object spread as possible ([#7627](https://github.com/facebook/jest/pull/7627))
- `[ci]` Initial support for Azure Pipelines ([#7556](https://github.com/facebook/jest/pull/7556))
- `[docs]` Changed Babel setup documentation to fix `async/await` ([#7701](https://github.com/facebook/jest/pull/7701))
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

After merging in master, please move up to correct section


### Performance

Expand Down
60 changes: 47 additions & 13 deletions docs/GettingStarted.md
Expand Up @@ -81,31 +81,65 @@ jest --init

### Using Babel

To use [Babel](http://babeljs.io/), install the `babel-jest` and `@babel/core` packages via `yarn`:
To use [Babel](http://babeljs.io/), install required dependencies via `yarn`:

```bash
yarn add --dev babel-jest @babel/core
yarn add --dev babel-jest @babel/core @babel/preset-env @babel/preset-react
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you don't need either of the presets - the other 2 are actually needed, though. Not sure how to best say that, and still have useful examples

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well you'd probably want to include something, at the very least you probably want to compile ES6 modules.

I think our bases are pretty well covered by "The ideal configuration for Babel will depend on your project.".

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We assume user already have Babel set up in the project and they only want to add Jest support, hence only babel-jest and @babel/core are needed. They need to be at top level of node_modules to satisfy peerDependencies and transform resolver

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

for babel 7, people are required to use @babel/core. So if we go with the assumption babel is correctly set up, we just need to add babel-jest

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it's sane to assume that Babel is there and we should make it obvious in the guide. We can't choose Babel plugins and presets for users, that's bad.

So, only adding babel-jest should suffice. We just need to make sure users have Babel 7 already set up.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well I do think no instructions would be better than not working instructions 😆.

If it was up to me I'd remove the React preset from these instructions, but otherwise leave them as is.

```

Don't forget to add a [`babel.config.js`](https://babeljs.io/docs/en/config-files) file in your project's root folder. For example, if you are using ES2018 and [React](https://reactjs.org) with the [`@babel/preset-env`](https://babeljs.io/docs/en/babel-preset-env) and [`@babel/preset-react`](https://babeljs.io/docs/en/babel-preset-react) presets:
Configure Babel to target your current version of Node by creating a `babel.config.js` file in the root of your project:

```js
```javascript
// babel.config.js
module.exports = {
presets: ['@babel/preset-env', '@babel/preset-react'],
presets: [
[
'@babel/preset-env',
{
targets: {
node: 'current',
},
},
],
'@babel/preset-react',
],
};
```

You are now set up to use all ES2018 features and React-specific syntax.
If you are not using React you can exclude `@babel/preset-react` from the above commands/config.

The ideal configuration for Babel will depend on your project. See [Babel's docs](https://babeljs.io/docs/en/babel-preset-env) for more details.

Jest will set `process.env.NODE_ENV` to 'test' if it's not set to something else, you can use that in your configuration to conditionally setup only the compilation needed for Jest, e.g.
DylanVann marked this conversation as resolved.
Show resolved Hide resolved

```javascript
// babel.config.js
module.exports =
SimenB marked this conversation as resolved.
Show resolved Hide resolved
process.env.NODE_ENV === 'test'
? {
presets: [
[
'@babel/preset-env',
{
targets: {
node: 'current',
},
},
],
],
}
: {
// Configuration needed for production.
};
```

> Note: `babel-jest` is automatically installed when installing Jest and will automatically transform files if a babel configuration exists in your project. To avoid this behavior, you can explicitly reset the `transform` configuration option:

```json
// package.json
{
"jest": {
"transform": {}
}
}
```javascript
DylanVann marked this conversation as resolved.
Show resolved Hide resolved
// jest.config.js
module.exports = {
transform: {},
};
```

#### Babel 6
Expand Down