A very fast, powerful, extensible and asynchronous Neovim HTTP client written in Lua.
rest.nvim
by default makes use of its own curl
wrapper made in pure Lua and a tree-sitter
parser to parse http
files. So what you can run get exact and detailed result what you see from
your editor!
In addition to this, you can also write integrations with external HTTP clients, such as the postman CLI.
Important
If you are facing issues, please report them so we can work in a fix together :)
- Easy to use
- Friendly, organized and featureful request results window
- Fast runtime with statistics about your request
- Set custom pre-request and post-request hooks to dynamically interact with the data
- Easily set environment variables based on the response to re-use the data later
- Tree-sitter based parsing and syntax highlighting for speed and perfect accuracy
- Format response body with native
gq
command - Possibility of using dynamic/environment variables and Lua scripting in HTTP files
- Save received cookies and load them automatically
Note
rest.nvim requires Neovim >= 0.10.1 to work.
curl
- tree-sitter-http (
scm
version)
rocks.nvim (recommended)
:Rocks install rest.nvim
:Rocks install tree-sitter-http dev
{
"rest-nvim/rest.nvim",
}
Note
you also need to install latest tree-sitter-http parser using
:TSInstall http
No .setup()
call is needed!
Just set your options via vim.g.rest_nvim
. It is fully documented and typed internally so you get
a good experience during autocompletion :)
---@type rest.Opts
vim.g.rest_nvim = {
-- ...
}
Note
You can also check out :h rest-nvim.config
for documentation.
---rest.nvim default configuration
---@class rest.Config
local default_config = {
---@type table<string, fun():string> Table of custom dynamic variables
custom_dynamic_variables = {},
---@class rest.Config.Request
request = {
---@type boolean Skip SSL verification, useful for unknown certificates
skip_ssl_verification = false,
---Default request hooks
---@class rest.Config.Request.Hooks
hooks = {
---@type boolean Encode URL before making request
encode_url = true,
---@type string Set `User-Agent` header when it is empty
user_agent = "rest.nvim v" .. require("rest-nvim.api").VERSION,
---@type boolean Set `Content-Type` header when it is empty and body is provided
set_content_type = true,
},
},
---@class rest.Config.Response
response = {
---Default response hooks
---@class rest.Config.Response.Hooks
hooks = {
---@type boolean Decode the request URL segments on response UI to improve readability
decode_url = true,
---@type boolean Format the response body using `gq` command
format = true,
},
},
---@class rest.Config.Clients
clients = {
---@class rest.Config.Clients.Curl
curl = {
---Statistics to be shown, takes cURL's `--write-out` flag variables
---See `man curl` for `--write-out` flag
---@type RestStatisticsStyle[]
statistics = {
{ id = "time_total", winbar = "take", title = "Time taken" },
{ id = "size_download", winbar = "size", title = "Download size" },
},
---Curl-secific request/response hooks
---@class rest.Config.Clients.Curl.Opts
opts = {
---@type boolean Add `--compressed` argument when `Accept-Encoding` header includes
---`gzip`
set_compressed = false,
},
},
},
---@class rest.Config.Cookies
cookies = {
---@type boolean Whether enable cookies support or not
enable = true,
---@type string Cookies file path
path = vim.fs.joinpath(vim.fn.stdpath("data") --[[@as string]], "rest-nvim.cookies"),
},
---@class rest.Config.Env
env = {
---@type boolean
enable = true,
---@type string
pattern = ".*%.env.*",
},
---@class rest.Config.UI
ui = {
---@type boolean Whether to set winbar to result panes
winbar = true,
---@class rest.Config.UI.Keybinds
keybinds = {
---@type string Mapping for cycle to previous result pane
prev = "H",
---@type string Mapping for cycle to next result pane
next = "L",
},
},
---@class rest.Config.Highlight
highlight = {
---@type boolean Whether current request highlighting is enabled or not
enable = true,
---@type number Duration time of the request highlighting in milliseconds
timeout = 750,
},
---@see vim.log.levels
---@type integer log level
_log_level = vim.log.levels.WARN,
---@class rest.Config.DebugInfo
_debug_info = {
-- NOTE: default option is `nil` to prevent overwriting as empty array
---@type string[]
unrecognized_configs = nil,
},
}
Create a new http file or open an existing one and run the :Rest run {name} command, or just place the cursor over the request and simply run :Rest run.
Method Request-URI HTTP-Version
Header-field: Header-value
Request-Body
Note
rest.nvim follows intellij's http client spec
for .http
file syntax. You can find examples of use in the spec/examples
directory.
By default rest.nvim
does not have any key mappings except the result buffers so you will not have
conflicts with any of your existing ones.
User Command | Behavior |
---|---|
:Rest open |
Open result pane |
:Rest run |
Run request under the cursor |
:Rest run {name} |
Run request with name {name} |
:Rest last |
Run last request |
:Rest logs |
Edit logs file |
:Rest cookies |
Edit cookies file |
:Rest env show |
Show dotenv file registered to current .http file |
:Rest env select |
Select & register .env file with vim.ui.select() |
:Rest env set {path} |
Register .env file to current .http file |
[!INFO] All
:Rest
subcommands opening new window supportcommand-modifiers
(:h command-modifiers
.) For example, you can run:hor Rest open
to open result pane in horizontal split.
See :h rest-nvim.commands
for more info
http://localhost:8000
# @lang=lua
> {%
local json = vim.json.decode(response.body)
json.data = "overwritten"
response.body = vim.json.encode(json)
%}
Put # @lang=lua
comment just above any script elements.
Scripts without @lang
will be parsed as javascript code to match with http spec.
rest.nvim
provides a [telescope.nvim] extension to select the environment variables file,
you can load and use it with the following snippet:
-- first load extension
require("telescope").load_extension("rest")
-- then use it, you can also use the `:Telescope rest select_env` command
require("telescope").extensions.rest.select_env()
Here is a preview of the extension working :)
- Enter: Select Env file
- Ctrl + O: Edit Env file
config.env.pattern
: For env file pattern (lua-pattern)
We also have lualine component to get what env file you select!
And don't worry, it will only show up under HTTP files.
-- Just add a component in your lualine config
{
sections = {
lualine_x = {
"rest"
}
}
}
-- To use a custom icon and color
{
sections = {
lualine_x = {
{
"rest",
icon = "๎",
fg = "#428890"
}
}
}
}
Here is a preview of the component working :)
- Fork it (https://github.com/rest-nvim/rest.nvim/fork)
- Create your feature branch (git checkout -b my-new-feature)
- Commit your changes (git commit -am 'feat: add some feature')
- Push to the branch (git push -u origin my-new-feature)
- Create a new Pull Request
Important
rest.nvim uses semantic commits that adhere to semantic versioning and these help with automatic releases, please use this type of convention when submitting changes to the project.
Tests can be ran via make test
. You must have luarocks
installed to install dependencies. The
test runner through make test
will automatically install all required dependencies.
rest.nvim is GPLv3 Licensed.