improve document

Author: JounQin

README.md

@@ -1,4 +1,308 @@
-# react-server-render
+# react-server-renderer
 
-[![Greenkeeper badge](https://badges.greenkeeper.io/JounQin/react-server-render.svg)](https://greenkeeper.io/)
-simple React SSR solution inspired by vue-server-render
+[![Greenkeeper badge](https://badges.greenkeeper.io/JounQin/react-server-renderer.svg)](https://greenkeeper.io/)
+
+Yet another simple React SSR solution inspired by vue-server-render with:
+
+1. Server bundle with hot reload on development and source map support
+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)
+
+## Real World Demo
+
+[react-study](https://github.com/JounQin/react-study)
+
+## Usage
+
+This module is heavily inspired by [vue-server-render](https://ssr.vuejs.org), it is recommended to read about [bundle-renderer](https://ssr.vuejs.org/en/bundle-renderer.html).
+
+If you're using [react-router](https://github.com/ReactTraining/react-router), you should read about [Server Rendering](https://reacttraining.com/react-router/web/guides/server-rendering).
+
+And also, data injection should be implement with [asyncBootstrap](https://github.com/ctrlplusb/react-async-bootstrapper).
+
+### Build Configuration
+
+#### Server Config
+
+```js
+import webpack from 'webpack'
+import merge from 'webpack-merge'
+import nodeExternals from 'webpack-node-externals'
+import { SSRServerPlugin } from 'ssr-webpack-plugin'
+
+import { resolve } from './config'
+
+import base from './base'
+
+export default merge(base, {
+  // Point entry to your app's server entry file
+  entry: resolve('src/entry-server.js'),
+
+  // This allows webpack to handle dynamic imports in a Node-appropriate
+  // fashion, and also tells `react-style-loader` to emit server-oriented code when
+  // compiling React components.
+  target: 'node',
+
+  output: {
+    path: resolve('dist'),
+    filename: `[name].[chunkhash].js`,
+    // This tells the server bundle to use Node-style exports
+    libraryTarget: 'commonjs2',
+  },
+
+  // 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.
+  externals: nodeExternals({
+    // do not externalize dependencies that need to be processed by webpack.
+    // you can add more file types here e.g. raw *.vue files
+    // you should also whitelist deps that modifies `global` (e.g. polyfills)
+    whitelist: /\.s?css$/,
+  }),
+
+  plugins: [
+    new webpack.DefinePlugin({
+      __SERVER__: true,
+    }),
+    // This is the plugin that turns the entire output of the server build
+    // into a single JSON file. The default file name will be
+    // `ssr-server-bundle.json`
+    new SSRServerPlugin(),
+  ],
+})
+```
+
+#### Client Config
+
+```js
+import webpack from 'webpack'
+import merge from 'webpack-merge'
+import HtmlWebpackPlugin from 'html-webpack-plugin'
+import { SSRClientPlugin } from 'ssr-webpack-plugin'
+
+import { __DEV__, publicPath, resolve } from './config'
+
+import base from './base'
+
+export default merge.smart(base, {
+  entry: {
+    app: [resolve('src/entry-client.js')],
+    vendors: [
+      'react',
+      'react-dom',
+      'react-redux',
+      'react-router',
+      'react-router-redux',
+      'react-router-config',
+      'react-router-dom',
+    ],
+  },
+  output: {
+    publicPath,
+    path: resolve('dist/static'),
+    filename: `[name].[${__DEV__ ? 'hash' : 'chunkhash'}].js`,
+  },
+  plugins: [
+    new webpack.DefinePlugin({
+      __SERVER__: false,
+    }),
+    new HtmlWebpackPlugin({
+      template: resolve('src/index.pug'),
+    }),
+    new webpack.optimize.CommonsChunkPlugin({
+      names: ['vendors', 'manifest'],
+    }),
+    // This plugins generates `ssr-client-manifest.json` in the
+    // output directory.
+    new SSRClientPlugin({
+      // path relative to your output path, default to be `ssr-client-manifest.json`
+      filename: '../ssr-client-manifest.json',
+    }),
+  ],
+})
+```
+
+You can then use the generated client manifest, together with a page template:
+
+```js
+const { createBundleRenderer } = require('react-server-rendererer')
+
+const template = require('fs').readFileSync('/path/to/template.html', 'utf-8')
+const serverBundle = require('/path/to/vue-ssr-server-bundle.json')
+const clientManifest = require('/path/to/vue-ssr-client-manifest.json')
+
+const renderer = createBundleRenderer(serverBundle, {
+  template,
+  clientManifest,
+})
+```
+
+With this setup, your server-rendered HTML for a build with code-splitting will look something like this (everything auto-injected):
+
+```html
+<html>
+  <head>
+    <!-- chunks used for this render will be preloaded -->
+    <link rel="preload" href="/manifest.js" as="script">
+    <link rel="preload" href="/main.js" as="script">
+    <link rel="preload" href="/0.js" as="script">
+    <!-- unused async chunks will be prefetched (lower priority) -->
+    <link rel="prefetch" href="/1.js" as="script">
+  </head>
+  <body>
+    <!-- app content -->
+    <div data-server-rendered="true"><div>async</div></div>
+    <!-- manifest chunk should be first -->
+    <script src="/manifest.js"></script>
+    <!-- async chunks injected before main chunk -->
+    <script src="/0.js"></script>
+    <script src="/main.js"></script>
+  </body>
+</html>`
+```
+
+### Server bundle
+
+All you need to do is for hot reload on development:
+
+1. compile server webpack config via node.js API like: `const const serverCompiler = webpack(serverConfig)`
+2. watch serverCompiler and replace server bundle on change
+
+Example: https://github.com/JounQin/react-study/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.
+
+Example: https://github.com/JounQin/react-study/blob/master/src/entry-server.js
+
+When you need to redirect on server or an error occurs, you should reject inside promise so that we can handle it.
+
+### renderToString and renderToStream(use `ReactDomServer.renderToNodeStream` inside)
+
+Since you generate server bundle renderer as above, you can easily call `renderer.renderToString(context)` or `renderer.renderToStream(context)`, where `context` should be a singloton of every request.
+
+`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.
+
+### 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
+
+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.
+
+```js
+import axios from 'axios'
+import hoistStatics from 'hoist-non-react-statics'
+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'}`
+
+    static propTypes = {
+      staticContext: PropTypes.object,
+    }
+
+    componentWillMount() {
+      // `styles.__inject__` will only be exist on server, and inject into `userContext`
+      if (styles && styles.__inject__) {
+        styles.__inject__(this.props.staticContext)
+      }
+    }
+
+    render() {
+      return (
+        <Component
+          {...this.props}
+          // use different axios instance on server
+          http={__SERVER__ ? this.props.staticContext.axios : axios}
+        />
+      )
+    }
+  }
+
+  return hoistStatics(
+    router ? withRouter(SsrConmponent) : SsrConmponent,
+    Component,
+  )
+}
+```
+
+Then use it:
+
+```js
+import PropTypes from 'prop-types'
+import React from 'react'
+import { connect } from 'react-redux'
+
+import { setCounter, increase, decrease } from 'store'
+import { withSsr } from 'utils'
+
+import styles from './styles'
+
+@withSsr(styles, false)
+@connect(
+  ({ counter }) => ({ counter }),
+  dispatch => ({
+    setCounter: counter => dispatch(setCounter(counter)),
+    increase: () => dispatch(increase),
+    decrease: () => dispatch(decrease),
+  }),
+)
+export default class Home extends React.PureComponent {
+  static propTypes = {
+    counter: PropTypes.number.isRequired,
+    setCounter: PropTypes.func.isRequired,
+    increase: PropTypes.func.isRequired,
+    decrease: PropTypes.func.isRequired,
+  }
+
+  asyncBootstrap() {
+    if (this.props.counter) {
+      return true
+    }
+
+    return new Promise(resolve =>
+      setTimeout(() => {
+        this.props.setCounter(~~(Math.random() * 100))
+        resolve(true)
+      }, 500),
+    )
+  }
+
+  render() {
+    return (
+      <div className="container">
+        <h2 className={styles.heading}>Counter</h2>
+        <button className="btn btn-primary" onClick={this.props.decrease}>
+          -
+        </button>
+        {this.props.counter}
+        <button className="btn btn-primary" onClick={this.props.increase}>
+          +
+        </button>
+      </div>
+    )
+  }
+}
+```
+
+Then `react-server-renderer` will automatically collect user styles on server and render them into output!
+
+---
+
+So actually it's not so simple right? Yes and no, if you choose to start using SSR, it is certain that you need pay for it, and after digging exist react SSR solutions like [react-universally](https://github.com/ctrlplusb/react-universally) or any other, I find out Vue's solution is really great and simple.
+
+## Feature Request or Troubleshooting
+
+Feel free to [create an issue](https://github.com/JounQin/react-server-renderer/issues/new).

package.json

@@ -1,8 +1,8 @@
 {
   "name": "react-server-renderer",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "simple React SSR solution inspired by vue-server-render",
-  "repository": "git@github.com:JounQin/react-server-render.git",
+  "repository": "git@github.com:JounQin/react-server-renderer.git",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
   "author": "JounQin <admin@1stg.me>",