Node.js + IPFS Guide
Building IPFS Applications with Node.Js
How to leverage the distributed, permanent web in your applications
Introduction
IPFS is a game-changer. In contrast to the web of today, IPFS could actually achieve a distributed, permanent web. And on top of that, it could be interplanetary, which is not possible at all with our current client-server architecture. IPFS leverages a peer-to-peer architecture, where every node is a client as well as a server. If you request something from the network, you will be serving the thing you requested to other nodes.
You can think of it as one giant BitTorrent swarm.
Besides the peer-to-peer architecture, the way we retrieve content on IPFS is revolutionary as well. Instead of identifying content by its location, i.e. its IP address, we identify it by a unique identifier created by hashing the content itself. This is called content-addressing. This is very useful for a couple of reasons:
- Data persistence. If a number of peers have the content you want, you will get it from the closest one. Even if the original uploader of the content goes offline, since it’s content-addressed, there’s a good chance you’ll still get it. Compared to the web of today, where if the server goes down, the content goes down with it, this is a great improvement.
- Built-in security. Since the content-identifier (CID), is created by hashing the content itself, you can always be sure that you get exactly what you asked for. There’s no way of cheating the system because if you modify the content, its identifier is going to change with it.
Looking for a more in-depth explanation of IPFS? Check out this post:
If you want to incorporate all of this into your Node.js applications, continue to the next section.
Getting Started
Github repository here
Before we get started, I want to get a couple of things out of the way. There are 2 implementations of IPFS clients, one in JavaScript and the other in Go. JavaScript might seem like the best choice here, but since it’s in a much earlier state of development than the Go client, this is not the best choice. We’ll use the Go client and connect to it with Node via its API.
Prerequisites:
- Node.js (ideally one of the later versions) & npm
- A go-ipfs client (installation instructions here)
- Postman or curl, for making requests to our REST API
First of all, our node has to be running in online mode, so open up a terminal and run ipfs daemon . You should see something like this:
On line 19, you can see the API server is listening on port 5001. This is what we need to connect to.
Secondly, create a new project directory and run npm install ipfs-http-client . This is the package we need to connect to our running IPFS node.
Next, let’s create the js file where we’ll connect to the node:
On line 3 we actually connect to the daemon API server. We can now start executing commands on the ipfs object to interact with the network.
As an example, let’s write a function that adds some text to IPFS:
On line 1, we create an object to add to IPFS. The path is what we want the file to be called on IPFS (we can include a directory), and the content is a Buffer of the file (in this case, just plain text) we want to add. Next, we add the file to ipfs with ipfs.add() , which returns an array with all the added files. Since we only added one, the result of console.log() will be:
If you’re following along, you’ll notice that the hash field will be exactly the same every time, because you added the same content I did. Also, notice that the path name doesn’t affect the content identifier. If you now want to retrieve your content, you have 2 possibilities:
- Use your local gateway server like this: http://localhost:8080/ipfs/QmWfVY9y3xjsixTgbd9AorQxH7VtMpzfx2HaWtsoUYecaX
The gateway server was spun up by your IPFS daemon. - Use a public gateway like this: https://gateway.ipfs.io/ipfs/QmWfVY9y3xjsixTgbd9AorQxH7VtMpzfx2HaWtsoUYecaX
All this is already pretty cool, but let’s see how we can use this in an app. To demonstrate some more functionality, let’s create a small REST API with Express.
Building an Application
Don’t forget to run npm install express .
Let’s start with some boilerplate code:
Go ahead and run this and test it out with curl http://localhost:3000 . You should see Welcome to my IPFS app .
Let’s now add a POST route:
We can now test out this route with Postman. Create a new POST request to http://localhost:3000/upload . You can choose what you put in the body, but it has to be JSON:
If everything went well, you should’ve gotten the response I got and some terminal output from our Express app: { path: 'postman request', content: 'postman says whassup' } . Since we use JSON middleware, req.body got parsed as a JS object, which is already the format we need to add something to IPFS. Let’s extend the functionality by modifying and calling the addFile function, and we’ll return a link to the added file over a public gateway:
In addFile() on line 8, we take in the req.body data as a parameter and use that to add to IPFS. We then return the fileHash , so that we can include it in the link we send back as a response. If we now make another POST request on Postman:
We get back a link to view our file on a public gateway! Note that this link might actually take a while to load since public gateways can be very slow.
That was it. Thanks for reading.
Resources:
- The IPFS Whitepaper, on IPFS
- Getting started with go-ipfs
- js-ipfs-http-client documentation
- Building an IPFS app with Node.js YouTube video
- Github repo for this project
