# Helia IPFS: a modular TypeScript node for linked content

> Helia provides a TypeScript implementation of IPFS for JavaScript and browser applications, with separate modules for strings, JSON, UnixFS, networking, storage, and named records. Its modular design gives application developers control over storage and protocol implementations, but it also makes dependency and node configuration a real adoption cost.

**ipfs/helia** — An implementation of IPFS in TypeScript

- Repository: https://github.com/ipfs/helia
- Website: https://helia.io
- Stars: 1,357 · Forks: 169
- Language: TypeScript
- License: Apache-2.0
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/ipfs-helia

## Helia's scope for TypeScript IPFS applications

Helia solves the problem of embedding IPFS capabilities in JavaScript and browser software without treating every protocol and storage decision as part of the core API. It is aimed at developers building applications in prolific JS and browser environments who need content-addressed storage and access to IPFS components. Its interface is intentionally narrow. The repository describes the basic Helia API in `packages/interface`, while concrete functionality is divided among packages under `packages/`.

The basic abstraction is useful when an application needs IPFS data structures but has different requirements for persistence, peer discovery, block exchange, or encoding. A server application might connect filesystem or S3-backed storage, while a browser application might use IndexedDB. Helia does not force those choices into one deployment model. The repository system diagram shows storage targets such as `File system/IDB/S3/etc` for blocks and `Level/S3/IDB/etc` for data, making this separation visible at the architecture level.

That design also means Helia is not simply a conventional all-in-one node selected by one command. Developers bring implementations for APIs that suit the application. The practical audience is therefore narrower than the phrase "an implementation of IPFS in TypeScript" may initially suggest. It is most relevant when application code needs Helia's typed interfaces and composable packages.

## Helia data flow from application objects to CIDs

Helia's data flow begins with an application calling `createHelia()` and attaching a format-specific module. The module handles conversion into content-addressed blocks, computes a CID through a multihash hasher, and makes the resulting content available through the Helia block and network layers. Retrieval reverses that process. The application passes a CID to the module, Helia obtains the required blocks, and the module decodes them back into a string, JavaScript object, or linked object.

The repository separates block storage from the protocol mechanisms that retrieve blocks. The diagram places `Blockstore` before `BlockBrokers`, with `Bitswap` and `TrustlessGateways` connected as possible block retrieval paths. `Libp2p` participates in the `DHT`, `PubSub`, `IPNI`, and `Reframe` components. `UnixFS` writes into the blockstore, while `@helia/ipns` uses the datastore. This is a composable pipeline rather than a single hard-coded transfer path.

The default hasher for the documented add methods is the `sha2-256 multihash`. Helia also accepts another hasher through `AddOptions`. This is not merely an internal optimization because the hash function affects identity. The README warns that changing the hasher returns a different CID for the same content. Applications must therefore treat their chosen codec and hasher as part of the data format's address contract.

## Choosing strings, JSON, DAG-JSON, or DAG-CBOR in Helia

Helia does not impose one serialization format on every object. The choice affects interoperability, representation, and how linked structures behave. `@helia/strings` handles plain strings. `@helia/json` handles plain JavaScript objects without exposing linked-object semantics in its basic example. DAG formats retain CID references between objects, which makes them appropriate when application records point to other immutable objects.

`@helia/dag-json` stores linked objects as CIDs in a JSON-based DAG. In its documented example, one object containing `{ hello: 'world' }` is added first. A second object containing `{ link: myImmutableAddress1 }` is then added. Reading the second object produces an object whose `link` property is a `CID`, and that CID can be passed to another `get` call. The address chain therefore remains navigable as typed objects.

`@helia/dag-cbor` is a real alternative when the application prefers Concise Binary Object Representation. Its API is documented as working in a similar way, but the stored representation uses CBOR. The practical difference is serialization, not a separate content model. A team that needs linked JavaScript objects must decide whether JSON-based interoperability or CBOR storage is more suitable. The repository does not provide a general performance comparison, so it does not support a claim that one format is faster or smaller in every application.

## Installing Helia modules and running a first string add

The README links each documented module from npm and points users to the `ipfs-examples/helia-examples` repository for setup and broader examples. It does not give an explicit installation command or a package-manager version requirement. Because no install command is documented here, inventing `npm install`, a package version, or a runtime flag would be misleading. Start from the linked package pages and the examples repository, then use the following first-use pattern exactly as shown in the README.

The example creates a Helia instance, attaches `@helia/strings`, adds `hello world`, and retrieves it through the returned immutable address. The expected output documented by the README is `hello world`.

```js
import { createHelia } from 'helia'
import { strings } from '@helia/strings'

const helia = await createHelia()
const s = strings(helia)
const myImmutableAddress = await s.add('hello world')
console.log(await s.get(myImmutableAddress))
```

This is a local add-and-get path. The README does not state that this bare `createHelia()` configuration supplies persistent storage or connects the application to a specific remote gateway. Developers should verify those choices against the selected Helia packages and application environment.

## Building a linked JSON graph with Helia CIDs

DAG-JSON is the clearest documented example of Helia's value beyond a simple key-value wrapper. The first add operation returns a CID for the object itself. The second add operation serializes a JavaScript object containing that CID. During retrieval, Helia decodes the outer object and preserves the CID value in its `link` property. The application can then use that value to retrieve the original object.

The important design boundary is that content identity and object navigation are separate operations. Adding an object returns an address. Embedding that address in another object creates a link. Fetching the outer object does not flatten the entire graph automatically. The example explicitly performs a second `get` call for `retrievedObject.link`. Applications that expect automatic dereferencing will need to account for this behavior in their own traversal logic.

This approach is a good fit for manifests, records that refer to prior versions, and application structures composed of immutable pieces. It is less convenient when a developer expects a mutable object graph. The returned CID represents immutable content. Updating a linked record means creating new content and, where appropriate, creating another link to the replacement.

## Helia's configurable storage and networking costs

Helia's modularity creates two different kinds of costs. The first is dependency management. The workspace contains separate packages for interfaces and implementations, and the README documents separate imports for `helia`, `@helia/strings`, `@helia/json`, `@helia/dag-json`, and `@helia/dag-cbor`. Applications should install only the modules required by their format and transport needs, while checking each package's own compatibility and documentation.

The second cost is integration work. `Blockstore`, `Datastore`, `Libp2p`, `Bitswap`, `TrustlessGateways`, `DHT`, `PubSub`, `IPNI`, and `Reframe` appear as distinct architectural elements. A production application must determine which ones are needed, configure the selected implementations, and decide how data survives process or browser restarts. The repository diagram names several possible storage backends but does not claim that every backend is bundled into the core package.

Helia is therefore a poor fit when the application needs a turnkey node with one predetermined storage policy and networking setup. It is a better fit when those choices are application concerns. The README does not document a rollback procedure, an upgrade matrix for storage backends, or a migration guide for changing hashers, so those checks belong in the initial technical evaluation.

## Helia maintenance, licensing, and release boundaries

The repository is not archived. Its last push was on 2026-10-14, which indicates recent repository activity based on the available maintenance data. Recent release entries include `utils-v3.0.6`, `unixfs-v8.0.9`, and `unixfs-v8.0.8`, all dated in September 2026. These releases belong to the broader repository package set rather than proving that every Helia interface has an identical release cadence.

The top-level repository identifies the project under the Apache-2.0 license, while the repository `package.json` uses `Apache-2.0 OR MIT`. The repository also contains `LICENSE-APACHE` and `LICENSE-MIT`. This is a licensing choice that should be reviewed against the application's distribution model, but this article does not provide legal advice. Teams should inspect the exact package license and notices shipped with the packages they publish.

For maintenance, the visible scripts include `npm run build`, `npm run test`, `npm run lint`, `npm run dep-check`, and `npm run doc-check`. The workspace uses npm workspaces and Aegir. An adopting project should also account for TypeScript, browser, and storage compatibility across upgrades. The README does not provide a complete version compatibility table.

## Conclusion

Helia fits TypeScript applications that need content-addressed data with direct control over codecs, storage, and network components. It is a poor fit for a simple application that wants a complete IPFS node without assembling one. Before adoption, check whether the required codec, persistence layer, libp2p protocols, browser storage support, and license choice match the application. For a first implementation, confirm that `createHelia()` can load `@helia/strings` without adding storage or networking requirements beyond the intended scope.

## FAQ

### What is Helia in TypeScript?

Helia is a modular TypeScript implementation of IPFS for JavaScript and browser environments. It exposes separate modules for data formats, storage, networking, and related IPFS functions.

### How do I add and retrieve a string with Helia?

Create a Helia instance with `createHelia()`, attach `@helia/strings` with `strings(helia)`, then call `add()` and `get()` using the returned CID. The README's example retrieves the original `hello world` value.

### Does Helia automatically use the same CID for content with different hashers?

No. The README states that changing the hasher produces a different CID for the same content. Applications should treat the selected hasher as part of the address format.

## Sources

- [ipfs/helia on GitHub](https://github.com/ipfs/helia)
- [License: Apache-2.0](https://github.com/ipfs/helia/blob/main/LICENSE)
- [Project website](https://helia.io)
- [README](https://github.com/ipfs/helia/blob/main/README.md)
- [Releases](https://github.com/ipfs/helia/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ipfs-helia