A JavaScript library for efficient data fetching
JavaScript Shell
Failed to load latest commit information.
build Move Promise shimming to build step. Apr 22, 2016
dist Travis build 489 committed dist/ and doc/ Jan 16, 2017
doc Travis build 482 committed dist/ and doc/ Nov 30, 2016
examples/datasource Update webWorkerSource to work with the the newest falcor Feb 12, 2016
lib Fixed cherry-pick merge conflict Jan 13, 2017
performance feat(performance): The last of the statically referred to keys. Jan 9, 2016
test Added tests for errorSelector change type support Jan 13, 2017
.bithoundrc Trying to figure out what file glob format bithound likes. Apr 1, 2015
.editorconfig feat: editorconfig Jan 14, 2016
.eslintrc Use eslint 2 Apr 19, 2016
.gitignore Commit docs to branch on developer site build Feb 23, 2016
.travis.yml Remove node 0.10 from tests as we use global Promise. Apr 22, 2016
CHANGELOG.md Update CHANGELOG with errorSelector changes Jan 13, 2017
LICENSE.txt added Apache 2 license file. May 2, 2015
MIGRATIONS.md Document new approach to Promise shimming. Apr 25, 2016
OSSMETADATA adding OSSMETADATA for NetflixOSS tracking Dec 11, 2015
README.md Some of the final changes for 1.x Feb 4, 2016
all.js Adding all build target so Router can be used in browser Sep 6, 2015
authors.txt added authors.txt. May 2, 2015
bower.json expand set of bower ignored files Jan 18, 2016
browser.js Fix lint errors in browser.js Aug 19, 2015
conf.json updating documentation. May 3, 2015
gulpfile.js Use eslint 2 Apr 19, 2016
package.json fix(ModelResponse): ensure proper Symbol.observable implementation Nov 5, 2016
server.js Fix eslint errors in server.js Aug 19, 2015
webpack.config.js Fix eslint in webpack.config.js Aug 19, 2015


Falcor Build Status Coverage Status bitHound Score

Developer Preview

1.x does not mean we are out of developer preview mode. Simply means we are breaking the contract and we would like to respect ^ within peoples NPM dependencies. 1.x does contain breaking changes that can be reviewed here

This release is a developer preview. We are looking for community help to track down and fix bugs. We are also looking for help integrating with existing MVC frameworks, as well as ports to other platforms.

  • master currently reflects work in progress, and contains backward incompatible changes which will become the next major version bump.
  • 0.x reflects the currently published npm version. Bug fixes specific to 0.x can be submitted against this branch.

Important Note for Webpack Users

If you're including falcor in your app, via npm and require('falcor'), and you're building a browser bundle for your app with Webpack, you'll need to add an alias entry for the 'rx' module in your webpack config, to avoid this RxJS bug: 'https://github.com/Reactive-Extensions/RxJS/issues/832'. You may already have such an entry, if you're using RxJS already. An example is below:

In webpack.config.js:

module.exports = {
  resolve: {
    alias: {
      // Workaround https://github.com/Reactive-Extensions/RxJS/issues/832, until it's fixed
      'rx$': <path to rx/dist/rx.js file >

Getting Started

You can check out a working example server for a Netflix-like application here right now. Alternately you can go through this barebones tutorial in which we use the Falcor Router to create a Virtual JSON resource. In this tutorial we will use Falcor's express middleware to serve the Virtual JSON resource on an application server at the URL /model.json. We will also host a static web page on the same server which retrieves data from the Virtual JSON resource.

Creating a Virtual JSON Resource

In this example we will use the falcor Router to build a Virtual JSON resource on an app server and host it at /model.json. The JSON resource will contain the following contents:

  "greeting": "Hello World"

Normally Routers retrieve the data for their Virtual JSON resource from backend datastores or other web services on-demand. However in this simple tutorial the Router will simply return static data for a single key.

First we create a folder for our application server.

mkdir falcor-app-server
cd falcor-app-server
npm init

Now we install the falcor Router.

npm install falcor-router --save

Then install express and falcor-express. Support for restify is also available, as is support for hapi via a third-party implementation.

npm install express --save
npm install falcor-express --save

Now we create an index.js file with the following contents:

// index.js
var falcorExpress = require('falcor-express');
var Router = require('falcor-router');

var express = require('express');
var app = express();

app.use('/model.json', falcorExpress.dataSourceRoute(function (req, res) {
  // create a Virtual JSON resource with single key ("greeting")
  return new Router([
      // match a request for the key "greeting"
      route: "greeting",
      // respond with a PathValue with the value of "Hello World."
      get: function() {
        return {path:["greeting"], value: "Hello World"};

// serve static files from current directory
app.use(express.static(__dirname + '/'));

var server = app.listen(3000);

Now we run the server, which will listen on port 3000 for requests for /model.json.

node index.js

Retrieving Data from the Virtual JSON resource

Now that we've built a simple virtual JSON document with a single read-only key "greeting", we will create a test web page and retrieve this key from the server.

Now create an index.html file with the following contents:

<!-- index.html -->
    <!-- Do _not_  rely on this URL in production. Use only during development.  -->
    <script src="https://netflix.github.io/falcor/build/falcor.browser.js"></script>
    <!-- For production use. -->
    <!-- <script src="https://cdn.jsdelivr.net/falcor/{VERSION}/falcor.browser.min.js"></script> -->
      var model = new falcor.Model({source: new falcor.HttpDataSource('/model.json') });

      // retrieve the "greeting" key from the root of the Virtual JSON resource
        then(function(response) {

Now visit http://localhost:3000/index.html and you should see the message retrieved from the server:

Hello World

Additional Resources

For detailed high-level documentation explaining the Model, the Router, and JSON Graph check out the Falcor website.

For API documentation, go here

For a working example of a Router, check out the falcor-router-demo.

For questions and discussion, use Stack Overflow.