Skip to content

Improved installation documentation wording and structure #17

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
surajkumar-arch wants to merge 1 commit into from
Closed

Improved installation documentation wording and structure #17

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
228 changes: 99 additions & 129 deletions installation.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,158 +1,134 @@
---
title: Installation
description: Install webpack and start bundling your JavaScript modules
description: Get webpack set up in your project — the right way, from day one
---

# Installing webpack

This guide covers how to install webpack in your project.

## Prerequisites

<Note>
webpack requires **Node.js version 10.13.0 or higher**. Check your Node.js version with `node -v`.
</Note>

Before installing webpack, make sure you have:
- Node.js installed (version 10.13.0 or higher)
- npm, yarn, or pnpm package manager

## Local Installation (Recommended)

For most projects, we recommend installing webpack locally. This allows different projects to use different versions of webpack and makes your build reproducible.

<Steps>
<Step title="Initialize your project">
If you haven't already, create a `package.json` file:

```bash
npm init -y
```
</Step>

<Step title="Install webpack and webpack-cli">
Choose your preferred package manager:

<CodeGroup>
```bash npm
npm install --save-dev webpack webpack-cli
```

```bash yarn
yarn add webpack webpack-cli --dev
```

```bash pnpm
pnpm add -D webpack webpack-cli
```
</CodeGroup>

<Info>
`webpack-cli` is optional but recommended. It provides a command-line interface for running webpack and accessing helpful commands.
</Info>
</Step>

<Step title="Verify installation">
Check that webpack was installed correctly:

```bash
npx webpack --version
```

You should see the webpack version number (currently 5.105.4).
</Step>
</Steps>

## Global Installation

<Warning>
Global installation is **not recommended** for most use cases. It locks you to a specific version of webpack across all projects and can cause version conflicts.
</Warning>

If you need webpack available globally (for quick experiments or testing):

<CodeGroup>
```bash npm
npm install --global webpack webpack-cli
If you're setting up webpack for the first time — or contributing to a project that already uses it — you're in the right place. This guide walks through everything step by step, with context on *why* each step matters.

## Before you start

You'll need **Node.js v10.13.0 or higher**. Check your current version with:
```bash
node -v
```

```bash yarn
yarn global add webpack webpack-cli
Don't have Node.js yet? Grab it from [nodejs.org](https://nodejs.org) before continuing. npm comes bundled with it, but yarn and pnpm work just as well.

---

## Local installation (recommended for almost everything)

Installing webpack *inside* your project — not globally — is the right call for real projects. It means each project controls its own webpack version, so builds are consistent no matter who runs them or on which machine.

**Step 1: Initialize your project**

If you don't have a `package.json` yet:
```bash
npm init -y
```

**Step 2: Install webpack and webpack-cli**

Pick your package manager:
```bash
# npm
npm install --save-dev webpack webpack-cli

# yarn
yarn add webpack webpack-cli --dev

# pnpm
pnpm add -D webpack webpack-cli
```

> **What's webpack-cli?** It's technically optional, but you want it. It gives you the `webpack` command in your terminal and a bunch of helpful extras. Think of it as the command-line layer on top of webpack's core.

**Step 3: Verify it worked**
```bash
npx webpack --version
```

```bash pnpm
You should see something like `webpack 5.105.4`. If you do — you're all set.

---

## Global installation (use sparingly)

You *can* install webpack globally, but it's not recommended for actual projects:
```bash
# npm
npm install --global webpack webpack-cli

# yarn
yarn global add webpack webpack-cli

# pnpm
pnpm add -g webpack webpack-cli
```
</CodeGroup>

After global installation, you can run `webpack` directly from your terminal.
The problem with global installs: they tie every project on your machine to the same webpack version. The moment two projects need different versions, things break. Fine for quick throwaway experiments — not for anything you're committing to a repo.

## Version-Specific Installation
---

To install a specific version of webpack:
## Installing a specific version

<CodeGroup>
```bash npm
Contributing to an existing codebase? Always check the project's `package.json` and match its webpack version exactly. Mismatched versions are a surprisingly common source of "works on my machine" bugs.
```bash
# npm
npm install --save-dev webpack@5.105.4 webpack-cli
```

```bash yarn
# yarn
yarn add webpack@5.105.4 webpack-cli --dev
```

```bash pnpm
# pnpm
pnpm add -D webpack@5.105.4 webpack-cli
```
</CodeGroup>

## Installing Loaders and Plugins
---

Webpack's power comes from its ecosystem of loaders and plugins. Install them as dev dependencies:
## Installing loaders and plugins

Webpack's real power comes from its ecosystem. Loaders let it process different file types (CSS, TypeScript, images, etc.); plugins extend what webpack does during the build itself. Install them as dev dependencies, same as webpack:
```bash
# Example: Installing loaders for CSS and TypeScript
# Loaders for CSS and TypeScript
npm install --save-dev css-loader style-loader ts-loader

# Example: Installing common plugins
# Common plugins
npm install --save-dev html-webpack-plugin mini-css-extract-plugin
```

## Bleeding Edge Installation
You'll wire these up in your `webpack.config.js` — covered in the Configuration guide.

<Warning>
The following npm package points to the latest development branch and may be unstable. Use at your own risk.
</Warning>
---

To install the latest development version directly from the repository:
## Bleeding edge (latest dev build)

If you're contributing to webpack itself or testing a fix that's already merged but not released:
```bash
npm install --save-dev webpack/webpack#main webpack-cli
```

## Verifying Your Installation

After installation, verify everything is set up correctly:
This installs directly from the `main` branch, so it can be unstable. Don't use this for production or shared projects without a good reason.

1. Check webpack version:
```bash
npx webpack --version
```
---

2. Check webpack-cli version:
```bash
npx webpack-cli --version
```
## Verifying your full setup

3. View webpack help:
```bash
npx webpack --help
```
Once installed, do a quick sanity check:
```bash
npx webpack --version # Should print the webpack version
npx webpack-cli --version # Should print the cli version
npx webpack --help # Lists all available options
```

## Package Scripts
---

Add webpack to your `package.json` scripts for easier access:
## Setting up npm scripts

```json package.json
Rather than typing `npx webpack` every time, add shortcut commands to your `package.json`. This is the pattern you'll see in virtually every open source project:
```json
{
"name": "my-webpack-project",
"version": "1.0.0",
Expand All @@ -169,27 +145,21 @@ Add webpack to your `package.json` scripts for easier access:
}
```

Now you can run:
Then run them like this:
```bash
npm run build # Build with default configuration
npm run build:prod # Build for production
npm run build:dev # Build for development
npm run watch # Watch for changes and rebuild
npm run build # Default build
npm run build:prod # Production build — minified, optimized
npm run build:dev # Development build — easier to debug
npm run watch # Auto-rebuilds whenever you save a file
```

## Next Steps
`watch` mode is especially useful during active development — you won't need to manually rebuild every time you make a change.

---

Now that webpack is installed, you're ready to:
## What's next?

<CardGroup cols={2}>
<Card title="Quick Start Guide" icon="rocket" href="/quickstart">
Create your first webpack bundle
</Card>
<Card title="Configuration" icon="gear" href="/configuration">
Learn how to configure webpack
</Card>
</CardGroup>
- **[Quick Start Guide](/quickstart)** — bundle your first files and see webpack in action
- **[Configuration](/configuration)** — learn how `webpack.config.js` works and how to customize your build

<Tip>
For production builds, consider installing `terser-webpack-plugin` (included by default in webpack 5) for JavaScript minification.
</Tip>
> **Production note:** webpack 5 includes `terser-webpack-plugin` out of the box. When you run `build:prod`, JavaScript minification happens automatically — no extra setup needed.