Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 38 ยท Getting Started

Install Webpack and Build Your First Bundle

Install Webpack and webpack-cli with npm, write a tiny project, add npm scripts, run your first build and read the dist output and the build summary line by line.

In this lesson you create a project from scratch, install Webpack, and produce your first bundle. You need Node.js (current LTS is a good choice) and npm. The commands below run in your own terminal; the site cannot run Webpack, so the commands are read-only, and a Node stand-in at the end shows what a build produces.

Create the project

Make a folder, initialize npm, and install Webpack as a development dependency. Bundlers are build tools: the shipped app only needs their output.

Terminal
mkdir hello-webpack
cd hello-webpack
npm init -y
npm install --save-dev webpack webpack-cli

Two packages are installed:

  • webpack is the core library.
  • webpack-cli provides the webpack command. Without it you can only use Webpack from JavaScript code.

Pin a local install. A global webpack command makes builds depend on whatever is on one machine; a local one is locked by package-lock.json, so everyone, including your CI server, builds the same way.

Write some modules

Create this layout:

TEXT
hello-webpack/
  package.json
  src/
    index.js
    greeting.js
  dist/
    index.html

src/greeting.js exports a function:

JavaScript
export function greet(name) {
  return `Hello, ${name}!`;
}

src/index.js imports it and writes into the page:

JavaScript
import { greet } from './greeting.js';

document.body.insertAdjacentHTML('beforeend', `<h1>${greet('Webpack')}</h1>`);

dist/index.html loads the file that Webpack will produce:

HTML
<!doctype html>
<html lang="en">
  <head><meta charset="utf-8"><title>Hello Webpack</title></head>
  <body>
    <script src="main.js"></script>
  </body>
</html>

Run the build

Webpack has zero-config defaults: entry ./src/index.js, output ./dist/main.js. So this already works:

Terminal
npx webpack

npx runs the locally installed binary. You should see a summary similar to this (sizes and hashes vary):

TEXT
asset main.js 1.2 KiB [emitted] [minimized] (name: main)
./src/index.js 117 bytes [built] [code generated]
./src/greeting.js 62 bytes [built] [code generated]
webpack 5.x compiled successfully in 180 ms

Read it from the top: main.js is the emitted asset, the two lines below are the modules that went into it (the dependency graph), and the last line says it worked. Open dist/index.html in a browser and you see the heading. Because no mode was set, Webpack printed a warning and used production, which is why the file is minimized.

Add npm scripts

Typing npx webpack is fine, but scripts document how your project builds. Edit package.json:

JSON
{
  "scripts": {
    "build": "webpack --mode production",
    "build:dev": "webpack --mode development"
  }
}

Now npm run build creates the production bundle and npm run build:dev a readable one. Open dist/main.js after the development build and you will see each of your modules inside a function, plus a small runtime. Build Modes explains the differences, and How a Bundler Works rebuilds that runtime by hand.

Add node_modules and dist to .gitignore. dist is generated output; anyone can recreate it with npm run build.

What the output contains

The production file is minimal, but the development file is worth reading once. Its structure is always the same:

flowchart TB
  A["modules object: path -> function"] --> B["module cache"]
  B --> C["__webpack_require__(id)"]
  C --> D["run the entry module"]

A map of modules, a cache so each runs once, a require function, and a call that starts the entry.

This stand-in does the same thing for two tiny in-memory modules and writes a bundle to a folder, so you can see the files a build produces.

Node.js Stand-in: a build that writes dist/

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The real bundle also adds helpers for ES module interop and for chunk loading, but the skeleton is this one.

Common first-build problems

  • webpack is not recognized. Use npx webpack or an npm script. The binary lives in node_modules/.bin.
  • Module not found: Can't resolve './src/index.js'. The entry file is missing or the command runs in the wrong folder.
  • A blank page. The HTML must point at the emitted file name. If you change the output name, change the script tag too; the HTML Webpack Plugin automates that.
  • A warning about mode. Set one explicitly, as the scripts above do.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why is webpack installed with --save-dev?

    A bundler is a build tool, so it belongs in devDependencies.
  2. 2. What does webpack-cli provide?

    The webpack package is the library; webpack-cli gives you the command line interface.
  3. 3. Without any configuration file, which file does Webpack bundle and where does it write?

    The defaults are entry ./src/index.js and output ./dist/main.js.
  4. 4. Why prefer a local install plus npm scripts over a global webpack?

    Locking the version removes "works on my machine" differences, including on CI.

Summary

  • Install webpack and webpack-cli as dev dependencies and run them through npx or npm scripts.
  • With no config, src/index.js is bundled into dist/main.js.
  • The build summary lists the emitted assets, the modules inside them, and the result.
  • A bundle is a module map, a cache and a require function, plus a call that starts the entry.
  • Set mode explicitly to avoid the default warning.

Next: The Webpack Configuration File