Add recipe for precompiling source files with webpack (#1212)

Author: danny-andrews

docs/recipes/precompiling-with-webpack.md

@@ -0,0 +1,29 @@
+## Precompiling source files with webpack
+
+The AVA [readme](https://github.com/avajs/ava#transpiling-imported-modules) mentions precompiling your imported modules as an alternative to runtime compilation, but it doesn't explain how. This recipe shows how to do this using webpack. (This example uses webpack 2.0)
+
+###### webpack.config.js
+
+```js
+const nodeExternals = require('webpack-node-externals');
+
+module.exports = {
+	entry: ['src/tests.js'],
+	target: 'node',
+	output: {
+		path: '_build',
+		filename: 'tests.js'
+	},
+	externals: nodeExternals,
+	module: {
+		rules: [{
+				test: /\.(js|jsx)$/,
+				use: 'babel-loader'
+		}]
+	}
+};
+```
+
+The important bits are `target: 'node'`, which ignores Node.js-specific `require`s (e.g. `fs`, `path`, etc.) and `externals: nodeModules` which prevents webpack from trying to bundle external Node.js modules which it may choke on.
+
+You can now run `$ ava _build/tests.js` to run the tests contained in this output.

readme.md

@@ -743,7 +743,7 @@ AVA currently only transpiles the tests you ask it to run, as well as test helpe
 
 If you use Babel you can use its [require hook](https://babeljs.io/docs/usage/require/) to transpile imported modules on-the-fly. To add it, [configure it in your `package.json`](#configuration).
 
-You can also transpile your modules in a separate process and refer to the transpiled files rather than the sources from your tests.
+You can also transpile your modules in a separate process and refer to the transpiled files rather than the sources from your tests. Example [here](docs/recipes/precompiling-with-webpack.md).
 
 ### Promise support
 
@@ -1137,6 +1137,7 @@ It's the [Andromeda galaxy](https://simple.wikipedia.org/wiki/Andromeda_galaxy).
 - [JSPM and SystemJS](docs/recipes/jspm-systemjs.md)
 - [Debugging tests with Chrome DevTools](docs/recipes/debugging-with-chrome-devtools.md)
 - [Debugging tests with WebStorm](docs/recipes/debugging-with-webstorm.md)
+- [Precompiling source files with webpack](docs/recipes/precompiling-with-webpack.md)
 
 ## Support