Web5 in 5️⃣ minutes

We’re going to build a decentralized application on the Web5 platform - in under 5 minutes. You'll learn how to CRUD (create, read, update, and delete) data from your users' personal data stores.

Let’s go! 🚀

---

Installation

info

Prerequisites

• Node Package Manager, npm, installed and on your system's $PATH.

• Node version 18 and above

1. Create a directory

This will be the home of your new Web5 app. In your CLI:

mkdir web5-app
cd web5-app

2. Install Web5

Use NPM to initialize a package.json file:

npm init -y

Use NPM to install Web5:

npm install @web5/api

These steps will create a package.json in the root of your project. Open package.json and add module as a type:

{
  "dependencies": {
    "@web5/api": "0.9.2"
  },
  "type": "module"
}

3. Import Web5

Let's create an index.js file to write our application:

touch index.js

For Windows using PowerShell:

New-Item index.js -ItemType File

note

After npm resolves the dependency, you may see a few warnings. You can ignore these for now.

Open index.js in your editor and add this line at the top of the file to import Web5:

import { Web5 } from '@web5/api';

Additional import for 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';

// @ts-ignore
if (!globalThis.crypto) globalThis.crypto = webcrypto;

Additional imports for 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';
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));

Now we have the Web5 SDK installed and are ready to start building!

---

1. Instantiate Web5 and Create DID

In Web5 apps, a user’s unique identifier - like an email address - is called a Decentralized Identifier (DID). We are building a decentralized app, so your users are using identifiers that aren't tied to a centralized authority.

The Web5 class is an isolated API object for doing all things Web5. The connect() function creates an instance of Web5 and also creates a decentralized identifier or obtains connection to an existing one.

In index.js below the import statement, create a new instance of Web5:

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

This Web5 instance is what you'll use to access the other objects of Web5 such as did and dwn. Within the connect function we’re using ion as the DID method. Learn more DID methods.

info

Web5 is split into three main top-level objects:

• web5.did
• web5.dwn
• web5.vc

Test your code

Wanna see the DID you just created?

In index.js, add the following line and save your file:

console.log(aliceDid);

Then from the terminal, run:

node index.js

You'll see the newly created DID.

Try it!

DID Creation Progress

Your DID will appear here

2. Write DWN Records

Now you’re able to write records in the user's Decentralized Web Node(DWN).

A DWN is a personal data store - a platform for messages, pictures, videos, medical records, and just about any content a user may want to store.

Read more about DWN

Your app should not store users' data in your centralized database. Instead, their data should be stored in their DWN. This is how the user retains ownership over their content. Through permissions, users can decide which apps can read, write, and delete content from their DWN.

The DWN exists in local storage under the name dwn-info. The DWN persists across browser sessions and can be synched across a user's devices.

A user can host their DWN in mulitple locations. The Web5 SDK is both browser and Node.js compliant, meaning you can use the same APIs on both client side and serverside.

Add the following to index.js:

const { record } = await web5.dwn.records.create({
    data: 'Hello, Web5!',
    message: {
      dataFormat: 'text/plain',
    },
  });

Test your code

Let's see what was just written to the DWN.

In index.js, add the following line and save your file:

console.log('writeResult', record);

Then from the terminal, run:

node index.js

You'll see the record that was written to the user's DWN. It will resemble:

  writeResult _Record {}

Enter "Hello Web5" in the input field and click "Run" to write a record to the sandbox DWN.

Try it!

Your message

Write progress

Your message will appear here

3. Read DWN Records

If the user has given your app read permissions to their DWN, you can read their data by accessing it through the record property. If you don't already have access to the record, you can query to obtain it.

To return the text data stored in the record, add the following to index.js:

const readResult = await record.data.text();

Test your code

To see the record that was read from the DWN, add the following to index.js:

console.log('readResult', readResult)

Then from the terminal, run:

node index.js

The output will resemble:

Hello Web5

Try it!

Read progress

Your read result will appear here

4. Update DWN Records

To update the record, call update on the record object itself.

Add the following to index.js:

const updateResult = await record.update({
    data: 'Hello, Web5! I am updated.',
  });

Test your code

To see the record that was updated in the DWN, add the following to index.js:

console.log('updateResult', await record.data.text())

Then from the terminal, run:

node index.js

The output will resemble:

updateResult Hello, I'm updated!

Enter "Hello, I'm updated" in the input field and click "Run!" to update the record in the sandbox DWN:

Try it!

Your updated message

Update progress

Your updated message will appear here

5. Delete DWN Records

Given permission from the user, your app can delete records from their DWN. Similar to reading, we’ll use the record object to remove the record.

Add the following to index.js:

const deleteResult = await web5.dwn.records.delete({
    message: {
      recordId: record.id,
    },
  });

Test your code

To see the status of the delete transaction, add the following to index.js:

console.log('deleteResult', deleteResult)

Then from the terminal, run:

node index.js

The output will resemble:

{ status: { code: 202, detail: 'Accepted' } }

Try it!

Delete progress

The result of your delete operation will appear here

---

Summary

Congrats! You've just created a local DWN to serve as your user's personal data store. Given a user's DID and appropriate permissions, your app can read, write, or delete data from the user's DWN, while leaving them in full control of their content.

info

• Download the completed index.js file
• View source code for the interactive sandbox of this Quickstart
• Run interactive sandbox directly in your browser

Next Steps

• Learn more about DIDs
• Learn more about DWNs
• Build a decentralized ToDo app