There are a couple options for bundlers, but the popularity contest is largely being won by Webpack. There is some notoriety around Webpack, mostly due to the ability to create monstrous configurations for complex builds. However, Webpack itself is fairly straightforward, and this post will walk through the basic setup and configuration.
In a hurry? The final product of this guide can be found in my basic-webpack-no-loaders repository.
The simplest usage of Webpack is very easy. Let’s get a basic project started.
Don’t forget to reference the Webpack documentation for more details, and to explore the options that Webpack provides!
You need to have Node.js installed.
For Linux and MacOS, the easiest way to install and work with Node is using nvm. Instructions for installing are on the nvm project page.
If using Windows, you can download an installer from the Node.js website.
The instructions are the same for Webpack in Windows, except you may need to use backslashes instead of slashes for paths on the command line. For example,
webpack src/main.js public/bundle.jsmight need to be
webpack src\main.js public\bundle.jsin Windows.
You can of course use Yarn instead of npm for all the command below. Just remember to use
yarn add -D <package>instead of
npm install -D <package>.
Make a new folder for your project (I’m using
basic-webpack). Then open this folder in a terminal.
npm init. It will prompt you for project details, but you can just hit enter for each option to use the default. In a real project, you would probably want to fill in actual details.
npm install -D webpack. This will install Webpack as a development dependency.
Let’s add some source code modules that we want to bundle!
src/ folder in your project, and then create a
src/foo.js file. Add the following to the file:
Then create a
src/main.js file, with this content:
Now we can see that main.js is reliant on foo.js. Now we need to create a bundle, which is a single file with all the code in it, neatly packaged to be used in the browser.
The simplest way to use Webpack is from the command line. Webpack, like most runnable npm modules, can be installed globally so that you could just run
webpack <options> directly. However, the best practice is to install locally to the project. So then to run Webpack, we either need to use
./node_modules/.bin/webpack OR we can setup an npm script. We will be doing the latter.
package.json file (which was created by
npm init above), add a line under the scripts property like this:
Now we can run Webpack with
npm run webpack -- <options>.
Webpack runs on the command line with the form
webpack <entry> <output>. We want to output our bundle to
src/main.js is our entry file.
npm run webpack -- src/main.js public/bundle.js. (It will create the
public/ folder automatically if it doesn’t exist.)
That’s it! That’s all there is to running Webpack in it’s most basic form. You can change your
package.json file to include the Weback command option so that you can just run
npm run webpack. Change the line
"webpack": "webpack", to be
"webpack": "webpack src/main.js public/bundle.js",.
However, this isn’t the standard way to use Webpack. There are a couple missing features which we usually want. You can actually do most of this from the command line, but the recommended path is to use a Webpack config file.
If you changed your
package.json file to include the paths in the Webpack script command, revert that change so that it’s just:
Now create a
webpack.config.js file in the project root, with these contents:
This is the bare basics to do the same thing as the command line. While it is a bit more verbose, it also is fairly clear.
Now you can run
npm run webpack, and it will automatically find the config file (we used the default name) and build the bundle.
Webpack comes with some built-in development and production tool which can be enabled with command line options. Edit scripts in
package.json again to be like:
Now we can do a production build with
npm run build. For development, we can run
npm run dev, and it will re-compile any time a file changes which will affect the bundle.
-p are shortcut options.
-d enables sourcemaps and turns on debug mode for loaders (more on loaders later).
-p sets the
NODE_ENV environment variable to “production” and replaces usages of process.env.NODE_ENV with ‘“production”‘ in your code.
-p also turns on UglifyJSPlugin, which does minification and dead-code removal. With these two combined, code such as the following will be removed in production builds:
The sourcemaps are not generated as a separate file by default. You can choose a different sourcemap output with a setting in the webpack config file. Webpack devtool documentation.
In the basic-webpack-no-loaders repo, you can run
checkout basic-production-ready to see the code as it should be if you followed along.
A quick look at what we have:
- We can put ES module and CommonJS module source files in
src/, and also include modules from
node_modules/installed with npm or Yarn.
- We can do a development build on change with
npm run dev, and we can create a production-ready bundle with
npm run build.
Our next step is to make the developer experience (DX) even better, by setting up webpack-dev-server.
Webpack-dev-server does two things: It acts as a static file server (by default), and it watches and bundles your source with some added code which will refresh your browser page when the source changes and the bundle is rebuilt.
Install webpack-dev-server with
npm install webpack-dev-server.
Next add a start script to
If we had an
index.html file in our project root, and it used a script with a source that pointed to
/bundle.js, then we could just run
npm start and serve that. However, we don’t really want our app to serve from the project root, we want to serve from the
public/ folder. Let’s add a bit of configuration to
The https setting is optional. These days HTTPS is strongly preferred for all websites. This option will set the dev server to automatically create a self-signed cert, and open the page via with https. You can also set a cert, key, and ca file. Check the devServer documentation for instructions.
public/index.html, and put this content in it:
That’s all we need, but to give us a slightly better first look, lets update
src/foo.js to modify the html:
Now with these changes, run
npm start. This should open a new page in your browser with the above html.
Since it will be using a self-signed cert, you will need to click through the “Advanced” option to allow it. In Chrome, you click “Proceed to
(unsafe)”, and in Firefox you click “Add Exception…” and I recommend unchecking the permanent option (since the cert won’t last very long anyway).
Congratulations! You now have webpack-dev-server running! You can test it out by changing
src/foo.js. When you save changes to either file, the webpage in your browser will refresh with the new bundle.
The final product is available to clone in basic-webpack-no-loaders.
src/, just make sure that the
entry property in
webpack.config.js points to your entry file (some common files are