https://github.com/Netflix/falcor
A JavaScript library for efficient data fetching
https://github.com/Netflix/falcor
Last synced: about 2 months ago
JSON representation
A JavaScript library for efficient data fetching
- Host: GitHub
- URL: https://github.com/Netflix/falcor
- Owner: Netflix
- License: apache-2.0
- Created: 2015-02-13T00:17:50.000Z (about 10 years ago)
- Default Branch: master
- Last Pushed: 2023-10-16T18:18:02.000Z (over 1 year ago)
- Last Synced: 2025-03-07T17:03:00.771Z (about 2 months ago)
- Language: JavaScript
- Homepage: http://netflix.github.io/falcor
- Size: 22.5 MB
- Stars: 10,490
- Watchers: 653
- Forks: 447
- Open Issues: 74
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
Awesome Lists containing this project
- awesome-github-repos - Netflix/falcor - A JavaScript library for efficient data fetching (JavaScript)
- awesome-list - falcor
- awesome-starred - Netflix/falcor - A JavaScript library for efficient data fetching (others)
README
# Falcor
[](https://travis-ci.org/Netflix/falcor)
[](https://coveralls.io/github/Netflix/falcor?branch=master)
## 2.0
**2.0** is the current stable Falcor release. **0.x** and **1.x** users are
welcome to upgrade.
- [Breaking changes between **1.x** and **2.0**](https://github.com/Netflix/falcor/blob/master/MIGRATIONS.md).
- [Breaking changes between **0.x** and **1.x**](https://github.com/Netflix/falcor/blob/1.0.0/MIGRATIONS.md).
## Roadmap
Issues we're tracking as part of our roadmap are tagged with the
[roadmap](https://github.com/Netflix/falcor/issues?q=is%3Aopen+is%3Aissue+label%3Aroadmap)
label. They are split into
[enhancement](https://github.com/Netflix/falcor/issues?q=is%3Aopen+is%3Aissue+label%3Aroadmap+label%3Aenhancement),
[stability](https://github.com/Netflix/falcor/issues?q=is%3Aopen+is%3Aissue+label%3Aroadmap+label%3Astability),
[performance](https://github.com/Netflix/falcor/issues?q=is%3Aopen+is%3Aissue+label%3Aroadmap+label%3Aperformance),
[tooling](https://github.com/Netflix/falcor/issues?q=is%3Aopen+is%3Aissue+label%3Aroadmap+label%3Atooling),
[infrastructure](https://github.com/Netflix/falcor/issues?q=is%3Aopen+is%3Aissue+label%3Aroadmap+label%3Ainfrastructure)
and
[documentation](https://github.com/Netflix/falcor/issues?q=is%3Aopen+is%3Aissue+label%3Aroadmap+label%3Adocumentation)
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](https://github.com/netflix/falcor-express-demo) 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:
```js
{
"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.
```bash
$ mkdir falcor-app-server
$ cd falcor-app-server
$ npm init
```
Now we install the falcor Router.
```bash
$ 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](https://github.com/Netflix/falcor-hapi).
```bash
$ npm install express --save
$ npm install falcor-express --save
```
Now we create an `index.js` file with the following contents:
```js
// 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`.
```bash
$ 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:
```html
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);
});
```
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
- Run `npm run dist` to build `dist/` locally
- Ensure the built files are not different from those built by Travis CI, hence creating no change to commit
- Update CHANGELOG with features/bug fixes to be released in the new version and 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
- For detailed high-level documentation explaining the Model, the Router, and JSON
Graph check out the [Falcor website](https://netflix.github.io/falcor).
- [API documentation](https://netflix.github.io/falcor/doc/Model.html)
- For a working example of a Router, check out the
[falcor-router-demo](https://github.com/netflix/falcor-router-demo).
- For questions and discussion, use [Stack
Overflow](https://stackoverflow.com/questions/tagged/falcor).