InterPlanetary File System — content-addressed peer-to-peer storage protocol. Files are referenced by CID, not location. Helia is the modern JS implementation; js-ipfs is deprecated.
- 01NFT metadata and media
- 02content-addressed assets
- 03censorship-resistant frontends
- 04reproducible data references
- 05decentralized app distribution
- pnpm add helia @helia/unixfs @helia/json
| Variable | Scope | Description |
|---|---|---|
| NEXT_PUBLIC_IPFS_GATEWAY | Client | Public IPFS HTTP gateway base URL (e.g. `https://ipfs.io`, `https://cloudflare-ipfs.com`, or your own dedicated gateway). |
Use Helia, the modern TypeScript IPFS implementation, for in-process IPFS — `js-ipfs` is deprecated. Create a node with `createHelia()` then add files via `unixfs(helia).addBytes(bytes)` or JSON via `json(helia).add(obj)` to get a CID. For pinning to keep content available, do NOT rely on a local Helia node — pin via a managed pinning service (Pinata, Filebase, web3.storage) or run kubo. To read in the browser, dereference CIDs through an HTTP gateway (`${NEXT_PUBLIC_IPFS_GATEWAY}/ipfs/{cid}`) and prefer subdomain gateways (`https://{cid}.ipfs.dweb.link`) for origin isolation. Always use CIDv1 base32 (default in Helia) for subdomain gateway compatibility, and store the CID onchain or in your DB — never the gateway URL.
- ⚑IPFS does NOT guarantee persistence — content disappears when no node pins it. Always pin via a managed service (Pinata/Filebase/web3.storage) or your own infra; in-browser Helia nodes are ephemeral.
- ⚑Public gateways (ipfs.io, cloudflare, dweb.link) rate-limit, censor, or go down — never hardcode a single gateway and never store gateway URLs in your DB; store the bare CID and resolve at render time.
- ⚑CIDv0 (`Qm...`) is incompatible with subdomain gateways — use CIDv1 base32 (`bafy...`) for `{cid}.ipfs.dweb.link` style URLs.
- ⚑Browser Helia uses bitswap over WebTransport/WebRTC — discovery to non-public peers can be slow or fail; for user-facing reads, an HTTP gateway is almost always faster and more reliable.
- ⚑Content is public and immutable — anything you upload can be downloaded by anyone forever (assuming someone pins it). Never put PII or secrets on IPFS even temporarily.
- ⚑Filecoin deals are separate from IPFS pinning — being pinned does not mean it's archived to Filecoin and vice versa.