A JavaScript library for efficient data fetching
ntower and NickHeiner Update README.md (#945)
Fix minor syntax error in example.
Latest commit ffff212 Aug 23, 2018
Permalink
Failed to load latest commit information.
build chore: modified README and MIGRATIONS text to prepare for 2.0.0 Feb 26, 2018
dist Travis build 711 committed dist/ and doc/ Aug 7, 2018
doc Travis build 711 committed dist/ and doc/ Aug 7, 2018
examples/datasource Update webWorkerSource to work with the the newest falcor Feb 12, 2016
lib Merge pull request #941 from Netflix/fix-stack-traces Aug 7, 2018
performance feat(performance): The last of the statically referred to keys. Jan 9, 2016
test Merge pull request #941 from Netflix/fix-stack-traces Aug 7, 2018
.bithoundrc Trying to figure out what file glob format bithound likes. Apr 1, 2015
.editorconfig feat: editorconfig Jan 14, 2016
.eslintrc fixed existing tests and lint issues Oct 6, 2017
.gitignore Omit vscode Jul 24, 2017
.npmignore added npmignore for not publishing tests with npm package Sep 22, 2017
.travis.yml Node 4 is no longer maintained. Added Node 8. May 23, 2018
CHANGELOG.md chore(CHANGELOG): Added 2.0.3 to CHANGELOG Jul 27, 2018
LICENSE.txt added Apache 2 license file. May 2, 2015
MIGRATIONS.md chore: modified README and MIGRATIONS text to prepare for 2.0.0 Feb 26, 2018
OSSMETADATA adding OSSMETADATA for NetflixOSS tracking Dec 11, 2015
README.md Update README.md (#945) Aug 23, 2018
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
deployKey.enc Removed oAuth token, using ssh instead May 18, 2017
gulpfile.js Use eslint 2 Apr 19, 2016
package-lock.json chore: update package-lock.json so fsevents dev dependency builds on … Jul 31, 2018
package.json test(ExpressIntegration): Fixed express integration test by simplifying Jul 27, 2018
server.js Fix eslint errors in server.js Aug 19, 2015
webpack.config.js Fix eslint in webpack.config.js Aug 19, 2015

README.md

Falcor

Build Status Coverage Status

2.0

2.0 is the current stable Falcor release. 0.x and 1.x users are welcome to upgrade.

Roadmap

Issues we're tracking as part of our roadmap are tagged with the roadmap label. They are split into enhancement, stability, performance, tooling, infrastructure and documentation categories, with near, medium and longer term labels to convey a broader sense of the order in which we plan to approach them.

Getting Started

You can check out a working example server for Netflix-like application 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
const falcorExpress = require('falcor-express');
const Router = require('falcor-router');

const express = require('express');
const 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: () => ({path: ['greeting'], value: 'Hello World'})
    }
  ]);
}));

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

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.

Create an index.html file with the following contents:

<!-- index.html -->
<html>
  <head>
    <!-- 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> -->
    <script>
      var model = falcor({source: new falcor.HttpDataSource('/model.json') });

      // retrieve the "greeting" key from the root of the Virtual JSON resource
      model.
        get('greeting').
        then(function(response) {
          document.write(response.json.greeting);
        });
    </script>
  </head>
  <body>
  </body>
</html>

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

Hello World

Steps to publish new version

  • Make pull request with feature/bug fix and tests
  • Merge pull request into master after code review and passing Travis CI checks
  • Run git checkout master to open master branch locally
  • Run git pull to merge latest code, including built dist/ and docs/ by Travis
  • Update CHANGELOG with features/bug fixes to be released in the new version
  • Run npm run prepare to build dist/ locally
  • Ensure the built files are not different from those built by Travis CI, hence creating no change to commit
  • Run npm version patch (or minor, major, etc) to create a new git commit and tag
  • Run git push origin master && git push --tags to push code and tags to github
  • Run npm publish to publish the latest version to NPM

Additional Resources