IPFS in JavaScript

JavaScript libraries

There are three main JavaScript libraries for working with IPFS in JavaScript: ipfs, ipfs-http-client, and kubo-rpc-client. All three work in Node.js and modern web browsers. JS-IPFS in Node.js is long-running and supports transports like TCP and UDP along with WebSockets and WebRTC, while JS-IPFS in the browser is short-lived and limited to Web APIs available on a web page; it only supports WebSockets and WebRTC as transports. The browser is also resource constrained and does not support all of the interfaces found in the Node.js version.

• ipfs-http-client is the official JavaScript client for talking to a js-ipfs node.
• kubo-rpc-client is the official JavaScript client for talking to a Kubo node.

JS-IPFS

WARNING

js-ipfs being discontinued

Development of the js-ipfs project (opens new window) is being discontinued to focus on Helia (opens new window), a leaner, more modular, modern implementation of IPFS in JavaScript scheduled for release in 2023. To learn more about Helia and the current state of IPFS in JS, see the blog post (opens new window).

Because of this, js-ipfs tutorials may be out of date, and will eventually be archived.

JS-IPFS (opens new window) is a full implementation of IPFS, similar to Kubo (Go-IPFS) (opens new window). You can use it either as a command-line application or as a library to start an IPFS node directly in your program, as JS implementation is available as two Node.js packages, ipfs-core and ipfs.

• ipfs-core (opens new window) includes the core IPFS API and is intended to be used to run an IPFS node as part of your application without the need to start external processes or manage API ports and servers.

IPFS Core API

See the JS core API reference → (opens new window)

• ipfs (opens new window) is built on ipfs-core but also includes the CLI, an HTTP RPC API server and, other tools to run ipfs as a background process, so it is a larger install with more dependencies.

ipfs-core vs. ipfs

If you are writing an application that needs to access the IPFS network, use ipfs-core. If you wish to use js-ipfs in a terminal window or run it as a server for use by multiple otherwise unrelated processes, use ipfs.

HTTP clients

The kubo-rpc-client API (opens new window) is a client library that controls an active Kubo node running through its RPC API.

• Use this library to talk to a Kubo node from your JavaScript application
• You can also interact with the RPC API directly using fetch() in a browser or a module like request in Node.js, but using this library can be much more convenient.

Changes to IPFS HTTP RPC API

There is ongoing work that will result in HTTP RPC API divergence in the future. See https://github.com/ipfs/kubo/issues/9125 for more information.

The ipfs-http-client API (opens new window) is a library that controls an active JS-IPFS node running through its own version of the RPC API over HTTP (opens new window).

• JS-IPFS will internally use this library if it detects another node is running on your machine. You can also interact with the HTTP version of JS-IPFS RPC API directly using fetch() in a browser or a module like request in Node.js, but using this library can be much more convenient.
• When using JS-IPFS as a backend, use the ipfs-client (opens new window) instead to leverage gRPC connections over WebSockets to allow some commands to achieve the bidirectional streaming necessary to have full duplex streams running in the browser.

All the libraries have the same interface (opens new window) for using all the major IPFS commands. This client library implements the interface-ipfs-core enabling applications to change between an embedded js-ipfs node and any remote IPFS node without changing the code. In addition, this client library implements a set of utility functions.

Interacting with IPFS

We recommend the second method (interacting with a separate IPFS node via RPC API) whenever reasonable. Keeping the IPFS node in a separate process (even if it’s one of your program spawns) isolates you from any stability problems with the node. If a user already has IPFS installed, this also means that you can take advantage of a single, standard installation on their machine. It’s also less code to load in a browser. If you need to spawn a separate IPFS process, you might want to take a look at js-ipfsd-ctl (opens new window), which uses the same interface to spawn a Kubo (Go-IPFS) node, a JS-IPFS node, or an in-process JS-IPFS node.

Browsers

The ipfs, kubo-rpc-client, and ipfs-http-client libraries work in browsers, but each has special considerations noted in their READMEs.

The implementation is split into several modules.

Node modules

• /packages/interface-ipfs-core Tests to ensure adherence of an implementation to the spec
• /packages/ipfs An aggregator module that bundles the core implementation, the CLI, HTTP API server and daemon
• /packages/ipfs-cli A CLI to the core implementation
• /packages/ipfs-core The core implementation
• /packages/ipfs-core-types Typescript definitions for the core API
• /packages/ipfs-core-utils Helpers and utilities common to core and the HTTP RPC API client
• /packages/ipfs-daemon Run js-IPFS as a background daemon
• /packages/ipfs-grpc-client A gRPC client for js-IPFS
• /packages/ipfs-grpc-protocol Shared module between the gRPC client and server
• /packages/ipfs-grpc-server A gRPC-over-websockets server for js-IPFS
• /packages/ipfs-http-client A client for the RPC-over-HTTP API presented by js-ipfs
• /packages/kubo-rpc-client A client for the RPC-over-HTTP API presented by Kubo
• /packages/ipfs-http-server JS implementation of the Kubo RPC HTTP API (opens new window)
• /packages/ipfs-http-gateway JS implementation of the IPFS HTTP Gateway (opens new window)
• /packages/ipfs-http-response Creates a HTTP response for a given IPFS Path
• /packages/ipfs-message-port-client A client for the RPC-over-message-port API presented by js-ipfs running in a shared worker
• /packages/ipfs-message-port-protocol Code shared by the message port client & server
• /packages/ipfs-message-port-server The server that receives requests from ipfs-message-port-client

Packages

Listing of the main JS packages in the IPFS ecosystem:

Package	Version	Deps	CI/Travis	Coverage	Lead Maintainer
Files
ipfs-unixfs		(opens new window)	(opens new window)	(opens new window)	Alex Potsides
Repo
ipfs-repo		(opens new window)	(opens new window)	(opens new window)	Alex Potsides
ipfs-repo-migrations		(opens new window)	(opens new window)	(opens new window)	N/A
Exchange
ipfs-bitswap		(opens new window)	(opens new window)	(opens new window)	Dirk McCormick
IPNS
ipns		(opens new window)	(opens new window)	(opens new window)	Vasco Santos
Generics/Utils
ipfs-utils		(opens new window)	(opens new window)	(opens new window)	Hugo Dias
ipfs-http-client		(opens new window)	(opens new window)	(opens new window)	Alex Potsides
kubo-rpc-client		(opens new window)	(opens new window)	(opens new window)	Marcin Rataj
ipfs-http-response		(opens new window)	(opens new window)	(opens new window)	Vasco Santos
ipfsd-ctl		(opens new window)	(opens new window)	(opens new window)	Hugo Dias
is-ipfs		(opens new window)	(opens new window)	(opens new window)	Marcin Rataj
aegir		(opens new window)	(opens new window)	(opens new window)	Hugo Dias
libp2p
libp2p		(opens new window)	(opens new window)	(opens new window)	Jacob Heun
peer-id		(opens new window)	(opens new window)	(opens new window)	Vasco Santos
libp2p-crypto		(opens new window)	(opens new window)	(opens new window)	Jacob Heun
libp2p-floodsub		(opens new window)	(opens new window)	(opens new window)	Vasco Santos
libp2p-gossipsub		(opens new window)	(opens new window)	(opens new window)	Cayman Nava
libp2p-kad-dht		(opens new window)	(opens new window)	(opens new window)	Vasco Santos
libp2p-mdns		(opens new window)	(opens new window)	(opens new window)	Jacob Heun
libp2p-bootstrap		(opens new window)	(opens new window)	(opens new window)	Vasco Santos
@chainsafe/libp2p-noise		(opens new window)	(opens new window)	(opens new window)	N/A
libp2p-tcp		(opens new window)	(opens new window)	(opens new window)	Jacob Heun
libp2p-webrtc-star		(opens new window)	(opens new window)	(opens new window)	Vasco Santos
libp2p-websockets		(opens new window)	(opens new window)	(opens new window)	Jacob Heun
libp2p-mplex		(opens new window)	(opens new window)	(opens new window)	Vasco Santos
libp2p-delegated-content-routing		(opens new window)	(opens new window)	(opens new window)	Jacob Heun
libp2p-delegated-peer-routing		(opens new window)	(opens new window)	(opens new window)	Jacob Heun
IPLD
@ipld/dag-pb		(opens new window)	(opens new window)	(opens new window)	N/A
@ipld/dag-cbor		(opens new window)	(opens new window)	(opens new window)	N/A
Multiformats
multiformats		(opens new window)	(opens new window)	(opens new window)	N/A
mafmt		(opens new window)	(opens new window)	(opens new window)	Vasco Santos
multiaddr		(opens new window)	(opens new window)	(opens new window)	Jacob Heun

Hands-on examples

Explore js-ipfs through interactive coding challenges at ProtoSchool (opens new window).

There are lots of JS-IPFS use-case examples in the ipfs/js-ipfs GitHub repository (opens new window). They're all self-contained projects that let your spin up and test environments quickly. Check them out → (opens new window)

A good starting place is the IPFS 101, spawn a node and add a file to the IPFS network (opens new window).