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.

​
Overview

Shamela provides runtime configuration through the configure() function, allowing you to set API credentials, customize WASM file locations, override fetch implementations, and configure logging.

​
Configuration Methods

​
configure()

Initializes runtime configuration including API credentials, custom fetch implementations, sql.js WASM location, and logger overrides. 
import { configure } from 'shamela';

configure({
  apiKey: process.env.SHAMELA_API_KEY!,
  booksEndpoint: process.env.SHAMELA_BOOKS_ENDPOINT!,
  masterPatchEndpoint: process.env.SHAMELA_MASTER_ENDPOINT!,
});

​
getConfig()

Returns the merged configuration snapshot combining runtime overrides with environment variables. 
import { getConfig } from 'shamela';

const config = getConfig();
console.log(config.apiKey);
console.log(config.sqlJsWasmUrl);

​
getConfigValue()

Reads a single configuration value without throwing when it is missing. 
import { getConfigValue } from 'shamela';

const apiKey = getConfigValue('apiKey');
if (!apiKey) {
  console.warn('API key not configured');
}

​
requireConfigValue()

Retrieves a configuration entry and throws an error if the value is not present. 
import { requireConfigValue } from 'shamela';

try {
  const endpoint = requireConfigValue('booksEndpoint');
  console.log('Books endpoint:', endpoint);
} catch (error) {
  console.error('Missing required configuration:', error.message);
}

​
resetConfig()

Clears runtime overrides and restores the default silent logger. Use this in tests or long-running processes when you need a clean configuration slate. 
import { resetConfig } from 'shamela';

// Reset to defaults
resetConfig();

​
Configuration Options

​
ShamelaConfig Type

All available configuration options: 
type ShamelaConfig = {
  /** API key used to authenticate against Shamela services */
  apiKey?: string;
  
  /** Endpoint used for book metadata */
  booksEndpoint?: string;
  
  /** Endpoint used for master metadata */
  masterPatchEndpoint?: string;
  
  /** Optional override for the sql.js wasm asset location */
  sqlJsWasmUrl?: string;
  
  /** Optional custom fetch implementation for environments without a global fetch */
  fetchImplementation?: typeof fetch;
};

​
Environment Variables

Configuration values are automatically read from environment variables when available:
Config KeyEnvironment Variable
apiKeySHAMELA_API_KEY
booksEndpointSHAMELA_API_BOOKS_ENDPOINT
masterPatchEndpointSHAMELA_API_MASTER_PATCH_ENDPOINT
sqlJsWasmUrlSHAMELA_SQLJS_WASM_URL
Runtime configuration set via configure() takes precedence over environment variables.

​
Custom Fetch Implementation

For environments without a global fetch function, you can provide a custom implementation: 
import { configure } from 'shamela';
import nodeFetch from 'node-fetch';

configure({
  fetchImplementation: nodeFetch as unknown as typeof fetch,
  apiKey: process.env.SHAMELA_API_KEY,
});

​
Custom Logger

Override the default silent logger with your own implementation: 
import { configure } from 'shamela';

const customLogger = {
  debug: (message: string) => console.debug(`[DEBUG] ${message}`),
  error: (message: string) => console.error(`[ERROR] ${message}`),
  info: (message: string) => console.info(`[INFO] ${message}`),
  warn: (message: string) => console.warn(`[WARN] ${message}`),
};

configure({
  logger: customLogger,
  apiKey: process.env.SHAMELA_API_KEY,
});

​
WASM Configuration

​
Auto-Detection (Node.js)

In standard Node.js environments, the WASM file is automatically detected: 
import { configure } from 'shamela';

configure({
  apiKey: process.env.SHAMELA_API_KEY,
  booksEndpoint: process.env.SHAMELA_BOOKS_ENDPOINT,
  masterPatchEndpoint: process.env.SHAMELA_MASTER_ENDPOINT,
  // sqlJsWasmUrl is auto-detected
});

​
Explicit Configuration (Bundlers)

For bundled environments like Next.js or webpack, explicitly set the WASM path: 
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,
});

​
Browser CDN (Auto)

In browsers, the library automatically uses a CDN-hosted WASM file: 
import { configure } from 'shamela';

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

​
Best Practices

Use environment variables for sensitive credentials like API keys. Never hardcode API keys in your source code.
Configure once at startup. Call configure() once at application initialization, before making any API calls.

​
Troubleshooting

​
Missing API Key

If you see an error about missing API key: 
// Check if API key is configured
const apiKey = getConfigValue('apiKey');
if (!apiKey) {
  throw new Error('SHAMELA_API_KEY environment variable not set');
}

​
Missing Endpoints

Required endpoints must be configured before making API calls: 
import { configure } from 'shamela';

// Configure only the endpoints you need
configure({
  apiKey: process.env.SHAMELA_API_KEY,
  booksEndpoint: process.env.SHAMELA_BOOKS_ENDPOINT,     // Required for book APIs
  masterPatchEndpoint: process.env.SHAMELA_MASTER_ENDPOINT, // Required for master APIs
});

​
WASM File Not Found

See the Next.js Usage Guide for bundler-specific WASM configuration.

​
Next Steps

Node.js Usage

Learn how to use Shamela in Node.js environments

Next.js Integration

Configure Shamela for Next.js applications

Build docs developers (and LLMs) love

Get started for freeTalk to us