⁂
web3.storage

The simple file storage service for IPFS & Filecoin.

Usage

Store your files with web3.storage and retrieve them via their unique Content ID. Our tools make it simple to hash your content locally, so you can verify the service only ever stores the exact bytes you asked us to. Pick the method of using with web3.storage that works for you!

Website

Create an account via https://web3.storage and upload right from the website using our uploader. Under the hood it uses the web3.storage client that we publish to npm to chunk and hash your files to calculate the root IPFS CID in your browser before sending them to https://api.web3.storage.

Once uploaded you can fetch your data from any IPFS gateway via https://dweb.link/ipfs/<root cid>

Create an api token for your account and you can use any of the following alternatives to upload your data.

JS Client

Use npm to install the web3.storage module into your JS project, create an instance of the client with your api token, and use the .put method to upload your files in node.js or the browser.

node.js

const { Web3Storage, getFilesFromPath } = require('web3.storage')
const storage = new Web3Storage({ token: process.env.WEB3_TOKEN })
const files = await getFilesFromPath(process.env.PATH_TO_ADD)
const cid = await storage.put(files)
console.log(`IPFS CID: ${cid}`)
console.log(`Gateway URL: https://dweb.link/ipfs/${cid}`)

See https://web3.storage/docs/#quickstart for a guide to using the js client for the first time.

CLI

Our command line tool w3 is a wrapper around the JS Client to make adding files from your terminal as simple as w3 put ~/gifs.

Install @web3-storage/w3 globally and save your api token then add your files to web3! It calculates the root CID for your files locally before sending them to web3.storage.

shell

$ w3 token
? Paste your API token for api.web3.storage › <your api token here>
⁂ API token saved

$ w3 put ~/Pictures/ayy-lamo.jpg
⁂ Stored 1 file
⁂ https://dweb.link/ipfs/bafybeid6gpbsqkpfrsx6b6ywrt24je4xqe4eo4y2wldisl6sk7byny5uky

Use it anywhere you can get a shell. Get creative! For example, we use this for perfomance testing the upload speed in CI!

Run w3 --help or have a look at https://github.com/web3-storage/web3.storage/tree/main/packages/w3#readme to find out everything it can do.

GitHub Action

The Action add_to_web3 wraps the w3 CLI to let you add files to web3.storage from your GitHub Workflows.

github-workflow.yaml

- run: npm run build # e.g output your static site to `./dist`

- uses: web3-storage/add-to-web3@v2
  id: web3
  with:
    web3_token: ${{ secrets.WEB3_STORAGE_TOKEN }}
    path_to_add: 'dist'

- run: echo ${{ steps.web3.outputs.cid }}
# "bafkreicysg23kiwv34eg2d7qweipxwosdo2py4ldv42nbauguluen5v6am"
- run: echo ${{ steps.web3.outputs.url }}
# "https://dweb.link/ipfs/bafkreicysg23kiwv34eg2d7qweipxwosdo2py4ldv42nbauguluen5v6am"

Set your api token and the path_to_add and watch it fly! We use add_to_web3 to add the web3.storage website to web3.storage from CI ∞!

cURL

Want to try it out? You can POST a file smaller than 100MB straight to https://api.web3.storage/upload with cURL.

curl -X POST --data-binary @file.txt -H 'Authorization: Bearer YOUR_API_KEY' https://api.web3.storage/upload  -s | jq
{
  "cid":"bafkreid65ervf7fmfnbhyr2uqiqipufowox4tgkrw4n5cxgeyls4mha3ma"
}

See https://web3.storage/docs/ for our complete documentation 📖🔍

Building web3.storage

Want to help us improve web3.storage? Great! This project uses node v16 and npm v7. It's a monorepo that use npm workspaces to handle resolving dependencies between the local packages/* folders.

You need an account on https://magic.link, and Docker running locally.

Copy the <.env.tpl> file to .env and set the values for the MAGIC_SECRET_KEY & NEXT_PUBLIC_MAGIC, from your magic.link account dashboard.

Then install the deps with npm and then run all the things with npm start

# install deps
npm install

# start the api and website
npm start

To be able to run the APIs you need to make sure the underlying DB is populated with the required tables. Please follow the instructions in the Populate Database section in the db package README.

To add a new workspace to the repo:

npm init -w ./packages/website

To run an npm script in one or more workspaces

npm run test --workspace=a --workspace=b

Testing

Each workspace has its own suite of testing tools, which you can learn more about in the relevant packages/* directory. Check out highlights in each readme using the links below, then dig into the relevant package.json file for a full list of available scripts.

• Website (packages/website)
• JavaScript API client (packages/client)
• HTTP API client (packages/api)
• CLI (packages/w3)
• Cron jobs (packages/cron)
• Database (packages/db)

Our docs website is currently hosted in a separate repo, but you can test it too!

Learn more

To learn more about the Web3.Storage service, upload a file through our friendly UI, or find detailed documentation for the JS client library, please head over to https://web3.storage

⁂