[Question] Unnecessary RSC Payload Re-validation on Navigation in Statically Exported Sites (output: 'export')

[imliuruiqi]

Hello Fumadocs team,

First, I want to say thank you for building such a powerful and well-designed documentation tool.

I'm opening this discussion to understand a specific navigation behavior I've observed while investigating the performance of our statically exported docs site (output: 'export'). I've noticed a consistent delay during client-side navigation, and I've managed to isolate the cause.

The Observation

In a statically exported Fumadocs site, when a user clicks a link (e.g., in the sidebar):

1. Prefetching works as expected: On mouse hover(or first loading), the browser correctly prefetches the RSC payload for the target page (e.g., .../page/index.txt?_rsc=abc).
2. Navigation triggers new requests: However, upon clicking the link, the Next.js router sends two new network requests for the same RSC payload, albeit with different _rsc hashes (e.g., .../page/index.txt?_rsc=def and .../page/index.txt?_rsc=ghi).
3. UI transition is blocked: The page transition is blocked until these two requests complete. Even if the server returns a 304 Not Modified, the network round-trip time becomes a noticeable delay in the UI (in our case, ~600ms total).

This behavior seems to prevent the router from using the prefetched data from the cache, forcing it to re-validate with the server on every click.

Comparison with a Pure Next.js App

To confirm this wasn't standard Next.js behavior, I created a minimal Next.js App Router project (without Fumadocs), configured it with output: 'export', and observed its navigation:

1. RSC payload is prefetched on hover.
2. On click, navigation is instantaneous.
3. No new network requests are made. The router correctly uses the prefetched, cached data to render the new page.

Is This an Intentional Feature?

This difference in behavior leads me to believe that a component or hook within the Fumadocs ecosystem might be wrapping next/link or using next/navigation in a way that intentionally forces a data refetch on navigation.

Initially, I thought this might be a recent change, but after testing, I've confirmed this behavior exists in both v15 and v16 of Fumadocs.

My question is: Is this forced re-validation intentional? Is it in place to support a specific dynamic feature, or could it be an unintended side effect that impacts the performance of fully static sites?

For a purely static build, the ideal behavior would be to leverage Next.js's instant navigation by using the prefetched payloads. Any insight you could provide would be greatly appreciated.

Thank you for your time and for this great project!

[fuma-nama]

Need a reproduction, it shouldn't happen nor observed to happen locally

[imliuruiqi]

I created a repo here with minimal config for static export:
https://github.com/imliuruiqi/fumadocs-static-export
and deployed as https://fumadocs-static-export.vercel.app/

[fuma-nama]

Try setting export const revalidate = false on your pages, I think it's a bug of Next.js static export

[imliuruiqi]

tried but not working.

[jigz]

next bug, doesn't look like it'll be fixed soon
vercel/next.js#85374
vercel/next.js#73427

"fix:next-out": "tsx scripts/fix-next-out.ts"

import fs from "node:fs";
import path from "node:path";

const OUT_DIR = path.join(process.cwd(), "out");
if (!(fs.existsSync(OUT_DIR) && fs.statSync(OUT_DIR).isDirectory())) {
  console.error(`Directory not found: ${OUT_DIR}`);
  process.exit(1);
}

const findNextDirs = () => {
  const results = new Set<string>();
  function walk(dir: string) {
    const entries = fs.readdirSync(dir, { withFileTypes: true });
    for (const entry of entries) {
      if (!entry.isDirectory()) {
        continue;
      }
      const full = path.join(dir, entry.name);
      if (entry.name.startsWith("__next.")) {
        results.add(full);
      }
      walk(full);
    }
  }
  walk(OUT_DIR);
  const found = Array.from(results).sort();
  return found;
};

const findFiles = (dir: string): string[] => {
  const files = fs.readdirSync(dir, { withFileTypes: true }).flatMap((e) => {
    const p = path.join(dir, e.name);
    return e.isDirectory() ? findFiles(p) : [p];
  });
  return files;
};

const nextDirs = findNextDirs();
for (const nextDir of nextDirs) {
  const basePath = path.basename(nextDir);
  const dirName = path.dirname(nextDir);
  const nextFiles = findFiles(nextDir);
  for (const nextFile of nextFiles) {
    const relative = path.relative(nextDir, nextFile);
    const fileName = `${basePath}\\${relative}`.replaceAll("\\", ".");
    const filePath = `${dirName}\\${fileName}`;
    const normalizedFilePath = path.normalize(filePath);
    console.log("Copying File:", "\n", nextFile, "\n", normalizedFilePath);
    fs.copyFileSync(nextFile, normalizedFilePath);
  }
}

[imliuruiqi]

thanks but sadly not working...