Getting Started

Environment

IDX needs to access the Ceramic network using an implementation of the Ceramic API as exported by the @ceramicnetwork/common library.

Packages implementing this interface include @ceramicnetwork/core and @ceramicnetwork/http-client.

Alpha release

IDX is currently in alpha and may be unstable.

Installation

There are two main libraries to use when building apps for IDX

IDX client library

This library is used by apps to interact with Ceramic and IDX documents

npm install @ceramicstudio/idx

IDX tools library

This library contains tools for developers to help create the data models used by apps

npm install --dev @ceramicstudio/idx-tools

Definitions and Schemas

All Documents attached to the Identity Index need to use a Definition.

Once a public Ceramic network is running, the IDX library will provide a set of Definitions that can be used directly, but in the meantime these needs to be defined by developers using IDX.

To create a Defininition, a specific Schema needs to be used, and therefore must be present on the Ceramic node used by the IDX instance. The idx-tools library can be used to easily publish schemas to the Ceramic node:

import { publishIDXConfig } from '@ceramicstudio/idx-tools'

// First we need to make sure the IDX config (definitions and schemas) are published on the Ceramic node

// Here `ceramic` implements the CeramicApi interface

const { definitions } = await publishIDXConfig(ceramic)

const appDefinitions = {

profile: definitions.basicProfile,

}

// Export the created `appDefinitions` so they can be used at runtime

Example usage

import { IDX } from '@ceramicstudio/idx'

// Import definitions created during development or build time

import { definitions } from './app-definitions'

// A first user (Alice) can set her profile on her IDX Document using the definition alias used by the app

const aliceIndex = new IDX({ ceramic, definitions })

await aliceIndex.set('profile', { name: 'Alice' })

// Other users (such as Bob) can read from known Indexes using the same definion alias and Alice's DID

const bobClient = new IDX({ ceramic, definitions })

const aliceProfile = await bobClient.get('profile', aliceIndex.id)