Reland experimental custom webpack support (#99234)
### What? Reland [#98862](https://github.com/vercel/next.js/pull/98862) after its revert in [#99227](https://github.com/vercel/next.js/pull/99227). Restore `next dev --custom-webpack` and `next build --custom-webpack`, CLI documentation, and the original e2e fixture, **without declaring webpack as a peer dependency**. `--webpack` continues using bundled webpack. ### Why? Allow applications to explicitly opt into their installed webpack version. The CLI records the absolute application directory before loading dev/build internals; config loading validates webpack, while Next.js's compiled webpack wrapper uses a project-scoped `createRequire` for every webpack import. This ensures `next.config.js`, user plugins, and Next.js compilation use the same webpack even if a different version is visible from inside the `next` package. Custom mode installs no webpack aliases; bundled mode keeps its explicit alias list. ### How? Restore the feature on post-revert canary without undoing intervening changes (including `next analyze`). Keep webpack as an application-installed dependency checked at opt-in time, rather than an npm peer in `next`'s published metadata. The e2e tests exercise webpack 5.98.0 and 5.111.0 in dev and production, config-time `require('webpack/package.json')`, custom and built-in plugins, the missing-install diagnostic, bundled fallback, and conflicting flags. A regression fixture disables pnpm hoisting and shadows webpack 5.98.0 beside `next` while the app installs 5.111.0; it proves Next still selects the app's instance. Another test builds with an explicit application directory from a different cwd. A dedicated Custom Webpack guide (shared between App and Pages Routers) includes install/usage examples and a pnpm `hoistPattern` note for plugins and workspace tooling that independently resolve webpack; both CLI option rows link to the guide. **Internal-sync caveat:** #99227 reports that declaring webpack as an optional peer introduced a dependency chain that duplicated Next.js in monorepos and broke internal sync. This reland **omits the peer declaration** to avoid that specific graph edge, while keeping runtime validation for `--custom-webpack`. The private dependency graph and sync reproduction are unavailable here; local tests do **not** independently prove internal sync is fixed. Maintainers should verify it before merging. **Local verification:** focused e2e **8/8 dev and 8/8 production** (plus targeted non-isolated checks for the two new tests), Next.js build and types, frozen lockfile install, changed-file ESLint, Prettier, and `pnpm types-and-precompiled` from a clean commit (no generated diff). Repo-wide `pnpm lint-eslint .` fails with a plugin-scope configuration error on the post-revert base as well (`import/no-extraneous-dependencies` cannot find plugin `import`); changed-file lint passes. **Review follow-up:** Restored the bundled-only `webpack/package` metadata alias and added config-time coverage for both extensionless and `.json` metadata imports. Per sokra's direction, no runtime version validation is added; the docs explicitly describe custom webpack as use at your own risk and list the tested versions without guaranteeing compatibility. **CI note:** Commit `51ebc4f9` passed docs-link, lint, types/precompiled, all production tests and changed-test flake runs, but a new explicit-directory case attempted `next build` inside a dev-mode shard and failed deterministically with a missing `.next/dev/trace`. The follow-up test-only commit `9d5c3d4e` instead exercises `next dev <appDir>` there and checks its HTTP output; it preserves the production `next build <appDir>` assertion. Focused dev and production e2e tests pass 8/8 locally; That commit's CI passed. Review follow-up `ed1c7bd0` also passed CI. The docs-only commit `10cbbd84` moves the setup section into the dedicated guide; its CI is running. The earlier docs-only commit also hit unrelated instant-validation snapshot mismatches, which were not rerun as flakes. <!-- NEXT_JS_LLM --> <!-- fleet 19431696-5f4c-400d-a3be-700bfe86abda --> --------- Co-authored-by:vercel-fleet-prod[bot] <318278635+vercel-fleet-prod[bot]@users.noreply.github.com> Co-authored-by:
Tobias Koppers <1365881+sokra@users.noreply.github.com>
Showing
Please
register
or
sign in
to comment