IPFS HTTP Client Lite

Common errors

• 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.

  cause 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

  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.
  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

  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.
  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.

Warnings

• gotcha 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.
  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.
• breaking 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.
  Fix: Ensure your Node.js environment meets the minimum requirement of `Node.js >=10.0.0`. Upgrade Node.js to a supported LTS version.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install ipfs-http-client-lite npm
• yarn add ipfs-http-client-lite yarn
• pnpm add ipfs-http-client-lite pnpm

Imports

• IpfsHttpClientLite
  wrong:

  const IpfsHttpClientLite = require('ipfs-http-client-lite')

  correct:

  import IpfsHttpClientLite from '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
  wrong:

  const cat = require('ipfs-http-client-lite').cat

  correct:

  import cat from 'ipfs-http-client-lite/src/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.

Quickstart

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();