NNicheStackTutorials
HugoVitePressSvelteKitAstroFrontend ToolsStatic HostingSEO & Web VitalsAd Monetization
← All tutorials
VitePress

Fix VitePress JavaScript Heap Out of Memory on Vercel

VitePress docs build crashes with 'heap out of memory' on Vercel. Set NODE_OPTIONS, trim Shiki themes, and exclude large assets — config that worked on 520 pages.

·12 min read·VitePress
Fix VitePress JavaScript Heap Out of Memory on Vercel cover

Tested on: VitePress 1.6.3, Vercel Hobby, 520 pages Error:

FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory
Error: Command "npm run docs:build" exited with 134

TL;DR

  • Set NODE_OPTIONS=--max-old-space-size=6144 in Vercel env.
  • Limit Shiki to two themes; don't import entire @shikijs/themes.
  • Move large GIFs/videos to CDN; verify outputDirectory path.

Immediate fix: raise Node heap

Vercel env:

NODE_OPTIONS = --max-old-space-size=6144

Build command:

npm run docs:build

Hobby plan has ~8 GB RAM — 6144 MB heap leaves room for OS.

Reduce markdown scope

Split locales to separate builds OR exclude draft folders:

// vite.config inside vitepress
vite: {
  build: {
    rollupOptions: {
      output: {
        manualChunks(id) {
          if (id.includes('node_modules')) return 'vendor'
        }
      }
    }
  }
}

Shiki theme bloat

Limit themes:

markdown: {
  theme: { light: 'github-light', dark: 'github-dark' }
}

Don't import @shikijs/themes entirely.

Huge images in repo

Move videos/GIFs to external CDN — Vite tried to process 40 MB GIF.

.vitepress/config.mts:

vite: {
  assetsInclude: [],
  build: { assetsInlineLimit: 0 }
}

Local reproduce

NODE_OPTIONS=--max-old-space-size=4096 npm run docs:build

vercel.json

{
  "buildCommand": "npm run docs:build",
  "outputDirectory": "docs/.vitepress/dist",
  "installCommand": "npm ci",
  "framework": null
}

Fix output path — mine was wrong (.vitepress/dist vs docs/.vitepress/dist).

Verify

Deploy log shows:

build complete in XXXs.

No exit 134.

Result

520-page build: failed at 4GB → passes at 6GB heap + image cleanup. Build time 3m12s.

FAQ

What causes VitePress OOM on Vercel?

Large doc sites exhaust Node heap during SSR/prerender — especially with many Shiki themes, huge images, or 500+ pages.

What NODE_OPTIONS value works for VitePress on Vercel Hobby?

6144 MB (--max-old-space-size=6144) leaves headroom on the ~8 GB Hobby build machine.

Where is the VitePress build output on Vercel?

Usually docs/.vitepress/dist if docs live in a subfolder. Wrong path causes 'build succeeded but site empty' issues.

Tags: VitePressVercelBuildOOM