{"id":17273,"library":"ipfs-http-client-lite","title":"IPFS HTTP Client Lite","description":"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.","status":"active","version":"0.3.0","language":"javascript","source_language":"en","source_url":"https://github.com/ipfs-shipyard/js-ipfs-http-client-lite","tags":["javascript","ipfs","http","api","client","rpc","rest"],"install":[{"cmd":"npm install ipfs-http-client-lite","lang":"bash","label":"npm"},{"cmd":"yarn add ipfs-http-client-lite","lang":"bash","label":"yarn"},{"cmd":"pnpm add ipfs-http-client-lite","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const IpfsHttpClientLite = require('ipfs-http-client-lite')","symbol":"IpfsHttpClientLite","correct":"import IpfsHttpClientLite from 'ipfs-http-client-lite'"},{"note":"For 'ultra small bundle size', individual methods can be imported directly from their source files. This import path might change in future major versions.","wrong":"const cat = require('ipfs-http-client-lite').cat","symbol":"cat","correct":"import cat from 'ipfs-http-client-lite/src/cat'"},{"note":"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.","symbol":"add","correct":"import add from 'ipfs-http-client-lite/src/add'"}],"quickstart":{"code":"import IpfsHttpClientLite from 'ipfs-http-client-lite';\n\n// Configure the IPFS client. Ensure your IPFS daemon is running on port 5001.\n// You can also add custom headers, e.g., for authorization.\nconst ipfs = IpfsHttpClientLite({\n  apiUrl: 'http://localhost:5001',\n  headers: {\n    Authorization: `Bearer ${process.env.IPFS_AUTH_TOKEN ?? ''}` // Example for authentication\n  }\n});\n\nasync function runExample() {\n  try {\n    // Add content to IPFS\n    const content = Buffer.from('Hello from ipfs-http-client-lite!');\n    const addResult = await ipfs.add(content);\n    console.log('Added content CID:', addResult.cid.toString());\n\n    // Retrieve content from IPFS\n    const retrievedData = await ipfs.cat(addResult.cid.toString());\n    console.log('Retrieved content:', retrievedData.toString());\n\n    // Example of using MFS (Mutable File System) commands\n    const mfsPath = '/my-directory/my-file.txt';\n    await ipfs.files.mkdir('/my-directory', { parents: true });\n    await ipfs.files.write(mfsPath, content, { create: true });\n    console.log(`Wrote content to MFS path: ${mfsPath}`);\n\n    const mfsContent = await ipfs.files.read(mfsPath);\n    console.log('Content from MFS:', mfsContent.toString());\n\n  } catch (error) {\n    console.error('An error occurred:', error);\n    console.warn('Ensure your IPFS daemon is running and accessible at http://localhost:5001.');\n    console.warn('If in a browser, check CORS settings on your IPFS daemon.');\n  }\n}\n\nrunExample();","lang":"typescript","description":"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."},"warnings":[{"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.","message":"When 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.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Ensure your Node.js environment meets the minimum requirement of `Node.js >=10.0.0`. Upgrade Node.js to a supported LTS version.","message":"The 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.","severity":"breaking","affected_versions":"<=0.3.0"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":">=0.0.1"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":">=0.0.1"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","cause":"The IPFS daemon is rejecting requests from your web application's origin due to CORS security policies.","error":"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."},{"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.","cause":"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.","error":"Error: connect ECONNREFUSED 127.0.0.1:5001"},{"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.","cause":"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.","error":"TypeError: ipfs.add is not a function"}],"ecosystem":"npm","meta_description":null}