progress

Author: yyx990803

en/README.md

@@ -1,3 +1,31 @@
-# vue-server-renderer
+# Vue.js Server-Side Rendering Guide
 
-Hello baby
+## What is 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 app on the client.
+
+A server-rendered Vue.js app can also be considered "isomorphic" or "universal", in the sense 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 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 Ajax, 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 slow internet 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 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 obviously 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 app, the first question you should ask it whether you actually need it. It mostly depends on how important time-to-content is for your app. For example, if you are building an internal dashboard where an extra few hundred milliseconds on initial load doesn't matter that much, SSR would be an overkill. However, in cases where time-to-content is absolutely critical, SSR can help you achieve the best possible initial load performance.
+
+We realize it could be quite challenging to build a server-rendered Vue app if you are not already familiar with webpack, Node.js and Vue itself. If you prefer a higher-level solution that provides a smoother on-boarding experience, you should probably give [Nuxt.js](http://nuxtjs.org/) a try. It's built upon the same Vue stack but abstracts away a lot of the complexities, 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. And it would still be beneficial to read through this guide to better understand how things work together.
+
+If you believe your use case justifies the use of SSR, then let's dive in!

en/SUMMARY.md

@@ -1,9 +1,14 @@
-# vue-server-renderer
-
 - [Basic Usage](basic.md)
-- [Why Use Bundle Renderer?](why-bundle-renderer.md)
+- [Writing Universal Code](universal.md)
+- [Using a Page Template](template.md)
+- [Using the Bundle Renderer](bundle-renderer.md)
 - [Creating the Server Bundle](server-bundle.md)
 - [Creating the Client Manifest](client-manifest.md)
+- [Routing](routing.md)
+- [Data Pre-fetching and State](data.md)
+- [Head Management](head.md)
+- [Handling CSS](css.md)
 - [Caching](caching.md)
+- [Streaming](streaming.md)
 - [Client Side Hydration](hydration.md)
 - [API Reference](api.md)

en/basic.md

@@ -1,5 +1,53 @@
-## rendering a vm
+# Basic Usage
 
-## rendering to stream
+## Installation
 
-## template
+``` bash
+npm install vue-server-renderer --save
+```
+
+#### Notes
+
+- It's recommended to use Node.js version 6+.
+- `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 Instance
+
+``` js
+// Step 1: Create a Vue instance
+const Vue = require('vue')
+const app = new Vue({
+  template: `<div>Hello World</div>`
+})
+
+// Step 2: Create a renderer
+const renderer = require('vue-server-renderer').createRenderer()
+
+// Step 3: Render the Vue instance to HTML
+renderer.renderToString(app, (err, html) => {
+  if (err) throw err
+  console.log(html)
+  // => <p server-rendered="true">hello world</p>
+})
+```
+
+It is pretty straightforward when used inside a Node.js server, for example [Express](https://expressjs.com/):
+
+``` js
+app.get('*', (req, res) => {
+  const app = new Vue({
+    data: {
+      url: req.url
+    },
+    template: `<div>Hello {{ url }}</div>`
+  })
+
+  renderer.renderToString(app, (err, html) => {
+    if (err) throw err
+    res.end(html)
+  })
+})
+```
+
+This is the most basic API to render a Vue app on the server. However, this is far from sufficient for a real world server-rendered app. In the following chapters we will cover the common issues encountered and how to deal with them.

en/why-bundle-renderer.md renamed to en/bundle-renderer.md

@@ -1,5 +1,9 @@
+# Using the BundleRenderer
+
 ## Problems with Basic SSR
 
+In our basic usage example, we directly required Vue and created an app instance in our Node.js server code. This is straightforward, however has quite a few issues in practice:
+
 - webpack
 - development and deployment
 - source map

en/code-splitting.md

@@ -0,0 +1,3 @@
+# Using a Page Template
+
+When you render a Vue app, the renderer only generates the markup of the app. We also need to wrap the output with an extra HTML page shell.

en/css.md

@@ -0,0 +1,21 @@
+# Writing Universal Code
+
+In a server-rendered app, most of our code will be "universal" - that is, it runs on both the server and the client. However, the two environments are quite different, so the behavior of our code will not be exactly the same. Here we will go over some differences that you need to be aware of.
+
+## Data Reactivity on the Server
+
+In a client-only app, every user will be using a fresh instance of the app in their browser. For server-side rendering we want the same: each request should have a fresh, isolated app instance so that there is no cross-request state pollution. Since each app is rendered only once, this means data reactivity is unnecessary on the server, so it is disabled by default. Disabling data reactivity also avoids the performance cost of converting data into reactive objects.
+
+## Component Lifecycle Hooks
+
+Since there are no dynamic updates, of all the lifecycle hooks, only `beforeCreate` and `created` will be called during SSR. This means any code inside other lifecycle hooks such as `beforeMount` or `mounted` will only be executed on the client.
+
+## Access to Environment-specific APIs
+
+Universal code cannot assume access to environment-specific APIs, so if your code directly uses browser-only globals like `window` or `document`, they will throw errors when executed in Node.js, and vice-versa.
+
+For tasks shared between server and client but use different platform APIs, it's recommended to wrap the platform-specific implementations inside a universal API, or use libraries that do this for you. For example, [axios](https://github.com/mzabriskie/axios) is an HTTP client that exposes the same API for both server and client.
+
+For browser-only APIs, the common approach is to lazily access them inside client-only lifecycle hooks.
+
+Note that if a 3rd party library is not written with universal code in mind, it could be tricky to use it in an server-rendered app. You *might* be able to get it working by mocking some of the globals, but it would be hacky and may interfere with the environment detection code of other libraries.