js-IPFS deprecation / replaced by Helia 🌞

TL;DR: js-IPFS is being deprecated, and has been superseded by Helia.

There are exciting times ahead for IPFS in JS. Some of you may have already heard of Helia, the new implementation that’s designed as a composable, lightweight, and modern replacement for js-IPFS.

It has a simplified API which can be extended by other modules depending on the requirements of your application such as @helia/unixfs, @helia/ipns, @helia/dag-cbor and others.

It ships with the latest and greatest libp2p, which means it has the best connectivity options, including the new WebTransport and WebRTC transports that dramatically improve the connectivity options for browser environments.

js-IPFS is in the process of being deprecated so you should port your apps to Helia to receive bug fixes, features, and performance improvements moving forwards.

:books: Learn more about this deprecation or how to migrate.


How does the migration to Helia effect projects making use of ipfs-http-client to control an external Kubo/go-ipfs node?

I have a couple projects using that configuration. Should I stick with ipfs-http-client for now? Does Helia have a replacement interface?

1 Like

If you’re using Kubo’s HTTP RPC API, you should switch to kubo-rpc-client - it was forked from ipfs-http-client a few months back so is a drop-in replacement and is where all the Kubo compatibility fixes go.


There is a duplicate post ⛔️ js-IPFS deprecation / replaced by Helia 🌞 | IPFS Blog & News - #2 by BigLep from the blog post, but we’ll make this this the canonical place to comment.

I have worked on js-ipfs previously and now since I needed to use it for a Layer 2 blockchain I am making, I re-tested js-ipfs and helia, since I saw the updates.

For my purpose (since I am not a go developer) I will probably still need to use js-ipfs as I find it a lot more semantic - the syntax of Helia is not intuitive, but this is what I feel. Maybe a go developer will not feel that way. I am more of a full stack JS dev so the style of writing the code is much easier for me on js-ipfs.

I can see that it will not be maintained any further and the team will shift to maintaining Helia and associated packages like dag-json, etc. But I need to work with MFS. I do not see any implementation of that on Helia. If there is, can you point me to the right function reference?

For my work, I will also need to setup clusters and I do not see an implementation of that on Helia. Again, maybe I am missing it, but I find js-ipfs much more intuitive for my work currently since I am working with a file system (that’s how I designed my system before reading the blog post) and I need the functions which allows me to create clusters and store files as a MFS.


1 Like

As a (larger than intended) aside: I’m curious why you feel Helia would be more familiar to “Go developers.” I’m also a full-stack engineer, specializing in JS and TS over the last 16 years, and Helia feels much more like idiomatic ESM JS than js-ipfs does. One main reason Helia exists is that js-ipfs was too tightly coupled to the Kubo API (go implementation of IPFS) and had a lot of architectural decisions influenced by Go. Helia has removed a large part of those problems already and intends to be idiomatic to the latest JS/TS standards. If we’re not meeting those goals in your eyes, we would love to hear how so we can improve Helia further.

I think your callout about needing cluster support for Helia nodes is valid. Would having an example added to GitHub - ipfs-examples/helia-examples: How to do most anything with your Helia node that shows how to set up a cluster of Helia nodes work for you?

As for MFS, you can find some info at Migrating from js IPFS · ipfs/helia Wiki · GitHub for how the APIs have changed. Is there some other information you need about creating files/folders with Helia?


Yes so I’ll explain the issue. The thing is that Express.js is not ESM based, and Express is the leanest framework that we mostly use to test most Node.js applications before deploying as a server directly. The examples for Helia.js are not how we deploy servers. I need Express to include other things like modules to connect to a database, or to expose a SSL based port with access control and JWT authentication. Express handles all that.

Currently, to use ES6 modules like say IPFS (latest versions) and Helia, I need to use a ES6 based framework which is either maintained by random devs (like tinyhttp) or too large to code small applications (like maybe Sails.js).

The examples are written in native Node.js but Node.js latest versions have ES6 bindings because of which it is working. If I include a module which does not have ES6 bindings then it becomes an issue.

This is not an issue specific to Helia,js as I realized since others are also upgrading their libraries to ES6. The issue is from the perspective of a middleware coder who cannot just use any framework which is not stable or is absolutely new. So, Express works best for us generally. The ES6 versions of Express are maintained by individual developers and they cannot be, thus, used for enterprise level applications where I need regular or at least LTS type maintenance.

I have used Helia though like mentioned before and it handles memory much better than IPFS.js especially for larger files. And I can easily migrate to UNIXFS style of handling the files and folders. So, I will definitely use it and provide feedback if I face any issue with Helia.js.

Thanks a lot for your help till now.

Glad you’ve had a good experience with memory consumption, one of the goals for Helia is definitely for it to be more lightweight than js-IPFS.

On the Express thing - it’s possible to use Helia from CJS codebases if you can’t upgrade to ESM yet - have you checked out the Helia CJS example?


Yes I’ll show you what happens if I do that:

This is my package.json:


This is happening because of the first dependency - terra.js

Terra js doesn’t work on Node 18 so I need to keep it at Node 16.

Is there any workaround for this?

You could use the patch-package module to remove the engine requirements and then go from there.

Node 16 is being removed from the maintenance cycle in October 2023. I am unaware of any workarounds to get Helia (or its deps) working on Node16. JS is moving towards the future, but unfortunately, fighting it requires an army we don’t have.

1 Like

So I upgraded to Node.js v20.5.0 and now I am getting the following the following error while using the Next js template for React and Helia UNIXFS installed:

I installed fs promises also from here:

But it is not getting applied to Next js:

Any idea what is happening?

@arunadaybasu please can you try again with @helia/unixfs@1.4.1 or later - there was a bug in the config of previous versions.

Please open an issue on GitHub - ipfs/helia-unixfs: UnixFS commands for helia if you are still having problems.

1 Like

Hey you’re achingbrain. I was trying out the IPFS templates and I was getting this error, but I’ll try with Helia js instead as you suggested.

I think the problem is that the browser polyfillls need to be added one by one. But I’ll do that with Helia js and report back here.


Hey I tried to use the webpack template but there is an error I am getting when trying to bootstrap the connection:

It seems like this is another one of those Webpack 4 module errors.

There is one more issue I am facing. When I upload a file and then try to access it from the public node it isn’t working. I am also not being able to get the multiaddress of the connection:

This is the code:

So it should print the address and then the multiaddress cause I need the multiaddress to connect it to a public peer. Or so I assume. Otherwise, the file which has been added is not accessible publicly using the URL being printed (which should be the public URL):

Hey @arunadaybasu, thanks for reaching out. Are you still running into issues?

If there is a particular issue with a GitHub - ipfs-examples/helia-examples: How to do most anything with your Helia node not running properly, opening an issue in that repo would be great. If there are topics that need discussion that aren’t a specific bug/issue, please post at Helia - IPFS Forums and we will do our best to help out there.

For orthers, specific issue debugging (not related to js-ipfs deprecation) may be off-topic for this thread, and would be better suited for a post at Helia - IPFS Forums.

I have been trying to use helia in my react.js application but keep getting the following error in console:
WebSocket connection to ‘wss://ny5.bootstrap.libp2p.io/p2p/QmQCU2EcMqAqQPR2i9bChDtGNJchTbq5TbXJJ16u19uLTa’ failed:
Failed to establish a connection to net::ERR_CONNECTION_REFUSED.
Failed to establish a connection to https://[2a02:4780:f:f81b::1]:4001/.well-known/libp2p-webtransport?type=noise: net::ERR_ADDRESS_UNREACHABLE.

And then the app crashes.
and the code is:
import { createHelia } from “helia”;
const helia = await createHelia();

Here’s my package.json:
“name”: “dapp-eth-dim”,
“version”: “0.1.0”,
“private”: true,
“dependencies”: {
@helia/unixfs”: “^1.4.1”,
@testing-library/jest-dom”: “^5.17.0”,
@testing-library/react”: “^13.4.0”,
@testing-library/user-event”: “^13.5.0”,
“bootstrap”: “^4.6.2”,
“helia”: “^2.1.0”,
“react”: “^18.2.0”,
“react-dom”: “^18.2.0”,
“react-scripts”: “5.0.1”,
“web-vitals”: “^2.1.4”,
“truffle”: “^5.0.2”,
“web3”: “^4.2.2”
“scripts”: {
“start”: “react-scripts start”,
“build”: “react-scripts build”,
“test”: “react-scripts test”,
“eject”: “react-scripts eject”
“eslintConfig”: {
“extends”: [
“browserslist”: {
“production”: [
“not dead”,
“not op_mini all”
“development”: [
“last 1 chrome version”,
“last 1 firefox version”,
“last 1 safari version”

Kindly suggest. Thanks

In a peer to peer system it’s normal that some peers will be unreachable.

Unfortunately browsers sometimes log error messages when connections fail, but the failures are survivable.

And then the app crashes

This isn’t enough information to be able to help you - please can you open an issue on the Helia repo with a minimal reproduction case, a link to a public GitHub repo will do.