docs: include ssr setup in example

Author: yyx990803

.gitignore

@@ -2,6 +2,7 @@
 .DS_Store
 node_modules
 dist
+dist-ssr
 link.sh
 .cache
 TODOs.md

example/main.js

@@ -1,4 +1,9 @@
 import App from './App.vue'
-import { createApp } from 'vue'
+import { createApp, createSSRApp } from 'vue'
 
-createApp(App).mount('#app')
+const app = __IS_SSR__ ? createSSRApp(App) : createApp(App)
+export default app
+
+if (typeof window !== 'undefined') {
+  app.mount('#app')
+}

example/ssr.js

@@ -0,0 +1,20 @@
+// This script is part of `yarn build-example-ssr`.
+
+const fs = require('fs')
+const path = require('path')
+const { renderToString } = require('@vue/server-renderer')
+const template = fs.readFileSync(path.resolve(__dirname, 'index.html'), 'utf-8')
+
+// here out server-side build directly exports an app instance.
+// in an actual SSR setup, you'll want to export a `createApp()` function that
+// returns a fresh app instance for each request. You probably also want to
+// return the router instance so that you can set the app's route state before
+// actually rendering it.
+const app = require('./dist-ssr/server/main.js').default
+
+renderToString(app).then((html) => {
+  fs.writeFileSync(
+    path.resolve(__dirname, 'dist-ssr/index.html'),
+    template.replace(/(<div id="app">)/, `$1${html}`)
+  )
+})

example/webpack.config.js

@@ -7,104 +7,147 @@ const MiniCssExtractPlugin = require('mini-css-extract-plugin')
 
 module.exports = (env = {}) => {
   const isProd = env.prod
-  const minimize = isProd && !env.noMinimize
-  const babel = isProd && !env.noBabel
+  const isSSR = env.ssr
 
-  return {
-    mode: isProd ? 'production' : 'development',
-    entry: path.resolve(__dirname, './main.js'),
-    devtool: 'source-map',
-    output: {
-      path: path.resolve(__dirname, 'dist'),
-      filename: '[name].js',
-      publicPath: '/dist/',
-    },
-    module: {
-      rules: [
-        {
-          test: /\.vue$/,
-          loader: 'vue-loader',
-        },
-        {
-          test: /\.png$/,
-          use: [
-            {
-              loader: 'url-loader',
-              options: {
-                limit: 8192,
-              },
+  /**
+   * Some notes regarding config for the server build of an SSR app:
+   * 1. target: 'node'
+   * 2. output.libraryTarget: 'commonjs' (so the exported app can be required)
+   * 3. externals: this is mostly for faster builds.
+   *    - externalize @vue/* deps via commonjs require()
+   *    - externalize client side deps that are never used on the server, e.g.
+   *      ones that are only used in onMounted() to empty modules
+   * 4. If using cache-loader or any other forms of cache, make sure the cache
+   *    key takes client vs. server builds into account!
+   */
+  const genConfig = (isServerBuild = false) => {
+    const minimize = isProd && !isServerBuild && !env.noMinimize
+    const useBabel = isProd && !isServerBuild && !env.noBabel
+
+    return {
+      mode: isProd ? 'production' : 'development',
+      entry: path.resolve(__dirname, './main.js'),
+      target: isServerBuild ? 'node' : 'web',
+      devtool: 'source-map',
+      output: {
+        path: path.resolve(
+          __dirname,
+          isSSR ? (isServerBuild ? 'dist-ssr/server' : 'dist-ssr/dist') : 'dist'
+        ),
+        filename: '[name].js',
+        publicPath: '/dist/',
+        libraryTarget: isServerBuild ? 'commonjs' : undefined,
+      },
+      externals: isServerBuild
+        ? [
+            (ctx, request, cb) => {
+              if (/^@vue/.test(request)) {
+                return cb(null, 'commonjs ' + request)
+              }
+              cb()
             },
-          ],
-        },
-        {
-          test: /\.css$/,
-          use: [
-            {
-              loader: MiniCssExtractPlugin.loader,
-              options: {
-                hmr: !isProd,
+          ]
+        : undefined,
+      module: {
+        rules: [
+          {
+            test: /\.vue$/,
+            loader: 'vue-loader',
+          },
+          {
+            test: /\.png$/,
+            use: [
+              {
+                loader: 'url-loader',
+                options: {
+                  limit: 8192,
+                },
               },
-            },
-            'css-loader',
-          ],
-        },
-        {
-          test: /\.js$/,
-          use: [
-            {
-              loader: 'cache-loader',
-              options: {
-                cacheIdentifier: hash(
-                  fs.readFileSync(path.resolve(__dirname, '../package.json')) +
-                    JSON.stringify(env)
-                ),
-                cacheDirectory: path.resolve(__dirname, '../.cache'),
+            ],
+          },
+          {
+            test: /\.css$/,
+            use: [
+              {
+                loader: MiniCssExtractPlugin.loader,
+                options: {
+                  hmr: !isProd,
+                },
               },
-            },
-            ...(babel
-              ? [
-                  {
-                    loader: 'babel-loader',
-                    options: {
-                      // use yarn build-example --env.noMinimize to verify that
-                      // babel is properly applied to all js code, including the
-                      // render function compiled from SFC templates.
-                      presets: ['@babel/preset-env'],
+              'css-loader',
+            ],
+          },
+          {
+            test: /\.js$/,
+            use: [
+              {
+                loader: 'cache-loader',
+                options: {
+                  cacheIdentifier: hash(
+                    // deps
+                    fs.readFileSync(
+                      path.resolve(__dirname, '../package.json')
+                    ) +
+                      // env
+                      JSON.stringify(env) +
+                      // client vs. server build
+                      isServerBuild
+                  ),
+                  cacheDirectory: path.resolve(__dirname, '../.cache'),
+                },
+              },
+              ...(useBabel
+                ? [
+                    {
+                      loader: 'babel-loader',
+                      options: {
+                        // use yarn build-example --env.noMinimize to verify that
+                        // babel is properly applied to all js code, including the
+                        // render function compiled from SFC templates.
+                        presets: ['@babel/preset-env'],
+                      },
                     },
-                  },
-                ]
-              : []),
-          ],
-        },
-        // target <docs> custom blocks
-        {
-          resourceQuery: /blockType=docs/,
-          loader: require.resolve('./docs-loader'),
-        },
+                  ]
+                : []),
+            ],
+          },
+          // target <docs> custom blocks
+          {
+            resourceQuery: /blockType=docs/,
+            loader: require.resolve('./docs-loader'),
+          },
+        ],
+      },
+      plugins: [
+        new VueLoaderPlugin(),
+        new MiniCssExtractPlugin({
+          filename: '[name].css',
+        }),
+        new webpack.DefinePlugin({
+          __IS_SSR__: !!isSSR,
+          __VUE_OPTIONS_API__: true,
+          __VUE_PROD_DEVTOOLS__: false,
+        }),
       ],
-    },
-    plugins: [
-      new VueLoaderPlugin(),
-      new MiniCssExtractPlugin({
-        filename: '[name].css',
-      }),
-      new webpack.DefinePlugin({
-        __VUE_OPTIONS_API__: true,
-        __VUE_PROD_DEVTOOLS__: false,
-      }),
-    ],
-    optimization: {
-      minimize,
-    },
-    devServer: {
-      stats: 'minimal',
-      contentBase: __dirname,
-      overlay: true,
-    },
-    resolveLoader: {
-      alias: {
-        'vue-loader': require.resolve('../'),
+      optimization: {
+        minimize,
+      },
+      devServer: {
+        stats: 'minimal',
+        contentBase: __dirname,
+        overlay: true,
       },
-    },
+      resolveLoader: {
+        alias: {
+          'vue-loader': require.resolve('../'),
+        },
+      },
+    }
+  }
+
+  if (!isSSR) {
+    return genConfig()
+  } else {
+    return [genConfig(), genConfig(true)]
   }
 }

package.json

@@ -16,6 +16,7 @@
     "test:webpack5": "WEBPACK5=true jest -c --coverage",
     "dev-example": "webpack-dev-server --config example/webpack.config.js --inline --hot",
     "build-example": "rm -rf example/dist && webpack --config example/webpack.config.js --env.prod",
+    "build-example-ssr": "rm -rf example/dist-ssr && webpack --config example/webpack.config.js --env.prod --env.ssr && node example/ssr.js",
     "lint": "prettier --write --parser typescript \"{src,test}/**/*.{j,t}s\"",
     "prepublishOnly": "tsc"
   },