Add a file

Working with files in ProtoSchool

Here in our ProtoSchool tutorials, we create a new IPFS node for you in the browser each time you hit the "Submit" button in a lesson. Whenever you see ipfs.someMethod() in our lessons, ipfs is a variable that refers to your IPFS instance, also known as a node. This IPFS node is not carried over from one lesson to another, which is why you'll see that we often pre-populate some code in a challenge to make the state of your new IPFS node the same as the final state of your node in the previous challenge.

We create these IPFS nodes behind the scenes so that you can focus on the content of each lesson. Outside of ProtoSchool, though, you'd want a more consistent experience and a node (or multiple nodes) that you could access repeatedly. To achieve this, you could either initialize js-ipfs in the browser on your own, or host your own node locally by installing IPFS and running a daemon in your terminal. When you're ready to experiment with that, you can visit the IPFS docs site to learn how to install IPFS and initialize your node.

As mentioned previously, the methods discussed in this tutorial are part of the IPFS Files API. Check the documentation for more specific details, such as options for each API method.

Add a single file with add

In order to make a file available on the IPFS network, you first need to add it to a specific IPFS node. It's important to remember that because IPFS is a peer-to-peer, decentralized system, adding a file doesn't mean uploading it to a remote server somewhere. Assuming you're using a node on your own machine, the process is more like picking a file from your computer and adding a label to it that says, "I'm shared on IPFS! My name is __. Come find me!" That label includes a Content Identifier (CID) derived from the file's contents that serves as a type of address that other peers can use to find a specific file, regardless of whose computer it's hosted on.

When you add a file to IPFS, you're putting it in your own node and making it accessible to peers on the network while your node is running. It will only remain available as long as someone who has it (like you!) is connected to the network. If no one else has found and shared your file yet, and you shut off your computer or stop your IPFS daemon from running, that content will no longer be available for anyone to discover. The more people who share your content, through a process called pinning, the more likely it is to be available at any one time.

Let's take a look at how to add a file to your IPFS node. We'll do this by executing the add method:

ipfs.add(data, [options])

So if we had the File object for an adorable photo of a kitten in our browser, accessible to us via a variable catPic, and we wanted to add it to our IPFS node, we could pass it into the add method as data like so:

const result = await ipfs.add(catPic)

The value of the variable result is an object in the following format:

{
    path: String,
    cid: CID,
    size: Number,
    mode: Number
}

Add multiple files with addAll

If you have more than one adorable animal photo to add to the node, use the addAll method instead:

ipfs.addAll([catPic, dogPic, giraffePic])

Because the addAll method returns an Async Iterable, you can only iterate over its values, one by one. If you need to return all the values, you can save each one into an array and then return the array.

To iterate over all the values of the Async Iterable, we can use a for await...of loop:

const result = []

for await (const resultPart of ipfs.addAll([catPic, dogPic, giraffePic])) {
    result.push(resultPart)
}

return result

To make things easier, we can use the it-all package that does this automatically:

// the all function comes from the it-all package
// and is made globally available (just like ipfs) in our code challenges

const result = await all(ipfs.addAll([catPic, dogPic, giraffePic]))

The value of the variable result is an array of objects (each identical in format to the output of add), one for each file added to IPFS, in the following format:

{
    path: String,
    cid: CID,
    size: Number,
    mode: Number
}

The value of the cid is a CID object (Content Identifier), a unique address generated from the contents of each file. (For a more in-depth look at how CIDs are generated and why they're important, check out our Content Addressing on the Decentralized Web tutorial.) In a future lesson, we will learn how to use this value to retrieve the contents of a file.

The add and addAll methods accept other data formats besides the File object and offer many advanced options for setting your chunk size and hashing algorithm, pinning files as they're added, and more. We're highlighting the basics in this tutorial, but you can check out the full documentation for the add or addAll methods to learn more.