JavaScript

This section is intended to help JavaScript developers get started using the Fauna JavaScript driver for application development.

Current version and repository location

Current stable version

4.8.2

Repository

Supported runtimes

This driver supports and is tested on:

  • Node.js

    • LTS

    • Stable

  • Chrome

  • Firefox

  • Safari

  • Internet Explorer 11

Installation

Node.js

npm install --save faunadb

See faunadb on NPM for more information.

Browsers

Via CDN:

<script src="//cdn.jsdelivr.net/npm/faunadb@latest/dist/faunadb.js"></script>

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

<script src="//cdn.jsdelivr.net/npm/faunadb@latest/dist/faunadb-min.js"></script>

Example application

The following example code runs a bare-bones Node.js application which creates a new document in a collection called scores.

Prerequisites

  • A Fauna account.

  • Node.js and the Fauna JavaScript driver. See Installation for driver installation help.

Procedure

  1. Navigate to the Fauna v4 Dashboard

    Log in to your Fauna account at v10 Fauna Dashboard if you’re not already logged in.

  2. Create a new database

    Create a new database and select your Region Group.

  3. Access the v4 Dashboard

    Access the Fauna v4 Dashboard by clicking the v4 Dashboard tab for the database.

  4. Create a new collection

    Under Collections, click NEW COLLECTION. Name your new collection People and save it.

  5. Create an access key

    Click SECURITY in the left-side navigation menu. Create a new key for your database. Be sure to save the key’s secret in a safe place, as it is only displayed once.

  6. Create a local environment variable with your access key’s secret

    On MacOS and Linux systems, enter the following in a terminal window:

    export FAUNADB_SECRET=<your-secret>

    For Windows systems, enter the following in a terminal window:

    set FAUNADB_SECRET=<your secret>

    For either example, replace <your secret> with the secret for the access key that you created.

  7. Create a local application file

    With your preferred editor, create a file called test.js with the following contents:

    const faunadb = require('faunadb')
    const q = faunadb.query
    
    const secret = process.env.FAUNADB_SECRET
    var endpoint = process.env.FAUNADB_ENDPOINT
    
    if (typeof secret === 'undefined' || secret === '') {
      console.error('The FAUNADB_SECRET environment variable is not set, exiting.')
      process.exit(1)
    }
    
    if (!endpoint) endpoint = 'https://db.fauna.com/'
    
    var mg, domain, port, scheme
    if ((mg = endpoint.match(/^(https?):\/\/([^:]+)(:(\d+))?/))) {
      scheme = mg[1] || 'https'
      domain = mg[2] || 'db.fauna.com'
      port = mg[4] || 443
    }
    
    const client = new faunadb.Client({
      secret: secret,
      domain: domain,
      port: port,
      scheme: scheme,
    })
    
    client.query(
      q.Create(
        q.Collection('People'),
        {
          data: {
            first: 'Linus',
            last: 'Torvalds',
            age: 52,
          },
        },
      )
    )
    .then((ret) => console.log(ret))
    .catch((err) => console.error(
      'Error: [%s] %s: %s',
      err.name,
      err.message,
      err.errors()[0].description,
    ))

    The above example app uses the Create function to create a new document in the People collection.

  8. Run your application

    In a terminal window, run the application:

    node test.js

    You should see results similar to this:

    {
      ref: Ref(Collection("People"), "324879521056555520"),
      ts: 1646088105160000,
      data: { first: 'Linus', last: 'Torvalds', age: 52 }
    }

    If you get an error, check to make sure your access key is correct.

\