VitePress MPA Mode

VitePress is fundamentally a Single Page Application (SPA) that performs page navigation through client-side routing after initial loading, without full page refreshes. However, in certain specific scenarios, you may want your website to behave like a traditional Multi-Page Application (MPA), where each navigation triggers a complete page load.

VitePress provides the mpa: true option to enable this mode.

When to Use MPA Mode?

• Extreme Lightweight: If you want the JavaScript payload for each page to be as small as possible, without loading Vue router and other SPA-related client-side logic.
• Isolated Environments: When pages are completely independent, don't need to share state, and you want to avoid the potential complexity of client-side scripts.
• Special Embedding Scenarios: When VitePress pages need to be embedded into a completely different website or application, using MPA mode can reduce potential style and script conflicts.

How to Enable

In your .vitepress/config.js configuration file, set mpa: true.

// .vitepress/config.js
export default {
  // ...other configuration
  mpa: true
}

Behavior Changes in MPA Mode

After enabling MPA mode, VitePress's behavior will undergo the following key changes:

1. Disable Client-side Routing: Vue Router will no longer be bundled into the client build. All page navigation will trigger traditional browser full page loads.
2. Smaller JS Bundle: Since there's no routing and SPA-related logic, the initial JavaScript bundle for each page will be significantly smaller.
3. No State Retention Between Pages: Since every navigation is a full page refresh, Vue component in-memory state (such as ref or reactive values) won't be preserved after page jumps.

Considerations

• User Experience: Page transitions in MPA mode may have white screen flickers and aren't as smooth as SPA mode. For content-focused documentation sites with less interactivity, this is usually acceptable.
• Data Persistence: If you need to share data between pages, you need to rely on traditional Web storage mechanisms such as localStorage or sessionStorage instead of Vue's in-memory state management.
• Preloading: Some performance optimizations in VitePress's SPA mode, such as preloading viewport-linked page resources, won't be available in MPA mode.

Summary

MPA mode is an "escape hatch" provided by VitePress that allows you to return to a more traditional web approach when needed. It sacrifices the smooth navigation experience of SPA for smaller client-side payloads and simpler page lifecycle.

For the vast majority of documentation sites, the default SPA mode is the best choice. Only consider enabling this mode when you clearly understand why you need MPA and are willing to accept the changes it brings.