`w3up-client`

You can easily integrate web3.storage 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 client reference docs for more creation options.

Create and register a space

When you upload things to web3.storage, 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. To use a space for uploads, it needs to be registered with the storage service by providing an email address.

To create a space using w3up-client, use the createSpace client method:

const space = await client.createSpace('my-awesome-space')

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.

After creating a Space, you'll need to register it with the w3up service before you can upload data.

First, set the space as your "current" space using the setCurrentSpace method, passing in the DID of the space object you created above:

await client.setCurrentSpace(space.did())

Next, call the registerSpace method, passing in an email address to register as the primary contact for the space:

try {
  await client.registerSpace('zaphod@beeblebrox.galaxy')
} catch (err) {
  console.error('registration failed: ', err)
}

Calling registerSpace will cause an email to be sent to the given address. Once a user clicks the confirmation link in the email, the registerSpace method will resolve. Make sure to check for errors, as registerSpace will fail if the email is not confirmed within the expiration timeout.

Now that you've registered a space, you're ready to upload files!

Upload files

Now that you've created and registered a space, you're ready to upload files to web3.storage!

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 filesFromPath 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.storeDirectory(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, encoded as a string.

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 UCAN