PrayerZone JavaScript SDK

The official, typed JavaScript and TypeScript client for the public PrayerZone prayer-times API.

Use it in Node.js, modern browsers, serverless functions, React, Vue, Svelte, Next.js, Nuxt, and other JavaScript runtimes with the Fetch API.

Features

• Complete TypeScript types
• City and mosque prayer schedules
• Nearby mosque discovery
• Qibla and calculation metadata
• Eight supported languages
• Request timeout and automatic retries
• In-memory cache and concurrent request deduplication
• Structured, actionable errors
• No runtime dependencies
• ESM and CommonJS builds

Installation

npm install @prayerzone/prayer-times

Node.js 18 or later is required. Modern browsers work without a polyfill.

Quick start

import { PrayerZone } from "@prayerzone/prayer-times";

const prayerZone = new PrayerZone();

const schedule = await prayerZone.getCityPrayerTimes("paris", {
  language: "fr",
});

console.log(schedule.city.name);
console.table(schedule.data.prayerTimes);
console.log(`Qibla: ${schedule.data.qibla.bearing}°`);

Mosque schedules

const schedule = await prayerZone.getMosquePrayerTimes(
  "paris_grande-mosquee-de-paris",
  { language: "fr" },
);

console.log(schedule.mosque.title);
console.table(schedule.data.prayerTimes);

Find nearby mosques

const mosques = await prayerZone.getNearbyMosques({
  longitude: 2.3522,
  latitude: 48.8566,
  maxDistance: 5_000,
});

for (const mosque of mosques) {
  console.log(mosque.title, mosque.distance);
}

Configuration

const prayerZone = new PrayerZone({
  timeoutMs: 8_000,
  retries: 2,
  retryDelayMs: 250,
  cacheTtlMs: 5 * 60_000,
  headers: {
    "X-Application": "my-prayer-app",
  },
});

| Option | Default | Description | |---|---:|---| | baseUrl | https://pray.zone | API origin; useful for tests or proxies | | fetch | globalThis.fetch | Custom Fetch API implementation | | timeoutMs | 10000 | Timeout for each request attempt | | retries | 2 | Retries for network, timeout, 408, 429, and 5xx errors | | retryDelayMs | 250 | Initial exponential retry delay | | cacheTtlMs | 300000 | Successful response cache duration; 0 disables it | | headers | — | Additional HTTP request headers |

Call prayerZone.clearCache() whenever an application needs a forced refresh.

Error handling

import { PrayerZoneError } from "@prayerzone/prayer-times";

try {
  await prayerZone.getCityPrayerTimes("unknown-city");
} catch (error) {
  if (error instanceof PrayerZoneError) {
    console.error(error.code, error.status, error.message);
  }
}

Possible codes are API_ERROR, NETWORK_ERROR, TIMEOUT, and VALIDATION_ERROR. The retryable property identifies temporary failures.

Languages

The language option accepts:

ar, bn, de, en, es, fr, it, pt

English (en) is used by default.

API and examples

• Interactive API documentation
• OpenAPI contract
• Framework integration examples
• Web Component
• Mosque and TV display

Localized PrayerZone websites

pray.zone is the canonical project and developer domain. PrayerZone also provides localized prayer-time websites:

• English — pray.zone
• Français — prieres.org
• Deutsch — gebet.jetzt
• Español — oraciones.day

Development

npm install
npm run validate

See CONTRIBUTING.md for the contribution workflow.

Attribution

Attribution is appreciated:

Prayer times powered by [PrayerZone](https://pray.zone/)

License

MIT