Registry / http-networking / ipfs-http-client-lite

ipfs-http-client-lite

JSON →
library0.3.0jsnpmunverified

ipfs-http-client-lite is a lightweight JavaScript client library designed to interact with the IPFS HTTP API. Its primary differentiator is its small bundle size, aiming for less than 20KB, making it suitable for resource-constrained browser environments. The current stable version is 0.3.0. Based on its release history, which includes incremental feature additions like MFS commands and pubsub, the project demonstrates an active, albeit not rapid, release cadence. It provides a focused alternative to the more comprehensive `ipfs-http-client` for applications where bundle size and minimal footprint are critical, supporting core IPFS operations such as adding and retrieving files, and interacting with the Mutable File System.

npm install ipfs-http-client-lite
INSTALL
IMPORT
SIG · IPFS-HTTP-CLIENT-L
I
ipfs-http-client-lite
http-networkingjavascriptv0.3.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

IpfsHttpClientLite
import IpfsHttpClientLite from 'ipfs-http-client-lite'
const IpfsHttpClientLite = require('ipfs-http-client-lite')
The README shows CommonJS `require`. For modern Node.js and bundlers, ESM `import` is preferred. The library may still require specific bundler configurations for ESM in some environments.
cat
import cat from 'ipfs-http-client-lite/src/cat'
const cat = require('ipfs-http-client-lite').cat
For 'ultra small bundle size', individual methods can be imported directly from their source files. This import path might change in future major versions.
add
import add from 'ipfs-http-client-lite/src/add'
Like `cat`, other core methods such as `add` can be imported directly for tree-shaking benefits, though the README doesn't explicitly show this specific example, it follows the pattern.

This quickstart demonstrates how to initialize the IPFS client, add content, retrieve it using `cat`, and interact with the Mutable File System (MFS) by creating a directory and writing/reading a file, including error handling.

import IpfsHttpClientLite from 'ipfs-http-client-lite'; // Configure the IPFS client. Ensure your IPFS daemon is running on port 5001. // You can also add custom headers, e.g., for authorization. const ipfs = IpfsHttpClientLite({ apiUrl: 'http://localhost:5001', headers: { Authorization: `Bearer ${process.env.IPFS_AUTH_TOKEN ?? ''}` // Example for authentication } }); async function runExample() { try { // Add content to IPFS const content = Buffer.from('Hello from ipfs-http-client-lite!'); const addResult = await ipfs.add(content); console.log('Added content CID:', addResult.cid.toString()); // Retrieve content from IPFS const retrievedData = await ipfs.cat(addResult.cid.toString()); console.log('Retrieved content:', retrievedData.toString()); // Example of using MFS (Mutable File System) commands const mfsPath = '/my-directory/my-file.txt'; await ipfs.files.mkdir('/my-directory', { parents: true }); await ipfs.files.write(mfsPath, content, { create: true }); console.log(`Wrote content to MFS path: ${mfsPath}`); const mfsContent = await ipfs.files.read(mfsPath); console.log('Content from MFS:', mfsContent.toString()); } catch (error) { console.error('An error occurred:', error); console.warn('Ensure your IPFS daemon is running and accessible at http://localhost:5001.'); console.warn('If in a browser, check CORS settings on your IPFS daemon.'); } } runExample();
Debug
Known issues
gotchaWhen using ipfs-http-client-lite in a web browser, Cross-Origin Resource Sharing (CORS) issues commonly arise. IPFS daemons by default reject requests from unknown domains, leading to 'origin not allowed' errors.
fix
Configure your IPFS daemon to allow requests from your frontend's domain. Use `ipfs config --json API.HTTPHeaders.Access-Control-Allow-Origin '["http://your-frontend-domain.com"]'` and `ipfs config --json API.HTTPHeaders.Access-Control-Allow-Methods '["PUT", "POST", "GET"]'`, then restart your daemon.
affects: >=0.0.1
breakingThe library explicitly states support for Node.js Current and Active LTS versions. Using older Node.js versions (e.g., <10.0.0) may lead to unexpected errors or compatibility issues.
fix
Ensure your Node.js environment meets the minimum requirement of `Node.js >=10.0.0`. Upgrade Node.js to a supported LTS version.
affects: <=0.3.0
gotchaWhen importing individual methods for smaller bundle sizes (e.g., `ipfs-http-client-lite/src/cat`), these 'src' imports are not part of the public API and may change paths or internal structures in minor or patch releases, potentially breaking applications.
fix
For maximum stability, especially in production, consider importing the main `IpfsHttpClientLite` factory function. If specific method imports are critical for bundle size, pin the `ipfs-http-client-lite` version explicitly in your `package.json` to prevent unexpected changes.
affects: >=0.0.1
gotchaThe library relies on an external IPFS daemon running. If the daemon is not running or is configured on a different port than specified in the client, network connection errors will occur.
fix
Verify your IPFS daemon is running with `ipfs daemon` and its API port is correctly configured (default is 5001). Check `ipfs config Addresses.API` and update it if necessary, then restart the daemon.
affects: >=0.0.1
Errors
Common errors & fixes
Access to fetch at 'http://localhost:5001/api/v0/...' from origin 'http://localhost:3000' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.
The IPFS daemon is rejecting requests from your web application's origin due to CORS security policies.
fix
Configure the IPFS daemon's CORS settings: `ipfs config --json API.HTTPHeaders.Access-Control-Allow-Origin '["http://localhost:3000", "http://127.0.0.1:3000"]'` and `ipfs config --json API.HTTPHeaders.Access-Control-Allow-Methods '["PUT", "POST", "GET"]'`. Remember to restart the IPFS daemon after making configuration changes.
Error: connect ECONNREFUSED 127.0.0.1:5001
The ipfs-http-client-lite library could not connect to the IPFS daemon at the specified address and port. This usually means the daemon is not running, or it's running on a different port/address.
fix
Start your IPFS daemon using `ipfs daemon`. If it's already running, verify its API address and port with `ipfs config Addresses.API` and ensure it matches the `apiUrl` configured in your `IpfsHttpClientLite` client.
TypeError: ipfs.add is not a function
This error occurs if you are trying to call a method like `add` directly on the `ipfs` object obtained from `IpfsHttpClientLite` when you might be expecting specific method exports, or if the client wasn't initialized correctly.
fix
Ensure you are using the correct method signature. `ipfs.add` expects `Buffer`, `Uint8Array`, or `ReadableStream` as input. If you imported specific methods, ensure `add` was among them and correctly aliased, or use the `IpfsHttpClientLite` factory function which returns an object with all available API methods.
Upgrade
Version history
0.3.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
6 hits · last 30 days
node
6
Resources