BROWSERS.md

Using JS IPFS in the Browser

JS IPFS is the implementation of IPFS protocol in JavaScript. It can run on any evergreen browser, inside a service or web worker, browser extensions, Electron and in Node.js.

This document provides key information about running JS IPFS in the browser.
Save time and get familiar with common caveats and limitations of the browser context.

Limitations of the Browser Context

• Transport options are limited to WebSockets and WebRTC.

  This means JS IPFS running in the browser is limited to Web APIs available on a web page. There is no access to raw TCP sockets nor low level UDP, only WebSockets and WebRTC.

• Key Web APIs require or are restricted by Secure Context policies.

  This means JS IPFS needs to run within Secure Context (HTTPS or localhost). JS IPFS running on HTTPS website requires Secure WebSockets (TLS) and won't work with unencrypted one. Web Crypto API not being available at all.

• DHT is not available in JS IPFS yet.

  We are working on it. For now, the discovery and connectivity to other peers is achieved with a mix of rendezvous and relay servers, delegated peer/content routing and preload servers.

Addressing Limitations

We provide a few additional components useful for running JS IPFS in the browser:

• libp2p-websocket-star - incorporates both a transport and a discovery service that is facilitated by the custom rendezvous server available in the repo.
  • Instructions on enabling websocket-star in js-ipfs config can be found here.
  • Make sure to run your own rendezvous server.
• libp2p-webrtc-star - incorporates both a transport and a discovery service that is facilitated by the custom rendezvous server available in the repo
  • Instructions on enabling webrtc-star in js-ipfs config can be found here.
  • Make sure to run your own rendezvous server.
• libp2p-webrtc-direct - a WebRTC transport that doesn't require the set up a signalling server.
  • Caveat: you can only establish Browser to Node.js and Node.js to Node.js connections.

Note: those are semi-centralized solutions. We are working towards replacing *-star with and ambient relays and libp2p-rendezvous. Details and progress can be found here.

You can find detailed information about running js-ipfs here.

Best Practices

• Configure nodes for using self-hosted *-star signaling and transport service. When in doubt, use WebSockets ones.
• Run your own instance of *-star signaling service. The default ones are under high load and should be used only for tests and development.
• Make sure content added to js-ipfs running in the browser is persisted/cached somewhere on regular IPFS daemon
  • Manually pin or preload CIDs of interest with refs -r beforehand.
  • Preload content on the fly using preload feature and/or configure delegated routing.
    • Avoid public instances in production environment. Make sure preload and delegate nodes used in config are self-hosted and under your control (expose a subset of go-ipfs APIs via reverse proxy such as Nginx).

Code Examples

Prebuilt bundles are available, using JS IPFS in the browser is as simple as:

<script src="https://cdn.jsdelivr.net/npm/ipfs/dist/index.min.js"></script>
<script>
document.addEventListener('DOMContentLoaded', async () => {
  const node = await Ipfs.create()
  const results = await node.add('=^.^= meow meow')
  const cid = results[0].hash
  console.log('CID created via ipfs.add:', cid)
  const data = await node.cat(cid)
  console.log('Data read back via ipfs.cat:', data.toString())
})
</script>

More advanced examples and tutorials can be found in /examples