diff --git a/content/guides/integrations.md b/content/guides/integrations.md index b82a0718dcc6..26fddf406688 100644 --- a/content/guides/integrations.md +++ b/content/guides/integrations.md @@ -5,24 +5,124 @@ contributors: - pksjce - bebraw - tashian + - skipjack --- -webpack is a module bundler, like Browserify or Brunch. It is not a task runner. Make, Grunt, or Gulp are task runners. But people get confused about the difference, so let's clear that up right away. +Let's start by clearing up a common misconception. webpack is a module bundler like [Browserify](http://browserify.org/) or [Brunch](http://brunch.io/). It is _not a task runner_ like [Make](https://www.gnu.org/software/make/), [Grunt](https://gruntjs.com/), or [Gulp](https://gulpjs.com/). Task runners handle automation of common development tasks such as linting, building, or testing your project. Compared to bundlers, task runners have a higher level focus. You can still benefit from their higher level tooling while leaving the problem of bundling to webpack. -Task runners handle automation of common development tasks such as linting, building, or testing your project. Compared to bundlers, task runners have a higher level focus. +Bundlers help you get your JavaScript and stylesheets ready for deployment, transforming them into a format that's suitable for the browser. For example, JavaScript can be [minified](/plugins/uglifyjs-webpack-plugin) or [split into chunks](/guides/code-splitting) and [lazy-loaded](/guides/lazy-loading) to improve performance. Bundling is one of the most important challenges in web development, and solving it well can remove a lot of pain from the process. -Bundlers help you get your JavaScript and stylesheets ready for deployment, transforming them into a format that's suitable for the browser. For example, JavaScript can be minified or split into chunks and loaded on-demand to improve performance. Bundling is one of the most important challenges in web development, and solving it well can remove a lot of pain from the process. +The good news is that, while there is some overlap, task runners and bundlers can play well together if approached in the right way. This guide provides a high-level overview of how webpack can be integrated into some of the more popular task runners. -webpack can work alongside task runners. You can still benefit from their higher level tooling while leaving the problem of bundling to webpack. [grunt-webpack](https://www.npmjs.com/package/grunt-webpack) and [gulp-webpack](https://www.npmjs.com/package/gulp-webpack) are good examples. -T> Often webpack users use npm `scripts` as their task runner. This is a good starting point. Cross-platform support can become a problem, but there are several workarounds for that. +## NPM Scripts -T> Even though webpack core focuses on bundling, you can find a variety of extensions that allow you to use it in a task runner kind of way. +Often webpack users use npm [`scripts`](https://docs.npmjs.com/misc/scripts) as their task runner. This is a good starting point. Cross-platform support can become a problem, but there are several workarounds for that. Many, if not most users, get by with simple npm `scripts` and various levels of webpack configuration and tooling. -?> Grunt +So while webpack's core focus is bundling, there are a variety of extensions that can enable you to use it for jobs typical of a task runner. Integrating a separate tool adds complexity, so be sure to weigh the pros and cons before going forward. -?> Gulp -?> Mocha +## Grunt -?> Karma +For those using Grunt, we recommend the [`grunt-webpack`](https://www.npmjs.com/package/grunt-webpack) package. With `grunt-webpack` you can run webpack or [webpack-dev-server](https://github.com/webpack/webpack-dev-server) as a task, get access to stats within [template tags](https://gruntjs.com/api/grunt.template), split development and production configurations and more. Start by installing `grunt-webpack` as well as `webpack` itself if you haven't already: + +``` bash +npm i --save-dev grunt-webpack webpack +``` + +Then register a configuration and load the task: + +__Gruntfile.js__ + +``` js +const webpackConfig = require('./webpack.config.js'); + +module.exports = function(grunt) { + grunt.initConfig({ + webpack: { + options: { + stats: !process.env.NODE_ENV || process.env.NODE_ENV === 'development' + }, + prod: webpackConfig, + dev: Object.assign({ watch: true }, webpackConfig) + } + }); + + grunt.loadNpmTasks('grunt-webpack'); +}; +``` + +For more information, please visit the [repository](https://github.com/webpack-contrib/grunt-webpack). + + +## Gulp + +Gulp is also a fairly straightforward integration with the help of the [`webpack-stream`](https://github.com/shama/webpack-stream) package (a.k.a. `gulp-webpack`). In this case, it is unnecessary to install `webpack` separately as it is a direct dependency of `webpack-stream`: + +``` bash +npm i --save-dev webpack-stream +``` + +Just `require('webpack-stream')` instead of `webpack` and optionally pass it an configuration: + +__gulpfile.js__ + +``` js +var gulp = require('gulp'); +var webpack = require('webpack-stream'); +gulp.task('default', function() { + return gulp.src('src/entry.js') + .pipe(webpack({ + // Any configuration options... + })) + .pipe(gulp.dest('dist/')); +}); +``` + +For more information, please visit the [repository](https://github.com/shama/webpack-stream). + + +## Mocha + +The [`mocha-webpack`](https://github.com/zinserjan/mocha-webpack) utility can be used for a clean integration with Mocha. The repository offers more details on the pros and cons but essentially `mocha-webpack` is a simple wrapper that provides almost the same CLI as Mocha itself and provides various webpack functionality like an improved watch mode and improved path resolution. Here is a small example of how you would install it and use it to run a test suite (found within `./test`): + +``` bash +npm i --save-dev webpack mocha mocha-webpack +mocha-webpack 'test/**/*.js' +``` + +For more information, please visit the [repository](https://github.com/zinserjan/mocha-webpack). + + +## Karma + +The [`karma-webpack`](https://github.com/webpack-contrib/karma-webpack) package allows you to use webpack to pre-process files in [Karma](http://karma-runner.github.io/1.0/index.html). It also makes use of [`webpack-dev-middleware`](https://github.com/webpack/webpack-dev-middleware) and allows passing configurations for both. A simple example may look something like this: + +``` bash +npm i --save-dev webpack karma karma-webpack +``` + +__karma.conf.js__ + +``` js +module.exports = function(config) { + config.set({ + files: [ + { pattern: 'test/*_test.js', watched: false }, + { pattern: 'test/**/*_test.js', watched: false } + ], + preprocessors: { + 'test/*_test.js': [ 'webpack' ], + 'test/**/*_test.js': [ 'webpack' ] + }, + webpack: { + // Any custom webpack configuration... + }, + webpackMiddleware: { + // Any custom webpack-dev-middleware configuration... + } + }); +}; +``` + +For more information, please visit the [repository](https://github.com/webpack-contrib/karma-webpack).