feat(v2): Webpack 5, PostCSS 8 by RDIL · Pull Request #4089 · facebook/docusaurus

RDIL · 2021-01-22T16:36:36Z

Released in 2.0.0-alpha.75

Breaking changes

As it's a major Webpack version upgrade, it is a breaking change and can require adapt things on your sites such as the configureWebpack of your custom plugins.

However, sites that do not have custom plugins and mostly use a basic config should be able to upgrade seamlessly.

Please report any issues otherwise.

Known issues:

Not compatible with alpha 75 / Webpack 5 praveenn77/docusaurus-lunr-search#52
error building locale=en TypeError: Cannot read property 'intercept' of undefined #4709

Using persistent caching

Make your CI cache the node_modules/.cache folder across 2 CI builds, and the 2nd build becomes much faster.

Upgrade Webpack 4 to Webpack 5 + upgrade related libs
PostCSS 7 to PostCSS 8
Leverage persistent caching for a much faster 2nd build
Try to keep retro compatibility in most cases (breaking changes are normally all in libs, not Docusaurus)

If you get some deprecation warnings, please report them here with the stacktrace, by running NODE_OPTIONS='--trace-warnings' yarn build

Tested on a lot of sites with great success:

React-Native: Upgrade website to Docusaurus using webpack 5 react/react-native-website#2573
Jest: Upgrade website to Docusaurus using webpack 5 jestjs/jest#11266
React-Navigation: chore: Test Docusaurus webpack 5 support react-navigation/react-navigation.github.io#974
Redux: chore: Docusaurus with webpack 5 reduxjs/redux#4067
React-Redux: chore: Docusaurus with webpack 5 reduxjs/react-redux#1714
QuestDB: https://github.com/questdb/questdb.io/pull/436
Relay: chore: Docusaurus with webpack 5 relay#3469
Create-React-App: chore: Docusaurus with webpack 5 react/create-react-app#10866
Hermes: chore: Docusaurus with webpack 5 hermes#500
Supabase: chore: Docusaurus with webpack 5 supabase/supabase#1256
WebdriverIO: chore: Docusaurus with webpack 5 webdriverio/webdriverio#6753
Apisix: chore: Test Docusaurus webpack 5 support apache/apisix-website#318
Metro: chore: Docusaurus on webpack 5 react/metro#667
Next Auth: chore: Test Docusaurus webpack 5 support nextauthjs/next-auth#1826
MikroORM: chore: Test Docusaurus webpack 5 support mikro-orm/mikro-orm#1716
Demisto: chore: Test Docusaurus webpack 5 support demisto/content-docs#616

netlify · 2021-01-22T16:38:11Z

[V2]

Built with commit 867d034

https://deploy-preview-4089--docusaurus-2.netlify.app

… broken

Signed-off-by: Reece Dunham <me@rdil.rocks>

github-actions · 2021-02-11T17:40:12Z

⚡️ Lighthouse report for the changes in this PR:

Category	Score
🟠 Performance	73
🟢 Accessibility	96
🟢 Best practices	100
🟢 SEO	100
🟢 PWA	95

Lighthouse ran on https://deploy-preview-4089--docusaurus-2.netlify.app/

slorber · 2021-04-23T17:56:05Z

So, I tested this on a lot of sites (cf list at the top) and it seems to work great in most cases, just noted a few minor changes to do.

We'll likely do one last Webpack 4 bugfix release soon and then merge this PR next week.

juzhiyuan · 2021-04-24T00:57:33Z

Glad to receive your PR! @slorber And if it's ready to merge, just let us know :)

…Webpack5)

# Conflicts: # packages/docusaurus-init/templates/bootstrap/package.json

> Conflict: Multiple assets emit different content to the same filename assets/ideal-img/datagit.100.png see #4089 (comment)

slorber · 2021-04-30T15:45:16Z

going to merge/release this, and add another PR for the asset modules, as there are some details I'm not yet able to solve

RDIL · 2021-04-30T16:45:15Z

🎉 🎉 🎉

slorber · 2021-04-30T16:53:23Z

Thanks for your work on this @RDIL ! happy to get this finally merged

> Conflict: Multiple assets emit different content to the same filename assets/ideal-img/datagit.100.png see #4089 (comment)

Summary: Use an unreleased version of Docusaurus to test the webpack5 support works for this site, detect potential problems, and perf improvements. See also facebook/docusaurus#4089 Pull Request resolved: #500 Reviewed By: dulinriley Differential Revision: D28129952 Pulled By: Huxpro fbshipit-source-id: 07942b60d5200ea6dc3a9de86844da349f700a31

Summary: Use an unreleased version of Docusaurus to test the webpack5 support works for this site, detect potential problems, and perf improvements. See also facebook/docusaurus#4089 Perf improvements - First build (local): 300s - Second build (local): 90s To get the benefits, it requires caching `node_modules/.cache`. It is not possible in GH actions, so I suggest migrating the site to Netlify and use the appropriate toml config (example: https://github.com/react-navigation/react-navigation.github.io/pull/974/files) --- Unrelated suggestion: Relay has a lot of versions and long build/start times Assuming nobody ever edit Relay docs of 2 years ago, you can improve the DX by limiting the number of versions display in dev with this docs plugin config: ``` onlyIncludeVersions: (isDev || isDeployPreview) ? ['current', ...versions.slice(0, 2)] : undefined, ``` For faster prod build, you can also move older docs to standalone deployments and link to them (see Jest for versions < 25 => https://jestjs.io/) Pull Request resolved: #3469 Reviewed By: rbalicki2 Differential Revision: D28127629 Pulled By: jstejada fbshipit-source-id: c78309aa1c7f14f22ecc33166ad5dce7d2e51f94

@ts-nocheck

* Initial webpack 5 work * It works on my machine (lol) * Committing a bit more work * It works - sorta * Update packages/docusaurus/package.json * at least fix prettier /shrug * making more progress. build should work now, css stuff is still a bit broken * Terser things Signed-off-by: Reece Dunham <me@rdil.rocks> * Working on things * Vendor webpack * Repair chunks, and tests * Rerun prettier * Re-add client prefetching * Update snapshots * Update snapshots * I hope this works * Remove redundant dev server code * relock * Trying to reduce memory usage and fix things * Dead code elim * Search bar works!!! * Prefetching should work again * lock * ts issue * Repair snapshot * Run prettier * Fix the CI for now * fix lint-prettier * clean-css works, now for the other one * Fix lockfile * Fixes prettier * Other css minification works!!! * Add clean-css options, fix webpack versions Signed-off-by: Reece Dunham <me@rdil.rocks> * Fix tests and several of the webpack loaders Signed-off-by: Reece Dunham <me@rdil.rocks> * Re-add support for simple css minifier * Update other related dependencies * Fix lockfile * Dev server fixups Signed-off-by: Reece Dunham <me@rdil.rocks> * Simplify css things * Update webpack, try with postcss 7 * Other cssnano repairs * fix lockfile * Clean up the babel preset * Fix lockfile * Bump RL SSR version * Fix the build errors * Lockfile fix * It works again * webpack 5 should close compiler after run * add proper webpack5 persistent caching config * upgrade webpack deps again * reduce build perf timeouts to avoid build time regressions * test if incremental build can run on netlify * netlify test * netlify test * netlify test * netlify test * netlify test * netlify test * netlify test * netlify test * netlify test * netlify test * netlify test * netlify test * netlify test * netlify test * netlify test * test * test * test * test * netlify test * netlify test * netlify test * netlify test * netlify test * netlify test * netlify test * netlify test * netlify test * netlify test * fix existsSync() calls * replace @ts-nocheck by a temporary Webpack type * replace @ts-nocheck by a temporary Webpack type * replace @ts-nocheck by a temporary Webpack type * migrate existing stats.warningsFilter to config.ignoreWarnings * remove stats from postBuild lifecycle data doc, as it is likely unused (we'll add it back if someone ask for it) * improve build.ts TS issues + move some sync code to async * cleanup TS of start.ts * fix TS error * fix TS issues * fix TS issues * fix ts error * netlify test * netlify test * netlify test * netlify test * netlify test * script cleanup * script cleanup * re-enable @typescript-eslint/ban-ts-comment * Deprecate getCacheLoader / getBabelLoader but keep retrocompatibility * useless TS * fix and comment gca(chunkName) prefetching function * remove deprecated mainTemplate.requireFn * temporarily use react-loadable-ssr-addon-v5-slorber until PR merged: facebook#4089 * comment unsafeCache option * add explicit and more precise webpack targets * splitChunks, use new type: "css/mini-extract" as it seems recommended for webpack 5 * webpack error handling: - log error.details as documented - keep using react-dev-utils/formatWebpackMessages for now * fix webpack5 warnings for evalSourceMapMiddleware.js * typo * rename webpackHotDevClient * make all modifications of react-dev-utils explicit with a comment * revert LogPlugin adapter * loader-utils update * add useful share cache comment * add useful comments regarding the null-loader used in SSR for css files * upgrade webpack-merge in a retrocompatible way * use MiniCssExtractPlugin.emit false as recommended * use @docusaurus/responsive-loader * revert MiniCssExtractPlugin esModule: false change * add link to PR for custom CleanWebpackPlugin * pwa: add fallback to env variable or webpack 5 fails to build * upgrade to CssMinimizerPlugin 2.0 * only build en locale for windows tests * line breaks between errors * add useful comment * Fix e2e tests with Yarn2 not finding new init template dependencies * fix bad import * disable browserslist target as webpack already tries to use browserlists if a config is found, and it is a problem for existing sites * webpack5 TS fixes * fix getMinimizer order (even if it does not work yet) * update postcss to v8, fix cssnano minimizer errors * add NavbarItem position to types (useful for QuestDB site upgrade to Webpack5) * add webpack cache env variable to reduce risk of webpack 5 adoption Co-authored-by: slorber <lorber.sebastien@gmail.com>

> Conflict: Multiple assets emit different content to the same filename assets/ideal-img/datagit.100.png see facebook#4089 (comment)

* chore: remove tooling config entries for paths that no longer exist (AI-assisted) - jest/vendor (cspell, stylelint, oxfmt): removed with the Vitest migration, #12010 - packages/create-docusaurus/templates/facebook (ESLint): removed in #9026 - website/docusaurus.config.js (oxfmt): the config is TypeScript since #9317 - packages/docusaurus-migrate/lib (Vitest): package removed in #9400 - website/netlifyDeployPreview (.gitignore): removed in #4447 - .cache-loader (.gitignore): cache-loader removed with Webpack 5, #4089 - commented-out website/i18n/fr negations (.gitignore) - ".svg" (oxfmt): typo for the "*.svg" pattern right below it Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * chore(knip): treat configuration hints as errors, ignore the ideal-image fork internals (AI-assisted) - Add treatConfigHintsAsErrors, and remove the 3 entries Knip reports as useless: the playwright binary, and the @docusaurus/plugin-css-cascade-layers and @mdx-js/react dependencies - Don't treat the react-ideal-image fork modules as theme component entries, so that Knip reports the unused ones Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * test: remove unused test fixtures (AI-assisted) - docs bad-id-site and bad-slug-on-doc-home-site: unused since #3245 - utils vcs simple-site: unused since #11512 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * test(website): fix the React-DOM version check of the bad package dogfood test (AI-assisted) The second check tested ReactVersion again, so a bad React-DOM version never threw. Introduced in #10391. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * chore: remove more stale config entries (AI-assisted) - .gitignore types: nothing generates a types dir, even in #1490 where it was added, and it ignores any new types/ source folder - .gitignore website/rspack-tracing.json: the Rspack trace is written to rspack-tracing.pftrace since #11290 - clear script --ignore docusaurus: protected the lib/ sources of the v1 "docusaurus" package, removed in #4902 - ESLint __mocks__ ignore: converted from .eslintignore in #12024, it only matches a root __mocks__ dir that doesn't exist - Syncpack type-alias group: only the exact @types/react version still needs it, the * ranges are gone since #12435 and the other dependencies use the catalog since #12696 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * chore: replace the Prettier and Jest leftovers (AI-assisted) The monorepo formats with oxfmt since #11824 and tests with Vitest since #12010 - Devcontainer: format with the Oxc extension instead of Prettier, which formatted with its defaults, and remove the Jest extension - README: remove the Prettier and Jest badges - CONTRIBUTING: the formatter is oxfmt Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

Initial webpack 5 work

849d9c0

facebook-github-bot added the CLA Signed Signed Facebook CLA label Jan 22, 2021

This comment has been minimized.

Sign in to view

lex111 reviewed Jan 22, 2021

View reviewed changes

Comment thread packages/docusaurus/src/webpack/utils.ts

This comment has been minimized.

Sign in to view

RDIL commented Feb 5, 2021

View reviewed changes

Comment thread .eslintrc.js Outdated

RDIL added 4 commits February 5, 2021 18:49

It works on my machine (lol)

24c3817

Committing a bit more work

7b2f923

It works - sorta

9bfe9fb

Merge branch 'master' into webpack-5

89e6cb3

RDIL commented Feb 9, 2021

View reviewed changes

Comment thread packages/docusaurus/package.json Outdated

RDIL added 7 commits February 9, 2021 14:16

Update packages/docusaurus/package.json

82b7a4c

at least fix prettier /shrug

09aaaeb

making more progress. build should work now, css stuff is still a bit…

78dc506

… broken

Terser things

3ac46d3

Signed-off-by: Reece Dunham <me@rdil.rocks>

Merge branch 'master' into webpack-5

833fe54

Working on things

31c6185

Vendor webpack

5970897

RDIL added 8 commits February 11, 2021 13:38

Repair chunks, and tests

8abd018

Rerun prettier

41e4d87

Re-add client prefetching

97d4dad

Update snapshots

90c9894

Update snapshots

90b1e22

I hope this works

e82f654

Remove redundant dev server code

0c73485

relock

5879eb7

This was referenced Apr 23, 2021

chore: Test Docusaurus webpack 5 support nextauthjs/next-auth#1826

Merged

chore: Test Docusaurus webpack 5 support mikro-orm/mikro-orm#1716

Merged

slorber mentioned this pull request Apr 26, 2021

chore: Test Docusaurus webpack 5 support demisto/content-docs#616

Closed

slorber added 2 commits April 27, 2021 16:42

add NavbarItem position to types (useful for QuestDB site upgrade to …

cafe2b4

…Webpack5)

Merge branch 'master' into webpack-5

46b1b82

# Conflicts: # packages/docusaurus-init/templates/bootstrap/package.json

slorber added a commit that referenced this pull request Apr 30, 2021

fix ideal-image warning due to missing hash:

fd7aa2b

> Conflict: Multiple assets emit different content to the same filename assets/ideal-img/datagit.100.png see #4089 (comment)

add webpack cache env variable to reduce risk of webpack 5 adoption

867d034

slorber merged commit 05e7250 into facebook:master Apr 30, 2021

RDIL deleted the webpack-5 branch April 30, 2021 16:44

slorber added a commit that referenced this pull request Apr 30, 2021

fix ideal-image warning due to missing hash:

0c859fe

> Conflict: Multiple assets emit different content to the same filename assets/ideal-img/datagit.100.png see #4089 (comment)

slorber mentioned this pull request Apr 30, 2021

feat: migrate webpack file-loader to asset modules #4708

Closed

slorber mentioned this pull request May 11, 2021

Performance - Reduce build time and memory usage #4765

Open

borekb mentioned this pull request May 14, 2021

Hot reload not working correctly (browser scrolls to top) #4794

Closed

favna mentioned this pull request Oct 22, 2021

Dependency of @types/react-loadable causes type conflict issues in 2.0.0-beta.7/8 #5772

Closed

5 tasks done

slorber mentioned this pull request Aug 26, 2024

refactor(core): Restore null-loader #10448

Merged

mrizwanashiq pushed a commit to mrizwanashiq/docusaurus that referenced this pull request Jun 25, 2026

fix ideal-image warning due to missing hash:

ab011e8

> Conflict: Multiple assets emit different content to the same filename assets/ideal-img/datagit.100.png see facebook#4089 (comment)

sparanoid pushed a commit to sparanoid/docusaurus that referenced this pull request Oct 12, 2026

fix ideal-image warning due to missing hash:

b4c8d4d

> Conflict: Multiple assets emit different content to the same filename assets/ideal-img/datagit.100.png see facebook#4089 (comment)

sparanoid pushed a commit to sparanoid/docusaurus that referenced this pull request Oct 12, 2026

fix ideal-image warning due to missing hash:

8d9f573

> Conflict: Multiple assets emit different content to the same filename assets/ideal-img/datagit.100.png see facebook#4089 (comment)

This was referenced Oct 15, 2026

break(core): migrate from file-loader/url-loader to bundler asset modules (AI-assisted) #12651

Merged

refactor: remove the remaining dead code leftovers (AI-assisted) #12751

Merged

slorber mentioned this pull request Oct 23, 2026

chore: clean up stale monorepo tooling config (AI-assisted) #12773

Merged

Navigation Menu

Repository navigation

feat(v2): Webpack 5, PostCSS 8 - #4089

feat(v2): Webpack 5, PostCSS 8#4089
slorber merged 157 commits into
facebook:masterfrom
RDIL:webpack-5

RDIL commented Jan 22, 2021 •

edited by slorber

Loading

Uh oh!

netlify Bot commented Jan 22, 2021 •

edited

Loading

Uh oh!

This comment has been minimized.

This comment has been minimized.

Uh oh!

This comment has been minimized.

This comment has been minimized.

Uh oh!

Uh oh!

github-actions Bot commented Feb 11, 2021 •

edited

Loading

Uh oh!

slorber commented Apr 23, 2021

Uh oh!

juzhiyuan commented Apr 24, 2021

Uh oh!

slorber commented Apr 30, 2021

Uh oh!

RDIL commented Apr 30, 2021

Uh oh!

slorber commented Apr 30, 2021

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

9 participants

Conversation

RDIL commented Jan 22, 2021 • edited by slorber Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Breaking changes

Known issues:

Using persistent caching

Uh oh!

netlify Bot commented Jan 22, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment has been minimized.

This comment has been minimized.

Uh oh!

This comment has been minimized.

This comment has been minimized.

Uh oh!

Uh oh!

github-actions Bot commented Feb 11, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

slorber commented Apr 23, 2021

Uh oh!

juzhiyuan commented Apr 24, 2021

Uh oh!

slorber commented Apr 30, 2021

Uh oh!

RDIL commented Apr 30, 2021

Uh oh!

slorber commented Apr 30, 2021

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

9 participants

RDIL commented Jan 22, 2021 •

edited by slorber

Loading

netlify Bot commented Jan 22, 2021 •

edited

Loading

github-actions Bot commented Feb 11, 2021 •

edited

Loading