Skip to main content

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

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 install Web5:

npm install @tbd54566975/web5@0.7.2
note

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

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

{
  "dependencies": {
    "@tbd54566975/web5": "0.7.2"
  },
  "type": "module"
}

3. Import Web5​

Let's create a src directory and index.js file to write our application:

mkdir src
cd src
touch index.js

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

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

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

1. Instantiate Web5​

The Web5 class is an isolated API object for doing all things Web5 and the connect() function creates an instance of Web5.

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.

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 about ION and other 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 your CLI, run:

node src/index.js

You'll see the newly created DID.

Try it!​

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('write result', record);

Then from the terminal, run:

node src/index.js

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

  write result _Record {}

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

Try it!​

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.

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)

The output will resemble:

Hello Web5

Try it!​

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, I'm 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())

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 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 record.delete();
Test your code

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

console.log('deleteResult', deleteResult)

The output will resemble:

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

Try it!​

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

Next Steps​

Was this page helpful?

Connect with us on Discord

Submit feedback: Open a GitHub issue

Edit this page: GitHub Repo

Contribute: Contributing Guide