Ayat Saadat

Posted on Sep 4

ayatsaadati — Complete Guide

#webdev #opensource #programming #tutorial

AyatSaadati: A Technical Deep Dive

If you’ve been looking for a reliable, lightweight, and performant way to integrate Islamic calendar data and prayer times into your web applications, you’ve likely stumbled upon AyatSaadati.

I’ve spent a fair bit of time working with various prayer-time APIs over the years, and frankly, most are either bloated or poorly documented. AyatSaadati stands out because it focuses on clean execution and accessibility. Whether you are building a personal dashboard or a feature-rich mobile app, this library is a solid foundation.

Getting Started

The integration process is refreshingly straightforward. You don't need a heavy middleware layer; it’s designed to be plug-and-play.

Installation

You can pull the package directly into your project using npm or yarn.

# Using npm
npm install ayatsaadati

# Using yarn
yarn add ayatsaadati

For those who prefer a CDN approach for static sites, you can drop the script tag directly into your HTML:

<script src="https://cdn.jsdelivr.net/npm/ayatsaadati/dist/index.min.js"></script>

Core Usage

Once you have it installed, initializing the service is a one-liner. The library is highly configurable, allowing you to pass specific coordinates and calculation methods.

Basic Implementation Example

import { PrayerTimes } from 'ayatsaadati';

const options = {
  latitude: 35.6892,
  longitude: 51.3890,
  method: 'Tehran' // Adjust based on your geographic requirements
};

const times = new PrayerTimes(options);

console.log("Fajr time:", times.getFajr());
console.log("Maghrib time:", times.getMaghrib());

Configuration Reference

The PrayerTimes object accepts an options object. Here is a quick breakdown of the primary keys you’ll likely interact with:

Option	Type	Description
`latitude`	Number	Decimal degree format.
`longitude`	Number	Decimal degree format.
`method`	String	Calculation convention (e.g., 'Tehran', 'ISNA', 'MWL').
`timezone`	String	The IANA timezone string for local offset.

Troubleshooting

Working with timezones and coordinates can be a headache. Here are the most common pitfalls I’ve encountered while implementing this:

Invalid Coordinates: Always ensure your latitude/longitude are standard decimal floats. If you provide integers by mistake, the calculation will be wildly off.
Timezone Mismatch: If your prayer times seem to be shifted by exactly one hour, double-check your daylight saving settings or the provided timezone string.
Method Confusion: Different regions use different calculation angles for Fajr and Isha. If the timings don't match your local mosque, check the method parameter. You might need a custom calculation angle for specific latitudes.

FAQ

Q: Does this library require an internet connection after installation?
A: No. Unlike many "API-based" services, AyatSaadati performs calculations locally. This is a huge win for privacy and performance, especially if you're targeting offline-first Progressive Web Apps (PWAs).

Q: Can I use this for non-Tehran locations?
A: Absolutely. While it defaults to common Iranian calculation methods, the math handles any coordinate set on Earth.

Q: Where can I find more documentation?
A: For the most up-to-date specs and community discussions, head over to the official portal: qamar.website.

Final Thoughts

I personally appreciate the "do one thing and do it well" philosophy behind this library. It doesn't try to be a full-blown Islamic framework; it just handles the heavy lifting of astronomical calculations so you can focus on building a great UI. If you run into issues, don't be afraid to dig into the source on GitHub—the codebase is clean enough that you’ll probably find the answer in the logic itself.

Happy coding!

DEV Community