Live "are my Hex deps up to date?" feedback for Elixir mix.exs, in the spirit
of crates.nvim. As you edit mix.exs, the plugin checks each dependency's
declared version requirement against hex.pm: inline virtual text shows the
latest version and status, and non-existent versions/packages show up as
diagnostics.
- Live inline virtual text as you edit
mix.exs, no:commandneeded - Status at a glance: up to date, upgradable, outdated pin, retired, or non-existent
- Non-existent versions/packages and retired-only matches also show up as real
vim.diagnosticentries - One-key actions: upgrade the requirement under the cursor, browse published versions, or open the package on hex.pm
- Treesitter parsing, with a Lua line-scanner fallback when the elixir parser is missing or the buffer doesn't parse mid-edit
- Status comes from
mix.exsalone; no shelling out tomix - Async, cached hex.pm requests; configurable text, highlights, and keymaps
- Neovim 0.10+
curlonPATH- (Recommended) the
elixirTreesitter parser (:TSInstall elixir); without it, the plugin falls back to Lua patterns.
With lazy.nvim:
{
"jpease/hex-outdated.nvim",
ft = "elixir",
opts = {},
}With packer.nvim:
use({
"jpease/hex-outdated.nvim",
config = function()
require("hex-outdated").setup({})
end,
})With mini.deps:
MiniDeps.add({ source = "jpease/hex-outdated.nvim" })
require("hex-outdated").setup({})With vim-plug:
Plug 'jpease/hex-outdated.nvim'
" after plug#end():
lua require("hex-outdated").setup({})As a native package (no plugin manager):
git clone https://github.com/jpease/hex-outdated.nvim \
~/.config/nvim/pack/plugins/start/hex-outdated.nvim-- in your init.lua
require("hex-outdated").setup({})Every manager other than lazy.nvim's opts = {} needs an explicit
require("hex-outdated").setup({}) call, because the plugin activates entirely
through setup().
When you open a mix.exs, status appears automatically and updates as you type.
:HexOutdated {refresh|toggle|upgrade|versions|open|info|lock}
(bare :HexOutdated = refresh; the subcommands act on mix.exs buffers only)
| Subcommand | Action |
|---|---|
refresh |
Re-fetch, bypassing the cache. |
toggle |
Enable/disable the inline display for the current buffer. |
upgrade |
Rewrite the requirement under the cursor to target the latest release, keeping its operator, precision, and spacing. |
versions |
Floating window of active published versions; <CR> inserts the selected one, q/<Esc> closes. |
open |
Open the package's page on hex.pm in a browser. |
info |
Floating detail view (requirement / locked / latest) for the dependency under the cursor. |
lock |
Toggle the per-buffer lock lens: a locked X · latest Y line under each dependency. |
The same actions are also plain functions, so you can bind your own keys:
local hex = require("hex-outdated")
-- hex.refresh() / hex.toggle() / hex.upgrade() / hex.versions() / hex.open()
-- hex.info() / hex.lock()upgrade and selecting a release from versions both preserve the current
requirement style: comparison requirements stay comparisons, bare exact
versions stay bare, and ~> keeps its existing precision (with full prerelease
versions preserved). Both re-analyze the buffer right away. Retired Hex
releases never count as the latest release and are not offered in the popup.
| Status | Meaning |
|---|---|
up_to_date |
The requirement allows the latest stable release. |
upgradable |
The requirement resolves, but excludes the latest release (~> 1.6.0 once 1.7.0 is out). |
outdated |
An exact pin (==) that is below the latest release. |
retired |
Only retired releases match the requirement (also a warning diagnostic). |
invalid |
No published release matches the requirement (also an error diagnostic). |
The plugin annotates public Hex packages only. It leaves git:/github:,
path:, and in_umbrella: deps alone, and also private organization:/repo:
packages, which the public API cannot see, whether or not they carry a
requirement. Requirements it can't analyze (combined and/or clauses) get no
inline status; the detail float still shows their latest release. When a fetch
fails, the detail float says why (timeout, rate limit, ...).
By default hex-outdated reads only mix.exs. When a mix.lock is present it can
also show what's actually locked, kept secondary so the inline requirement
status stays primary:
- Detail float.
:HexOutdated info(or pressKon a dependency line) shows requirement / locked / latest for the dependency under the cursor. - Lens.
:HexOutdated locktoggles alocked X · latest Yline under each dependency (off by default). - Stale-lock diagnostic. A warning when
mix.lockholds a version that no longer satisfies your requirement (e.g. after you tighten it), prompting amix deps.get.
The lock context is re-read when the buffer is analyzed and when mix.lock
may have changed outside it: on regaining focus, on entering the buffer, and
after a :! command.
All of this no-ops when there is no mix.lock. Disable it entirely with
lock = { enabled = false }. The K binding only acts on dependency lines and
otherwise falls through to LSP hover / keywordprg; set popup.hover_key = false
to leave K alone.
setup merges your options over the defaults. Unknown options and values of
the wrong type are reported and ignored:
require("hex-outdated").setup({
enabled = true, -- show status when a mix.exs opens (:HexOutdated toggle flips it per buffer)
auto_update = true, -- re-analyze on buffer changes
debounce_ms = 500, -- delay (milliseconds) before re-analyzing after an edit
api = {
base_url = "https://hex.pm/api",
timeout_ms = 5000, -- invalid/non-positive values use 5000
max_concurrent = 8, -- cap on simultaneous curl processes
},
lock = {
enabled = true, -- read mix.lock when present
lens = false, -- locked-version lens; off by default
stale_diagnostic = true, -- warn when the lock no longer satisfies the requirement
},
cache = {
ttl_seconds = 3600, -- how long a successful fetch is cached
error_ttl_seconds = 60, -- how long a failed fetch is cached before retry
},
text = { -- %s is the latest version; only %s and %% are format specifiers
up_to_date = "✓ %s",
upgradable = "↑ %s",
outdated = "↓ %s",
invalid = "✗ no such version",
retired = "⚠ retired release",
loading = "…",
error = "fetch error",
lock_behind = "locked %s · latest %s", -- lens line when the lock is behind
lock_current = "locked %s · up to date",
},
highlight = { -- highlight group per status
up_to_date = "HexOutdatedUpToDate",
upgradable = "HexOutdatedUpgradable",
outdated = "HexOutdatedOutdated",
invalid = "HexOutdatedInvalid",
retired = "HexOutdatedRetired",
loading = "HexOutdatedLoading",
error = "HexOutdatedError",
lock = "HexOutdatedLock",
lock_behind = "HexOutdatedLockBehind",
},
popup = {
border = "rounded", -- any nvim_open_win() border: a style name or a character list
max_height = 20, -- max lines in the versions/info float
hover_key = "K", -- key for the detail float; false leaves K unmapped
},
-- buffer-local keymaps, action = lhs; actions are the :HexOutdated
-- subcommands: refresh, toggle, upgrade, versions, open, info, lock
keymaps = {}, -- e.g. { upgrade = "<leader>cu", versions = "<leader>cv", info = "<leader>ci" }
})Highlight groups link to Diagnostic* by default and respect your colorscheme
if you define them first: HexOutdatedUpToDate, HexOutdatedUpgradable,
HexOutdatedOutdated, HexOutdatedInvalid, HexOutdatedRetired,
HexOutdatedLoading, HexOutdatedError, HexOutdatedLock,
HexOutdatedLockBehind.
hex-outdated parses mix.exs with Treesitter to find dependency tuples in the
list the project's deps: setting names: an inline list, deps() (deps/0
by default), every clause of a call with arguments such as
deps(Mix.env()), or a module attribute such as @deps.
It falls back to a Lua line scanner in two cases: Neovim doesn't ship the
elixir parser, and while you type the buffer is often syntactically
incomplete, where Treesitter's error recovery can swallow neighboring
dependency tuples. The scanner only needs to track strings, comments, and
do/end blocks, so a half-written tuple doesn't hide the rest of the list.
Treesitter stays the primary path because a real parse tree handles
well-formed files without the scanner's heuristics. For a composed setting such as
deps: deps() ++ extra(), only the leading call or list is read, and a list
assembled through local variables is only read where its tuples sit in the
returned expression. A Hex package alias such as
{:local_app, "~> 2.0", hex: :actual_package} points the API lookup at the
real package, while the local application name still keys into mix.lock. For
each public Hex dependency the plugin asynchronously queries
https://hex.pm/api/packages/:name (cached), sets retired releases aside, then
compares your requirement against the active published versions using Hex
prerelease semantics. The requirement status comes from mix.exs alone; the
plugin reads mix.lock locally, and only for the optional lock context above.
There is no shelling out to mix.
just check # fmt-check, lint, test, test-nvim
just test # busted suite in spec/ (no Neovim)
just test-nvim # nvim --headless -u NONE -i NONE -l test/run.lua
just format # stylua
just lint # luacheck
spec/ holds specs that run without Neovim, stubbing the vim APIs a module
touches. test/ holds specs that need a real editor (Treesitter, extmarks,
diagnostics, jobs, buffers) and runs with only nvim on PATH.
CI runs stylua and luacheck on Ubuntu, busted (on LuaJIT, like Neovim) on
Ubuntu and macOS, and the headless suite on Ubuntu, macOS, and Windows with
stable Neovim plus Ubuntu with 0.10, the oldest supported release. The Ubuntu
and macOS legs install the elixir Treesitter parser and set
HEX_OUTDATED_REQUIRE_TS=1, so the Treesitter specs fail rather than skip if
it is missing.
MIT © Justin Pease
