Introducing muslim.nvim

السلام عليكم

As Muslim software engineers we spend hours in the editor. We read docs, ship features, and solve bugs — but the world of deadlines and sprints shouldn’t make us miss our prayers. That’s why I built muslim.nvim: a tiny, fast Neovim plugin that calculates Muslim prayer times and shows the remaining time until the current waqt right in your statusline (perfectly integrated with lualine). No context switching, no extra apps — just your editor gently reminding you when it’s time to pause, reflect, and pray.

✨ Features

complete offline calculation based on Equation of Time and Declination of Sun
supports hanafi school of thought adjustments
supported methods: MWL, ISNA, Egypt, Makkah, Karachi, Tehran, Jafari, France, Russia, Singapore.
supports higher latitude adjustment
lualine integration to display current waqt status

📦 Requriements

Neovim >= 0.11
plenary.nvim
lualine (optional)

🚀 Installation

Install the plugin with your preferred package manager

1
{
2
    "tajirhas9/muslim.nvim",
3
    dependencies = {
4
        "nvim-lua/plenary.nvim",
5
        -- OPTIONAL
6
        "nvim-lualine/lualine.nvim"
7
    }
8
}

⚙️ Configuration

muslim.nvim comes with the following defaults:

1
{
2
    refresh        = 1,        -- Refresh interval in minutes to update prayer waqt times
3
    latitude       = nil,      -- MANDATORY TO BE PROVIDED. Geolocation latitude of the place of calculation
4
    longitude      = nil,      -- MANDATORY TO BE PROVIDED. Geolocation longitude of the place of calculation
5
    utc_offset     = 0,        -- timezone, default is GMT+0
6
    school         = 'hanafi', -- school of thought
7
    method         = 'MWL',    -- calculation method. default is Muslim World League
8
    time_format    = '12H',    -- time display format: '12H' for 12-hour with AM/PM, '24h' for 24-hour
9
    countdown_only = false,    -- show only countdown to next prayer
10
    offset         = {         -- per-prayer minute offsets to fine-tune calculated times
11
        fajr     = 0,          -- negative values subtract, positive values add minutes
12
        sunrise  = 0,
13
        dhuhr    = 0,
14
        asr      = 0,
15
        sunset   = 0,
16
        maghrib  = 0,
17
        isha     = 0,
18
        midnight = 0,
19
    },
20
}

🛠️ Setup

1
local muslim = require("muslim")
2
muslim.setup({
3
    latitude = 23.816237996387994,
4
    longitude = 90.79664030627636,
5
    timezone = 'Asia/Dhaka',
6
    utc_offset = 6,
7
    refresh = 5
8
})

🧭 Commands

muslim.nvim supports the following user commands.

Command	Description
`:PrayerTimes`	Returns a table with the waqt timestamps for the day

`:PrayerTimes` sample return value

1
|-------------------------|
2
| Waqt       | Time       |
3
|-------------------------|
4
| fajr       | 05:05 AM   |
5
| sunrise    | 06:20 AM   |
6
| dhuhr      | 12:06 PM   |
7
| asr        | 04:15 PM   |
8
| sunset     | 05:53 PM   |
9
| maghrib    | 05:53 PM   |
10
| isha       | 07:03 PM   |
11
| midnight   | 12:06 AM   |
12
|-------------------------|

🧰 Utility functions

Function name	Description
`prayer_time`	Returns a formatted text. Shows remaining time for current waqt (if valid) and start time of next waqt
`today_prayer_time_epochs`	Returns a table with all the waqt time (in epochs) for the day

These functions can be used to enhance the behavior of the plugin. For example, create a scheduler with vim.schedule and show the prayer time as a popup notification for certain warnings.

🧩 Integration with lualine

If you want the prayer times to appear in the statusline, you have to update your lualine configuration to add the following to the section of the lualine you want the text to be.

1
{ muslim.prayer_time, id = "muslim.nvim" }

🎨 Sample lualine configuration

To get something similar to the image above, the configuration can be as below:

1
require("lualine").setup({
2
    sections = {
3
        lualine_a = {
4
                        { 'mode',
5
                            icons_enabled = true,
6
                            separator = { left = '' },
7
                            right_padding = 2
8
                        }
9
                    },
10
        lualine_b = { { 'filename', path = 1 }, 'branch' },
11
        lualine_c = { { clients_lsp } },
12
        -- added muslim.nvim here
13
        lualine_x = {
14
                        { 'datetime', style = 'default' },
15
                        { muslim.prayer_time, id = "muslim.nvim", color = { fg = colors.blue } }
16
                    },
17
        lualine_y = { 'filetype', 'progress' },
18
        lualine_z = {
19
            { 'location', separator = { right = '' }, left_padding = 2 },
20
        },
21
    }
22
})