feat: support serving index.html in middleware mode (#2871)

* feat: support for serving `index.html` in middleware mode

* docs: document `server.middlewareMode`

docs/config/index.md

@@ -430,6 +430,42 @@ export default async ({ command, mode }) => {
 
   File system watcher options to pass on to [chokidar](https://github.com/paulmillr/chokidar#api).
 
+### server.middlewareMode
+
+- **Type:** `'ssr' | 'html'`
+
+  Create Vite server in middleware mode. (without a HTTP server)
+
+  - `'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.
+
+- **Related:** [SSR - Setting Up the Dev Server](/guide/ssr#setting-up-the-dev-server)
+
+- **Example:**
+```js
+const express = require('express')
+const { createServer: createViteServer } = require('vite')
+
+async function createServer() {
+  const app = express()
+
+  // Create vite server in middleware mode.
+  const vite = await createViteServer({
+    server: { middlewareMode: 'ssr' }
+  })
+  // 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`
+    // because Vite will do that.
+  })
+}
+
+createServer()
+```
+
 ### server.fsServe.strict
 
 - **Experimental**

docs/guide/ssr.md

@@ -75,8 +75,11 @@ async function createServer() {
 
   // Create vite server in middleware mode. This disables Vite's own HTML
   // serving logic and let the parent server take control.
+  //
+  // If you want to use Vite's own HTML serving logic (using Vite as
+  // a development middleware), using 'html' instead.
   const vite = await createViteServer({
-    server: { middlewareMode: true }
+    server: { middlewareMode: 'ssr' }
   })
   // use vite's connect instance as middleware
   app.use(vite.middlewares)

packages/playground/ssr-react/server.js

@@ -26,7 +26,7 @@ async function createServer(
       root,
       logLevel: isTest ? 'error' : 'info',
       server: {
-        middlewareMode: true,
+        middlewareMode: 'ssr',
         watch: {
           // During tests we edit the files too fast and sometimes chokidar
           // misses change events, so enforce polling for consistency

packages/playground/ssr-vue/server.js

@@ -31,7 +31,7 @@ async function createServer(
       root,
       logLevel: isTest ? 'error' : 'info',
       server: {
-        middlewareMode: true,
+        middlewareMode: 'ssr',
         watch: {
           // During tests we edit the files too fast and sometimes chokidar
           // misses change events, so enforce polling for consistency

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

@@ -116,7 +116,7 @@ export interface ServerOptions {
   /**
    * Create Vite dev server to be used as a middleware in an existing server
    */
-  middlewareMode?: boolean
+  middlewareMode?: boolean | 'html' | 'ssr'
   /**
    * Prepend this folder to http requests, for use when proxying vite as a subfolder
    * Should start and end with the `/` character
@@ -300,8 +300,11 @@ export async function createServer(
   const config = await resolveConfig(inlineConfig, 'serve', 'development')
   const root = config.root
   const serverConfig = config.server
-  const middlewareMode = !!serverConfig.middlewareMode
   const httpsOptions = await resolveHttpsConfig(config)
+  let { middlewareMode } = serverConfig
+  if (middlewareMode === true) {
+    middlewareMode = 'ssr'
+  }
 
   const middlewares = connect() as Connect.Server
   const httpServer = middlewareMode
@@ -485,7 +488,7 @@ export async function createServer(
   middlewares.use(serveStaticMiddleware(root, config))
 
   // spa fallback
-  if (!middlewareMode) {
+  if (!middlewareMode || middlewareMode === 'html') {
     middlewares.use(
       history({
         logger: createDebugger('vite:spa-fallback'),
@@ -512,7 +515,7 @@ export async function createServer(
   // serve custom content instead of index.html.
   postHooks.forEach((fn) => fn && fn())
 
-  if (!middlewareMode) {
+  if (!middlewareMode || middlewareMode === 'html') {
     // transform index.html
     middlewares.use(indexHtmlMiddleware(server))
     // handle 404s
@@ -524,7 +527,7 @@ export async function createServer(
   }
 
   // error handler
-  middlewares.use(errorMiddleware(server, middlewareMode))
+  middlewares.use(errorMiddleware(server, !!middlewareMode))
 
   const runOptimize = async () => {
     if (config.cacheDir) {