falcor README

The project's README from github.com/Netflix/falcor. As one markdown file: 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

Additional Resources

falcor (Netflix/falcor)

Searching Database…

10.6K ·GitHub
Falcor
What is this?Falcor is a JavaScript library from Netflix for efficient data fetching, letting you model all your backend data as one virtual JSON graph that the client can query piece by piece instead of juggling many REST endpoints.
Is it a client library, a server framework, or both?It is a library used on both sides: a Model API on the client to query the JSON Graph, and a Router (with Express/Hapi/Restify middleware) on the server to resolve that virtual JSON into real data.
How do I get a basic Falcor server and client running?Install the falcor Router plus express and falcor-express, write an index.js that builds a Router and serves it at /model.json, then create an index.html that uses the Falcor Model to fetch keys from that endpoint over HTTP.
What does it depend on under the hood?The library itself depends on falcor-json-graph, falcor-path-syntax, falcor-path-utils and symbol-observable, and typical setups add express (or hapi/restify) plus falcor-express for the server transport.
Any catches when upgrading or adopting it?There are breaking changes between 0.x, 1.x and the current 2.0 release, so upgrading across major versions requires checking the changelog rather than a drop-in swap.
Who is this aimed at?It's aimed at JavaScript/Node backend and frontend developers building data-heavy apps (like Netflix's own UI) who want one unified data model instead of many bespoke REST calls.
What is JSON Graph?JSON Graph is the virtual JSON document model Falcor uses to represent an application's entire remote data set, which the Router builds on-demand from backend datastores or other services.
How does Falcor avoid the classic REST over-fetching problem?Instead of fixed endpoints, clients request specific paths in the shared JSON Graph, and the Router resolves only those paths, so requests return exactly the needed data in as few round trips as possible.
Where can I see a working example?There is a working example server built to resemble a Netflix-like application, plus a separate falcor-router-demo showing the Router in action.
Where do I ask questions about Falcor?The README points users to Stack Overflow for questions and discussion.
What are similar projects?express, koa, pollyjs, multer, node-restify, ky, fiber, pino
Which topics is it in?express, http, json, rest-api, backend, npm, frontend, api, apache-2.0, server, nodejs, library
Creator
Netflix
Size
23.1 MB
Stars
10.6K
Updated
CommitAug 28
Age
11y
Commits · 90 Days