BROWSERS.md

Using JS IPFS in the Browser

Table of Contents

• Limitations of the Browser Context
• Addressing Limitations
• Best Practices
• Code Examples

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 currently 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 ones. Web Crypto API not being available at all.

• JS IPFS comes with limited support for the DHT in client mode which delegates content discovery requests to other DHT nodes.

  However, it's worth noting that even though you'll get results from DHT queries, most nodes in the network are not dialable from browsers because they only support TCP and/or QUIC transports.

  For now, the content discovery and connectivity to other peers are achieved with a mix of DHT client requests, 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-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 signaling 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 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 signalling and transport service. When in doubt, use WebSockets ones.
• Run your own instance of *-star signalling 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 a regular long-running IPFS daemon, e.g. kubo
  • 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 environments. Make sure preload and delegate nodes used in config are self-hosted and under your control (expose a subset of kubo (formerly go-ipfs) APIs via reverse proxy such as Nginx).
• If your main goal is to provide content and files to the IPFS network from a browser and you would like to avoid running infrastructure, consider using a pinning service like Web3.storage.

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:', new TextDecoder().decode(data))
})
</script>

More advanced examples and tutorials can be found in the examples