Merge pull request #5 from yoshuawuyts/server-side-rendering

Server side rendering

README.md

@@ -19,6 +19,7 @@ productive package.
   - [server sent events](#server-sent-events-sse)
   - [keyboard](#keyboard)
   - [websockets](#websockets)
+- [Rendering in Node](#rendering-in-node)
 - [API](#api)
 - [FAQ](#faq)
 - [Installation](#installation)
@@ -27,7 +28,7 @@ productive package.
 ## Features
 - __minimal size:__ weighing under `8kb`, `choo` is a tiny little framework
 - __single state:__ immutable single state helps reason about changes
-- __small api:__ with only 5 methods, there's not a lot to learn
+- __small api:__ with only 6 methods, there's not a lot to learn
 - __minimal tooling:__ built for the cutting edge `browserify` compiler
 - __transparent side effects:__ using "effects" and "subscriptions" brings
   clarity to IO
@@ -223,6 +224,52 @@ app.model({
 })
 ```
 
+## Rendering in Node
+Sometimes it's necessary to render code inside of Node; for serving first
+requests, testing or other purposes. Applications that are capable of being
+rendered in both Node and the browser are called _[isomorphic
+applications][isomorphic]_.
+
+Rendering in Node is slightly different than in the browser. First off, to
+maintain performance all calls to `subscriptions`, `effects`, and `reducers`
+are disabled. That means you need to know what the state of your application is
+going to be _before_ you render it - no cheating!
+
+Secondly, the `send()` method inside `router` and `view` has been disabled. If
+you call it your program will crash (give it a try, just to see!)
+
+Disabling all these things means that your program will render [`O(n)`][big-o]
+(computer science speak for "constant time"), which is super neat. Off to
+[10.000 QPS][qps] we go!
+
+To render in Node call the `.toString()` method instead of `.start()`. The
+first argument is the path that should be rendered, the second is the state:
+```js
+const http = require('http')
+const client = require('./client')  // path to client entry point
+http.createServer(function (req, res) {
+  const html = client.toString('/', { message: 'hello server!' })
+  res.setHeader('Content-Type', 'text/html; charset=utf-8')
+  res.end(html)
+})
+```
+
+In order to make our `choo` app call `app.start()` in the browser and be
+`require()`-able in Node, we check if [`module.parent`][module-parent] exists:
+```js
+const choo = require('choo')
+const app = choo()
+
+app.router((route) => [
+  route('/', (params, state, send) => choo.view`
+    <h1>${state.message}</h1>
+  `)
+])
+
+if (module.parent) module.exports = app
+else document.body.appendChild(app.start())
+```
+
 ## API
 ### app = choo()
 Create a new `choo` app
@@ -252,6 +299,12 @@ Creates a new router. See
 documentation. Registered views have a signature of `(params, state, send)`,
 where `params` is URI partials.
 
+### html = app.toString(route, state)
+Render the application to a string. Useful for rendering on the server. First
+argument is a path that's passed to the router. Second argument is the state
+object. When calling `.toString()` instead of `.start()`, all calls to `send()`
+are disabled, and `subscriptions`, `effects` and `reducers` aren't loaded.
+
 ### tree = app.start()
 Start the application. Returns a DOM element that can be mounted using
 `document.body.appendChild()`.
@@ -263,21 +316,28 @@ Start the application. Returns a DOM element that can be mounted using
 - __preact:__ [tbi]
 - __angular2:__ [tbi]
 
-## Which packages was choo built on?
+### Which packages was choo built on?
 - __views:__ [`yo-yo`](https://github.com/maxogden/yo-yo)
 - __models:__ [`send-action`](https://github.com/sethvincent/send-action),
   [`xtend`](https://github.com/raynos/xtend)
 - __routes:__ [`sheet-router`](https://github.com/yoshuawuyts/sheet-router)
 - __http:__ [`xhr`](https://github.com/Raynos/xhr)
 
-## What packages do you recommend to pair with choo?
+### Does choo use a virtual-dom?
+`choo` uses [morphdom][morphdom], which diffs real DOM nodes instead of virtual
+nodes. It turns out that [browsers are actually ridiculously good at dealing
+with DOM nodes][morphdom-bench], and it has the added benefit of working with
+_any_ library that produces valid DOM nodes. So to put a long answer short:
+we're using something even better.
+
+### What packages do you recommend to pair with choo?
 - [tachyons](https://github.com/tachyons-css/tachyons) - functional CSS for
   humans
 - [sheetify](https://github.com/stackcss/sheetify) - modular CSS bundler for
   browserify
 - [pull-stream](https://github.com/pull-stream/pull-stream) - minimal streams
 
-## How can I optimize choo?
+### How can I optimize choo?
 To bring down file size, consider running the following `browserify`
 transforms:
 - [unassertify](https://github.com/twada/unassertify) - remove `assert()`
@@ -307,7 +367,14 @@ $ npm install choo
 [9]: https://npmjs.org/package/choo
 [10]: https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat-square
 [11]: https://github.com/feross/standard
+
 [dom]: https://en.wikipedia.org/wiki/Document_Object_Model
 [keyboard-support]: https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent#Browser_compatibility
 [sse]: https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events
 [ws]: https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API
+[isomorphic]: https://en.wikipedia.org/wiki/Isomorphism
+[big-o]: https://rob-bell.net/2009/06/a-beginners-guide-to-big-o-notation/
+[qps]: https://en.wikipedia.org/wiki/Queries_per_second
+[morphdom]: https://github.com/patrick-steele-idem/morphdom
+[morphdom-bench]: https://github.com/patrick-steele-idem/morphdom#benchmarks
+[module-parent]: https://nodejs.org/dist/latest-v6.x/docs/api/modules.html#modules_module_parent

examples/server/client.js

@@ -0,0 +1,16 @@
+const choo = require('../../')
+
+const mainView = require('./views/main')
+
+const app = choo()
+
+app.router((route) => [
+  route('/', mainView)
+])
+
+if (module.parent) {
+  module.exports = app
+} else {
+  const tree = app.start()
+  document.body.appendChild(tree)
+}

examples/server/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "http",
+  "private": true,
+  "main": "client.js",
+  "scripts": {
+    "start": "NODE_ENV=development node server.js"
+  },
+  "dependencies": {
+    "bankai": "^2.0.2",
+    "browserify": "^13.0.1",
+    "server-router": "^2.1.0"
+  }
+}

examples/server/server.js

@@ -0,0 +1,22 @@
+const serverRouter = require('server-router')
+const http = require('http')
+
+const PORT = 8080
+
+const client = require('./client')
+
+const server = http.createServer(createRouter())
+server.listen(PORT, () => console.log(`listening on port ${PORT}`))
+
+function createRouter () {
+  const router = serverRouter('/404')
+
+  router.on('/404', (req, res) => res.end('not found'))
+  router.on('/', function (req, res, params) {
+    const html = client.toString('/', { message: 'hello server!' })
+    res.setHeader('Content-Type', 'text/html; charset=utf-8')
+    res.end(html)
+  })
+
+  return router
+}

examples/server/views/main.js

@@ -0,0 +1,10 @@
+const choo = require('../../../')
+
+module.exports = function (params, state, send) {
+  const message = state.message
+  return choo.view`
+    <section>
+      <h1>${message}</h1>
+    </section>
+  `
+}

index.js

@@ -14,15 +14,31 @@ module.exports = choo
 function choo (opts) {
   opts = opts || {}
   const name = opts.name || 'choo'
+  const _models = []
   var _router = null
-  var _models = [ appInit(opts) ]
 
+  start.toString = toString
   start.router = router
   start.model = model
   start.start = start
 
   return start
 
+  // render the application to a string
+  function toString (route, state) {
+    const initialState = {}
+
+    _models.forEach(function (model) {
+      if (model.state) apply(model.name, model.state, initialState)
+    })
+
+    const tree = _router(route, xtend(initialState, state), function () {
+      throw new Error('send() cannot be called on the server')
+    })
+
+    return tree.toString()
+  }
+
   // start the application
   // null -> DOMNode
   function start () {
@@ -30,6 +46,7 @@ function choo (opts) {
     const reducers = {}
     const effects = {}
 
+    _models.push(appInit(opts))
     _models.forEach(function (model) {
       if (model.state) apply(model.name, model.state, initialState)
       if (model.reducers) apply(model.name, model.reducers, reducers)

scripts/test-size

@@ -5,7 +5,7 @@
 #   -t uglifyify \
 #   | discify --open
 
-browserify index.js --full-paths \
+browserify index.js \
   -g unassertify \
   -g uglifyify \
   | uglifyjs \