JavaScript heap out of memory when building large documentation sites with extensive mathematical formulas

[cell-juicy]

Describe the bug

When attempting to build my documentation site (containing thousands of markdown notes with extensive mathematical formulas) using VitePress, the build process fails with a JavaScript heap out-of-memory error.

What I did:

1. Development server (vitepress dev) runs successfully
2. Production build (vitepress build) consistently fails with OOM error
3. Tried increasing Node.js memory limit to 8GB as suggested in common solutions
4. Build still fails with similar memory error.

What I don't know:

• Why development mode works but production build fails
• I tried splitting the file into two parts of similar size and executing the deploy command separately, and both build processes completed successfully. Is the problem simply because the site has too many files?

Console output of failed build command:

$ node --max-old-space-size=8192 node_modules/vitepress/bin/vitepress.js build docs

  vitepress v1.6.3


<--- Last few GCs --->

[7244:0000027693210080]   803322 ms: Mark-Compact (reduce) 8046.6 (8237.9) -> 8004.1 (8189.2) MB, 68426.88 / 0.00 ms  (average mu = 0.144, current mu = 0.012) allocation failure; GC in old space requested
[7244:0000027693210080]   869959 ms: Mark-Compact (reduce) 8050.2 (8235.2) -> 8004.0 (8188.7) MB, 65427.66 / 0.00 ms  (average mu = 0.087, current mu = 0.018) allocation failure; GC in old space requested


<--- JS stacktrace --->

FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory
----- Native stack trace -----

 1: 00007FF7D94D39EB node::SetCppgcReference+18459
 2: 00007FF7D9443238 DSA_meth_get_flags+93160
 3: 00007FF7D9EBC771 v8::Isolate::ReportExternalAllocationLimitReached+65
 4: 00007FF7D9EA5EC8 v8::Function::Experimental_IsNopFunction+1336
 5: 00007FF7D9D07970 v8::Platform::SystemClockTimeMillis+659328
 6: 00007FF7D9D13BF3 v8::Platform::SystemClockTimeMillis+709123
 7: 00007FF7D9D11554 v8::Platform::SystemClockTimeMillis+699236
 8: 00007FF7D9D04690 v8::Platform::SystemClockTimeMillis+646304
 9: 00007FF7D9D19D0A v8::Platform::SystemClockTimeMillis+733978
10: 00007FF7D9D1A587 v8::Platform::SystemClockTimeMillis+736151
11: 00007FF7D9D231BE v8::Platform::SystemClockTimeMillis+772046
12: 00007FF7D9D33D0A v8::Platform::SystemClockTimeMillis+840474
13: 00007FF7D9D387D8 v8::Platform::SystemClockTimeMillis+859624
14: 00007FF7D9AAF862 v8::base::Thread::StartSynchronously+372274
15: 00007FF7D99FC8FF v8::PropertyDescriptor::value+12159
16: 00007FF7D99FC3B7 v8::PropertyDescriptor::value+10807
17: 00007FF7D99D84D2 v8::CodeEvent::GetFunctionName+46994
18: 00007FF7D9F6E0FE v8::PropertyDescriptor::writable+678094
19: 00007FF7D9FE437C v8::PropertyDescriptor::writable+1162060
20: 00007FF7D9EDF6A0 v8::PropertyDescriptor::writable+93808
21: 00007FF75A15644B

I'm seeking assistance from the VitePress maintainers to diagnose and resolve this issue.(I do not currently plan to submit a PR for this issue as I lack the technical understanding of VitePress internals required to fix it.)

Reproduction

Steps to reproduce:

1. Clone the reproduction repository:

   git clone https://github.com/cell-juicy/bug-demo
   cd bug-demo

2. Install dependencies:

   npm install

3. Run the build command (either format works):

   node --max-old-space-size=8192 node_modules/vitepress/bin/vitepress.js build docs
   # OR
   npm run docs:build

4. Observe the JavaScript heap out-of-memory error after several minutes of processing

Live reproduction:

• StackBlitz demo: https://stackblitz.com/~/github.com/cell-juicy/bug-demo
• GitHub repository: https://github.com/cell-juicy/bug-demo

Expected behavior

The production build should complete successfully without JavaScript heap out of memory errors.(Of course, it would be nice if the production build was faster)

System Info

System:
    OS: Windows 11 10.0.26100
    CPU: (8) x64 Intel(R) Core(TM) i5-10210U CPU @ 1.60GHz
    Memory: 1.04 GB / 7.74 GB
  Binaries:
    Node: 20.17.0 - D:\Program Files\nodejs\node.EXE
    npm: 11.3.0 - D:\Program Files\nodejs\npm.CMD
  npmPackages:
    vitepress: latest => 1.6.3

Additional context

I searched for existing VitePress issues using the keyword "out of memory" but didn't seem to find any reports that matched my specific situation.

Validations

• Check if you're on the latest VitePress version.
• Follow our Code of Conduct
• Read the docs.
• Check that there isn't already an issue that reports the same bug to avoid creating a duplicate.

[brc-dd]

Might be related to #4415.

You can try running with higher max-old-space-size like 32GB (your physical memory doesn't matter, it will use swap in that case).

Or use some other framework that supports ISR for example.

[cell-juicy]

Hi @brc-dd , thanks for your advice - I successfully deployed my VitePress project locally using your console command (it took a little while though)! 😊 I'd like to ask if this problem is due to the large size of my project file, or if it could be a bug with VitePress/markdown-it-mathjax3?

[brc-dd]

Hard to tell without proper profiling. It isn't with markdown-it-mathjax3. I had tried changing it with katex and other mathajax plugins. All of them were failing.