|
| 1 | +# Webpack Development Guide |
| 2 | + |
| 3 | +> Note: CLAUDE.md is a symlink to AGENTS.md. They are the same file. |
| 4 | +
|
| 5 | +## Project Overview |
| 6 | + |
| 7 | +webpack is a JavaScript module bundler. |
| 8 | + |
| 9 | +## Key Directories |
| 10 | + |
| 11 | +- `lib/` — Main source code |
| 12 | +- `lib/optimize/` — Optimization plugins (tree shaking, chunk splitting, etc.) |
| 13 | +- `lib/serialization/` — Cache serialization |
| 14 | +- `lib/schemes/` — URI scheme plugins (HttpUri, DataUri, Virtual) |
| 15 | +- `schemas/` — JSON schemas for webpack options |
| 16 | +- `types.d.ts` — Auto-generated type definitions (do not edit manually) |
| 17 | +- `tooling/` — Build tooling scripts |
| 18 | +- `test/` — All tests |
| 19 | +- `.changeset/` — Changeset files for releases |
| 20 | + |
| 21 | +All available commands are defined in `package.json` scripts. Refer to `package.json` for the latest definitions. |
| 22 | + |
| 23 | +## Development Workflow |
| 24 | + |
| 25 | +### 1. Making Changes to `lib/` |
| 26 | + |
| 27 | +After modifying source code in `lib/`: |
| 28 | + |
| 29 | +```bash |
| 30 | +yarn fix:code # ESLint autofix |
| 31 | +yarn fmt # Prettier format |
| 32 | +# Or combined: |
| 33 | +yarn fix # runs fix:code + fix:special + fmt |
| 34 | +``` |
| 35 | + |
| 36 | +### 2. Modifying Schemas or Types |
| 37 | + |
| 38 | +If your change affects module exports, options, or type definitions: |
| 39 | + |
| 40 | +1. Edit the relevant schema file in `schemas/` (e.g., `schemas/WebpackOptions.json`, `schemas/plugins/`) |
| 41 | +2. Run `yarn fix:special` to regenerate: |
| 42 | + - `types.d.ts` (compiled from JSDoc + schemas) |
| 43 | + - Precompiled schema validators |
| 44 | + - Runtime code |
| 45 | +3. Other files can then reference the updated types via JSDoc `@typedef {import("...")}` imports |
| 46 | + |
| 47 | +### 3. Adding a Changeset |
| 48 | + |
| 49 | +Every user-facing change needs a changeset file: |
| 50 | + |
| 51 | +```bash |
| 52 | +# Create .changeset/<descriptive-name>.md with this format: |
| 53 | +--- |
| 54 | +"webpack": patch # or minor / major |
| 55 | +--- |
| 56 | + |
| 57 | +Description of the change. |
| 58 | +``` |
| 59 | + |
| 60 | +Use `patch` for bug fixes, `minor` for new features, `major` for breaking changes. |
| 61 | + |
| 62 | +### 4. Writing Tests |
| 63 | + |
| 64 | +Test files live in `test/` with naming conventions: |
| 65 | + |
| 66 | +- `*.unittest.js` — Unit tests (`yarn test:unit`) |
| 67 | +- `*.basictest.js` — Basic integration tests (`yarn test:basic`) |
| 68 | +- `*.test.js` — Full integration tests |
| 69 | +- `*.longtest.js` — Long-running tests |
| 70 | + |
| 71 | +**Test case directories:** |
| 72 | + |
| 73 | +- `test/cases/` — Compilation test cases (each subdirectory is a test case with `index.js` + optional `webpack.config.js`) |
| 74 | +- `test/configCases/` — Config-driven test cases (each has `webpack.config.js` + test files) |
| 75 | +- `test/statsCases/` — Stats output snapshot tests |
| 76 | +- `test/watchCases/` — Watch mode test cases (file change detection, incremental rebuild) |
| 77 | +- `test/hotCases/` — HMR (Hot Module Replacement) test cases |
| 78 | + |
| 79 | +For unit tests, use Jest directly. Example: `test/FileSystemInfo.unittest.js` uses `memfs` for filesystem mocking. |
| 80 | + |
| 81 | +### 5. Running Tests |
| 82 | + |
| 83 | +**Choose test command based on modified directory:** |
| 84 | + |
| 85 | +| Modified directory/file | Command | |
| 86 | +| ----------------------- | ------------------------------------------------------------------------ | |
| 87 | +| `test/*.unittest.js` | `yarn test:unit` | |
| 88 | +| `test/cases/` | `yarn test:basic` | |
| 89 | +| `test/configCases/` | `yarn test:basic -- --testPathPattern="ConfigTestCases"` | |
| 90 | +| `test/statsCases/` | `yarn test:basic -- --testPathPattern="StatsTestCases"` | |
| 91 | +| `test/watchCases/` | `yarn test:base -- --testPathPattern="WatchTestCases"` | |
| 92 | +| `test/hotCases/` | `yarn test:base -- --testPathPattern="HotTestCases"` | |
| 93 | +| `lib/` (general) | `yarn test:basic` for quick check, then `yarn test:integration` for full | |
| 94 | +| `schemas/` | `yarn fix:special` then `yarn lint:types` | |
| 95 | + |
| 96 | +**Common commands:** |
| 97 | + |
| 98 | +```bash |
| 99 | +yarn test:unit # Unit tests only |
| 100 | +yarn test:basic # Basic tests only |
| 101 | +yarn test:integration # All integration tests |
| 102 | +yarn test:base -- --testPathPattern="FileSystemInfo" # Run specific test file |
| 103 | +yarn test:base -- --testNamePattern="pattern" # Run specific test name |
| 104 | +``` |
| 105 | + |
| 106 | +Tests require `--expose-gc --max-old-space-size=4096 --experimental-vm-modules` (already configured in scripts). |
0 commit comments