feat!: appType (spa, mpa, custom), boolean middlewareMode

docs/config/server-options.md

@@ -153,14 +153,12 @@ export default defineConfig({
 
 ## server.middlewareMode
 
-- **Type:** `'ssr' | 'html'`
-
-Create Vite server in middleware mode. (without a HTTP server)
+- **Type:** `boolean`
+- **Default:** `false`
 
-- `'ssr'` will disable Vite's own HTML serving logic so that you should serve `index.html` manually.
-- `'html'` will enable Vite's own HTML serving logic.
+Create Vite server in middleware mode
 
-- **Related:** [SSR - Setting Up the Dev Server](/guide/ssr#setting-up-the-dev-server)
+- **Related:** [appType](./shared-options#apptype), [SSR - Setting Up the Dev Server](/guide/ssr#setting-up-the-dev-server)
 
 - **Example:**
 
@@ -173,14 +171,15 @@ async function createServer() {
 
   // Create Vite server in middleware mode.
   const vite = await createViteServer({
-    server: { middlewareMode: 'ssr' }
+    server: { middlewareMode: true },
+    appType: 'custom'
   })
   // Use vite's connect instance as middleware
   app.use(vite.middlewares)
 
   app.use('*', async (req, res) => {
-    // If `middlewareMode` is `'ssr'`, should serve `index.html` here.
-    // If `middlewareMode` is `'html'`, there is no need to serve `index.html`
+    // If `appType` is `'custom'`, should serve response here.
+    // If `appType` is `'spa'` or `'mpa'`, there is no need to serve `index.html`
     // because Vite will do that.
   })
 }

docs/config/shared-options.md

@@ -336,9 +336,15 @@ Env variables starts with `envPrefix` will be exposed to your client source code
 `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 `''`.
 :::
 
-## spa
+## appType
 
-- **Type:** `boolean`
-- **Default:** `true`
+- **Type:** `'spa' | 'mpa' | 'custom'`
+- **Default:** `'spa'`
+
+Whether your application is a Single Page Application (SPA), a [Multi Page Application (MPA)](../guide/build#multi-page-app), or Custom Application (SSR and frameworks with custom HTML handling):
+
+- `'spa'`: include SPA fallback middleware and configure [sirv](https://github.com/lukeed/sirv) with `single: true` in preview
+- `'mpa'`: only include non-SPA HTML middlewares
+- `'custom'`: don't include HTML middlewares
 
-Whether your application is a Single Page Application (SPA). Set to `false` for other kinds of apps like MPAs. Learn more in Vite's [SSR guide](/guide/ssr#vite-cli).
+Learn more in Vite's [SSR guide](/guide/ssr#vite-cli). Related: [`server.middlewareMode`](./server-options#servermiddlewaremode).

docs/guide/ssr.md

@@ -78,9 +78,10 @@ async function createServer() {
   // serving logic and let the parent server take control.
   //
   // In middleware mode, if you want to use Vite's own HTML serving logic
-  // use `'html'` as the `middlewareMode` (ref https://vitejs.dev/config/#server-middlewaremode)
+  // use `appType: 'spa' | 'mpa'`
   const vite = await createViteServer({
-    server: { middlewareMode: 'ssr' }
+    server: { middlewareMode: true },
+    appType: 'custom'
   })
   // use vite's connect instance as middleware
   app.use(vite.middlewares)
@@ -267,11 +268,7 @@ In some cases like `webworker` runtimes, you might want to bundle your SSR build
 
 ## Vite CLI
 
-The CLI commands `$ vite dev` and `$ vite preview` can also be used for SSR apps:
-
-1. Add your SSR middleware to the development server with [`configureServer`](/guide/api-plugin#configureserver) and to the preview server with [`configurePreviewServer`](/guide/api-plugin#configurepreviewserver).
-   :::tip Note
-   Use a post hook so that your SSR middleware runs _after_ Vite's middlewares.
-   :::
-
-2. Set `config.spa` to `false`. This switches the development and preview server from SPA mode to SSR/MPA mode.
+The CLI commands `$ vite dev` and `$ vite preview` can also be used for SSR apps you can add your SSR middleware to the development server with [`configureServer`](/guide/api-plugin#configureserver) and to the preview server with [`configurePreviewServer`](/guide/api-plugin#configurepreviewserver).
+:::tip Note
+Use a post hook so that your SSR middleware runs _after_ Vite's middlewares.
+:::

packages/vite/src/node/config.ts

@@ -51,6 +51,13 @@ export interface ConfigEnv {
   mode: string
 }
 
+/**
+ * spa: include SPA fallback middleware and configure sirv with `single: true` in preview
+ * mpa: only include non-SPA HTML middlewares
+ * custom: don't include HTML middlewares
+ */
+export type AppType = 'spa' | 'mpa' | 'custom'
+
 export type UserConfigFn = (env: ConfigEnv) => UserConfig | Promise<UserConfig>
 export type UserConfigExport = UserConfig | Promise<UserConfig> | UserConfigFn
 
@@ -211,11 +218,12 @@ export interface UserConfig {
     >
   }
   /**
-   * Whether your application is a Single Page Application (SPA). Set to `false`
-   * for other kinds of apps like MPAs.
-   * @default true
+   * Whether your application is a Single Page Application (SPA),
+   * a Multi-Page Application (MPA), or Custom Application (SSR
+   * and frameworks with custom HTML handling)
+   * @default 'spa'
    */
-  spa?: boolean
+  appType?: AppType
 }
 
 export interface ExperimentalOptions {
@@ -292,7 +300,7 @@ export type ResolvedConfig = Readonly<
     /** @internal */
     packageCache: PackageCache
     worker: ResolveWorkerOptions
-    spa: boolean
+    appType: AppType
   }
 >
 
@@ -536,7 +544,10 @@ export async function resolveConfig(
       }
     },
     worker: resolvedWorkerOptions,
-    spa: config.spa ?? true
+    appType:
+      config.appType ?? config?.server?.middlewareMode === 'ssr'
+        ? 'custom'
+        : 'spa'
   }
 
   // flat config.worker.plugin

packages/vite/src/node/preview.ts

@@ -104,7 +104,7 @@ export async function preview(
     sirv(distDir, {
       etag: true,
       dev: true,
-      single: config.spa
+      single: config.appType === 'spa'
     })
   )
 

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

@@ -100,6 +100,7 @@ export interface ServerOptions extends CommonServerOptions {
 
 export interface ResolvedServerOptions extends ServerOptions {
   fs: Required<FileSystemServeOptions>
+  middlewareMode: boolean
 }
 
 export interface FileSystemServeOptions {
@@ -268,10 +269,7 @@ export async function createServer(
     config.server.https,
     config.cacheDir
   )
-  let { middlewareMode } = serverConfig
-  if (middlewareMode === true) {
-    middlewareMode = 'ssr'
-  }
+  const { middlewareMode } = serverConfig
 
   const middlewares = connect() as Connect.Server
   const httpServer = middlewareMode
@@ -487,10 +485,8 @@ export async function createServer(
   middlewares.use(serveRawFsMiddleware(server))
   middlewares.use(serveStaticMiddleware(root, server))
 
-  const isMiddlewareMode = middlewareMode && middlewareMode !== 'html'
-
   // spa fallback
-  if (config.spa && !isMiddlewareMode) {
+  if (config.appType === 'spa' && !middlewareMode) {
     middlewares.use(spaFallbackMiddleware(root))
   }
 
@@ -499,12 +495,12 @@ export async function createServer(
   // serve custom content instead of index.html.
   postHooks.forEach((fn) => fn && fn())
 
-  if (config.spa && !isMiddlewareMode) {
+  if (config.appType !== 'custom' && !middlewareMode) {
     // transform index.html
     middlewares.use(indexHtmlMiddleware(server))
   }
 
-  if (!isMiddlewareMode) {
+  if (!middlewareMode) {
     // handle 404s
     // Keep the named function. The name is visible in debug logs via `DEBUG=connect:dispatcher ...`
     middlewares.use(function vite404Middleware(_, res) {
@@ -514,7 +510,7 @@ export async function createServer(
   }
 
   // error handler
-  middlewares.use(errorMiddleware(server, !!middlewareMode))
+  middlewares.use(errorMiddleware(server, middlewareMode))
 
   const initOptimizer = async () => {
     if (isDepsOptimizerEnabled(config)) {
@@ -652,7 +648,8 @@ export function resolveServerOptions(
 ): ResolvedServerOptions {
   const server: ResolvedServerOptions = {
     preTransformRequests: true,
-    ...(raw as ResolvedServerOptions)
+    ...(raw as ResolvedServerOptions),
+    middlewareMode: !!raw?.middlewareMode
   }
   let allowDirs = server.fs?.allow
   const deny = server.fs?.deny || ['.env', '.env.*', '*.{crt,pem}']

playground/json/server.js

@@ -20,14 +20,15 @@ async function createServer(
     root,
     logLevel: isTest ? 'error' : 'info',
     server: {
-      middlewareMode: 'ssr',
+      middlewareMode: true,
       watch: {
         // During tests we edit the files too fast and sometimes chokidar
         // misses change events, so enforce polling for consistency
         usePolling: true,
         interval: 100
       }
     },
+    appType: 'custom',
     json: {
       stringify: true
     }

playground/optimize-missing-deps/server.js

@@ -17,11 +17,12 @@ async function createServer(root = process.cwd(), hmrPort) {
     root,
     logLevel: isTest ? 'error' : 'info',
     server: {
-      middlewareMode: 'ssr',
+      middlewareMode: true,
       hmr: {
         port: hmrPort
       }
-    }
+    },
+    appType: 'custom'
   })
   app.use(vite.middlewares)
 

playground/ssr-deps/server.js

@@ -22,7 +22,7 @@ export async function createServer(root = process.cwd(), hmrPort) {
     root,
     logLevel: isTest ? 'error' : 'info',
     server: {
-      middlewareMode: 'ssr',
+      middlewareMode: true,
       watch: {
         // During tests we edit the files too fast and sometimes chokidar
         // misses change events, so enforce polling for consistency
@@ -32,7 +32,8 @@ export async function createServer(root = process.cwd(), hmrPort) {
       hmr: {
         port: hmrPort
       }
-    }
+    },
+    appType: 'custom'
   })
   // use vite's connect instance as middleware
   app.use(vite.middlewares)

playground/ssr-html/server.js

@@ -37,7 +37,7 @@ export async function createServer(root = process.cwd(), hmrPort) {
     root,
     logLevel: isTest ? 'error' : 'info',
     server: {
-      middlewareMode: 'ssr',
+      middlewareMode: true,
       watch: {
         // During tests we edit the files too fast and sometimes chokidar
         // misses change events, so enforce polling for consistency
@@ -47,7 +47,8 @@ export async function createServer(root = process.cwd(), hmrPort) {
       hmr: {
         port: hmrPort
       }
-    }
+    },
+    appType: 'custom'
   })
   // use vite's connect instance as middleware
   app.use(vite.middlewares)

playground/ssr-pug/server.js

@@ -31,7 +31,7 @@ export async function createServer(root = process.cwd(), hmrPort) {
     root,
     logLevel: isTest ? 'error' : 'info',
     server: {
-      middlewareMode: 'ssr',
+      middlewareMode: true,
       watch: {
         // During tests we edit the files too fast and sometimes chokidar
         // misses change events, so enforce polling for consistency
@@ -41,7 +41,8 @@ export async function createServer(root = process.cwd(), hmrPort) {
       hmr: {
         port: hmrPort
       }
-    }
+    },
+    appType: 'custom'
   })
   // use vite's connect instance as middleware
   app.use(vite.middlewares)

playground/ssr-react/server.js

@@ -33,7 +33,7 @@ export async function createServer(
       root,
       logLevel: isTest ? 'error' : 'info',
       server: {
-        middlewareMode: 'ssr',
+        middlewareMode: true,
         watch: {
           // During tests we edit the files too fast and sometimes chokidar
           // misses change events, so enforce polling for consistency
@@ -43,7 +43,8 @@ export async function createServer(
         hmr: {
           port: hmrPort
         }
-      }
+      },
+      appType: 'custom'
     })
     // use vite's connect instance as middleware
     app.use(vite.middlewares)

playground/ssr-vue/server.js

@@ -37,7 +37,7 @@ export async function createServer(
       root,
       logLevel: isTest ? 'error' : 'info',
       server: {
-        middlewareMode: 'ssr',
+        middlewareMode: true,
         watch: {
           // During tests we edit the files too fast and sometimes chokidar
           // misses change events, so enforce polling for consistency
@@ -47,7 +47,8 @@ export async function createServer(
         hmr: {
           port: hmrPort
         }
-      }
+      },
+      appType: 'custom'
     })
     // use vite's connect instance as middleware
     app.use(vite.middlewares)