Nvim Plugin PrayerTime

Overview

prayertime.nvim is a lightweight, standalone Neovim plugin that integrates accurate Islamic prayer schedules directly into your workflow. Stay mindful with live statusline countdowns, floating timetables, and automated Adhan notifications without leaving your editor.

Features

• Live Statusline: Real-time countdown to the next prayer
• Smart Caching: Works offline by persisting the last successful fetch to disk
• Automated Alerts: Hook into User autocommands to trigger custom notifications or scripts at prayer times
• Duha Support: Automatically calculates the Duha window (Sunrise offset)
• Extensible: Register custom formats or data providers

Requirements

• Neovim 0.9+ (vim.pack, vim.json)
• nvim-lua/plenary.nvim
• Optional: rcarriga/nvim-notify for nicer alerts

Installation

lazy.nvim

{
  "muhfaris/prayertime.nvim",
  dependencies = { "nvim-lua/plenary.nvim" },
  opts = {
    city = "Jakarta",
    country = "Indonesia",
    method = 2
  },
}

packer.nvim

use({
  "muhfaris/prayertime.nvim",
  requires = { "nvim-lua/plenary.nvim" },
  config = function()
    require("prayertime").setup({ city = "Jakarta" })
  end,
})

vim-plug

Plug "nvim-lua/plenary.nvim"
Plug "muhfaris/prayertime.nvim"

lua << EOF
require("prayertime").setup({
  city = "Jakarta",
  country = "Indonesia",
})
EOF

Usage

Basic Setup

local prayer = require("prayertime")

prayer.setup({
  city = "Jakarta",
  country = "Indonesia",
  method = 2,
})

Lualine Integration (Optional)

You can surface the statusline string anywhere—here's a Lualine example:

require("lualine").setup({
  sections = {
    lualine_y = {
      require("prayertime").get_status,
      "progress"
    },
  },
})

Configuration

require("prayertime").setup() accepts:

Option	Default	Description
format	"standard"	Output format style
city	"Jakarta"	City for prayer times
country	"Indonesia"	Country for prayer times
method	2	Calculation method (see Aladhan API)
duha_offset_minutes	15	Minutes after sunrise for Duha

Invalid values fall back to the defaults and emit a vim.notify warning so mistakes are obvious.

Method Reference

The method option follows Aladhan's calculation methods. If you omit method, Aladhan picks the closest authority for the provided city/country/coordinates.

Commands

Command	Description
:PrayerReload	Refetch prayer times
:PrayerFormat <name>	Change display format
:PrayerTimes	Show prayer times
:PrayerTest [prayer time]	Test PrayertimeAdhan event with optional HH:MM
:PrayerToday [float|notify]	Display today's schedule

These commands keep timers in sync—only one 60-second timer is ever active, even if the plugin is reloaded multiple times.

Key Mappings

Trigger your favorite commands quickly from normal mode:

vim.keymap.set("n", "<leader>pt", function()
  require("prayertime").show_today({ mode = "float" })
end, { desc = "PrayerTime: show today" })

vim.keymap.set("n", "<leader>pr", function()
  require("prayertime").refresh()
end, { desc = "PrayerTime: refresh schedule" })

Or map the user commands directly:

vim.keymap.set("n", "<leader>pt", "<cmd>PrayerToday notify<CR>", { desc = "PrayerTime: notify table" })
vim.keymap.set("n", "<leader>pr", "<cmd>PrayerReload<CR>", { desc = "PrayerTime: refetch" })
vim.keymap.set("n", "<leader>pa", "<cmd>PrayerTest<CR>", { desc = "PrayerTime: test adhan" })

Events & Automation

Each time a prayer window starts, prayertime.nvim fires a User autocommand named PrayertimeAdhan. Handlers receive ev.data.prayer and ev.data.time, making it easy to wire extra alerts:

vim.api.nvim_create_autocmd("User", {
  pattern = "PrayertimeAdhan",
  callback = function(ev)
    vim.notify(("Time for %s (%s)"):format(ev.data.prayer, ev.data.time))
  end,
})

Example: Play Custom Adhan Sound

vim.api.nvim_create_autocmd("User", {
  pattern = "PrayertimeAdhan",
  callback = function(ev)
    if ev.data.prayer ~= "Sunrise" then
      vim.api.nvim_out_write("\7") -- terminal bell
      vim.fn.jobstart({ "aplay", "/home/user/Music/adhan.wav" }, { detach = true })
    end
  end,
})

Quick Display

To preview today's schedule from Lua, call:

require("prayertime").show_today({ mode = "float" }) -- or "notify"

The floating view anchors to the bottom-right corner and auto-closes after a few seconds (press q or <Esc> to dismiss immediately).

Introspection

The standard format caches the raw API payload and exposes helpers so you can build custom UIs:

local prayer = require("prayertime")
local payload = prayer.get_cached_payload()     -- deep copy of the last JSON response
local last_synced = prayer.get_last_updated()
local derived_ranges = prayer.get_derived_ranges()

The payload includes Aladhan's original metadata (Hijri date, timezone, etc.), so you can inspect additional fields without firing your own HTTP requests.

Caching & Reliability

The latest schedule is persisted at stdpath("cache") .. "/prayertime/schedule.json". If Neovim starts while offline (or before the next refresh completes), the plugin reuses that cache whenever the city/country/method match your configuration, so statuslines and :PrayerToday remain populated immediately after launch.

Network requests retry up to three times (with a one-second delay) before an error notification is shown.

Health Check

Run :checkhealth prayertime to verify:

• Neovim version and optional rcarriga/nvim-notify integration
• nvim-lua/plenary.nvim availability (required for HTTP)
• Reachability of Aladhan's API using your current/default location settings