# How to store data using Web3.Storage

In this how-to guide, you'll learn how to store data programmatically for your development projects using the Web3.Storage JavaScript client. This includes making your data available on the decentralized IPFS (opens new window) network with persistent long-term storage provided by Filecoin (opens new window) — all for free.

If you just want to quickly store a few files using Web3.Storage rather than include upload functionality in an app or service you're building, you may want to skip this guide for now and simply use the Files page (opens new window) on the Web3.Storage site.

For developers, Web3.Storage provides a simple interface for storing data using syntax inspired by familiar web APIs such as fetch (opens new window) and File (opens new window). This guide focuses on the JavaScript client library, which is the simplest way to use Web3.Storage programmatically.

Uploading data to Web3.Storage using the JavaScript client library requires a free API token, which in turn requires a Web3.Storage account. If you already have an account and a token, read on. If not, have a look at the quickstart guide to get up and running in just a few minutes.

CAUTION

All data uploaded to Web3.Storage is available to anyone who requests it using the correct CID. Do not store any private or sensitive information in an unencrypted form using Web3.Storage.

# Installing the client

In your JavaScript project, add the web3.storage package to your dependencies:

npm install web3.storage

# Creating a client instance

First we need to create a Web3.Storage client object, passing in an API token to its constructor:

import { Web3Storage } from 'web3.storage'

function getAccessToken() {
  // If you're just testing, you can paste in a token
  // and uncomment the following line:
  // return 'paste-your-token-here'

  // In a real app, it's better to read an access token from an 
  // environement variable or other configuration that's kept outside of 
  // your code base. For this to work, you need to set the
  // WEB3STORAGE_TOKEN environment variable before you run your code.
  return process.env.WEB3STORAGE_TOKEN
}

function makeStorageClient() {
  return new Web3Storage({ token: getAccessToken() })
}

# Preparing files for upload

The Web3.Storage client's put method accepts an array of File objects (opens new window).

There are a few different ways of creating File objects available, depending on your platform.

    TIP

    When uploading multiple files, try to give each file a unique name. All the files in a put request will be bundled into one content archive, and linking to the files inside is much easier if each file has a unique, human-readable name.

    # Uploading to Web3.Storage

    Once you have an array of Files, uploading is simple:

    async function storeFiles(files) {
      const client = makeStorageClient()
      const cid = await client.put(files)
      console.log('stored files with cid:', cid)
      return cid
    }

    IMPORTANT

    Deleting files from the Web3.Storage site's Files page (opens new window) will remove them from the file listing for your account, but that doesn't prevent nodes on the decentralized storage network from retaining copies of the data indefinitely. Do not use Web3.Storage for data that may need to be permanently deleted in the future.

    # Showing progress to the user

    The put method has some options that can be passed in to get progress on the upload as it happens in the background. There are two callback parameters you can use: onRootCidReady, and onStoredChunk.

    The onRootCidReady callback is invoked as soon as the client has calculated the content identifier (CID) that identifies the data being uploaded. Because this calculation happens locally on the client, the callback is invoked before the upload begins.

    As each chunk of data is uploaded, the onStoredChunk callback gets invoked with the size of the chunk in bytes passed in as a parameter.

    Here's a simple example of using the callbacks to print the progress of an upload to the console:

    async function storeWithProgress(files) {  
      // show the root cid as soon as it's ready
      const onRootCidReady = cid => {
        console.log('uploading files with cid:', cid)
      }
    
      // when each chunk is stored, update the percentage complete and display
      const totalSize = files.map(f => f.size).reduce((a, b) => a + b, 0)
      let uploaded = 0
    
      const onStoredChunk = size => {
        uploaded += size
        const pct = totalSize / uploaded
        console.log(`Uploading... ${pct.toFixed(2)}% complete`)
      }
    
      // makeStorageClient returns an authorized Web3.Storage client instance
      const client = makeStorageClient()
    
      // client.put will invoke our callbacks during the upload
      // and return the root cid when the upload completes
      return client.put(files, { onRootCidReady, onStoredChunk })
    }

    # Storing IPFS Content Archives

    So far we've focused on using the put method, which accepts regular files and packs them into an IPFS Content Archive (CAR) file before uploading to Web3.Storage. If you're already using IPFS in your application, or if you want more control over the IPLD (opens new window) graph used to structure your data, you can construct your own CAR files and upload them directly.

    See Working with CAR files for more information about Content Archives, including how to create and manipulate them with code or command-line tools.

    Once you have a Content Archive, you can use the putCar client method to upload it to Web3.Storage.

    The putCar method accepts a CarReader, which is a type defined by the @ipld/car (opens new window) package.

    You can create a CarReader from a Uint8Array using the fromBytes static method:

    import { CarReader } from '@ipld/car'
    
    // assume loadCarData returns the contents of a CAR file as a Uint8Array
    const carBytes = await loadCarData()
    const reader = await CarReader.fromBytes(carBytes)
    
    const client = makeStorageClient()
    const cid = await client.putCar(reader)
    console.log('Uploaded CAR file to Web3.Storage! CID:', cid)
    

    See the putCar reference documentation for more information about putCar, including optional parameters.

    The Working with CAR files guide has more information about the @ipld/car package, including how to implement the loadCarData function and other ways to construct a CarReader.

    # Next steps

    The put method returns an IPFS content identifier (CID) (opens new window) that can be used to fetch your files over IPFS. Once uploaded, your data is immediately available for retrieval via IPFS and will be stored with Filecoin storage providers within 48 hours. To learn how to fetch your data using the Web3.Storage client, or directly from IPFS using a gateway or the IPFS command line, see the how-to guide on retrieval.

    You can also get more information about the status of your data. See the query how-to guide to learn how to get more details about your data, including the status of any Filecoin storage deals.