cinject v1.0.0

cinject

An isomorphic rendering framework for React. It uses React, as well as Cheerio on the server and jQuery on the client.

Features

• Render entire documents on the server and reconcile them on the client
• Serialize and synchronize state
• Define component properties asynchronously
• Selectively expose components and other variables when evaluating node attributes

Installation

Install it from NPM:

npm install cinject

Usage

Document format

The package relies on properly formatted documents to know which elements are meant to be components. To specify a component, add the _component attribute to the desired containing node. Any other attributes specified on this node will be passed as properties to the component when it is rendered.

To evaluate attributes as JavaScript, surround them with curly braces like in JSX. Note that there are some limitations with the regular expression parsing and such values may require special formatting, such as replacing quotes with single quotes or ".

A component in an HTML document might look something like this:

<div _component=Navigation sections="{['About us', 'Gallery', 'Contact']}"></div>

Rendering and reconciling

The package is meant to be used on both the server and client, but each has slightly different dependencies and must access different files depending on the environment. Currently, it suppots Browserify with the browser field in its package.json file. If you would like to use it with a different packaging tool, please submit a pull request!

First, load the package and create a new rendering context. The purpose of this abstraction is to be able to selectively expose components and variables.

var cinject = require("cinject")(acquirerComponents, contextualizer);

The acquirerComponents is a potentially asynchronous function that returns a component of a given name. If omitted, it will simply call require.

The contextualizer argument is a string that is evaluated in the context of the attribute parser which can be used to expose variables. For example, you may use this to set a variable to an object exposing application-specific logic so you don't need to access a global variable or import a package when evaluating every single component property.

To render or reconcile the components on a page, call the cinject context with the page source (on the server) or root node of the document (on the client), the page's state, and the current URL query parameters of the page. This will return a promise. On the client, it will resolve to the parsed source. On the client, it will transform the document automatically.

cinject(source, {
	user: "John Doe"
}, url.parse(request.url).query).then(function(sourceRendered) {
	...
};