Helia: IPFS's Modern JavaScript Implementation

Helia is the actual answer to a question this series has sidestepped so far: if a browser or Node.js app wants to speak IPFS directly, rather than through a gateway URL, what does it run today? js-ipfs, the project that used to answer that question, is deprecated. Helia is its replacement, and it's worth understanding on its own terms, not just as "the new js-ipfs," since its modular design changes what building a JavaScript IPFS app actually looks like, from the size of the bundle a browser has to download down to which pieces of the protocol a project even needs to import in the first place.

TL;DR:

• js-ipfs, the original JavaScript IPFS implementation, is deprecated. Helia is the modern replacement, TypeScript-first, built for both browser and Node.js environments
• Helia's architecture is modular rather than monolithic: a lightweight core, with separate packages for UnixFS, CAR handling, DAG-CBOR, and other pieces this series has already covered individually
• That modularity is the practical difference from js-ipfs: an app only imports what it actually uses, which keeps browser bundle sizes down instead of shipping the entire protocol stack for an app that only needs, say, UnixFS file reads
• Helia is a full participant in the concepts this series already covers, it can run as a relay-dependent Circuit Relay client (from the libp2p article) when a browser can't accept direct TCP connections, and it fetches and verifies blocks the same trustless way any other implementation does
• For anyone building a browser-based frontend on top of AIOZ Pin-hosted content, rather than going through a gateway URL, Helia is the practical current toolkit, complementary to AIOZ Pin's own official SDK, which is Node.js-only and server-side by design

Why This Needed Its Own Explainer

Every retrieval mechanism this series has covered, DHT lookups, Bitswap exchanges, CAR exports, block verification, is protocol-level: true regardless of which actual piece of software implements it. But someone building a JavaScript application still needs a real library to call, and the answer to "which one" changed. js-ipfs, the original implementation, reached end of life, and pointing a new project at deprecated tooling is a real, practical mistake this article exists to prevent.

What Helia Actually Is

Helia is the modern, actively maintained JavaScript and TypeScript implementation of IPFS, designed to work in both browser and Node.js environments. It implements the same underlying protocols this series has already covered in depth, content addressing, the Merkle DAG, libp2p for networking, Bitswap for block exchange, just as a JavaScript-native codebase built with today's async patterns and TypeScript support rather than js-ipfs's older architecture.

The Real Difference: Modularity Over a Monolith

The meaningful architectural shift isn't just "newer code," it's how Helia is structured. Instead of one large bundle containing every IPFS feature whether an app needs it or not, Helia ships a lightweight core plus separate, focused packages: UnixFS support for the file-and-directory representation this series' UnixFS article covers, CAR handling for the archive format from this series' CAR-files article, DAG-CBOR for the IPLD codec covered in this series' IPLD article, and others, each importable independently. An app that only reads UnixFS files doesn't have to ship code for DAG-CBOR handling it never touches, which directly matters for anything running in a browser, where bundle size affects real load time.

Helia in a Browser: Relying on What This Series Already Covers

A browser-based Helia node runs into the exact connectivity constraints this series' libp2p article already described: a browser can't accept inbound TCP connections the way a server-side node can, so browser-based Helia nodes commonly depend on Circuit Relay to participate in the network at all, the same relay mechanism covered there, not a separate browser-specific protocol. Once connected, Helia's block retrieval and verification work the same trustless way this series' content-verification article describes for any IPFS implementation: every block gets hash-checked against its CID regardless of which software fetched it.

Migrating an Existing js-ipfs Project

For a project still running on js-ipfs, the practical question isn't whether to move, deprecated means no further fixes or security patches land on it, it's how disruptive the move actually is. Because Helia implements the same underlying protocols this series covers throughout, content addressing, the Merkle DAG, DHT and Bitswap retrieval, the migration is mostly an API and packaging change rather than a conceptual one: code built around fetching and verifying CIDs keeps the same mental model, while the actual imports shift from one monolithic js-ipfs package to Helia's core plus whichever specific modular packages, UnixFS, CAR, DAG-CBOR, the project actually needs. The deprecation isn't a reason to delay a new project either; starting on js-ipfs today means inheriting the migration work later instead of avoiding it now.

Where Helia Fits Next to AIOZ Pin's Own SDK

AIOZ Pin's own official SDK, @aioznetwork/aioz-pin-sdk, is Node.js-only and built for server-side pinning operations, uploading, managing, and pinning content to AIOZ Pin's infrastructure. Helia solves a different, complementary problem: reading and interacting with IPFS content, including content already pinned on AIOZ Pin, from inside a browser-based application, without routing every request through a gateway URL. A typical architecture keeps both roles separate: the AIOZ Pin SDK on a server handles pinning and persistence, while a Helia-powered frontend can fetch, verify, and work with that same CID directly on the client side when an app's design calls for it.

Frequently Asked Questions

Is js-ipfs still the right choice for a new JavaScript IPFS project? No. js-ipfs is deprecated. Helia is its actively maintained replacement and is the current standard for JavaScript and TypeScript IPFS development.

What makes Helia's architecture different from js-ipfs? Helia is modular: a small core plus separate, independently importable packages for UnixFS, CAR, DAG-CBOR, and other features, instead of one large bundle containing everything regardless of what an app actually uses.

Does Helia work in the browser? Yes, that's one of its primary target environments, alongside Node.js. Browser-based Helia nodes typically depend on Circuit Relay for connectivity, since browsers can't accept direct inbound connections.

Does Helia verify content the same way other IPFS implementations do? Yes. Block retrieval and hash verification follow the same trustless model this series covers for IPFS generally, independent of which specific software implements it.

Can Helia be used together with AIOZ Pin? Yes, and they serve different roles. AIOZ Pin's Node.js SDK handles server-side pinning; Helia is what a browser-based frontend would use to fetch and verify that same pinned content directly, without going through a gateway URL.

Does using Helia require running a full IPFS node? It depends on configuration, but Helia's modular design specifically supports lighter-weight setups, importing only the pieces an application actually needs rather than a complete node's full feature set.

Related Reading

• ipfs:// in the Browser: How It Actually Works - the broader browser-support gap Helia is one part of the answer to
• libp2p: The Networking Layer Underneath IPFS - the Circuit Relay mechanism browser-based Helia nodes commonly depend on
• UnixFS: How IPFS Represents Files and Directories - one of Helia's modular packages, covered in full elsewhere in this series
• AIOZ Pin CLI Tutorial: Login, Pin, List, and Unpin Files - the server-side tooling Helia complements rather than replaces

References

• Helia