Olivia Coumans' Blog

Using Vim with VSCode

2022-01-03T00:00:00Z

In this post, I’ll share tips on using the Vim plugin in VSCode. It’s an excellent way to explore a different editing style and get a feel for Vim without leaving your current setup. The plugin provides access to Vim’s modes and motions with minimal configuration.

I originally started using Vim to rely less on my mouse, and it’s made a huge difference. These days, I regularly switch between VSCode (with the Vim plugin) and Neovim, and having Vim baked into my daily workflow makes that back-and-forth feel seamless. Plus, editing with Vim is fun! If you're considering trying it, let’s dive in.

Installation

First, install the plugin Vim. Once you relaunch your code editor and open a file, you’ll see NORMAL in the bottom bar - one of Vim’s modes. Your cursor will also look a bit different.

Remember Vim and its modes

Vim has several modes, each with its keyboard shortcuts and motions. The four most common are:

Normal mode (also called "Command mode"): This is the mode you'll use most of the time. In Normal mode, you can navigate your file with commands like g and gg, search for text (e.g., /Gary to search for that name), and more.
Insert mode: This is where you write text. To enter Insert mode, press i. You’ll use this mode whenever you want to add or modify code.
Visual mode: This mode is the equivalent of selecting text with your mouse. To enter Visual mode, press v. You can select an entire line by pressing V while in Visual mode.
Last line mode: Access this mode by pressing :. It allows you to run commands like opening a file (:e filename), saving a file (:w), and exiting Vim (:q).

Learning vim

If you're new to Vim, vimtutor is an excellent resource to get started. It’s an interactive tutorial that covers the basics and helps you become comfortable with the editor. Once Vim is installed on your computer, you can access the tutorial anytime by typing vimtutor in your terminal.

Additionally, I highly recommend this Youtube playlist by the Primeagen. This series of videos provides practical insights and tips to help you get comfortable with Vim more quickly.

Basic settings

Now that you have Vim installed and running, let’s configure it to fit your workflow. To improve your Vim experience, you can customize a range of settings, like the leader key or enabling relative line numbers.

In traditional Vim, you configure Vim settings in a vimrc file, where you define key mappings, plugins, and various preferences. In VSCode, you can enable a similar setup using the vim.vimrc.enable setting, which allows you to use a vimrc file to configure your Vim plugin. However, I prefer configuring Vim settings directly within VSCode’s settings.json, as it feels more integrated with the VSCode environment.

The leader key in Vim is combined with other keys to create custom keyboard shortcuts, especially in normal mode. As you get more comfortable, you’ll likely create "remaps”, shortcuts for common actions like toggling the sidebar or quickly switching between files.

In VSCode, you can define your shortcuts and pick a leader key, with , and space being popular choices. Feel free to experiment and see what works best for you.

Here’s how I configure my Vim settings in settings.json:

// settings.json
{
  "vim.leader": " ",
  "vim.hlsearch": true,
  "vim.useSystemClipboard": true,
  "vim.smartRelativeLine": true
}

"vim.leader": " ",: Sets the spacebar as my leader key, which triggers custom keyboard shortcuts.
vim.hlsearch: Highlights search results when you search with / in normal mode, making it easier to spot matches.
vim.useSystemClipboard Ensures you can copy and paste between Vim and your system clipboard (no need to use extra commands like *y).
vim.smartRelativeLine: Displays the current line number and other line numbers relative to your position. This speeds up navigation and makes it easier to jump between lines. For example, 2k will take you two lines up from where you are. This one was a life-changer for me!

Creating custom shortcuts

Remaps are the secret sauce when using Vim as your primary code editor. They allow you to associate the actions you often perform with keyboard shortcuts. In VSCode, you can add custom shortcuts in your settings.json. The Vim plugin allows you to add custom keybindings per mode:

vim.normalModeKeyBindingsNonRecursive: Custom keybindings for Normal mode.
vim.visualModeKeyBindingsNonRecursive: Custom keybindings for Visual mode.
vim.insertModeKeyBindingsNonRecursive: Custom keybindings for Insert mode (I don’t use this, but it's available).

Here are some of my shortcuts:

  "vim.normalModeKeyBindingsNonRecursive": [
    {
      "before": ["<leader>", "n"],
      "commands": ["workbench.action.toggleSidebarVisibility"]
    },
    {
      "before": ["<leader>", "r", "r"],
      "commands": ["editor.action.rename"]
    },
    {
      "before": ["K"],
      "commands": ["editor.action.showHover"]
    },
    {
      "before": ["<leader>", "r", "f"],
      "commands": ["fileutils.renameFile"]
    },
    {
      "before": ["<leader>", "p", "s"],
      "commands": ["fuzzySearch.activeTextEditor"]
    }
  ],

Breaking down the commands

before: This is the key combination you press to trigger the action. Each key combination is an array of keys you press in sequence. For example, <leader> + n means pressing the leader key followed by the letter n.
commands: These are predefined VSCode actions or commands triggered by your custom keybinding. You can assign these to do anything from toggling visibility to renaming files.

For example, I use the rename action quite a lot. It is usually triggered by F2, but I found that shortcut awkward. So, I created a custom shortcut with <leader> + r + r that feels more comfortable and matches a keymap I have in Neovim.

A few favorite custom keymaps

In my settings.json, I have a few favorite keymaps:

Toggle Sidebar visibility: <leader> + n toggles the sidebar visibility. I use this one quite often.
Rename: <leader> + r + r saves me some time since I don't often use the function key.
Show Hover information: K shows detailed hover information for a function or variable. This is the keyboard equivalent of hovering over a function or variable with your mouse.

Keymaps using extension capabilities

You can get quite creative when defining your keymaps. You can leverage some extensions you've added. For instance, I have custom keymaps for:

Renaming a file: <leader>+r+f renames the current file using the file util extension.
Fuzzy search: <leader> + p + s triggers a fuzzy search in the active text editor using the fuzzy search extension.

Explore and customize

It can quickly become a rabbit hole, but that's part of the beauty of using Vim. There is complete documentation of all the existing keybindings in VSCode. A good exercise is to review the default keybindings and see if there are any you commonly use that could be further customized or improved.

Extending Vim power with some plugins

Vim in VSCode supports several built-in Vim plugins that enhance what Vim can do.

One plugin I highly recommend enabling is vim-surround. It makes working with brackets, quotes, and tags much faster. You can quickly change or delete surrounding characters with just a few keystrokes.

To enable it, go to your settings and search for Vim: Surround. You'll see a checkbox to turn it on.

Once enabled, here are a few examples of what you can do while in normal mode:

Change single quotes to double quotes: cs'"
Rename an HTML tag: cst.

It's a small plugin, but once you get used to it, it'll feel like a must-have! You can check out more examples in the official documentation.

Some of my favorite Vim motions

One of the first big challenges when getting started with Vim is to try to stay in Normal mode as much as possible. This is the key to becoming fast and efficient with Vim.

Here are some of my go-to motions in Normal mode:

gg: Jump to the top of the file
G: Jump to the bottom of the file
f and F: Move to a specific character on the current line (f searches forward, F searches backward). For instance, in the line Hello there, typing ft from the start of the line moves your cursor to the t in there.
zz: Center the current line in the viewport
0w: If you're mid-line or at the end, this brings you back to the start of the line, then moves to the first word
D: Delete everything from your cursor to the end of the line
dd: Delete the entire line
cc: Delete the line and immediately enter Insert mode on the same line
<number>k or <number>j: Move up or down multiple lines
cit: When editing HTML, this puts you into Insert mode inside a tag and deletes the existing content (Small warning: this is very powerful but will remove any current content inside the tag!)
u: Undo your last action (a lifesaver when things don't go as expected...)

Getting used to these motions can be a mental workout at first. However, with practice, they quickly become second nature!

Vim also supports text objects, which makes it easy to edit things like words, quotes, or parentheses, no matter where your cursor is inside them. For example, ci" changes everything inside quotes, and da( deletes everything around a set of parentheses. It takes some time to get the hang of it, but once you do, the benefits of using Vim become clear!

Bonus: moving a code block up or down in visual mode

I remember watching a React presentation by Ryan Florence, where I first saw this trick. During the talk, he highlighted a code block in visual mode and moved it up and down without cutting and pasting. If you want to do the same in VSCode with Vim, add these to your settings.json:

  "vim.visualModeKeyBindings": [
    {
      "before": ["J"],
      "commands": ["editor.action.moveLinesDownAction"]
    },
	  {
      "before": ["K"],
      "commands": ["editor.action.moveLinesUpAction"]
    }
  ],

Now, you can select a block of code in visual mode and move it up with K or down with J. Awesome stuff!

Conclusion and further resources

If you're interested in testing out Vim, the plugin in VSCode is a great place to start. Once you're more comfortable with the basics, there are many resources to help you dive deeper into the Vim world:

VimTricks
ThePrimeagen YouTube channel
Changelog has some great podcast episodes about vim

My current VSCode settings and keymaps are in my dotfiles.

And if you're curious about trying out Neovim, I have a repo with my current Neovim config, which will continue to evolve.

I hope you find this blog post helpful. If you have any questions or want to chat about Vim, feel free to reach out on Bluesky 😀

Search for a string in your git history with git log

2022-01-07T00:00:00Z

Recently, I discovered a useful functionality of git log while cleaning up some code. You can pass an option to git log to get back a list of all the commits that changed a particular string. Let's explore that feature!

Using `git log -S`

If you want to find all the occurrences of a specific string in your git history, git log -S is perfect for the job.

For example, if you look for a particular component in a React app, you can type:

git log -S ContentWrapper

It will return a list of all the commits where that string appears:

commit ab68707f03a5636c399213194a32c29d631e7c2b
Author: Olivia Coumans <my_email@email.com>
Date:   Tue Jan 4 11:03:34 2022 +0100
  feat(styles): create PageContentWrapper comp

commit 5e79c7fa417c5a58b7b6c6bfb71de318686a6210
Author: Olivia Coumans <my_email@email.com>
Date:   Thu Dec 30 12:57:15 2021 +0100
  feat(footer): add site footer

You can then use git show [COMMIT_HASH] to display the content of a commit with all the diffs.

git show ab68707

Bonus: list all the commits that modified a file

git log -p FILE_PATH is a quick way to list all the commits that modified a specific file.

Don't hesitate to pass flags to customize the output of git log:

git log --name-only --oneline -p ./components/SiteHeader/SiteHeader.tsx

The above example will only display the hash and the name of each commit that modified the file.

Conclusion and further resources

With git log and some of its options, you can quickly find out when some piece of code was removed or added while staying in your terminal. I hope it will be helpful for you too!

Some further resources:

Exploring generics and generic constraints in TypeScript

2022-01-14T00:00:00Z

Generics can be hard to grasp when first learning TypeScript. This post will review what generics are and why we use them. We'll then move on to explore generic constraints. They are a handy trick to keep in mind to build more type-safe code.

Generics as a superpower to build reusable code

The whole idea behind generics is to write functions or data structures that can work with many different types depending on the context.

The most common example to introduce generics is the identity function. The sole goal of this function is to return the argument it receives.

function identify(value) {
	return value;
}

If you have strict enabled in your tsconfig, the code above will cause a type error. It will tell you that value has the implicit type of any. The first approach to fixing this issue is to make value an any type explicitly.

function identity(arg: any) {
	return arg;
}

One problem with this approach is that you lose all type safety. By making value a type of any, the return value of identity will also be of type any. If you store it in a variable, this variable will also be of type any, which could cause some type errors.

const name = identify("Lisa"); // name will be of type `any`
const total: number = name; // would not throw a type error

We want TypeScript to infer the type of the argument. That's when generics come to the rescue.

function identity<T>(arg: T): T {
	return arg;
}

const name = identity("Lisa");
// will infer that T = string
// identity<string>("Lisa");

You can think of a generic as a placeholder or a variable that TypeScript will fill with the correct type information later. In this example, when you invoke identity, TypeScript will fill the blanks and replace the generic T with a concrete type (string in the case of the example).

A real-life example of generics

Let's imagine we want to build a helper function to get the difference between two arrays. Some criteria for our helper function:

We want this function to be reusable with all arrays, no matter what elements they contain.
We want to make sure that both arrays contain the same type of elements.
We want to pass a function filterFn that we can use to filter the lists.

function getArrayDifference<T>(
  prevList: T[],
  currList: T[],
  filterFn: (el: T, list: T[]) => boolean
): T[] {
    const removedElements = prevList.filter(el => filterFn(el, currList));
    const addedElements = currList.filter(el => filterFn(el, prevList));

    return [...removedElements, ...addedElements];
}

Let's try this function. Let's imagine we want to use it to get the difference between two lists of tags.

interface Tag {
	id: number;
	name: string;
}

const prevTags = [
	{id: 1, name: 'TypeScript'},
	{id: 2, name: 'Svelte'}
]

const currTags = [
	{ id: 1, name: 'TypeScript'}
]

const tagFilterFn = (tag: Tag, listOfTags: Tag[]) => {
    return listOfTags.findIndex(el => el.id === tag.id) < 0;
};

const diff = getArrayDifference(prevTags, currTags, tagFilterFn);
// TypeScript replaces T with Tag
// getArrayDifference<Tag>
// we get back [{id: 2,  name: "Svelte"}]

If you inspect the getArrayDifference in this example, you will see that TypeScript considers T to be Tag.
It returns a list of Tag. diff will be of type Tag[]. If we had used any in our helper function definition, diff would have been of type any as well, and we would have lost all the advantages of using TypeScript.
Thanks to generics, we also have some type safety for our filterFn. In the above example, its first argument must be of type Tag, and its second argument must be a list of tags.

Generics make our function type-safe and reusable with other types. We could use our helper with arrays of numbers.

const otherDiff = getArrayDifference([1, 2, 3], [2, 3], (curr, list) => !list.includes(curr));
// T = number
// returns [1]

Now that we are well immersed in generics, let's explore generic constraints!

Generic constraints or generics with limitations

The whole idea behind generic constraints is to limit the possibilities of the types a generic can represent. Generics are like wildcards. However, we could already know that we want the type to have specific properties from the get-go. You can create a generic constraint with the extends keyword. Let's have a look at some typical use-cases for generic constraints.

Usecase #1: you want to use a specific property on a generic type

Let's say we want to write a function that filters a list by id and pretty-prints the result. This function should be generic because we want it to be reusable with many different types.

At first, we might write something like:

function findByIdAndPrint<T>(list: T[], id: string) {
	// The line below will cause a type error
	const itemToPrint = list.find(item => item.id === id);

	if (itemToPrint) {
		console.log(JSON.stringify(itemToPrint, null, 2));
	} else {
		console.log('No item found');
	}
}

This won't work. TypeScript will throw a type error Property "id" does not exist on type "T". We have to tell TypeScript that T will have an id property no matter what.

interface HasId {
	id: string
}

// we could also inline the constraint with T extends {id: string}
function findByIdAndPrint<T extends HasId> {
	const itemToPrint = list.find(item => item.id === id);

	if (itemToPrint) {
		console.log(JSON.stringify(itemToPrint, null, 2));
	} else {
		console.log('No item found');
	}
}

What does extends do?

It tells TypeScript that T must have a property id.
extends also means that our type T is not limited to having only a property id and can have many more.
We constraint our generic so that this function won't work with any type without an id property.

Usecase #2: Create a relationship between two generics

You might have come across the keyword keyof. keyof is an operator that returns a union of all the keys of an interface or type.

interface Person {
	name: string;
	age: number;
}

type PersonKeys = keyof Person // 'name' | 'age'

How does it relate to our generic constraint? Let's say we have a function that acts as a getter for a property on an object.

Our first approach might be to just write it without any generics:

function getPropertyValue(obj: Record<string, unknown>, key: string) {
    return obj[key]
}

Record is a utility type that creates an object type. The problem with this approach is that we can pass just any string as a second argument. And we might want only to allow the user to give a key that exists on the object.

Generics and generic constraints to the rescue!

function getPropertyValue<T extends Record<string, unknown>, K extends keyof T>(obj: T, key: K) {
	return obj[key]
}

We first constraint T to tell TypeScript that this will be an object. unknown is an excellent alternative to using any as it is more restrictive.
We then pass a second generic K. We directly limit what K can represent with extends. We use keyof to tell TypeScript that K will be a key of T.

getPropertyValue({ name: 'Ryan', age: 26 }, 'name'); // 'Ryan'

// this code will throw a type error
getPropertyValue({ name: 'Lisa'}, 'country');

In this case, we use generic constraints to create a relationship between two generics that, otherwise, could stand for any type and be entirely independent of one another.

Conclusion

In this post, we explored generics and generic constraints. We saw a few examples of how much power generics give us as typescript developers to make our code more flexible, reusable, and type-safe.

Some useful resources to go deeper:

An overview of the unknown type in Typescript

2022-01-21T00:00:00Z

Typescript's version 3.0 introduced a new type, unknown. Contrary to any, we do not opt out entirely from the type system by assigning a type unknown to a value. This blog post will explore the purpose of unknown and some key differences between unknown and any.

Purpose of unknown

The purpose of unknown is similar to any. It is used to represent any possible value. We might want to write a helper function that takes any possible type as an argument. Or we might not know when writing our program what type of value a particular variable will hold at runtime.

It is an excellent alternative to using the infamous any type. Even though it might do something similar to any, they are critical differences between both. To understand those, let's first review some of the pitfalls of using any.

The multiple risks of using `any`

If we explicitly give an any type to a value, we can then assign it to any variable, no matter their type.

const ourValue: any = 'hello';

// we can assign it a variable supposed to contain a number
const importantNumberVal: number = ourValue;

// we can assign it to a variable supposed to
// contain an array of strings
const listOfNames: string[] = ourValue;

This code is perfectly valid Typescript code. However, we know it will cause all sorts of errors down the line. We can also use our value typed any with a function that requires a specific type of argument to work correctly.

interface Person {
	name: string
}

// we could use it with a function that has a specific type signature
function greetPerson(person: Person): string {
	return `Hello ${name}`;
}

const problematicValue: any = 12;
// will not throw any errors or warnings
greetPerson(problematicValue);

These two examples are only reminders that while any can be very convenient, we must remember its tradeoffs too. While we gain flexibility, we give up most of the benefits of using Typescript.

`unknown`, a type-safe alternative to `any`

unknown is much more restrictive than the type any. Let's revisit an earlier code example, replacing any with unknown.

const ourValue: unknown = 'hello';

// type error here
// Type 'unknown' is not assignable to type 'number'
const importantNumberVal: number = ourValue;

// another type error :)
// Type 'unknown' is not assignable to type 'string[]'
const listOfNames: string[] = ourValue;

We can no longer use ourValue in all situations. The general rule is that you can only assign a value of type unknown to a variable that is any or unknown. But how do we use it then?

Type narrowing to use a type `unknown` value

You can only assign a value of type unknown to a variable that has the type unknown or any. But, in our example, our variable importantNumberVal holds a number type. In that case, the only solution is type narrowing. We need to do some runtime checks to use our value.

If we wanted to use it to assign it to a constant that holds a number, we would need first to check that it is of type number.

const ourValue: unknown = 'hello';

if (typeof ourValue === 'number' && !Number.isNaN(ourValue)) {
	// it works!
	const importantNumberVal: number = ourValue;
}

Using unknown means doing this extra check. It is virtually unusable until we narrow what type it is. However, in the above example, we keep our code type-safe. But, like most good things, it requires some extra work.

Using `unknown` to regain some type safety

One interesting technique is to assign a value of type any to a variable of type unknown. We can restrict what we can do with this value in our program this way.

Let's imagine we want to use a function from an external package. The function has a return type of any for the specific helper we wish to use. If we are ok with eventual type errors and have a degree of certainty about the return value, we might assign it to a variable of type any.

import { getValueFromPackage } from 'some-awesome-npm-package'

function printNameInfoToTheUser(): void {
	const data: any = getValueFromPackage()

	// name will have the any type
	const { name, count } = data
	const humanReadableCount = count + 1;

	// some more code...
	console.log(name);
	console.log('Total count:', humanReadableCount);
}

The problem with using any is that it spreads. In the example, we can destructure data without any warnings from Typescript, even though those properties might not exist. Moreover, name and count will also have the any type. Even if this example is a little contrived, this will often cause some issues in a more realistic scenario. The package we use might change its schema and return an object that no longer has a name property. Or we could make a typo and spell one of the properties wrong.

Using a variable of type unknown to store the return value of the third-package function is an excellent way to gain some type safety.

function printNameInfoToTheUser(): void {
	const data: unknown = getValueFromPackage()

	// Warning: This will throw some type errors
	// Property 'name' does not exist on type 'unknown'
	// Property 'count' does not exist on type 'unknown'
	const { name, count } = data
	const humanReadableCount = count + 1;

	// some more code...
	print(name);
	print('Total count:', humanReadableCount);
}

By replacing any with unknown, we no longer can destructure data. Typescript yells a little at us by throwing two type errors: Property 'name' does not exist on type 'unknown' and Property 'count' does not exist on type 'unknown'.

To use the return value, we need to be more specific about what value it holds. We can solve this issue using type guards and a little generic helper.

// helper to check that a key exists or not on an object
function hasProperty<T extends object, K extends string>(
  obj: T,
  propertyName: K
): obj is T & Record<string, unknown> {
  return propertyName in obj;
}

function printNameInfoToTheUser(): void {
  const data: unknown = getValueFromPackage();

  // type safety has a price...
  if (
    typeof data === 'object' &&
    data !== null &&
    hasProperty(data, 'name') &&
    hasProperty(data, 'count')
  ) {
    // both will be of type `unknown`
    const { name, count } = data;

    // type-checking count to avoid calculation errors
    let humanReadableCount = 0;
    if (typeof count === 'number' && Number.isNaN(count)) {
      humanReadableCount = count + 1;
      console.log('Total count:', humanReadableCount);
    }

    if (typeof name === 'string') {
      console.log(name);
    }
  } else {
    // throw or show other message
  }
}

In our example, getValueFromPackage is supposed to return an object. By assigning it to unknown, we make it unusable in the rest of the code, unless we restrict what type of value it contains.

hasProperty is a type predicate. A type predicate is a function that returns a boolean whose value will determine the types inferred by Typescript. For example, typeof is a built-in type predicate. When you use it inside an if statement (e.g. typeof val === 'number'), Typescript will infer that val is a number in the entirety of the if block. In our case, when hasProperty returns true, Typescript will infer that the key we were looking up on our object is of unknown type.

Let's dissect the multiple conditions in the if statement:

typeof data === 'object' enables us to already tell Typescript that this value is an object.
Because null happens to be an object in JavaScript, we need to tell Typescript that data is an object and not null.
We then use a type predicate hasProperty to confirm that both count and name are present on our object.

Inside of our if block, we still need to restrict further the count and name values to use them because they are both unknown.

This example shows how we can regain some type of safety if we use an external package with many any types. However, it is really up to you to evaluate whether going through those steps is worth it.

Conclusion and further resources

In the wild, you will see many packages use any in their type definitions. Because unknown was introduced only in the v3 of Typescript, they are many codebases that do not use it heavily. However, it can serve us well to use it instead of any. It enables us to avoid some of the pitfalls of using any. However, as seen in our last example, it can also bring many extra steps and type checks. My rule of thumb is always to use unknown first before using any. When writing helper functions, for instance, it can help avoid accidentally using the argument value without doing any type checks first. I hope this post was a little helpful to you!

Here are some valuable resources:

Getting started with tmux

2022-02-05T00:00:00Z

Apart from its cool name, tmux is also a great tool to make your developer life easier. In this post, we'll look at the purpose of tmux and some basic terminology. We'll write a tmux configuration that is enough to start using it and look at the most common commands.

Why use tmux?

Have you ever gotten lost switching between a tab in iterms where you run your tests while another tab runs your application (and a third one runs the backend)? Or do you have to work with a couple of repositories at once and have multiple terminals opened at the same time? tmux is a terminal multiplexer. The whole purpose of tmux is to make your life easier running and switching between different programs in one terminal.

Some basic terminology

Let's look at different critical terms before diving deeper into using and configuring tmux.

A session in tmux gets created when you start tmux in your terminal. You can run multiple sessions at once (though only one is visible at a time, the others will be detached). Each session contains its own set of windows and panes.

A window is your entire terminal window. A pane is what you create when you split your terminal window vertically or horizontally. Tmux enables you to make those splits and windows with whatever keymap you choose. You can also script it all (see the last section at the end).

A tmux window:

A tmux pane:

Installing tmux and running it

First, make sure you have tmux installed on your system. Check out the tmux official wiki for all the information you need to install it properly. Once installed, you can check that everything is working by running the command tmux in your terminal. You should be in a tmux session. To exit it, type exit and enter.

Configuring and using tmux

Now it is time to configure tmux (just a little bit) and explore some cool things we can do with it. First, let's create a .tmux.conf file in your root directory. This is the configuration file tmux will load when you launch it.

touch ~/.tmux.conf

Testing your config

The goal of configuring it is to find what works for you. I'd recommend writing the tmux config while being in tmux so that you can test it out as we add new things to it. If you are inside tmux, just like a bashrc, you need to source your tmux config as you make changes for it to take effect.

If you're inside tmux, you can source your updated config in command mode. Run <ctrl-b>: (ctrl b followed by a colon). You should see the bottom bar changing. Enter source-file ~/.tmux.conf and your configuration should be loaded. Let's add a custom keymap to our configuration to do this quicker:

bind r source-file ~/.tmux.conf\; display "config reloaded"

bind is our way to tell tmux that r preceded by the prefix key should source the tmux config. By pressing <ctrl-b> followed by r, this will reload your config without leaving tmux. Don't forget to source your config one last time in command mode before trying out this command. This key combination might feel very awkward. So let's move on to choose a better prefix.

Choose a prefix you're comfortable with

The whole point of tmux is to have keyboard shortcuts that work for you. tmux has a set of default keymaps to create windows, new panes, switch between sessions, etc. Each keymap uses a prefix. You can think of it as the leader key in vim. You combine the prefix with another key to interact with tmux and ask it to do something. By default, the prefix is C-b (ctrl-b). If you like this prefix, you can move on to the next section. A popular alternative is to use C-a as the prefix.

Add this to your tmux config:

# in your ~/.tmux.conf
# Setting the prefix from C-b to C-a
set -g prefix C-a
# free original prefix keybinding
unbind C-b
# make sure we can send C-a to other apps
bind C-a send-prefix

set -g prefix C-a will tell tmux every time it runs control+a as its prefix.
unbind is to free C-b and keep only one combination as our prefix.
bind C-a send-prefix is to make sure you can use this keymap in programs running inside of tmux. For instance, if you use vim and do not include this line, any of your vim keymaps using C-a would no longer work inside tmux.

A small note before going further

In the rest of the article, I'll be writing <PREFIX> often followed by a letter to explain the different commands you can use in tmux. <PREFIX> is whatever prefix you choose to use (for instance, Ctrl-a).

Creating windows and panes in tmux

Generally, after setting up the prefix in the tmux configuration, it is very common also to customize the keymap to create new panes (vertical or horizontal splits in a window) and navigate between those panes. In your .tmux.conf, add:

# below your prefix config
bind | split-window -h
bind - split-window -v
unbind '"'
unbind %

Let's dissect these few lines.

By default, to create a horizontal split, you would use <PREFIX>" (C-a followed by a double quote "). Instead, we bind - to create a horizontal split. You can create a new pane in your window using your prefix followed by -.
For a vertical split, the keymap is by default <PREFIX>%. A popular replacement is to use | instead. It might also be easier to remember. You can now type <PREFIX>| to create a vertical split.

The default keymap is <PREFIX>c to create a new window.

If you want to test these keymaps, reload your config (<PREFIX>r).

Navigating between panes and windows in a tmux session

To navigate between your windows, there are three main ways:

<PREFIX> n to go to the next window
<PREFIX> 1 to go to a particular window. Every window has a number. It starts at 0.
<PREFIX> w to have an interactive list of all your windows with a preview of what contains each window.

A popular option to navigate between your panes is to use the same keys as in vim (k to go up, j to go down, h to go to the left pane, l to go to the right pane). Let's add this to our tmux.conf

# in your ~/.tmux.conf
# map direction keys for vim like experience
bind h select-pane -L
bind j select-pane -D
bind k select-pane -U
bind l select-pane -R

I also use the vim keys to resize the panes.

# in your ~/.tmux.conf
# resize panes with repeated key
bind -r H resize-pane -L 5
bind -r J resize-pane -D 5
bind -r K resize-pane -U 5
bind -r L resize-pane -R 5

But if you do not care about vim, you can use <PREFIX> followed by the arrow key to move your cursor to a particular split.

Creating sessions and naming sessions

Earlier, I mentioned that you could have multiple sessions with their own set of windows and panes (and processes running). When you start tmux, you create a session at the same time. My go-to commands to manipulate sessions in tmux:

tmux new-session -s coding to start tmux and create a "coding" session.
If you are already in a tmux session and wish to create a new one, you can run tmux new-session -s processes -d. The -d is essential here. It will make that session in detached mode.
To switch between sessions, you can use <PREFIX>( to go to the next session or <PREFIX>) to go to the previous session.
You can also use an interactive list (like for the windows) by pressing <PREFIX>s. Press q to leave the interactive list.
To rename your current session, use <PREFIX>$.

Detached mode

One great functionality is to run processes in the background using tmux detached mode. You can always re-attach to a session later on.

If you are always in tmux, you can essentially leave tmux momentarily while not killing any processes by pressing <PREFIX>d. It will send whatever tmux session you're on in the background. You can reattach this same session to run tmux attach-session (or tmux a).

If you have several tmux sessions running in detached mode, you can also attach to a particular session directly. Use tmux a -t NAME_OF_YOUR_SESSION. NAME_OF_YOUR_SESSION will be your session name.

Closing a tmux window and stopping all tmux processes

One significant point of attention is to make sure you do not forget a tmux session that runs in the background. tmux ls is an excellent command to remember. It will list all your tmux sessions and show you when they were created.

When it comes to quitting a window or pane, here's my list of essential commands:

To kill a window or pane, <PREFIX>x (ctr-a x in my case).
You can also use <PREFIX>& to kill a window.

When it comes to killing a session in tmux, I generally kill all sessions simultaneously. I first leave tmux by pressing <PREFIX>d. It will send all sessions in detached mode. tmux still runs but in the background. If you do a tmux ls, you'll still see all of your sessions. I then do tmux kill-server (be careful because it will essentially kill all sessions and processes running in tmux). If you want to kill one specific session, leave tmux (<PREFIX>d) and then type tmux kill-session -t NAME_OF_SESSION_TO_KILL.

Scrolling in your tmux buffer

There is a mode called copy mode in tmux. You enter it by pressing <PREFIX>[ (and quit it by pressing ENTER). After pressing <PREFIX>[, you can then move in your buffer with your arrow keys. You can also use vim keys in copy mode (like b and w to move from one word to another, gg ) if you enable vim keys in your config.

# in your ~/.tmux.conf
# enable vi key bindings
setw -g mode-keys vi

Searching in a tmux buffer

Here are the steps if you are searching for something in your current buffer:

Enter copy mode <PREFIX>[.
Press ? if you want to search for an element above your current position in your buffer. Or you can press / to search down.
Type the element you are searching for.
Press n to move between the found occurrences.

Help in tmux

If you forget how to do something in tmux, tmux has a help menu with a list of the keymaps. Type <PREFIX>? to enter it (and q to exit it).

Colors in tmux

To have your colors work properly in tmux in programs like vim or emac, add this to your config:

# Configure color for terminal
set -g default-terminal "screen-256color"

Extending tmux with plugins

There is a plugin system to extend tmux. If you feel like adding some plugins, you need to install tpm (tmux plugin manager). You can find all the installation information in the Github repository. Once you've installed it, you can add some plugins to your tmux config. You should add all the plugin related stuff at the very end of your config.

Here's what I have in my config:

# at the very end of ~/.tmux.conf
set -g @themepack 'powerline/default/cyan'

# set up plugins
set -g @plugin 'tmux-plugins/tpm'
# theme
set -g @plugin 'jimeh/tmux-themepack'

# Initialize TMUX plugin manager
# keep this line at the very bottom of tmux.conf
run '~/.tmux/plugins/tpm/tpm'

Instead of configuring it by hand, I added tmux-themepack to style the bottom bar.

Scripting tmux with tmuxinator

At this point, we have a working tmux config and a set of keymaps we are comfortable with to create windows, sessions, and move in our terminal. What gives tmux an extra edge over using built-in tabs in your terminal (if you have those) is automating things. If you open your terminal every morning to launch the same programs and create the same tmux sessions, you can create a script and launch everything in half a second.

tmuxinator is a great tool to create scripts quickly. Let's create an example script together to get the ball rolling for you. Let's start a project called "work".

First, we launch tmuxinator by typing tmuxinator new work. Let's modify the newly created config:

# /Users/yourusername/.config/tmuxinator/work.yml

name: work
# the path you want to launch tmux in
root: ~/projects/devblog

# Controls whether the tmux session should be attached to
# automatically. Defaults to true.
# attach: false

windows:
  - editor: nvim
  - process: npm run dev

name will be the name of your script. Once created, when you open your terminal, you can type tmuxinator work and it will launch tmux, creating all the windows you mentioned in the script.
The windows property contains a list of the different windows we want to create. It will create two windows: "editor" and the other named "process".
We then launch nvim in the editor window while starting npm in the other window.

If you're into aliases, you can create a quick one for tmuxinator (it is a great name, but it can be a long one to write).

# in your ~/.bashrc
alias tx="tmuxinator"

# I also have an alias for tmux cos I'm lazy :)
alias tm="tmux"

Conclusion and great resources

We've explored tmux and how to configure it and use it. We finished the article by writing a small script that is only a glimpse of all the cool things we can do with tmux. Here's my list of all the cheatsheets, documentation, and books to get extra comfortable with tmux:

Getting Started with tmux/tmux Wiki
Tmux Cheat Sheet & Quick Reference
One of the best books on tmux: tmux 2: Productive Mouse-Free Development by Brian P. Hogan
Tmuxinator
Video on tmux by ThePrimeagen
GitHub - liv7c/dotfiles: Personal config for bash, tmux, git, and neovim: my custom config if you feel like taking a look (definitely a work in progress)

I hope this guide will be helpful to you. If you have any questions, you can reach me on Bluesky.

Testing HTML in React Components with Vitest

2024-09-08T00:00:00Z

In this guide, we'll walk through the steps to set up HTML validation for React components using Vitest. You'll learn how to ensure your components adhere to proper HTML structure, improving code quality and catching errors early in the development process.

What is HTML validation, and why does it matter?

You may have already used a service like W3C validation service for your web pages. This type of validator scans your HTML and checks for essential elements, such as that the document has a language attribute (<hmtl lang="en">), but also that your HTML markup is valid. Having valid HTML is crucial to creating a more accessible experience for your users.

There are so many ways to check whether your HTML is valid. With React, we tend to create a lot of small components and often lack the vision of what the HTML of the page as a whole looks like. So, a service like the W3C validation service is still necessary. However, having quicker feedback while writing our reusable components during development is extremely helpful. It can significantly decrease the number of errors we encounter when we validate the HTML of a whole page. Moreover, when creating component libraries, it is essential to ensure the component has a valid HTML markup. Thus, in this post, we'll set up html-validate in vitest to add those HTML checks at the component level and improve the feedback loop overall.

Setting up html validation in vitest

I assume you already have a react project with vitest. If not, you can check out the entire demo code in the final section of the post.

The first step is to install html-validate. If you use npm or pnpm along with vitest v2, you might need to use the flag --legacy-peer-deps. This flag turns off the peer dependency checking during installation.

# npm i -D html-validate
# pnpm i -D html-validate
yarn add --dev html-validate

Then, we need to modify the test setup file. You probably already have a setup file defined in your Vite or Vitest config. The setup file is run before each test file and reduces the boilerplate.

/// <reference types="vitest" />
import {defineConfig} from 'vite';
import react from '@vitejs/plugin-react';

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [react()],
  test: {
    globals: true,
    // your test setup files
    setupFiles: ['./src/setup-tests.ts'],
    environment: 'happy-dom',
  },
});

In my Vite config, I have defined one setup file ./src/setup-tests/ts. In your setup file, add this line:

// adding this to my `src/setup-tests.ts`
import 'html-validate/vitest';

This line extends the expect capabilities by adding some handy matcher functions such as toBeValid and toHTMLValidate. For the exhaustive list of the available matcher functions, check out the html-validate source code for vitest.

Once we have added the new dependency and the line in our test setup file, we're generally good to go!

Validate your React component HTML in your tests

I created a small Button component for this demo with some problematic HTML markup.

import {PropsWithChildren} from 'react';

export function Button({children}: PropsWithChildren) {
  return (
    <button>
      <div>{children}</div>
    </button>
  );
}

If we look at the HTML specifications for the button element, we see that a button can only contain phrasing content. The HTML spec defines phrasing content as the text of the document. You can only include elements concerning the text's appearance (e.g., strong, span). It is an easy error to make. Now, let's write a test that helps us catch that issue (and others).

Let's create a test file for our button and add a test case to validate the HTML:

import {Button} from './Button';
import {render, screen} from '@testing-library/react';

describe('Button', () => {
  test('has valid HTML', async () => {
    const {container} = render(<Button>Hello</Button>);
    const htmlString = container.innerHTML;

    expect(htmlString).toHTMLValidate();
  });
});

In this test, we use the .toHTMLValidate() helper from html-validate. We also use the container.innerHTML to pass to toHTMLValidate the actual HTML markup of our component. When we run the test, we see that the test fails.

The test output shows us that our simple Button component has two issues:

it is missing the recommended type attribute.
And it captures the error we discussed - the invalid div element inside of a button element.

The whole demo code

You can check out the entire demo code on StackBlitz.

Conclusion

In this guide, we set up html-validate to validate the HTML of our React components in vitest. It greatly improves the feedback loop and helps catch all kinds of HTML errors quicker during development. I hope the guide was helpful. If you have any extra questions, don't hesitate to reach out!

A practical introduction to code splitting in React

2025-03-26T00:00:00Z

In this blog post, we'll explore various techniques for code splitting in React applications. We'll cover methods like lazy loading components, dynamic imports, and route-based code splitting. Throughout the article, we'll use a demo app to illustrate each technique so you can follow along and implement these concepts in your React projects. If you’d like to code along, feel free to clone the Github repository.

Before exploring the different techniques, let’s first understand code splitting and how it can improve the user experience.

What is code splitting?

At its core, code splitting is a technique for dividing your code into different chunks or pieces. A chunk is a separate file that your bundler (or build tool) loads at specific moments — for example, a JavaScript file that loads when your user navigates to the About page.

Code splitting works alongside your build tool. Build tools like Vite bundle and optimize your CSS, JavaScript, images, and other assets for production. The build tool determines which code should load initially (when the app first starts) and which can be loaded on demand (as the user interacts with the app). While the techniques for code splitting can vary depending on the build tool, the underlying concept remains the same.

Setting up the demo app

To follow along with this post, clone the repository from GitHub and check out the start-route-code-splitting branch:

git clone https://github.com/liv7c/demo-code-splitting-react-vite
cd demo-code-splitting-react-vite
npm install
git checkout start-route-code-splitting
npm run dev

The start-route-code-splitting branch contains the initial setup, but no code-splitting techniques have been applied yet.

App overview

After running the app, you should see the following pages:

Home Page: The main landing page of the app.
Movies Page: Displays a list of movies fetched from a free API.
Movie Detail Page: Shows detailed information about a specific movie.
About Page: Includes an informational modal for additional details.

Technical stack

The app was created with Vite using the npm create vite@latest command.
React Query is used for data fetching, and Radix UI is used for the modal component.
The app uses React Router v7 but is not in framework mode (it’s not a Remix-style app). It uses createBrowserRouter to manage routes. You can view the router configuration in the Github repo.

Implementing code-splitting at the route level

If you use a framework (Next or Remix), route-level code splitting is handled automatically. However, this is an easy win for many single-page applications built without a framework that can significantly improve performance.

After running npm run build, you’ll notice that Vite currently generates one JS file (over 100KB). As you add more content to each page, this file will only get bigger. This means that users must download the entire app’s JavaScript code, even if they visit only a specific part of the app.

We can help Vite split our code at the route level. This ensures JavaScript for a specific page loads only when needed.

Step 1: Using `React.lazy` for route-level code splitting

In our router/index.tsx, instead of importing every page component directly, we can use React.lazy to import every page. We’ll skip lazy loading for the Home page, as it’s likely the most common entry point to the app.

React.lazy ensures a component is imported only when it gets rendered. This is the behavior we want for most of the routes.

Let’s wrap every page component with React.lazy:

// in src/router/index.tsx
import {createBrowserRouter} from 'react-router';
import Home from '../pages/Home';
import {AppLayout} from '../layouts/AppLayout';
import {lazy} from 'react';

// We wrap each page previously imported with React.lazy.
// React.lazy takes a function that returns a promise resolving to a React component.
const About = lazy(() => import('../pages/About'));
const NotFound = lazy(() => import('../pages/NotFound'));
const MovieDetails = lazy(() => import('../pages/MovieDetails'));
const Movies = lazy(() => import('../pages/Movies'));

Step 2: Adding Suspense for loading states

Next, we need to add a Suspense boundary to handle loading states while the code is being fetched. We could add one to the AppLayout to have a generic loader.

Let’s create a quick loader component:

// src/components/Loader/index.tsx
type LoaderProps = {
  message?: string;
};

export function Loader({message = 'Loading content...'}: LoaderProps) {
  return (
    <>
      <p>
        <span className="sr-only">{message}</span>
      </p>
      <div className="my-4 flex h-12 w-12 animate-spin justify-self-center rounded-full border-8 border-gray-300 border-t-teal-600" />
    </>
  );
}

Then, we can wrap the Outlet in the AppLayout with a Suspense component and use our new fancy loader as a fallback:

// components/AppLayout/index.tsx
import {Suspense} from 'react';
import {NavLink, Outlet} from 'react-router';
import {Loader} from '../../components/Loader';

export function AppLayout() {
  return (
    <>
      <header className="bg-teal-800 text-white">
        {/* rest of header content */}
      </header>
      <main>
        <div className="max-width-wrapper py-6">
          {/* let's wrap up our Outlet with a Suspense component */}
          <Suspense fallback={<Loader />}>
            <Outlet />
          </Suspense>
        </div>
      </main>
    </>
  );
}

Step 3: Testing our changes

This simple change greatly improves our build output. After running npm run build, we see that Vite creates a JS file for each page. Additionally, there’s a JS file for the date utility used on the movies and movie detail pages. In larger projects, where pages may become complex and large, this approach ensures the build doesn’t generate one massive JavaScript file for the entire application.

If you'd like to see the completed code for the route-level code-splitting, you can check out the end-route-code-splitting branch:

git checkout end-route-code-splitting

Fixing the multiple loaders

Now that we’ve split our routes using React.lazy, we’ve reduced our initial JavaScript load. However, we now have a subtle UX issue: multiple loaders.

When users land on the Movies page, they first see the Loader from AppLayout. Then, after the component mounts, React Query starts fetching movie data, triggering another loading state. This creates a flickering effect where two loaders appear back-to-back.

To fix this, we have a few approaches.

Solution 1: use another Suspense boundary

We could wrap each movie and movie detail page with a Suspense boundary that uses fallback={null}, meaning no loading indicator will be displayed. However, this is not ideal since users will see an empty space while the route component loads.

// in router/index.tsx
export const router = createBrowserRouter([
  // ...
  {
    id: 'movies',
    path: '/movies',
    element: (
      <Suspense fallback={null}>
        <Movies />
      </Suspense>
    ),
  },
  // ...
]);

This might be a perfectly acceptable solution if:

The component loads quickly.
A brief blank state does not negatively impact the user experience.

Solution 2: leverage useSuspenseQuery from @tanstack-query

A more robust approach is to use useSuspenseQuery from react-query (it is no longer experimental since v5). Here are some key differences between useSuspenseQuery and useQuery:

Simplified Loading State: useSuspenseQuery eliminates the need to handle loading states manually, as it guarantees the data property will be defined once the query resolves. React will suspend the component until the data is available. This means you don’t need to handle the loading state manually, letting Suspense take care of it automatically.
Error Handling: Since useSuspenseQuery no longer returns an error state, it's essential to use an ErrorBoundary to handle potential errors during the data fetching. Without it, unhandled errors would cause your UI to break

In our hooks/useMovies.ts, let’s add a new hook:

// hooks/useMovies.ts
import {useQuery, useSuspenseQuery} from '@tanstack/react-query';
import {fetchMovie, fetchMovies} from '../api/movies';

export const useMoviesWithSuspense = () => {
  return useSuspenseQuery({
    queryKey: ['movies'],
    queryFn: fetchMovies,
    select: (data) => {
      return data.results;
    },
  });
};

Then, in our Movies.tsx, we can replace the useMovies hook with useMoviesWithSuspense:

// pages/Movies.tsx
import {Link} from 'react-router'
import {useMoviesWithSuspense} from '../hooks/useMovies'
import {formatDate} from '../utils/date'

function Movies() {
	// let's use our new hook.
	// It no longer returns a `status`
  const {data: movies} = useMoviesWithSuspense()

  return (
    <>
      <h1 className="mb-4 text-xl">Our most popular movies</h1>
      <ul className="grid grid-cols-2 gap-x-5 gap-y-10">
        {movies.map((movie) => {
          return (
          //Nothing changes here
         )
        })}
      </ul>
    </>
  )
}

export default Movies

Let’s install react-error-boundary to handle errors and add a React boundary to our AppLayout.

npm install react-error-boundary

In the AppLayout, we can add an ErrorBoundary around the Suspense boundary to catch any potential errors in the data-fetching process and prevent the entire app from crashing.

import {Suspense} from 'react';
import {NavLink, Outlet} from 'react-router';
import {Loader} from '../../components/Loader';
import {ErrorBoundary} from 'react-error-boundary';

export function AppLayout() {
  return (
    <>
      <header className="bg-teal-800 text-white">{/* some content */}</header>
      <main>
        <div className="max-width-wrapper py-6">
          <ErrorBoundary fallback={<p>⚠️Something went wrong</p>}>
            <Suspense fallback={<Loader />}>
              <Outlet />
            </Suspense>
          </ErrorBoundary>
        </div>
      </main>
    </>
  );
}

This acts as a catch-all ErrorBoundary. Alternatively, we could integrate an ErrorBoundary directly into the router configuration for a specific route. You can find more information about this approach in the React Router documentation.

Solution 3: Combining the power of loader functions from react-router with react-query

The third approach (and my personal favorite) combines React Router's loader functions (introduced in react-router v6.4) with React Query.

For our MovieDetails, we face a similar challenge as we did on the Movies page: we need to fetch movie data once the component renders. By combining react-query with react-router loaders, we fetch data during the routing process rather than after component mounting, while still leveraging react-query's caching capabilities.

Since we’re using react-router v7 and createBrowserRouter, loaders allow us to fetch data before the component mounts. The result is passed directly to the component, and we can continue using react-query for caching.

Setting up the loader function

First, let’s create a new file loader.ts in our MovieDetails folder (feel free to name it differently). This file will contain our loader function:

// src/pages/MovieDetails/loader.ts
import type {LoaderFunctionArgs} from 'react-router';
import type {QueryClient} from '@tanstack/react-query';
import {getMovieDetailsQuery} from '../../api/movies';
import type {Movie} from '../../types/movie';

export const movieDetailsLoader =
  (queryClient: QueryClient) =>
  async ({params}: LoaderFunctionArgs) => {
    const query = getMovieDetailsQuery(params.id ?? '');

    return queryClient.ensureQueryData(query) as Promise<Movie>;
  };

I created a getMovieDetailsQuery that returns the query options we were using in our useMovie hook:

// in src/api/movies.ts

export const getMovieDetailsQuery = (movieId: string) => {
  return {
    queryKey: ['movies', movieId],
    queryFn: () => fetchMovie(movieId),
    enabled: Boolean(movieId),
  };
};

Some key points about the loader function:

QueryClient: The loader function receives a queryClient that we will pass from the router. Since loaders are not hooks, we cannot use useQueryClient to access the react-query store directly.
getMovieDetailsQuery: This function returns the query options we usually use with useQuery.
What movieDetailsLoader returns: It returns a function with the loader signature. The returned function receives arguments like the params that react-router automatically passes to all the loader functions.
ensureQueryData: The ensureQueryData method ensures that if the data isn't already cached, the query will be executed to fetch the data. Check out the react query document.

Moving the query client to its own file

Before we can use this loader, we need to make the queryClient available in our app. Let’s extract the queryClient into a separate file so we can import it wherever needed.

Let's create a src/queryClient/index.ts:

import {QueryClient} from '@tanstack/react-query';

export const queryClient = new QueryClient();

In main.tsx, let’s import and use it.

// src/main.tsx
// ...
import {queryClient} from './queryClient';

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <QueryClientProvider client={queryClient}>
      <RouterProvider router={router} />
    </QueryClientProvider>
  </StrictMode>
);

Modifying our router

Now, in router/index.tsx, we can import the loader function and the queryClient:

// router/index.tsx
// ... other imports
import {queryClient} from '../queryClient';
import {movieDetailsLoader} from '../pages/MovieDetails/loader';

export const router = createBrowserRouter([
  {
    id: 'root',
    element: <AppLayout />,
    children: [
      // ...
      {
        id: 'movieDetail',
        path: '/movies/:id',
        // we use the loader property and call the movieDetailsLoader which returns a
        // function with the correct signature.
        loader: movieDetailsLoader(queryClient),
        element: <MovieDetails />,
      },
      // ...
    ],
  },
]);

Accessing loaded data in the `MovieDetails` page

Finally, we can replace the useMovie hook in the MovieDetails component with the useLoaderData hook, which gives us access to the data returned by the loader function. The Typescript part comes from this fantastic article, which digs deeper into the technique we are currently implementing.

// in pages/MovieDetails/index.tsx

function MovieDetails() {
  //We replace our useMovie with useLoaderData
  // notice we no longer have any isLoading or isError 👀
  const movie = useLoaderData() as Awaited<
    ReturnType<ReturnType<typeof movieDetailsLoader>>
  >;

  return (
    <div>
      <Link to="/movies" className="mb-3 inline-block py-2 underline">
        &larr; Back to all movies
      </Link>
      <h1 className="text-3xl">{movie.title}</h1>
      <p className="mt-3">by {movie.director}</p>
      <p className="mt-3">Release date: {formatDate(movie.release_date)}</p>
      <div className="my-4 border border-dotted border-amber-500 p-3">
        <h2 className="mb-3 font-bold">Summary</h2>
        <p>{movie.opening_crawl}</p>
      </div>
    </div>
  );
}

Benefits of all this work

We’ve written quite a bit of code for this third solution. Some key benefits of this approach are:

We no longer have to manage any isLoading or isError booleans in our MovieDetails page since the loader fetches the data before the component mounts.
We still benefit from React Query’s caching, to avoid unnecessary refetching.

Which approach to choose?

Each solution offers different trade-offs between simplicity, performance, and developer experience. There isn't a one-size-fits-all solution.

Solution 1 is straightforward but may lack robustness and lead to layout shifts. Solution 2 offers a more efficient approach by leveraging the route's closest Suspense boundary and ErrorBoundary, with minimal code changes. Solution 3, on the other hand, embraces newer capabilities from React Router, introducing a shift in how we load data on the client side.

By adopting Solution 2 or Solution 3, we eliminated the problem of multiple loaders on the Movie and MovieDetails pages! Additionally, our build output remains unchanged after these refactorings.

To see the implementations of these approaches, you can checkout the end-multiple-loaders branch:

git checkout end-multiple-loaders

Beyond code splitting at the route level

While route-level code splitting provides significant benefits, it may not be sufficient for complex applications where individual pages contain numerous components or require large libraries. In such cases, code-splitting at the route level might not reduce load times, as you could end up with large JavaScript chunks that need to be downloaded. This section will explore how to apply more granular techniques for code-splitting to optimize loading performance.

Scenario: we have added a fancy animation that is quite heavy

I’ve created a new branch where I added a fancy loading animation.

git checkout starter-lazy-loading-component

The animation is a Lottie animation, a JSON file you can use with the react-lottie library. If you’re curious, you can check out the animation on the About page by clicking on the button 🐰.

After running npm run build, we have a JS file for the About page of over 100KB. The file size is due mainly to the react-lottie library used to play the animation.

What problem are we trying to fix?

In our case, many users might not even interact with the modal that triggers the animation. This means the react-lottie library is unnecessarily included in the initial JavaScript bundle, even though it isn’t used immediately.

To optimize this, we can use code-splitting to ensure that the react-lottie library is loaded only when the user interacts with the modal. This way, we avoid loading unnecessary code upfront.

Lazy-loading the Animation component

First, let’s improve our FancyAnimation component. We can use React.lazy to dynamically import the react-lottie library, and we’ll also need to wrap this lazy-loaded component in a Suspense component. This ensures that the application handles any slight delay when loading the animation.

// components/FancyAnimation/index.tsx
import {usePrefersReducedMotion} from '../../hooks/usePrefersReducedMotion';
import {lazy, Suspense} from 'react';
import easterBunnyAnimation from './easter_bunny_anim.json';

// Replace the import LottiePlayer from 'lottie-react' with this dynamic import
const LottiePlayer = lazy(() => import('lottie-react'));

export const FancyAnimation = () => {
  const prefersReducedMotion = usePrefersReducedMotion();

  return (
    <div className="min-h-[450px]">
      {/* wrap the LottiePlayer component with Suspense */}
      <Suspense fallback={null}>
        <LottiePlayer
          animationData={easterBunnyAnimation}
          loop={false}
          autoplay={!prefersReducedMotion}
        />
      </Suspense>
    </div>
  );
};

If we look at our build output, Vite now creates a separate chunk that contains the code related to react-lottie and a chunk for the About page of about 30KB.

Further optimization: lazy-loading the animation JSON

While we’ve reduced the chunk size of our About page, most of the 30KB is still due to the animation JSON itself. To optimize further, we can load the animation JSON only when the component is rendered rather than include it in the initial load.

Since we’re using React 19, we can take advantage of the new use hook, which allows us to read the value of a promise (like our JSON animation) and suspend the component while the promise is resolving. By combining the use hook with Suspense, we can lazily load both the react-lottie library and the animation JSON.

Using React’s `use` hook to load the animation JSON

Let’s refactor the component to dynamically import the animation JSON and use the use hook to handle the promise resolution. This change will further reduce the initial load size.

First, let’s create the promise for the animation outside of the component:

// in components/FancyAnimation/index.tsx

// After the imports, create the promise to import the animation JSON dynamically.
const animationPromise = import('./easter_bunny_anim.json').then(
  (data) => data.default
);

Then, we can create an inner component that our Suspense boundary can wrap. If we don’t, when the animation gets loaded, it will suspend to a Suspense boundary higher up the component tree, as the entire FancyAnimation would suspend. Let’s use the use hook and pass it the animation JSON promise we’ve just created.

import {usePrefersReducedMotion} from '../../hooks/usePrefersReducedMotion';
import {lazy, Suspense, use} from 'react';

const LottiePlayer = lazy(() => import('lottie-react'));
const animationPromise = import('./easter_bunny_anim.json').then(
  (data) => data.default
);

// Create an inner component that contains the LottiePlayer and the animation JSON
const AnimationContent = () => {
  const prefersReducedMotion = usePrefersReducedMotion();
  const animationData = use(animationPromise);

  return (
    <LottiePlayer
      animationData={animationData}
      loop={false}
      autoplay={!prefersReducedMotion}
    />
  );
};

export const FancyAnimation = () => {
  return (
    <div className="min-h-[450px]">
      <Suspense fallback={null}>
        <AnimationContent />
      </Suspense>
    </div>
  );
};

Final build output

With this refactoring, our build output is back to a tiny JS file size of around 12 KB for the About page. Users not interacting with the modal won't have to load that JavaScript.

You can see the final implementation by checking out the end-lazy-loading-component branch:

git checkout end-lazy-loading-component

Conclusion

In this blog post, we explored some techniques around code-splitting in a React single-page application. We looked at code-splitting at the route level and at a couple of techniques to mitigate the dreaded multiple loaders effect. We had some practice with Suspense and the new use hook. We then experimented with optimizing our bundle when we use a heavy component on a page. I hope you found this post helpful! Feel free to reach out on Bluesky if you have any questions or would like to share your own experiences with this topic!

Resources

An introduction to table driven tests in Vitest

2025-04-09T00:00:00Z

I first encountered the concept of "table driven tests" when coding in the beautiful Go language. The technique is straightforward: You create a table (an array in your JavaScript code) to define the cases you want to test. Then you let the test runner loop through all the test cases. It is an extremely efficient technique for adding new test cases, reducing the boilerplate, and testing a lot more use cases.

This technique is absolutely brilliant for unit tests. In this blog post, we'll explore how to use it in Vitest.

Let's write a table driven test

Let's create a quick function to validate an email:

// utils/validators.ts
export function isValidEmail(email: string): boolean {
  const trimmedEmail = email.trim();

  if (!trimmedEmail) {
    return false;
  }

  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;

  return emailRegex.test(trimmedEmail);
}

In the test file, we will add a describe block for that util function:

// utils/validators.test.ts
import {isValidEmail} from './validators';

describe('isValidEmail', () => {});

Traditionally, to test this function, we would write tests like the following snippet:

// utils/validators.test.ts
import {isValidEmail} from './validators';

describe('validateEmail', () => {
  test('returns false when email is empty', () => {
    const result = isValidEmail('');
    expect(result).toBe(false);
  });

  test('returns false when email is empty string with white spaces', () => {
    const result = isValidEmail('  ');
    expect(result).toBe(false);
  });

  // lots of edge cases still to cover
});

With table driven testing, instead of writing each test manually, we first define our test cases in an array.

describe('isValidEmail', () => {
  const testCases: {
    name: string;
    input: string;
    expected: boolean;
  }[] = [
    {
      name: 'email is empty',
      input: '',
      expected: false,
    },
    {
      name: 'email is an empty string with white spaces',
      input: '  ',
      expected: false,
    },
    {
      name: 'missing domain',
      input: 'username@',
      expected: false,
    },
    {
      name: 'missing username',
      input: '@email.com',
      expected: false,
    },
    {
      name: 'missing at sign',
      input: 'useremail',
      expected: false,
    },
    {
      name: 'invalidates duplicate email entries with white spaces',
      input: '   test@email.com    test@email.com',
      expected: false,
    },
    {
      name: 'valid email',
      input: 'test@email.com',
      expected: true,
    },
    {
      name: 'handles leading white spaces',
      input: '   test@email.com',
      expected: true,
    },
    {
      name: 'handles trailing white spaces',
      input: 'test@email.com    ',
      expected: true,
    },
    {
      name: 'handles trailing and leading white spaces',
      input: '   test@email.com    ',
      expected: true,
    },
  ];
});

You can define your test cases the way you want. You could rename expected to want or expectedOutput. There is no strict rule here. You can name the properties however you like, and even include additional fields if needed. I like adding a name and using the object structure to make things as readable as possible.

The only thing left is to run our tests using test.each() from Vitest. We pass our test cases to test.each, then define a callback that receives each test case's values.

import {isValidEmail} from './validators';

describe('isValidEmail', () => {
  const testCases: {
    name: string;
    input: string;
    expected: boolean;
  }[] = [
    {
      name: 'email is empty',
      input: '',
      expected: false,
    },
    // rest of our test cases...
  ];

  // You could also use `it.each`
  test.each(testCases)('$name', ({input, expected}) => {
    const result = isValidEmail(input);
    expect(result).toBe(expected);
  });
});

Some things to note:

Because we use objects to define each case, we can access each property by their name using the $ notation. If we had used testName instead of name in our test cases array, we would have written test.each(testCases)('$testName', instead.
We define a callback function that receives each test case object. We write the test logic once, and reuse it for each case.

If we run the test, we can see an output where Vitest runs each test case and outputs the result in a very clean, readable way:

 ✓ src/utils/validators.test.ts (10 tests) 2ms
   ✓ isValidEmail > 'email is empty' 1ms
   ✓ isValidEmail > 'email is empty string with white spac…' 0ms
   ✓ isValidEmail > 'missing domain' 0ms
   ✓ isValidEmail > 'missing username' 0ms
   ✓ isValidEmail > 'missing at sign' 0ms
   ✓ isValidEmail > 'invalidates duplicate email entries w…' 0ms
   ✓ isValidEmail > 'valid email' 0ms
   ✓ isValidEmail > 'handles leading white spaces' 0ms
   ✓ isValidEmail > 'handles trailing white spaces' 0ms
   ✓ isValidEmail > 'handles trailing and leading white sp…' 0ms

This technique makes it very easy to add new test cases!

Using nested arrays instead of objects for the test cases

An alternative is to use nested arrays instead of objects, which can be more concise. If you prefer this notation, you would define the test cases like this:

describe('isValidEmail', () => {
  const testCases: [name: string, input: string, expected: boolean] = [
    ['email is empty', '', false],
    ['email is empty with white spaces', '  ', false],
    // ...
  ];
});

Then, instead of accessing the properties of an object in your test.each, you access the different array values based on their position:

describe('isValidEmail', () => {
  const testCases: [name: string, input: string, expected: boolean][] = [
    ['email is empty', '', false],
    ['email is empty with white spaces', '  ', false],
  ];

  test.each(testCases)('%s', (_name, input, expected) => {
    const result = isValidEmail(input);
    expect(result).toBe(expected);
  });
});

%s interpolates the name we provided. It follows the printf formatting rules. %s means you want to interpolate a string. For a number, you would write %d for instance.

You can choose whichever style feels clearer or more readable to you.

When to use table driven tests

There’s no hard rule about when to use table driven tests, but it’s especially useful when:

There are many slight variations to test (like lots of different types of inputs, etc.), and the test logic remains the same.
The logic is simple and pure. Table testing shines when testing pure functions, which are functions that, given the same input, will always return the same output.

What about Jest?

In Jest, you can use .each in the same way as in Vitest. You can check out the documentation for the each method in Jest here. The examples in the documentation should feel familiar!

Complete code demo

If you feel like playing with the code from this blog post, it is available on Stackblitz.

Conclusion

In this post, we explored a technique called table driven testing, which is quite popular in the Go community. However, we can also apply it to our JavaScript code!

By defining test cases in a table (an array of objects or arrays), we can quickly test multiple input variations without repeating ourselves. This technique reduces the boilerplate and makes adding more test cases easy. It is especially handy when testing pure functions or utils.

Thanks for reading! I hope you find the post useful. If you have any questions or want to chat about unit tests, don't hesitate to reach out on Bluesky 😀

Resources

How to use the HTML specification to write better HTML

2025-05-14T00:00:00Z

When writing HTML, I often ask myself all kinds of questions. For instance, when should I use an <article> element? Is it valid HTML to use a <p> tag inside an <li>? The HTML specification has been my go-to resource for answering these questions, particularly the fourth section, "The elements of HTML". It is an incredible resource, but navigating it can feel a little overwhelming at first.

This blog post is here to help you find your way through the HTML specification and get the information you need. By understanding how to navigate the specification, you'll be able to write more semantic HTML that better describes your content.

A first taste of the HTML specification and some key terms

There are different sections in the HTML specification. The section I want to focus on in this blog post is section 4 "The elements of HTML". This section lists each HTML element and explains how and when to use it. It is full of examples and explanations that are invaluable when trying to write semantic HTML.

When browsing the spec, you'll notice a few terms, such as "Category" or "Content Model". Let's quickly clarify what those are.

Content model

Content model describes what content an element can contain. Each HTML element can contain specific categories. Some HTML elements, such as the heading tag, can contain only phrasing content. Whenever you wonder what you can put inside of an HTML element, you should look at the element's content model.

How to read an HTML specification entry

In this section, we'll discuss how to read an HTML specification entry. Let's say you're looking at the specification for the <li> element. Each element in the specification is described using a consistent set of sections. Here's a quick breakdown of some key sections you'll find for most elements:

Content model: This tells you what can go inside the element tags. In the case of the <li> tag, its content model is "flow content", meaning it can contain almost any HTML element.
Content attributes: The section lists the possible attributes you can specify on the element.
Contexts in which the element can be used: It indicates where the element can be used. For instance, some elements are only valid within specific parent elements. In the case of the <li>, this section explains that <li> should be used inside of <ol>, <ul> or <menu> elements.

The specification also includes many clickable links to help you explore further. For example, if you need a refresher on what "flow content" means, click on the link, and you'll be taken to a detailed overview of that term.

Building a better mental image of the different elements and their purpose

Beyond the category and content model, the HTML specification groups HTML elements into different subsections based on their purpose.

Here are some of the key subsections in section 4 of the specification:

Document metadata: It contains elements used to describe the document itself rather than its content. It includes elements like the <head> element and <title>.
Sections: It groups the different HTML elements that create a new section of the document. Sections are the building blocks of your page layout. It contains elements such as <body>, <article> , <section>, <nav>, etc.
Grouping content: It contains elements such as <p> or <ul> that serve to group content together. For example, a <p> groups related sentences, while a <ul> wraps a list of items.
Text-level semantics: It contains all the elements that give more meaning to inline text, such as <strong>, <time>, or <em>.
Forms: It contains all the elements to create HTML forms. This is where you can find all the different input types that exist.

There are other subsections for embedded content (for HTML elements such as <video> or <img>) and a separate subsection for tables.

The way the different HTML elements are grouped within each subsection is a good reminder that each element has a particular purpose. If you're unsure which element to use, start by asking what role the content plays in your document. For example, if you’re organizing your site’s layout, check the "Sections" subsection first.

Beyond the `<div>` element: Understanding semantic sections in HTML

The <div> element, found in the “Grouping content” subsection of the HTML specification, is a generic container used to group elements without conveying any semantic meaning.

Despite this, many websites still use <div> to wrap entire sections of content. Although valid, there are often better alternatives. The specification provides a set of HTML elements that we can use to describe the different sections more effectively based on their content. Think of each section as a container with its own specific purpose.

Here are some of the key semantic sectioning elements:

<article>: A self-contained and independent section of the document.
<section>: A thematic grouping of content typically including a heading that describes its content.
<nav>: A container for navigation links to other pages or sections of the same page.
<header>: Introduces a section or a page. It typically contains a logo, a main heading, or a table of contents.

Using a <nav> indicates that this section contains essential navigation links. Assistive technologies can use this information to detect navigation blocks more easily. Using a <section> signals that the enclosed content is thematically related and part of the overall document structure (e.g., a section containing all the services your business offers).

The importance of headings to give structure to your document

Heading elements (<h1>, <h2>, etc.) are part of the "Sections" subsection. They are a crucial way to add structure to a document. As mentioned in the spec, 'they represent headings for their sections'. There are some critical takeaways to take from that section:

Headings are a way to create sections within your document.
The different heading levels match the level of nested sections. When you use a <h1>, it means the top-level section. If you use a <h3> after a <h2>, it means a sub-subsection. The levels are a way to add some hierarchy to your content.

Headings form a document outline. An outline is like a table of contents of your different headings in the order they appear on the page. I once read that headings can be thought of as chapters in a book. Getting your headings right is a crucial first step toward making your document more semantic and accessible.

Let's look at a quick example:

<main>
  <h1>Super cool business</h1>
  <section>
    <h2>About</h2>
    <h3>Services</h3>
  </section>
  <section>
    <h2>Guides</h2>
    <h3>How to use our new AI product</h3>
  </section>
</main>

The outline of the following code would be:

- Super cool business
	- About
		- Services
	- Guides
		- How to use our new AI product

Some general rules:

Do not create headings to make some text bigger. A heading marks a section of your document. It should help you determine whether the text is a heading or not.
Don't forget to check the hierarchy of your headings. If you have an h3 after an h2, does that make sense as a sub-subsection?
Think of headings as a table of contents. This will help determine whether any headings are missing on the page. You can use an extension to quickly view the outline of your document. I use HTML5 Outliner.

Let's use the spec to answer some HTML questions

Let's see how the spec can help answer some HTML questions.

Question 1: Is it valid HTML to use a `<p>` tag inside a `<button>` element?

Can I write code like this?

<button>
	<svg>/* some cool svg content */</svg>
	<p>See offer details</p>
</button>

Let's answer that step by step!

First, let's look for the <button> element in the spec.
To check what the element can contain, we can look at its content model. It states that it expects phrasing content and that you should not nest any interactive element inside of a button. For instance, even if an anchor link is considered phrasing content, you should not nest it inside of a button.
If you search for the <p> tag inside the spec, you'll see it is not phrasing content.
Therefore, we cannot use a <p> tag inside a <button>.

There are different options to fix the HTML. If it's about making the text take up its own line, we can add some CSS to the button, for instance.

Question 2: How to caption or annotate an image?

Let's imagine we have this piece of code:

<img src="https://cute-dog-pic.png" alt="A golden retriever holding a tennis ball in its mouth" />
<p>Our dog Poppy right before its 2nd birthday</p>

With CSS, we can make the <p> tag appear next to or underneath the picture. However, in the HTML, how do we group those two elements? Let's look at the specs!

We are trying to create a relationship between 2 elements. So, the "Grouping content" subsection might be the best place to look.
There are lots of different elements (<p>, <ul>, <ol>) in this subsection. However, for our image, the <figure> element is likely the most suitable choice in our case.
We see that the <figure> represents self-contained content, making sense on its own, optionally accompanied by a caption.
In this case, we can use it to group our image with the text underneath, which we can then turn into a <figcaption>.

<figure>
	<img src="https://cute-dog-pic.png" alt="A golden retriever holding a tennis ball in its mouth" />
	<figcaption>Our dog Poppy right before its 2nd birthday</figcaption>
</figure>

Conclusion and quick tips

This is a brief overview of how to get started with the HTML spec and start using it. It may appear daunting at first, as it contains a lot of information. However, I hope this blog post gives you a glimpse of how useful it is when trying to mark up a document and choose what element to use.

Some last quick tips:

You can use the element index if you want to check for a specific HTML element. It will link you back to the specific section in the spec.
When reading the spec, if you wonder what an element can contain, look at the content model.
Read the examples as they often complement or expand on how to use the element.
Ask yourself how to describe the content best when you choose an HTML element.

Resources

How to set up a pre-commit Git hook with Husky and lint-staged

2025-05-26T00:00:00Z

Git hooks are a great way to automatically run specific tasks (such as formatting or linting tasks) at key moments in your Git workflow. In this post, we'll explore Git hooks and walk through how to set up a pre-commit hook using Husky and lint-staged to lint and format your staged files automatically. Let’s dive in.

What are Git hooks?

As mentioned in the Git documentation, Git hooks are a way to run scripts at specific moments in your Git workflow. They can help automate repetitive checks and enforce formatting or linting rules that help collaboration.

Inside any Git-tracked project, open the .git folder. You’ll find a series of folders that include a hooks folder.

Structure inside a .git folder showing the hooks directory, among others.

The hooks folder contains example hook scripts (e.g., pre-commit.sample) that you can customize to automate tasks before commits, pushes and more. To make our lives easier, we’ll use husky to set up a Git hook. Husky makes it easy to create shareable Git hooks that you can add to version control.

Setting up the demo project

In this blog post, we’ll work with a simple repository that contains a small React app created with Vite.

To follow along, scaffold a Vite React and Typescript app:

npm create vite@latest demo-git-hooks-husky -- --template react-ts
cd demo-git-hooks-husky && npm install

At this point, you have a basic “Hello World” React app. The Vite boilerplate includes an eslint.config.js file to lint the files. Let’s install prettier to format our files:

npm install --save-dev prettier

Then, create .prettierrc at the root of the project with basic rules:

{
  "arrowParens": "always",
  "bracketSpacing": false,
  "printWidth": 80,
  "semi": false,
  "singleQuote": true,
  "tabWidth": 2,
  "trailingComma": "es5",
  "useTabs": false
}

Installing and configuring Husky

Husky is a development dependency to make it easier to add Git hooks. First, let’s install it:

npm install --save-dev husky

Once Husky is installed, run the following:

npx husky init

As explained in the official documentation, this command adds a “prepare” script to the package.json and creates a pre-commit hook in the .husky folder you should now have at the root of your repository.

The prepare script is one of the NPM lifecycle scripts that run automatically at specific moments. The prepare script runs on local npm install even when no arguments get passed (see the NPM doc for more details on the prepare script). This means that any developer who installs the project dependencies will automatically have the Git hooks correctly set up with Husky.

Let’s configure the pre-commit hook that was automatically created to make it more relevant to our project!

Configuring the `pre-commit` script with lint-staged

In our demo app, we have linting and formatting rules we want to apply to all our source files. While you could run linting and formatting as a GitHub action on push or pull requests, a pre-commit hook provides faster feedback by catching issues before a commit is created. When we try to commit a series of changes, we can write our Git hook to run a list of checks before a commit gets created.

Update the package.json lint and format scripts

By default, the pre-commit hook in .husky contains:

npm test

A good start is to ensure that all files are checked by our linter and formatted before they are committed to Git. In our package.json, we already have a lint script. Let's add a few more:

{
  "scripts": {
    "lint": "eslint .",
    "lint:fix": "eslint --max-warnings=0 --fix",
    "format": "prettier --write .",
    "format:file": "prettier --write"
  }
}

lint runs eslint on all the files.
The lint:fix script will try to auto-fix linting issues where possible. With the flag --max-warnings=0, it will fail (exit with an error) if any errors or warnings remain. We’ll use this script in our pre-commit to add an extra layer of protection and make sure to know as soon as possible if we need to fix the code manually.
format will format and write the changes.
The format:file script formats the files passed to it, which works well with lint-staged since it provides the staged files as input. It is a slight optimization as a way to only run prettier on staged files and not on the whole project.

Setting up lint-staged to lint and format staged files

lint-staged is an NPM package that will help us run our linter or formatter on staged files. We don’t want commits to fail because of issues in unrelated files. lint-staged will help us run the checks we define in our pre-commit hook on the files that are in the Git staging area. The Git staging area is where your tracked files get placed after you use git add the-file-you-modified.

Let’s install lint-staged:

npm install --save-dev lint-staged

There are many options to configure lint-staged. One of them is to create a .lintstagedrc at the root of the project.

touch .lintstagedrc

In the configuration file for lint-staged, we associate file extensions with the npm scripts we want to run for those files. Let’s add the following config to our .lintstagedrc:

{
  "*.{js,jsx,ts,tsx}": ["npm run lint:fix", "npm run format:file"],
  "*.{json,md,mdx,css,scss,html,yml,yaml}": "npm run format:file"
}

You can also add lint-staged configuration directly in the package.json if you do not want to create an extra configuration file:

{
  "lint-staged": {
    "*.{js,jsx,ts,tsx}": ["npm run lint:fix", "npm run format:file"],
    "*.{json,md,mdx,css,scss,html,yml,yaml}": "npm run format:file"
  }
}

Let’s now add an NPM script to the package.json to run lint-staged:

{
  "scripts": {
    "check:precommit": "lint-staged"
  }
}

Use lint-staged with the husky `pre-commit` hook

Now that we have lint-staged configured, we can modify the .husky/precommit file and use the check:precommit script we have added to the package.json. In .husky/pre-commit, add the following content:

npm run check:precommit

With all those changes, we now have a working pre-commit setup that uses eslint and prettier on the files we want to commit.

Under the hood: how does husky work?

When husky is installed, it runs a script that updates the .git/config file by setting the core.hooksPath to the .husky directory. This tells Git to look in .husky for hook scripts instead of the default .git/hooks directory.

In .git/config:

[core]
  ...
  hooksPath = .husky/_

In the husky source code, in the index.js, there is a statement that sets up the hooksPath:

let {status: s, stderr: e} = c.spawnSync('git', [
  'config',
  'core.hooksPath',
  `${d}/_`,
]);

In the above snippet, c.spawnSync is a way to launch a child process in Node. This is like running git config core.hooksPath <some_path> in the terminal.

Final project setup overview: Putting everything together

Here's a quick overview of the key files and their contents once everything is configured:

In package.json:

{
  "scripts": {
    "lint": "eslint .",
    "format": "prettier --write .",
    "format:file": "prettier --write",
    "lint:fix": "eslint --max-warnings=0 --fix",
    "check:precommit": "lint-staged"
  },
  "devDependencies": {
    "eslint": "...",
    "husky": "...",
    "lint-staged": "...",
    "prettier": "..."
  }
}

In .husky/pre-commit:

npm run check:precommit

In .lintstagedrc:

{
  "*.{js,jsx,ts,tsx}": ["npm run lint:fix", "npm run format:file"],
  "*.{json,md,mdx,css,scss,html,yml,yaml}": "npm run format:file"
}

This provides a fast, local pre-commit workflow to catch linting or formatting issues before they are committed to Git.

You can find the whole demo on GitHub.

Troubleshooting

If the pre-commit does not work:

Make sure you've staged the files using git add.
Make sure you've staged a file that your lint-staged configuration supports (a tsx, js or whatever extension you have configured).
Reinstall the dependencies if you do not see a .husky folder at the root of your project.

Conclusion

In this blog post, we explored how to use husky to create a pre-commit hook and how to use lint-staged to run checks on staged files. Pre-commit hooks help catch problems early and are a fantastic way to improve consistency when working on a shared codebase. I hope you find this blog post helpful. If you have any questions, don’t hesitate to reach out on Bluesky 😀

Resources

How to use jq with curl to explore an API’s JSON response

2025-06-22T00:00:00Z

jq is a useful command-line tool to process a JSON payload quickly. I tend to use jq in conjunction with curl to explore third-party APIs. jq is a powerful tool for filtering or transforming JSON data. In this article, we’ll explore a couple of its functionalities while playing with two free third-party APIs. The goal is to become more comfortable with jq by the end of the blog post and to have started building a cheat sheet of our own.

How to install `jq`

To install jq, you can download the binary on the jq website. If you are on a Mac, you can install jq with homebrew:

brew install jq

For a complete set of installation instructions, check out the Github repository section on that topic.

What is jq and what can we do with it?

jq is described in its official documentation as a “lightweight and flexible command-line JSON processor”. jq is lightweight and quick (it is written in C). Its flexibility comes from the number of features and possibilities available when using it. You could use jq to:

Pipe JSON data (curl <URL> | jq .) and get a formatted and colored output.
Filter out keys and quickly extract the data you are interested in from a JSON output.
Sort a JSON output based on a specific key.
Limit the JSON output to n elements (for instance, you might want the first five elements from a JSON array).
Retrieve all the keys of a JSON response (this might be handy when interacting with a third-party API).
And much more!

In all the commands we’ll explore, we’ll pipe JSON data to jq to process. Piping means taking the output of a command (such as curl returning API data) and directly passing it to another program for processing. In the shell, to pipe an output, we use the | symbol. For instance:

curl <URL> | jq .

The previous command uses curl to fetch the data available at a given URL. Then, it passes the data to jq.

You don’t need to pipe data to jq to use it. You can pass a JSON file to jq as an argument:

jq . <filepath_to_json_file>

Processing JSON data with `jq`

Let’s get started working with JSON arrays. For this section, we will use the JSON placeholder that provides dummy To-Do API endpoints.

curl -s https://jsonplaceholder.typicode.com/todos

With this command, we obtain a JSON array of 200 elements.

Extract the length of a JSON array with `jq`

If you are wondering how many items are in a JSON array, you can use the length helper in jq:

curl -s https://jsonplaceholder.typicode.com/todos | jq length

In your terminal, you should see a single number as an output (200 in our case).

Getting an item at a given index from a JSON array with `jq`

Getting the first item of a JSON array is as simple as typing jq '.[0]':

curl -s https://jsonplaceholder.typicode.com/todos | jq '.[0]'

To get the last item of an array, you can use jq '.[-1]':

curl -s https://jsonplaceholder.typicode.com/todos | jq '.[-1]'

Getting `n` elements of an array with `jq`

To get the first five elements, you can use a similar notation to Go’s slices:

curl -s https://jsonplaceholder.typicode.com/todos | jq '.[:5]'

When you write down [:5], it means all the indices (starting at 0) excluding the index of 5. You can provide the starting index if you have a range in mind:

curl -s https://jsonplaceholder.typicode.com/todos | jq '.[2:5]'

The above command jq ‘[2:5]’ includes three elements (the elements at index 2, 3, and 4).

Selecting specific properties

Let’s switch things up! Many APIs include a large amount of data that we may not be interested in. Let’s use the swapi API to explore a more complex dataset.

If we retrieve the Star Wars characters using the API's people endpoint, we’ll see that the output puts all the characters in a results key. The top-level keys in the output JSON object include pagination data.

To solely include the people, we can write:

curl -s https://swapi.py4e.com/api/people/ | jq ".results"

The jq “.results” will process the JSON data and output the result array.

Then, we can use the previous commands we have learned. We could get the first character from the people API using the following command:

curl -s https://swapi.py4e.com/api/people/ | jq ".results | .[0]"

We can go even further than that. We can extract the keys we are interested in from the results array.

Using the map function to pick specific keys from array items

map in jq will do something similar to the map array function in JavaScript. It applies a given transformation to each item in the array.

In jq, we can build new JSON objects with the properties we want using a shorthand like {name, url}. This syntax is equivalent to writing {“name”: .name, “url”: .url}. In our case, we can pass this shorthand to map:

curl -s https://swapi.py4e.com/api/people/ | jq ".results | map({name, url})"

It extracts the results properties and maps each item in the results array to a smaller object containing only the name and url fields. In your terminal, you should see an output that looks like the following snippet:

[
  {
    "name": "Luke Skywalker",
    "url": "https://swapi.py4e.com/api/people/1/"
  },
  {
    "name": "C-3PO",
    "url": "https://swapi.py4e.com/api/people/2/"
  }
  // more data...
]

Beyond picking the properties we are interested in, we can filter the data using jq. Let’s look at how next!

Filtering data using the `select` function in `jq`

Let’s imagine we are looking for one character in particular in our Star Wars API. We can use the select function to filter by a specific property, such as name in our case.

We can do the following:

Use curl to retrieve data from a specified URL.
Combine the map and select functions to look for our character.

curl -s https://swapi.py4e.com/api/people/ | jq '.results | map(select(.name == "Obi-Wan Kenobi"))'

In the above command, we will select items with a name that matches the string “Obi-Wan Kenobi”.

If we want to be less restrictive, we can use a regex:

curl -s https://swapi.py4e.com/api/people/ | jq '.results | map(select(.name | test("Leia"; "i")))'

We pipe the .name property of each item to the test function. The second argument of test is to make the matching pattern case-insensitive.

There are other functions we can use with select, such as startswith or endswith. For instance, let’s say we want all the movies whose title starts with 'The'. We could write the following command:

curl -s https://swapi.py4e.com/api/films/ | jq '.results | map(select(.title | startswith("The")))'

We first pick the .results property from the JSON object returned by the API.
Then, we use map to indicate this is an operation on each list item. For each list item, we want to select the films with titles that start with “The”.

Sorting an array of objects with `jq`

Another useful feature of jq is the ability to sort data using the sort_by function.

Let’s go back to our Star Wars API. Let’s imagine we want to sort the characters by their height.

curl -s https://swapi.py4e.com/api/people/ | jq ".results | sort_by(.height | tonumber) | reverse | map({name, height})"

Let’s dissect that command:

We curl the people endpoint from the Star Wars API.
We pick the results property as it contains the array of characters on the first page.
We sort the array by each element’s height. Because the API returns each character height as a string, we must convert each height to a number to obtain a correct sorting result.
We pass to sort_by the property we want to use to sort our array. We can convert the property if needed. In the example, we use tonumber to cast each string into a number.
Then, we can pipe the results to reverse if we want to reverse the order of the results. In our case, it will return an array from the character with the largest height to the character with the smallest height.
Finally, we use map to extract the name and height of each character.

The output looks like:

[
  {
    "name": "Darth Vader",
    "height": "202",
  },
  {
    "name": "Biggs Darklighter",
    "height": "183",
  },
  {
    "name": "Obi-Wan Kenobi",
    "height": "182",
  },
  // some more sorted data...
];

Inspecting the keys of a payload

To get a quick idea of what keys a given JSON payload contains, you can use the keys function.

curl -s https://swapi.py4e.com/api/people/ | jq "keys"

In a glimpse, we get back an array of all the keys from the API response:

["count", "next", "previous", "results"]

If we wanted to get an idea of what type of data the API has for a character, we could do:

curl -s https://swapi.py4e.com/api/people/ | jq ".results[0] | keys"

In this command, we look at the first element of the result array and get back its keys:

// output from the previous curl command
[
  "birth_year",
  "created",
  "edited",
  "eye_color",
  "films",
  "gender",
  "hair_color",
  "height",
  "homeworld",
  "mass",
  "name",
  "skin_color",
  "species",
  "starships",
  "url",
  "vehicles"
]

Cheat sheet and recap

Here's a small list of the different commands we tried in this post:

curl <URL> | jq .: to pretty-print JSON from an API.
jq . <file.json>: to process JSON data from a local file.
curl -s <URL> | jq length: to count the number of items in an array (it will only work with JSON arrays).
curl -s <URL> | jq '.[0]': to get the first element of an array.
curl -s <URL> | jq '.[-1]': to get the last element of an array.
curl -s <URL> | jq '[:5]': to get the first N elements of an array (in this case 5).
curl -s <URL> | jq '.[2:5]': to get a slice of an array (indices 2 to 4 in this example).
curl -s <URL> | jq '.results': to extract a specific key from a JSON object.
curl -s <URL> | jq '.results[0]': to get the first object in an array of objects.
curl -s <URL> | jq '.results | map({name, url})': to map array and extract specific keys from each array item.
curl -s <URL> | jq '.results | map(select(.name == "Obi-Wan Kenobi"))': to filter array items using an exact match.
curl -s <URL> | jq '.results | map(select(.name | test("Leia"; "i")))': to filter array items using a regular expression.
curl -s <URL> | jq '.results | map(select(.title | startswith("The")))': to filter array items where their title starts with a given string.
curl -s <URL> | jq '.results | sort_by(.height | tonumber) | reverse | map({name, height})': to sort by height (casting the height into a number), using a descending order.
curl -s <URL> | jq 'keys': to list the keys at the root level.
curl -s <URL> | jq '.results[0] | keys': to list the keys of the first item in the results array.

Conclusion

In this article, we explored the jq command-line utility. It is a powerful tool for processing and transforming JSON data. We’ve only brushed the surface of what jq can do. I hope this post provides some ideas on how to use it. As always, if you have any questions or want to chat about jq or other command-line tools, reach out on Bluesky!

Resources

Build Git helpers from scratch with Bash and fzf

2025-08-03T00:00:00Z

fzf is a command-line fuzzy-finder you can run in your terminal to filter any list of files, command history, and more. fzf is versatile and can be used in combination with other tools such as grep and Git.

In this blog post, we’ll explore how to create small bash helpers for Git using fzf. By the end of this post, you’ll understand what fzf is and how to combine its power with other tools. I hope this tutorial also gives you lots of ideas for applying similar techniques to build your own helpers. Let's get started!

Note: if you're looking for a prebuilt plugin with Git and fzf integrations, check out fzf-git.sh by the creator of fzf. This blog post focuses on building small helpers from scratch combining different programs to make the whole thing less intimidating. Playing around with Bash and fzf is a lot of fun. I hope you enjoy the post!

What fzf is and how to install it

fzf is a command-line fuzzy-finder. It is a tool that enables you to quickly browse any kind of list and search for matches by typing.

In the fzf repository on Github, you can find detailed instructions on how to install it based on your operating system.

On MacOS, the easiest way is to install it using homebrew:

brew install fzf

Once you’ve installed it, if you type fzf in your terminal, you should see a list of all the files in your current directory.

fzf

Integrate fzf with Bash

fzf integrates well with several shells, including Bash and Zsh. Integrating it with your shell activates a series of cool features, such as being able to select a command in your command-line history and paste it.

Add this to your bashrc:

# Set up fzf key bindings and fuzzy completion
eval "$(fzf --bash)"

If you are following along using another shell, check out the official documentation on how to set shell integration.

Don’t forget to source your shell config after modifying it (e.g., source ~/.bashrc).

Now, what does adding shell integration do? You should now be able to type <Ctrl-r> (Control key + r) in your terminal, select a command from your history, and paste it directly into your terminal.

I use this keybinding all the time. Now, let’s move to the next level and see how we can build useful utilities with fzf.

Combine the power of fzf with Git to create small helpers

fzf is a fuzzy-finder, and you can pipe data from many sources, including Git, into it. This makes it easy to create small helpers. Let’s build a couple of helpers to use Git more efficiently. To follow along, create a new file in your home directory called .bash_helpers (you can call it whatever you want!):

touch ~/.bash_helpers

Then, source it in your .bashrc. Sourcing it tells your shell to import all the functions from the ~/.bash_helpers so you can use them.

# Add this to your ~/.bashrc
source ~/.bash_helpers

It is a good way to keep things more organized.

After modifying .bashrc or .bash_helpers, don't forget to source your shell config (source ~/.bashrc) in your terminal to apply the changes.

Let’s create a helper to check out a specific git branch

If you navigate to a local Git repository, you can list all of your branches using:

git --no-pager branch

In the above command:

--no-pager is used to remove Git pagination and get the full list of branches.

If we pipe it to fzf, we end up with a list of the git branches that we can search through and select.

git --no-pager branch | fzf

The idea for this first example is to create a helper that shows us the list of branches through fzf and, when we select a branch, we switch to that branch.

In the .bash_helpers, let’s create a function and let’s call it, for instance, sfb (for “switch find branch”):

function sfb() {
	local line branch
	line=$(git --no-pager branch -vv | fzf)
	branch=$(echo "$line" | sed -E 's/^[* ]+([^ ]+).*/\1/')
	git switch "$branch"
}

Let's break down what this function does:

With local, we create two local variables scoped to the function: branch and line.
line stores the full row selected from the fzf list, which includes extra info like the tracking status.
branch stores the branch name extracted from the line variable.
We use sed to extract the branch name. When you run git branch, you’ll see output like this: an asterisk in front of your current branch and some extra information like tracking details. The sed command strips away all this extra formatting to get a clean branch name.
Let's look at what this sed command sed -E 's/^[* ]+([^ ]+).*/\1/' does.
- sed is called a stream editor. It is a way to modify a stream of text.
- -E enables us to pass a regular expression to sed to edit a given string.
- ^[* ]+: We start by matching any asterisk or space at the start of the line.
- ([^ ]+): It is a capture group for the branch name. It takes any subsequent character that is not a space. And it will stop the capture group once it encounters a space.
- .*: We match with .* any other character that follows the branch name.
- With \1, we tell sed to replace the input string with the capture group that contains the branch name.
git switch is equivalent to git checkout and will check out the branch we selected.

Next, before testing it, we could add an extra check to make sure the command is run in a Git repository. Let's use the handy command git rev-parse --is-inside-work-tree. This Git command returns a boolean indicating whether we are in a Git repository or not.

function sfb() {
	if ! git rev-parse --is-inside-work-tree &>/dev/null; then
		echo "Error: Not inside a Git repository"
		return 1
	fi

	local line branch
	line=$(git --no-pager branch -vv | fzf)
	branch=$(echo "$line" | sed -E 's/^[* ]+([^ ]+).*/\1/')
	git switch "$branch"
}

git rev-parse returns a boolean. If it returns false, we exit the function.
&>/dev/null: It is a way to ignore the output of the Git command. &> redirects both standard output and standard error to /dev/null, which is what is called a "Null device". It is a way to discard the command output completely.

Let’s give it a go. Save your file and go back to your shell. Source your bashrc (source ~/.bashrc). Go to a local repository that has several branches and type in your command line:

sfb

Here's an example output of running this command:

You should see the fzf picker showing all your Git branches. The * in front of the branch indicates your current checked-out branch. If you select one, you should now be checked out on that other branch.

Extracting the `git rev-parse` check in its own function

We will reuse the logic to check whether the directory is a Git repository. Let's extract the logic with git rev-parse in a function for easier reuse. In your .bash_helpers, add:

function ensure_git_repo() {
	  if ! git rev-parse --is-inside-work-tree &>/dev/null; then
        echo "Error: Not inside a Git repository"
        return 1
    fi
}

We can then use it in our sfb helper:

function sfb() {
	ensure_git_repo || return 1

	local line branch
	line=$(git --no-pager branch -vv | fzf)
	branch=$(echo "$line" | sed -E 's/^[* ]+([^ ]+).*/\1/')
	git switch "$branch"
}

ensure_git_repo || return 1 is a shorthand syntax. It is equivalent to doing:

	if ! ensure_git_repo; then
		return 1;
	fi

With the || syntax, if the first expression is truthy, the second expression does not get checked. In our case, if ensure_git_repo is successful (returns 0), the return 1 won't get evaluated.

Let's create a helper to delete a Git branch using fzf

Using a very similar logic, we can create a helper to delete a branch. Let’s create another function dfb (that stands for “delete find branch”) and reuse the branch selection through fzf logic:

function dfb() {
	# Let's use our helper to check if it is a Git repository
	ensure_git_repo || return 1

	local line branch
	line=$(git --no-pager branch -vv | fzf)
	branch=$(echo "$line" | sed -E 's/^[* ]+([^ ]+).*/\1/')
}

Now, because it is a destructive operation, let’s add a confirmation step. With Bash, we can use read -p to get user input and confirm that the user wants to delete the branch:

function dfb() {
	ensure_git_repo || return 1

  local line branch
	line=$(git --no-pager branch -vv | fzf)
	branch=$(echo "$line" | sed -E 's/^[* ]+([^ ]+).*/\1/')

	# show the user what command it is about to run
	echo "git branch -D $branch"
	read -p "Are you sure you want to delete this branch? [y|n]" -n 1
	echo ""

	if [[ $REPLY =~ ^[Yy]$ ]]; then
		git branch -D "$branch"
	else
	  echo "Branch deletion aborted"
  fi
}

read -p will prompt the user. -n 1 means we only take one character from the user input.
$REPLY is a global shell variable. By default, read will store the user input in $REPLY
In the if statement, we use =~ to match the user input with a regular expression ^[Yy]$. If the user types Y or y, we delete the branch.

Let’s try it out. In your shell, source your bashrc and then type:

dfb

It should show you a list of branches. If you select one, you will be prompted to confirm whether you want to delete it.

Let’s create a helper to choose a commit to rebase a branch onto

One of my favorite Git + fzf utilities is one I call gri. It enables me to choose the commit I want to rebase my branch on. Let’s build this one together.

First, let’s create a Bash function called gri (it stands for “git rebase interactive”).

function gri() {
	ensure_git_repo || return 1
}

First, we need to list all the commits and pipe them to fzf.

git log --color=always --pretty=oneline --abbrev-commit

--color=always keeps the colored output.
--pretty=oneline keeps the commit information on a single line.
--abbrev-commit shortens the commit hash.

If you try out this command, it will print out in this format:

Next, we need to pipe it into fzf to allow the user to select a commit.

function gri() {
	ensure_git_repo || return 1

	local line commit
	line=$(git log --color=always --pretty=oneline --abbrev-commit | fzf --ansi)
}

To keep the colored output, we pass --ansi to fzf.

To extract just the commit hash, we can use sed again. Here’s what the final function looks like:

function gri() {
	ensure_git_repo || return 1

	local line commit
	line=$(git log --color=always --pretty=oneline --abbrev-commit | fzf --ansi)

	if [[ -z "$line" ]]; then
		return
	fi

	commit=$(echo "$line" | sed -E "s/^([^ ]+).*/\1/")
	git rebase "$commit"
}

We use a capture group in the regular expression in sed to capture the commit hash only.
-z is a string test operator in Bash. It checks if the string is empty. This condition handles the case when the user doesn’t select a commit.

Now test it in your terminal:

gri

You should see a menu with your commits. If you select one, you’ll be taken to Git’s interactive rebase menu.

Other ideas

In this post, we explored the power of fzf, taking git as an example. But you can use it with many other programs. One recent use case I had was that I wanted to select a Docker container to execute a command inside of it. At work, I have at times 60 containers running simultaneously, so it can be tricky to find the one I’m looking for.

I ended up doing a command that looked like that:

docker exec -it $(docker ps --format "{{.Names}}" | fzf) sh

docker container exec allows you to execute a command inside a running container.
-it means that I want to have an interactive mode within the container.
sh is the program I want to launch within the container.
docker ps --format “{{.Names}}” lists out only the names of the containers.

We could put this command in a Bash function, too. There are so many useful use cases of using fzf. The sky is really the limit!

Complete code from this post

You can find all the code from this post in the fzf-git-tutorial repository on Github.

Conclusion

In this blog post, we explored fzf and built together a couple of Bash utils combining the power of fzf with Git. We built one to check out a Git branch, being able to pick from the available local branches. We also looked at how to build a helper to rebase onto a commit by using fzf to see a list of the different commits. We've only really scratched the surface of all the useful things we could do with fzf. I hope this blog post gives you some ideas! You can find all the code examples from this tutorial in the fzf-git-tutorial repository. Like always, if you have any questions or would like to share some of your own utils, don’t hesitate to reach out on Bluesky!

Versions used in this post

Here are the versions of Bash and fzf used in this post:

bash --version
# GNU bash, version 5.2.37(1)-release (aarch64-apple-darwin23.4.0)

fzf --version
# 0.65.0

git --version
# git version 2.50.0

You don't need these exact versions, but if you run into any issues (particularly with Bash), try updating Bash or fzf.

Further resources

fzf Github repository
Bash scripting cheatsheet
fzf-git-tutorial repository
My Bash utility functions in my dotfiles
For a more advanced Git + fzf integration, check out fzf-git by the creator of fzf

How to test packages locally before publishing using yalc

2025-11-16T00:00:00Z

If you maintain an npm package, you might want to test changes locally in an app that depends on it before publishing. This article shows how to do that using yalc, an alternative to npm link and yarn link.

In this tutorial, we’ll use a common real-world example: a shared frontend configuration package consumed by an application. We’ll add new configuration settings to the frontend config package and test how those changes affect the app that uses it without publishing or pushing any code on GitHub.

This tutorial uses a React-based example, but the workflow using yalc is the same regardless of whether you use Vue, Svelte, or another framework.

Initial setup

In this tutorial, we’ll use two repositories:

tutorial-frontend-config: this is the repository containing the frontend configuration to be shared across projects. It contains ESLint and Prettier configuration files.
react-yalc-tutorial: it’s a small application built with Vite. It is a typical React/TypeScript app with a few components. It already uses the tutorial-frontend-config.

# Clone the frontend config package and install its dependencies
git clone git@github.com:liv7c/tutorial-frontend-config.git
cd tutorial-frontend-config
npm install

# Go back to your parent folder (if needed)
cd ..

# Clone the example React app and install its dependencies
git clone git@github.com:liv7c/react-yalc-tutorial.git
cd react-yalc-tutorial
npm install

Before we continue, let’s install yalc globally so it’s ready to use:

npm install -g yalc

Everything is set up, so let’s get started.

Let’s update the config package

The tutorial-frontend-config repository contains all our shared frontend configuration rules for linting and formatting. We have a published version on npm, and several projects already depend on it. Let’s say we want to try out a new ESLint plugin: eslint-plugin-perfectionist. It not only handles import ordering but also includes sorting rules for TypeScript types and component props. Let’s go to our frontend config repo and create a new Git branch:

cd PATH_TO_REPO/tutorial-frontend-config
git switch -C feature/use-perfectionist-eslint-plugin

A quick tour of the tutorial-frontend-config repository

The tutorial-frontend-config repository is an npm workspace. A workspace is a way to have multiple packages within the same repo. In this case, there are two packages:

configs that contains the package published on npm.
example-app: a demo app that consumes the configs package.

Here are a few useful details about npm workspaces:

When you run npm install at the root of the workspace, it will install the dependencies of all workspace packages. This works thanks to the workspace property in the root package.json:

// in package.json
  "workspaces": [
    "packages/*",
    "example-app"
  ],

Packages can reference each other. I have an example app in the repo that references the other workspace package in its dependencies:

// in example-app/package.json
    "@oliviacl/tutorial-frontend-config": "*",

When you want to work on a specific package inside a monorepo, navigate into that package’s folder. Each package has its own package.json file, which contains specific dependencies. In our case, we’ll be working in the configs package.

cd tutorial-frontend-config/packages/configs

Let’s add the Perfectionist plugin to our ESLint config

The goal is to modify the ESLint config to use a new plugin: eslint-plugin-perfectionist.

Make sure you are in the correct directory (tutorial-frontend-config/packages/configs).

If we examine the eslint.js file, we currently use eslint-plugin-import with a few rules. With eslint-plugin-perfectionist, we can remove eslint-plugin-import and the rules we had for this plugin, as the perfectionist plugin will handle those functionalities. In the packages/configs directory, run:

npm uninstall eslint-plugin-import

Then remove all references to eslint-plugin-import from eslint.js:

// remove import
import importPlugin from "eslint-plugin-import";

// eslint.js
export default [
	// delete the plugin from the plugins section
  plugins: {
	  // Delete the following line
	  import: importPlugin,
  },
  rules: {
	  // Delete this block in the rules
      'import/order': [
        'warn',
        {
          groups: ['builtin', 'external', 'internal', 'parent', 'sibling', 'index'],
          'newlines-between': 'always',
          alphabetize: { order: 'asc', caseInsensitive: true },
        },
      ],
	}
]

Let’s commit those changes:

git add . && git commit -m 'chore(eslint): remove eslint-plugin-import with rules'

Then, let’s install the new ESLint plugin (make sure you are still in the packages/configs directory):

npm install eslint-plugin-perfectionist

We add it as a dependency so projects using our config don’t need to install it themselves.

Let’s update our ESLint config to use the plugin. We can use a ready-made config as mentioned in the plugin documentation.

First, import the plugin:

// in eslint.js
import perfectionist from 'eslint-plugin-perfectionist';

Then, add the perfectionist plugin:

// in eslint.js

export default [
  js.configs.recommended,
  ...tseslint.configs.recommended,
  perfectionist.configs['recommended-natural'],
  // ...
];

Let’s commit this:

git add . && git commit -m "feat(eslint): add perfectionist plugin"

Testing our changes with yalc

This is where yalc comes in. We want to test the changes we made to our ESLint config before pushing or publishing the changes.

Publishing our package locally via yalc publish

yalc creates a local store on your computer inside a ~/.yalc directory. We can publish packages to this directory. yalc then makes it easy to use the packages published to that local store in applications that depend on them.

In the packages/configs directory, run:

yalc publish

After running the command, you should see the following message in your terminal:

@oliviacl/tutorial-frontend-config@1.0.4 published in store.

If you inspect the .yalc directory in your home folder, you should see the following structure:

❯ tree ~/.yalc
.yalc
├── installations.json
└── packages
    └── @oliviacl
        └── tutorial-frontend-config
               └── 1.0.4
                ├── CHANGELOG.md
                ├── eslint.d.ts
                ├── eslint.js
                ├── index.d.ts
                ├── index.js
                ├── package.json
                ├── prettier.d.ts
                ├── prettier.js
                ├── README.md
                └── yalc.sig

5 directories, 11 files

Adding the package via yalc add

Now, let’s change directory and move to the tutorial application we cloned in the previous section:

cd PATH_TO_REPO/react-yalc-tutorial

Make sure you’ve run npm install first. Now, to use our package published in the yalc local store, we only need to run:

yalc add @oliviacl/tutorial-frontend-config

If you open your package.json, you’ll see that the dependency was replaced with a reference to the .yalc directory:

	// in your package.json
  "devDependencies": {
    "@oliviacl/tutorial-frontend-config": "file:.yalc/@oliviacl/tutorial-frontend-config",
  }

Inside the repo, you should also see a .yalc folder containing the latest version of your package. When you run yalc add, yalc copies the package from the ~/.yalc store into your repo.

Run npm install. This will install any new dependencies required by the updated ESLint config.

If you run npm run lint, you should see new warnings coming from this new plugin:

It works!

Making multiple changes and propagating them with `yalc push`

Now, let’s say we want to make more changes to tutorial-frontend-config. In tutorial-frontend-config, we could modify the prettier config and update it to use double quotes, for instance:

// in packages/configs/prettier.js
export default {
  semi: true,
  trailingComma: 'es5',
  // we switch singleQuote from true to false
  singleQuote: false,
  printWidth: 100,
  tabWidth: 2,
  useTabs: false,
  arrowParens: 'always',
  endOfLine: 'lf',
};

To propagate the changes, no need to run yalc publish. You can run:

# run this command from packages/configs
yalc push

yalc push pushes the changes to the Yalc store and automatically updates all projects using the published version in yalc.

You should see a command output that looks like this:

@oliviacl/tutorial-frontend-config@1.0.4 published in store.
Pushing @oliviacl/tutorial-frontend-config@1.0.4 in /Users/YOUR_USERNAME/projects/react-yalc-tutorial
Package @oliviacl/tutorial-frontend-config@1.0.4 added ==> /Users/YOUR_USERNAME/projects/react-yalc-tutorial/node_modules/@oliviacl/tutorial-frontend-config

If you go back to the react-yalc-tutorial project and open the .yalc folder, you should see that the Prettier file has been updated. And if you run npx prettier --check src or enable format-on-save, you should see the new Prettier rules being applied.

Cleaning things up when done testing with `yalc remove`

Once we’re done testing, we can run the following command inside react-yalc-tutorial:

yalc remove @oliviacl/tutorial-frontend-config

This command removes the yalc entry from package.json and cleans up the yalc.lock file.

If you’re testing multiple packages with yalc and want to remove all of them at once, run:

yalc remove --all

Working with component libraries

In this tutorial, we worked with a configuration package that doesn’t require a build step. However, the workflow with yalc is almost the same when working with a component library that has a build step. The only difference is that you will want to run npm run build to build your library before running yalc publish or yalc push. yalc will copy all the files that should be published, using your package.json as a source of truth.

npm run build && yalc publish

Conclusion

In this post, we looked at how to use yalc to test a package locally without publishing it or pushing any changes. It’s a very useful tool for trying out changes locally. yalc is a great alternative to npm link or yarn link and, as you saw in the example, is pretty straightforward to use.

I hope this tutorial was helpful! As always, if you have any questions or would like to chat, don’t hesitate to reach out on Bluesky.

Extra resources

Improve your Git CLI experience with Git aliases, delta, and custom functions

2026-02-27T00:00:00Z

In this article, we’ll explore various settings we can add to our Git config to make it nicer to work with when using the Git command-line interface. We’ll look at Git aliases, customizing the Git pager, and custom functions you could build on top of Git. One of the best aspects of using the Git CLI is the number of customizations you can add to match your workflow. The beauty of it is that all those customizations are portable. You can switch editor and your Git workflow stays the same.

A quick tour of the gitconfig

There are many ways to configure Git. You can configure it at the repository level in the .git/config inside of your local repository. You can also configure Git globally or at the system level. In this article, we will focus on the global settings. It’s a file located at the root of your user directory named .gitconfig:

cat ~/.gitconfig

You might remember typing git config --global user.name "John Doe" when you first installed Git on your computer. This command creates and writes to your global git config. This file contains several sections with settings you want to set globally and apply to any Git project on your machine. Here’s an example of a gitconfig file:

[user]
  name = John Doe
  email = johndoe@email.com

[core]
  editor = nvim
  excludesfile = ~/.gitignore_global

[init]
  defaultBranch = main

[commit]
  gpgsign = true

[push]
  default = simple
  autoSetupRemote = true

All settings inside the gitconfig are grouped within sections. Here’s an overview of the sections:

The user section contains your name and email that will be used as committer fields in your commits.
The core section contains configurations such as the editor you wish to use when you amend a commit. You also add a global gitignore file in excludesfile. Git will then automatically ignore the files mentioned in this global gitignore for any local repository on your computer.
The init section contains settings that get applied when you run git init. With defaultBranch set to main, the default branch created will be named main instead of master.
The commit and push sections are to configure how Git behaves when pushing or committing. In the example, autoSetupRemote creates the remote branch automatically if it isn’t yet created in your remote repository, on Github for instance.

The first step to further customizing Git on the command line is to use another feature we haven’t looked at yet: Git aliases.

Create your own shortcuts with Git aliases

In your gitconfig, you can add a section called [alias]. An alias looks like:

[alias]
	st = status

On the left side, you add your alias name. The alias name is the shortcut you want to use. On the right is the value the alias expands to. You can use any Git command with its various flags as an alias value. In this first example, we have an alias st that expands to status. In your terminal, you can now type:

$ git st

This command will give the same output as typing git status as st expands to status.

We all have commands we end up using all the time, or useful commands we’d use more often if we could remember which flags to pass. Let’s imagine you use git log --oneline all the time.

git log --oneline

This command provides a more compact overview of the last commits on a branch. Here’s an example of a typical output:

69ca546 (HEAD -> main, origin/main) chore(bash): remove bash_completion from bash_profile
775be90 feat(bash): add wasm build to path
4f545cc feat(bash): disable go pls telemetry

With Git aliases, you can add a shortcut that will expand to that exact command:

# In your ~/.gitconfig
[alias]
  lo = "log --oneline"

Now, you can type:

git lo

And it will expand to git log --oneline, giving you the same output.

In my gitconfig, I have a series of aliases I use to add files, push, unstage commits, and many others:

[alias]
  aa = add --all
  s = status -s
  st = status
  br = branch
  c = commit --verbose
  cm = commit -m
  cp = cherry-pick
  co = checkout
  ll = log --oneline --graph
  p = push
  pf = push --force-with-lease
  unstage = restore --staged .

One of my favorites from this example is unstage. With git unstage, I unstage any file I might have added to the Git staging area. To commit with a message, I do a git cm “my commit message” and it does the same thing as typing git commit -m “my commit message”. Git aliases are quick to add and can make a difference in your everyday Git CLI experience.

When you use commands like git diff and git show, Git uses a pager to show their respective output. By default, Git uses less. As mentioned in the documentation, you can choose your own pager. delta is a great alternative to the default pager. It provides language syntax highlighting and configurable options. You can customize delta to show the Git diff in a split view. You can also make it show line numbers. There are many features worth exploring.

To use delta, first install it following their installation guide. If you’re on MacOS, you can use Homebrew (brew install git-delta). Then, in your ~/.gitconfig, add the following rule to the core settings section:

[core]
    pager = delta

To customize delta further, you can also add to your gitconfig a [delta] section:

[delta]
	navigate = true
	side-by-side = true
	line-numbers = true

navigate activates navigation keybindings. You can now use n to jump to the next Git diff or N to jump backwards.
side-by-side changes the output to show on the left the previous committed version of the committed file and on the right the current modifications.
line-numbers is to display the line numbers. You can turn it off by passing false.

If you run git diff now, you should see a much clearer Git diff. For instance, here’s the before/after of running git show in one of my repos.

Before adding delta:

After adding delta:

Build custom functions for more complex tasks with Git

You can think of Git as a powerful utility that you can combine with other utilities to make certain tasks easier. The power of Git lies in its composability.

In a former blog post “Build Git helpers from scratch with Bash and fzf”, I wrote about how to create Git helpers with fzf. fzf is a command-line fuzzy finder. In that article, we build several utilities with Git and fzf:

dfb: a helper function to delete a Git branch more easily
gri: With this function, you can choose via fzf which commit you want to rebase your branch onto. Then you get the classic Git rebase-interactive menu.

You can add shell functions directly in your ~/.bashrc, ~/.zshrc, or any file loaded by your shell config file. To test the following function, you can add it directly for now in your bashrc or zshrc, reload your config file via a source ~/.bashrc or source ~/.zshrc, and then you should be able to use it.

Another common Git task is staging a file or specific changes in a modified file. Let’s create a small helper that follows the same technique as the ones mentioned before.

In my bash config, I have a bash function called gaf:

function ensure_git_repo() {
    if ! git rev-parse --is-inside-work-tree &> /dev/null; then
        echo "Error: Not inside a Git repository"
        return 1
    fi
}

# use fzf to stage modified or untracked files.
function gaf() {
    ensure_git_repo || return 1

    git ls-files -m -o --exclude-standard | fzf -m --print0 | xargs -0 -o -t git add
}

If we dissect this function:

ensure_git_repo is a small check to make sure you use this function inside a Git repository.
git ls-files is a way to list files in your repository. The flag -m means we include in the list only modified files. -o is a way to include untracked files in the output. If you create a file that you have not committed yet, this file will be included in the list. --exclude-standard means the list won’t include excluded files. This command will take your .gitignore into account.
This command pipes the result of git ls-files to fzf. Then, fzf will show to standard output a list of the modified files you can then add. fzf -m enables multi-selection. You can then select several files at once using the Tab key.
The final part uses xargs to flatten the list of selected files and pass them to git add.

After adding the function, navigate to a local directory with some uncommitted changes, and then type:

$ gaf

You should see a list of modified files, similar to the following screenshot:

You can then select a single file in the list with the Enter key. It will select the current file highlighted. If you want to select multiple files at once, you can use the Tab key and Shift Tab to unselect a file. If you then run git status, you should see that your selected files are now in the Git staging area. In the example, I selected the README in the fzf menu:

You can use gaf -p to stage specific modifications from a file. When you select a file, you then get the Git interactive menu, where you can stage portions of that file:

$ gaf -p

In my repo, I then select my README and get the interactive menu where I can choose to stage or not a specific portion of the README:

There are many utilities you can come up with that match those micro tasks you do with Git and enable you to stay in your shell and not depend on a specific graphical interface. If you are curious, here’s a link to my dotfiles that contain Git helpers I use every day.

Conclusion

In this article, we looked at a few ways to make the Git command-line interface more user-friendly. Git aliases are a great first step toward creating your own shortcuts for Git commands, with or without flags. Delta is a small utility that improves the readability of Git diffs and works with little configuration. Finally, we explored an example of creating functions on top of Git to make common tasks easier. The possibilities are endless. I hope this article gives you a few ideas. If you have any questions or would like to chat, as always, don’t hesitate to reach out on Bluesky.

Resources

The article gave a quick overview of the gitconfig. For a more complete overview of all available settings, check out the Git documentation.
For a more comprehensive overview of delta, check out the delta documentation.
If you want a step-by-step guide on how to build Git and fzf helpers, check out my former blog post "Build Git helpers from scratch with Bash and fzf".

Olivia Coumans' Blog

Using Vim with VSCode

Installation

Remember Vim and its modes

Learning vim

Basic settings

Creating custom shortcuts

Breaking down the commands

A few favorite custom keymaps

Keymaps using extension capabilities

Explore and customize

Extending Vim power with some plugins

Some of my favorite Vim motions

Bonus: moving a code block up or down in visual mode

Conclusion and further resources

Search for a string in your git history with git log

Using git log -S

Bonus: list all the commits that modified a file

Conclusion and further resources

Exploring generics and generic constraints in TypeScript

Generics as a superpower to build reusable code

A real-life example of generics

Generic constraints or generics with limitations

Usecase #1: you want to use a specific property on a generic type

Usecase #2: Create a relationship between two generics

Conclusion

An overview of the unknown type in Typescript

Purpose of unknown

The multiple risks of using any

unknown, a type-safe alternative to any

Type narrowing to use a type unknown value

Using unknown to regain some type safety

Conclusion and further resources

Getting started with tmux

Why use tmux?

Some basic terminology

Installing tmux and running it

Configuring and using tmux

Testing your config

Choose a prefix you're comfortable with

A small note before going further

Creating windows and panes in tmux

Navigating between panes and windows in a tmux session

Creating sessions and naming sessions

Detached mode

Closing a tmux window and stopping all tmux processes

Scrolling in your tmux buffer

Searching in a tmux buffer

Help in tmux

Colors in tmux

Extending tmux with plugins

Scripting tmux with tmuxinator

Conclusion and great resources

Testing HTML in React Components with Vitest

What is HTML validation, and why does it matter?

Setting up html validation in vitest

Validate your React component HTML in your tests

The whole demo code

Conclusion

A practical introduction to code splitting in React

What is code splitting?

Setting up the demo app

App overview

Technical stack

Implementing code-splitting at the route level

Step 1: Using React.lazy for route-level code splitting

Step 2: Adding Suspense for loading states

Step 3: Testing our changes

Fixing the multiple loaders

Solution 1: use another Suspense boundary

Solution 2: leverage useSuspenseQuery from @tanstack-query

Solution 3: Combining the power of loader functions from react-router with react-query

Setting up the loader function

Moving the query client to its own file

Modifying our router

Accessing loaded data in the MovieDetails page

Benefits of all this work

Which approach to choose?

Beyond code splitting at the route level

Scenario: we have added a fancy animation that is quite heavy

Using `git log -S`

The multiple risks of using `any`

`unknown`, a type-safe alternative to `any`

Type narrowing to use a type `unknown` value

Using `unknown` to regain some type safety

Step 1: Using `React.lazy` for route-level code splitting

Accessing loaded data in the `MovieDetails` page

Using React’s `use` hook to load the animation JSON

Beyond the `<div>` element: Understanding semantic sections in HTML

Question 1: Is it valid HTML to use a `<p>` tag inside a `<button>` element?

Configuring the `pre-commit` script with lint-staged

Use lint-staged with the husky `pre-commit` hook

How to install `jq`

Processing JSON data with `jq`

Extract the length of a JSON array with `jq`

Getting an item at a given index from a JSON array with `jq`

Getting `n` elements of an array with `jq`

Filtering data using the `select` function in `jq`

Sorting an array of objects with `jq`

Extracting the `git rev-parse` check in its own function