{"id":15673,"library":"kubo-rpc-client","title":"Kubo RPC Client","description":"The `kubo-rpc-client` package provides a JavaScript client library for interacting with the Kubo RPC API, allowing developers to programmatically control and query an IPFS Kubo node. It enables functionalities such as adding and retrieving data, managing pins, and interacting with the IPFS swarm. Currently at version 6.1.0, the library maintains a regular release cadence, incorporating new features like `provide.stat` and `pin.update`, and ensuring interoperability with recent Kubo versions (e.g., Kubo 0.38). It differentiates itself as the official client for Kubo's HTTP RPC API, offering a direct interface to the underlying IPFS daemon's capabilities, contrasting with higher-level IPFS client libraries that might embed or abstract away the RPC communication. It supports both Node.js (Current and Active LTS versions) and browser environments, providing a consistent API across platforms.","status":"active","version":"6.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/ipfs/js-kubo-rpc-client","tags":["javascript","http","http-client","ipfs","kubo","rpc","rpc-client","typescript"],"install":[{"cmd":"npm install kubo-rpc-client","lang":"bash","label":"npm"},{"cmd":"yarn add kubo-rpc-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add kubo-rpc-client","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const { create } = require('kubo-rpc-client')","symbol":"create","correct":"import { create } from 'kubo-rpc-client'"},{"note":"This is the TypeScript type for the client instance returned by `create`. It is useful for strong typing when working with the API.","symbol":"IPFSClient","correct":"import type { IPFSClient } from 'kubo-rpc-client'"},{"note":"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.","wrong":"import { KuboRpcClient } from 'kubo-rpc-client'","symbol":"KuboRpcClient","correct":"<!-- In browser HTML --> <script src=\"https://unpkg.com/kubo-rpc-client/dist/index.min.js\"></script> <!-- Then use global --> KuboRpcClient.create()"}],"quickstart":{"code":"import { create } from 'kubo-rpc-client'\n\nasync function run() {\n  try {\n    // Connect to the local Kubo RPC API (default: http://localhost:5001)\n    const client = create({\n      url: process.env.IPFS_API_URL ?? 'http://localhost:5001/api/v0'\n    })\n\n    // Get the IPFS node ID\n    const { id, agentVersion, protocolVersion } = await client.id()\n    console.log('Connected to IPFS node:')\n    console.log(`  ID: ${id}`)\n    console.log(`  Agent Version: ${agentVersion}`)\n    console.log(`  Protocol Version: ${protocolVersion}`)\n\n    // Add a simple string to IPFS\n    const data = 'Hello from kubo-rpc-client!'\n    const result = await client.add(data)\n    console.log(`Added data to IPFS: ${result.path}`)\n    console.log(`Content ID (CID): ${result.cid}`)\n\n    // Retrieve the data by its CID\n    const retrievedBytes = client.cat(result.path)\n    let retrievedData = ''\n    for await (const chunk of retrievedBytes) {\n      retrievedData += new TextDecoder().decode(chunk)\n    }\n    console.log(`Retrieved data: \"${retrievedData}\" (CID: ${result.cid})`)\n\n  } catch (error) {\n    console.error('Error interacting with IPFS:', error)\n  }\n}\n\nrun()","lang":"typescript","description":"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)."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=6.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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()`.","cause":"The Kubo IPFS daemon is not running or is not accessible at the specified address and port.","error":"Error: connect ECONNREFUSED 127.0.0.1:5001"},{"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.","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).","error":"ReferenceError: require is not defined in ES module scope"},{"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.","cause":"The `create` function did not successfully return a client instance, or the client instance is not correctly typed/handled.","error":"TypeError: client.add is not a function"}],"ecosystem":"npm"}