Kinto HTTP Client

5.3.0 verified Sat Apr 25 auth: no javascript

JavaScript HTTP client for the Kinto API (current stable version 5.3.0). Maintained by the Kinto team, with releases on a monthly cadence. Full rewrite in TypeScript since v5.0.0. Supports Node.js >=10 and modern browsers. Key differentiators: provides both high-level bucket/collection classes and lower-level batch/pagination utilities; offers pluggable fetch and event systems; ships TypeScript definitions and supports CommonJS and ESM. Requires peer dependencies node-fetch, form-data, and atob.

Common errors

error Cannot find module 'node-fetch' ↓

cause Peer dependency missing; node-fetch is required for Node.js but not installed automatically.

fix

npm install node-fetch

error TypeError: client.fetchServerInfo is not a function ↓

cause Using a constructor that returns a deprecated version of the client or using an old import pattern.

fix

Ensure you are using named import: import { KintoClient } from 'kinto-http' and instantiate with new KintoClient(...).

error Uncaught ReferenceError: atob is not defined ↓

cause atob is not available in Node.js; atob peer dependency is missing.

fix

npm install atob

error Error: Invalid version: 'v1' ↓

cause The API version is specified incorrectly; Kinto expects a version segment in the URL (e.g., /v1).

fix

Ensure the server URL ends with '/v1' or the correct API version.

Warnings

breaking Full rewrite in TypeScript; EventEmitter replaced with interface and made optional. ↓

fix Refer to v5 migration guide: replace EventEmitter usage with custom event interface or omit.

breaking Removed support for Total-Records header on GET; use listRecords with totalRecords? instead. ↓

fix Use options such as { query: { _limit: someNumber } } to control pagination.

deprecated Basic authentication via `Authorization: Basic ...` header with atob/btoa deprecated; prefer OAuth Bearer tokens. ↓

fix Use headers: { Authorization: 'Bearer <token>' } instead.

gotcha Peer dependencies (node-fetch, form-data, atob) must be installed manually; not included automatically. ↓

fix Run: npm install node-fetch form-data atob

gotcha In browsers, native fetch is used; node-fetch is not required but may be polyfilled if used in test environments. ↓

fix Ensure node-fetch is installed only for Node.js; no need in browser.

gotcha The safe option (safe: true) for create/update/delete operations may fail if the server does not support ETags properly; handle errors gracefully. ↓

fix Wrap operations in try-catch and check error types.

Install

npm install kinto-http

yarn add kinto-http

pnpm add kinto-http

Imports

KintoClient

wrong

import KintoClient from 'kinto-http'

correct

import { KintoClient } from 'kinto-http'

Default export not available; named import only.

Bucket
```
import { Bucket } from 'kinto-http'
```
High-level Bucket class for bucket operations.
Collection
```
import { Collection } from 'kinto-http'
```
High-level Collection class for collection operations.

SUPPORTED_PROTOCOL_VERSION

wrong

const SUPPORTED_PROTOCOL_VERSION = require('kinto-http').SUPPORTED_PROTOCOL_VERSION

correct

import { SUPPORTED_PROTOCOL_VERSION } from 'kinto-http'

Exported constant; available as named export since v5.

KintoClient (CommonJS)

wrong

const KintoClient = require('kinto-http')

correct

const { KintoClient } = require('kinto-http')

CJS users must destructure named exports.

Quickstart

Shows how to initialize a Kinto client, create a bucket/collection, and perform CRUD operations.

import { KintoClient } from 'kinto-http';

const client = new KintoClient('https://kinto.dev.mozaws.net/v1', {
  headers: { Authorization: 'Basic ' + btoa('user:pass') }
});

async function main() {
  const serverInfo = await client.fetchServerInfo();
  console.log('Server:', serverInfo);

  const bucket = client.bucket('default');
  const collection = bucket.collection('tasks');

  // Create a record
  const { data } = await collection.createRecord({ title: 'Buy milk', done: false });
  console.log('Created record:', data.id);

  // List records
  const { data: records } = await collection.listRecords();
  console.log('Records:', records);

  // Update
  await collection.updateRecord({ ...data, title: 'Buy almond milk' });

  // Delete
  await collection.deleteRecord(data.id);
}

main().catch(console.error);