DEV Community: Ethan Carlsson

nvim-hurl and Some Intuitions on UX

Ethan Carlsson — Sun, 31 Aug 2025 12:39:07 +0000

I just made a new release to a plugin I've developed to run hurl files (https://hurl.dev/)
in Neovim (https://github.com/ethancarlsson/nvim-hurl.nvim/releases/tag/v1.2.0).
I really like working on this project, it's designed for me to use and so when
I add features I only ever add the features that I'm actually going to use.

In this case I added additional functionality to work with temporary variables.
I've always found variables kind of awkward to use in tools like Postman, you end
up clicking through so much UI to add a variable that in all likelihood you'll need
to change the next time you run the command. For that reason I didn't put much
effort into variables, and in practice I only use variables that I know aren't
going to change often, like {{host}} and {{auth_token}}. Copy and pasting
the other values is almost always quicker and more ergonomic than creating variables
when your exploring an API. The only case where I'll use variables is if I'm intending
to run the file as a test and not edit it.

They can however be used to solve a problem though. When your working on http APIs
a common issue is that in order to create a resource you need to first get the ID
of a related resource.

POST {{url}}/orders

{
  "items": [
    {
      "id": "ce039087-835a-4484-89dc-70c2ea123b40"
    }
  ]
}

In order to create this order I need to first retrieve the ID of the item and copy
and past it into this request. This can get tedious when there's multiple IDs or
if I want to test out multiple items.

So it would be convenient if I could have this:

POST {{url}}/orders

{
  "items": [
    {
      "id": "{{id}}"
    }
  ]
}

That way I don't need to worry about having to edit the file, I just update the
variable. But this get's us back to the original problem I was facing with tools
like Postman, setting the variable is often just as much work as just copying and
pasting it into the file. So how do we make it less effort.

My trick was to build on my existing workflow, so I still copy things, but now
if I copy this object all the variables can be automatically mapped to hurl variable
template variables.

{
  "id": "2ab2e8d4-ae06-44e6-9ae3-c0891185bfe2",
  "sku": "boo/US-/Gre/Bla",
  "item_name": "Grey Boots"
}

You copy the object and then run :Hurlsvr "* (you don't have to write the whole, just remap it),
then {{id}}, {{sku}} and {{item_name}} will all be populated by the values
in the object. This way I can scroll through a list of items and whenever I want
to change the variables I just yank them into
a register.

This still doesn't really fit how I work though, usually a just need to select a
couple of variables, so I use this configuration

vim.keymap.set(
    "n",
    "<leader>yh",
    [["8yy<cmd>Hurlsvr "8<CR>]], -- You can use a different register if you want "8 was arbitrarily chosen
    { desc = "Yank line to register and then to hurl variables" }
)

This automates pulling the value from the register and lets me select just a given
line, I just need the ID so using this I can just yank this line"id": "2ab2e8d4-ae06-44e6-9ae3-c0891185bfe2",
and it will make just {{id}} accessible in the hurl file. More importantly,
it will do it in just three key strokes.

This still has a disadvantage over the good old fashioned copy and past functionality,
when you've copied and pasted you know the variable is there and you know it's value.
I added completions to the plugin to make the variables more transparent, you can
see what variables are available and the contents of the variable.

Some intuitions on UX

I'd like to use the changes I made here to help systematize my own intuitions about
what makes good UX.

Good UX involves less actions. All else equal, if you can do the same thing in less clicks, key presses, etc., you should.
Good UX matches the users exact use case. The ability to turn partial JSON into hurl variables is incredibly specific and it's exactly what I need. I considered making it work with YAML or to be able to parse variables in the format that hurl uses (key=var). But that's not how I use it and the extra support would just complicate the tool.
Good UX fits into existing UI, it doesn't introduce new UI elements. I considered introducing a pop-up to be able to see what variables are active, but in the end found that the completions were enough for me to be able to get an idea of what variables I can use. Since I already use completions in Neovim I don't need to change the way I use the Neovim very drastically when manipulating hurl files.

These intuitions are very specific to how I use this plugin. There are some things
I don't need to think about, like making it easy to learn how to use it or account
for different use cases. But this is a plugin just for me, so I don't have to think
about those things, and that's what has made it such a fun project to work on.

Exploring APIs with Neovim and Hurl

Ethan Carlsson — Mon, 11 Sep 2023 19:14:25 +0000

Hurl is a very interesting project that extends the functionality of curl.
It offers an alternative to more GUI oriented software like Postman.

Hurl is foremost a command line tool and should be easy to use on a local
computer, or in a CI/CD pipeline. Some tools in the same space as Hurl
(Postman for instance), are GUI oriented, and we find it less attractive than
CLI
-- Hurl FAQ

This caught my attention. I've been a user of Postman for a while, but over time
I've found the tool to be more and more clunky, especially when working on
larger projects.

It's awkward to navigate.
It can be slow and memory hungry, especially when there are lots of tabs open.
It's written with the mouse in mind, keyboard shortcuts feel more like an afterthought.
It's hard, or at least awkward, to integrate into other tools.

All of these problems have been resolved for me by combining Neovim and Hurl.
To do this I wrote a plugin, nvim-hurl.nvim,
it runs hurl files and displays the response those files get from the server.

Using this setup I was able to solve all the issues I had with Postman
leveraging the power of Neovim and Hurl together.

Jumping around files with a fuzzy finder like Telescope or fzf is a lot more comfortable. I don't waste time scrolling through tabs or searching through giant collections anymore.
This will depend on the plugins you use, but for the most part Neovim is a lot lighter Postman. More importantly, I don't find myself in the situation where I have 1000 tabs open anymore. This is a user problem to some extent, I could always just close tabs, but Postman's design really encourages it.
Using Vim keybindings means I automatically get a more keyboard centered workflow.
Once I'm done editing the Hurl files, I can run them however I want. It was easy to integrate into Neovim, it's easy to integrate it into a CLI, and it would be easy to integrate it into anything that can run command line tools.

This setup also let me take advantage of the entire neovim plugin ecosystem.

I get highlighting from Treesitter. There's already support for hurl files, and by setting the file type of the response we get highlighting there as well.
If there's an LSP running, it can be used on the response. There's no support Hurl files yet, but it's convenient when you need to format json responses for example.
I've already mentioned it, but fuzzy finding in Neovim is great.

The plugin also offers additional features for hurl, like being able to swap in
and out variable files with
Hurlsvf {variables_file}.

This lets you change URL like in the demonstration above, but could also be used
to quickly and easily change OAuth tokens for example.

It also offers a way to interactively explore APIs with a command named
CurlGoFromCursor. It runs a simple curl command from your cursor allowing you
to quickly navigate through links in RESTful APIs.

Because the Hurl file is just text, and the response is just text,
it’s very easy to add functionality to the plugin and very easy to
integrate into an existing workflow. Hurl might not have all the features
of some of its GUI competitors at the moment, but it doesn't need those
features if it's so easy to integrate it into other tools that have those
features.

Should you create new constants for tests

Ethan Carlsson — Wed, 10 Aug 2022 18:02:28 +0000

Yes and no. It depends on what you are testing.

If the constant is part of a public API it should probably be tested. But
otherwise you're just making your tests more flaky.

Where it makes sense

If you have

class Currency { 
    public static readonly EUROS = 'EUR'
}

It might be acceptable to write a test like

test('Currency.EUROS is EUR', () => {
    expect(Currency.EUROS).toBe('EUR');
})

In most cases this is overkill. But if your dealing with something where the
string of a currency matters a lot it might be make sense to write a test like this.

Where it doesn't make sense

It could be argued that you implicitly get the value of the test above by using
the constants directly inside other tests like this:

class CurrencyLocaleService {
    getCurrencyForLocale(locale: string): string {
        if (locale === Locale.SPAIN) {
            return Currency.EUROS
        }
        ...
    }
}

...
describe('CurrencyLocaleService', () => {
    const SPAIN_LOCALE = 'es_ES'

    const CURRENCY_EUR = 'EUR'

    test('getCurrencyForLocale with spain locale, returns euros', () => {
        const sut = new CurrencyLocaleService();
        expect(sut.getCurrencyForLocale(SPAIN_LOCALE)).toBe(CURRENCY_EUR);
    })
})

This way we implicitly get the benefit of the first test. If the above test fails,
it will also mean that Currency.EUROS has been changed.

What's more we are also implicitly checking the correctness of Locale.SPAIN, so
if that ever changes this test will also fail.

In this way, the above test proves the correctness of the program a lot better than
this one:

describe('CurrencyLocaleService', () => {
    test('getCurrencyForLocale with spain locale, returns euros', () => {
        const sut = new CurrencyLocaleService();
        expect(sut.getCurrencyForLocale(Locale.SPAIN)).toBe(Currency.EUROS);
    })
})

However, I like this test better because it only tests the one thing. We might have
a legitimate reason to change the values of these constants, maybe some external
API needs currency to be in lower case 'eur'. If that's the case then a test
that checks that getCurrencyForLocale with spain locale, returns euros should not
fail, because while the string has changed Currency.EUROS still means the same thing.

Maybe we will need to change our first test to this

test('Currency.EUROS is eur', () => {
    expect(Currency.EUROS).toBe('eur');
})

But not both tests.

Tests aren't really about proving that your code is correct

I think the reason people like to write tests like this

describe('CurrencyLocaleService', () => {
    const SPAIN_LOCALE = 'es_ES'

    const CURRENCY_EUR = 'EUR'

    test('getCurrencyForLocale with spain locale, returns euros', () => {
        const sut = new CurrencyLocaleService();
        expect(sut.getCurrencyForLocale(SPAIN_LOCALE)).toBe(CURRENCY_EUR);
    })
})

Is the belief that the goal of our tests exist to show correctness and protect
the code from becoming incorrect. If someone comes along and changes the value
of Currency.EURO all our tests will fail and there's no chance that the code
will make it to production.

However, we will need to change the code, and that doesn't mean that the code is now
wrong.

Tests aren't really about showing that your code is correct, I don't think. They're
about expressing what we expect our code to do. If I make a change to existing
code the tests should fail, but only to the extent that our expectations have changed.

If I change Locale.SPAIN from 'es_ES' to 'es-ES', this test should fail

test('Locale.SPAIN is "es_ES"', () => {
    expect(Locale.SPAIN).toBe('es-ES');
})

if it exists, because the expectation changed. But no other test should fail.

Don't write Conditional Logic in Tests

Ethan Carlsson — Mon, 25 Jul 2022 15:30:07 +0000

Conditional logic should not go in tests

This is one of the most important rules in
writing good tests.

You should be suspicious of any test that includes constructs like
if, while, for, try or anything similar that your language might have.

There are two main reasons for this

1. It forces you to read the code

I shouldn't have to read the code to know why a test failed

import {expect} from 'vitest';
...
test('JacketAdvisor', () => {
    ...
    if (weatherOutside === 'cold') {
        expect(sut.shouldBringAJacket()).toBeTruthy()
    } else {
        expect(sut.shouldBringAJacket()).toBeFalsy()
    }
})

The above code is reasonably easy to read, but if the test fails I will get this
message

FAIL  path/to/tests > JacketAdvisor
AssertionError: expected true to be falsy

and I'll have to open the code to figure out why it failed.
Each case should be handled in a different test


import {describe, expect} from 'vitest';

...

describe('JacketAdvisor', () => { 
    test('with cold weather shouldBringAJacket returns true', () => {
        ...
        expect(sut.shouldBringAJacket()).toBeTruthy()
    })

    test('without cold weather shouldBringAJacket returns false', () => {
        ...
        expect(sut.shouldBringAJacket()).toBeFalsy()
    })
})

This way when the test fails I'll have something like this:

FAIL  path/to/tests > JacketAdvisor > with cold weather shouldBringAJacket returns true
AssertionError: expected true to be falsy

And I'll know immediately why the test failed.

2. It introduces untested code

This is maybe the more insidious problem. If you have untested logic that you use
to test your code, you have no tests that confirm you are actually making the
correct assertions.

For example if I accidentally set weatherOutside to 'col' in the second example
above, the first test will fail. But in the second example, this code expect(sut.shouldBringAJacket()).toBeTruthy()
will just never run. I won't know that the code was wrong until it hits production
because the test code was wrong and had a bug.

But I need conditional logic for some assertion

Most of the time when you think you need to add conditional logic what you really
need to do is properly isolate your system under test. But there are exceptions where
it does make sense to introduce conditional logic.

1. You're working with legacy code

When it comes to legacy code all rules go out the window. If you need to add a
bit of logic to set up a test harness and make it possible to safely refactor
that code, then just do it. Don't let the perfect get in the way of the good.

Just remember that it's temporary. When you've refactored the system to the
point where it's components can be tested in isolation test those components and
delete the old tests.

2. Your writing a testing library or a custom assertion

It's actually impossible to have a test with no conditional logic
because under the hood all assertions look something like this:

function assertTruthy(val) {
    if (val == false) {
        throw new AssertionError({message: 'expected true to be false'});
    }
}

Instead of "Don't write Conditional Logic in Tests" the rule should probably be
"Test code should never have logic that branches beyond one level and should only
branch in order to make an assertion"(of course, that's not a very good title though).

If you need to, you can write your own custom assertions with conditional logic
inside them to use in your tests. This is allowed because unlike a test an assertion
can be tested very easily without your tests becoming absurd.

Just remember to write a test that asserts that your assertion throws the right
exceptions and avoid overly complex branching logic inside those assertions.

These are exceptions though, conditional logic should still be treated as a smell,
you shouldn't write a bunch of custom assertions to get around this rule.

Using Git Hooks To Run your Tests and/or Linter

Ethan Carlsson — Wed, 20 Jul 2022 06:07:00 +0000

If you're looking to set up a simple way to run
code before each commit in a pre-commit hook for
a Javascript project, this is how I did it.

Setup

Hooks don't actually depend on anything other than git, but
I'm using vite and yarn in this project.
It would work the same with any build tool,
and if you use npm just replace yarn [command] with npm run [command].

For the hook to work you need to write this code in
{YOUR_PROJECT_ROOT}/.git/hooks/pre-commit.
So to get started write one of the following into your
terminal from your project root:

For vim: vim .git/hooks/pre-commit

For nano: nano .git/hooks/pre-commit

For VS Code: code .git/hooks/pre-commit

Or create and edit the file in whatever other way you like.

Code

#!/bin/bash

yarn lint
linting_result=$?

if [[ $linting_result -ne 0 ]]
then
  echo "LINT FAILED!"
  echo 'Please fix linting problems before committing.'
  exit 1
fi

yarn test
test_result=$?

if [[ $test_result -ne 0 ]]
then
  echo "TESTS FAILED!"
  echo 'Please make sure tests pass before committing.'
  exit 1
fi

The yarn test and yarn lint commands work exactly the same as
they do when called from the command line at the root of my project.

I get the exit code and check to see if it equals zero here:

linting_result=$?

if [[ $linting_result -ne 0 ]]

if it doesn't equal 0 (-ne 0), I echo a message
and exit the bash code with another non-zero exit code,

then
  echo "LINT FAILED!"
  echo 'Please fix linting problems before committing.'
  exit 1
fi

If either the tests or the linter fail they exit
with a code of 1. But if it exits with a different code
I'd like to know why, so I exit with anything non-zero and don't
let the commit go forward.

Next steps

All you need to do now is run chmod +x .git/hooks/pre-commit, to make the code executable,
and the code will run on every commit.

Check out the documentation and add
whatever other hooks you like. I run the same code on push as well using
the pre-push hook for example

Build a Vite Plugin to Inline Critical Resources

Ethan Carlsson — Wed, 13 Jul 2022 06:05:17 +0000

Vite's defaults will lead to your page loading slower than it needs to.
Vite will build your html to look something like this.

...
<head>
...
<script type="module" crossorigin="" src="myJavascript.js"></script>
<link rel="stylesheet" href="myCss.css">
</head>
...

The browser will find these two tags in the head and then have to request them and
evaluate them before it can continue rendering the page. This means that your
users will just be staring at a blank screen for a couple of seconds, especially
on a slow connection or before any caching.

This is a good default. Most modern websites have some JavaScript or
CSS that is critical for rendering the page correctly, but Vite has no way of
identifying what is critical. So it will load it all at the top to make sure it
doesn't miss anything.

But we do know what is critical, so we should defer everything that is not critical,
so we can render early with only the critical assets. Modern advice is to inline those
critical elements. This great article,
that you've probably run into thanks to chromes dev tools, suggests this pattern:

<style type="text/css">
.my-critical-css {...}
</style>

<link rel="preload" href="myCss.cs" as="style" onload="this.onload=null;this.rel='stylesheet'">
<noscript><link rel="stylesheet" href="myCss.css"></noscript>

And we can do the same thing for JavaScript even more easily.

<script>
    runCriticalJS();
</script>

<script type="module" crossorigin="" src="myJavascript.js" defer></script>

Implementation

JavaScript

Implementing this in JavaScript was very easy for my site because I don't have a lot
of JavaScript and most of what I do have is not necessary for rendering.

the only thing that is critical is my themes. I allow users to change themes and
colour preferences and store that information in local storage.
So I need to check that the user's preference before rendering anything, otherwise, there will be a flash of incorrectly styled content.

So to solve this I can just minimise the relevant JavaScript and put it
all inside a script tag in the head.

<script>
var themePref=window.localStorage.getItem("theme-preference");themePref&&document.querySelector(":root").setAttribute("data-theme",themePref)
</script>

Then I defer the rest.

<script type="module" crossorigin="" src="/assets/main.57999a66.js" defer></script>

To do this last bit I wrote a tiny plugin that finds the script file and adds a
defer attribute to the end of it.

// deferNonCriticalJS.ts
export function deferNonCriticalJS(html: string): string {
    const jsRegex = /\n.*<script type="module" /;
    const nonCriticalJs = html.match(jsRegex);
    if (nonCriticalJs === null ) {
        return html
    }

    const deferredJs = nonCriticalJs[0] + 'defer ';

    return html.replace(jsRegex, deferredJs)
}

// criticalPlugin.ts
import {deferNonCriticalJS} from './criticalJS';

export default function (criticalCssDir: string) {
    return {
        name: 'html-transform',
        async transformIndexHtml(html: string) {
            return deferNonCriticalJS(html)
        }
    }
}
// vite.config.ts
export default defineConfig({
...
    plugins: [
        critical(),
    ]
...
}

Inline CSS

I could technically do the same for the CSS. However, there is a lot more css,
and it's more likely to change. So I need an automated solution.

To do this I decided to separate my CSS into critical and non-critical directories.
Then I loop through every file in the non-critical directory, minify the content
and return a string with all the CSS in it.

export async function findAndMinifyCritical(dir: string): Promise<string> {
    let criticalCss = '';

    fs.readdirSync(dir).forEach(file => {
        const f = `${dir}/${file}`;
        const content = fs.readFileSync(f).toString();
        criticalCss += csso.minify(content).css;
    });

    return criticalCss;
}

Then I append the critical css to the end of the head tag

export function inlineCritical(html: string, critical: string): string {
    return html.replace('</head>', `<style>${critical}</style></head>`);
}

Finally, I defer the non-critical CSS.

export function deferNonCritical(html: string): string {
    const styleRegx = /\n.*<link rel="stylesheet" href=".*">/;
    const nonCriticalCss = html.match(styleRegx);
    if (nonCriticalCss === null) {
        return html;
    }

    const nonCritCss = nonCriticalCss[0]
        .replace(
            'rel="stylesheet"',
            'rel="preload" as="style" onload="this.onload=null;this.rel=\'stylesheet\'"');

    return html.replace(
        styleRegx,
        nonCritCss + `<noscript>${nonCriticalCss}</noscript>`
    );
}

Putting it all together

To put it all together I create this function

import {deferNonCritical, findAndMinifyCritical, inlineCritical} from './criticalCss';
import {deferNonCriticalJS} from './criticalJS';

export async function deferAndInline(html: string, criticalCssDir: string): Promise<string> {
    const htmlWithDefferredJs = deferNonCriticalJS(html);
    return inlineCritical(
        deferNonCritical(htmlWithDefferredJs),
        await findAndMinifyCritical(criticalCssDir)
    )
}

And I call it within the plugin

export default function (criticalCssDir: string) {
    return {
        name: 'defer-and-inline-critical',
        async transformIndexHtml(html: string) {
            return await deferAndInline(html, criticalCssDir)
        }
    }
}

Which finally lets me add it to my config

plugins: [
    {
        ...critical(__dirname + '/src/criticalCss'),
        apply: 'build'
    },
]

I only run it on build because it slows down dev a lot. I could improve the
code speed, but it wouldn't be worth it, most of the slowdown comes from
looping through a directory full of CSS files and reading them all.

Conclusions

If you're working on a larger project you'll probably want to look into packages like
critical.

But for a personal project or if you need fine-grained control over how critical
assets effect rendering, you can learn a lot by trying to set something like this
up for yourself.