Skip to main content
Get up and running with Komga SDK in under 5 minutes.

​
Prerequisites

Komga server running and accessible (local or remote)
Node.js 18+ or a modern browser environment
Valid credentials (username/password or API key)

​
Install

bun add komga-sdk

​
Create a client

1

Import and configure

import { createKomgaClient } from 'komga-sdk';

const client = createKomgaClient({
  baseUrl: 'http://localhost:25600',
  auth: {
    type: 'basic',
    username: 'admin@example.com',
    password: 'your-password',
  },
  timeout: 30000,
  retry: { limit: 3 },
});
2

Use a domain service

import { LibraryService } from 'komga-sdk';

const libraryService = new LibraryService(client);
const libraries = await libraryService.getAll();

console.log('Your libraries:');
libraries.forEach(lib => console.log(`- ${lib.name}`));
Replace localhost:25600 with your Komga server address if running remotely.

​
Complete example

Here’s a full working example:
index.ts
import { createKomgaClient, BookService, SeriesService, LibraryService } from 'komga-sdk';

// 1. Create the client
const client = createKomgaClient({
  baseUrl: 'http://localhost:25600',
  auth: {
    type: 'basic',
    username: 'admin@example.com',
    password: 'your-password',
  },
});

// 2. Initialize services
const bookService = new BookService(client);
const seriesService = new SeriesService(client);
const libraryService = new LibraryService(client);

// 3. Fetch data
async function main() {
  // List libraries
  const libraries = await libraryService.getAll();
  console.log(`Found ${libraries.length} libraries`);

  // List recent books
  const books = await bookService.list({ 
    page: 0, 
    size: 10,
    sort: ['created,desc'] 
  });
  console.log(`Found ${books.totalElements} total books`);
  
  // Show first book details
  if (books.content.length > 0) {
    const firstBook = books.content[0];
    console.log(`Latest book: ${firstBook.metadata.title}`);
  }
}

main().catch(console.error);

​
Verify it works

Run your script: 
bun run index.ts
You should see output like: 
Found 3 libraries
Found 1247 total books
Latest book: One Piece Vol. 1
If you get authentication errors, double-check your credentials. See Troubleshooting for common issues.

​
What’s next?

Authentication

Learn about API keys, Bearer tokens, and security best practices.

Books Guide

List, search, and manage books in your library.

Pagination

Handle large datasets with pagination and sorting.

Error Handling

Gracefully handle API and validation errors.