Registry / http-networking / kubo-rpc-client

kubo-rpc-client

library6.1.0jsnpmunverified

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.

http-networking data

npm install kubo-rpc-client

github ↗package ↗

INSTALL

IMPORT

SIG · KUBO-RPC-CLIENT

kubo-rpc-client

http-networkingjavascriptv6.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

create

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

✗ const { create } = require('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

✓  <script src="https://unpkg.com/kubo-rpc-client/dist/index.min.js"></script>  KuboRpcClient.create()

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

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.

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

Debug

Known issues

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

affects: >=6.0.0

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

affects: >=1.0.0

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

affects: >=1.0.0

Errors

Common errors & fixes

Error: connect ECONNREFUSED 127.0.0.1:5001

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

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

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.

Upgrade

Version history

6.1.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/ipfs/js-kubo-rpc-client ↗

packagehttps://www.npmjs.com/package/kubo-rpc-client ↗