Better storage.
Better transfers.
Better internet.

When you need file storage for your project, website, or application, web3.storage is here for you. All it takes to get started storing on the decentralized web is a free API token — no need to wrestle with complicated details.

In the past, storing data on the decentralized web wasn't always easy — but that's where web3.storage comes in. Most data on the internet today is hosted by massive storage providers like Amazon, Google, and Microsoft. This makes it simpler for developers to store application data, but big corporate platforms like these create silos by locking developers and users alike into walled gardens of services. What's more, as the market continues to consolidate, a small oligopoly of providers are essentially becoming the storage backbone of the internet.

One solution to this problem is using decentralized storage instead of big, corporate platforms to store data for apps and services. However, decentralized storage can be difficult to manage and add extra time and effort to an already crowded developer workflow — for example, most decentralized storage services need you to compile your data into a specific format, find a storage provider to host your data, buy some cryptocurrency to pay the storage provider, and then send your data across the internet. This is where web3.storage comes in.

With web3.storage, you get all the benefits of decentralized storage technologies with the frictionless experience you expect in a modern dev workflow. All you need to use web3.storage is an API token and your data. Under the hood, web3.storage is backed by the provable storage of Filecoin and makes data accessible to your users over the public IPFS network — but when it comes down to building your next application, service, or website, all you need to know is that web3.storage makes building on decentralized technologies simple.

Quickstart

Ready to get started using web3.storage right now? Get up and running in minutes by following this quickstart guide. In this guide, we'll walk through the following steps:

1. Creating a web3.storage account.
2. Getting a free API token.
3. Creating and running a simple script to upload a file.
4. Getting your uploaded file using your browser or curl.

This guide uses Node.js since it's the fastest way to get started using the web3.storage JavaScript client programmatically, but don't worry if Node isn't your favorite runtime environment — or if you'd rather not do any coding at all. You can also use web3.storage in the following ways:

• Work with the API methods in the JavaScript client library using the JS runtime of your choice.
• Upload and retrieve files directly from your Account page on the web3.storage website.

node --version && npm --version
> v16.4.2
> 7.18.1

Create an account

You need a web3.storage account to get your API token and manage your stored data. You can sign up for free using your email address or GitHub.

Now that you're signed up and logged in, it's time to get your API token. ↓

Get an API token

It only takes a few moments to get a free API token from web3.storage. This token enables you to interact with the web3.storage service without using the main website, enabling you to incorporate files stored using web3.storage directly into your applications and services.

1. Hover over Account and click Create an API Token in the dropdown menu to go to your web3.storage API Tokens page.
2. Enter a descriptive name for your API token and click Create.
3. Make a note of the Token field somewhere secure where you know you won't lose it. You can click Copy to copy your new API token to your clipboard.

Now that you have your new API token, it's time to use a simple script to upload a file to web3.storage. ↓

Create the upload script

You can use the web3.storage site to upload files, but it's also quick and easy to create and run a simple upload script — making it especially convenient to add large numbers of files. This script contains logic to upload a file to web3.storage and get a content identifier (CID) back in return.

1. Create a folder for this quickstart project, and move into that folder:

   mkdir web3-storage-quickstart
   cd web3-storage-quickstart
   

2. Create a file called put-files.js and paste in the following code:

   import process from 'process'
   import minimist from 'minimist'
   import { Web3Storage, getFilesFromPath } from 'web3.storage'
   
   async function main () {
     const args = minimist(process.argv.slice(2))
     const token = args.token
   
     if (!token) {
       return console.error('A token is needed. You can create one on https://web3.storage')
     }
   
     if (args._.length < 1) {
       return console.error('Please supply the path to a file or directory')
     }
   
     const storage = new Web3Storage({ token })
     const files = []
   
     for (const path of args._) {
       const pathFiles = await getFilesFromPath(path)
       files.push(...pathFiles)
     }
   
     console.log(`Uploading ${files.length} files`)
     const cid = await storage.put(files)
     console.log('Content added with CID:', cid)
   }
   
   main()
   

3. Create another file called package.json and paste in the following code:

   {
       "name": "web3-storage-quickstart",
       "version": "0.0.0",
       "private": true,
       "description": "Get started using web3.storage in Node.js",
       "type": "module",
       "scripts": {
           "test": "echo \"Error: no test specified\" && exit 1"
       },
       "dependencies": {
           "minimist": "^1.2.5",
           "web3.storage": "^3.1.0"
       },
       "author": "YOUR NAME",
       "license": "(Apache-2.0 AND MIT)"
   }
   

4. Save both files, and then run npm install from your project folder:

   npm install
   

   This step may take a few moments. Once it's done, the command should output something like this:

   added 224 packages, and audited 225 packages in 14s
   
   40 packages are looking for funding
    run `npm fund` for details
   
   found 0 vulnerabilities
   

Your script is good to go! Next, we'll run the script to upload a file. ↓

Run the script

Now that you've got your script ready to go, you just need to run it in your terminal window using node.

1. Run the script by calling node put-files.js, using --token to supply your API token and specifying the path and name of the file you want to upload. If you'd like to upload more than one file at a time, simply specify their paths/names one after the other in a single command. Here's how that looks in template form:

   node put-files.js --token=<YOUR_TOKEN> ~/filename1 ~/filename2 ~/filenameN
   

   Once you've filled in your details, your command should look something like this:

   node put-files.js --token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJkaWQ6ZXRocjoweGZFYTRhODlFNUVhRjY5YWI4QUZlZUU3MUE5OTgwQjFGQ2REZGQzNzIiLCJpc3MiOiJ3ZWIzLXN0b3JhZ2UiLCJpYXQiOjE2MjY5Njk3OTY1NTQsIm5hbWUiOiJib25maXJlIn0.0S9Ua2FWEAZSwaemy92N7bW8ancRUtu4XtLS3Gy1ouA ~/hello.txt
   

1. The command will output a CID:

   Content added with CID: bafybeig7sgl52pc6ihypxhk2yy7gcllu4flxgfwygp7klb5xdjdrm7onse
   

2. Make a note of the CID, which looks like bafyb.... You'll need it in order to get your file.

Next up, we'll go over two methods for you to retrieve your data from web3.storage ↓

Get your file

You've already done the most difficult work in this guide — getting your files from web3.storage is simple.

1. Go to https://dweb.link/ipfs/YOUR_CID, replacing YOUR_CID with the CID you noted in the last step.
2. You should see a link to your file. If you uploaded multiple files at once, you'll see a list of all the files you uploaded.
3. Click on a file's link to view it in your browser!

Finding your files again

If you ever need to find your files again, and you've forgotten the CID, head over to the Files table in web3.storage:

Next steps

Congratulations! You've just covered the basics of web3.storage. To learn more, take a look at these useful resources:

• Checkout some example projects in the web3.storage GitHub repo
• For a deep dive into storing files, visit the Store how-to guide.
• To learn more about the details of getting files, have a look at the Retrieve how-to guide.
• Visit the reference API section for more details on what else you can do with the web3.storage service and how to integrate it into your own projects.