JavaScriptJavaScript driver

The section describes Fauna’s open source JavaScript driver, which provides the resources required to interact with FaunaDB.

Repository: fauna/faunadb-js

Supported runtimes

This driver supports and is tested on:

  • Node.js

    • LTS

    • Stable

  • Chrome

  • Firefox

  • Safari

  • Internet Explorer 11



npm install --save faunadb

See faunadb on NPM for more information.


Via CDN:

<script src="//"></script>

The minified version of the driver can also be used via CDN:

<script src="//"></script>


Requiring the driver

var faunadb = require('faunadb'),
  q = faunadb.query

This is the recommended require stanza. The faunadb.query module contains all of the functions to create FaunaDB Query expressions.

Instantiating a client and issuing queries

var client = new faunadb.Client({ secret: 'YOUR_FAUNADB_SECRET' })

Once the client has been instantiated, it can be used to issue queries. For example, to create an instance in an existing class named test with the data: { testField: 'testValue' }:

var createP = client.query(
    { data: { testField: 'testValue' } }

All methods on faunadb.Client return ES6 Promises. So, if we wanted to handle the Promise to access the Ref of the newly created instance:

createP.then(function(response) {
  console.log(response.ref); // Logs the ref to the console.

response is a JSON object containing the FaunaDB response. See the JSDocs for faunadb.Client.

By default, the client object executes queries using HTTP Keep-Alive requests, which means that the connection is held open longer than required to receive a query response. This behavior can reduce the connection overhead when your code needs to issue many queries.

Should you ever need to disable keep-alive connections, you can do so in the client constructor’s options:

var client = new faunadb.Client({
  keepAlive: false,

When keepAlive is set to false, each query that your code executes results in a separate HTTP connection to FaunaDB.

Pagination helpers

The driver contains helpers to provide a simpler API for consuming paged responses from FaunaDB. See the Paginate reference for a description of paged responses.

Using the helper to page over sets lets the driver manage cursors and pagination state. For example, client.paginate:

var helper = client.paginate(

The return value, helper, is an instance of PageHelper. The each method executes a callback function on each consumed page.

helper.each(function(page) {
  // Logs the page's contents,
  // for example: [ Ref(Collection("test"), "1234"), ... ]

Note that each returns a Promise<void> that is fulfilled on the completion of pagination.

The pagination can be transformed server-side via the Fauna Query Language by using the map and filter functions.

For example, to retrieve the matched instances:

  .map(function(ref) {
    return q.Get(ref)
  .each(function(page) {
    console.log(page); // Logs the retrieved documents.

See the JSDocs for more information on the pagination helper.

Per-query options

Some options (currently only secret) can be overridden on a per-query basis:

var createP = client.query(
      data: { testField: 'testValue' }
  { secret: 'YOUR_FAUNADB_SECRET' }
var helper = client.paginate(
  q.Match(q.Index('test_index'), 'example-term'),
  { secret: 'YOUR_FAUNADB_SECRET', }


The JavaScript driver includes no polyfills. Support for Internet Explorer 11 requires a Promise polyfill.

Next steps

Was this article helpful?

We're sorry to hear that.
Tell us how we can improve!

Thank you for your feedback!