Getting Started | webpack

Webpack is a good fit when your application needs a customizable build pipeline: bundling JavaScript modules, processing assets, integrating loaders and plugins, and shaping output for different environments. For a very small page with one or two scripts, a bundler may be unnecessary at first; for an application with shared dependencies, npm packages, assets, and production builds, webpack gives you explicit control over how everything is assembled.
Webpack is used to efficiently compile JavaScript modules. Once installed, you can interact with webpack either from its CLI or API. If you're still new to webpack, please read through the core concepts and this comparison to learn why you might use it over the other tools that are out in the community.
The examples in this guide use webpack-cli 7, which requires Node.js 20.9.0 or later.
Check out this guide live on StackBlitz.
If you want to get a working webpack project up and running quickly, the easiest way is to scaffold one using create-webpack-app.
Need a CLI-based project setup or templates? See the Init command for webpack's scaffolding flow.
This command generates a ready-to-use webpack project with a sensible default configuration. Continue below if you'd like to understand how to set up webpack manually step by step.
First let's create a directory, initialize npm, install webpack locally, and install the webpack-cli (the tool used to run webpack on the command line):
Throughout the Guides we will use diff blocks to show you what changes we're making to directories, files, and code. For instance:
Now we'll create the following directory structure, files and their contents:
We also need to adjust our package.json file in order to make sure we mark our package as private, as well as removing the main entry. This is to prevent an accidental publish of your code.
We also add "type": "module" so that Node.js treats .js files in this project as ES modules. That setting applies project-wide, including future Node.js scripts and webpack configuration files. If you would rather keep Node's default CommonJS behavior, omit "type": "module" and write the configuration later in this guide with require(...) and module.exports instead of import and export default.
If you want to learn more about the inner workings of package.json, then we recommend reading the npm documentation.
In this example, there are implicit dependencies between the <script> tags. Our index.js file depends on lodash being included in the page before it runs. This creates an implicit dependency on a global variable (_), making script execution order critical and harder to maintain.
There are problems with managing JavaScript projects this way:
Webpack solves these issues by explicitly declaring dependencies and bundling them together. This removes reliance on global variables and ensures scripts are executed in the correct order.
First we'll tweak our directory structure slightly, separating the "source" code (./src) from our "distribution" code (./dist). The "source" code is the code that we'll write and edit. The "distribution" code is the minimized and optimized output of our build process that will eventually be loaded in the browser. Tweak the directory structure as follows:
The dist directory is build output, so you usually do not hand-edit files there in a mature project. We are moving index.html into dist for now only as temporary scaffolding, so the browser has an HTML file that loads the first generated bundle. Later on in another guide, we will generate index.html rather than edit it manually. Once this is done, it should be safe to empty the dist directory and regenerate all the files within it.
To bundle the lodash dependency with index.js, we'll need to install the library locally:
With npm 5 and later, packages installed with npm install <package> are saved to dependencies by default. If you're installing a package for development purposes (e.g. a linter, testing libraries, etc.) then you should use npm install --save-dev. More information can be found in the npm documentation.
Now, let's import lodash in our script:
Now, since we'll be bundling our scripts, we have to update our index.html file. Let's remove the lodash <script>, as we now import it, and modify the other <script> tag to load the bundle, instead of the raw ./src file:
A couple other script loading strategies exist. Deferred loading is one such alternative to the above, where instead scripts are consolidated into the <head> and are given the defer attribute. This strategy downloads the external script resource(s) in parallel with document parsing, and will execute the scripts in order of document appearance after parsing has finished. This is in contrast to the above, in which the parser pauses to download and then execute the external resource synchronously. To learn more about this process, MDN has a nice reference guide.
In this setup, index.js explicitly requires lodash to be present, and binds it as _ (no global scope pollution). By stating what dependencies a module needs, webpack can use this information to build a dependency graph. It then uses the graph to generate an optimized bundle where scripts will be executed in the correct order.
With that said, let's run npx webpack from the project root. If webpack is installed locally, npx will run the local binary from node_modules/.bin; otherwise, it may download and execute it. This command takes our script at src/index.js as the entry point and generates dist/main.js as the output.
Your output may vary a bit, but if the build is successful then you are good to go.
Webpack runs in production mode by default when no mode is set, so the output above includes [minimized] and the generated dist/main.js will be optimized for browsers rather than easy reading. While learning, you can run npx webpack --mode development, yarn webpack --mode development, or pnpm exec webpack --mode development to produce a more readable bundle.
Open index.html from