# falcor

> A JavaScript library for efficient data fetching.

Latest version **2.4.1** (published 2025-08-28) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install falcor
pnpm add falcor
yarn add falcor
bun add falcor
```

## Health

**Score 33/100 (F)** — status: maintenance-mode.

Positive: has types package; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.4.1 |
| Published | 2025-08-28 |
| First published | 2015-06-30 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | separate (@types/falcor) |
| Module format | CommonJS |
| Dependencies | 4 |
| Unpacked size | 2 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Netflix |
| Maintainers | kkwon, kaylie, donutespresso, tbranyen, tvui-user, tvuiops-user, gsimpson, barb_the_builder, mmarchini, wesleytodd, satyend |
| Keywords | JSON, Netflix, Observable, falcorjs |

## Links

- npm: https://www.npmjs.com/package/falcor
- Repository: https://github.com/Netflix/falcor
- Issues: https://github.com/Netflix/falcor/issues
- npm.io page: https://npm.io/package/falcor

## Dependencies (4)

- [falcor-json-graph](https://npm.io/package/falcor-json-graph.md) ^1.1.7
- [falcor-path-utils](https://npm.io/package/falcor-path-utils.md) ^0.7.5
- [symbol-observable](https://npm.io/package/symbol-observable.md) ^1.2.0
- [falcor-path-syntax](https://npm.io/package/falcor-path-syntax.md) ^0.2.4

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 2.4.1 (latest) — 2025-08-28
- 2.4.0 — 2025-08-26
- 2.3.2 — 2021-03-29
- 2.2.2 — 2020-08-03
- 2.2.1 — 2020-08-03
- 2.2.0 — 2020-01-24
- 2.1.0 — 2019-07-10
- 2.0.7 — 2019-05-06
- 2.0.6 — 2019-03-05
- 2.0.5 — 2018-11-19
- 2.0.4 — 2018-10-18
- 2.0.3-observe-46bc9629 — 2018-08-24
- 2.0.3 — 2018-07-27
- 2.0.3-schema-support-1 — 2018-07-12
- 2.0.2 — 2018-06-07
- … 27 more at https://npm.io/package/falcor/versions

## README

<p align="center">
  <img src="https://cloud.githubusercontent.com/assets/1016365/8711049/66438ebc-2b03-11e5-8a8a-75934f7ca7ec.png">
</p>

# Falcor

[![Build Status](https://travis-ci.org/Netflix/falcor.svg)](https://travis-ci.org/Netflix/falcor)
[![Coverage Status](https://coveralls.io/repos/Netflix/falcor/badge.svg?branch=master&service=github)](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
<!-- 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
-   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).

---
_Source: https://npm.io/package/falcor · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._