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:
- Installing the client library
- Creating and provisioning your first space
- Uploading a file or directory
- Viewing your file with IPFS
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) for a streamlined approach.
Additional Notes
-
:warning: Important :warning: If you do not provide the
account
parameter when creating a space, you risk losing access to your space in case of device loss or credential issues. -
Account Parameter
Supplying anaccount
in the options automatically provisions a delegated recovery account. This enables you to store data securely and delegate access to the recovery account, allowing access to your space from other devices as long as you have your account credentials. -
Name Parameter
Thename
parameter is optional. If provided, it will be stored in your client’s local state and can serve as a user-friendly identifier for interfaces. -
Current Space
- If this is your Agent's first space, it will be automatically set as the "current space."
- For additional spaces, you can manually set a new space as the current one using:
await client.setCurrentSpace(space.did());
-
Authorized Gateways
When creating a space, you can specify which Gateways are authorized to serve the content you upload. By default, if no other flags are set the client will automatically grant access to the Storacha Gateway (opens in a new tab) to serve the content you upload to your space.
However, you can authorize other Storacha compliant gateways to serve content instead.
To achieve this, you must first establish a connection with the desired Gateway. This connection enables the client to publish the necessary delegations that grant the Gateway permission to serve your content.
To configure other Gateways to serve the content you upload to your new space, follow these steps:
import * as UcantoClient from '@ucanto/client' import { HTTP } from '@ucanto/transport' import * as CAR from '@ucanto/transport/car' // Connects to Storacha Freeway Gateway const storachaGateway = UcantoClient.connect({ id: id, codec: CAR.outbound, channel: HTTP.open({ url: new URL('https://w3s.link') }), });
Once connected to the Gateway, you can create a space and authorize serving content from that gateway:
const space = await client.createSpace("my-awesome-space", { account, authorizeGatewayServices: [storachaGateway], });
If you want to ensure that no Gateway is authorized to serve the content of your space, you can use the
skipGatewayAuthorization
flag:const space = await client.createSpace("my-awesome-space", { account, skipGatewayAuthorization: true, });
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 Blob
s, 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.