Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ragaeeb/shamela/llms.txt

Use this file to discover all available pages before exploring further.

API Key Required: You need a valid Shamela API key before proceeding.Request your API key by emailing mail@shamela.ws.

​
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

Build docs developers (and LLMs) love

Get started for freeTalk to us