`w3up-client`

You can easily integrate Storacha into your JavaScript apps using w3up-client, our JavaScript client for the w3up platform.

In this guide, we'll walk through the following steps:

Install

You'll need Node (opens in a new tab) version 18 or higher, with NPM version 7 or higher to complete this guide. You can check your local versions like this:

node --version && npm --version

Add the library to your project's dependencies:

npm install @web3-storage/w3up-client

To use the client, import and call the create function:

import { create } from "@web3-storage/w3up-client";
 
const client = await create();

See the w3up-client README (opens in a new tab) for more creation options.

Create and provision a space

When you upload things to Storacha, each upload is associated with a "space", which is a unique identifier that acts as a namespace for your content. Spaces are identified by DID using keys created locally on your devices.

The first thing to do is login your Agent with your email address. Calling login will cause an email to be sent to the given address. Once a user clicks the confirmation link in the email, the login method will resolve. Make sure to check for errors, as login will fail if the email is not confirmed within the expiration timeout. Authorization needs to happen only once per agent.

const account = await client.login("[email protected]");

If your account doesn't have a payment plan yet, you'll be prompted to select one after verifying your email. A payment plan is required to provision a space. You can use the following loop to wait until a payment plan is selected:

// Wait for a payment plan with a 1-second polling interval and 15-minute timeout
await account.plan.wait();

Spaces can be created using the createSpace client method:

const space = await client.createSpace("my-awesome-space", { account });

Alternatively, you can use the w3cli command w3 space create (opens in a new tab).

The name parameter is optional. If provided, it will be stored in your client's local state store and can be used to provide a friendly name for user interfaces.

If an account is provided in the options, a delegated recovery account is automatically created and provisioned, allowing you to store data and delegate access to the recovery account. This means you can access your space from other devices, as long as you have access to your account.

If this is your Agent's first space, it will automatically be set as the "current space." If you already have spaces and want to set the new one as current, you can do so manually:

await client.setCurrentSpace(space.did());

ℹ️ Note: If you do not create the space passing the account parameter you run the risk of losing access to your space!

Upload files

Now that you've created and provisioned a space, you're ready to upload files to Storacha!

Call uploadFile to upload a single file, or uploadDirectory to upload multiple files.

uploadFile expects a "Blob like" input, which can be a Blob (opens in a new tab) or File (opens in a new tab) when running in a browser. On Node.js, see the files-from-path library (opens in a new tab), which can load compatible objects from the local filesystem.

uploadDirectory requires File-like objects instead of Blobs, as the file's name property is used to build the directory hierarchy.

You can control the directory layout and create nested directory structures by using / delimited paths in your filenames:

const files = [
  new File(["some-file-content"], "readme.md"),
  new File(["import foo"], "src/main.py"),
  new File([someBinaryData], "images/example.png"),
];
 
const directoryCid = await client.uploadDirectory(files);

In the example above, directoryCid resolves to an IPFS directory with the following layout:

.
├── images
│   └── example.png
├── readme.md
└── src
    └── main.py

View your file on an IPFS gateway

The uploadFile and uploadDirectory methods described in the previous step both return a CID, or Content Identifier - a unique hash of the data.

To create a link to view your file on an IPFS gateway, create a URL of the form https://${cid}.ipfs.${gatewayHost}, where ${cid} is the CID of the content you want to view, and ${gatewayHost} is the domain of the gateway. To use our own gateway at w3s.link, your URL would be https://${cid}.ipfs.w3s.link.

Opening the gateway URL in a browser will take you to your uploaded file, or a directory listing of files, depending on what you uploaded.

Of course, gateways aren't the only option for fetching data from IPFS! If you're running a kubo (opens in a new tab) node, you can use ipfs get <your-cid> (opens in a new tab) to fetch your content from the peer-to-peer IPFS Bitswap network.

Command line Go Client