fix(core): evict the client and server persistent caches together, to avoid a build hang

packages/docusaurus/src/webpack/__tests__/base.test.ts

@@ -161,7 +161,7 @@ describe('base webpack config', () => {
       vi.unstubAllEnvs();
     });
 
-    async function getCacheVersion({
+    async function getCache({
       isServer = false,
       siteMetadata = props.siteMetadata,
     }: {
@@ -174,7 +174,15 @@ describe('base webpack config', () => {
         minify: true,
         configureWebpackUtils: await createTestConfigureWebpackUtils(),
       });
-      return (config.cache as {version: string}).version;
+      // Docusaurus bundler configs are typed with Webpack types
+      return config.cache as unknown as {
+        version: string;
+        buildDependencies: string[];
+      };
+    }
+
+    async function getCacheVersion(params?: Parameters<typeof getCache>[0]) {
+      return (await getCache(params)).version;
     }
 
     // Browserslist reads this env variable before any config file
@@ -232,14 +240,32 @@ describe('base webpack config', () => {
       expect(oldNodeVersion).not.toBe(newNodeVersion);
     });
 
-    // TODO a warm client cache with a cold server cache hangs the build
-    // See https://github.com/meta/docusaurus/pull/13034
-    it('keeps the client cache when the server Node.js target changes', async () => {
-      stubServerNodeTarget('24.11.1');
-      const oldNodeVersion = await getCacheVersion({isServer: false});
-      stubServerNodeTarget('24.11.2');
-      const newNodeVersion = await getCacheVersion({isServer: false});
-      expect(oldNodeVersion).toBe(newNodeVersion);
+    // A warm client cache with a cold server cache hangs the build
+    // See https://github.com/meta/docusaurus/pull/13035
+    describe('evicts the client and server caches together', () => {
+      it('evicts the client cache when the server Node.js target changes', async () => {
+        stubServerNodeTarget('24.11.1');
+        const oldNodeVersion = await getCacheVersion({isServer: false});
+        stubServerNodeTarget('24.11.2');
+        const newNodeVersion = await getCacheVersion({isServer: false});
+        expect(oldNodeVersion).not.toBe(newNodeVersion);
+      });
+
+      it('evicts the server cache when the client browsers change', async () => {
+        stubBrowserslistQuery('chrome 90');
+        const oldBrowsersVersion = await getCacheVersion({isServer: true});
+        stubBrowserslistQuery('baseline widely available');
+        const baselineVersion = await getCacheVersion({isServer: true});
+        expect(oldBrowsersVersion).not.toBe(baselineVersion);
+      });
+
+      it('uses the same build dependencies for the client and server caches', async () => {
+        const clientCache = await getCache({isServer: false});
+        const serverCache = await getCache({isServer: true});
+        expect(clientCache.buildDependencies).toEqual(
+          serverCache.buildDependencies,
+        );
+      });
     });
 
     it('is evicted when a plugin package version changes', async () => {

packages/docusaurus/src/webpack/base.ts

@@ -118,7 +118,11 @@ export async function createBaseConfig({
       // Changing the target browsers or Node.js version must evict the cache
       // The same Browserslist queries can match other browsers over time and
       // after data upgrades, for example "baseline widely available"
-      getTargets({isServer}),
+      // The client and server caches must be evicted together, or the MDX
+      // cross-compiler cache hangs the build
+      // See https://github.com/meta/docusaurus/pull/13035
+      getTargets({isServer: false}),
+      getTargets({isServer: true}),
       // The plugin code computing loader options is not a build dependency
       // Upgrading a third-party plugin must evict the cache
       siteMetadata.pluginVersions,
@@ -134,7 +138,9 @@ export async function createBaseConfig({
   function getCacheBuildDependencies(): string[] {
     return [
       __filename,
-      path.join(__dirname, isServer ? 'server.js' : 'client.js'),
+      // Both: the client and server caches must be evicted together
+      path.join(__dirname, 'client.js'),
+      path.join(__dirname, 'server.js'),
       // Docusaurus config changes can affect MDX/JSX compilation, so we'd
       // rather evict the cache.
       // See https://github.com/questdb/questdb.io/issues/493