Choosing the Right Build Mode for Quasar: SPA, SSR, and SSG Comparison

The Delivery Dilemma: SEO vs. Simplicity

When building a Vue-based application with Quasar, the most critical architectural decision is the Build Mode. This choice determines how your HTML is generated, how search engines index your content, and how users perceive the initial load speed. Choosing the wrong mode often leads to expensive refactors when a project moves from a private dashboard (where SEO is irrelevant) to a public-facing product (where First Contentful Paint is a business KPI).

The primary goal is to balance Time to Interactive (TTI)—the time it takes for a page to become fully functional—with Search Engine Optimization (SEO) and infrastructure costs.

Comparing Quasar Build Modes

Quasar allows you to target multiple modes from a single codebase, but the runtime behavior and hosting requirements differ significantly. The following table compares the primary web-based modes for Quasar 2.x (Vue 3).

Feature	SPA (Single Page App)	SSR (Server-Side Rendering)	SSG (Static Site Generation)
HTML Generation	Client-side (Browser)	On-demand (Node.js Server)	At Build Time (Static Files)
SEO Capability	Limited (Client-rendered)	Excellent	Excellent
First Paint Speed	Slower (Blank screen until JS)	Fast (Pre-rendered HTML)	Fastest (Static HTML)
Hosting Requirement	Static Host / CDN	Node.js Runtime	Static Host / CDN
Dynamic Content	Real-time	Real-time	Requires Rebuild/Incremental

Engineering Trade-offs

SPA: The Low-Overhead Choice

An SPA is the simplest to deploy. Since the server only provides a shell HTML file and a JavaScript bundle, you can host it on any static provider (S3, Netlify, Vercel). However, users on slow networks see a blank screen while the bundle downloads and executes, and crawlers may struggle to index content that relies heavily on asynchronous API calls.

SSR: The Performance Powerhouse

SSR renders the page on a Node.js server for every request. This eliminates the "blank screen" problem and provides full HTML to search engines. The trade-off is Hydration: the process where Vue takes over the static HTML and makes it interactive. If the server-rendered HTML differs from what the client expects (e.g., using Date.now() in a template), you will encounter "Hydration Mismatch" warnings in the console.

SSG: The Static Compromise

SSG provides the SEO and speed of SSR but removes the need for a live Node.js server. It pre-renders every route into a static HTML file during the build process. This is ideal for blogs or marketing sites, but impractical for apps with thousands of dynamic user-generated pages.

PWA: The Layered Enhancement

Progressive Web App (PWA) mode is not a replacement for the above but an addition. It adds a Service Worker—a script that runs in the background to cache assets and enable offline functionality. You can combine PWA with SPA, SSR, or SSG.

Implementation: Enabling SSR and PWA

To transition a project to SSR and PWA, you must modify the configuration and handle server-side logic. Run these commands in your project root using the Quasar CLI.

1. Add the Modes

# Add SSR mode
quasar mode add ssr

# Add PWA mode
quasar mode add pwa

2. Configure Server-Side Logic

In an SSR environment, some code runs only on the server and some only on the client. Use the process.env.SERVER or process.env.CLIENT flags in your boot files or components to prevent crashes (e.g., accessing window or document on the server).

// src/boot/example.js
export default ({ ssrMode }) => {
  if (ssrMode) {
    console.log('Running on the server');
  } else {
    console.log('Running in the browser');
    // Safe to access window.localStorage here
  }
}

3. Validation and Testing

To verify that SSR is working correctly and not falling back to client-side rendering, follow these steps:

• Inspect Source: Right-click the page in the browser and select View Page Source. If you see your actual content (not just <div id="q-app"></div>), SSR is active.
• Network Throttling: Open Chrome DevTools > Network tab. Set throttling to "Slow 3G". Refresh the page. If the text appears before the loading spinner finishes, the first paint is being handled by the server.
• Hydration Check: Open the Console. Ensure there are no warnings stating "Hydration completed but contains mismatches".

Limitations and Risks

• State Serialization: When using SSR, any data fetched on the server must be serialized and sent to the client to prevent the client from re-fetching the same data and causing a flicker.
• PWA Caching: PWA service workers can cache assets aggressively. If you deploy a new version, users may see old content until the service worker updates and the page is refreshed.
• Memory Leaks: Because the Node.js server stays alive across multiple requests, global variables in SSR mode can lead to memory leaks or data leaking between different users' sessions.

Rollback Procedure

If SSR introduces too much complexity or server latency, you can revert to SPA mode by removing the SSR configuration and rebuilding:

# Build as SPA instead of SSR
quasar build -m spa