Tungsten.js is a modular framework for creating web UIs with high-performance rendering on both server and client.
- High-performance virtual DOM updates powered by virtual-dom
- Use of mustache templates, parsed with Ractive.js, which render to virtual DOM objects
- Event system which binds and delegates each event type to the document root
- Adaptor for Backbone.js or Ampersand.js views and models
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
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. There is also a similar Ampersand.js adaptor available. The preferred adaptor can be included via CommonJS or ES6 Modules at tungstenjs/adaptors/backbone/index.js or tungstenjs/adaptors/ampersand/index.js and exposes base modules for Backbone or Ampersand (as well as a direct reference to Backbone or Ampersand itself).
Tungsten.js has no dependency on jQuery.
npm install tungstenjs --save
For the latest, but unstable, version:
npm install git+http://github.com:wayfair/tungstenjs.git#master --save
The UMD build is also available for including Tungsten.js in a project. It assumes underscore is included as window._. Other dependencies are bundled in the build.
<!-- Include underscore -->
<script src="//cdnjs.cloudflare.com/ajax/libs/underscore.js/1.8.3/underscore-min.js"></script>
<!-- Backbone.js Adaptor -->
<script src="./node_modules/tungstenjs/dist/tungsten.backbone.js"></script>For compiling templates, ractive at window.Ractive is necessary. The template compiler is bundled in the build (ordinarily precompiling templates would be done on the server):
<!-- Include Ractive for parsing templates -->
<script src="//cdn.ractivejs.org/latest/ractive.js"></script>
<!-- to compile templates, use tungsten._template.compileTemplates({myTemplate: 'Hello {{name}.'})` -->An client-side only example of a Tungsten.js app using the UMD build is available in the examples.
The recommended method of adding Tungsten.js to your application is via 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 webpack build:
module.exports = {
// [...]
resolve: {
alias: {
'jquery': path.join(__dirname, '../src/polyfill/jquery')
}
}
};See examples for more details.
Node.js(for builds; not necessary for production runtime)webpackor other CommonJS compatible client-side module loader- {{ mustache }} renderer on server (for server-side rendering)
The Backbone.js adaptor can be included by requiring tungstenjs/adaptors/backbone after installing the tungstenjs Node module. Similarly, the Ampersand.js adaptor can be included by requiring tungstenjs/adaptors/ampersand. Each of these adaptors provide a view, model, and collection property which should be used as the base view, model, and collection constructors in the application. As usual with Backbone and Ampersand, custom constructors can extend from each of these.
When using the Backbone or Ampersand adaptor, 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.
Detailed documentation on Tungsten.js features can be found in /docs:
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.
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:
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.