shamela 1.3.0 → 1.3.2

package/README.md

@@ -18,115 +18,137 @@ A universal TypeScript library for accessing and downloading Maktabah Shamela v4
 ## Table of Contents
 
 - [Installation](#installation)
-- [Environment Variables](#environment-variables)
-- [Usage](#usage)
-    - [Getting Started](#getting-started)
-    - [API Functions](#api-functions)
-        - [getMasterMetadata](#getmastermetadata)
-        - [downloadMasterDatabase](#downloadmasterdatabase)
-        - [getBookMetadata](#getbookmetadata)
-        - [downloadBook](#downloadbook)
-        - [getBook](#getbook)
-        - [getMaster](#getmaster)
-        - [getCoverUrl](#getcoverurl)
+- [Quick Start](#quick-start)
+  - [Standard Node.js](#standard-nodejs)
+  - [Next.js / Bundled Environments](#nextjs--bundled-environments)
+  - [Browser](#browser)
+- [API Reference](#api-reference)
+  - [getMasterMetadata](#getmastermetadata)
+  - [downloadMasterDatabase](#downloadmasterdatabase)
+  - [getBookMetadata](#getbookmetadata)
+  - [downloadBook](#downloadbook)
+  - [getBook](#getbook)
+  - [getMaster](#getmaster)
+  - [getCoverUrl](#getcoverurl)
 - [Examples](#examples)
-    - [Downloading the Master Database](#downloading-the-master-database)
-    - [Downloading a Book](#downloading-a-book)
-    - [Retrieving Book Data](#retrieving-book-data)
-    - [Retrieving Master Data in memory](#retrieving-master-data-in-memory)
 - [Data Structures](#data-structures)
-- [Next.js demo](#nextjs-demo)
+- [Next.js Demo](#nextjs-demo)
+- [Troubleshooting](#troubleshooting)
 - [Testing](#testing)
 - [License](#license)
 
 ## Installation
 
 ```bash
-bun add shamela
+npm install shamela
 ```
 
-or
-
 ```bash
-npm install shamela
+bun add shamela
 ```
 
-or
-
 ```bash
 yarn add shamela
 ```
 
-or
-
 ```bash
 pnpm install shamela
 ```
 
-## Environment Variables
+## Quick Start
+
+### Standard Node.js
 
-Before using the library, you need to set up some environment variables for API keys and endpoints:
+For simple Node.js scripts (non-bundled environments), the library auto-detects the WASM file:
 
-- `SHAMELA_API_KEY`: Your API key for accessing the Shamela API.
-- `SHAMELA_API_MASTER_PATCH_ENDPOINT`: The endpoint URL for the master database patches.
-- `SHAMELA_API_BOOKS_ENDPOINT`: The base endpoint URL for book-related API calls.
-- `SHAMELA_SQLJS_WASM_URL` (optional): Override the default CDN URL used to load the `sql.js` WebAssembly binary when running in the browser.
+```typescript
+import { configure, getBook } from 'shamela';
 
-You can set these variables in a `.env` file at the root of your project:
+// 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
+});
 
-```dotenv
-SHAMELA_API_KEY=your_api_key_here
-SHAMELA_API_MASTER_PATCH_ENDPOINT=https://shamela.ws/api/master_patch
-SHAMELA_API_BOOKS_ENDPOINT=https://shamela.ws/api/books
-# Optional when you host sql-wasm.wasm yourself
-# SHAMELA_SQLJS_WASM_URL=https://example.com/sql-wasm.wasm
+// Use the library
+const book = await getBook(26592);
+console.log(`Downloaded book with ${book.pages.length} pages`);
 ```
 
-### Runtime configuration (browsers and serverless)
+### Next.js / Bundled Environments
+
+For Next.js, webpack, Turbopack, and other bundlers, you need to explicitly configure the WASM file path.
 
-When you cannot rely on environment variables—such as when running inside a browser, an edge worker, or a serverless function—use the `configure` helper to provide credentials at runtime:
+**1. Update `next.config.ts` or `next.config.js`:**
 
-```ts
+```typescript
+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:**
+
+```typescript
+// lib/shamela-server.ts
 import { configure } from 'shamela';
+import { join } from 'node:path';
 
 configure({
-    apiKey: process.env.NEXT_PUBLIC_SHAMELA_KEY,
-    booksEndpoint: 'https://shamela.ws/api/books',
-    masterPatchEndpoint: 'https://shamela.ws/api/master_patch',
-    // Optional: host sql-wasm.wasm yourself to control caching/CDN placement
-    sqlJsWasmUrl: '/assets/sql-wasm.wasm',
-    // Optional: integrate with your application's logging system
-    logger: console,
-    // Optional: provide a custom fetch implementation (for tests or SSR)
-    fetchImplementation: fetch,
+  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:**
+
+```typescript
+'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` }
+  });
+}
 ```
 
-You can call `configure` multiple times—values are merged, so later calls update only the keys you pass in.
+**Important:** Only import `shamela` in server-side code (Server Actions, API Routes, or Server Components). Never import in client components or `layout.tsx`.
 
-The optional `logger` must expose `debug`, `info`, `warn`, and `error` methods. When omitted, the library stays silent by default.
+### Browser
 
-## Usage
+In browsers, the library automatically uses a CDN-hosted WASM file:
 
-### Getting Started
+```typescript
+import { configure, getBook } from 'shamela';
 
-First, import the library functions into your project:
+configure({
+  apiKey: 'your-api-key',
+  booksEndpoint: 'https://SHAMELA_INSTANCE.ws/api/books',
+  masterPatchEndpoint: 'https://SHAMELA_INSTANCE.ws/api/master_patch',
+  // Automatically uses CDN: https://cdn.jsdelivr.net/npm/sql.js@1.13.0/dist/sql-wasm.wasm
+});
 
-```javascript
-import {
-    getMasterMetadata,
-    downloadMasterDatabase,
-    getBookMetadata,
-    downloadBook,
-    getBook,
-    getMaster,
-    getCoverUrl,
-} from 'shamela';
+const book = await getBook(26592);
 ```
 
-### API Functions
+## API Reference
 
-#### getMasterMetadata
+### getMasterMetadata
 
 Fetches metadata for the master database.
 
@@ -134,57 +156,49 @@ Fetches metadata for the master database.
 getMasterMetadata(version?: number): Promise<GetMasterMetadataResponsePayload>
 ```
 
-- `version` (optional): The version number of the master database you want to check for updates (defaults to 0)
+- `version` (optional): The version number to check for updates (defaults to 0)
 
-**Returns:** Promise that resolves to master database metadata including download URL and version
+**Returns:** Promise resolving to master database metadata including download URL and version
 
 **Example:**
 
-```javascript
-const masterMetadata = await getMasterMetadata();
-console.log(masterMetadata.url); // Download URL for master database patch
-console.log(masterMetadata.version); // Latest version number
+```typescript
+const metadata = await getMasterMetadata();
+console.log(metadata.url);     // Download URL
+console.log(metadata.version); // Version number
 
 // Check for updates from a specific version
 const updates = await getMasterMetadata(5);
 ```
 
-#### downloadMasterDatabase
+### downloadMasterDatabase
 
-Downloads the master database and saves it to a specified path. The master database contains comprehensive information about all books, authors, and categories available in the Shamela library.
+Downloads the master database containing all books, authors, and categories.
 
 ```typescript
 downloadMasterDatabase(options: DownloadMasterOptions): Promise<string>
 ```
 
-- `options`: Configuration object containing:
-    - `masterMetadata` (optional): Pre-fetched metadata from `getMasterMetadata`
-    - `outputFile`: Object with `path` property specifying the output file path
+- `options.masterMetadata` (optional): Pre-fetched metadata
+- `options.outputFile.path`: Output file path (`.db`, `.sqlite`, or `.json`)
 
-**Returns:** Promise that resolves to the path of the created output file
+**Returns:** Promise resolving to the output file path
 
 **Example:**
 
-```javascript
+```typescript
 // Download as SQLite database
 await downloadMasterDatabase({
-    outputFile: { path: './master.db' },
+  outputFile: { path: './master.db' }
 });
 
 // Download as JSON
 await downloadMasterDatabase({
-    outputFile: { path: './master.json' },
-});
-
-// Use pre-fetched metadata for efficiency
-const masterMetadata = await getMasterMetadata();
-await downloadMasterDatabase({
-    masterMetadata,
-    outputFile: { path: './master.db' },
+  outputFile: { path: './master.json' }
 });
 ```
 
-#### getBookMetadata
+### getBookMetadata
 
 Fetches metadata for a specific book.
 
@@ -192,105 +206,90 @@ Fetches metadata for a specific book.
 getBookMetadata(id: number, options?: GetBookMetadataOptions): Promise<GetBookMetadataResponsePayload>
 ```
 
-- `id`: The unique identifier of the book
-- `options` (optional): Configuration object containing:
-    - `majorVersion`: The major version to check against
-    - `minorVersion`: The minor version to check against
+- `id`: Book identifier
+- `options.majorVersion` (optional): Major version to check
+- `options.minorVersion` (optional): Minor version to check
 
-**Returns:** Promise that resolves to book metadata including release URLs and versions
+**Returns:** Promise resolving to book metadata
 
 **Example:**
 
-```javascript
+```typescript
 const metadata = await getBookMetadata(26592);
-console.log(metadata.majorReleaseUrl); // URL for downloading the book
-console.log(metadata.majorRelease); // Major version number
-
-// Check specific versions
-const versionedMetadata = await getBookMetadata(26592, {
-    majorVersion: 1,
-    minorVersion: 2,
-});
+console.log(metadata.majorReleaseUrl);
+console.log(metadata.minorReleaseUrl);
 ```
 
-#### downloadBook
+### downloadBook
 
-Downloads and processes a book from the Shamela database. This function downloads the book's database files, applies patches if available, and exports the data to the specified format.
+Downloads and processes a book from Shamela.
 
 ```typescript
 downloadBook(id: number, options: DownloadBookOptions): Promise<string>
 ```
 
-- `id`: The unique identifier of the book to download
-- `options`: Configuration object containing:
-    - `bookMetadata` (optional): Pre-fetched metadata from `getBookMetadata`
-    - `outputFile`: Object with `path` property specifying the output file path
+- `id`: Book identifier
+- `options.bookMetadata` (optional): Pre-fetched metadata
+- `options.outputFile.path`: Output file path (`.db`, `.sqlite`, or `.json`)
 
-**Returns:** Promise that resolves to the path of the created output file
+**Returns:** Promise resolving to the output file path
 
 **Example:**
 
-```javascript
+```typescript
 // Download as JSON
 await downloadBook(26592, {
-    outputFile: { path: './book.json' },
-});
-
-// Download as SQLite database
-await downloadBook(26592, {
-    outputFile: { path: './book.db' },
+  outputFile: { path: './book.json' }
 });
 
-// Use pre-fetched metadata for efficiency
-const bookMetadata = await getBookMetadata(26592);
+// Download as SQLite
 await downloadBook(26592, {
-    bookMetadata,
-    outputFile: { path: './book.db' },
+  outputFile: { path: './book.db' }
 });
 ```
 
-#### getBook
+### getBook
 
-Retrieves complete book data as a JavaScript object. This is a convenience function that handles temporary file creation and cleanup automatically.
+Retrieves complete book data as a JavaScript object.
 
 ```typescript
 getBook(id: number): Promise<BookData>
 ```
 
-- `id`: The unique identifier of the book to retrieve
+- `id`: Book identifier
 
-**Returns:** Promise that resolves to complete book data including pages and titles
+**Returns:** Promise resolving to book data with pages and titles
 
 **Example:**
 
-```javascript
-const bookData = await getBook(26592);
-console.log(bookData.pages.length); // Number of pages in the book
-console.log(bookData.titles?.length); // Number of title entries
-console.log(bookData.pages[0].content); // Content of the first page
+```typescript
+const book = await getBook(26592);
+console.log(book.pages.length);
+console.log(book.titles?.length);
+console.log(book.pages[0].content);
 ```
 
-#### getMaster
+### getMaster
 
-Retrieves the entire master dataset (authors, books, categories) as a JavaScript object, including the version number that the
-API reports for the snapshot.
+Retrieves the entire master dataset as a JavaScript object.
 
 ```typescript
 getMaster(): Promise<MasterData>
 ```
 
-**Returns:** Promise that resolves to the complete master dataset with version metadata
+**Returns:** Promise resolving to master data with authors, books, categories, and version
 
 **Example:**
 
-```javascript
-const masterData = await getMaster();
-console.log(masterData.version); // Version of the downloaded master database
-console.log(masterData.books.length); // Number of books available
-console.log(masterData.categories.length); // Number of categories available
+```typescript
+const master = await getMaster();
+console.log(master.version);
+console.log(master.books.length);
+console.log(master.authors.length);
+console.log(master.categories.length);
 ```
 
-#### getCoverUrl
+### getCoverUrl
 
 Generates the URL for a book's cover image.
 
@@ -298,230 +297,223 @@ Generates the URL for a book's cover image.
 getCoverUrl(bookId: number): string
 ```
 
-- `bookId`: The unique identifier of the book
+- `bookId`: Book identifier
 
-**Returns:** The complete URL to the book's cover image
+**Returns:** Cover image URL
 
 **Example:**
 
-```javascript
+```typescript
 const coverUrl = getCoverUrl(26592);
-console.log(coverUrl); // "https://shamela.ws/covers/26592.jpg"
+// Returns: "https://shamela.ws/covers/26592.jpg"
 ```
 
 ## Examples
 
 ### Downloading the Master Database
 
-```javascript
+```typescript
 import { downloadMasterDatabase } from 'shamela';
 
-(async () => {
-    try {
-        // Download as SQLite database
-        const dbPath = await downloadMasterDatabase({
-            outputFile: { path: './shamela_master.db' },
-        });
-        console.log(`Master database downloaded to: ${dbPath}`);
-
-        // Download as JSON for programmatic access
-        const jsonPath = await downloadMasterDatabase({
-            outputFile: { path: './shamela_master.json' },
-        });
-        console.log(`Master data exported to: ${jsonPath}`);
-        console.log('The JSON file includes authors, books, categories, and the master version number.');
-    } catch (error) {
-        console.error('Error downloading master database:', error);
-    }
-})();
+// Download as SQLite
+const dbPath = await downloadMasterDatabase({
+  outputFile: { path: './shamela_master.db' }
+});
+console.log(`Downloaded to: ${dbPath}`);
+
+// Download as JSON
+const jsonPath = await downloadMasterDatabase({
+  outputFile: { path: './shamela_master.json' }
+});
 ```
 
 ### Downloading a Book
 
-```javascript
+```typescript
 import { downloadBook, getBookMetadata } from 'shamela';
 
-(async () => {
-    const bookId = 26592;
+const bookId = 26592;
 
-    try {
-        // Download book as database file
-        await downloadBook(bookId, {
-            outputFile: { path: `./book_${bookId}.db` },
-        });
+// Download book
+await downloadBook(bookId, {
+  outputFile: { path: `./book_${bookId}.db` }
+});
 
-        // Download with pre-fetched metadata
-        const metadata = await getBookMetadata(bookId);
-        await downloadBook(bookId, {
-            bookMetadata: metadata,
-            outputFile: { path: `./book_${bookId}.json` },
-        });
-    } catch (error) {
-        console.error('Error downloading book:', error);
-    }
-})();
+// With pre-fetched metadata
+const metadata = await getBookMetadata(bookId);
+await downloadBook(bookId, {
+  bookMetadata: metadata,
+  outputFile: { path: `./book_${bookId}.json` }
+});
 ```
 
 ### Retrieving Book Data
 
-```javascript
+```typescript
 import { getBook } from 'shamela';
 
-(async () => {
-    try {
-        const bookData = await getBook(26592);
-
-        console.log(`Book has ${bookData.pages.length} pages`);
-
-        if (bookData.titles) {
-            console.log(`Book has ${bookData.titles.length} titles/chapters`);
-
-            // Display table of contents
-            bookData.titles.forEach((title) => {
-                console.log(`${title.id}: ${title.content} (Page ${title.page})`);
-            });
-        }
-
-        // Access page content
-        const firstPage = bookData.pages[0];
-        console.log(`First page content: ${firstPage.content.substring(0, 100)}...`);
-    } catch (error) {
-        console.error('Error retrieving book:', error);
-    }
-})();
-```
-
-### Retrieving Master Data in memory
+const book = await getBook(26592);
 
-```javascript
-import { getMaster } from 'shamela';
+console.log(`Book has ${book.pages.length} pages`);
 
-(async () => {
-    try {
-        const masterData = await getMaster();
+// Display table of contents
+book.titles?.forEach(title => {
+  console.log(`${title.id}: ${title.content} (Page ${title.page})`);
+});
 
-        console.log(`Master snapshot version: ${masterData.version}`);
-        console.log(`Master dataset includes ${masterData.books.length} books`);
-        console.log(`Master dataset includes ${masterData.categories.length} categories`);
-    } catch (error) {
-        console.error('Error retrieving master data:', error);
-    }
-})();
+// Access page content
+const firstPage = book.pages[0];
+console.log(firstPage.content.substring(0, 100));
 ```
 
-### Getting Book Cover URLs
-
-```javascript
-import { getCoverUrl, downloadMasterDatabase } from 'shamela';
+### Getting Book Covers
 
-(async () => {
-    try {
-        // Download master data to get book information
-        const masterData = await downloadMasterDatabase({
-            outputFile: { path: './master.json' },
-        });
+```typescript
+import { getCoverUrl, getMaster } from 'shamela';
 
-        // Read the master data
-        const data = await Bun.file('./master.json').json();
+const master = await getMaster();
 
-        // Generate cover URLs for all books
-        data.books.forEach((book) => {
-            const coverUrl = getCoverUrl(book.id);
-            console.log(`${book.name}: ${coverUrl}`);
-        });
-    } catch (error) {
-        console.error('Error processing covers:', error);
-    }
-})();
+// Generate cover URLs for all books
+master.books.forEach(book => {
+  const coverUrl = getCoverUrl(book.id);
+  console.log(`${book.name}: ${coverUrl}`);
+});
 ```
 
 ## Data Structures
 
-The library provides comprehensive TypeScript types for all data structures:
-
 ### BookData
 
-- `pages`: Array of raw rows from the `page` table, including `content`, `id`, `part`, `page`, `number`, `services`, and `is_deleted`.
-- `titles`: Array of raw rows from the `title` table with `content`, `id`, `page`, `parent`, and `is_deleted`.
+```typescript
+type BookData = {
+  pages: Page[];
+  titles: Title[];
+};
+```
 
 ### MasterData
 
-- `authors`: Raw entries from the `author` table with the original `biography`, `death_text`, `death_number`, `is_deleted`, and `name` fields.
-- `books`: Raw entries from the `book` table containing the original metadata columns (`author`, `bibliography`, `category`, `date`, `hint`, `major_release`, `metadata`, `minor_release`, `pdf_links`, `printed`, `type`, and `is_deleted`).
-- `categories`: Raw entries from the `category` table including `is_deleted`, `order`, and `name`.
-- `version`: Version number reported by the Shamela API for the downloaded master database.
+```typescript
+type MasterData = {
+  authors: Author[];
+  books: Book[];
+  categories: Category[];
+  version: number;
+};
+```
 
 ### Page
 
-- `id`: Unique identifier.
-- `content`: Text content of the page.
-- `part`, `page`, `number`: Numeric references stored exactly as they appear in the source database.
-- `services`: Optional metadata column from the source database.
-- `is_deleted`: Flag indicating whether the page has been marked as deleted in Shamela updates.
+```typescript
+type Page = {
+  id: number;
+  content: string;
+  part?: string;
+  page?: number;
+  number?: string;
+};
+```
 
 ### Title
 
-- `id`: Unique identifier.
-- `content`: Title text.
-- `page`: Page number where title appears (if available).
-- `parent`: Optional parent title ID for hierarchical structure.
-- `is_deleted`: Flag indicating whether the title has been marked as deleted.
+```typescript
+type Title = {
+  id: number;
+  content: string;
+  page: number;
+  parent?: number;
+};
+```
+
+### Content Helpers
 
-### Content helpers
+- `parseContentRobust(content: string)`: Converts Shamela page HTML into structured lines
+- `sanitizePageContent(content: string)`: Removes footnote markers and normalizes text
+- `splitPageBodyFromFooter(content: string)`: Separates page content from footnotes
+- `removeArabicNumericPageMarkers(text: string)`: Removes Arabic page number markers
+- `removeTagsExceptSpan(content: string)`: Strips HTML tags except span elements
 
-- `parseContentRobust(content: string)`: Converts Shamela page HTML into a list of structured lines while preserving title markers and punctuation.
-- `sanitizePageContent(content: string)`: Removes common footnote markers and normalises ligatures from Shamela pages.
+## Next.js Demo
 
-## Next.js demo
+A minimal Next.js 16 demo application is available in the `demo/` directory.
 
-A minimal Next.js 16 application in `demo/` replaces the previous Storybook setup and offers an RTL-friendly explorer for the Shamela APIs. The server renders requests so the browser can bypass CORS limits and you only need to provide an API key and book identifier at runtime.
+**Setup:**
 
-Create a `demo/.env.local` file (or export the variables in your shell) containing the real endpoints you wish to call:
+Create `demo/.env.local`:
 
-```dotenv
-SHAMELA_API_MASTER_PATCH_ENDPOINT=https://dev.shamela.ws/api/v1/patches/master
-SHAMELA_API_BOOKS_ENDPOINT=https://dev.shamela.ws/api/v1/patches/book-updates
-# Optional when hosting the wasm asset yourself
-# SHAMELA_SQLJS_WASM_URL=https://example.com/sql-wasm.wasm
+```env
+SHAMELA_API_KEY=your_api_key
+SHAMELA_API_MASTER_PATCH_ENDPOINT=https://SHAMELA_INSTANCE.ws/api/master_patch
+SHAMELA_API_BOOKS_ENDPOINT=https://SHAMELA_INSTANCE.ws/api/books
 ```
 
-Then launch the demo:
+**Run:**
 
 ```bash
-bun run demo
+bun run demo              # Development
+bun run demo:build        # Production build
+bun run demo:start        # Production server
 ```
 
-Visit [http://localhost:3000](http://localhost:3000) to enter your API key, choose a book ID, and call helpers like `getMasterMetadata`, `getMaster`, `getBook`, and `downloadMasterDatabase` directly from the interface. For production-style builds use:
+Visit [http://localhost:3000](http://localhost:3000) to explore the API.
 
-```bash
-bun run demo:build
-bun run demo:start
-```
+## Troubleshooting
 
-When deploying to Vercel, point the project to the `demo` directory and supply the same environment variables in the dashboard so the API routes can reach Shamela.
+### Error: "Unable to automatically locate sql-wasm.wasm file"
 
-## Testing
+This occurs in bundled environments (Next.js, webpack, Turbopack). 
 
-The library includes comprehensive tests powered by `bun test`. To run the unit suite, ensure you have the necessary environment variables set, then execute:
+**Solution:** Add explicit configuration:
 
-```bash
-bun test src
+```typescript
+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,
+});
 ```
 
-For end-to-end tests:
+### Next.js: Module not found errors
 
-```bash
-bun run e2e
+1. Add to `next.config.ts`:
+   ```typescript
+   serverExternalPackages: ['shamela', 'sql.js']
+   ```
+
+2. Only import shamela in server-side code
+
+3. Create a separate `lib/shamela-server.ts` for configuration
+
+### Production build works differently than development
+
+Ensure `serverExternalPackages` is set in your Next.js config for both development and production.
+
+### Monorepo setup issues
+
+Adjust the WASM path based on your structure:
+
+```typescript
+configure({
+  sqlJsWasmUrl: join(process.cwd(), '../../node_modules/sql.js/dist/sql-wasm.wasm'),
+  // ... other config
+});
 ```
 
-### Formatting
+## Testing
 
-Apply Biome formatting across the repository with:
+Run tests with Bun:
 
 ```bash
-bun run format
+bun test src              # Unit tests
+bun run e2e               # End-to-end tests
+bun run format            # Format code
+bun run lint              # Lint code
 ```
 
 ## License
 
-This project is licensed under the MIT License - see the LICENSE file for details.
+MIT License - see LICENSE file for details.