Repository files navigation

Hurl.nvim is a Neovim plugin designed to run HTTP requests directly from `.hurl` files. Elevate your API development workflow by executing and viewing responses without leaving your editor.

• Neovim stable (0.10.2) or nightly. It might not work with older versions of Neovim.

• 🚀 Execute HTTP requests directly from.hurl files.
• 👁‍🗨 Multiple display modes for API response: popup or split.
• 🌈 Highly customizable through settings.
• 📦 Environment file support for managing environment variables.
• 🛠 Set environment variables withHurlSetVariable command.
• 📝 View and manage environment variables withHurlManageVariable command.
• 📜 View the response of your last HTTP request withHurlShowLastResponse command.

Add the following configuration to your Neovim setup withlazy.nvim:

{"jellydn/hurl.nvim",dependencies= {"MunifTanjim/nui.nvim","nvim-lua/plenary.nvim","nvim-treesitter/nvim-treesitter",-- Optional, for markdown rendering with render-markdown.nvim    {'MeanderingProgrammer/render-markdown.nvim',opts= {file_types= {"markdown"},      },ft= {"markdown"},    },  },ft="hurl",opts= {-- Show debugging infodebug=false,-- Show notification on runshow_notification=false,-- Show response in popup or splitmode="split",-- Default formatterformatters= {json= {'jq'},-- Make sure you have install jq in your system, e.g: brew install jqhtml= {'prettier',-- Make sure you have install prettier in your system, e.g: npm install -g prettier'--parser','html',      },xml= {'tidy',-- Make sure you have installed tidy in your system, e.g: brew install tidy-html5'-xml','-i','-q',      },    },-- Default mappings for the response popup or split viewsmappings= {close='q',-- Close the response popup or split viewnext_panel='<C-n>',-- Move to the next response popup windowprev_panel='<C-p>',-- Move to the previous response popup window    },  },keys= {-- Run API request    {"<leader>A","<cmd>HurlRunner<CR>",desc="Run All requests"},    {"<leader>a","<cmd>HurlRunnerAt<CR>",desc="Run Api request"},    {"<leader>te","<cmd>HurlRunnerToEntry<CR>",desc="Run Api request to entry"},    {"<leader>tE","<cmd>HurlRunnerToEnd<CR>",desc="Run Api request from current entry to end"},    {"<leader>tm","<cmd>HurlToggleMode<CR>",desc="Hurl Toggle Mode"},    {"<leader>tv","<cmd>HurlVerbose<CR>",desc="Run Api in verbose mode"},    {"<leader>tV","<cmd>HurlVeryVerbose<CR>",desc="Run Api in very verbose mode"},-- Run Hurl request in visual mode    {"<leader>h",":HurlRunner<CR>",desc="Hurl Runner",mode="v"},  },}

When configuring nvim-treesitter addhurl to theensure_installed list ofparsers.

Simple demo in split mode:

hurl.nvim seamlessly integrates with environment files namedvars.env to manage environment variables for your HTTP requests. These environment variables are essential for customizing your requests with dynamic data such as API keys, base URLs, and other configuration values.

You can specify the name of the environment file in yourhurl.nvim configuration. By default,hurl.nvim looks for a file namedvars.env, but you can customize this to any file name that fits your project's structure.

Here's how to set a custom environment file name in yourhurl.nvim setup:

require('hurl').setup({-- Specify your custom environment file name hereenv_file= {'hurl.env',  },-- Other configuration options...})

The plugin searches for avars.env (env_file config) in multiple locations to accommodate various project structures and ensure that environment-specific variables for your HTTP requests are easily accessible. The search occurs in the following order:

1. Current File's Directory: The directory where the current file is located. This is particularly useful for projects where environment variables are specific to a particular module or component.

2. Specific Directories in Project: The plugin scans predefined directories within the project, which are commonly used for organizing different aspects of a project:

   • src/: The source code directory.
   • test/ andtests/: Directories typically used for test scripts.
   • server/: If your project includes a server component, this directory is checked.
   • src/tests/ andserver/tests/: These are checked for environment variables specific to tests within the respectivesrc andserver directories.

3. Intermediate Directories from Git Root to Current File: If the project is a git repository, the plugin identifies the root of the repository and then searches forvars.env in every directory on the path from this root to the current file's directory. This feature is particularly useful in monorepo setups or large projects, where different modules or packages may have their own environment variables.

By checking these locations, the plugin ensures a comprehensive search for environment variables, catering to a wide range of project structures and setups.

To change the environment file name, use theHurlSetEnvFile command followed by the new file name. You can have multiple variable files by having comma-separated values.

• Ensure that the new environment file exists in the directories where the plugin searches for it, as outlined in theFile Location section.
• This change will apply globally for the current session of Neovim. If you restart Neovim, it will revert to the defaultvars.env unless you change it again.

This is a feature that allows you to define custom variables in your.hurl files. You can define a list of custom variables with a name and a callback function that returns the value of the variable. The callback function is executed every time the variable is used in the.hurl file.

-- Custom below to add your own fixture variablesfixture_vars= {    {name='random_int_number',callback=function()returnmath.random(1,1000)end,    },    {name='random_float_number',callback=function()localresult=math.random()*10returnstring.format('%.2f',result)end,    },  }

Then you can use{{random_int_number}} and{{random_float_number}} in your.hurl files.

POST https://api.example.comContent-Type: application/json{  "name": "Product ID {{random_int_number}}",  "price": {{random_float_number}}}

Check out the following demos to seehurl.nvim in action:

Run the entire file by pressing<leader>A or runHurlRunner command.

Select a range of lines and press<leader>h to execute the request or runHurlRunner command.

Place your cursor on a HURL entry and press<leader>a or runHurlRunnerAt command to execute the entry request.

RunHurlVerbose command to execute the request in verbose mode.

Place your cursor on the line you want to run to that entry and press<leader>te or runHurlRunnerToEntry command to execute the request.

Note: it's running from start of file to the selected entry and ignore the remaining of the file. It is useful for debugging purposes.

Similar toHurlRunnerToEntry, we could run from current entry to end of file withHurlRunnerToEnd command.

RunHurlToggleMode command to toggle between split and popup mode.

TheHurlSetVariable command allows you to set environment variables for your HTTP requests. This is particularly useful for setting dynamic data such as API keys, base URLs, and other configuration values.

To use this command, type:HurlSetVariable followed by the variable name and its value. For example:

:HurlSetVariable API_KEY your_api_key

This will set theAPI_KEY environment variable toyour_api_key. You can then use this variable in your.hurl files like this:

GET https://api.example.comAuthorization: Bearer {{API_KEY}}

TheHurlManageVariable command provides a convenient way to view your environment variables. When you run this command, it opens a new buffer in popup with the current environment variables and their values.

To use this command, simply type:HurlManageVariable in the command line:

:HurlManageVariable

The default keymap for this buffer is:

• q: Close the buffer
• e: Edit the variable

For now, if you want to modify the global variables, you can do so by using theHurlSetVariable command or by editing yourvars.env file directly.

TheHurlShowLastResponse command allows you to view the response of your last HTTP request.

:HurlShowLastResponse

hurl.nvim comes with some default key mappings to streamline your workflow:

• q: Close the current popup window.
• <C-n>: Switch to the next popup window.
• <C-p>: Switch to the previous popup window.

These key mappings are active within the popup windows thathurl.nvim displays.

hurl.nvim can be customized with the following default configurations:

--- Default configuration for hurl.nvimlocaldefault_config= {debug=false,mode='split',show_notification=false,auto_close=true,-- Default split optionssplit_position='right',split_size='50%',-- Default popup optionspopup_position='50%',popup_size= {width=80,height=40,  },env_file= {'vars.env'},fixture_vars= {    {name='random_int_number',callback=function()returnmath.random(1,1000)end,    },    {name='random_float_number',callback=function()localresult=math.random()*10returnstring.format('%.2f',result)end,    },  },find_env_files_in_folders=utils.find_env_files_in_folders,formatters= {json= {'jq'},html= {'prettier','--parser','html',    },xml= {'tidy','-xml','-i','-q',    },  },}

To apply these configurations, include them in your Neovim setup like this:

require('hurl').setup({debug=true,-- Enable to show detailed logsmode='popup',-- Change to 'popup' to display responses in a popup windowenv_file= {'vars.env'},-- Change this to use a different environment file nameformatters= {json= {'jq'},-- Customize the JSON formatter commandhtml= {'prettier',-- Customize the HTML formatter command'--parser','html',    },xml= {'tidy',-- Customize the XML formatter command'-xml','-i','-q',    },  },})

Adjust the settings as per your needs to enhance your development experience withhurl.nvim.

• Logs are saved at~/.local/state/nvim/hurl.nvim.log on macOS.

• If you're using a stable version of Neovim that doesn't support Hurl syntax highlighting, you can set the filetype tosh orbash for your.hurl files. This will enable basic syntax highlighting that can improve readability. To do this, add the following line to your Neovim configuration:

autocmdBufRead,BufNewFile*.hurlsetfiletypesh

For example, here is myautocmd for.hurl files.

• Hurl - Run and Test HTTP Requests
• Inspired byray-x/web-tools.nvim: Neovim plugin for web developers
• UtilizeMunifTanjim/nui.nvim: UI components for Neovim plugins and configurations

👤Huynh Duc Dung

• Website:https://productsway.com/
• Twitter:@jellydn
• Github:@jellydn

If this plugin has been helpful, please give it a ⭐️.

Thanks goes to these wonderful people (emoji key):

Dung Duc Huynh (Kaka) 💻📖	Cenk Kılıç 💻📖	Andre Van Der Merwe 💻	Sergey Kochetkov 📖💻	rbingham 💻	Horacio Sanson 💻📖	xiwang 💻📖
wenjin 💻	Aron Griffis 💻	Javier Ugarte 💻	Daniel Jeller 💻📖	Xouzoura 💻	Duong Tan Phat 💻	Andreas Kemkers 📖
Add your contributions

This project follows theall-contributors specification. Contributions of any kind welcome!