# 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

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 (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

Listing of the main JS packages in the IPFS ecosystem:

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