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()
.
Install​
- NPM
- CDN
npm install @web5/api
<script src="https://unpkg.com/@web5/api@0.11.0/dist/browser.js"></script>
or
<script src="https://cdn.jsdelivr.net/npm/@web5/api@0.11.0/dist/browser.mjs"></script>
Import​
- NPM
- CDN
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));
import { Web5 } from 'https://unpkg.com/@web5/api@0.11.0/dist/browser.js';
or
import { Web5 } from 'https://cdn.jsdelivr.net/npm/@web5/api@0.11.0/dist/browser.mjs'
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)
The outputs of this method invocation will be used throughout the other API methods.
Parameters​
options
Web5ConnectOptions
optional
Show parameters
agent
Web5Agent
optional
appData
AppDataStore
optional
connectedDid
string
optional
sync
string
optional
techPreview
TechPreviewOptions
optional
Show parameters
dwnEndpoints
string[]
optional
Return Value​
web5
Web5
did
DidApi
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 Community Node​
Connect to the free DIF community node instance hosted by Google Cloud:
const {did, web5} = await Web5.connect({
didCreateOptions: {
// Use community DWN instance hosted on Google Cloud
dwnEndpoints: ['https://dwn.gcda.xyz']
},
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',
});
Was this page helpful?
Connect with us on Discord
Submit feedback: Open a GitHub issue
Edit this page: GitHub Repo
Contribute: Contributing Guide