feat: spa option, preview and dev for MPA and SSR apps

docs/config/index.md

@@ -462,6 +462,13 @@ export default defineConfig(({ command, mode }) => {
   `envPrefix` should not be set as `''`, which will expose all your env variables and cause unexpected leaking of of sensitive information. Vite will throw error when detecting `''`.
   :::
 
+### isSPA
+
+- **Type:** `boolean`
+- **Default:** `true`
+
+  This toggles the SPA catch-all routing of the development and preview server: by default, all URLs are rendered to the same single page (in order to enable SPA client-side routing). For SSR and MPA apps, this behavior can be disabled by setting `isSPA` to `false`.
+
 ## Server Options
 
 ### server.host

packages/vite/src/node/config.ts

@@ -204,6 +204,15 @@ export interface UserConfig {
       'plugins' | 'input' | 'onwarn' | 'preserveEntrySignatures'
     >
   }
+  /**
+   * Whether the app is a SPA.
+   * This toggles the SPA catch-all routing of the development and preview
+   * server: by default, all URLs are rendered to the same single page (in order
+   * to enable SPA client-side routing). For SSR and MPA apps, this behavior can
+   * be disabled by setting `isSPA` to `false`.
+   * @default true
+   */
+  isSPA?: boolean
 }
 
 export interface ExperimentalOptions {
@@ -469,6 +478,8 @@ export async function resolveConfig(
 
   const optimizeDeps = config.optimizeDeps || {}
 
+  config.isSPA ??= true
+
   const resolved: ResolvedConfig = {
     ...config,
     configFile: configFile ? normalizePath(configFile) : undefined,

packages/vite/src/node/preview.ts

@@ -1,5 +1,6 @@
 import path from 'path'
 import type * as http from 'http'
+import fs from 'fs'
 import sirv from 'sirv'
 import connect from 'connect'
 import type { Connect } from 'types/connect'
@@ -97,19 +98,42 @@ export async function preview(
 
   app.use(compression())
 
+  const { isSPA } = config
+
+  if (isSPA) {
+    // We need to apply the plugins' server post hooks before `sirv()`. (Because
+    // `sirv(_, { single: true })` catches all routes and plugin middlewares
+    // would never run.)
+    postHooks.forEach((fn) => fn && fn())
+  }
+
   // static assets
   const distDir = path.resolve(config.root, config.build.outDir)
   app.use(
     config.base,
     sirv(distDir, {
       etag: true,
       dev: true,
-      single: true
+      single: isSPA
     })
   )
 
-  // apply post server hooks from plugins
-  postHooks.forEach((fn) => fn && fn())
+  if (!isSPA) {
+    // We apply the plugins' server post hooks after `sirv()` so that `sirv()`
+    // can serve pre-rendered pages before any SSR middleware.
+    postHooks.forEach((fn) => fn && fn())
+
+    // 404 handling (this simulates what most static hosts do)
+    app.use(config.base, (_, res, next) => {
+      const file = path.join(distDir, './404.html')
+      if (fs.existsSync(file)) {
+        res.statusCode = 404
+        res.end(fs.readFileSync(file))
+      } else {
+        next()
+      }
+    })
+  }
 
   const options = config.preview
   const hostname = resolveHostname(options.host)

packages/vite/src/node/server/index.ts

@@ -503,20 +503,25 @@ export async function createServer(
   middlewares.use(serveRawFsMiddleware(server))
   middlewares.use(serveStaticMiddleware(root, server))
 
-  // spa fallback
-  if (!middlewareMode || middlewareMode === 'html') {
-    middlewares.use(spaFallbackMiddleware(root))
-  }
-
-  // run post config hooks
-  // This is applied before the html middleware so that user middleware can
-  // serve custom content instead of index.html.
+  // We need to apply post server hooks before `spaFallbackMiddleware()`.
+  // (Because `spaFallbackMiddleware()` catches all routes and plugin
+  // middlewares would never run.)
   postHooks.forEach((fn) => fn && fn())
 
-  if (!middlewareMode || middlewareMode === 'html') {
+  const isMiddlewareModeSSR = middlewareMode && middlewareMode !== 'html'
+
+  if (config.isSPA && !isMiddlewareModeSSR) {
+    // SPA catch-all fallback routing
+    middlewares.use(spaFallbackMiddleware(root))
     // transform index.html
     middlewares.use(indexHtmlMiddleware(server))
-    // handle 404s
+  }
+
+  // Handle 404s.
+  // We keep 404 handling when `config.isSPA === false` because some SSR tools,
+  // such as vite-plugin-ssr, cannot always render 404 pages. (E.g. if the
+  // vite-plugin-ssr user didn't define a `_error.page.js`.)
+  if (!isMiddlewareModeSSR) {
     // Keep the named function. The name is visible in debug logs via `DEBUG=connect:dispatcher ...`
     middlewares.use(function vite404Middleware(_, res) {
       res.statusCode = 404