# IPFS in JavaScript

# JavaScript libraries

There are two main JavaScript libraries for working with IPFS, ipfs and ipfs-http-client. Both 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 WebScoekts 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.

# 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 client

JS-IPFS HTTP RPC API (opens new window) is a client library that controls an active IPFS node (Kubo or JS-IPFS) running through its RPC API.

  • JS-IPFS will internally use this library if it detects another node is running on your machine. 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.
  • 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 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

This table is generated using the module package-table (opens new window) with package-table --data=package-list.json.

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
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).