Skip to content

Commit 5a6ba1f

Browse files
skipjackskipjack
authored
docs(guides): populate the integrations guide (#1465)
Ideally these will be short, concise sections with the goal of quickly giving readers a rough idea of what the integration may look like and then sending them over to the actual repository for more detail. I think we should be careful getting too bogged down in this page seeing as most webpack users likely won't need these integrations (you can get pretty far with just webpack and npm). Resolves #53
1 parent cddc142 commit 5a6ba1f

File tree

1 file changed

+110
-10
lines changed

1 file changed

+110
-10
lines changed

‎content/guides/integrations.md

Lines changed: 110 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -5,24 +5,124 @@ contributors:
55
- pksjce
66
- bebraw
77
- tashian
8+
- skipjack
89
---
910

10-
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.
11+
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.
1112

12-
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.
13+
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.
1314

14-
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.
15+
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.
1516

16-
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.
1717

18-
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.
18+
## NPM Scripts
1919

20-
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.
20+
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.
2121

22-
?> Grunt
22+
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.
2323

24-
?> Gulp
2524

26-
?> Mocha
25+
## Grunt
2726

28-
?> Karma
27+
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:
28+
29+
``` bash
30+
npm i --save-dev grunt-webpack webpack
31+
```
32+
33+
Then register a configuration and load the task:
34+
35+
__Gruntfile.js__
36+
37+
``` js
38+
const webpackConfig = require('./webpack.config.js');
39+
40+
module.exports = function(grunt) {
41+
grunt.initConfig({
42+
webpack: {
43+
options: {
44+
stats: !process.env.NODE_ENV || process.env.NODE_ENV === 'development'
45+
},
46+
prod: webpackConfig,
47+
dev: Object.assign({ watch: true }, webpackConfig)
48+
}
49+
});
50+
51+
grunt.loadNpmTasks('grunt-webpack');
52+
};
53+
```
54+
55+
For more information, please visit the [repository](https://github.com/webpack-contrib/grunt-webpack).
56+
57+
58+
## Gulp
59+
60+
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`:
61+
62+
``` bash
63+
npm i --save-dev webpack-stream
64+
```
65+
66+
Just `require('webpack-stream')` instead of `webpack` and optionally pass it an configuration:
67+
68+
__gulpfile.js__
69+
70+
``` js
71+
var gulp = require('gulp');
72+
var webpack = require('webpack-stream');
73+
gulp.task('default', function() {
74+
return gulp.src('src/entry.js')
75+
.pipe(webpack({
76+
// Any configuration options...
77+
}))
78+
.pipe(gulp.dest('dist/'));
79+
});
80+
```
81+
82+
For more information, please visit the [repository](https://github.com/shama/webpack-stream).
83+
84+
85+
## Mocha
86+
87+
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`):
88+
89+
``` bash
90+
npm i --save-dev webpack mocha mocha-webpack
91+
mocha-webpack 'test/**/*.js'
92+
```
93+
94+
For more information, please visit the [repository](https://github.com/zinserjan/mocha-webpack).
95+
96+
97+
## Karma
98+
99+
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:
100+
101+
``` bash
102+
npm i --save-dev webpack karma karma-webpack
103+
```
104+
105+
__karma.conf.js__
106+
107+
``` js
108+
module.exports = function(config) {
109+
config.set({
110+
files: [
111+
{ pattern: 'test/*_test.js', watched: false },
112+
{ pattern: 'test/**/*_test.js', watched: false }
113+
],
114+
preprocessors: {
115+
'test/*_test.js': [ 'webpack' ],
116+
'test/**/*_test.js': [ 'webpack' ]
117+
},
118+
webpack: {
119+
// Any custom webpack configuration...
120+
},
121+
webpackMiddleware: {
122+
// Any custom webpack-dev-middleware configuration...
123+
}
124+
});
125+
};
126+
```
127+
128+
For more information, please visit the [repository](https://github.com/webpack-contrib/karma-webpack).

0 commit comments

Comments
 (0)