DEV Community: Matti Bar-Zeev

Bazel For a Frontend Monorepo

Matti Bar-Zeev — Sun, 05 Apr 2026 19:11:31 +0000

Disclaimer: This was done primarily as a study exercise. The goal was to learn Bazel hands-on and explore whether it could be a good fit for optimizing the build pipeline of this monorepo in the future. The hooks package Bazelification covered here has landed in production by the time you’re reading this, but the full monorepo migration is still a future ambition, not a done deal.

I have a JavaScript monorepo called Pedalboard. It holds a few React component libraries, hooks, linting plugins, and dev tooling. Nothing crazy, but it has been a good playground for experimenting with different build tools over the years.

Right now, whenever a change lands in the repo, a GitHub Actions workflow kicks off and does roughly this:

pnpm install
pnpm run build
pnpm run test:since
pnpm run lint:since

And then it publishes any packages that need a new version.

The test:since and lint:since scripts are smart enough to only run on packages that changed. But pnpm install and pnpm run build run unconditionally every time, on everything. That’s wasteful, and it was bugging me.

I had been hearing about Bazel for a while. It promises smart caching, reproducible builds, and the ability to only rebuild what actually changed. So I figured: why not give it a shot on this monorepo? Worst case I learn something. Best case I have a clear path to a much faster CI pipeline.

To be clear about scope, this post covers Bazelifying one package from the monorepo (the hooks package) end to end: install, build, test, and lint. The goal was not to migrate the whole repo overnight, but to understand the full workflow for one package and figure out whether Bazel is worth the investment.

What I was NOT trying to do here is model the internal dependency graph between packages in the monorepo (for example components depending on hooks). That is a next step and a separate story.

Let’s get into it.

Caching

Caching is a big part of what makes Bazel attractive. It can cache build artifacts locally or remotely, and in a CI context like GitHub Actions that remote cache is where the real speed gains come from. But setting that up properly is its own topic, and we’re not going to deal with it here. This post is about getting the fundamentals right first. That said, we will still benefit from local caching out of the box, which already means that re-running a build or test without any changes will be near-instant.

Preparing a project for Bazel

Rather than installing Bazel directly, I’m going with Bazelisk. Think of it as the .nvmrc equivalent for Bazel: it reads a .bazelversion file and downloads the right binary for you. It also means your team won’t end up on different Bazel versions by accident.

I install it at the root of the monorepo:

pnpm add -D @bazel/bazelisk -w

To be able to invoke it via pnpm, I add a script to the root package.json:

“bazel”: “bazel”

And the .bazelversion file at the project root pins the version:

9.0.1

The MODULE.bazel at the project’s root

The project needs a root build file, for this we create the MODULE.bazel with this content for now:

module(  
   name = "pedalboard",  
   version = "1.0.0"  
)

Install NPM packages with Bazel

Here is where Bazel throws its first curveball. When Bazel fetches npm packages, it does not put them in node_modules. It downloads them into its own internal cache. My first reaction was “ok but every other tool in this repo expects node_modules to exist, I’m not running two install systems side by side”. Turns out that concern is valid, and the solution is a rule that symlinks Bazel’s downloaded packages back into node_modules. Fair enough.

The ruleset for this is rules_js from aspect-build. I went through the docs to get this right — AI was not helpful here at all, it kept giving me examples with mixed-up APIs from different versions.

Here is the updated MODULE.bazel:

module(
   name = “pedalboard”,
   version = “1.0.0”
)

bazel_dep(name = “rules_nodejs”, version = “6.7.3”)
bazel_dep(name = “aspect_rules_js”, version = “3.0.3”)

node = use_extension(“@rules_nodejs//nodejs:extensions.bzl”, “node”)
node.toolchain(node_version_from_nvmrc = “//:.nvmrc”)
use_repo(node, “nodejs_toolchains”)

pnpm = use_extension(“@aspect_rules_js//npm:extensions.bzl”, “pnpm”)
use_repo(pnpm, “pnpm”)
pnpm.pnpm(pnpm_version_from = “//:package.json”)

npm = use_extension(“@aspect_rules_js//npm:extensions.bzl”, “npm”)
npm.npm_translate_lock(
   name = “npm”,
   pnpm_lock = “//:pnpm-lock.yaml”,
)
use_repo(npm, “npm”)

We pull in rules_nodejs and aspect_rules_js as dependencies, then use their extensions to pin the Node and pnpm versions. The npm_translate_lock call reads pnpm-lock.yaml and makes all packages available as Bazel targets. This is, by the way, one of the reasons I migrated from Yarn to pnpm — Bazel’s npm support is built around pnpm lockfiles. ;)

We also need a REPO.bazel file at the project root to tell Bazel to ignore node_modules when scanning for source files (related to this open issue):

“””Repository configuration for the Pedalboard monorepo.”””

ignore_directories([“**/node_modules”])

Bazelifying the hooks package

The hooks package is the one I’m starting with. It’s a straightforward TypeScript package — no SCSS, no complex bundling, just source files compiled to ESM and CJS, plus type declarations. A good first target.

Since it’s TypeScript, I need a transpiler Bazel can work with. The recommended option is aspect_rules_swc (GitHub), which wraps the SWC compiler. I add it to MODULE.bazel:

bazel_dep(name = “aspect_rules_swc”, version = “2.7.0”)

Build

Compiling TypeScript

The package currently builds two output formats: ESM and CJS. Each has its own SWC config. Here is .swcrc.esm.json:

{
   “jsc”: {
       “parser”: {
           “syntax”: “typescript”,
           “tsx”: false
       },
       “target”: “es2020”
   },
   “module”: {
       “type”: “es6”
   },
   “sourceMaps”: true
}

And .swcrc.cjs.json is the same but with ”type”: “commonjs” in the module section.

Now for the BUILD.bazel file in the hooks package. The idea is to declare the source files as a js_library, then pass them to two swc rules — one for each output format:

load(“@aspect_rules_swc//swc:defs.bzl”, “swc”)

filegroup(
   name = “build”,
   srcs = [
       “:compile_esm”,
       “:compile_cjs”,
   ],
)

js_library(
   name = “sources”,
   srcs = [“index.ts”] + glob([“src/**/*.ts”], exclude = [“**/*.test.ts”]),
)

swc(
   name = “compile_esm”,
   srcs = [“:sources”],
   swcrc = “.swcrc.esm.json”,
   source_maps = “true”,
   out_dir = “dist/esm”,
)

swc(
   name = “compile_cjs”,
   srcs = [“:sources”],
   swcrc = “.swcrc.cjs.json”,
   source_maps = “true”,
   out_dir = “dist/cjs”,
)

Running pnpm bazel build :build from inside the package — Bazel compiles and drops the ESM and CJS artifacts into bazel-bin.

Not bad.

Type declarations

SWC compiles TypeScript but does not emit .d.ts files. For that I need aspect_rules_ts, which wraps tsc in declaration-only mode:

bazel_dep(name = “aspect_rules_ts”, version = “3.0.0”)

I also add a flag to .bazelrc so the rule respects skipLibCheck from the tsconfig rather than overriding it:

common --@aspect_rules_ts//ts:skipLibCheck=honor_tsconfig

Before wiring this into the hooks package, I need a root BUILD.bazel file. Two things require it:

aspect_rules_js needs the root to be a valid Bazel package so that npm_translate_lock can resolve the //:all target during module extension evaluation.
npm_link_all_packages at the root is what child packages reference when they pull in node_modules. Without a root BUILD.bazel, those targets simply don’t exist.

Here is the root BUILD.bazel:

# Root BUILD file required by aspect_rules_js

load(“@npm//:defs.bzl”, “npm_link_all_packages”)
load(“@aspect_rules_ts//ts:defs.bzl”, “ts_config”)

npm_link_all_packages(name = “node_modules”)

ts_config(
   name = “tsconfig_base”,
   src = “tsconfig.base.json”,
   visibility = [“//packages:__subpackages__”],
)

I expose tsconfig_base here because sub-packages extend it and need access to it from within Bazel’s sandbox.

Back in the hooks BUILD.bazel, I add the type compilation target:

load(“@npm//:defs.bzl”, “npm_link_all_packages”)
...
load(“@aspect_rules_ts//ts:defs.bzl”, “ts_config”, “ts_project”)

npm_link_all_packages(name = “node_modules”)

filegroup(
   name = “build”,
   srcs = [
       “:compile_esm”,
       “:compile_cjs”,
       “:compile_types”, # Adding the step to compile types
   ],
)

# Defining the ts config for types, using the base config we defined earlier
ts_config(
   name = “tsconfig”,
   src = “tsconfig.esm.json”,
   deps = [“//:tsconfig_base”],
)

# Building it...
ts_project(
   name = “compile_types”,
   srcs = [“:sources”],
   tsconfig = “:tsconfig”,
   deps = [“:node_modules/@types/react”],
   declaration = True,
   declaration_dir = “dist/types”,
   emit_declaration_only = True,
   validate = False,
)

One of the deps is @types/react, which we get through npm_link_all_packages. Here is where we’re at now:

One gotcha I hit: Bazel does not like the v prefix in .nvmrc (as in v20.0.0). It needs the bare version number. Not the most helpful error message, but ok.

Copying the files to the package’s dist dir

Bazel writes all build outputs to bazel-bin, not back to the source tree. That’s by design. But our publishing tool (Changesets) expects the dist directory to sit inside the package itself. So I need to copy the artifacts back.

For that I add aspect_bazel_lib to MODULE.bazel:

bazel_dep(name = “aspect_bazel_lib”, version = “2.9.4”)

And in the hooks BUILD.bazel, two new targets handle the copy:

copy_to_directory(
   name = “dist_dir”,
   srcs = [
       “:compile_esm”,
       “:compile_cjs”,
       “:compile_types”,
   ],
   replace_prefixes = {“dist/”: “”},
)

write_source_files(
   name = “build_and_copy”,
   files = {
       “dist”: “:dist_dir”,
   },
)

copy_to_directory collects the outputs and strips the dist/ prefix so we end up with esm/, cjs/, and types/ at the top level. write_source_files then copies that directory back into the source tree.

Running the build_and_copy target triggers the full build and writes the results to dist/. The last piece is updating the build npm script in package.json:

“build”: “bazel run //packages/hooks:build_and_copy”

Build done. On to testing.

Testing

Running Jest

Our test runner is Jest, so for that we need to install the aspect_rules_jest for Bazel. In the MODULE.bazel we add:

bazel_dep(name = "aspect_rules_jest", version = "0.25.2")

In the hookd BUILD.bazel file we load the rule

load("@aspect_rules_jest//jest:defs.bzl", "jest_test")

The Rule requires the project to have “jest-cli” as a dependency. So we need to add it to the package.json of the project’s root.

The jest configuration we’re using also inherits from a root jest config, and we need to expose it to nested packages. Since the tests in Bazel run its sandbox (bazel-bin) we need to expose this root configuration so it will be available there. This is why we’re using js_libray for it. In the root’s BUILD.bazel we add:

...  
load("@aspect_rules_js//js:defs.bzl", "js_library")

...

js_library(  
   name = "jest_config_base",  
   srcs = ["jest.config.base.js"],  
   visibility = ["//packages:__subpackages__"],  
)

Last we set the target in the hooks package BUILD.bazel file:

...  
load("@aspect_rules_jest//jest:defs.bzl", "jest_test")

...

js_library(  
   name = "test_sources",  
   srcs = glob(["src/**/*.test.ts"]),  
)

...

jest_test(  
   name = "jest",  
   config = "jest.config.js",  
   auto_configure_reporters = False,  
   args = ["--reporters=default"],  
   data = [  
       ":sources",  
       ":test_sources",  
       "jest.config.js",  
       "//:jest_config_base",  
       "//:node_modules/@swc/core",  
       "//:node_modules/@swc/jest",  
       ":node_modules/@testing-library/react-hooks",  
       ":node_modules/react",  
   ],  
   node_modules = ":node_modules",  
)

And in order to get a logs which are not riddled with a lot of unescaped color chars, you can add this to your .bazelrc

test --test_env=FORCE_COLOR=0

Last thing remaining to do is replace the package.json test npm script to call bazel, like so:

"test": "bazel run //packages/hooks:jest",

Coverage report

It’s possible to pass parameters to Bazel, meaning that you run a npm script, and it passes the params to Bazel target. For that you need to add an “extra” 2 “--”, one to pass the Bazel and the other to pass to Jest. For example:

pnpm test -- -- --coverage

We can make it a bit easier if we set the npm script to include the first “--”:

"test": "bazel run //packages/hooks:jest --",

And now we can call it like this

pnpm test -- --coverage

This also helps when we call it from the root of the project when we collect the coverage for all. In that case pnpm knows to pass the param without needing the extra “--”, so nothing has to be changed on the root’s package.json

What we have will trigger the coverage report, but you won’t see the coverage directory in the package, since Bazel writes it into the sandbox. This is not what we want.

So you can tell Bazel test target where you want the coverage dir to be written in, using the coverageDirectory param. Sadly, it does not respect the Jest config for this, and you need to put it in the actual call. So we end up with this:

"test": "bazel run //packages/hooks:jest -- --coverageDirectory=$(pwd)/coverage",

Coverage paths and the NYC reporter

There is one more wrinkle with coverage. The root's coverage:combined script collects each package's coverage-final.json into .nyc_output/ using the collectFiles script from @pedalboard/scripts, then runs nyc report to produce the final lcov output.

The problem: when Jest runs inside Bazel's sandbox, the file paths it embeds in coverage-final.json point deep into the Bazel cache. NYC tries to open each file at that exact path to annotate the source, but those sandbox paths are gone by the time the report runs. The coverage data is all there — statements, branches, functions — but the reporter can't find the source files and falls over.

The fix is to remap the paths at collection time. Instead of copying each coverage-final.json straight into .nyc_output/, the collectFiles script now normalizes every path in the JSON back to its real relative path from the repo root before writing the file. NYC can then resolve the sources without any extra configuration, regardless of whether the coverage was produced by Bazel or plain Jest.

Watch mode

At the current state the aspect_rules_jest does not support the watch mode for Jest and to make it work in Bazel requires additional configuration, which I think is not necessary. Watch mode is for dev time, and I think it is perfectly fine to use the plain old npm Jest to do that.

For that I create another npm script:

"test:watch": "jest --watch"

And there we have it.

Cool ! we’re ready to jump to the linting process

Linting

We’re going to go to the Bazel center registry again to look for a rule that can help us. This is the rule we need to add to the MODULE.bazel file:

bazel_dep(name = "aspect_rules_lint", version = "2.3.0")

There is a version conflict with the rules_go dependency, and to solve that we override its version, like this in the MODULE.bazel file:

single_version_override(  
   module_name = "rules_go",  
   version = "0.60.0",  
)

Exposing the ESlint config for all sub packages

In the root’s BUILD.bazel file we will make the eslint configuration available for all sub packages. We are using the js_library for that, and notice that we add all the dependencies that this configuration requires:

js_library(  
   name = "eslintrc",  
   srcs = ["eslint.config.mjs"],  
   deps = [  
       ":node_modules/globals",  
       ":node_modules/eslint",  
       ":node_modules/@eslint/js",  
       ":node_modules/eslint-plugin-react",  
       ":node_modules/typescript-eslint",  
       ":node_modules/@typescript-eslint/parser",  
       ":node_modules/@typescript-eslint/eslint-plugin",  
       ":node_modules/@pedalboard/eslint-plugin-craftsmanlint",  
   ],  
   visibility = ["//packages:__subpackages__"],  
)

Making ESlint available for all sub packages

The recommended way to go about linting in Bazel is to create a dedicated tools/lint “package” which makes the ESlint tool available to all packages. For that we create a tools/lint directory and put 2 files in it:

tools/lint/BUILD.bazel

load("@npm//:eslint/package_json.bzl", eslint_bin = "bin")

eslint_bin.eslint_binary(  
   name = "eslint",  
   data = [  
       "//:node_modules/chalk",  
   ],  
)

This declares the eslint_binary target (//tools/lint:eslint) that the aspect uses to actually run ESLint

tools/lint/linterz.bzl

load("@aspect_rules_lint//lint:eslint.bzl", "lint_eslint_aspect")  
load("@aspect_rules_lint//lint:lint_test.bzl", "lint_test")

eslint = lint_eslint_aspect(  
   binary = Label("//tools/lint:eslint"),  
   configs = [  
       Label("//:eslintrc"),  
   ],  
)

eslint_test = lint_test(aspect = eslint)

This is a Starlark library that defines and exports the eslint aspect and eslint_test factory for sub packages to load()

Here we use the lint_eslint_aspect rule and notice that we give it the configuration we declared recently in the root’s BUILD.bazel file.

Using the eslint_test target

Now that we have all this set we can use the eslint_test target. We do that in the package’s BUILD.bazel file:

...

load("@aspect_rules_js//js:defs.bzl", "js_library")  
load("//tools/lint:linters.bzl", "eslint_test")

...

eslint_test(  
   name = "lint",  
   timeout = "short",  
   srcs = [  
       ":compile_types",  # ts_project — all non-test TS sources  
       ":test_sources",   # js_library — test files  
   ],  
)

Last thing remaining to do is replace the package.json test npm script to call bazel, like so:

"lint": "bazel run //packages/hooks:lint",

Wrapping up

So what did we actually accomplish here?

We took one package from a JavaScript monorepo and plugged it into Bazel end to end: dependency installation via the pnpm lockfile, TypeScript compilation to ESM and CJS, type declaration generation, copying build artifacts back to dist/, running Jest tests with coverage support, and ESLint linting. All through Bazel targets wired up to the existing npm scripts, so nothing in the repo's external interface changed.

Was it worth it? That depends on what you're optimizing for. The setup cost is real — Bazel is not exactly beginner-friendly, and I spent more time than I'd like to admit figuring out why things were failing. The error messages are unhelpful and the documentation has gaps that AI tools made worse, not better.

But the fundamentals are solid. The local caching already pays off during development, and the path to remote caching in CI is clear. Once the dependency graph between packages is modeled in Bazel (still to come), the build system will know exactly what to rebuild and what to skip. That's the goal.

For now, one package is Bazelified and in production. The rest of the monorepo will follow — eventually. No promises on timeline. 😄

You can find the full code in the Pedalboard repo on GitHub.

From Lerna to Changesets

Matti Bar-Zeev — Sun, 15 Mar 2026 14:13:26 +0000

If you've been following the saga of my Pedalboard monorepo, you'll know that Lerna and I have a... complicated relationship. I originally reached for it in my No BS monorepo series to handle the two things monorepos constantly need: versioning and publishing. It worked, then it stopped being maintained, then it rose from the ashes as a phoenix, and here we are - still using it. But lately I've been looking at Changesets and wondering if it's time to finally make the switch.

What Lerna Actually Does in Pedalboard (at This Point)

This is worth being honest about, because Lerna's scope in this project has been narrowing for a while.
What's left for Lerna is captured in two blocks of lerna.json:

{
    "npmClient": "pnpm",
    "useNx": false,
    "command": {
        "publish": {
            "ignoreChanges": ["ignored-file", "*.md"],
            "message": "chore(release): publish %s"
        },
        "version": {
            "message": "chore(release): version",
            "allowBranch": "master",
            "conventionalCommits": true
        }
    },
    "packages": ["packages/*"],
    "version": "independent"
}

That's it. Lerna's entire job, at this point:

Detect which packages changed since the last release
Bump their versions based on conventional commit messages (patch/minor/major)
Tag the release in git
Publish to npm via lerna publish --yes --no-verify-access

The root package.json confirms this - the only mention of lerna is a single script:

"publish:lerna": "lerna publish --yes --no-verify-access"

A fully-grown monorepo tool, reduced to a very specific, yet very important, job: release management.

I wrote about this philosophical evolution in Rethinking the "One Ring To Rule Them all" Monorepo manager, the idea that one tool shouldn't do everything - each tool should own its lane. Lerna owns the release lane. But is it the best tool for that lane?

Enter Changesets

Changesets (technically @changesets/cli) takes a different approach to the same problem. Instead of reading conventional commit messages and auto-detecting what changed, it asks developers to be intentional: when you make a change, you run changeset and write a brief description of what changed and what kind of semver bump it warrants (patch, minor, major). That creates a small markdown file in a .changeset/ directory.

When it's time to release, you run changeset version to consume those files and bump the appropriate package versions, then changeset publish to push to npm.

The appeal, for me, is the explicitness. With Lerna's conventional commits approach, version bumps are inferred from commit messages - which means they're only as reliable as your commit discipline. If someone sneaks a breaking change in with a fix: prefix (we've all been there, don't lie), Lerna will happily publish a patch. Changesets sidesteps this by making the bump intent part of the PR itself.

Initializing Changesets

Enough theory. The initialization is one command:

pnpm dlx @changesets/cli init

This creates a .changeset/ directory with a README.md and, more importantly, a config.json:

{
  "$schema": "https://unpkg.com/@changesets/config@3.1.3/schema.json",
  "changelog": "@changesets/cli/changelog",
  "commit": false,
  "fixed": [],
  "linked": [],
  "access": "restricted",
  "baseBranch": "main",
  "updateInternalDependencies": "patch",
  "ignore": []
}

Not bad for a starting point, but two things need fixing immediately.

Two config issues, right off the bat

baseBranch: "main" - Pedalboard's branch is master, not main. Changesets uses this to determine what's changed since the last release. Wrong base means changeset status compares against the wrong thing:

"baseBranch": "master"

access: "restricted" - This controls the npm access level. "restricted" means private packages, which is a sensible safe default, but all of Pedalboard's packages are public on npm:

"access": "public"

Two lines. Two things I'm glad I noticed before pushing a release and wondering why nothing published.

The other defaults are fine: "commit": false means Changesets won't auto-commit the version bumps (CI handles that), and "updateInternalDependencies": "patch" means when a package is bumped, any internal packages that depend on it get a patch bump too.

A Good Time to Clean Up Dead Scripts

While looking at what Lerna does, I also noticed a publish:lerna:skip-git script sitting in package.json:

"publish:lerna:skip-git": "lerna publish --yes --no-verify-access --no-git-tag-version --no-push --loglevel=silly"

The flags tell the story - --no-git-tag-version --no-push were there to let you test publishing locally without polluting git history. A debug escape hatch.

A quick search across the repo and all the blog posts confirmed it: nobody ever called it. Not the GitHub Actions workflow, not any other script, not a single post. It was just sitting there.

I considered whether to create a Changesets equivalent, but Changesets already separates versioning and publishing into two distinct commands, and with "commit": false in the config, changeset version doesn't touch git at all. If I ever need a no-tags publish, changeset publish --no-git-tag is one command away. No need to enshrine it as a named script until it earns its place.

Deleted. One less thing to explain.

Pulling Out Lerna Completely

With the scripts gone, time to finish the job.

Remove the lerna devDependency:

pnpm remove lerna -w

That uninstalls it from the workspace root and cleans up pnpm-lock.yaml. Satisfying.

Delete lerna.json:

The config file that's been in this repo since the very beginning - independent versioning, conventional commits, allowBranch: master - none of it is relevant anymore. Deleted.

At this point, Lerna is fully gone from the project. No dependency, no config, no scripts. The repo doesn't know it ever existed. Changesets now owns the release lane.

Installing Changesets Properly

Using pnpm dlx to run Changesets is fine for a quick init, but not something you want in CI or for contributors who clone the repo. Time to make it a first-class devDependency:

pnpm add @changesets/cli -D -w

The -w flag installs it at the workspace root, making it available across all packages. With it installed, the changeset binary lands in node_modules/.bin, so pnpm changeset just works.

For the versioning step, I added a named script - something that reads clearly in CI and in conversation. I considered just version, but that's a reserved npm lifecycle hook that runs before pnpm version. version:changeset is explicit and unambiguous:

"version:changeset": "changeset version"

Running pnpm run version:changeset consumes all pending changeset files, bumps the affected package versions, and updates the CHANGELOGs. And I mean consume - the changeset files are deleted as part of the process. They're a one-time intent, not a log. Once applied, they're gone. If the changeset files aren't committed to git before you run this, there's no way to get them back. Lesson learned the slightly painful way.

A Mindset Shift: Intent Over Detection

This is where Changesets genuinely thinks differently from Lerna, and it took me a moment to internalize.

With Lerna's conventional commits approach, version bumps were detected - Lerna would look at what changed in git and infer a bump from the commit message. Automatic. You made commits, Lerna figured out the rest.

Changesets doesn't detect anything. It only knows what you tell it. When you run pnpm changeset, it asks you to explicitly select which packages are affected and what kind of bump they warrant. No git inspection, no inference. Pure intent.

The practical consequence: infra-only changes don't need a changeset at all. This whole migration, removing Lerna, adding Changesets, updating scripts, touched the root package.json and the CI config. None of the published packages changed. No new features, no bug fixes, nothing that affects consumers. So no changeset is needed, and no packages will be bumped. That's correct behaviour.

This is very different from Lerna, where a commit like chore: migrate from Lerna to Changesets touching the root would still be scanned and might trigger bumps depending on how it interpreted the scope.

The flip side is the cascade effect. When you do create a changeset for a package that others depend on, Changesets will automatically bump those dependents too - controlled by "updateInternalDependencies": "patch" in the config. So if @pedalboard/hooks gets a minor bump, @pedalboard/components (which depends on it) gets a patch bump to update its dependency range. It cascades through the graph.

Explicit intent in, correct cascade out. Once you accept that the changeset file is the release decision - not a side effect of a commit - the whole model clicks.

The Publish Script

With versioning covered, publishing needs its own script:

"publish:changeset": "changeset publish"

changeset publish does three things in sequence: checks which packages have a version that hasn't been published to npm yet, publishes those, and creates and pushes a git tag for each one (e.g. @pedalboard/hooks@1.2.3).

That last part, the git tag push, means the CI runner needs a git identity configured before this script runs. The existing workflow already has this from the Lerna days:

- run: |
    git config --local user.name 'github-actions[bot]'
    git config --local user.email 'github-actions[bot]@users.noreply.github.com'

That step stays. Changesets needs it for the same reason Lerna did.

Enforcing the Changeset Discipline in CI

One thing Lerna's conventional commits approach gave for free: it simply wouldn't bump a package if no relevant commit touched it. With Changesets, the responsibility is on the developer. Which raises a fair question: what stops someone from opening a PR that modifies a package and forgetting to create a changeset?

Changesets has an answer: changeset status --since=origin/master exits non-zero if any packages have changed without a covering changeset file. You can wire it into CI as a gate that fails early, before lint and tests even run. For now I'm leaving it out - I will take care of it in the future.

Updating the GitHub Actions Workflow

With all the pieces in place, the final step is the workflow itself. The complete updated npm-publish.yml:

name: Build and publish

on:
    push:
        branches:
            - master
    workflow_dispatch:
    release:
        types: [created]

jobs:
    build:
        runs-on: ubuntu-latest
        steps:
            - uses: actions/checkout@v4
              with:
                  fetch-depth: 0
            - uses: pnpm/action-setup@v4
            - uses: actions/setup-node@v4
              with:
                  node-version: 20
            - run: pnpm install
            - run: pnpm run lint:since
            - run: pnpm run test:since
            - run: pnpm run build

            # Publish to NPM
            - uses: actions/setup-node@v4
              with:
                  node-version: 20
                  registry-url: https://registry.npmjs.org/
            - run: |
                  git config --local user.name 'github-actions[bot]'
                  git config --local user.email 'github-actions[bot]@users.noreply.github.com'
            # Don't run custom Git hooks
            - run: git config --local core.hooksPath .git/hooks
            - run: pnpm run version:changeset
            - run: git add -A
            # Skip commit and push if version:changeset produced no changes (e.g. no pending changesets)
            - run: |
                  git diff --staged --quiet || (git commit -m "chore(release): version" && git push)
            - run: pnpm run publish:changeset
              env:
                  NODE_AUTH_TOKEN: ${{ secrets.npm_token }}

A few things worth noting in the publish sequence. version:changeset must run before publish:changeset - it's what consumes the changeset files, bumps package.json versions, and updates the CHANGELOGs. Without it, changeset publish has nothing new to publish (it only publishes versions not yet on npm).

Because version:changeset modifies files, those changes need to be committed and pushed back to the repo before publishing. The single run step handles both: git diff --staged --quiet exits zero if nothing changed, short-circuiting the rest - so commit and push are skipped entirely if there were no pending changesets. If there were changes, it commits and pushes in one go. The | block scalar is needed because YAML would misinterpret the || shell operator as a nested mapping otherwise.

Everything else - the git identity config, the hook bypass, the fetch-depth: 0 for full git history, the master-only trigger - carries over unchanged. Lerna is gone, Changesets is in.

Wrapping Up

This migration started as a question - "is Lerna still the right tool for this one job?" - and ended with a cleaner, more intentional release flow.

Here's what changed:

lerna and lerna.json are gone
@changesets/cli is a proper devDependency
Two new scripts in package.json: version:changeset, publish:changeset
One line changed in the GitHub Actions workflow

But the bigger takeaway is the mental model shift. Lerna inferred release intent from git history. Changesets makes you declare it explicitly. That sounds like more work, and honestly - it is, slightly. But it's the right work. The changeset file becomes part of your PR, reviewed alongside the code, describing the user-facing impact. The version bump is a deliberate decision, not an inference.

Would I recommend this migration for every monorepo? If your release discipline is solid and conventional commits work for you, Lerna (or its successors) might be fine. But if you want version bumps to be explicit, reviewable, and decoupled from commit message conventions - Changesets is worth the switch.

As always, the full code is in the Pedalboard repository on GitHub. Have you made this migration yourself, or are you sticking with Lerna? I'd love to hear how others are handling it.

Related posts:

No BS monorepo - Part 1 - where Lerna first entered Pedalboard
No BS monorepo - Part 2 - auto-publishing with Lerna and GitHub Actions
Lerna is no longer maintained. Now what? - Part 1 - the NX detour
This is no Lerna, it's a freaking Phoenix! - the rant that aged well
Rethinking the "One Ring To Rule Them all" Monorepo manager - why each tool should own its lane
Migrating a monorepo from Yarn to PNPM - the previous leg of this journey

Migrating a monorepo from Yarn to PNPM

Matti Bar-Zeev — Sat, 07 Mar 2026 14:05:04 +0000

My Pedalboard monorepo has been running on Yarn 3 workspaces for quite a while now. I've written about it many times, setting it up, refactoring workspace scripts, making it build just what's needed, and even going through a whole Lerna drama. It's been a journey, and Yarn has served me well.

Author's note (March 2026): Since this post was written, this monorepo has migrated from Lerna to Changesets. Some of the workflows, scripts, and tooling described here have changed. See From Lerna to Changesets for what's different

But here's the thing, the JavaScript ecosystem moves fast, and pnpm has been gaining serious traction. Its strict dependency handling, blazing speed, and disk-space efficiency are hard to ignore. So I figured it's time to rip off the band-aid and migrate my workspaces from Yarn to pnpm.

In this post, I'll walk you through the actual migration process, the gotchas I ran into, and whether pnpm lives up to the hype for a real-world monorepo.

The Current Setup

Before we start tearing things apart, let's look at what we're working with. The Pedalboard monorepo currently runs on:

Yarn 3.2.0 with the workspace-tools plugin
Lerna (independent versioning) for publishing
7 packages under packages/* - React components, hooks, linting plugins, and dev tools

Here's the root package.json workspace configuration:

{
    "workspaces": [
        "packages/*"
    ],
    "packageManager": "yarn@3.2.0"
}

And the .yarnrc.yml that ties it all together:

nodeLinker: node-modules

plugins:
  - path: .yarn/plugins/@yarnpkg/plugin-workspace-tools.cjs
    spec: "@yarnpkg/plugin-workspace-tools"

yarnPath: .yarn/releases/yarn-3.2.0.cjs

The workspace scripts use Yarn's workspaces foreach command for running tasks across packages:

{
    "test": "yarn workspaces foreach -pRv run test",
    "lint": "yarn workspaces foreach -pRv run lint",
    "build": "yarn workspaces foreach -ptv run build"
}

So there's Yarn-specific syntax sprinkled throughout. Let's see what it takes to swap it out.

Out With the Old

The first step is satisfyingly destructive, deleting all the Yarn-specific files:

.yarnrc.yml - gone
.yarn/ directory (vendored binary, plugins, cache) - gone
yarn.lock - gone

In their place, pnpm needs just one config file. I created a pnpm-workspace.yaml at the root:

packages:
  - 'packages/*'

That's it. No plugins, no vendored binary, no special config. Already feeling lighter.

Translating the Scripts

This is where the meat of the migration lives. Yarn and pnpm have different CLI syntax for workspace operations, so every script that touches workspaces needs updating.

The root package.json scripts went from this:

{
    "test": "yarn workspaces foreach -pRv run test",
    "test:since": "yarn workspaces foreach --since -pRv run test",
    "lint": "yarn workspaces foreach -pRv run lint",
    "build": "yarn workspaces foreach -ptv run build"
}

To this:

{
    "test": "pnpm -r run test",
    "test:since": "pnpm --filter '...[origin/master]' run test",
    "lint": "pnpm -r run lint",
    "build": "pnpm -r run build"
}

The pnpm -r flag handles recursive execution across packages. But the interesting bit is the --since replacement.

How pnpm Handles "Since"

Yarn's --since flag runs commands only on packages that changed compared to the default branch. pnpm achieves this with --filter using a git-diff syntax:

pnpm --filter '...[origin/master]' run test

The [origin/master] part selects packages where files changed compared to origin/master. The ... prefix is the clever bit - it means "also include dependents of changed packages." So if @pedalboard/hooks changed, @pedalboard/components (which depends on it) gets selected too. That's exactly the behavior we want in CI.

I also had to update yarn bundle references in individual package scripts to pnpm run bundle, and swap --untraced yarn.lock to --untraced pnpm-lock.yaml in the Chromatic commands.

One subtlety: the coverage script passes extra flags to the test scripts recursively. With Yarn the syntax was:

"coverage:all": "yarn workspaces foreach -pRv run test -- --coverage --silent"

The natural pnpm equivalent would be:

"coverage:all": "pnpm -r run test -- --coverage --silent"

But pnpm v9 changed how -- is handled - it now passes the -- separator through to the underlying script, so jest ends up receiving "--" "--coverage" "--silent" and treats -- as a test name pattern instead of a separator. The fix: drop the extra -- and pass the flags directly:

"coverage:all": "pnpm -r run test --coverage --silent"

pnpm passes unrecognized flags through to the script, so --coverage reaches jest correctly.

Updating Lerna

Lerna's config needed two changes. The npmClient field changed from "npm" to "pnpm", and I removed the now-obsolete bootstrap command block:

{
    "npmClient": "pnpm",
    "command": {
        "publish": {
            "ignoreChanges": ["ignored-file", "*.md"],
            "message": "chore(release): publish %s"
        },
        "version": {
            "message": "chore(release): version",
            "allowBranch": "master",
            "conventionalCommits": true
        }
    },
    "packages": ["packages/*"],
    "version": "independent"
}

Another Yarn holdover was the resolutions field in the root package.json. pnpm uses its own format for dependency overrides:

{
    "pnpm": {
        "overrides": {
            "parse-url": "^8.1.0"
        }
    }
}

The pnpm Strictness Tax

Here's where things got interesting. pnpm's strict dependency isolation is one of its biggest selling points - it prevents phantom dependencies (using packages you haven't explicitly declared). But it also means that things that "just worked" under Yarn's hoisting can break.

I hit six cases of this:

1. Missing `@types/react` in the hooks package

error TS7016: Could not find a declaration file for module 'react'.

My @pedalboard/hooks package uses React (it's a hooks library, after all) but only declared react as a peerDependency - no @types/react in devDependencies. Under Yarn, the types were hoisted from @pedalboard/components and available everywhere. Under pnpm, each package only sees its own declared dependencies.

Fix: Added @types/react to the hooks package's devDependencies. Honestly, this should have been there all along - pnpm just caught the sloppy dependency declaration.

2. Shared esbuild config couldn't find its dependencies

Error: Cannot find module 'esbuild-sass-plugin'

The esbuild.config.js lives at the monorepo root and is called from package directories via node ../../esbuild.config.js. It requires esbuild and esbuild-sass-plugin, but those were only declared in packages/components. Node resolves require() relative to the file's location (the root), not the CWD. Under Yarn, hoisting put them in the root node_modules. Under pnpm, they weren't there.

Fix: Added esbuild and esbuild-sass-plugin to the root devDependencies. Since the config file lives at the root, its dependencies should be declared there.

3. The `postcss` module in the stylelint plugin

Same story - @pedalboard/stylelint-plugin-craftsmanlint imports postcss types but only had stylelint (which depends on postcss) as a direct dependency. pnpm doesn't allow accessing transitive dependencies.

Fix: Added postcss as an explicit devDependency.

4. The `workspace:` Protocol for Inter-Package Dependencies

This was the most subtle one. The @pedalboard/components package depends on @pedalboard/hooks with a regular version range:

{
    "dependencies": {
        "@pedalboard/hooks": "^0.3.1"
    }
}

Under Yarn, workspace symlinks meant Jest could transform and test this dependency just fine. Under pnpm, the module resolution goes through .pnpm/ store paths, which tripped up Jest's transformIgnorePatterns - Jest refused to transform the ESM export statements in the hooks package.

The proper pnpm fix is the workspace: protocol:

{
    "dependencies": {
        "@pedalboard/hooks": "workspace:^"
    }
}

This tells pnpm to always link to the local workspace package. During pnpm publish, it automatically replaces workspace:^ with the actual version range like ^0.3.1. Clean, explicit.

I also updated every other inter-workspace dependency to use workspace:^. For example, @pedalboard/components also depends on @pedalboard/stylelint-plugin-craftsmanlint as a devDependency, which got the same treatment.

One thing to watch out for: any time you change a workspace:^ specifier, you need to run pnpm install locally and commit the updated pnpm-lock.yaml. CI runs with --frozen-lockfile by default, so it will fail hard if the lockfile doesn't match package.json. I learned this the fun way when the CI pipeline blew up with:

ERR_PNPM_OUTDATED_LOCKFILE Cannot install with "frozen-lockfile" because
pnpm-lock.yaml is not up to date with packages/components/package.json

Just run pnpm install and commit the lockfile. Simple fix, easy to forget.

But that alone wasn't enough. Jest was still choking on the @pedalboard/hooks ESM code. The root cause: pnpm's module resolution routes workspace packages through its .pnpm/ store paths, and Jest's default transformIgnorePatterns excludes everything in node_modules - including those store paths. The fix was a one-liner in jest.config.base.js:

transformIgnorePatterns: ['node_modules/(?!@pedalboard)'],

This tells Jest: "ignore node_modules for transformation, except for anything under @pedalboard." With that, Jest correctly transforms the workspace packages' TypeScript/ESM source. It's a small change with an outsized impact.

5. Storybook's `@storybook/node-logger` version conflict

This one only showed up when running Chromatic. The Storybook build failed with:

Error: Cannot find module 'storybook/internal/node-logger'

storybook/internal/node-logger is a v8+ internal path that doesn't exist in Storybook v7. But the project uses v7. What happened: pnpm's resolver pulled in @storybook/node-logger@8.6.14 as a transitive dependency from somewhere, and its shim tries to import from the v8 internal path. Under Yarn, the v7 version was consistently hoisted everywhere.

Fix: pin it in pnpm's overrides:

{
    "pnpm": {
        "overrides": {
            "@storybook/node-logger": "7.6.21"
        }
    }
}

6. Missing `style-loader` and `css-loader` in components

After fixing the logger, Storybook's build still failed:

Module not found: Error: Can't resolve 'style-loader'

The Storybook config in packages/components/.storybook/main.js uses @storybook/addon-styling-webpack with explicit webpack rules that reference style-loader and css-loader. Under Yarn, these were hoisted from some transitive dependency and available globally. Under pnpm, they need to be declared where they're actually used.

Fix: added style-loader and css-loader to @pedalboard/components's devDependencies.

CI/CD Updates

The three GitHub Actions workflows needed the pnpm/action-setup@v4 step added before Node setup, and all yarn commands replaced with pnpm equivalents:

steps:
    - uses: actions/checkout@v4
      with:
          fetch-depth: 0
    - uses: pnpm/action-setup@v4
    - uses: actions/setup-node@v4
      with:
          node-version: 20
    - run: pnpm install
    - run: pnpm run build

The pnpm/action-setup@v4 action reads the packageManager field from package.json to know which pnpm version to install. No extra configuration needed.

I also updated a hardcoded spawn('yarn', ...) call in the coverage aggregation script to use pnpm.

Bonus: TypeScript Gaps Yarn Was Hiding

This one isn't strictly a pnpm migration issue, but pnpm's strictness smoked it out. When building @pedalboard/components, I got:

error TS2550: Property 'fill' does not exist on type 'any[]'.
Do you need to change your target library? Try changing the 'lib' compiler option to 'es2015' or later.

Array.fill is ES2015. We were using it. TypeScript didn't know about it because tsconfig.base.json had no target or lib set - which defaults to ES3. Yarn's hoisting had been accidentally providing a newer TypeScript version from one of the workspace packages, masking the gap.

The fix: add explicit target and lib to the base config:

{
    "compilerOptions": {
        "target": "ES2020",
        "lib": ["ES2020"]
    }
}

And since only the React packages (components, hooks, media-loader) run in a browser, DOM types belong there specifically - not in the base that's shared with Node.js tooling packages like the ESLint and Stylelint plugins:

{
    "compilerOptions": {
        "lib": ["ES2020", "DOM"],
        "module": "ES2020"
    }
}

A latent bug that was hiding in plain sight. pnpm didn't cause it - it just made it impossible to ignore.

Lerna Needed More Convincing

After all that, I thought the migration was done. Then I tried to run lerna publish and got:

lerna ERR! ENOWORKSPACES Usage of pnpm without workspaces is not supported.

The root cause: Lerna v5 has zero knowledge of the workspace:^ protocol. When it publishes @pedalboard/components, it sends the package.json as-is, workspace:^ and all. npm receives "@pedalboard/hooks": "workspace:^" as a literal dependency version, tries to resolve it in the registry, finds nothing, and returns a deeply unhelpful 404.

The real fix: upgrade Lerna. Support for the workspace: protocol was added in v6.1.0, and in v8 (current latest) it's solid. Bump the version:

{
    "devDependencies": {
        "lerna": "^8.0.0"
    }
}

In lerna v8, workspace discovery from pnpm-workspace.yaml happens automatically - the old useWorkspaces option was removed (it'll throw ECONFIGWORKSPACES if you leave it in). Lerna v7+ also pulls in nx as a task runner by default, which I don't need:

{
    "npmClient": "pnpm",
    "useNx": false
}

Registry auth with pnpm publish

With lerna v5, npmClient: pnpm only affected installs - lerna always called npm publish internally regardless. The auth setup that actions/setup-node generates worked fine because npm expands the ${NODE_AUTH_TOKEN} variable from its generated .npmrc.

Lerna v8 actually honors npmClient for publishing too, so now pnpm publish is doing the work. pnpm doesn't pick up ${NODE_AUTH_TOKEN} from the npm-generated config the same way. The fix: a .npmrc at the project root that pnpm always reads:

registry=https://registry.npmjs.org/
//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}

Safe to commit - no real token, just an env var reference that resolves correctly in CI.

Wrapping Up

The migration is done and everything is green - all 7 packages build, all tests pass, and linting works (the few lint errors that remain are pre-existing, not migration-related).

The biggest takeaway? pnpm's strict dependency isolation is a feature, not a bug. It caught several sloppy dependency declarations that Yarn's hoisting was silently papering over. Every package now explicitly declares what it uses, and that's just better engineering.

The workspace: protocol is a nice touch too - it makes inter-package dependencies explicit and handles the version replacement during publishing automatically. I wish I'd had this from the start.

Was it worth the migration effort? yes, but there is still more to come which will explain why I chose to migrate to pnpm ;)

Pedalboard on GitHub

Why Testing After with AI Is Even Worse

Matti Bar-Zeev — Sat, 28 Feb 2026 15:30:22 +0000

Back then, I wrote a piece about “Why Testing After Is a Bad Practice” where I laid out 4 main reasons why writing unit tests after the code is already implemented is a bad practice. Here’s a quick summary:

Unconsciously complying with a given “reality” - Writing tests after tends to shape the tests around the existing code, and not challenge it or make sure it does what it should
Emotional attachment to our code - You’ve already developed some emotional attachment to the code, and you unconsciously avoid changing it, even when required
Overly mocking - Your code was poorly designed since nothing (mainly tests) required it to be modular and separated by concerns. This causes the tests written after to mock a lot of modules and services in order to test basic functionalities
Gets neglected at the end - When you write tests after, they tend to get neglected due to project delivery considerations.

These 4 main reasons still stand, but in the age of AI Agentic Coding, tests that were always (mistakenly) considered as tedious, boring tasks, became the ultimate candidate for code generation.
I’m here to explain why writing tests with AI after the code was implemented is even worse than writing tests after without it. For that, I will take the 4 reasons mentioned above and show how they become even more critical. Let's start with the first one:

Unconsciously complying with a given “reality”

AI Agentic coding, and in that sense, LLMs in general, have their reality. Since they are stateless, their reality is the accumulated "problem" context they pick along the way. When your code is already implemented, it becomes part of the context, and therefore, part of the reality for the AI Agent. In this case, the Agent will write tests that satisfy this reality, for example, if you implemented code that has a logical flaw within, it will write a test which asserts this logical flaw.
In Andrej Karpathy’s talk Deep Dive into LLMs like ChatGPT, he claims that the better answer for a math problem (for example) will always be going through the mathematical flow and giving the answer at the end as opposed to giving the answer first, and then explaining the flow after, due to the same reason - when the agent gives the answer first, it becomes a part of its context and it will try to justify it as it continues.

Emotional attachment to our code

This again refers to the “problem” context the agent has. It is not the developer who is emotionally attached to the code, but rather the Agent, which is attached to its context. If your prompt is “write unit tests for this module” it will write unit tests for this module, without examining if the module is currently doing what it should. So the “Emotional attachment to code” here is replaced by “Strict attachment to the context”.

Overly mocking

I heard this from many developers - “The Agent has mocked every little thing, even the code it should test!”.
Yes, this happens a lot, and for a “good” reason, if that can be said. The Agent was instructed to write tests, and the success criteria for the Agent is simple: make the tests pass, and it will do whatever it takes to achieve that goal. Extensive mocking is part of it.
The reason for that usually comes from bad code design and coupling between modules, but sometimes it is just the Agent “getting carried away” and generating a full environment just to test a simple unit. In some cases it even mocks parts of the module under test, just to make the test pass. The horror.
(BTW, I saw situations where in order to fix a test the agent simply decided to remove it - mission accomplished 😐)

Gets neglected at the end

Maybe in the age of agentic coding it will still be addressed in the end, but it won’t be neglected (since the agent will write the tests for us), but here is exactly where our problem lies - the task of writing tests is being pushed to the end of the dev cycle, and under delivery pressure, we hand the steering wheel to the Agent and approve whatever it generates. The end result is bad tests which don’t supply us with the safety net we need (even more so, in the age of agentic coding).

The rise of TDD (and Planning)

I see more and more community influencers speaking favorably on TDD when working with agentic coding, for example here is @mattpocockuk TDD Red Green Refactor is OP With Claude Code.
TDD is nothing new and it was dismissed for years by developers who underestimated its long-term value. I’m super glad that agentic coding has brought it back to center stage and made its advantages clear.
This, BTW, also goes for planning. Yes, planning! That part where you need to think before you start typing code. Agentic coding is showing us that TDD and proper planning are essential for better results.
The red - green - refactor is helping the agent (and the engineer using it) to stay focused on the end result with small increments. Small increments always give better outcomes when it comes to agentic coding.

In conclusion

Avoid delegating test writing to the end of the development cycle, especially to an Agent, since it will only try to satisfy the already written logic and will not provide you with the safety net you desperately need. If you can practice TDD as part of your work with agentic coding, that’s even better. You can incorporate TDD into the agentic coding skills, where the agent will write the test first, write the minimal code to make it pass, and then refactor. Combined with solid planning, this approach produces more predictable and more trustworthy results.

Photo by Pawel Czerwinski on Unsplash

Replacing a Plop React component generator with a Claude Code Skill

Matti Bar-Zeev — Fri, 06 Feb 2026 13:14:34 +0000

The challenge in the age of Agentic coding

One of the biggest challenges emerging in the age of agentic coding is determinism and standards-enforcement. In large organizations this becomes even more critical, where many developers are using agentic coding to produce a lot of code modifications, and maintaining standards and good quality becomes nearly impossible without the right tools.

This, however, is not a new issue. Large organizations always struggled with this and automatic tools were created to reduce the friction of standard and quality enforcement, such as ESlint, Prettier, Git commit hooks, tests, to name a few.

One of the tools which helps avoiding misalignment is a generator tool which helps developers scaffold and ramp-up components in a consistent manner, quickly and by given templates.

An example for such a tool is Plop, which is a generator that can rely on templates and developer’s input to scaffold code. I actually wrote an article about creating such a tool for scaffolding a React component, along with tests, Storybook story etc.

But...

Thinking about the agentic coding tools we’re all using, using Plop appeared to be somewhat redundant, and I wondered if I could convert my Plop generator for React components to a Claude Code Skill.

First, let’s be on the same page on what Claude skill is -

Skills extend what Claude can do. …Claude adds it to its toolkit. Claude Code skills follow the Agent Skills open standard, which works across multiple AI tools.

From here

I also understand that Skill is the evolution of Slash Commands, while commands were a simple MD file, Skill is more robust, that can have its own context content, meta data and as the docs say, can be reused in different agents.

For the demonstration here, I will be using VSCode with Claude installed

All the code can be found under my Pedalboard monorepo.

Let’s begin -

Requirements

I would like to have a Skill called /create-react-component.
When using this Skill, the developer will input the desired component’s name and once given, it will create the following files under the the /src/<component-name> directory (in the “components” package):

Index.tsx - the component main file
Index.css - the components CSS
Index.stories.tsx - the component’s Storybook story
Index.test.tsx - the component’s unit test

These files will be made according to templates for complete result determinism.

Let’s start

I’m going to do this experiment on components packages which reside on my Pedalboard project. This project was manually written until now, so this is the first time I’m introducing agentic coding to it.

The first thing I would do is to initialize the project as a Claude Code project, using the /init command -

Claude goes over the project, inspects it and creates a new CLAUDE.md file. In there it stores all that it found about the project, like that it’s a monorepo, and it runs with Yarn, and uses Jest for testing etc.

Creating a custom Skill

Skills in Claude reside under the ./claude/skills directory.
We can prompt Claude to create a skill

Create a Claude skill called create-react-component

Claude went over the code in the entire monorepo and came up with this skill.md:

---
name: create-react-component
description: "Create a new React component in packages/components following established conventions"
argument-hint: [ComponentName]
---


Create a new React component in the `packages/components` package following the established conventions.


## Component: $ARGUMENTS


Create a folder `packages/components/src/$ARGUMENTS/` with the following files:


### 1. `index.tsx` — Component implementation
Use the template from [templates/component.tsx](templates/component.tsx):
- Replace `{{ComponentName}}` with `$ARGUMENTS`
- Replace `{{component-name}}` with the kebab-case version


### 2. `index.test.tsx` — Jest unit tests
Use the template from [templates/component.test.tsx](templates/component.test.tsx):
- Replace `{{ComponentName}}` with `$ARGUMENTS`


### 3. `index.stories.tsx` — Storybook story
Use the template from [templates/component.stories.tsx](templates/component.stories.tsx):
- Replace `{{ComponentName}}` with `$ARGUMENTS`


### 4. `index.scss` — Component styles
Use the template from [templates/component.scss](templates/component.scss):
- Replace `{{component-name}}` with the kebab-case version of `$ARGUMENTS`


### 5. Update barrel export
Add a named export to `packages/components/index.ts`:

export {default as $ARGUMENTS} from './src/$ARGUMENTS';

After creating all files, run `yarn test` and `yarn lint` from `packages/components/` to verify everything works.

You might have noticed that the Skill relies on some templates. Claude “saw” that the project used Plop with handlebars templates, it took the templates and created a newer version of them under the .claude/skills/create-react-component/templates path. So what we currently have is this file structure:

.claude/
├── settings.local.json
└── skills/
    └── create-react-component/
        ├── SKILL.md                        # Main instructions with frontmatter
        └── templates/
            ├── component.tsx               # Component template
            ├── component.test.tsx          # Test template
            ├── component.stories.tsx       # Story template
            └── component.scss              # Style template

It appears that unlike Plop, the templates used by the Skill do not have to be Handlebars templates, the Skill can settle with double curly brackets (“{{...}}”) for args placeholders.
So we have the Skill instructions and we have the templates ready - it’s time to try it out

Trying it out…

For Claude to register the new Skill we need to restart it, and after we do, we prompt the following:

/create-react-component TestComponent

Hmmm… Claude nicely created 4 files, let’s look at the index file for the component to see what we got:

/**
* Copyright (c) 2025-present, Matti Bar-Zeev.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*/


import React from 'react';
import PropTypes from 'prop-types';
import './index.scss';


export interface TestComponentProps {
   title: string;
}


const TestComponent = (props: TestComponentProps) => {
   const {title} = props;


   return (
       <div className="test-component">
           <span>{title}</span>
       </div>
   );
};


TestComponent.propTypes = {
   title: PropTypes.string,
};


export default TestComponent;

Not bad, but as you can see, Claude took my “legacy” Plop templates, which were meant for JS (and not TypeScript) and simply migrated them, as is, to the Skill’s template. Let’s change them to fit TS, and then use the Skill again to make sure Claude indeed always follows them. Here is my prompt for that:

Take the templates from .claude/skills/create-react-component/templates and convert them to be TypeScript complaint, removing redundant code, like propTypes

And after Claude did some required modifications, let’s run the Skill to create the component again

/**
* Copyright (c) 2025-present, Matti Bar-Zeev.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*/


import React from 'react';
import './index.scss';


export interface TestComponentProps {
   title: string;
}


const TestComponent = ({title}: TestComponentProps) => {
   return (
       <div className="test-component">
           <span>{title}</span>
       </div>
   );
};


export default TestComponent;

Much better :)

Tests are passing and also Storybook story looks as it should:

Is using template files a good thing?

One of the questions I’ve asked myself is why not having the SKILL.md also contain the templates and be done with it?
So having templates as a separated content offers a few advantages:
Smaller initial context - The SKILL.md file stays concise with just instructions. The templates are only loaded when the skill actually runs (via Read tool calls).
Cleaner separation - Instructions vs. template content are clearly separated, making the skill easier to maintain.
On-demand loading - Templates are fetched only when needed, rather than always being present in the skill definition.
Templates reuse - other Skills can use templates from another Skill.

That being said, it’s important to note that reading the templates requires a read tool call, which might slow things down a bit, but I think that the overall advantages mentioned above are worth it.

As mentioned about, You can find the new skill markdown and templates in the Pedalboard monorepo on GitHub.

Cheers

Photo by Art Institute of Chicago on Unsplash

Responsible Vibe Coding

Matti Bar-Zeev — Sat, 11 Oct 2025 15:05:55 +0000

With the rise of AI agentic coding, Vibe-Coding entered our dev life and stirred quite a storm. The web is full of vibe-coding opinions and rants, some say it's a new dawn, some lash at it - but this post is not any of these.

In this post, I would like to share some of my current insights on the process, especially what works for me and how to avoid the many "traps" vibe coding may lead you into.
As I see it, like in many technologies and tools, it is never the tech's fault but rather the wrong usage of it. But unlike other techs, vibe coding kinda lures you into using it wrongly. It requires very strict self-discipline.

If we have to, we can separate vibe coders into two - those who know and understand the technology the agent uses and have a good architectural mindset, vs. those who just wanna get something working fast without caring what's going on under the hood. We can go further and separate it even more - those who know how to articulate their intentions well in plain English and those who don't.

The rise of the "verbal programmer"

Tech has a repeating growth cycle - from something that is unnatural for humans, like typing code, into something that blends smoothly with our natural mental model, like touch screens, voice AI assistants, VR, etc.
The software development world was always dominated by those who could think like a computer. Take an idea they have and translate it into "if" statements and loops. This is not the case anymore.

AI coding requires a different set of skills, one might call "soft skills." It is how you communicate your intentions in a verbal way. The top skill required is for one to master the English language (LLMs are mainly trained in the English language, that's a cold fact), and if you wish to receive good outcomes from it, you must master this communication skill.
It is no longer how fast you type or how well you know a syntax, but how accurately you can express your intentions and requirements.

The "verbal programmer" is the one who will get the better results and faster than the "analytic programmer."
I simply love it.

Not just "What" but also "How"

If someone asked me what is the most crucial thing to understand about coding with AI, I would say, "Understand that it is a development assistant, not a code magician."

Many claim that they're frustrated with the results they get. I used to say that too when I first started playing with it, and I think I know why it happened - we used to think that we only need to tell our agent what to do, but for better results, you also need to tell it how you want it to be done. And for the "how," you need to know your shit. If you leave it to the agent, you're in for big surprises.

So instead of "get the list of songs from this API and render it as a list," you might wanna say, "get the list of songs using the fetch API and render it in a list by reusing the Song component as the rendering component for a single song, having the song unique ID as the key."

It is more than ok to ask the agent to give you options you can choose from and create a small pros and cons comparison. In the end, you are the one who needs to decide what direction to go.
If you are not familiar with the solutions offered, it is a great opportunity to learn about them, the first step being to ask the agent why it thinks this is the best solution for the problem at stake.

Which model?

I must admit that I don't have an answer for that, and TBH I don't think that there will ever be a good answer for that. The model race is happening as we speak, and almost every day you hear of another model version which is supposed to be better at this and that. The FOMO is overwhelming and distracting us from the main objective.

To quote Westley,

"~~Life~~ software development is pain, Highness, anyone who says differently is selling something."

Code still remains hard, and creating a complex application is still a challenge.
Like you, I used a bunch of them, jumping from one to another, and I managed to get good results from what was considered a "poor at coding" model, and bad results from those who claimed to be good at coding.

It's true that model training stops at different times and the weight parameters can vary to address coding better. Still, my 2 cents on the matter - the model you choose is not that critical. Most of us don't deal with cutting-edge tech in our day-to-day, and for the large majority of code generation, the top models are pretty much the same.

I tend to think of it as a guitar player messing around with many overdrive pedals when what he should really be focusing on is playing the riff correctly.

Architectural concerns

Many have said it before - agents don't excel at making good architectural decisions.
They are absolutely right (pun intended).

If we take React, for example, unless you specify it, there is a good chance the agents will attempt to write everything in a single component with no real thinking about reuse or SoC. I don't blame them. How could they know that you planned to use the SongList component in another component? How should they know that the SongList component should not be aware of the logic which fetches the data it renders?

Another example is creating Express server endpoints. If you don't specify it, there is nothing holding the agent from creating the routes, the controllers, and the services which handle the request all in the same file.

While determining the next token in creating a component might be "straightforward" for the model, the architectural decisions are more complex, and the content on which the model has trained probably does not represent your organization's business logic. Chances are it will fail to make the right decisions then.
Again, this is not saying the model isn't "smart" (like I heard many say). It simply means that it hasn't got the context it needs to make the right decisions. And the context needed for these kinds of decisions is massive.

Yet, having written these lines, I started wondering... what if the agent writes the routes, controller, and services in the same file? Should we fear spaghetti code in the era of AI?
After all, I can give the spaghetti code to my agent and it will know how to untangle it... right?
I have my answer for that (spoiler alert - "don't encourage spaghetti code!"), but I also leave it here for you to ponder about as well. Leave your answers in the comments below.

As mentioned before, our agent also doesn't always know how to choose the most suitable solutions for the problem. For example, if you tell it to create code for fetching data from a certain endpoint, you will most likely end up using the "axios" lib. Why? Because this is the pattern the model has seen commonly in many projects, but it does not mean that it suits your project. You would be quite satisfied with the native fetch API. I, for one, would always prefer the native APIs first over installing third-party libraries. In fact, I have this as a stored "memory" in Cursor:

"The user prefers that the assistant always use native APIs and validate official documentation before implementing custom in-house or third-party solutions."

What works for me

I cannot consider what I'm doing "vibe-coding". For lack of a better term, I will call it "Responsible vibe-coding"
Here how it goes -

Todos

I first start with a clear and very precise TODO. This can be a simple feature or a bug fix. I believe that everyone has their own list of what should be done, whether it is an MD file with bullets or a Jira board.
This allows me to get a high-level view of what should be done and consider if there are tasks that should come before or after one another. The smaller the task is, the better. Once I have this list sorted out (and it's a dynamic list, so tasks can be added, removed, or reordered in it), I can continue to the next steps.

I found that categorizing the list helps me stay focused on what's important. Here are my categories:

MVP - The things that the product cannot be completed without. Every task there is mandatory
Bugs - The list of bugs that I found along the way or that I know of. These tasks completion is also mandatory
Refactoring - Anything I would like to re-organize or write in a different way, while not altering the current functionality. Especially when you're vibe-coding, soon enough you will discover areas where things could have been done differently to improve code reusing, ease future maintenance etc.
Nice to have - Well, this goes without saying.

Some of the tasks required a plan. A PRD (Product Requirements Document) is in order, and this is the first stage I start to request the AI agent for assistance.

The plan - PRD (or SPEC)

I would take the task at hand and ask the agent to create a PRD for it. An example for such a prompt may look like this:

For the task of <task from the todo here>, create a PRD which consists of the following: a brief of the current status, a solution overview, very detailed implementation phases, each containing steps that can be marked once completed. Each phase should be a deliverable phase, meaning the application is still shippable once the phase is completed. There is no need for risk assessments, future planning, or testing recommendations.
Write the PRD to a prd-<task-name>.md under the prd directory.

Recently, Cursor released a "Plan" mode to their chat, which does a pretty good job, asking leading and clarification questions and producing a good plan for the agent to follow.

When the agent completes this task, you should have a PRD markdown file under the prd folder of your project. I think it makes a lot of sense to have a dedicated directory for those PRDs in your project. They come in very handy when you want to communicate with others and hand in details of the implementation.

The most critical part in this step is to review the PRD.

Given that your task was small and well defined, the PRD should not be a long document. Go over the solution overview and see if it fits your requirements. Check the implementation phases and make sure that the agent did not insert any undesired steps, because it will try.
Ask the agent a question about the decisions it took. Don't let it get away with the "You're absolutely right!" BS. Ask it to give the pros and cons of a decision you're not sure about and decide accordingly.

Implementing the PRD

When you're satisfied with the PRD, it is time to move forward to the implementation. I usually go with,

Start implementing phase 1.1 <the title for the phase>. Implement this phase only and don't continue until I approve your implementation.

Agents do have the tendency to get carried away (I literally had an agent telling me, "Sorry, I got carried away," when I asked why it continued implementing the next phase).

Once the agent finishes implementing the phase, go over the modified code, review it, see that you understand what it did, and if not, require explanations (this is, BTW, a great way to learn stuff as you go).
Don't be quick to click that "Keep all" button. Take the time to review the changes; otherwise, you will lose track very quickly. If you don't understand what your agent is doing, you're in for some serious time loss.

Also, if you think the agent modified too many files - more than was needed given your understanding of the architecture - you might be facing a vibe-code-smell (see section on that below), and you might wanna stop and see what you can do to better architect your code. The conclusions may lead you into adding some tasks under the "Refactoring" todo section.

Debugging

Agents tend to insert a lot of console logs and other debugging tools when they generate the code. I don't mind it that much, and I think that when the feature is being implemented, it greatly helps to figure out if it works as expected.
Loggers also help the agent find bugs in the implementation. I found myself, in several cases, giving the agent the log stack from my browser or Node server for it to figure out what went wrong and at what point, and it was very helpful.
Having said that, it would be wise to clean up the massive logging after the implementation is completed, leaving only the crucial log messages.
Clean up
Surprisingly enough, the agent seems to avoid discarding unused files.
Many times, I found the agent leaving "dead code" behind and moving on, and I ended up telling it, "Remove any redundant or dead code from the modified files." You'd be surprised at how much junk is accumulated during vibe-coding.

Vibe code smell

I came to the realization that there is such a thing as Vibe-code-smell, and it's important to identify it as soon as possible and act to un-smell it.
Like in traditional code-smell, this is an indication of "... weaknesses in design that may slow down development or increase the risk of bugs or failures in the future."
Identifying the code-smell when vibe-coding is a bit more challenging, because you're less intimate with the code being written. But here are a few indications you can keep an eye on -

Too many modified files

As simple as it sounds, this is when your agent performs modifications in too many files, way more than what you thought your prompt required. This usually hints that your code design is broken, perhaps SoC is not well implemented correctly. In React, for example, it may indicate props drilling or bad state management, perhaps a component that needs to be extracted into smaller components and reused properly.
In any case, this is the first indication that your agent is running wild and that you are losing control over what it's doing.

"You're absolutely right!"

Careful now with how you accept this warm compliment from your agent. The model behind the agent, as you know, is a simple token-resolver machine in the end, and if you suggest an idea to it, it becomes part of its context, therefore, it will attempt to justify it in the next resolved tokens. Although you are very smart, you cannot be absolutely right all the time.
Ask the agent to debate, show the pros and cons of your suggestion, and maybe offer other options with comparisons.

Too many iterations

Sometimes you will see the agent going into a loop of trying to solve an issue, saying that it found the solution, implementing it, checking it, realizing it was not solved, and then repeating.
For me, after the 3rd attempt, I will stop it and look at the code myself, while having the agent as an assistant in debugging it. Read what the agent is outputting in the chat to make sure it did not get carried away outside the scope of the issue at hand. This is also a good place to say that I'm not in favor of giving the agent free permission to run any command or tool at will. I always want to approve what it is about to execute when it's not just modifying code. Aside from avoiding the risks in it, this also gives me good control over stopping it from spiraling into endless iterations.

In conclusion

Responsible Vibe Coding is not about resisting the new way of developing - it's about embracing it with awareness, discipline, and ownership. The power of AI-driven coding agents is undeniable, but that power comes with a responsibility: to stay in control, to think architecturally, and to communicate intentionally. The line between "let the agent handle it" and "guide the agent effectively" is thin, and learning to walk it makes all the difference between chaos and craftsmanship.

Vibe coding can make us faster, but only if we remain thoughtful. It can make development smoother, but only if we don't surrender our understanding of what's happening under the hood. The agent can generate the code, but it's still our job to ensure it makes sense - structurally, logically, and contextually.

In the end, Responsible Vibe Coding is not just a method - it's a mindset. It's about shifting from "prompt and pray" to "plan, guide, and verify." It's about treating the AI as a capable collaborator, not an infallible magician. When done right, it brings out the best in both human reasoning and machine efficiency. When done carelessly, it amplifies the very weaknesses we once hoped it would fix.

So keep your architecture clean, your prompts precise, and your curiosity alive. Code responsibly, vibe intentionally.

Cheers

Photo by Lukas Tennie on Unsplash

Elegant Hybrid TS project’s build

Matti Bar-Zeev — Tue, 25 Mar 2025 14:30:00 +0000

Oh BTW, This post was 100% human written with no AI assistance whatsoever. All typos and bad grammar are my own. Enjoy :)

I doubt you remember, but back at the time I wrote a piece about Hybrid NPM package through TypeScript Compiler (TSC), which explained how you can leverage TSC to produce 2 artifact types (ESM and CJS) from a single source code.
I thought it was pretty clever. Hell, I still do 😉

Recently though, I came across one of Matt Pocock’s TS course lessons (which I highly recommend on btw) that suggested a more elegant way to achieve that. In this post I will migrate to that way and explain what I do so your AI agent won’t get left behind ;)

Note: It would be best if you go over the Hybrid NPM package through TypeScript Compiler (TSC) article, so you will get the context of what I’m about to write on.

I have this package in my Pedalboard monorepo, called @pedalboard/media-loader (that you should totally check out if you’re a React dev struggling with media loading performance), which has a build process that generates 2 types of artifacts - ESM and CJS. In order to support that I’ve created 2 different tsconfig.json files and in the build script I’m running them both.
It looks something like this:

"build": "tsc --project tsconfig.esm.json & tsc --project tsconfig.cjs.json",

Although there is nothing wrong with it, it kinda requires this plumbing in the package.json file and all-in-all feels a bit of a brute-force-primitive. Fortunately there is a more elegant way to achieve that using the references config.
Here is how:

Both the tsconfig.esm.json and tsconfig.cjs.json are in the root dir of the package, and to them I will add the “main” config file - tsconfig.json, and its content looks like this:

{
   "references": [
       {
           "path": "./tsconfig.esm.json"
       },
       {
           "path": "./tsconfig.cjs.json"
       }
   ],
   "files": []
}

Let’s go over it real quick - it has a references array which has 2 paths defined in it, one for each config file, and it has an empty array for the files config, to ensure that the tsconfig.json does not enforce any type checking, but rather leaves that to the referenced projects.

Now we need to change the build script. Instead of what we have, we now write this:

"build": "tsc -b",

Notice the -b param, which tells TSC to run it in build mode, thus taking into consideration the different references in the main tsconfig.json file. In other words, without the -b param, it won’t work as we expect it to.

And that is it!

When we run our build script now, TSC will run both configurations and create both ESM and CJS artifacts.
There is a lot more you can do with the project references like cache type check results (for faster builds) or define dependencies between projects, but in this case what we have is enough.

The code is available on Github @pedalboard/media-loader

Be seeing you

Photo by Trnava University on Unsplash

I've built the TodoMVC app with HTMX and lived to tell the story

Matti Bar-Zeev — Tue, 12 Nov 2024 15:00:00 +0000

In this post, I’ll walk you through my experiences building the TodoMVC app using HTMX. I'll cover the architectural considerations, handy tips, pros and cons, insights, and everything in between.

The code can be found here, along with an elaborated README - https://github.com/mbarzeev/todomvc/tree/htmx/examples/htmx

The TodoMVC project

Back when JavaScript frameworks were flooding the web ecosystem and a new, promising framework seemed to emerge every month as the next big thing, Addy Osmani set out to create a benchmark application. His goal was to push each framework to its reasonable limits, giving developers a sort of "speed-dating" experience to evaluate them quickly.

This project was known as TodoMVC, and you can still find its content relevant for technologies like React, Vue, Svelte etc. It has become the goto place for checking whether a technology fits your purposes or not.

HTMX

If you’re in tune with web dev trends you’ve probably heard or read about HTMX. This is a small JS project, aiming to simplify the way we build web apps, relying more on server rendered markup and AJAX.

My interest in this technology stems from my "Back to Square One" approach, which is all about stepping off the frameworks and meta-frameworks roller coaster for a moment to take a fresh look at how we build things today—and explore ways to improve the experience for both us and our customers.

HTMX fits this approach pretty well, relying on much less JS code for heavy client magic, and more on web standards and the http protocol.

Opportunity knocks

Obviously the first place I went to check whether HTMX is something that one can rely on was the TodoMVC project, alas, there was no example written with this technology.

Hear that Opportunity knocking?
I can create this example and deepen my HTMX knowledge on the process, and hey - I might be able to contribute to the TodoMVC open-source project. This is a win-win-win situation. I like those.

First steps

Gladly the TodoMVC project has a great contribution docs and it also provides a starting template, along with a detailed application spec. I took the template and spec and started inspecting them to get a better understanding on how the app client is constructed (the markup) and what functionality needs to be supported.

This initial phase, as you will see later, will have serious implications on how the final HTMX app architecture will end up like.

HTMX app architecture

I believe the key takeaway from this article is that you can't approach HTMX app architecture the same way you would with reactive, client-heavy JavaScript frameworks. Doing so would mean missing out on HTMX’s unique advantages and could lead to frustration, making it feel difficult or unintuitive. Building with HTMX is a completely different discipline.

In HTMX most of the work is done on the server side, thus most of your architecture decisions are relevant for that tier, yet, you need to construct the client markup in a sensible way that will allow you to enjoy the different swapping strategies HTMX offers.

In the case of TodoMVC, I was, for better or worse, constrained by the template’s markup. However, I didn’t have much desire to change the template anyway, as I wanted to see how HTMX would perform within these limitations.

Server architecture

I will be using the C4 model in order to visualize the “server container” architecture.
The server container has 4 components in it:

Component	Description
TodosRouter	Defines the routes the client uses to interact with the app
TodosAPI	The "Model" - Holds and manipulates the todos data, handling all CRUD ops
Templating engine	The "View" - Renders HTML from the data
TodosController	The "Controller" - Handles requests, using TodosAPI to compose HTML

Yes, you could do the entire thing in a single file, but since the application here is very conservative it allowed me to think deeper on how I would see an HTMX driven application being code-designed.

One of the aspects of HTMX that really appealed to me is that the client directly receives content it can immediately parse and display, rather than receiving a JSON data structure that then has to be converted into markup.

This means there must be a component responsible for "translating" the data into markup. That tier would be the templating engine. This approach allows us, perhaps in the future, to change how we “translate” data into markup without altering other parts of the system.

The component which orchestrates it all is the controller, and it works with the API to get and manipulate the data, and then takes the result and passes it through the templating engine component in order to send markup to the client.

The diagram below describes it better:

The tech stack

It’s a good point to present the technologies we’re going to use for this application. Obviously these are my choices, and you can choose whatever alternative you feel comfortable with -

First, I’m using a NodeJS env. It’s the most intuitive for me plus it keeps JS across all.
For the app server I’m using Fastify. The templating engine is EJS. The client would be plain ‘ol HTML, JS and CSS with the help of HTMX.

That’s it.

The page’s parts

It was tempting to divide the page into little components and treat each as a template, but this is exactly where I found myself needing to insist on taking a different approach.
It narrows down to HTMX ability to perform an AJAX call instead of making a “conventional” http GET request to render the app.
While an http GET will refresh the entire page, causing all the resources to be re-fetched, the AJAX call allows me to replace a certain portion of the doc without the need for refresh, but this requires some architectural mind-shift.

The diagram below represents the application’s parts -

Let’s go one by one and understand what each template is responsible for -

index.ejs

This template is what's returned when we request the page from the root url. It is responsible for loading the app’s CSS and JS required, and inside of it it embeds the todos.ejs.
Notice that the input for “What needs to be done?” is part of the index.ejs since there is no need for it to be refreshed from the server.

todos.ejs

This is the main application. It holds the Todos list and the footer at the bottom.
I wanted to bundle them together since this is the part which gets refreshed whenever we add, remove, toggle or even filter todos.

This template is also the one which has the hx-triggers to load the data when events are triggered from the server. Basically, this is the place which listens to what happens in the application and refreshes the application part accordingly.

todo-list.ejs

This is the todo list, a simple UL with a loop going over the given todos and creating an LI element for each.
In the original TodoMVC template, this section is also responsible for rendering the “toggle-all” button, found on the left side of the input. I wanted to keep this structure, though I’d probably not constructed it this way to begin with.

The “toggle-all” button is using hx-patch to make a PATCH request to the /todos/toggle endpoint in order to toggle all the todos.

footer.ejs

This template is responsible for the todo count, filtering, and clearing all completed todos. It only appears when there are todos in the system and updates whenever a todo is added, deleted, or marked as completed or active.
It uses anchor tags for the filters, navigating to a URL that includes the filter. However, we’re using HTMX boosting here to ensure that we don’t refresh the entire page, but only fetch what is needed.

single-todo.ejs

This one renders a single todo, but it is not that simple.
You can toggle the single todo by clicking on the checkbox, and you can also edit the todo’s label by double-clicking it.
I’m using hx-patch to make a PATCH request to the /todos/toggle/:id endpoint (now with the corresponding todo’s id), and I’m using hx-patch also to make a PATCH request to the /todos/edit/:id endpoint to edit the label.

Rendering & boosting

HTMX, if you allow it, makes you think of an application rendering in 2 ways - either you refresh the entire doc upon state change or you swap different sections in the page according to a server state change.
This means that you need to design the document content in such a way that you can support both methods.

Our application has a hx-boost="true" attribute at its body level. This means that it will be applied to all nested in it, since this attribute is inherited.

In TodosMVC case it can be shown when requesting the application for the first time in comparison to fetching just the internal todos markup (that is the todos list and footer)

Accessing the app for the first time

To get a better understanding, here is a sequence diagram of fetching the application for the first time:

When this is the first time the application gets rendered, the GET request is not boosted, meaning that we want to get the entire markup for the main document, and not just parts of it.

HTMX knows how to append a hx-boosted header on requests which are boosted and it is something we can query later on the server and know which action should be performed. As can seen in the example below:

fastify.get('/', async (request, reply) => {
    let isHxBoosted = request.headers['hx-boosted'] === 'true';
    const {filter} = request.query;
    const markup = isHxBoosted
        ? await this.todoController.renderTodos(filter)
        : await this.todoController.renderIndexPage(filter);
    return reply.type('text/html').send(markup);
});

In the example above we render the entire index page and return it back to the browser.

Filtering the todos

Let’s look at what happens when we filter the todos by clicking the “completed” filter button on the Footer:

We perform a GET request with the filter set to “completed”. The request is boosted and the server knows not to do a completed render to the page, but just the todos part. It renders the todos.ejs template with the filtered data and returns this markup to the client, which knows to swap it in the right place.

Editing a single todo

What happens when we edit a single todo item?

In the example above we send a PATCH request (yes, we try to stick to ReST protocols the best we can) with the new label and the todo item’s id, from there we update the todo and render a single todo item, by rendering the single-todo.ejs template. Once we have its markup we return it to the client which knows to swap it in the closest LI element to the element which triggered this request.

Adding a new todo

And when we’re adding a new todo? Here we’re using the HTMX events -

In the example above we use the great power of HTMX events.
The first action is easy to understand, we send a POST request for the new label to be added to the todos list.
Once this task is completed, we do not return any markup, but rather return a response that has a hx-trigger header with an event called “todoCreated”.
This event can then be listened upon on the client, and when it receives it can perform actions, like refreshing the todos.
Registering to this event is done on the todos.ejs template where, as you can see, we also listen to other events

<section
   class="todos"
   hx-get="/todos?filter=<%= filter %>"
   hx-trigger="todoCreated from:body, todoDeleted from:body, allToggled from:body, singleToggled from:body"
   hx-swap="outerHTML"
>

In most of the cases, there is a need to fetch the entire inner todos markup, that is the todos list and the footer. The most optimized way is to fetch it all in a single request instead of separating it to several requests, each for a different part of the app. See more about it in the “Thoughts” parts below.

Toggling and cleaning

Both are done with the same techniques shown above. You can check out the code on GitHub to see how it is done,

Filtering

The footer holds a filtering section where you can choose between “Active”, “Completed” and “All” filters.
The way it is done is by navigating to a URL which holds the filter type as a request param. The A href looks like this:

<li>
    <a class="selected" href="?filter=active">Active</a>
</li>

But as you guessed it we do not want a full page reload when a filter is selected, and again the hx-boost comes to our help and the request for the “index” page is boosted and our server knows how to handle this and returns only the relevant markup.

In the footer.ejs we set that the response target will be the .todos selector and we’re set to go:

<ul class="filters" hx-target=".todos">

And that’s it. We have a fully working TodoMVC app built with HTMX :)

Thoughts

Client side logic

At certain places in the client code I found myself in need to add JS code, using “real” vanilla JS in one place and HTMX syntax in another.
One example is clearing the input for new todos when a submit for a new todo was made. It looks like this:

(function (window) {
    'use strict';

    // Clear the todo label input after creating a new todo
    window.document.body.addEventListener('todoCreated', () => {
        const todoLabelInputElement = window.document.querySelector('.new-todo');
        todoLabelInputElement.value = '';
    });
})(window);

Now, I could have done this by returning a blank todo from the server upon creating a new todo, but I thought it was an overkill (WDYT?).

There is no rule to avoid using JS on the client, and you should not avoid that when it makes sense, but I think that the approach should be “JS should be used to enrich/hydrate the markup we receive from the server and not for creating the DOM in the first place”.
I’m cool with the decision of performing this cleanup in JS on the client side.

Switching styles upon editing

When you double click a single todo item, it changes style class to “editing” and also when you blur the input it switches back. This transition is done by listening for those events using the hx-on syntax and then executing the event handler with inline JS. Yikes… I know.

<label hx-on:dblclick="this.closest('li').classList.replace('<%= todo.status %>', 'editing');this.closest('li').querySelector('.edit').focus();"><%= todo.label %></label>

And on the input, check the hx-on:blur:

<input
       class="edit"
       name="label"
       value="<%= todo.label %>"
       hx-on:blur="this.closest('li').classList.replace('editing', '<%= todo.status %>');"
       hx-patch="/todos/edit/<%= todo.id %>"
       hx-target="closest li"
       hx-swap="outerHTML"
   />
</li>

Not very elegant, but I feel that as long as it is kept at a reasonable scope,it’s fine. What bothers me a bit is that we’re keeping a state (the todo.status) on the client, and one of the things I like about HTMX is the fact that it ~~forces~~ encourages you to keep the state in a single place - the server.
Having said that, calling the server each time to change the style is a bit of an overkill. If you have suggestions on how this can be more elegant while still performant, do share in the comments below.

Requesting the entire todos markup each time?

For quite a few scenarios I’m requesting the server to render the todos markup, which consists of the todos list and footer, over and over again.
Even with the HTMX boosting it feels a bit too much… but is it?

Yes, reactive applications, which do some heavy lifting on the client, know to listen to changes and render the specific elements accordingly, and when I look at the DOM changes I kinda wish I could do the same with HTMX.

Well, in theory, I could.
I could separate the changes into different http requests, but it felt like going too “religious” over this. Yes, the application core renders again and we have a request going out of the browser again, but receiving a markup which represents the single source of state found on the server kinda makes me peaceful about it. It is not like we make a request to the server for an initial state and from there on we’re juggling between 2 potential states, one on the client and one on the server, hoping that they will be synced in the end.
Don’t know… still thinking about it.

Going offline

I think that this is the biggest concern here.
If the application is offline, nothing can render as expected on the client. It is not like we fetched the entire code needed for the client and from there on we can still perform actions on the client and buffer them in case of offline network. Here it is a bit more complicated.
There are ways to mitigate it using cache techniques or service-workers, but I think that when you choose HTMX you need to understand that your client is highly dependent on network connection.

Conclusions

This was a really interesting challenge. I learned quite a lot on how HTMX works and what it means to create an architecture for an application using this technology.
I find HTMX very appealing but I understand from what I read out there that there are still places where HTMX fails. I’m not entirely convinced yet, since I think that most of these failures derive from trying to approach HTMX applications in the same way you would with Reactive technology. It’s not.
This implementation is very naive, but it is a good start to understand the potential of HTMX and also where it falls short. I think that the integration with WebComponents can be an interesting evolution to this project.
I really like the idea that HTMX strips down much of the complexity of building a web app these days.

As said the code can found here: https://github.com/mbarzeev/todomvc/tree/htmx/examples/htmx
You can also check out the PR I’ve made on the original TodoMVC repo, and I’d really appreciate you voting for it so that the maintainers will review and consider including it (even when the repo is no longer actively maintained).

Hope this helps and inspires you,
Take care

Resources

HyperMedia Systems book
HTMX docs
TodoMVC on Github
C4Model

Back to sq1: My basic HTML template

Matti Bar-Zeev — Tue, 01 Oct 2024 10:00:00 +0000

What is the best basic template for an HTML doc?
I often ask myself this question, and though there are quite a few code generators which do just that (or at least claim to) I wanted to take control over the very basic foundation of any web page, regardless of whether I’m using React, Solid, vanilla or any other frontend solution to build it.
What should it include and why?

The core idea behind "back to sq1" is to utilize the right tools for the right tasks and to fully understand the purpose of each tool. As we go along this post, I hope this will become clearer. I will go through each line (or related group of elements) step by step, explaining its function and why I believe it should be part of a basic HTML template.

Let’s start from the top -

DOCTYPE

<!DOCTYPE html>

According to the specs “Including the DOCTYPE in a document ensures that the browser makes a best-effort attempt at following the relevant specifications.” We don’t want anything surprising going on when the document is rendered, right?
BTW, it is case insensitive, so we can also write <!DOCTYPE HTML> but I prefer the format above (so is my IDEA so we’re cool on that).

The html root element

<html lang="en" dir="ltr">
    …
</html>

For creating our HTML doc we need to start with the html tag. Did you know that you can omit this tag in certain situations? But why would we - let’s keep it readable and understandable.
The lang attribute can be applied to all elements (yes, not just html), but it is a good practice to put the lang up there and have all its descendant elements adhere to it.

We also want to add the direction the page is at, meaning what is the direction of the content in this page. E.g. If it's English, we will use ltr (left to right), if it's Hebrew, rtl.

That pretty much sums it for the html root tag. The other attributes available for it are either obsolete or not needed for common modern web pages.

The head element

The head element is where things begin to vary. Here we need to think about what we want this tag to contain as it can affect our page performance among other things.
We will start with the page’s metadata. The head tag will usually hold some meta tags. Lets see what are the basic meta tags we would like to have

Meta tags

charset

<meta charset="utf-8">

Here we set the encoding of the entire html doc. It must be utf-8 since it is the only valid encoding for HTML5 documents. Also it has to be within the first 1024 char of the document, so it is wise to put it first.
Having this will eliminate the need to use the content-type http-equiv meta tag (see below).

viewport

<meta name="viewport" content="width=device-width, initial-scale=1.0">

The name and the content are like “key” and “value”. Here we set the viewport to width=device-width, initial-scale=1.0. What do they mean?
“width=device-width” means that when the page loads, its width should be the width of the device it is being displayed on. You can also set this width to actual size in pixels but I don’t think there is a real use-case for that.
The “initial-scale” defines the zoom level of the document. 1.0 means that it is 100%.
So basically what we’re saying here is “your width is the display width and your zoom should be 100% to begin with”.

http-equiv

“Defines a pragma directive”. What is a pragma you ask? Basically it is more information on how to handle this document that the browser understands.
The allowed values for this meta are http headers. According to the docs there are 5 headers you can use, but I’m only interested in one - the content-security-policy.
The content-security-policy is the one that allows us to define the security policy without needing to register them on the response header.
There are some advantages to that, one of them relates to the JAMstack, where you eventually serve static pages from a CDN. It might be that the pages being cached do not bear the same headers the response has from the origin server and you still want your CSP (content security policy) to protect the page. In addition to that, headers tend to have size limits and sometimes CSPs can be quite large.
So I suggest having this meta in your html page and not on the header. I think that the most basic one is allowing src resources only from a secured http connection. Later on you can enrich that to gain better security over the web page.

<meta http-equiv="Content-Security-Policy" content="default-src https:" />

Author

This one is for setting the author of this document, and why the hell not to?

<meta name="author" content="Matti Bar-Zeev">

Description

This is mainly for SEO. It describes the page purpose so that search engine indexing could get a better understanding on how to index it. There are a lot more meta tags and tricks to increase SEO indexing but this is a topic which deserves its own post. For now, here is what I have:

<meta name="description" content="Your site description">

Title tag

Finally we’re getting into something which also has a displayable aspect to it - the title tag.
This tag determines the text shown in a page's tab. Let’s keep it as simple as it is:

<title>Your Website Title</title>

Fav Icon

Another important thing is the fav icon. This is the icon that the browser will show on the page’s tab, and in bookmarks (hence the “favorite” in the name) and usually bears the brand logo.
Usually this will hold a 16x16 pixels .png, .ico or some other low volume image. avoid large fav icons since they still need to be seen in a 16x16 resolution yet their size will affect your site’s Core Web Vitals (CWV) score. The path can be either relative or absolute. I will go with the relative one

<link rel="icon" href="./favicon.ico">

Resetting the styles

It is well known that each browser has its own “understanding” of what the default CSS styles should be, thus the same CSS can result in a different visual experience across different browsers. So far for a single standard to rule them all.
What we need to do to avoid this chaos is to reset and align the styles before we start writing our first CSS rule.
There is a great article by Josh Cameo (if you haven't already, check out his blog, the guy's a true inspiration) where he gives his reset style rules with a good explanation about each decision. This is my goto reset CSS file.
I’m adding the media=”all” to declare that this reset is applied to all sorts of media, no matter screen size.

<link rel="stylesheet" href="./reset.css" media="all"/>

Other CSS resources

I’m going to separate my CSS resources. We already saw that we have the reset.css which aligns all browsers. On top of that I will have a common.css which will contain rules that are common for all pages in the site, and on top of that I will have the specific page.css that will contain rules only for the page we’re at.
This gives a lot of advantages, first by caching the “static” css files while only fetching the changing CSS for each page, and also keeping a good SoC of which CSS rule goes where, and not mixing responsibilities.
So I’m adding these lines:

<link rel="stylesheet" href="./common.css" media="all" />
<link rel="stylesheet" href="./page.css" media="all" />

The body element

This is where our page content is being placed. Generally speaking this tag should have 3 main “sections” - header, main and footer. These are all semantic html tags, and here is the place to emphasize the importance of using semantic html over generic div’s. This will help SEO and users who need a better accessible site. Always try to find the most suitable semantic html to represent your content.

At the end of the content inside the body element I will put the scripts. The reason is well known but still - JS scripts tend to be render blocking, and also cause the browser to fetch, evaluate and execute them (which may take time). Having the scripts at the end gives the browser a chance to render the content before starting to execute scripts.
So here what we have in the body element:

<body>
        <header>Header</header>
        <main>Main</main>
        <footer>Footer</footer>

        <script src="./page.js"></script>
    </body>

I think that this is it for now. Here is the final result:

<!DOCTYPE html>
<html>
   <head>
       <meta charset="UTF-8" />
       <meta name="viewport" content="width=device-width, initial-scale=1.0" />
       <meta http-equiv="Content-Security-Policy" content="default-src https:" />
       <meta name="author" content="Matti Bar-Zeev">
       <meta name="description" content="Your site description" />
       <title>Your Website Title</title>
       <link rel="icon" href="./favicon.ico" />
       <link rel="stylesheet" href="./reset.css" media="all" />
       <link rel="stylesheet" href="./common.css" media="all" />
       <link rel="stylesheet" href="./page.css" media="all" />
   </head>


   <body>
       <header>Header</header>
       <main>Main</main>
       <footer>Footer</footer>


       <script src="./page.js"></script>
   </body>
</html>

Now you can start enriching your web page with content and interactivity.
I hope that this basic template helps you understand the different parts better so you can choose them with care instead letting a generator do the decisions for you, without knowing their meaning

If you have any other ideas that you think should be included in the basic HTML template, please leave your comment in the comments section below

Cheers

*Hey! for more content like the one you've just read check out @mattibarzeev 🍻

Photo by Sean Stratton on Unsplash

Optimize your React’s Carousel with MediaLoader

Matti Bar-Zeev — Sat, 23 Mar 2024 15:06:33 +0000

At some stage in our development journey, we've likely come across an image carousel. This component typically contains multiple images nested within it, allowing users to navigate forwards and backwards between them.

However, there's a performance drawback to many existing implementations. Consider an image carousel featuring 100 images: in most scenarios, all images are loaded upfront, even if the user only views a single image. This results in a significant waste of network bandwidth and may delay the retrieval and availability of other critical assets.

Let me show you what I mean -
I’m using the react-responsive-carousel as my React carousel component and I'm adding six images to it. Here's the code for that:

<Carousel showThumbs="{false}" className="carousel">
    <div>
        <img src="/assets/image-01.jpg" />
        <p className="legend">Legend 1</p>
    </div>
    <div>
        <img src="/assets/image-02.jpg" />
        <p className="legend">Legend 2</p>
    </div>
    <div>
        <img src="/assets/image-03.jpg" />
        <p className="legend">Legend 3</p>
    </div>
    <div>
        <img src="/assets/image-04.jpg" />
        <p className="legend">Legend 4</p>
    </div>
    <div>
        <img src="/assets/image-05.jpg" />
        <p className="legend">Legend 5</p>
    </div>
    <div>
        <img src="/assets/image-06.jpg" />
        <p className="legend">Legend 6</p>
    </div>
</Carousel>

As demonstrated in the video below, upon rendering the carousel, all six images are requested and fetched, even though only the first one is initially visible. Subsequently, I can proceed to navigate between the images:

Now, let's introduce the MediaLoader to assist us with the loading strategy. I'm merely wrapping the Carousel component with the MediaLoader and specifying a loading strategy that operates as follows: it examines the transform style of the sliding element and loads the necessary image accordingly. This approach is straightforward yet effective for this particular scenario. Take a look at the updated code below:

<MediaLoader
    loadingStrategy={(mediaHTMLElementRefs, loadMedia) => {
        const sliderElement = document.querySelector('.slider.animated') as HTMLElement;
        let imageIndexToLoad = getImageIndexFromTransformStyle(sliderElement.style.transform);


        function getImageIndexFromTransformStyle(transformStyle: string) {
            let imageIndexToLoad = 0;
            if (transformStyle) {
                const match = transformStyle.match(/-?[\d.]+(?:%|px)/);
                if (match) {
                    const transformPercent = match[0];
                    imageIndexToLoad = parseInt(transformPercent) / -100;
                }
            }
            return imageIndexToLoad;
        }


        function loadImageByIndex(index: number) {
            let imageRefToLoad = mediaHTMLElementRefs[index];
            if (imageRefToLoad && imageRefToLoad.current) {
                loadMedia(imageRefToLoad.current);
            }
        }


        const callback = (mutationList) => {
            for (const mutation of mutationList) {
                if (mutation.attributeName === 'style') {
                    const style = mutation.target.style;
                    imageIndexToLoad = getImageIndexFromTransformStyle(style.transform);
                    loadImageByIndex(imageIndexToLoad);
                    break;
                }
            }
        };


        const observer = new MutationObserver(callback);
        observer.observe(sliderElement, {attributes: true});


        loadImageByIndex(imageIndexToLoad);
    }}
>
    <Carousel showThumbs={false} className="carousel">
        <div>
            <img src="/assets/image-01.jpg" />
            <p className="legend">Legend 1</p>
        </div>
        <div>
            <img src="/assets/image-02.jpg" />
            <p className="legend">Legend 2</p>
        </div>
        <div>
            <img src="/assets/image-03.jpg" />
            <p className="legend">Legend 3</p>
        </div>
        <div>
            <img src="/assets/image-04.jpg" />
            <p className="legend">Legend 4</p>
        </div>
        <div>
            <img src="/assets/image-05.jpg" />
            <p className="legend">Legend 5</p>
        </div>
        <div>
            <img src="/assets/image-06.jpg" />
            <p className="legend">Legend 6</p>
        </div>
    </Carousel>
</MediaLoader>

Notice that there have been no alterations made to the Carousel code itself. As depicted in the video below, only the necessary image is now loaded:

Pretty neat, right? You can also check the working demo in the project’s Storybook.

Naturally, you can refine the logic and make it more sophisticated. For instance, you could consider loading the next image upon hovering over the arrow button. Additionally, you might opt to load images exclusively during periods of network idleness. The decision is entirely yours, granting you full control over the process.

To read more about the MediaLoader see this post.

Share your thoughts in the comment :)

Take control over your media loading

Matti Bar-Zeev — Tue, 19 Mar 2024 17:00:00 +0000

MediaLoader is a versatile React component that provides fine-grained control over the loading of media assets such as images, videos, and audio files. It offers a customizable loading strategy, allowing developers to prioritize resources and optimize user experience.

It has been a while, I know.
Hopefully I have something for you that will compensate for my absence 🙂

As you may already know, web performance has become increasingly significant within the frontend community. Those who value their work and prioritize user experience dedicate considerable effort to enhancing the performance of their websites and applications.

Improving performance involves loading only essential resources, allowing the network connection to prioritize critical assets and expedite the page's readiness and interactivity.
Media content—such as images, videos, and audio—typically constitutes the bulk of data to be loaded. Moreover, when the browser encounters a media tag during document parsing, it initiates immediate loading by default.

The "lazy" attribute for the img tag aims to alleviate network load by enabling the deferred loading of images until necessary. When you use the lazy attribute, the browser will only load the image when it enters the viewport, helping to conserve bandwidth and improve page loading times, especially on pages with many images.

However, this is insufficient. We recognize that viewport entry alone may not always suffice as the desired trigger. There are instances where we might prefer loading based on observing a CSS property or clicking an element, among other examples. Additionally, it's important to note that images are not the sole type of media content we aim to lazy-load, yet they unfortunately lack support for such functionality.

This is where the MediaLoader comes in to fill the gap.

MediaLoader is a versatile React component that provides fine-grained control over the loading of media assets such as images, videos, and audio files. It offers a customizable loading strategy, allowing developers to prioritize resources and optimize user experience.

With MediaLoader, you can effortlessly manage the loading process, dynamically loading media content based on user interactions, viewport visibility and much more. Whether you're building a gallery, a multimedia-rich website, or an application with heavy media content, MediaLoader empowers you to deliver a seamless and performant user experience.

MediaLoader is designed to be as non-intrusive as possible, integrating into your existing React applications without imposing a heavy footprint and without changing the DOM structure. It provides a lightweight wrapper around your current media, without requiring a complete overhaul of your codebase.

You can check out some demo examples in this Storybook, and see the code in the pedalboard repo.

How do I use it?

You first need to install it:

yarn add @pedalboard/media-loader

npm install @pedalboard/media-loader

Now, say you have this JSX:

<img src="/assets/image-04.jpg" alt="image-04"></img>
<img src="/assets/image-05.jpg" alt="image-05"></img>
<img src="/assets/image-06.jpg" alt="image-06"></img>
<div>
    <img src="/assets/image-09.jpg" alt="image-09"></img>
</div>

All you need to do is to wrap it with the MediaLoader component and provide a loading strategy to it, like so:

import MediaLoader from '@pedalboard/media-loader';
...

<MediaLoader
    loadingStrategy={(mediaHTMLElementRefs, loadMedia) => {
        // You loading strategy here
    }}
>
    <img src="/assets/image-04.jpg" alt="image-04"></img>
    <img src="/assets/image-05.jpg" alt="image-05"></img>
    <img src="/assets/image-06.jpg" alt="image-06"></img>
    <div>
        <img src="/assets/image-09.jpg" alt="image-09"></img>
    </div>
</MediaLoader>

The loadingStrategy is a function which receives 2 arguments - An array of the media element refs and the loadMedia function. When you call the loadMedia function with a given ref it will load the associated media for it, whether it is an image, video or audio.

Your loading strategy might be something like this:

loadingStrategy={(mediaHTMLElementRefs, loadMedia) => {
                       const intersectionCallback = (entries) => {
                           entries.forEach((entry) => {
                               if (entry.isIntersecting) {
                                   let elem = entry.target;
                                   loadMedia(elem);
                               }
                           });
                       };
                       let options = {
                           rootMargin: '0px',
                           threshold: 1.0,
                       };
                       let observer = new IntersectionObserver(intersectionCallback, options);


                       mediaHTMLElementRefs.forEach((mediaHTMLElementRef) => {
                           let target = mediaHTMLElementRef.current;
                           if (target) {
                               observer.observe(target);
                           }
                       });
                   }}

In the example above we act the same as the lazy attribute of an img tag. Once the element intersects the viewport, we trigger the load.

You can now probably see the great control it allows you to have over your media content loading. Another example can be monitoring the left CSS property of the element and only when it surpasses 300, load it’s media content:

import MediaLoader from '@pedalboard/media-loader';
...

<MediaLoader
    loadingStrategy={(mediaHTMLElementRefs, loadMedia) => {
        const monitor = (target) => {
            const computedStyle = getComputedStyle(target.parentElement);
            const currentLeft = parseFloat(computedStyle.left);
            // If the image container reach a certain left then load it
            if (currentLeft > 300) {
                loadMedia(target);
                return;
            }

            // Continue monitoring in the next frame
            requestAnimationFrame(() => monitor(target));
        };

        mediaHTMLElementRefs.forEach((mediaHTMLElementRef) => {
            let target = mediaHTMLElementRef.current;
            if (target) {
                requestAnimationFrame(() => monitor(target));
            }
        });
    }}
>
    <div
        className="image-container"
        onClick={(event) => {
            (event.target as HTMLDivElement).classList.add('animate-media');
        }}
    >
        <img src="/assets/image-01.jpg" alt="image-09" className="run"></img>
        <div>And now me</div>
    </div>
    <div
        className="image-container"
        onClick={(event) => {
            (event.target as HTMLDivElement).classList.add('animate-media');
        }}
    >
        <img src="/assets/image-02.jpg" alt="image-09" className="run"></img>
        <div>Quick! Click me ;)</div>
    </div>
    <div
        className="image-container"
        onClick={(event) => {
            (event.target as HTMLDivElement).classList.add('animate-media');
        }}
    >
        <img src="/assets/image-03.jpg" alt="image-09" className="run"></img>
        <div>Click me ;)</div>
    </div>
</MediaLoader>

You can read more about it in the project README file, download it from the NPM registry and start playing with it 🙂

I’d love to hear your thoughts and feedback on this project, and if it helped you produce a better performing web content.

Until next time,
Cheers!

Photo by USGS on Unsplash

SolidStart, Netlify and Forms

Matti Bar-Zeev — Fri, 23 Jun 2023 11:14:08 +0000

My daughter has ventured into the world of bracelet crafting, and now she's on a mission to conquer the internet with her handmade creations and maybe even get some orders going. I thought it was a good opportunity to have a go on SolidStart and build a complete (yet very naive) eComm site with it.

You may wonder why I chose SolidStart. Well, I am particularly impressed with SolidJS and believe that this framework offers a compelling alternative to other UI frameworks out there, mainly React. However, that is a separate discussion altogether.

Fueled by an abundance of motivation and under the watchful eye of my sweet yet demanding child, I embarked on my late-night coding sessions, completely unaware of the intriguing (or should I say, "frustrating") challenges that awaited me.

Curious to know how I conquered those obstacles? Well, you're in for a treat. Just keep reading...

Hey! for more content like the one you're about to read check out @mattibarzeev on Twitter 🍻

First let’s set some background

SolidStart?

SolidStart is a meta-framework (I didn’t coin the term, look it up) that stands shoulder-to-shoulder with the likes of NextJS, SvelteKit, and Remix. It's a game-changer when it comes to simplifying the development process of robust web applications. Think of it as your go-to solution for effortlessly bundling essential components like routing, authentication, and other features that are often deemed repetitive and mundane.

Netlify?

Netlify is a platform which helps developers publish their web content efficiently and fast. From efficient hosting solutions to seamless integration with your codebase, automation workflows, form submission handling, and powerful APIs, Netlify has got you covered and then some.

What's particularly exciting is that Netlify has recently welcomed Rayn Corniato, the mastermind behind SolidJS, as one of its employees, so this all comes together quite nicely :)

Deploying SolidStart on Netlify

I’ve created the site, with nested routes and what-have-you and reached a point where I want to deploy it and check the end-to-end “purchase” flow.
I utilize Netlify's Github deployment option, which involves granting Netlify access to a specific Github repository. In this setup, I define a command, typically an npm script like npm run build, that generates the site artifacts. Additionally, I specify the distribution directory.

With this configuration, Netlify actively monitors any changes made to a designated branch on Github. When a change occurs, Netlify automatically triggers the build command and deploys the resulting artifacts from the specified distribution directory. This seamless integration ensures that my site stays up to date with minimal effort.

This works well in most ordinary cases, but SolidStart is a bit different.
You see, the “dist” directory does not contain any HTML files nor does it have any edge functions that handles the site’s requests. This means that if we give Netlify the out-of-the-box “dist” directory as the distribution directory, the site won’t work.

Luckily there is a solution for that - A Vite plugin called solid-start-netlify.
Though still experimental, I found out that it did the work for me. You use it like this in your vite.config.js:

import netlify from 'solid-start-netlify';
...


export default defineConfig({
    plugins: [
        solid({
            adapter: netlify({edge: true}),
        }),
    ],
});

By setting the adapter like so, Vite will now create a new distribution directory called “netlify” and in it you will find the edge functions’ declaration that Netlify can work with in order to respond with the site’s content.
Here is the netlify directory content:

Now you can set Netlify to take the “netlify” directory as the distribution directory and it works as expected.

SolidStart forms submission on Netlify

Netlify offers a cool feature that simplifies form submission handling. Here's how it works: by annotating your form as being managed by Netlify, you enable Netlify to automatically analyze the form, extract the necessary data, and attentively listen for any submissions. Once a form is submitted, you can conveniently access the data in a dedicated section within your Netlify admin console.

But again, it’s different when it comes to SolidStart 🙂
There are 2 challenges here - the first one is not related specifically to SolidStart (or SolidJS for that matter), but it is a general issue that Netlify has with JS generated forms.

When I say JS generated forms I mean any form which is generated using JS (that obviously means JSX as well). You see, when netlify is “asked” to inspect a certain form, it expects it to be a real markup, so it can traverse it and extract the different fields that will be submitted.
It cannot do that with JS generated form (yet, I believe this is something that they are either working on now or in the near future), so we have to use a workaround for that

The workaround is to create an html file which has the form, named as you desire, and with the same fields the JSX form has. Here is an example for the form tag of a “regular” html form:

<form name="checkout" netlify netlify-honeypot="bot-field" hidden>
...

“netlify” tells Netlify to inspect this form. I created such a file and placed it in the “public” directory.
The next step is to take our JSX form and add a hidden input field to it which adds a “form-name” field to the submission with a value of the same name we gave the “regular” html form.
So If we named our “regular” form “checkout” we need to add this field to our JSX form:

<input type="hidden" name="form-name" value="checkout" />

Now Netlify can inspect that “regular” html form and register it with its fields. You can read more about this approach here.

The second challenge is a bit more complex, and sadly not documented (so I hope you’ve found this resource after a short search) -
I would like to have a onSubmit callback for my form, cause I would like to do some data manipulations before sending it to the server, so I add this:

<form onSubmit={handleSubmit}>

And according to the docs, this is what you need to do in the callback:

const handleSubmit = (event) => {
event.preventDefault();


const myForm = event.target;
const formData = new FormData(myForm);


fetch('/', {
method: 'POST',
headers: {'Content-Type': 'application/x-www-form-urlencoded'},
body: new URLSearchParams(formData).toString(),
});
};

We gather to form data and do a POST request to the root route.
But this does not submit the form… why?

The reason is that the root route, or any other SolidStart route for that matter, is handled by an edge function, and submitting a form to a route which is handled by an edge function cripples Netlify form submission handling.

So what do we do then? We submit the form to a route we know is static, like… the “regular” html form we’ve used before (it’s in the public directory and therefore available). Changing the POST endpoint to that file solved the issue!

To recap

Netlify does not know how to inspect JS generated forms out-of-the-box
Make sure that you have a “regular” html form with a name and all the fields of the JSX form, available on the public directory
Add hidden input in your JSX form which defines a “form-name” field with the value of the name you gave the “regular” html form
You cannot submit a Netlify managed form to an endpoint which is handled by an edge function
On submit, make sure that the endpoint you’re submitting to is not being handled by edge functions

I hope this helps you, and if you’re aware of other or better ways to achieve that, make sure you share with the rest of us in the comments below :)

Hey! for more content like the one you've just read check out @mattibarzeev on Twitter 🍻

DEV Community: Matti Bar-Zeev

Bazel For a Frontend Monorepo

Caching

Preparing a project for Bazel

The MODULE.bazel at the project’s root

Install NPM packages with Bazel

Bazelifying the hooks package

Build

Compiling TypeScript

Type declarations

Copying the files to the package’s dist dir

Testing

Running Jest

Coverage report

Coverage paths and the NYC reporter

Watch mode

Linting

Exposing the ESlint config for all sub packages

Making ESlint available for all sub packages

Using the eslint_test target

Wrapping up

From Lerna to Changesets

What Lerna Actually Does in Pedalboard (at This Point)

Enter Changesets

Initializing Changesets

Two config issues, right off the bat

A Good Time to Clean Up Dead Scripts

Pulling Out Lerna Completely

Installing Changesets Properly

A Mindset Shift: Intent Over Detection

The Publish Script

Enforcing the Changeset Discipline in CI

Updating the GitHub Actions Workflow

Wrapping Up

Migrating a monorepo from Yarn to PNPM

The Current Setup

Out With the Old

Translating the Scripts

How pnpm Handles "Since"

Updating Lerna

The pnpm Strictness Tax

1. Missing @types/react in the hooks package

2. Shared esbuild config couldn't find its dependencies

3. The postcss module in the stylelint plugin

4. The workspace: Protocol for Inter-Package Dependencies

5. Storybook's @storybook/node-logger version conflict

6. Missing style-loader and css-loader in components

CI/CD Updates

Bonus: TypeScript Gaps Yarn Was Hiding

Lerna Needed More Convincing

Registry auth with pnpm publish

Wrapping Up

Why Testing After with AI Is Even Worse

Unconsciously complying with a given “reality”

Emotional attachment to our code

Overly mocking

Gets neglected at the end

The rise of TDD (and Planning)

In conclusion

Replacing a Plop React component generator with a Claude Code Skill

The challenge in the age of Agentic coding

But...

Requirements

Let’s start

Creating a custom Skill

Trying it out…

Is using template files a good thing?

Responsible Vibe Coding

The rise of the "verbal programmer"

Not just "What" but also "How"

Which model?

Architectural concerns

What works for me

Todos

The plan - PRD (or SPEC)

Implementing the PRD

Debugging

Vibe code smell

Too many modified files

"You're absolutely right!"

1. Missing `@types/react` in the hooks package

3. The `postcss` module in the stylelint plugin

4. The `workspace:` Protocol for Inter-Package Dependencies

5. Storybook's `@storybook/node-logger` version conflict

6. Missing `style-loader` and `css-loader` in components