Skip to content

Installing the JS HTTP Client

This guide descibes how to install the JS HTTP Client so your JavaScript application can perform writes, queries, or pins on a remote Ceramic node during runtime.

Requirements

Installing the JS HTTP Client requires a console, Node.js v14, and npm v6. Make sure to have these installed on your machine.

While npm v7 is not officially supported, you may still be able to get it to work. However you will need to install the node-pre-gyp package globally. This is required until node-webrtc, which IPFS depends on, is upgraded.

npm install -g node-pre-gyp

1. Install the HTTP client

Open your console and install the JS HTTP Client using npm.

npm install @ceramicnetwork/http-client

2. Import the HTTP client

import CeramicClient from '@ceramicnetwork/http-client'

3. Configure your node URL

const API_URL = "https://yourceramicnode.com"

Available options for your node setup:

  • Free community nodes: Discover free HTTP endpoints
  • Commercial node providers: Discover paid node providers
  • Host your own node: Learn how to setup and host your own node
  • localhost: You may want to use the JS HTTP Client with a Ceramic node running on your local machine for development and testing. To achieve this, first start a local daemon by installing the CLI. Once the CLI is installed, you can pass https://localhost:7007 to the HTTP client. This setup will allow you to read streams from other nodes connected on the Ceramic network, but writes to your local node will only be available on nodes found on the peerlist. For now, these streams will not be available to other nodes on the network due to a limitation in js-ipfs which will be fixed in the future.

4. Create a Ceramic instance

const ceramic = new CeramicClient(API_URL)

5. Import DID resolvers

Import the DID resolvers for all DID methods that will need to authenticate to perform writes using this HTTP Client. If your HTTP Client will only perform queries, then jump ahead to the queries page.

import KeyDidResolver from 'key-did-resolver'
import ThreeIdResolver from '@ceramicnetwork/3id-did-resolver'

6. Create a DID instance

Create a DID instance which wraps an instance of a DID resolver that includes all individual DID resolvers from the previous step. It should also include a DID Provider for the DID Method you are using for authentication.

import { DID } from 'dids'
const resolver = { ...KeyDidResolver.getResolver(),
                   ...ThreeIdResolver.getResolver(ceramic) }
const did = new DID({ resolver })

7. Set DID instance on HTTP client

ceramic.did = did

Next steps

If your application needs to perform writes, proceed to setting up authentication. If your app only needs to perform queries, then jump ahead to queries.