Quickstart

Get started with Shamela in minutes

API Key Required: You need a valid Shamela API key before proceeding.

Request your API key by emailing [e-mail].

Configuration

Before using the library, configure it with your API credentials and endpoint URLs.

Standard Node.js

For non-bundled Node.js environments, the WASM file is auto-detected:

import { configure, getBook } from 'shamela';

// Configure API credentials
configure({
  apiKey: process.env.SHAMELA_API_KEY,
  booksEndpoint: process.env.SHAMELA_BOOKS_ENDPOINT,
  masterPatchEndpoint: process.env.SHAMELA_MASTER_ENDPOINT,
  // sqlJsWasmUrl is auto-detected in standard Node.js
});

Next.js / Bundled Environments

For Next.js, webpack, Turbopack, and other bundlers, you must explicitly configure the WASM file path.

1. Update next.config.ts

   Add the required external packages:

   import type { NextConfig } from 'next';
   
   const nextConfig: NextConfig = {
     serverExternalPackages: ['shamela', 'sql.js'],
     // ... rest of your config
   };
   
   export default nextConfig;
   
2. Create a server-only configuration file

   Create lib/shamela-server.ts:

   import { configure } from 'shamela';
   import { join } from 'node:path';
   
   configure({
     sqlJsWasmUrl: join(process.cwd(), 'node_modules', 'sql.js', 'dist', 'sql-wasm.wasm'),
     apiKey: process.env.SHAMELA_API_KEY,
     booksEndpoint: process.env.SHAMELA_BOOKS_ENDPOINT,
     masterPatchEndpoint: process.env.SHAMELA_MASTER_ENDPOINT,
   });
   
   export { downloadBook, getBook, getBookMetadata, getMaster, downloadMasterDatabase } from 'shamela';
   
3. Use in Server Actions

   Import from your configuration file in server-side code:

   'use server';
   
   import { getBookMetadata, downloadBook } from '@/lib/shamela-server';
   
   export async function downloadBookAction(bookId: number) {
     const metadata = await getBookMetadata(bookId);
     return await downloadBook(bookId, {
       bookMetadata: metadata,
       outputFile: { path: `./books/${bookId}.db` }
     });
   }
   

   Only import shamela in server-side code (Server Actions, API Routes, or Server Components). Never import in client components or layout.tsx.

Browser Environments

In browsers, the library automatically uses a CDN-hosted WASM file:

import { configure, getBook } from 'shamela';

configure({
  apiKey: 'your-api-key',
  booksEndpoint: 'https://shamela.ws/api/books',
  masterPatchEndpoint: 'https://shamela.ws/api/master_patch',
  // Automatically uses CDN: https://cdn.jsdelivr.net/npm/sql.js@1.13.0/dist/sql-wasm.wasm
});

Your first API call

Once configured, you can start using the Shamela API.

Download a book

Download a complete book with all pages and titles:

import { getBook } from 'shamela';

const book = await getBook(26592);

console.log(`Downloaded book with ${book.pages.length} pages`);
console.log(`Table of contents has ${book.titles.length} entries`);

// Access page content
const firstPage = book.pages[0];
console.log(firstPage.content);

Get master database

Retrieve the complete library catalog with all books, authors, and categories:

import { getMaster } from 'shamela';

const master = await getMaster();

console.log(`Version: ${master.version}`);
console.log(`Total books: ${master.books.length}`);
console.log(`Total authors: ${master.authors.length}`);
console.log(`Total categories: ${master.categories.length}`);

Download to file

Export books or master data to JSON or SQLite files:

import { downloadBook, downloadMasterDatabase } from 'shamela';

// Download book as JSON
await downloadBook(26592, {
  outputFile: { path: './book.json' }
});

// Download book as SQLite database
await downloadBook(26592, {
  outputFile: { path: './book.db' }
});

// Download master database
await downloadMasterDatabase({
  outputFile: { path: './master.db' }
});

Content processing

For client-side or lightweight use cases where you only need content utilities without database functionality, use the shamela/content export:

import {
  mapPageCharacterContent,
  splitPageBodyFromFooter,
  removeTagsExceptSpan,
  htmlToMarkdown,
} from 'shamela/content';

// Process content without loading sql.js (~1.5KB gzipped vs ~900KB)
const normalized = mapPageCharacterContent(rawContent);
const cleaned = removeTagsExceptSpan(normalized);
const [body, footnotes] = splitPageBodyFromFooter(cleaned);
const markdown = htmlToMarkdown(body);

The shamela/content export is ideal for React/Next.js client components where you want to process pre-downloaded book data without loading the full sql.js WASM bundle.

Next steps

Explore the API reference to learn about all available functions:

Configuration

Learn about configuration options and environment variables

Metadata & Downloads

Download books and master databases

Content Utilities

Process and transform Arabic book content

Data Structures

Understand the data types returned by the API