Upgrade guide from Helia 3.0.0 to Helia 4.0.0

New features and bug fixes

Please see the release notes for the full run-down of all the new features and bug fixes in helia@4.x.x.

Migration guide

New http only @helia/http package

Helia@4.0.0 aims to increase the viability of IPFS in web browsers by leaning heavily on Trustless Gateways for block retrieval and Delegated HTTP Routers for other operations such as resolving block providers and IPNS.

The new @helia/http module implements the Helia API defined in @helia/interface meaning it is compatible with the full @helia/* ecosystem of helper modules.

import { createHeliaHTTP } from '@helia/http'
import { unixfs } from '@helia/unixfs'
import { CID } from 'multiformats/cid'

const cid = CID.parse('QmFoo')
const node = await createHeliaHTTP()
const fs = unixfs(node)

// do UnixFS things
for await (const buf of fs.cat(cid)) {
  // ...do something with buf
}

helia continues to depend on libp2p

The helia package takes a more varied approach and continues to use libp2p which supports all transports supported by js-libp2p, e.g. TCP, WebSockets, WebTransport, and WebRTC, in addition to all protocols supported by js-libp2p.

The .libp2p property has been removed from the Helia API but it is still present on the return type of the createHelia function exported from the helia module.

If you are using the return types of this function there is nothing to do, otherwise you will have to update your code to use the types from helia instead of @helia/interface, if you depend on accessing the .libp2p property in your code.

Routing

Because the .libp2p property has been removed from the Helia API a new .routing property has been added to enable use of Delegated HTTP Routers to perform what were previously content and peer routing operations in a libp2p-agnostic way.

Before

const peerId = peerIdFromString('123Foo...')

const peerInfo = await helia.libp2p.peerRouting.findPeer(peerId)

After

const peerId = peerIdFromString('123Foo...')

const peerInfo = await helia.routing.findPeer(peerId)

IPNS

@helia/ipns has been updated to use the new .routing property on the Helia API by default so there's no need to configure a separate libp2p router any more, instead it will use whatever has been configured on the passed Helia node.

Before

import { createHelia } from 'helia'
import { ipns } from '@helia/ipns'
import { libp2p } from '@helia/ipns/routers'

const node = await createHelia()
const name = ipns(helia, {
  routers: [
    libp2p(helia)
  ]
})

const peerId = peerIdFromString('123Foo...')
const cid = await name.resolve(peerId)

After

import { createHelia } from 'helia'
import { ipns } from '@helia/ipns'

const node = await createHelia()
const name = ipns(helia)

const peerId = peerIdFromString('123Foo...')
const cid = await name.resolve(peerId)

Pub/Sub

Helia's dependency on @chainsafe/libp2p-gossipsub has been removed. This is because it's not used to resolve or publish IPFS content, and is quite large with many dependencies, and also consumes a non-trivial amount of CPU so is often an unnecessary encumbrance.

If your project requires it, you can restore the previous configuration by passing custom libp2p config to the Helia factory function:

import { createHelia, libp2pDefaults } from 'helia'
import { gossipsub } from '@chainsafe/libp2p-gossipsub'

const libp2pOptions = libp2pDefaults()
libp2pOptions.services.pubsub = gossipsub()

const helia = await createHelia({
  libp2p: libp2pOptions
})