Quickstart

Install komga-sdk and make a request against a Komga server.

Prerequisites

A Komga server that is reachable from your application. The default local server URL is http://localhost:25600.

Node.js 18 or newer, a modern browser, or another runtime with Fetch, Web Crypto, Headers, Request, and Response APIs.

A Komga username and password or an API key, unless your application supplies its own session headers.

Install

npm
pnpm
yarn
bun

npm install komga-sdk

pnpm add komga-sdk

yarn add komga-sdk

bun add komga-sdk

The package is ESM. In a TypeScript project, use a current ESM-capable runtime or compile with moduleResolution: "bundler"; TypeScript reference includes a minimal configuration.

Configure environment variables

Keep the server URL and credentials out of source control:

.env

KOMGA_URL=http://localhost:25600
KOMGA_USER=admin@example.com
KOMGA_PASSWORD=replace-me
# Or use KOMGA_API_KEY instead of the Basic credentials.
KOMGA_API_KEY=replace-me

Load these values through your runtime’s environment mechanism. Do not expose a long-lived API key or Basic password in a browser bundle; create a server-side boundary when the browser must access a private Komga server.

Create a client

createKomgaClient requires a baseUrl. Authentication is optional:

import { createKomgaClient } from 'komga-sdk';

export const client = createKomgaClient({
  baseUrl: process.env.KOMGA_URL ?? 'http://localhost:25600',
  auth: {
    type: 'basic',
    username: process.env.KOMGA_USER!,
    password: process.env.KOMGA_PASSWORD!,
  },
});

For a production integration, prefer https:// whenever credentials leave the local machine. The client uses native Fetch and does not configure retries, timeouts, caching, or response validation. Add those concerns in your application or through a custom Fetch implementation when you need them.

Make your first request

Generated operation parameters are flat. The client is passed in the optional second argument:

index.ts

import { getLibraries } from 'komga-sdk';
import { client } from './lib/komga.js';

const result = await getLibraries({ client });

if (result.error) {
  console.error('Komga request failed', result.response?.status, result.error);
} else {
  for (const library of result.data ?? []) {
    console.log(`${library.id}: ${library.name}`);
  }
}

A generated request resolves to { data, error, request, response } by default. It does not throw for an HTTP error. Check error before reading data; response can be absent for a network or request-construction failure.

Query a paginated endpoint

getBooks requires a bookSearch object and accepts pagination values in the same flat parameter object:

import { getBooks } from 'komga-sdk';
import { client } from './lib/komga.js';

const result = await getBooks(
  {
    page: 0,
    size: 20,
    sort: ['metadata.title,asc'],
    bookSearch: { fullTextSearch: 'manga' },
  },
  { client },
);

if (result.error === undefined) {
  console.log(`Found ${result.data.totalElements ?? 0} books`);
  for (const book of result.data.content ?? []) {
    console.log(book.metadata.title);
  }
}

Browser session example

A browser application that already has a Komga session cookie can ask Fetch to include it:

import { createKomgaClient, getCurrentUser } from 'komga-sdk';

const browserClient = createKomgaClient({
  baseUrl: 'https://komga.example.com',
  credentials: 'include',
});

const session = await getCurrentUser({ 'remember-me': true }, { client: browserClient });
if (session.error) {
  console.error('Session is not available', session.response?.status);
}

The SDK does not implement a login page or token exchange. For cross-origin requests, Komga and the browser must agree on an allowed origin and credentialed CORS policy.

Use `unwrap` when you want exceptions

unwrap is the explicit throwing boundary. It returns generated data or throws KomgaApiError:

import { KomgaApiError, getBookById, unwrap } from 'komga-sdk';

try {
  const book = unwrap(await getBookById({ bookId: 'book-123' }, { client }));
  console.log(book.metadata.title);
} catch (error) {
  if (error instanceof KomgaApiError && error.status === 404) {
    console.log('Book not found');
  } else {
    throw error;
  }
}

Run the example

npx tsx index.ts

bun run index.ts

Replace http://localhost:25600 with the URL of your Komga server. Keep credentials in environment variables or a secrets manager rather than source code.

What’s next?

Authentication

Configure Basic Auth, API keys, custom headers, sessions, and browser credentials.

Quick reference

Review flat operation signatures, result handling, and pagination.

Best practices

Decide where to add application-owned retries, caching, and validation.

Get started

Core SDK

API guides

Reference

Prerequisites

Install

Configure environment variables

Create a client

Make your first request

Query a paginated endpoint

Browser session example

Use `unwrap` when you want exceptions

Run the example

What’s next?

Authentication

Quick reference

Best practices

​Prerequisites

​Install

​Configure environment variables

​Create a client

​Make your first request

​Query a paginated endpoint

​Browser session example

​Use unwrap when you want exceptions

​Run the example

​What’s next?

Authentication

Quick reference

Best practices

Prerequisites

Install

Configure environment variables

Create a client

Make your first request

Query a paginated endpoint

Browser session example

Use `unwrap` when you want exceptions

Run the example

What’s next?