@ndreckshage/tungstenjs

Tungsten.js is a modular framework for creating web UIs with high-performance rendering on both server and client.

wayfair.github.io/tungstenjs/

What Tungsten.js Provides

• High-performance virtual DOM updates powered by virtual-dom
• Use of mustache templates, with HTML parsed by htmlparser2, which render to virtual DOM objects
• Event system which binds and delegates each event type to the document root
• Adaptor for Backbone.js views and models

Motivation

Tungsten.js was built as an alternative to existing front-end JavaScript libraries because we needed a library with:

• Fast, first-class server-side rendering across multiple platforms
• Fast client-side DOM updates with support back to IE8
• Modular interfaces to swap out library components as necessary

How Tungsten.js Works

In Tungsten.js, the initial page loaded is rendered with Mustache templates on the server (in, say, C++, PHP, or Go) then rehydrated by Tungsten.js on the client. Subsequent DOM updates are made with those same mustache templates which have been pre-compiled to functions which return virtual DOM objects used by virtual-dom to diff and patch the existing DOM.

An adaptor layer is used to connect with Tungsten.js with a preferred modular client-side framework to handle data and view management. The default adaptor is a thin layer on top of Backbone.js with a childViews hash to define relationships between views and a compiledTemplate property to define the root pre-compiled template function. Other adaptors can also be used with the core library.

Tungsten.js has no dependency on jQuery.

Setup

Install

npm install tungstenjs --save

For the latest, but unstable, version:

npm install git+http://github.com:wayfair/tungstenjs.git#master --save

UMD

The UMD build is the preferred method for including Tungsten.js in a project, and is generally included via require('tungstenjs'). Dependencies are bundled in the build. It exposes underscore and backbone as tungstenjs._ and tungstenjs.Backbone to be used globally if necessary.

To compile templates, use tungsten.templateHelper.compileTemplates({myTemplate: 'Hello {{name}.'}). Ordinarily this is done on the server at build time.

An client-side only example of a Tungsten.js app using the UMD build is available in the examples.

Bundler (e.g., webpack)

Tungsten.js can be built for your application using a module bundler such as webpack. Because Backbone expects jQuery to be present, Tungsten.js includes a jQuery-less shim, src/polyfill/jquery, which is included in the default build.

Requirements

• Node.js (for builds; not necessary for production runtime)
• webpack or other CommonJS compatible client-side module loader
• {{ mustache }} renderer on server (for server-side rendering)

API

The API a developer interacts with when building an API with Tungsten.js is the API of the Backbone adaptor, which provides View, Model, and Collection properties. These are available directly when importing the Tungsten.js build and are used as the base view, model, and collection constructors in the application. As usual with Backbone, custom constructors can extend from each of these.

Getting Started

When building a Tungsten.js app we recommend starting with an app model, app view, and app (mustache) template. These are the entry points for a Tungsten.js applications. A place to bootstrap the app and get everything started is also needed: often this is in the form of an init file:

var AppView = require('./views/app_view');
var AppModel = require('./models/app_model');
var template = require('../templates/app_view.mustache');

module.exports = new AppView({
  el: '#app',
  template: template,
  model: new AppModel(window.data)
});

See the Tungsten.js TodoMVC app for a complete example.

Documentation

Detailed documentation on Tungsten.js features can be found in /docs:

• Templates
• Views
• Models
• Components
• Debugger

Versioning

master changes regularly and so is unsafe and may break existing APIs. Published releases, however, attempt to follow semver. High level changelog available at CHANGELOG.md.

Credits

Tungsten.js was created by Matt DeGennaro and is maintained by the JavaScript team at Wayfair. Contributions are welcome.

Tungsten.js uses portions of these and other open source libraries:

• virtual-dom
• vdom-virtualize
• htmlparser2
• backbone
• backbone-nested-models
• Tocca.js

License

Tungsten.js is distributed with an Apache Version 2.0 license. See LICENSE for details. By contributing to Tungsten.js, you agree that your contributions will be licensed under its Apache Version 2.0 license.