Guide > Scaling Up > Server-Side Rendering の翻訳を追従 (#319)

* SSR guide

vuejs/docs@799b2c8#diff-520c551813b4a6b395629e927acb684917c702b7be5d9c1d600b4ecb685fa6cc

* feat: added Vite to SSR

vuejs/docs@f27fce0#diff-520c551813b4a6b395629e927acb684917c702b7be5d9c1d600b4ecb685fa6cc

* Ssr webpack

vuejs/docs@88c61cb#diff-fcd18f6043ee99c60994cbae68a156d26a9dff4598479cfeaca2cd88c7690b18

* docs : translate ssr page

Author: naokie

src/.vuepress/config.js

@@ -211,16 +211,16 @@ const sidebar = {
       ]
     },
   ],
-  // ssr: [
-  //   ['/guide/ssr/introduction', 'Introduction'],
-  //   '/guide/ssr/getting-started',
-  //   '/guide/ssr/universal',
-  //   '/guide/ssr/structure',
-  //   '/guide/ssr/build-config',
-  //   '/guide/ssr/server',
-  //   '/guide/ssr/routing',
-  //   '/guide/ssr/hydration'
-  // ],
+  ssr: [
+    ['/guide/ssr/introduction', 'Introduction'],
+    '/guide/ssr/getting-started',
+    '/guide/ssr/universal',
+    '/guide/ssr/structure',
+    '/guide/ssr/build-config',
+    '/guide/ssr/server',
+    '/guide/ssr/routing',
+    '/guide/ssr/hydration'
+  ],
   contributing: [
     {
       title: 'ドキュメントへの貢献',

src/guide/ssr.md

@@ -2,7 +2,7 @@
 
 ## 完全な SSR ガイド
 
-私たちは、サーバーでレンダリングされた Vue アプリケーションを作成するためのスタンドアロンのガイドを作成しました。これは、すでにクライアント側の Vue 開発、サーバー側の Node.js 開発そして Webpack に精通している方にとって非常に詳細なガイドです。[ssr.vuejs.org](https://ssr.vuejs.org/) を確認してください。
+私たちは、サーバーでレンダリングされた Vue アプリケーションを作成するためのスタンドアロンのガイドを作成しました。これは、すでにクライアント側の Vue 開発、サーバー側の Node.js 開発そして Webpack に精通している方にとって非常に詳細なガイドです。[こちら](/guide/ssr/introduction.html) を確認してください。
 
 ## Nuxt.js
 
@@ -11,3 +11,13 @@
 ## Quasar Framework SSR + PWA
 
 [Quasar Framework](https://quasar.dev) は、SSR アプリケーション (PWA ハンドオフオプションあり) を生成するフレームワークで、最高クラスのビルドシステム、実用的な環境設定、そして開発者の拡張性を活用して、あなたのアイデアを設計し構築することを簡単にします。100 を超える "Material Design 2.0" に準拠したコンポーネントがあり、どれかひとつをサーバ上で実行できます。これはブラウザでも使用でき、サイト内の `<meta>` タグで管理もできます。 Quasar は Node.js と webpack ベースの開発環境で、SPA、PWA、SSR、Electron、Capacitor、そして Cordova アプリケーション、全て 1 つのコードベースからの迅速な開発を合理化し、加速させます。
+
+## Vite SSR
+
+[Vite](https://vitejs.dev/) は、フロントエンド開発の経験を大幅に改善する新しいタイプのフロントエンドビルドツールです。大きく分けて 2 つの部分で構成されています。:
+
+- ソースファイルをネイティブ ES モジュールで提供する開発サーバで、豊富な組み込み機能と、驚異的な速さの HMR (Hot Module Replacement) を備えています。
+
+- コードを [Rollup](https://rollupjs.org/) でバンドルするビルドコマンドで、本番用に高度に最適化した静的アセットを出力するようにあらかじめ設定されています。
+
+Vite は組み込みの [サーバサイドレンダリングのサポート](https://vitejs.dev/guide/ssr.html) もあります。Vue を使ったプロジェクトの例は [こちら](https://github.com/vitejs/vite/tree/main/packages/playground/ssr-vue) で見ることができます。

src/guide/ssr/build-config.md

@@ -0,0 +1,106 @@
+# Build Configuration
+
+The webpack config for an SSR project will be similar to a client-only project. If you're not familiar with configuring webpack, you can find more information in the documentation for [Vue CLI](https://cli.vuejs.org/guide/webpack.html#working-with-webpack) or [configuring Vue Loader manually](https://vue-loader.vuejs.org/guide/#manual-setup).
+
+## Key Differences with Client-Only Builds
+
+1. We need to create a [webpack manifest](https://webpack.js.org/concepts/manifest/) for our server-side code. This is a JSON file that webpack keeps to track how all the modules map to the output bundles.
+
+2. We should [externalize application dependencies](https://webpack.js.org/configuration/externals/). This makes the server build much faster and generates a smaller bundle file. When doing this, we have to exclude dependencies that need to be processed by webpack (like `.css`. or `.vue` files).
+
+3. We need to change webpack [target](https://webpack.js.org/concepts/targets/) to Node.js. This allows webpack to handle dynamic imports in a Node-appropriate fashion, and also tells `vue-loader` to emit server-oriented code when compiling Vue components.
+
+4. When building a server entry, we would need to define an environment variable to indicate we are working with SSR. It might be helpful to add a few `scripts` to the project's `package.json`:
+
+```json
+"scripts": {
+  "build:client": "vue-cli-service build --dest dist/client",
+  "build:server": "SSR=1 vue-cli-service build --dest dist/server",
+  "build": "npm run build:client && npm run build:server",
+}
+```
+
+## Example Configuration
+
+Below is a sample `vue.config.js` that adds SSR rendering to a Vue CLI project, but it can be adapted for any webpack build.
+
+```js
+const { WebpackManifestPlugin } = require('webpack-manifest-plugin')
+const nodeExternals = require('webpack-node-externals')
+const webpack = require('webpack')
+
+module.exports = {
+  chainWebpack: webpackConfig => {
+    // We need to disable cache loader, otherwise the client build
+    // will used cached components from the server build
+    webpackConfig.module.rule('vue').uses.delete('cache-loader')
+    webpackConfig.module.rule('js').uses.delete('cache-loader')
+    webpackConfig.module.rule('ts').uses.delete('cache-loader')
+    webpackConfig.module.rule('tsx').uses.delete('cache-loader')
+
+    if (!process.env.SSR) {
+      // Point entry to your app's client entry file
+      webpackConfig
+        .entry('app')
+        .clear()
+        .add('./src/entry-client.js')
+      return
+    }
+
+    // Point entry to your app's server entry file
+    webpackConfig
+      .entry('app')
+      .clear()
+      .add('./src/entry-server.js')
+
+    // This allows webpack to handle dynamic imports in a Node-appropriate
+    // fashion, and also tells `vue-loader` to emit server-oriented code when
+    // compiling Vue components.
+    webpackConfig.target('node')
+    // This tells the server bundle to use Node-style exports
+    webpackConfig.output.libraryTarget('commonjs2')
+
+    webpackConfig
+      .plugin('manifest')
+      .use(new WebpackManifestPlugin({ fileName: 'ssr-manifest.json' }))
+
+    // https://webpack.js.org/configuration/externals/#function
+    // https://github.com/liady/webpack-node-externals
+    // Externalize app dependencies. This makes the server build much faster
+    // and generates a smaller bundle file.
+
+    // Do not externalize dependencies that need to be processed by webpack.
+    // You should also whitelist deps that modify `global` (e.g. polyfills)
+    webpackConfig.externals(nodeExternals({ allowlist: /\.(css|vue)$/ }))
+
+    webpackConfig.optimization.splitChunks(false).minimize(false)
+
+    webpackConfig.plugins.delete('preload')
+    webpackConfig.plugins.delete('prefetch')
+    webpackConfig.plugins.delete('progress')
+    webpackConfig.plugins.delete('friendly-errors')
+
+    webpackConfig.plugin('limit').use(
+      new webpack.optimize.LimitChunkCountPlugin({
+        maxChunks: 1
+      })
+    )
+  }
+}
+```
+
+## Externals Caveats
+
+Notice that in the `externals` option we are whitelisting CSS files. This is because CSS imported from dependencies should still be handled by webpack. If you are importing any other types of files that also rely on webpack (e.g. `*.vue`, `*.sass`), you should add them to the whitelist as well.
+
+If you are using `runInNewContext: 'once'` or `runInNewContext: true`, then you also need to whitelist polyfills that modify `global`, e.g. `babel-polyfill`. This is because when using the new context mode, **code inside a server bundle has its own `global` object.** Since you don't really need it on the server, it's actually easier to just import it in the client entry.
+
+## Generating `clientManifest`
+
+In addition to the server bundle, we can also generate a client build manifest. With the client manifest and the server bundle, the renderer now has information of both the server _and_ client builds. This way it can automatically infer and inject [preload / prefetch directives](https://css-tricks.com/prefetching-preloading-prebrowsing/), `<link>` and `<script>` tags into the rendered HTML.
+
+The benefits are two-fold:
+
+1. It can replace `html-webpack-plugin` for injecting the correct asset URLs when there are hashes in your generated filenames.
+
+2. When rendering a bundle that leverages webpack's on-demand code splitting features, we can ensure the optimal chunks are preloaded / prefetched, and also intelligently inject `<script>` tags for needed async chunks to avoid waterfall requests on the client, thus improving TTI (time-to-interactive).

src/guide/ssr/getting-started.md

@@ -0,0 +1,99 @@
+# Getting Started
+
+> This guide is currently under active development
+
+## Installation
+
+In order to create a server-side rendered application, we need to install the `@vue/server-renderer` package:
+
+```bash
+npm install @vue/server-renderer
+## OR
+yarn add @vue/server-renderer
+```
+
+#### Notes
+
+- It's recommended to use Node.js version 10+.
+- `@vue/server-renderer` and `vue` must have matching versions.
+- `@vue/server-renderer` relies on some Node.js native modules and therefore can only be used in Node.js. We may provide a simpler build that can be run in other JavaScript runtimes in the future.
+
+## Rendering a Vue Application
+
+Unlike a client-only Vue application, which is created using `createApp`, an SSR application needs to be created using `createSSRApp`:
+
+```js
+const { createSSRApp } = require('vue')
+
+const app = createSSRApp({
+  data() {
+    return {
+      user: 'John Doe'
+    }
+  },
+  template: `<div>Current user is: {{ user }}</div>`
+})
+```
+
+Now, we can use the `renderToString` function to render our application instance to a string. This function returns a Promise which resolves to the rendered HTML.
+
+```js{2,13}
+const { createSSRApp } = require('vue')
+const { renderToString } = require('@vue/server-renderer')
+
+const app = createSSRApp({
+  data() {
+    return {
+      user: 'John Doe'
+    }
+  },
+  template: `<div>Current user is: {{ user }}</div>`
+})
+
+const appContent = await renderToString(app)
+```
+
+## Integrating with a Server
+
+To run an application, in this example we will use [Express](https://expressjs.com/):
+
+```bash
+npm install express
+## OR
+yarn add express
+```
+
+```js
+// server.js
+
+const { createSSRApp } = require('vue')
+const { renderToString } = require('@vue/server-renderer')
+const server = require('express')()
+
+server.get('*', async (req, res) => {
+  const app = createSSRApp({
+    data() {
+      return {
+        user: 'John Doe'
+      }
+    },
+    template: `<div>Current user is: {{ user }}</div>`
+  })
+
+  const appContent = await renderToString(app)
+  const html = `
+  <html>
+    <body>
+      <h1>My First Heading</h1>
+      <div id="app">${appContent}</div>
+    </body>
+  </html>
+  `
+
+  res.end(html)
+})
+
+server.listen(8080)
+```
+
+Now, when running this Node.js script, we can see a static HTML page on `localhost:8080`. However, this code is not _hydrated_: Vue hasn't yet taken over the static HTML sent by the server to turn it into dynamic DOM that can react to client-side data changes. This will be covered in the [Client Side Hydration](hydration.html) section.

src/guide/ssr/hydration.md

@@ -0,0 +1,33 @@
+# Client Side Hydration
+
+Hydration refers to the client-side process during which Vue takes over the static HTML sent by the server and turns it into dynamic DOM that can react to client-side data changes.
+
+In `entry-client.js`, we are simply mounting the app with this line:
+
+```js
+app.mount('#app')
+```
+
+Since the server has already rendered the markup, we obviously do not want to throw that away and re-create all the DOM elements. Instead, we want to "hydrate" the static markup and make it interactive.
+
+Vue provides a `createSSRApp` method for use in client-side code (in this case, in our `entry-client.js`) to tell Vue to hydrate the existing static HTML instead of re-creating all the DOM elements.
+
+### Hydration Caveats
+
+Vue will assert the client-side generated virtual DOM tree matches the DOM structure rendered from the server. If there is a mismatch, it will bail hydration, discard existing DOM and render from scratch. There will be a warning in the browser console but your site will still work.
+
+The first key way to ensure that SSR is working to ensuring your application state is the same on client and server. Take special care not to depend on APIs specific to the browser (like window width, device capability or localStorage) or server (such as Node built-ins), and take care where the same code will give different results when run in different places (such as when using timezones, timestamps, normalizing URLs or generating random numbers). See [Writing Universal Code](./universal.md) for more details.
+
+A second key thing to be aware of when using SSR + client hydration is that invalid HTML may be altered by the browser. For example, when you write this in a Vue template:
+
+```html
+<table>
+  <tr>
+    <td>hi</td>
+  </tr>
+</table>
+```
+
+The browser will automatically inject `<tbody>` inside `<table>`, however, the virtual DOM generated by Vue does not contain `<tbody>`, so it will cause a mismatch. To ensure correct matching, make sure to write valid HTML in your templates.
+
+You might consider using a HTML validator like [the W3C Markup Validation Service](https://validator.w3.org/) or [HTML-validate](https://html-validate.org/) to check your templates in development.

src/guide/ssr/introduction.md

@@ -0,0 +1,47 @@
+# Server-Side Rendering Guide
+
+> This guide is currently under active development
+
+## What is Server-Side Rendering (SSR)?
+
+Vue.js is a framework for building client-side applications. By default, Vue components produce and manipulate DOM in the browser as output. However, it is also possible to render the same components into HTML strings on the server, send them directly to the browser, and finally "hydrate" the static markup into a fully interactive application on the client.
+
+A server-rendered Vue.js application can also be considered "isomorphic" or "universal". This means that the majority of your app's code runs on both the server **and** the client.
+
+## Why SSR?
+
+Compared to a traditional SPA (Single-Page Application), the advantage of SSR primarily lies in:
+
+- Better search engine optimization (SEO), as the search engine crawlers will directly see the fully rendered page.
+
+  Note that as of now, Google and Bing can index synchronous JavaScript applications just fine. Synchronous being the key word there. If your app starts with a loading spinner, then fetches content via API call, the crawler will not wait for you to finish. This means if you have content fetched asynchronously on pages where SEO is important, SSR might be necessary.
+
+- Faster time-to-content, especially on the slow Internet connection or slow devices. Server-rendered markup doesn't need to wait until all JavaScript has been downloaded and executed to be displayed, so your user will see a fully-rendered page sooner. This generally results in better user experience, and can be critical for applications where time-to-content is directly associated with the conversion rate.
+
+There are also some trade-offs to consider when using SSR:
+
+- Development constraints. Browser-specific code can only be used inside certain lifecycle hooks; some external libraries may need special treatment to be able to run in a server-rendered app.
+
+- More involved build setup and deployment requirements. Unlike a fully static SPA that can be deployed on any static file server, a server-rendered app requires an environment where a Node.js server can run.
+
+- More server-side load. Rendering a full app in Node.js is going to be more CPU-intensive than just serving static files, so if you expect high traffic, be prepared for corresponding server load and wisely employ caching strategies.
+
+Before using SSR for your application, the first question you should ask is whether you actually need it. It mostly depends on how important time-to-content is for your application. For example, if you are building an internal dashboard where an extra few hundred milliseconds on the initial load doesn't matter that much, SSR would be overkill. However, in cases where time-to-content is absolutely critical, SSR can help you achieve the best possible initial load performance.
+
+## SSR vs Prerendering
+
+If you're only investigating SSR to improve the SEO of a handful of marketing pages (e.g. `/`, `/about`, `/contact`, etc), then you probably want **prerendering** instead. Rather than using a web server to compile HTML on-the-fly, prerendering generates static HTML files for specific routes at build time. The advantage is setting up prerendering is much simpler and allows you to keep your frontend as a fully static site.
+
+If you're using [webpack](https://webpack.js.org/), you can add prerendering with the [prerender-spa-plugin](https://github.com/chrisvfritz/prerender-spa-plugin). It's been extensively tested with Vue apps.
+
+## About This Guide
+
+[//]: # 'TODO: This guide is focused on server-rendered Single-Page Applications using Node.js as the server. Mixing Vue SSR with other backend setups is a topic of its own and briefly discussed in a [dedicated section].'
+
+This guide will be very in-depth and assumes you are already familiar with Vue.js itself, and have a decent working knowledge of Node.js and webpack.
+
+[//]: # 'If you prefer a higher-level solution that provides a smooth out-of-the-box experience, you should probably give [Nuxt.js](https://nuxtjs.org/) a try. It's built upon the same Vue stack but abstracts away a lot of the boilerplate, and provides some extra features such as static site generation. However, it may not suit your use case if you need more direct control of your app's structure. Regardless, it would still be beneficial to read through this guide to understand better how things work together.'
+
+[//]: # 'TODO: As you read along, it would be helpful to refer to the official [HackerNews Demo](https://github.com/vuejs/vue-hackernews-2.0/), which makes use of most of the techniques covered in this guide'
+
+Finally, note that the solutions in this guide are not definitive - we've found them to be working well for us, but that doesn't mean they cannot be improved. They might get revised in the future - and feel free to contribute by submitting pull requests!