add document about custom dynamic title for better SEO

Author: JounQin

README.md

@@ -8,6 +8,7 @@ Yet another simple React SSR solution inspired by vue-server-render with:
 2. prefetch/preload client injection with ClientManifest, generated by [ssr-webpack-plugin](https://github.com/JounQin/ssr-webpack-plugin)
 3. server css support with [react-style-loader](https://github.com/JounQin/react-style-loader)
 4. Async component support with [react-async-component](https://github.com/ctrlplusb/react-async-component) and [react-async-bootstrapper](https://github.com/ctrlplusb/react-async-bootstrapper)
+5. custom dynamic head management for better SEO
 
 ## Real World Demo
 
@@ -35,7 +36,7 @@ import { resolve } from './config'
 
 import base from './base'
 
-export default merge(base, {
+export default merge.smart(base, {
   // Point entry to your app's server entry file
   entry: resolve('src/entry-server.js'),
 
@@ -64,6 +65,7 @@ export default merge(base, {
 
   plugins: [
     new webpack.DefinePlugin({
+      'process.env.REACT_ENV': '"server"',
       __SERVER__: true,
     }),
     // This is the plugin that turns the entire output of the server build
@@ -79,7 +81,8 @@ export default merge(base, {
 ```js
 import webpack from 'webpack'
 import merge from 'webpack-merge'
-import HtmlWebpackPlugin from 'html-webpack-plugin'
+// do not need 'html-webpack-plugin' any more because we will render html from server
+// import HtmlWebpackPlugin from 'html-webpack-plugin'
 import { SSRClientPlugin } from 'ssr-webpack-plugin'
 
 import { __DEV__, publicPath, resolve } from './config'
@@ -106,11 +109,9 @@ export default merge.smart(base, {
   },
   plugins: [
     new webpack.DefinePlugin({
+      'process.env.REACT_ENV': '"client"',
       __SERVER__: false,
     }),
-    new HtmlWebpackPlugin({
-      template: resolve('src/index.pug'),
-    }),
     new webpack.optimize.CommonsChunkPlugin({
       names: ['vendors', 'manifest'],
     }),
@@ -172,7 +173,7 @@ All you need to do is for hot reload on development:
 
 Example: https://github.com/JounQin/react-hackernews/blob/master/server/dev.js
 
-Your server bundle entry should export a function with a `userContext` param which return a promise, and it should resolve a react component instance.
+Your server bundle entry should export a function with a `context` param which return a promise, and it should resolve a react component instance.
 
 Example: https://github.com/JounQin/react-hackernews/blob/master/src/entry-server.js
 
@@ -184,17 +185,17 @@ Since you generate server bundle renderer as above, you can easily call `rendere
 
 `renderToString` is very simple, just `try/catch` error to handle it.
 
-`renderToStream` is a tiny complicated to handle, you can rediect or reject request by listening `error` event and handle error param. If you want to render application but change response status, you can listen `afterRender` event and handle with your own `userContext`, for example maybe you want to render 404 Not Found page via React Component but respond with 404 status.
+`renderToStream` is a tiny complicated to handle, you can rediect or reject request by listening `error` event and handle error param. If you want to render application but change response status, you can listen `afterRender` event and handle with your own `context`, for example maybe you want to render 404 Not Found page via React Component but respond with 404 status.
 
 ### State management
 
 If you set `context.state` on server, it will auto inject a script contains `window.__INITIAL_STATE__` in output, so that you can resue server state on client.
 
-### Style injection on server
+### Style injection and Head Management
 
 Without SSR, we can easily use `style-loader`, however we need to collect rendered components with there styles together on runtime, so we choose to use [react-style-loader](https://github.com/JounQin/react-style-loader) which forked [vue-style-loader](https://github.com/vuejs/vue-style-loader) indeed.
 
-Let's create a simple HOC for server style and http injection.
+Let's create a simple HOC for server style, title management and http injection.
 
 ```js
 import axios from 'axios'
@@ -203,38 +204,72 @@ import PropTypes from 'prop-types'
 import React from 'react'
 import { withRouter } from 'react-router'
 
-export const withSsr = (styles, router = true) => Component => {
-  class SsrConmponent extends React.PureComponent {
-    static displayName = `Ssr${Component.displayName ||
-      Component.name ||
-      'Component'}`
+// custom dynamic title for better SEO both on server and client
+const setTitle = (title, self) => {
+  title = typeof title === 'function' ? title.call(self, self) : title
 
-    static propTypes = {
-      staticContext: PropTypes.object,
-    }
+  if (!title) {
+    return
+  }
 
-    componentWillMount() {
-      // `styles.__inject__` will only be exist on server, and inject into `userContext`
-      if (styles && styles.__inject__) {
-        styles.__inject__(this.props.staticContext)
+  if (__SERVER__) {
+    self.props.staticContext.title = `React Server Renderer | ${title}`
+  } else {
+    // `title` here on client can be promise, but you should not and do not need to do that on server,
+    // because on server async data will be fetched in asyncBootstrap first and set into store,
+    // then title function will be called again when you call `renderToString` or `renderToStream`.
+    // But on client, when you change route, maybe you need to fetch async data first
+    // Example: https://github.com/JounQin/react-hackernews/blob/master/src/views/UserView/index.js#L18
+    // And also, you need put `@withSsr` under `@connect` with `react-redux` for get store injected in your title function
+    Promise.resolve(title).then(title => {
+      if (title) {
+        document.title = `React Server Renderer | ${title}`
       }
-    }
+    })
+  }
+}
 
-    render() {
-      return (
-        <Component
-          {...this.props}
-          // use different axios instance on server
-          http={__SERVER__ ? this.props.staticContext.axios : axios}
-        />
-      )
-    }
+export const withSsr = (styles, router = true, title) => {
+  if (typeof router !== 'boolean') {
+    title = router
+    router = true
   }
 
-  return hoistStatics(
-    router ? withRouter(SsrConmponent) : SsrConmponent,
-    Component,
-  )
+  return Component => {
+    class SsrConmponent extends React.PureComponent {
+      static displayName = `Ssr${Component.displayName ||
+        Component.name ||
+        'Component'}`
+
+      static propTypes = {
+        staticContext: PropTypes.object,
+      }
+
+      componentWillMount() {
+        // `styles.__inject__` will only be exist on server, and inject into `staticContext`
+        if (styles.__inject__) {
+          styles.__inject__(this.props.staticContext)
+        }
+
+        setTitle(title, this)
+      }
+
+      render() {
+        return (
+          <Component
+            {...this.props}
+            // use different axios instance on server to handle different user client headers
+            http={__SERVER__ ? this.props.staticContext.axios : axios}
+          />
+        )
+      }
+    }
+
+    return hoistStatics(
+      router ? withRouter(SsrConmponent) : SsrConmponent,
+      Component,
+    )
+  }
 }
 ```
 
@@ -250,7 +285,6 @@ import { withSsr } from 'utils'
 
 import styles from './styles'
 
-@withSsr(styles, false)
 @connect(
   ({ counter }) => ({ counter }),
   dispatch => ({
@@ -259,6 +293,7 @@ import styles from './styles'
     decrease: () => dispatch(decrease),
   }),
 )
+@withSsr(styles, false, ({ props }) => props.counter)
 export default class Home extends React.PureComponent {
   static propTypes = {
     counter: PropTypes.number.isRequired,
@@ -297,7 +332,27 @@ export default class Home extends React.PureComponent {
 }
 ```
 
-Then `react-server-renderer` will automatically collect user styles on server and render them into output!
+And inside the template passed `title` to bundle renderer:
+
+```html
+<html>
+  <head>
+    <title>{{ title }}</title>
+  </head>
+  <body>
+    ...
+  </body>
+</html>
+```
+
+Then `react-server-renderer` will automatically collect user styles and title on server and render them into output!
+
+Notes:
+
+* Use double-mustache (HTML-escaped interpolation) to avoid XSS attacks.
+* You should provide a default title when creating the context object in case no component has set a title during render.
+
+Using the same strategy, you can easily expand it into a generic head management utility.
 
 ---
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-server-renderer",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "simple React SSR solution inspired by vue-server-render",
   "repository": "git@github.com:JounQin/react-server-renderer.git",
   "main": "lib/index.js",