From bcda7537dda7eeb38bef3405e1265226ba6d69ae Mon Sep 17 00:00:00 2001
From: James Talmage <james@talmage.io>
Date: Mon, 4 Apr 2016 00:33:25 -0400
Subject: [PATCH] Add a recipe for properly configuring babel when using
 `.babelrc`.

---
 docs/recipes/babelrc.md | 86 +++++++++++++++++++++++++++++++++++++++++
 readme.md               |  3 ++
 2 files changed, 89 insertions(+)
 create mode 100644 docs/recipes/babelrc.md

diff --git a/docs/recipes/babelrc.md b/docs/recipes/babelrc.md
new file mode 100644
index 000000000..4f9cf2e18
--- /dev/null
+++ b/docs/recipes/babelrc.md
@@ -0,0 +1,86 @@
+# Configuring Babel
+
+There are multiple options for configuring how AVA transpiles your tests using Babel.
+
+ - [Specify a complete config in `package.json`](#specify-a-complete-config-in-packagejson)
+ - [Extend existing `.babelrc` without modification](#extend-existing-babelrc-without-modification)
+ - [Extend existing `.babelrc` with additional plugins or presets](#extend-existing-babelrc-with-additional-plugins-or-presets)
+ - [Extend an alternate config file (i.e. not `.babelrc`)](#extend-alternate-config-file)
+ - [Notes](#notes)
+
+## Specify a complete config in `package.json`
+
+The `babelrc` option defaults to `false`, meaning `.babelrc` files are not considered when transpiling tests. This means you must specify your complete config in `package.json`.
+
+```json
+{
+  "ava": {
+    "babel": {
+      "plugins": ["rewire"],
+      "presets": ["es2015"]
+    }
+  }
+}
+```
+
+## Extend existing `.babelrc` without modification
+
+Use the `"inherit"` shortcut if you want your tests transpiled the same as your sources. This will use your `.babelrc` directly (with a few additional [internal plugins](#notes)).
+
+`package.json`:
+
+```json
+{
+ "ava": {
+   "babel": "inherit"
+ }
+}
+```
+
+## Extend existing `.babelrc` with additional plugins or presets
+
+Set `babelrc` to `true`. This will use your `.babelrc` and extend it with any additional plugins specified.
+
+`package.json`:
+
+```json
+{
+  "ava": {
+    "babel": {
+      "babelrc": true,
+      "plugins": ["custom-plugin-name"],
+      "presets": ["custom-preset"]
+    }
+  }
+}
+```
+
+## Extend alternate config file.
+
+
+If, for some reason, you do not want to extend `.babelrc`, set the `extends` option to the alternate config you want to use during testing.
+
+`package.json`:
+
+```json
+{
+  "ava": {
+    "babel": {
+      "extends": "./babel-test-config.json",
+      "plugins": ["custom-plugin-name"],
+      "presets": ["custom-preset"]
+    }
+  }
+}
+```
+
+The above uses `babel-test-config.json` as the base config, and extends it with the custom plugins and presets specified.
+
+## Notes
+
+AVA *always* adds a few custom Babel plugins when transpiling your plugins. They serve a variety of functions:
+
+ * Enable `power-assert` support.
+ * Rewrite require paths internal AVA dependencies like `babel-runtime` (important if you are still using `npm@2`).
+ * Generate test metadata to determine which files should be run first (*future*).
+ * Static analysis of dependencies for precompilation (*future*).
diff --git a/readme.md b/readme.md
index 84f520e45..80b5072ef 100644
--- a/readme.md
+++ b/readme.md
@@ -581,6 +581,8 @@ You can also use the special `"inherit"` keyword. This makes AVA defer to the Ba
 }
 ```
 
+See AVA's [`.babelrc` recipe](docs/recipes/babelrc.md) for further examples and a more detailed explanation of configuration options.
+
 Note that AVA will *always* apply the [`espower`](https://github.com/power-assert-js/babel-plugin-espower) and [`transform-runtime`](https://babeljs.io/docs/plugins/transform-runtime/) plugins.
 
 ### TypeScript support
@@ -916,6 +918,7 @@ It's the [Andromeda galaxy](https://simple.wikipedia.org/wiki/Andromeda_galaxy).
 - [When to use `t.plan()`](docs/recipes/when-to-use-plan.md)
 - [Browser testing](docs/recipes/browser-testing.md)
 - [TypeScript](docs/recipes/typescript.md)
+- [Configuring Babel](docs/recipes/babelrc.md)
 
 ## Support