Andrew Welch’s landmark webpack treatise covers just about everything you’d need to get working with an organized, comprehensive webpack-based workflow. I know this because I’d recently made the transition from Gulp to webpack with only a fraction of what’s covered in his post. It took me a long time. If you’re looking for an up-close view of the machinery, Andrew’s article will make the most of your five minutes.
If you’re still not sure that webpack makes any sense, or how it can be okay to have 66 dependencies for a demonstration, join me here for a moment.
I’d started pawing at webpack a few times only to get confused or frustrated at the lack of a Gulp-like simplicity.
In hindsight, simplicity was the wrong thing to look for because webpack is just more complicated.
Making produtive use of it demanded that I rethink my approach to front end assets and how they come together. It took me a while to hammer out my humble workflow, and I’d like to share the critical shift in orientation that finally made all the technical hurdles worth the trouble.
Imagine a project that relies on jQuery, some plugins and scripts, and a Gulp workflow. For that project, webpack will feel like overkill. It probably is overkill. The retooling and complication may not be worth it for every project.
A Conveyor Belt and a Production Manager
Gulp and webpack are different animals.
Using Gulp is like having a conveyor belt where you can tinker with each of the stations. You drop stuff in at different points, it all moves down the line, and it’s dumped out somewhere.
Using webpack is more like hiring a production manager to listen to all your needs and wrangle all the stuff efficiently. Instead of adjusting conveyor belt stations, you tell the production manager where to find things and what you’d like to end up with. You spend most of your time going into great detail clarifying your instructions, and the manager gets it done.
Webpack doesn’t just want to compile your things and dump them out, it wants to help you solve production problems. "Help me help you," it says. Here are my tips for working with webpack:
Don’t skim when you’re reading about entry points.
The webpack magic starts and ends with entry points, so it’s important to understand what they are and how you can use them. The concept shouldn’t be too unfamiliar: entry points are the built assets you’ll reference in your markup so the browser can work with your bundles.
Your current setup might have a global
app.js that handles site-wide navigation and search functionality, for example, and then
forms.js that you use only on pages with forms. Each could easily be an entry point in your webpack setup.
Where things can get more interesting is that a single entry point can load code asynchronously, dynamically split code, and usher in all kinds of fancy that doesn’t have an equivalent with your current setup.
But they don’t have to be complicated. The entire contents of an entry point might look like this:
That’s an imaginary
/dist/css/forms.bundle.css which I can include on the front end. In this case I’d also have a
/dist/js/forms.bundle.js I’d ignore.
/dist/js/forms.bundle.js in my site’s markup.
Know what an entry point is and how you intend to use one or several of them in your project.
Don’t bring files and expect to leave with some other files.
Bring packages and code and expect to leave with bundles.
You might start whistling while you work.
For example, let’s say you’re using Prism to add syntax highlighting to your code blocks.
Previously, you might have visited the download page to customize and download a build with whatever features you’d want. You’d plop them in your web folder and add the JS and CSS to your markup:
<script src="prism.js"></script> <link rel="stylesheet" href="prism.css">
You could have put them in a project source folder and had gulp minify and combine them as well, but ultimately you were putting the result in the web root one way or another. You would then have to manually grab new files for changes, whether it’s to Prism’s core code, a change of color theme, or different language support.
data-manual property to your script tag to prevent that and configure it via API.
<script src="prism.js" data-manual></script>
You’d then write some code telling Prism what to do, putting it in
<script> tags on your page or in another file (like
Now let’s look at this Prism example with a webpack setup.
By virtue of using webpack, we’ve probably already included bundle references somewhere in our markup:
<script src="app.bundle.js"></script> <link rel="stylesheet" href="app.bundle.css">
app. filename is deliberate, because this bundle is actually a collection of different things and not just our Prism assets; each file is the result of webpack’s bundling process. That process likely includes combining and minifying files (among other things), resulting in
app.bundle.css. You can choose whatever filenames you’d like, of course.
yarn at the command line.
That’s exactly what we’ll in the webpack equivalent of our example:
npm install prismjs
npm now downloads Prism for you into your project’s
node_modules directory. Unless you’ve done something horribly wrong,
node_modules shouldn’t be web-accessible.
import Prism from 'prismjs';
Nothing happens with this alone, so we have to add one line that tells Prism to highlight all the code blocks it finds:
import Prism from 'prismjs'; Prism.highlightAll();
- When you
npm install, the package and its version are added to your
package.jsonfile. This will signal to other developers that your project uses Prism, and the package manager will look out for compatibility issues and make sure any project code can share the same version of Prism to keep things efficient.
- Your repository is cleaner since dependencies are downloaded separately. (Commit your bundles, don’t commit your
node_modules.) This can be helpful for licensing, too.
Webpack will champion your dependencies and performance needs, so try to shift your thinking toward what code you need and where it should have an impact rather than what files you need and how you’ll manage them in your webroot and your markup.
I found many helpful articles on my quest that had totally incompatible approaches to solve similar problems. It’s complicated, there’s a whole lot you can do, and it’ll feel fantastic when all the pieces are working for you and speeding up your development process.
I’m far from an expert on the subject, but my prior confusion was genuine and long-lasting. Despite the significant effort to use webpack in my projects, my code is cleaner and my build process is much smoother and I’d probably have tried to make the move sooner if I’d known how much it would improve my development efforts in general.
I hope this is helpful! Please post a comment or send me an email if you have questions, comments, or corrections.