Kubo RPC Client

Common errors

• Error: connect ECONNREFUSED 127.0.0.1:5001

  cause The Kubo IPFS daemon is not running or is not accessible at the specified address and port.
  fix Start your IPFS Kubo daemon (e.g., `ipfs daemon`) and ensure its API address matches the `url` option provided to `kubo-rpc-client.create()`.

• ReferenceError: require is not defined in ES module scope

  cause Attempting to use CommonJS `require()` syntax in a JavaScript module that is treated as an ES module (e.g., in a package with `"type": "module"` or a `.mjs` file).
  fix Refactor your imports to use ES module syntax: `import { create } from 'kubo-rpc-client'`. If running in Node.js, ensure your environment supports ESM, or configure your project to transpile to CJS if necessary.

• TypeError: client.add is not a function

  cause The `create` function did not successfully return a client instance, or the client instance is not correctly typed/handled.
  fix Verify that the `create` call is not throwing an error and that `client` is indeed the object returned by `create`. Ensure you are using `await` with `client.add()` and other async operations, as they return Promises.

Warnings

• breaking Version 6.0.0 introduced breaking changes related to its internal dependencies. It now requires compatibility with the latest versions of `@libp2p/*` and `@multiformats/multiaddr` packages.
  Fix: Ensure that your project's dependencies for `@libp2p/*` and `@multiformats/multiaddr` are updated to their latest compatible versions when upgrading to `kubo-rpc-client@6.0.0` or higher.
• gotcha The `create` function defaults to `http://localhost:5001/api/v0`. If your Kubo node is running on a different address or port, or is not running at all, the client will fail to connect.
  Fix: Always specify the correct `url` option to `create({ url: '...' })` if your Kubo node is not at the default address. Ensure your Kubo daemon is running and accessible from where your client code is executed.
• gotcha When running `kubo-rpc-client` in a browser environment, be aware of browser security policies (e.g., CORS). Direct connections to a local Kubo RPC API might be blocked if the client is served from a different origin.
  Fix: Configure your Kubo node with appropriate CORS headers (`ipfs config --json API.HTTPHeaders.Access-Control-Allow-Origin '["http://your-app-domain.com"]'`) or use a proxy server to route requests if cross-origin access is required.

Install

• npm install kubo-rpc-client npm
• yarn add kubo-rpc-client yarn
• pnpm add kubo-rpc-client pnpm

Imports

• create
  wrong:

  const { create } = require('kubo-rpc-client')

  correct:

  import { create } from 'kubo-rpc-client'

  While CommonJS `require` might work in older Node.js versions or with transpilation, `kubo-rpc-client` is primarily designed for ESM. Use `import` for modern Node.js and browser build systems.
• IPFSClient

  import type { IPFSClient } from 'kubo-rpc-client'

  This is the TypeScript type for the client instance returned by `create`. It is useful for strong typing when working with the API.
• KuboRpcClient
  wrong:

  import { KuboRpcClient } from 'kubo-rpc-client'

  correct:

  <!-- In browser HTML --> <script src="https://unpkg.com/kubo-rpc-client/dist/index.min.js"></script> <!-- Then use global --> KuboRpcClient.create()

  When loaded via a script tag in the browser, the exports are available under the global `KuboRpcClient` object. It is not directly importable as a named export from the package for module usage.

Quickstart

Demonstrates how to initialize the Kubo RPC client, retrieve the IPFS node ID, add a string to IPFS, and then retrieve it by its Content ID (CID).

import { create } from 'kubo-rpc-client'

async function run() {
  try {
    // Connect to the local Kubo RPC API (default: http://localhost:5001)
    const client = create({
      url: process.env.IPFS_API_URL ?? 'http://localhost:5001/api/v0'
    })

    // Get the IPFS node ID
    const { id, agentVersion, protocolVersion } = await client.id()
    console.log('Connected to IPFS node:')
    console.log(`  ID: ${id}`)
    console.log(`  Agent Version: ${agentVersion}`)
    console.log(`  Protocol Version: ${protocolVersion}`)

    // Add a simple string to IPFS
    const data = 'Hello from kubo-rpc-client!'
    const result = await client.add(data)
    console.log(`Added data to IPFS: ${result.path}`)
    console.log(`Content ID (CID): ${result.cid}`)

    // Retrieve the data by its CID
    const retrievedBytes = client.cat(result.path)
    let retrievedData = ''
    for await (const chunk of retrievedBytes) {
      retrievedData += new TextDecoder().decode(chunk)
    }
    console.log(`Retrieved data: "${retrievedData}" (CID: ${result.cid})`)

  } catch (error) {
    console.error('Error interacting with IPFS:', error)
  }
}

run()