.. and press ENTER to ask a question on web5, how to write code and more.

Skip to main content

Web5.connect()

The Web5 JS SDK provides a simple interface to get started building Web5 applications quickly. It provides APIs to use Decentralized Identifiers (DIDs) and Decentralized Web Nodes (DWNs) right away by initializing the SDK through Web5.connect().


caution

WEB5 JS SDK IS CURRENTLY IN TECH PREVIEW

The SDK is currently still in Tech Preview and under active development. Additional functionality will be added in the lead up to version 1.0, and modifications will be made to address issues and community feedback.

Install

npm install @web5/api

Import

Node 19+
import { Web5 } from '@web5/api';
Node <=18
/*
Needs globalThis.crypto polyfill.
This is *not* the crypto you're thinking of.
It's the original crypto...CRYPTOGRAPHY.
*/
import { webcrypto } from "node:crypto";
import { Web5 } from '@web5/api';

// @ts-ignore
if (!globalThis.crypto) globalThis.crypto = webcrypto;
React Native
/*
React Native needs crypto.getRandomValues polyfill and sha512.
This is *not* the crypto you're thinking of.
It's the original crypto...CRYPTOGRAPHY.
*/
import "react-native-get-random-values";
import { hmac } from "@noble/hashes/hmac";
import { sha256 } from "@noble/hashes/sha256";
import { sha512 } from "@noble/hashes/sha512";
import { Web5 } from '@web5/api';

ed.etc.sha512Sync = (...m) => sha512(ed.etc.concatBytes(...m));
ed.etc.sha512Async = (...m) => Promise.resolve(ed.etc.sha512Sync(...m));

secp.etc.hmacSha256Sync = (k, ...m) =>
hmac(sha256, k, secp.etc.concatBytes(...m));
secp.etc.hmacSha256Async = (k, ...m) =>
Promise.resolve(secp.etc.hmacSha256Sync(k, ...m));

Connect

Using Web5.connect(), an instance of Web5 is created that enables an app to connect to an existing decentralized identifier (DID) either by direct creation or connection to an identity agent app or create a new one. The method also creates a locally running Decentralized Web Node (DWN) and associates it with the DID.

This local DWN is synchronized with a remote DWN node (if specified) that enables connectivity and sync across the user's devices and other users. While the Web5 JS SDK is in technical preview, a remote DWN is automatically provisioned and connected to the local DWN - syncing every 2 minutes.

const { web5, did: userDid } = await Web5.connect();

Options

Enables an app to request connection to a user's local identity app (like a desktop or mobile agent - work is underway for reference apps of each), or generate an in-app DID to represent the user (e.g. if the user does not have an identity app)

note

The outputs of this method invocation will be used throughout the other API methods.

Parameters

options
Web5ConnectOptions
optional
Show parameters


agent
Web5Agent
optional
An instance of a Web5Agent implementation. Defaults to creating a local Web5UserAgent if not provided.
appData
AppDataStore
optional
An instance of an AppDataStore implementation. Defaults to a LevelDB-backed store with an insecure, static unlock passphrase if not provided. To allow the end user to enter a secure passphrase of their choosing, provide an initialized AppDataVault.
connectedDid
string
optional
An existing DID to connect to. If provided, the agent property must also be provided.
sync
string
optional
Enable or disable synchronization of DWN records between local and remote DWNs. Sync defaults to running every 2 minutes and can be set to any value accepted by ms (https://www.npmjs.com/package/ms). To disable sync set to 'off'
techPreview
TechPreviewOptions
optional
Show parameters


dwnEndpoints
string[]
optional
a list of DWN endpoints to define in the DID created and returned by this method. If this property is omitted during the Tech Preview, two nodes will be included by default (e.g. https://dwn.tbddev.org/dwn0, https://dwn.tbddev.org/dwn3)

Return Value

web5
Web5
A class instance of Web5 that enables access to a locally running DWN, DID interaction methods, and other capabilities related to the connected DID
did
DidApi
A class instance representing the decentralized identifier that was created or attained connection to

Upgrade your application to a PWA

Upgrade your app to a PWA and use Web5 activated polyfills to add Decentralized Resource Locators(DRLs) and manage DWN offline syncs. See DWA starter app

// Activate Web5 Service Worker Polyfills 
activatePolyfills({
onCacheCheck() { return { ttl: 30000, };
},
});

Examples

Below are examples of how to use Web5.connect() with or without additional option parameters.

Connect with no parameters
const { web5, did: userDid } = await Web5.connect();
Connect to DIF/Google Community Node

Connect to the community node instance hosted by Google and DIF:

const {did, web5} = await Web5.connect({
didCreateOptions: {
dwnEndpoints: ['https://dwn.gcda.xyz'], // User provides google's community DWN instance
},
registration: {
onSuccess: () => {
// Registration succeeded, set a local storage value to indicate the user is registered and registration does not need to occur again.
},
onFailure: (error) => {
// Registration failed, display an error message to the user, and pass in the registration object again to retry next time the user connects.
},
},
})
Connect with an existing Decentralized Web Node endpoint
const { web5, did } = await Web5.connect({
techPreview: {
dwnEndpoints: ['https://dwn.your-domain.org/'],
},
});
Connect with an existing agent and existing DID

If connectedDid is provided, the agent property must also be provided.

const { web5, did } = await Web5.connect({
agent: identityAgent,
connectedDid: existingDid,
});
Configure sync interval when connecting to Web5

Sync defaults to running every 2 minutes and can be set to any value accepted by ms. To disable sync set to 'off'.

const { web5, did } = await Web5.connect({
sync: '5s',
});

Connect with us on Discord

Submit feedback: Open a GitHub issue

Edit this page: GitHub Repo

Contribute: Contributing Guide