Migration duration

This migration took me months to complete. I did not spend all my spare time on it, but it still dragged on because it was tedious and boring, and at some points even small progress required a significant investment of time.

Migrating network share configurations and putting together the foundations for the migration was probably the most painful part.

Preserving existing resources required careful manual imports and sometimes risky manual edits to the Pulumi state. It was not a clean import: LXC containers needed small tweaks and refreshes to be properly imported rather than recreated from scratch.

Once the foundations were in place, the rest moved fairly quickly, though not without its own quirks. The first 20% of the migration consumed roughly 80% of the total time. The remaining 80% took another 80%.

Missing foundations

Pulumi falls short when it comes to file and template management. There is no built-in way to create files from templates or to load templates and substitute variables the way Terraform does. I ended up writing a custom template system based on Handlebars so I could keep templates in isolated files with proper syntax highlighting and linter support.

Some Pulumi primitives also lack basic functionality. RemoteFile requires you to manually create parent directories if they are missing, and it does not support setting file permissions on the remote. Both limitations are understandable given how differently operating systems handle these things, but they are still annoying. I ended up writing custom classes that wrap RemoteFile just to automate all of this.

RemoteCommand only accepts in-memory strings, not script files. So if you want to run a longer script, you either load it into memory and pass it directly, or you copy the script to the remote host, set its permissions, execute it with RemoteCommand, and then clean up afterwards. Annoying. I wrote a custom class to handle that workflow too.

By the end I had a set of custom classes for the most common operations: creating remote files from Handlebars templates, deploying configuration files to paths that mirror the local assets folder structure, and creating executable files from either templates or static sources. Everything became much simpler, faster, and more pleasant to work with once these abstractions were in place.

But I’m overall happy

Despite all the annoyances and custom code I had to write, I still prefer this over Terraform. Being able to import shared constants or write unit tests is great.

I wrote my stack in TypeScript, which means I can also statically derive information that would simply be impossible in Terraform (like the IP addresses of each container or the domain names linked to them) even from files far from where those values are defined, just by leveraging TypeScript generics and compiler inference.

Being able to structure files in whatever folder layout I prefer is also really nice, and my service definitions became much cleaner and easier to read thanks to splitting the code in a more composable way than Terraform ever allowed.

Now that I have invested in these foundations, I will keep using Pulumi and build more things on top of it. That said, had I known the time and effort it would take to reach this point, I would have delayed the migration.

There are real benefits to Pulumi over Terraform, but at the time I simply wanted to add another LXC container to my homelab without repeating too much boilerplate and prop drilling. All this effort was not worth it just for those small improvements.

It is worth it, though, for the broader improvements to the entire homelab stack: the better development experience that comes from type-checking and inference, the powerful code reuse, the simpler modules and utilities.

I also used this migration as an excuse to fix things that had been wrong in the original server configuration: setting up SMB and CIFS properly for network shares, unifying all ZSH configuration for Debian, migrating from Oh My ZSH to Oh My Posh, and even automating the installation of services that were previously set up by hand.

So, if you are starting from scratch, absolutely give Pulumi a try. If you have an existing stack and are considering a migration, double whatever time estimate you have, and if it still makes sense after that, go for it.

Chaining apply to create resources

I discovered .apply(callback) very early and started using it everywhere, long before I really understood what it does. Most Pulumi resources expose lazy values wrapped in some sort of Input. A very common beginner mistake is to try to unwrap those values by creating other resources inside apply chains like this:

import * as pulumi from "@pulumi/pulumi";
import { RandomPassword } from "@pulumi/random";
import { remote } from "@pulumi/command";

const password = new RandomPassword('password');

const connection = {}; // Omitted for simplicity
export const changePassword = pulumi
  .output(password.result)
  .apply((password) => {
    return new remote.Command('change-password', {
      connection,
      create: `echo 'root:${password}' | chpasswd`
    });
});

Before Pulumi can apply a plan, it has to compute it. Pulumi does this by running in preview (dry-run) mode, which does not create, update, or delete any resources. Instead, it computes the resources that would exist and compares them against the current state. During preview, Pulumi will not run apply callbacks because those callbacks depend on provider side effects to resolve the lazy values.

In the example above, during preview Pulumi correctly detects that it needs to create a new RandomPassword, but it never sees the remote.Command meant to change the password because the apply callback is never executed.

This compounds quickly, especially when you use apply to manage dependencies for remote files or scripts. You might need to run mkdir -p to ensure the parent folder exists, then copy the file, then make it executable with chmod, and finally execute it. I ended up with deep chains of nested apply calls just to deploy scripts for restarting services or reloading configuration. That easily becomes four or five levels of nesting once you add container creation into the mix.

The fix is straightforward: do not create resources inside apply callbacks. Instead, declare resources at the top level and use apply only to compute the inputs that those resources need.

Here is the same example rewritten correctly:

import * as pulumi from "@pulumi/pulumi";
import { RandomPassword } from "@pulumi/random";
import { remote } from "@pulumi/command";

const password = new RandomPassword('password');

const connection = {}; // Omitted for simplicity
export const changePassword = new remote
  .Command('change-password', {
    connection,
    create: pulumi
      .output(password.result)
      .apply((password) =>
        `echo 'root:${password}' | chpasswd`
      )
  });

Now Pulumi can see both resources clearly, and it knows that remote.Command depends on the output of RandomPassword. It will create the RandomPassword first and then the remote.Command.

This pattern matters not only for performance (Pulumi can parallelize work more effectively when dependencies are explicit and granular) but also for producing accurate previews.

My recommendations

Never create resources inside apply callbacks. Use apply only to derive input values for resources that are declared at the top level.

Overusing pulumi.Input

Another rookie mistake I made was typing almost everything as a lazy value using pulumi.Input. This caused two kinds of problems:

• It prevents you from using the value in places that need eager evaluation (for instance, in resource names, which must be known at preview time to detect duplicates and changes).
• It breaks class prototype chains in a way that is only detected at runtime. This is fine if you pass around plain objects, but it can be quite tricky if you pass something more complex, like a 1Password client.

For each value, it’s worth asking whether it is truly lazy at its source. One of my early mistakes was to build helpers around remote.Command and remote.CopyToRemote that treated the remote file path as a lazy value, even though the path was completely static and known before any code ran. That prevented me from using the path in resource names, forced me into extra apply chains, and made the preview diffs less useful.

My recommendations

Use pulumi.Input only for values that genuinely depend on provider side effects or other lazy outputs. Keep static values as plain types so you can safely use them in resource names and other places that must be known during preview.

Not leaning on the parent property

Sometimes we need to create explicit dependencies between resources because Pulumi cannot reliably infer them from the resource definitions alone.

For example, when copying a file to a remote path, the copy will fail if the target directory does not already exist. Creating that directory is just a simple mkdir -p on the remote host, but Pulumi has no way to know that the directory must be created before the file is copied.

We can solve this with dependsOn, triggers, or ( usually the better option) the parent property. Each resource can have a single parent. Pulumi will then create the child after the parent, delete the child before the parent, and recreate the child when the parent is replaced. That behaviour is extremely helpful when you want to ensure, for example, that all files are recopied whenever a container is replaced.

Consider the following code:

import { remote } from "@pulumi/command";
import * as pulumi from "@pulumi/pulumi";
import { dirname } from "node:path";

const remotePath = "/tmp/my-folder/my-file";
const connection = {}; // Omitted for simplicity

const createContainerFolder = new remote.Command('create-container-folder', {
	connection,
	create: `mkdir -p ${dirname(remotePath)}`,
})

export const remoteFile = new remote.CopyToRemote(
	`my-file`,
	{
		connection,
		source: new pulumi.asset.StringAsset("Hello, world!"),
		remotePath,
	},
	{ parent: createContainerFolder },
);

This integrates nicely with Pulumi: the remote file is visible in preview mode, is copied only after the container folder is created, and is removed before the command that creates the folder is deleted. The preview also shows the remote file nested under that resource, which makes the dependency obvious when you inspect the plan.

However, this approach has some limitations. Each resource can have at most a single parent, but there are many situations where a resource depends on multiple others. There is also a subtler issue: changing a resource’s parent modifies its URN, which means Pulumi cannot update it in-place — it must destroy and recreate it instead. That is acceptable for some resources, but I ran into many situations where I did not want to risk losing important data by destroying the original.

My recommendations

Prefer parent over dependsOn or triggers when you want to express a clear, structural dependency between resources and have that relationship reflected in previews and replacements. Just be aware that changing a resource’s parent will trigger a destroy-and-recreate cycle rather than an in-place update.

Why 1Password

One of my goals for the Pulumi migration was to automate the setup of SSH connections to my containers. I use 1Password to handle all my passwords, and SSH felt like a convenient way to avoid manually copying the private SSH keys that Pulumi creates into my .ssh folder.

I also had plenty of secrets defined in a separate secrets file that I wanted to move into 1Password, so that there would be a single source of truth for all API keys, usernames, passwords, and tokens in both my homelab and my browser sessions.

However, I found the Pulumi 1Password provider quite limiting for this setup:

• It only supports reading items, and I want to create new items when I add new containers to my homelab.
• Access is rate limited by the service account restrictions. There is a limit of 1000 read operations per hour and 100 write operations per hour for 1Password and 1Password Families accounts per service account token. Those limits also apply on a daily basis to the 1Password account. My homelab vault already has around 50 secrets, which effectively limits me to about 20 executions per day. That is not enough on days when I’m actively experimenting.

So I decided to build my own 1Password client. There are some important details to take into account if you follow this approach. I ran into a number of issues and eventually managed to sort them out.

Avoiding rate limits

Service account rate limits are too restrictive for my use case, so I am effectively forced to use the desktop app authentication mechanism to avoid them.

When I started my Pulumi migration, the latest version of the 1Password JS SDK available was v0.3.1, which only supported service accounts as an authentication mechanism. I decided to wrap the 1Password CLI in a TypeScript class so I could use the desktop app as the authentication mechanism and avoid the service account rate limits.

CLI client issues

Using the CLI directly introduced a few practical issues.

First, dollar sign ($) characters were incorrectly double-escaped. This led to my client trying to overwrite, on each execution, existing passwords that contained dollar signs.

The plans still worked correctly, but this had a noticeable performance impact. I could not figure out how to properly fix this, so I decided to remove the dollar sign from the set of special characters allowed to be used by the Pulumi random.randomPassword provider.

Second, sequential access was too slow, but simply making access parallel caused 1Password to ask multiple times, concurrently, for permissions to access the vault.

To fix this, I forced the first access to a secret to be sequential, with the rest of the accesses running in parallel. This way, after I allow access once, the remaining accesses do not need to ask for permissions again.

SSH Keys

One of the things I wanted to achieve was a better integration with my SSH client, so that whenever I apply a Pulumi plan I get the SSH keys to connect to the container in 1Password, and I can SSH into it directly from my terminal without manually copying private keys all over the place.

However, there is no way to import SSH keys to 1Password with the CLI, so I had to delegate the actual SSH key generation to 1Password and then copy it over to the remote container.

Localized labels

My development machine is set up in Spanish, so when I create a login item in 1Password the username field is labeled nombre de usuario and the password field is labeled contraseña. This also affects the credential field on API key items, which is labeled credencial.

I normally don’t pay much attention to those labels, but they are important when requesting items from 1Password, because those field labels are what the CLI client will return. To support multiple languages I had to define a list of alternative labels for each kind of field I wanted to request, and then make my client return the first matching field.

Caching items

My custom 1Password wrapper was the slowest part of my Pulumi codebase, taking about 80% of the runtime (100 seconds out of 120-second executions). I managed to reduce this to a negligible duration with caching and parallelization:

• Keep a cache for all items that you read. You probably don’t need to worry about stale items because this will run in less than a minute, and if you update any item in this period you can just re-run the plan later. Don’t forget to invalidate the cache entry if you update the item as part of the plan.
• Parallelize as much work as possible. Describe a strong dependency tree for your resources so that you only try to read 1Password items that have already been created by a parent resource. That way you will be able to run most 1Password interactions in parallel.
• Minimize cold starts and permission requests by gating all concurrent requests behind a sequential gate. This way you will get asked for permission only once, and after this initial request everything will run in parallel. Otherwise, every single request will be asking for permissions and hitting cold internal caches as they all run in parallel.

My LCX containers

I run several containers in my homelab, mainly NixOS and Debian LXC containers. Each container has a small volume where the operating system, applications, and configuration are stored. Everything there is created automatically through Infrastructure as Code.

Some containers also have additional storage to persist application data. For example, I have a Debian LXC container running SigNoz, and I keep its ClickHouse database and logs on a separate volume.

Others share data across containers. To accomplish this, I run a dedicated container providing an SMB server, while the rest connect to it as regular SMB clients.

Some containers can be safely recreated from scratch, but a few of them contain data I want to keep. That made migrating existing containers an important requirement (rather than deleting and recreating them).

Importing existing containers

If a container is simple and has no complex child resources, you can import it directly:

pulumi import proxmoxve:CT/container:Container <NAME> proxmox/<PROXMOX_ID>

However, more complex containers may require additional resources like copying local files or running remote scripts. In these cases I found it easier to let Pulumi create a temporary new container (with a different IP address), and then manually update the Pulumi state to point it to the original container. Afterward, you can delete the temporary container in Proxmox to keep things clear.

Manually editing Pulumi state

Editing the Pulumi state manually is dangerous, but it can significantly simplify migrations.

Export the current stack state:

pulumi stack export > state.json

By default, secrets are encrypted. To export plaintext secrets pass the --show-secrets option:

pulumi stack export --show-secrets > state.json

You can re-import the state with (it doesn’t matter if your state has cyphered or plaintext secrets):

pulumi stack import --file state.json

Pulumi can also refresh the state from real resources (only for supported resources):

pulumi refresh

Fixing password and SSH keys differences

If you use RandomPassword to generate the root password, you must import that password before creating the new container and modifying the state. Otherwise, updating the password resource later is harder due to how Pulumi handles secrets.

You can import the RandomPassword resource like this:

pulumi import random:index/randomPassword:RandomPassword <NAME> <CLEARTEXT_PASSWORD>

An alternative is to define the password as a Pulumi secret, but I prefer not forcing imported containers to keep their Terraform-generated password forever. If I recreate the infrastructure from scratch, I want fresh passwords.

The advanced importing process

Combining all the steps, the import process for non-trivial containers looks like this:

1. Update your Pulumi code so it creates a new container without conflicts (e.g., temporarily change the container’s IP).
2. Run Pulumi and let it create the new container and all its child resources.
3. Export the state: pulumi stack export > state.json
4. Edit the state file: locate the new container resource and replace its ID with the ID of the original container.
   • The ID appears multiple times (at least three times within the container resource and possibly more if other resources reference it).
   • Update every occurrence or Pulumi may detect differences and attempt to recreate or modify the container.
5. Import the updated state: pulumi stack import --file state.json
6. Refresh the state: pulumi refresh
7. Update your Pulumi code back to the intended configuration (undoing step 1).
8. Run pulumi preview to confirm Pulumi detects no differences.

Issues I run into

Some problems are expected, especially around remote connections.

At one point I manually edited the state but didn’t update every occurrence of a value. Pulumi then tried to run a command in the container but couldn’t connect, and I received a vague unexpected EOF error. I eventually fixed it by deleting the affected remote::Command resource from the state and letting Pulumi recreate it. Since my scripts are idempotent, rerunning them wasn’t an issue.

Another major issue involved remote files. Pulumi needs to know the file contents to compute hashes and determine identifiers, even during previews. Some of my remote files are templates that depend on Pulumi outputs, including RandomPassword, which isn’t available during previews. I created a custom resource to delay asset creation until outputs resolved, but this led to errors like:

property asset value {<nil>} has a problem: either asset or archive must be set

A final thought

This migration is taking longer than I expected. I like Pulumi’s programming model overall but there are some rough edges. The migration would be significantly easier if:

• Pulumi supported creating remote files from local templates plus input variables, similar to Terraform’s templatefile.
• Proxmox allowed creating detached volumes, so containers could be recreated without touching storage.

Maybe these features exist and I just haven’t found them yet. If I discover better solutions, I’ll write another post about it.

Basic asynchronous work

We start with a simple digital clock that updates every second, a baseline to confirm the UI stays interactive as we add asynchronous work.

Next we add an artificial “heavy” async task: each has an ID and start/complete timestamps, and we delay it a few seconds to show different loading patterns. Clicking “Do heavy work!” starts a task; the result appears when it finishes.

The code is a bit long, but most of it is just scaffolding to make the demo clear and interactive.

Refactoring with Suspense and use

We can improve the UI and simplify the code with React’s newer APIs. A first step is to replace the ad-hoc promise handling in HeavyWorkSummary with the use hook and Suspense.

The use hook lets you read a promise as if it were a synchronous value. For pending promises it throws that same promise to the caller. React treats this “throwing a pending promise until the component has finished loading” as suspending.

If that thrown value isn’t caught, rendering breaks. React’s intended pattern is to wrap any component that uses use inside a Suspense boundary. Suspense renders its fallback until its children stop suspending, then it renders the children.

We wrap HeavyWorkSummary in Suspense, replace the ad-hoc promise handling with use, and move the loading UI into the boundary’s fallback.

Keeping stale data with useDeferredValue and background rendering

The UI works but is not ideal: as soon as we click the button we lose the last completed result. Often we want to keep showing that (with a hint that it is outdated) until new data is ready. Imagine a list that loads more data on demand: showing stale data while loading is usually better than showing nothing until the new data is available.

That’s what useDeferredValue is for.

On first call, useDeferredValue returns whatever you pass in. When the component re-renders because that parameter changed, useDeferredValue still returns the previous value, but it is tightly integrated with Suspense and will also trigger a background render, and this time it will return the new value.

Background rendering only makes sense with Suspense. If that background render causes a child to suspend, React does not commit the new DOM tree (which would show the fallback). Instead it keeps the previous one. So the DOM under the Suspense boundary does not change until the suspending children have finished loading. The user keeps seeing the old content until the new content is ready.

To see this in action, we add useDeferredValue to the demo and walk through the behaviour.

useDeferredValue demo

In HeavyWorkController we add deferredHeavyWorkId = useDeferredValue(heavyWorkId) and use deferredHeavyWorkId instead of heavyWorkId for the content that can suspend.

Here is the same flow as a sequence of renders and user actions:

1. First render: ID 0, deferred ID 0. No loading state for ID 0, so no Suspense rendered yet.
   • User clicks the “Do heavy work!” button
2. Second render: ID 1, deferred ID still 0. Children use deferred ID, so same result and no DOM update.
   • useDeferredValue will trigger now a background render, no user action required
3. Third render (background): deferred ID 1. React renders the Suspense boundary; HeavyWorkSummary suspends for ID 1. First time for this boundary, so no previous DOM element exists. React updates the DOM, showing the fallback (HeavyWorkLoadingIndicator). Second DOM update.
   • Let’s assume in this example the user waits until it finishes loading, we will see what happens if they click in a later example
4. Promise for ID 1 settles. HeavyWorkSummary stops suspending so Suspense shows it instead of fallback. Background render done, React updates the DOM. Fourth render, third DOM update.
   • Now imagine user clicks the “Do heavy work!” button again
5. Fifth render: ID 2, deferred ID still 1. Same UI, no DOM update.
   • useDeferredValue triggers a background Render
6. Sixth render (background): deferred ID 2. HeavyWorkSummary for ID 2 suspends (no settled promise yet). Suspense renders its fallback because HeavyWorkSummary is suspending so React does not update the DOM but keeps the previous boundary content (result for ID 1).
   • Let’s assume user waits for a bit, we will consider what happens if user clicks in this moment in a different walk through afterwards
7. Promise for ID 2 settles. HeavyWorkSummary stops suspending; React updates the DOM with the new result. Seventh render, fourth DOM update. Summary of DOM updates so far:
   • Initial render with heavy work id 0
   • Loading status for heavy work id 1
   • Resulting status for heavy work id 1
   • Resulting status for heavy work id 2

A few edge cases are worth spelling out.

User clicks again before the first load finishes

1. First render: ID 0, deferred ID 0, no Suspense rendered yet.
   • User clicks “Do heavy work!”
2. Second render: ID 1, deferred ID 0. Same result, no DOM update.
   • useDeferredValue triggers a background render.
3. Third render (background): deferred ID 1. HeavyWorkSummary suspends for ID 1; first time for this Suspense boundary, so React shows HeavyWorkLoadingIndicator. Second DOM update.
   • User clicks “Do heavy work!” again before load finishes.
4. Fourth render: ID 2, deferred ID 1. Same as second render so no DOM changes.
   • useDeferredValue triggers a background render.
5. Fifth render (background): deferred ID 2. HeavyWorkSummary for ID 2 gets a new promise and suspends; use ignores the previous promise. Boundary still shows fallback, so React does not update the DOM.
   • If the user waits for load to finish we get the new result; if they click again we repeat from step 4 until they wait for a promise to settle.
6. Promise for ID 2 settles. HeavyWorkSummary stops suspending; React updates the DOM for ID 2. Sixth render, third DOM update.

User clicks again while some work is loaded but the latest is still loading

Same idea as above. Foreground render: ID X+1, deferred ID X: same output so no DOM update. useDeferredValue then triggers a background render with deferred ID X+1. HeavyWorkSummary for X+1 gets a new promise and suspends; use drops the previous promise. The boundary keeps showing the old content until the new promise settles, so React does not update the DOM.

Loading hints

Our UI is far from ideal: users have no signal that work is in progress until it finishes. We should show a loading indicator while still keeping the stale data on screen. When the deferred ID and the current ID differ, we are in the foreground render just before the background one, so we can render HeavyWorkLoadingIndicator with the new ID and the user will see it immediately.

If the user clicks several times before load completes, the loading indicator updates to the latest requested ID. Pretty neat!

Manual background rendering with useTransition

useDeferredValue keeps stale data on screen automatically. When you need to control when a background render starts, use useTransition. It returns isPending (true while a Transition is in progress) and startTransition, which you call with a function (React calls this function Action) which may be async.

When you call startTransition, React first re-renders with isPending === true, starting the Transition, and runs the Action. It does not update the DOM again until the Action has finished and no children are suspending. Then it re-renders with isPending === false and the new state, finishing the Transition.

The example below swaps useDeferredValue for manual startTransition.

The loading indicator now shows the wrong ID, because React does not re-render until the Transition finishes. useOptimistic fixes that.

Immediate UI updates with useOptimistic

We can start transitions manually and keep the previous UI until async work finishes, and we can show a loading state when there is no prior data. But once a Transition has started, the UI does not update again until it ends so there is no progress or intermediate feedback.

useOptimistic lets you apply state updates immediately from inside an Action, so the UI can reflect in-progress work (e.g. a progress bar for a multi-step operation). The name suggests “optimistic UI“, but it is really about immediate updates from async code.

In our demo we fix the loading indicator by adding optimistic state for the pending heavy-work ID: we update it inside the Action so the user sees the right ID right away, and it is updated again when the transition completes.

Here we could have used other patterns, but in real apps useOptimistic is useful for multi-step feedback or any UI that should update immediately even when the underlying work is async and ongoing.

Comparison and recap

For a quick reference, the APIs are summarised below. The demos above show each one in context; the React docs explain each API in detail, though the big picture is easier to see when they are used together.

• use (introduced in React 19)
• useOptimistic (introduced in React 19)
• useTransition, Transition, Actions (introduced in React 18)
• useDeferredValue (introduced in React 18)
• <Suspense>

<Suspense>

Shows its fallback while any child is suspending (throwing a pending promise).

suspending

A component is suspending when it throws a pending promise instead of returning UI.

useDeferredValue

Works with <Suspense>: when the value changes it triggers a background render and only updates the DOM when children stop suspending. Use it to keep stale data on screen while new data loads.

useTransition

Lets you start a Transition manually. State updates inside the transition do not cause a DOM update until the Transition finishes, so the previous UI stays visible.

Transition

Started via the startTransition function returned by useTransition. Batches state updates: the component that started the Transition does not re-render until the transition finishes (all awaited promises and suspending children are done).

Action: the function you pass to startTransition. It may be sync or async.

Action

See Transition

use

Reads a promise or context; if the promise is pending, the component suspends. Lets you use promises directly under Suspense boundaries.

My Homelab DNS requirements

My Homelab setup uses several kinds of DNS records:

• Many CNAME records that map short, readable names to an Nginx reverse proxy. The proxy then forwards each incoming request to the correct private IP and port.
• A few A records that point directly to private IPs. These aren’t accessible outside my network, and that’s intentional as those services are meant to stay private.
• Some dynamic host records used to expose a few services publicly. These combine dynamic host login credentials (configured later in my public-facing services) and the DNS records that clients will query.

Setting this up with the Pulumi OVH provider is straightforward. I created a small wrapper class around the provider to reduce some boilerplate. The most interesting part is the helper function for creating a dynamic host record:

import * as ovh from "@ovhcloud/pulumi-ovh";
import type * as pulumi from "@pulumi/pulumi";

const rootDomainName = 'my-domain-name.ovh'

const createDynhostRecord({
    publicDomainName,
    loginSuffix,
    password,
}: {
    publicDomainName: string;
    loginSuffix: pulumi.Input<string>;
    password: pulumi.Input<string>;
}) => {
    const dynhostLogin = new ovh.domain.DynhostLogin(
        publicDomainName,
        {
            zoneName: rootDomainName,
            loginSuffix,
            password,
            subDomain: publicDomainName.slice(0, -rootDomainName.length - 1),
        },
    );

    new ovh.DomainZoneDynhostRecord(publicDomainName, {
        zoneName: dynhostLogin.zoneName,
        subDomain: dynhostLogin.subDomain,
        ip: "1.1.1.1",
    });
}

I pass the login suffix and password as inputs from the caller. Both values come from 1Password (I’ll explain how in a separate post).

This setup ensures all required DNS records exist. However, I still need to import the existing records; otherwise, Pulumi will fail during apply, since the resources already exist even though they’re not part of the Pulumi state yet.

Importing existing OVH DNS records in bulk

Importing them is a bit tricky. Pulumi allows importing resources one by one or in bulk via an import file. Instead of creating this file by hand, you can generate it automatically with:

pulumi preview --import-file ./import.json

The resulting import.json will look like this (with many more entries):

{
    "resources": [
        {
            "type": "ovh:Domain/zoneRecord:ZoneRecord",
            "name": "my-subdomain.my-domain.ovh",
            "id": "<PLACEHOLDER>",
            "version": "2.10.0",
            "pluginDownloadUrl": "github://api.github.com/ovh/pulumi-ovh"
        }
    ]
}

Notice the <PLACEHOLDER> value for id. You must replace this with the actual ID used by the OVH provider.

Each provider computes resource IDs differently. You can discover the ID format by creating a dummy resource and inspecting the Pulumi state. For OVH DNS records, you’ll see that the ID is a simple numeric value.

This matches the ID used by the Terraform OVH provider. A Terraform state with OVH DNS records looks like:

{
  // Other fields omitted for brevity
  "resources": [{
    // Other fields omitted for brevity
    "type": "ovh_domain_zone_record",
    "provider": "provider[\"registry.terraform.io/ovh/ovh\"]",
    "instances": [{
      // Other fields omitted for brevity
      "attributes": {
        // Other fields omitted for brevity
        "id": "0123456789" // NUMERIC_ID
      } 
    }]
  }]
}

However, Pulumi OVH provider uses a different format for imports. Instead of just NUMERIC_ID, the import ID must be:

<NUMERIC_ID>.<DNS_ZONE>

So in this example, the ID you should use is:

0123456789.my-domain.ovh

Once you’ve replaced all placeholders, import everything in one go:

pulumi import -f ./import.json

Importing existing OVH DNS records one by one

You can also import individual records. You’ll need three things:

1. The resource type. For OVH DNS records it is ovh:Domain/zoneRecord:ZoneRecord. (I pulled this from the generated JSON import file; I’m not sure of another direct way).
2. The resource name. The name you assigned to the Pulumi resource on creation.
3. The import ID, in the import format. Note that for OVH DNS records this is <NUMERIC_ID>.<DNS_ZONE>.

For the earlier example ( my-subdomain.my-domain.ovh, ID 0123456789), the import command is:

pulumi import ovh:Domain/zoneRecord:ZoneRecord my-subdomain.my-domain.ovh 0123456789.ulz.ovh

One of my goals was to define the entire setup as code. I wanted to avoid clicking around in the UI and waiting for pages to load every time I needed to change a setting. So I installed Proxmox (manually), set up API credentials, and jumped on the Terraform bandwagon. With it, I defined all my containers, firewall rules, and the public and private domain names needed to access my services.

The maintenance issues

This worked well for a while, but as the infrastructure grew, it became harder to maintain and several pain points appeared:

• Splitting resources across files is awkward. Everything has to live at the root module level, or you’re forced to create full modules if you want to use folders. I went with the latter, which left me with a ton of boilerplate variables.tf files and repeated providers.tf definitions.
• Sharing constants is painful. They need to be defined in the root module and manually passed down to every child module.
• There’s no easy way to share data types. I’m not a Go developer, so writing custom Terraform plugins or providers isn’t feasible. But I really wish I could enforce a consistent input structure across all my LXC container modules.

The setup itself isn’t overly complex, though. I have a cheap .ovh domain, and I use Terraform to point several DNS records to private IPs in my network. Then I use the bpg/proxmox provider to declare firewall rules and LXC containers. Most of those containers run NixOS with custom configuration.nix files generated from templates that inherit from a base template. With Sander0542/nginxproxymanager, I configure an internal proxy that forwards HTTP(S) traffic to the correct container and port.

There are a few parts I’m saving for future posts—like how everything is monitored with Open Telemetry and SigNoz, or how one of the containers runs Samba so the others can share files easily.

The migration

Eventually, I decided I needed to simplify the code behind this setup. I considered moving to CDKTF… only to learn that it had been deprecated two days before I looked into it. That’s how I discovered Pulumi.

I’m still learning it and migrating things slowly (so far, only the DNS records), but I’ve already figured out a couple of interesting things:

• Importing existing Terraform resources from a Terraform Enterprise–hosted state into Pulumi.
• Reading and writing secrets directly from 1Password (something I never automated with Terraform).

I’ll cover both topics in future posts. This one is just an introduction to the series about my Homelab and its migration to Pulumi. The full migration will take months—partly because I’m not in a hurry (everything is already running fine) and partly because I don’t want to lose anything during the transition. Importing existing resources is essential for me.

You will find all my posts about this migration in the homelab category, as well as listed below:

• Migrating OVH DNS records from Terraform to Pulumi

This year, however, I want to do things differently. Over the past few months, I’ve been working on a couple of projects that have sparked new ideas. I now have notes, discoveries, and stories worth sharing—both about the work itself and the motivation behind it. Writing this down publicly should also help keep me accountable.

I’ll begin with my Homelab and its migration from Terraform to Pulumi. I’m also planning to redesign this website and potentially move away from WordPress on the client side. Expect a few posts on each project, along with regular progress updates.

Although I’m writing mainly for myself, as a kind of learning journal, I hope some of it proves useful to you as well.

See you around!

After playing a bit with TypeScript type system I came up with these types which I think can be useful and will be using for sure in future projects. You can play with it in this playground or see the code right below:

export type KeyPath<
    T extends string,
    K extends string,
    Separator extends string = ".",
> = `${T}${"" extends T ? "" : Separator}${K}`;

export type KeyPaths<T extends object, P extends string = "", Separator extends string = "."> = {
    [K in keyof T]-?: K extends string
        ? NonNullable<T[K]> extends object
            ? KeyPath<P, K, Separator> | KeyPaths<NonNullable<T[K]>, KeyPath<P, K, Separator>, Separator>
            : KeyPath<P, K, Separator>
        : never;
}[keyof T & string];

export type GetTypeAtKeyPath<T, Path extends string, Separator extends string = "."> = Path extends keyof T
    ? T[Path]
    : Path extends `${infer K}${Separator}${infer Rest}`
      ? K extends keyof T
          ? NonNullable<T[K]> extends object
              ? GetTypeAtKeyPath<NonNullable<T[K]>, Rest, Separator>
              : never
          : never
      : never;

Let’s dig into how to use it and how KeyPath, KeyPaths and GetTypeAtKeyPath work and how to use it.

List key paths with KeyPath

First we define a type for a KeyPath, that is, sequence of paths joined with a specific separator (usually a dot, ., but we make it customizable). To build this type we use TypeScript’s template literal types.

export type KeyPath<
    T extends string,
    K extends string,
    Separator extends string = ".",
> = `${T}${"" extends T ? "" : Separator}${K}`;

We will leverage KeyPath type to extract each component of a key path.

Check key paths with KeyPaths

Next we need a type that represents all possible key paths for a given object. The simplest scenario is when the object has no nested objects, in this situation its keys are its key paths as there is no nesting. The complex scenario is when the object has nested keys: each key is a key path but we also have to extract all the key paths for the nested objects and prefix them with the key in the parent object where we found the nested object. Recursion, that is.

So we define a type KeyPaths that given an object, a “parent key path” and a separator, it represents all the key paths in the object, prefixed with the “parent key path”.

export type KeyPaths<
  // The object we will extract key paths from
  T extends object,
  // The key path to this object, empty string for object's root
  P extends string = "",
  // The separator for key paths
  // Default to dot (.) because it's a frequent notation
  Separator extends string = "."
> = {
    // Type a new object where values are the union of possible key paths with key as prefix
    // We disregard nullable values with -?
    // nullable values leak undefined into keys
    [K in keyof T]-?: K extends string
        // Remove nullable to look for nested objects
        ? NonNullable<T[K]> extends object
            // There's a nested object, so we must explore it
            ? KeyPath<P, K, Separator> | KeyPaths<NonNullable<T[K]>, KeyPath<P, K, Separator>, Separator>
            // No nested object, we only return the current key
            : KeyPath<P, K, Separator>
        // Key is not a string so we can't really build a key path with it
        : never;
}[keyof T & string]; // Extract all values in the new object

Get type for key path with GetTypeAtKeyPath

We also need some type to extract the type at a given key path, let’s call it GetTypeAtKeyPath. To do so we build on top of KeyPath foundations. We begin by extracting the first key of the key path, then extracting the type of the value at that key and finally repeating the process with the rest of the key path and the value we just extracted. What if we reach the last key in the key path? We just return the type of the value at that key.

export type GetTypeAtKeyPath<
  // The object to extract types from
  T,
  // The key path
  Path extends string,
  // Key path separator
  Separator extends string = "."
> = Path extends keyof T
    // Key path is an actual key of this object
    ? T[Path]
    // Extract first key in the key path
    : Path extends `${infer K}${Separator}${infer Rest}`
      // Check that first key in key path is an actual key of the object
      ? K extends keyof T
          // Ensure the key path is referring to a nested object
          ? NonNullable<T[K]> extends object
              // Extract type for remaining key path in nested object
              ? GetTypeAtKeyPath<NonNullable<T[K]>, Rest, Separator>
              // Value for first key is not an object so key path is invalid
              : never
          // First key in the path is not a key of the object so key path is invalid
          : never
      // Key path is wrongly formatted
      : never;

Type-safe getters/setters

Combining KeyPaths and GetTypeAtKeyPath we can define a generic type-safe getters and setters. Let’s assume we have a simple User data structure like:

interface User {
  name: {
    first: string
    last: string
  }
  birth?: {
    year: number
  }
}

const me: User = {
  name: {
    first: 'Lluís',
    last: 'Ulzurrun de Asanza Sàez',
  },
}

A type-safe key-path based setter for the User data structure would look like:

const updateUserAttribute = <
  // Hold the key path here to refer it later
  K extends KeyPaths<User>
>(
  // Given a user
  user: User,
  // Some key path
  keyPath: K,
  // And a valid value
  newValue: GetTypeAtKeyPath<User, K>
) => {
  // Implementation is not important
}

// This is valid at build time
updateUserAttribute(me, 'birth.year', 0)
updateUserAttribute(me, 'birth', undefined)

// This will fail at build time
updateUserAttribute(me, 'birth.year', '0')

Finally we can define a type-safe key-path getter for the User data structure with:

const getUserAttribute = <
  // Hold the key path here to refer it later
  K extends KeyPaths<User>
>(
  // Given a user
  user: User,
  // Some key path
  keyPath: K
): 
// Returns a valid value
GetTypeAtKeyPath<User, K> => {
  // The compiler detects this return value as wrong as expected (birth year is a number!)
  return 'some value'
}

// This type is properly inferred
const name = getUserAttribute(me, 'name.first')

Modern front-end developer experience is nicer than the one we had in 2007 when WordPress came out.

• CSS preprocessors help you reduce boilerplate and reuse mixins.
• TypeScript minimizes runtime errors with its type-checking and IDE auto-completion.
• The latest syntactic sugar from ECMAScript drafts makes your code simpler.
• Partial content refresh when files change with HMR enables a seamless experience.

Regular WordPress themes require reloading the entire page when any JavaScript or CSS changes. However, with tools like Vite we can achieve a state-of-the-art developer experience.

In this post I will guide you through all the steps required to add SASS, TypeScript, and HMR support to any WordPress theme.

Hot module replacement

HMR is based on browser-server collaboration. First, the browser loads an initial version of all the files. After that, it opens a bidirectional connection to the server (typically using a WebSocket).

The server uses the bidirectional connection to notify the browser when any file changes. Then, the browser replaces the old script/link tag in the DOM with a new tag that loads again the affected file. To force reloading the asset, the browser appends a timestamp to the URL of file.

Some assets may not be directly usable in the browser. For instance, SASS files must be compiled into CSS, TypeScript files into JavaScript, and some modern ECMAScript features might need some transformations to be compatible with the stable version of the browsers.

Vite solves these problems using a WebSocket interface for notifying file changes, a client script that handles the tag updates, and a dev server to provide the client script and the browser-ready assets.

Using Vite in WordPress

We will be working on a new file named hmr.php. The code can be added directly to your theme functions.php but keeping it in a different file will make things cleaner. To load hmr.php in your theme functions.php we can use require_once and get_theme_file_path:

require_once get_theme_file_path('/hmr.php');

Adding Vite dev server helpers

The first thing to add to hmr.php are a couple of helper functions: one to get the Vite dev server URL and the other to check whether HMR should be used or not. We can define the Vite dev server URL in our wp-config.php file, right after the <?php opening tag at beginning of the file:

define('VITE_DEV_SERVER_URL', 'http://localhost:1337');

Now we can create the two helpers in hmr.php:

• getViteDevServerAddress to return the Vite dev server URL.
• isViteHMRAvailable to check that the Vite dev server URL is defined.

function getViteDevServerAddress()
{
    return VITE_DEV_SERVER_URL;
}

function isViteHMRAvailable()
{
    return !empty(getViteDevServerAddress());
}

Loading Vite client script

Vite client script is an ECMAScript module. ECMAScript modules can be loaded in most browsers but they need an additional type="module" attribute added to the script tag, which WordPress doesn’t add. We will need a helper function to simplify adding this attribute to our scripts. Let’s open hmr.php and add a loadJSScriptAsESModule helper:

/**
 * Loads given script as a EcmaScript module.
 * 
 * @param string $script_handle Name of the script to load as
 * module.
 *
 * @return void
 */
function loadJSScriptAsESModule($script_handle)
{
    add_filter(
        'script_loader_tag',
        function ($tag, $handle, $src) use ($script_handle) {
            if ($script_handle === $handle) {
                return sprintf(
                    '<script type="module" src="%s"></script>',
                    esc_url($src)
                );
            }
            return $tag;
        }, 10, 3
    );
}

Now we can load the Vite client script from the dev server when available. We should add to hmr.php:

const VITE_HMR_CLIENT_HANDLE = 'vite-client';
if (isViteHMRAvailable()) {
    wp_enqueue_script(
        VITE_HMR_CLIENT_HANDLE,
        getViteDevServerAddress().'/@vite/client',
        array(), // This script has no dependencies
        null // WordPress appends a version queryString to the URL when this value is not null
    );
    loadJSScriptAsESModule(VITE_HMR_CLIENT_HANDLE);
}

The dev server is not available

Load your site right now and you will realize that the browser tries to load the /@vite/client file but fails. That’s because we haven’t started the Vite dev server yet, so let’s set it up and start it afterward.

Creating a package.json

In the NPM ecosystem, the recommended way to install dependencies is by defining them in a package.json file. This file can live in your theme’s folder.

Our initial package.json will look like this:

{
  "name": "wordpress-theme",
  "version": "1.0.0",
  "private": true,
  "license": "UNLICENSED",
  "scripts": {
    "start": "vite build && vite dev",
    "build": "vite build"
  },
  "devDependencies": {
    "vite": "^4.0.3"
  }
}

This file has 2 important sections:

1. scripts section allows us to group some commands into scripts that we will use later on. We define two:
   • start will build our scripts for production (you need some production assets like style.css in order to activate the new theme in WordPress, even if you want to run it in development mode) and start the Vite dev server.
   • build will build our scripts for production.
2. devDependencies section allows us to define dependencies that are required during development. We only have one dependency: vite.

Install the dependencies now by running: npm install.

Setting up Vite

Vite setup lives in a file named vite.config.ts, next to the package.json file we just created. It’s a regular TypeScript file that must have a default export with the Vite settings. We can use the defineConfig function that Vite offers to add type-checking support to our config object, spotting typos and other errors. A basic vite.config.ts file with HMR looks like this:

import { defineConfig } from 'vite';

export default defineConfig({
  server: {
    port: 1337,
    host: '0.0.0.0',
  },
});

In line 5 we define the port the Vite dev server listens to – 1337 – and in line 6 we allow connections from any host (useful if you run your WordPress site in a Docker container).

The dev server is not ready yet

If you start the Vite dev server right now it will fail because it can’t find an index.html file. Vite looks for an index.html file by default and serves any imported script. We can’t use an index.html file as the entry point because that’s not how WordPress themes work. Instead, we will provide the list of files to build and serve. The first one is our theme style.css, which we will write using SASS.

Writing style.css using SASS

Create a new folder for our SASS files, sass. Then create there a new SASS file to hold our styles, sass/style.scss. To keep things simple, style.scss will be quite short:

/*!
Theme Name: YOUR THEME
Theme URI: https://your-theme-url.com
Description: A blank WordPress Theme with SASS, TypeScript and Hot Module Replacement (HMR) support
Author: YOUR NAME
Version: 1.0
*/

$background-color: red;

body {
  background: $background-color;
}

We need an additional file, sass/style.ts , to import sass/style.scss. It only has to import sass/style.scss, so this one-liner is enough:

import './style.scss';

Vite can’t build SASS files by default so we must update our package.json to install an additional dependency to build our SASS files.

Add the following code inside the devDependencies section, right before line 11, declaring Vite as a dependency: "sass": "^1.56.1",. package.json will look like this:

{
  "name": "wordpress-theme",
  "version": "1.0.0",
  "private": true,
  "license": "UNLICENSED",
  "scripts": {
    "start": "vite build && vite dev",
    "build": "vite build"
  },
  "devDependencies": {
    "sass": "^1.56.1",
    "vite": "^4.0.3"
  }
}

Loading stylesheet from Vite dev server

Now we will update our hmr.php file so our theme loads the new SASS file instead of the original style.css, but only when the Vite dev server is available. To achieve this we will use the add_filter WordPress function to customize the stylesheet URI and directory URI.

if (isViteHMRAvailable()) {
  add_filter(
      'stylesheet_uri', function () {
          return getViteDevServerAddress().'/sass/style.scss';
      }
  );

  add_filter(
      'stylesheet_directory_uri', function () {
          return getViteDevServerAddress().'/sass';
      }
  );
}

A working SCSS stylesheet with HMR

Start the Vite dev server using npm start now and go to your site. The background color will be red. Modify the style.scss file. Notice how the site applies the latest changes without any kind of reload. Sweet.

Generating production assets

So far we got the SASS files and the HMR working but we are still missing a piece: building the final style.css file for production usage. This step requires a bit of coding, too, since by default we cannot really customize the destination path of the internal assets that Vite generates.

A Vite plugin to copy build results

Let’s open vite.config.ts and write a small CopyFile function. This function will take 2 parameters: the source file name and the destination path and it will return a new Vite plugin. The plugin will copy the source file to the destination.

import fs from 'fs';
import { resolve as resolvePath, dirname } from 'path';
import { Plugin } from 'vite';

const CopyFile = ({
  sourceFileName,
  absolutePathToDestination,
}: {
  sourceFileName: string;
  absolutePathToDestination: string;
}): Plugin => ({
  name: 'copy-file-plugin',
  writeBundle: async (options, bundle) => {
    const fileToCopy = Object.values(bundle).find(({ name }) => name === sourceFileName);

    if (!fileToCopy) {
      return;
    }

    const sourcePath = resolvePath(options.dir, fileToCopy.fileName);

    await fs.promises.mkdir(dirname(absolutePathToDestination), {
      recursive: true,
    });

    await fs.promises.copyFile(sourcePath, absolutePathToDestination);
  },
});

Next, we can use the plugin in the defineConfig call.

Copying files with our Vite plugin

Vite has a plugins option where we can provide an array of plugins that it will use. Let’s update the defineConfig call to pass a new instance of our copy-file-plugin plugin configured to copy the style.css file to the right destination:

const __dirname = new URL('.', import.meta.url).pathname;

export default defineConfig({
  plugins: [
    CopyFile({
      sourceFileName: 'style.css',
      absolutePathToDestination: resolvePath(__dirname, './style.css'),
    }),
  ],
  build: {
    target: 'modules',
    outDir: '.vite-dist',
    rollupOptions: {
      input: {
        'stylesheet': './sass/style.ts',
      },
    },
  },
  server: {
    port: 1337,
    host: '0.0.0.0',
  },
});

Note that we are also setting an explicit bundle in rollupOptions. The value of the key we use – stylesheet – is not important but the name of the entry point file will affect the source file in line 6: we use style.css as the source file name in line 6 because we are using the style.ts proxy file as the entry point for the bundle in line 15.

Building the theme with Vite

Build the theme running npm run build. If you run the theme in production mode you will see the right styles. Make any changes to style.scss. To see the result you will need to build the theme again with npm run build and reload the page. Old school development, right? Let’s enable development mode again by undoing the changes in wp-config.php and let’s add some TypeScript to our theme.

Using TypeScript in a WordPress theme

Let’s write some TypeScript for our theme. We will create an example script that will append an item to the WordPress admin bar if it’s visible or log a warning otherwise.

Writing the TypeScript file

Create a new ts folder for all our TypeScript sources and a ts/hello-world.ts file with the following content:

const appendDebugEntry = (config: {
  adminBarSelector: string;
  debugEntryContainerClasses: Array<string>;
  debugEntryContainerTagName: string;
  debugEntryTagName: string;
  debugEntryText: string;
}): void => {
  const adminBar = document.querySelector(config.adminBarSelector);

  if (!adminBar) {
    console.warn('WordPress admin bar is disabled so no debug item has been added');
    return;
  }

  const debugEntryContainer = document.createElement(config.debugEntryContainerTagName);
  debugEntryContainer.classList.add(...config.debugEntryContainerClasses);

  const debugEntry = document.createElement(config.debugEntryTagName);
  debugEntry.textContent = config.debugEntryText;
  debugEntryContainer.appendChild(debugEntry);

  adminBar.appendChild(debugEntryContainer);
};

appendDebugEntry({
  adminBarSelector: '#wpadminbar',
  debugEntryTagName: 'li',
  debugEntryContainerClasses: ['ab-top-secondary', 'ab-top-menu'],
  debugEntryContainerTagName: 'ul',
  debugEntryText: 'Written from TypeScript',
});

Next, we have to update our Vite config to build the new file.

Adding the TypeScript file to our Vite config

We must update our vite.config.ts file to:

1. Create a new bundle with ts/hello-world.ts.
2. Copy the bundle build results to js/hello-world.js so we can ship a production version when running npm run build.

Specifically, we must add the highlighted lines (7-10 and 18).

export default defineConfig({
  plugins: [
    CopyFilePlugin({
      sourceFileName: 'style.css',
      absolutePathToDestination: resolvePath(__dirname, './style.css'),
    }),
    CopyFilePlugin({
      sourceFileName: 'helloWorld',
      absolutePathToDestination: resolvePath(__dirname, './js/hello-world.js'),
    }),
  ],
  build: {
    target: 'modules',
    outDir: '.vite-dist',
    rollupOptions: {
      input: {
        stylesheet: './sass/style.ts',
        helloWorld: './ts/hello-world.ts',
      },
    },
  },
  server: {
    port: 1337,
    host: '0.0.0.0',
  },
});

After this, we must update our theme so it enqueues the new TypeScript file.

Enqueueing TypeScript in our WordPress theme

Then we can enqueue the script in our functions.php file. We have to take into account that there are 2 different scripts to be enqueued:

1. We want to load the TypeScript source we wrote during development. To do so we request the file from the Vite dev server so it gets transpiled into something our browser can run.
2. We want to load the production-ready JavaScript output when the theme is running in production. Vite generates this file when running npm run build.

We will add an action to wp_enqueue_scripts hook and use wp_enqueue_script to load our script right after we require hmr.php in our functions.php. It’s important to require hmr.php before because it defines isViteHMRAvailable and getViteDevServerAddress that we need to decide which file to load.

add_action(
    'wp_enqueue_scripts', function () {
        $handle = 'hello-world';
        $dependencies = array();
        $version = null;

        if (isViteHMRAvailable()) {
            loadJSScriptAsESModule($handle);
            wp_enqueue_script(
                $handle,
                getViteDevServerAddress() . '/ts/hello-world.ts',
                $dependencies,
                $version
            );
        } else {
            wp_enqueue_script(
                $handle,
                get_stylesheet_directory_uri() . '/js/hello-world.js',
                $dependencies,
                $version
            );
        }
    }
);

A working TypeScript file with HMR

You can load your site now. If the WordPress admin bar is enabled you will notice a new entry on the trailing side that says «Written from TypeScript». You will see a warning logged in the console otherwise. Make changes to hello-world.ts and you will notice the page reloads automatically to apply the changes.

Summary and downloads

You can add SASS, TypeScript, and HMR to any WordPress theme, no matter how old it is. You must do some changes to support modern frontend tooling:

1. Load Vite client script.
2. Add a package.json and dependencies (more details).
3. (Optional) Writing your stylesheet using SASS.
4. (Optional) Using TypeScript code in your theme.

Enjoy a better developer experience with your next WordPress theme and let me know what you think in the comments!