Forem: Francesco Di Donato

How I Turned 4 Sites and a Shared Lib Into One pnpm Workspace

Francesco Di Donato — Tue, 14 Apr 2026 22:00:00 +0000

Before the monorepo, my local ~/Workspace/didof/ looked like a cork board of unrelated projects: four Astro sites with their own node_modules folders, their own lockfiles, their own @didof/shared-something-that-was-always-out-of-sync, and their own build commands. Pushing a fix to the shared library meant four npm link dances, four CI builds, and a lingering anxiety that one of the sites was running a three-week-old version of whatever I just edited.

Two weeks ago I rolled all of that into a single pnpm workspace. Four Astro apps (didof.dev, velocaption.com, speechstudio.ai, linkpreview.ai) plus one shared library (@didof/shared) now live under one packages/ folder, share one lockfile, and can cross-reference each other's source at build time. I'm shipping faster, and the cross-version bugs are gone.

This post is the walkthrough, with every gotcha I actually hit.

Key Takeaways

pnpm-workspace.yaml is a three-line file that declares which folders are part of the workspace. That's the whole mechanism.

workspace:* in a dependency spec points at a sibling package. No publishing, no npm link, no version drift.

Run any script across packages with pnpm --filter <name> <script>. Combine filters for graph-aware builds.

Subpath exports in a sibling's package.json lets another package import just one module (e.g. a registry file) without pulling in the whole site.

The five gotchas at the end of this post cost me roughly four hours combined. All of them are cheap to fix once you know about them.

Why pnpm, Not npm or Yarn

npm workspaces work. Yarn workspaces work. I use pnpm because of how it handles node_modules.

Every package in a pnpm workspace gets its own node_modules folder, but the contents are symlinks into a single content-addressable store at the monorepo root. One copy of React on disk, referenced by every package that depends on React. With four Astro sites each pulling in the same ~800 MB of Astro + Vite + React + Radix + Tailwind, the savings are dramatic:

$ du -sh node_modules          # content store at root
1.2G
$ du -sh packages/*/node_modules  # per-package symlink farms
4.8M    packages/didof.dev/node_modules
3.2M    packages/velocaption.com/node_modules
3.1M    packages/speechstudio.ai/node_modules
2.9M    packages/linkpreview.ai/node_modules

If I had four separate node_modules folders with copies of the same stuff, that's closer to 5 GB. pnpm reduces it to 1.2 GB. On a laptop with 500 GB of storage and a tendency to hoard Docker images, that matters.

The other reason is strict dependency resolution. npm and Yarn will let your code import any package that happens to be in node_modules, including transitive dependencies your project never declared. Everything works locally, everything works in CI, and then one day a parent dependency drops that transitive dep in a minor version bump and your build breaks in production with no diff to blame.

Here's a concrete case I lived with Yarn on the old didof.dev repo. A Vite plugin I used depended on lodash internally. Somewhere in my source I wrote:

import debounce from "lodash/debounce";

I never added lodash to my own package.json. It worked for months. Then the Vite plugin upgraded to lodash-es, dropped the old dep, and my build broke:

Could not resolve "lodash/debounce" from src/hooks/useDebounce.ts

With pnpm, this mistake surfaces the moment you write the import. pnpm's node_modules layout only exposes packages you directly declare — transitive ones are hidden inside .pnpm/. So the first run of pnpm dev after adding that import fails immediately:

[plugin:vite:import-analysis] Failed to resolve import "lodash/debounce" from "src/hooks/useDebounce.ts"

Same error, six months earlier, when it's a two-minute fix (pnpm add lodash) instead of a production incident.

The Layout That Actually Works

content-hub/
├── pnpm-workspace.yaml
├── package.json          # root; devDeps shared across packages
├── pnpm-lock.yaml        # single lockfile for everything
├── scripts/              # monorepo-wide scripts
├── packages/
│   ├── shared/           # @didof/shared: plugins, schemas, utils
│   ├── didof.dev/
│   ├── velocaption.com/
│   ├── speechstudio.ai/
│   └── linkpreview.ai/
└── .gitignore

Every package has its own package.json, astro.config.mjs, tsconfig.json, src/, and dist/. The root package.json is a thin shell that holds monorepo-wide dev tooling (tsx, typescript, sharp, glob) and a handful of scripts that delegate into packages:

{
  "scripts": {
    "dev:didof": "pnpm --filter didof.dev dev",
    "dev:velocaption": "pnpm --filter velocaption.com dev",
    "build:all": "pnpm -r build",
    "sync": "pnpm tsx scripts/content-sync.ts",
    "ship:didof": "pnpm --filter didof.dev ship",
    "ship:velocaption": "pnpm --filter velocaption.com ship"
  }
}

The pattern repeats for every workspace member: one dev:<name> and one ship:<name> per site. Cross-site commands (build:all, sync) stay unqualified since they operate on the graph.

No clever turbo orchestration. Just pnpm filters. For four sites that mostly build independently, Turborepo would be over-engineering.

pnpm-workspace.yaml: The Three-Line File That Starts It All

This is the entire contents of pnpm-workspace.yaml at the repo root:

packages:
  - "packages/*"

That's the whole mechanism. Anything matching that glob is a workspace member. When I cloned linkpreview.ai into packages/linkpreview.ai/ and ran pnpm install, pnpm discovered it, linked its declared deps, and exposed it under its declared package name. No further registration needed.

The packages key accepts multiple globs if you want more specific grouping (apps/*, libs/*, tooling/*). For a flat layout one glob is enough.

Sharing Code: `workspace:*`

The shared library lives at packages/shared/ with this identity:

{
  "name": "@didof/shared",
  "version": "0.0.1"
}

Any site that wants to use it declares a dependency with the workspace:* protocol:

{
  "name": "didof.dev",
  "dependencies": {
    "@didof/shared": "workspace:*"
  }
}

The * means "whatever version is in the workspace right now." On pnpm install, pnpm creates a symlink from packages/didof.dev/node_modules/@didof/shared pointing at packages/shared/. Edits in shared show up instantly in every consumer: no rebuild, no publish, no npm link of the day.

When you actually publish the workspace (say, releasing @didof/shared to npm for public consumption), pnpm rewrites workspace:* to the real version number at pack time. The published package.json looks normal to any consumer outside the workspace. Inside the workspace, development stays symlinked.

Here's what packages/shared/package.json's exports map looks like in practice:

{
  "name": "@didof/shared",
  "exports": {
    ".": "./index.ts",
    "./plugins": "./plugins/index.ts",
    "./schemas": "./schemas/index.ts",
    "./astro-config-base": "./astro-config-base.ts",
    "./components/CodeBlockScript.astro": "./components/CodeBlockScript.astro",
    "./styles/codeblock.css": "./styles/codeblock.css"
  }
}

Consumers import specific entrypoints:

import { baseBlogSchema } from "@didof/shared/schemas";
import { codeblockCopyTransformer } from "@didof/shared/plugins";
import "@didof/shared/styles/codeblock.css";

Each subpath maps to a specific file. You keep the barrel-import ergonomics without pulling the whole library into a bundle when only one piece is needed.

Setting Up the Workspace From Scratch

If you're starting from zero (or consolidating existing repos the way I did), the bootstrap is maybe a dozen commands. Here's the full sequence.

Create the root and init a package:

mkdir content-hub && cd content-hub
pnpm init
git init

Declare which folders are workspace members:

cat > pnpm-workspace.yaml <<'EOF'
packages:
  - "packages/*"
EOF

Move each existing project into packages/<name>. For a greenfield package, mkdir packages/<name> and pnpm init inside it. Either way pnpm discovers them on the next install.

mkdir packages
mv ../didof.dev packages/
mv ../velocaption.com packages/
# ... one mv per project

Every moved project keeps its own package.json, but its individual pnpm-lock.yaml and node_modules are obsolete. Clean them so the monorepo-root lockfile takes over:

rm -rf packages/*/node_modules packages/*/pnpm-lock.yaml

Install everything from the new root:

pnpm install

Verify pnpm found every package:

pnpm -r ls --depth -1

That prints each workspace member with its declared dependencies. If a package is missing, check that its package.json sits directly in packages/<name>/, not nested inside another folder.

From here, workspace:* references resolve automatically, --filter scripts work, and shared dev tooling goes at the root:

pnpm add -D -w typescript tsx sharp

That's the entire bootstrap. Fewer moving parts than most single-project setups.

Running Scripts with `--filter`

The --filter flag is where most of my daily work happens. A few patterns that earn their keep:

Run dev on one site:

pnpm --filter didof.dev dev

Build every package in topological order (respects workspace:* deps):

pnpm -r build

pnpm sees that didof.dev depends on @didof/shared and builds shared first. If you swap pnpm for npm workspaces you'd need to orchestrate this yourself or rely on a runner like Turborepo.

Run a command in every package that matches a pattern:

pnpm --filter "./packages/*" check

Add a dependency to a specific package:

pnpm --filter didof.dev add @radix-ui/react-dialog

Add a root-level dev dependency (the -w flag for workspace root):

pnpm add -D -w sharp

That last one is the first gotcha I hit. More on that below.

Subpath Exports Across Packages

Here's where monorepos start earning their keep for real.

packages/velocaption.com/ has a tool registry at src/features/tools/registry.ts that exports a TOOL_REGISTRY object with 16 entries. My didof.dev landing page wants to show a subset of those tools as a "Free Tools by Velocaption" section.

Before the monorepo, the only way to do this was to fetch https://velocaption.com/tools/rss.xml at build time, parse the XML, and hope the deployed site was up. Now I add a subpath export to velocaption's package.json:

{
  "name": "velocaption.com",
  "exports": {
    ".": "./...",
    "./tools-registry": "./src/features/tools/registry.ts"
  }
}

Add it as a workspace dep in didof.dev:

{
  "dependencies": {
    "velocaption.com": "workspace:*"
  }
}

Now didof.dev imports the registry directly:

import { TOOL_REGISTRY } from "velocaption.com/tools-registry";

Astro/Vite resolves the TypeScript at build time. No compilation step, no JSON generation, no HTTP request to production. The landing page renders from the same source of truth the velocaption site uses for its own tool pages.

For content that's a little more shape-y (like blog posts with frontmatter), I wrote a small build-time aggregator that globs sibling src/content/blog/*/index.mdx, parses frontmatter, copies cover images into didof.dev's public folder, and emits JSON. The pattern is the same: filesystem reads, not HTTP. Sibling packages are just code and data on disk.

Five Gotchas

These cost me time. They shouldn't cost you any.

1. `pnpm deploy` is a built-in, not your `deploy` script

I wrote a ship npm script that chained pnpm check && pnpm build && pnpm deploy. The pnpm deploy step failed every time with ERR_PNPM_NOTHING_TO_DEPLOY. Took me ten minutes to find out: pnpm deploy is a pnpm subcommand that copies a package's production dependencies somewhere. It doesn't run my deploy npm script.

The fix is pnpm run deploy (explicit script invocation):

{
  "scripts": {
    "deploy": "wrangler pages deploy dist --project-name didof-dev",
    "ship": "pnpm check && pnpm build && pnpm run deploy"
  }
}

Any script name that collides with a pnpm built-in needs pnpm run <name> to disambiguate. The built-in commands to watch out for: deploy, install, add, remove, update, link, pack, publish, start, test. Most of those are obvious (don't override install), but deploy and start are common enough to conflict.

2. `pnpm add` without `-w` puts deps in the wrong place

Running pnpm add sharp from the monorepo root looks like it should add sharp to the root's package.json. It does not. pnpm will refuse, or worse, add it to a random package depending on which directory you're in.

To add to the root:

pnpm add -D -w sharp

The -w is short for --workspace-root. To add to a specific package from anywhere:

pnpm --filter didof.dev add @radix-ui/react-dialog

3. Vite's `fs.allow` narrows when you have multiple Astro apps

After adding linkpreview.ai as a fourth Astro app, running pnpm --filter didof.dev dev started emitting this:

[vite] The request url ".../node_modules/.pnpm/astro@.../dist/runtime/client/dev-toolbar/entrypoint.js" is outside of Vite serving allow list

Vite's dev server has an allowlist of paths it's willing to serve files from. With one Astro app in a repo, it correctly detects the project root and includes the hoisted node_modules/.pnpm/ store two levels up. With multiple sibling Astro apps, the auto-detection gets narrower and excludes the store, which breaks Astro's own dev toolbar.

Fix: explicitly tell Vite the whole monorepo is fair game, in each Astro app's config:

import { fileURLToPath } from "node:url";
import { dirname, resolve } from "node:path";

const MONOREPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "../..");

export default defineConfig({
  vite: {
    server: {
      fs: {
        allow: [MONOREPO_ROOT],
      },
    },
  },
});

4. Native-binding packages need `approve-builds`

Packages like sharp, esbuild, and @mediapipe/hands ship native binaries that install via postinstall scripts. pnpm 10+ blocks those scripts by default for security. The first time you try to use sharp, it errors with "postinstall was skipped."

Fix: run pnpm approve-builds once and pick the packages you trust. pnpm records them in your .npmrc or package.json so future installs run their postinstalls automatically.

5. `workspace:*` does not work for dynamic `import()` from Node scripts

My build scripts do await import("velocaption.com/tools-registry") at build time. With Vite handling the import, the workspace resolution works. With a plain Node tsx script running outside Vite's resolution, it does not: Node's module resolver has no idea what velocaption.com is.

Fix for build scripts that need to reach into sibling packages: resolve absolute paths with node:path and use pathToFileURL:

import { resolve } from "node:path";
import { pathToFileURL } from "node:url";

const registryPath = resolve(
  __dirname,
  "../../velocaption.com/src/features/tools/registry.ts",
);
const mod = await import(pathToFileURL(registryPath).href);
const registry = mod.TOOL_REGISTRY;

This gives up the package-name aliasing but works from any Node context. For scripts that only run through Vite (e.g. inside Astro pages), stick with workspace:* imports.

When to Reach for Turborepo or Nx

I don't use either, and I've been happy with plain pnpm workspaces for four apps. But there's a threshold.

Turborepo earns its keep when:

You have so many packages that topological ordering alone isn't enough and you need smart caching of build outputs across runs
CI needs to skip rebuilds of packages whose source files haven't changed
You want a built-in dependency graph visualizer

Nx earns its keep when you're in a strongly-typed polyglot monorepo (TypeScript plus Python plus Go) or when your team wants generators to scaffold new packages with the same shape.

For "four websites plus a shared lib, all in TypeScript, built independently," pnpm workspaces is the correct tool. Don't let FOMO push you onto a bigger runner before you've felt the specific pain it solves.

Troubleshooting

Symptom	Cause	Fix
`ERR_PNPM_NOTHING_TO_DEPLOY` from your `ship` script	`pnpm deploy` is a built-in	Use `pnpm run deploy`
`pnpm add` behaves oddly from the repo root	Missing `-w` flag	`pnpm add -D -w <pkg>` to add to root
Vite dev server warns about `fs.allow`	Multiple Astro apps narrow the allowlist	Add `server.fs.allow: [monorepoRoot]` to each Astro's Vite config
`pnpm install` logs `postinstall was skipped for sharp`	pnpm 10+ security default	`pnpm approve-builds` once
Sibling workspace import fails in a plain Node script	Node module resolver can't see workspace: links	`pathToFileURL(resolve(__dirname, "..."))` for dynamic import
Cross-package type imports not resolving	Missing `exports` map on the sibling's package.json	Add subpath exports, reimport

Frequently Asked Questions

Should I use pnpm workspaces for a two-package repo?

Yes, even for two. The overhead is a three-line YAML file. The payoff is a single lockfile, cross-package references via workspace:*, and the ability to grow without restructuring. Two becomes four becomes seven, and you don't want to be migrating your dep model at that point.

Do I need to publish `@didof/shared` to npm for the workspace to work?

No. Workspace dependencies resolve through local symlinks at install time. Publishing is only needed when consumers outside the workspace want to pull your shared library. All the code in this post runs entirely locally with no registry round-trip.

What about CI? Does pnpm workspace break GitHub Actions?

Not at all. The pnpm/action-setup GitHub Action handles workspaces out of the box. One pnpm install at the root resolves the entire graph. Your CI steps become pnpm --filter <package> build or pnpm -r test.

Can I have different TypeScript versions per package?

Technically yes, but I wouldn't. Put TypeScript at the root as a devDependency, let every package share the same version, and use per-package tsconfig.json files with extends to differentiate compile options. Version drift across packages creates confusing type errors that are hard to debug.

Does `workspace:*` work with Yarn Berry or npm workspaces?

The workspace:* protocol originated in pnpm and is now supported by Yarn Berry and npm 7+. The filter commands differ: npm uses --workspace=<name>, Yarn uses yarn workspace <name> <cmd>, pnpm uses --filter <name>. The underlying workspace resolution is similar across all three.

Closing

The switch cost me one afternoon of moving files and two additional hours fighting the five gotchas above. It's paid for itself every week since. Shared library edits propagate instantly. Cross-site data flows through direct filesystem reads. Installing dependencies takes seconds because everything's already in the store. Lockfile drift between sites is gone.

If you have more than one related project sharing a codebase, there's probably a pnpm workspace in your future. Start with three lines of YAML.

Remote Terminal: iPhone to Mac via Tailscale

Francesco Di Donato — Sat, 11 Apr 2026 09:07:40 +0000

I wanted to run terminal commands on my Mac from my iPhone. Not through some clunky VNC app. Not by opening SSH ports on my router. I wanted a real terminal, in my pocket, that works from anywhere, without exposing my machine to the internet.

It took five minutes, two free tools, and zero networking knowledge. Here is exactly how.

Key Takeaways

Tailscale creates a private WireGuard tunnel between your devices. No ports opened on your router.

Remobi serves a web terminal via npx. One command, no install.

Binding to your Tailscale IP (not 0.0.0.0) is the difference between "works" and "safe to leave running."

Add it to your iPhone Home Screen and it behaves like a native app.

What Are We Building?

A full terminal running on your Mac, accessible from Safari on your iPhone, encrypted end-to-end, invisible to the public internet. You type commands on your phone, they execute on your Mac. You can be on the same WiFi or on the other side of the planet. It does not matter because the connection goes through a private mesh network, not the internet.

Full blog post on my website.

The stack is two tools:

Tailscale: a free mesh VPN built on WireGuard. It gives each of your devices a private IP address (like 100.x.y.z) and routes traffic between them through an encrypted tunnel. Nothing is exposed to the public internet. No router configuration needed. If you have local services like n8n running on your machine, Tailscale makes them accessible from your phone too.
Remobi: a tiny terminal server you launch with npx. It opens a web-based terminal that you access from any browser. No installation, no accounts.

What You Will Need

A Mac (any recent macOS version)
An iPhone (or iPad, or any device with a browser)
A Tailscale account (free for personal use, up to 100 devices)
Node.js installed on your Mac (for npx)

Total setup time: about five minutes.

Set Up Tailscale on Both Devices

If you already use Tailscale, skip to the next section.

Install Tailscale on your Mac from the website or the App Store.
Install Tailscale on your iPhone from the App Store.
Log in with the same account on both devices.
On your iPhone, toggle the VPN on.

That is it. Both devices are now on the same private network. You can verify by opening Terminal on your Mac and running:

tailscale status

You should see both your Mac and your iPhone listed. Note your Mac's Tailscale IP. It starts with 100. and looks something like 100.122.133.96.

If the tailscale command is not found, add an alias to your shell config:

echo 'alias tailscale="/Applications/Tailscale.app/Contents/MacOS/Tailscale"' >> ~/.zshrc
source ~/.zshrc

Launch the Terminal Server

Here is where most guides get the security wrong.

The obvious command to start Remobi is:

npx remobi@latest serve --host 0.0.0.0

That works. But 0.0.0.0 tells your Mac to listen on every network interface. Your Tailscale tunnel, yes, but also your local WiFi. If you are at a coffee shop, anyone on the same network could theoretically browse to your local IP and get a terminal on your machine.

The fix is simple. Bind Remobi to your Tailscale IP only:

npx remobi@latest serve --host 100.122.133.96

Replace that IP with your actual Tailscale IP from the previous step. Now the terminal server only accepts connections from the private Tailscale network. Someone sitting next to you at Starbucks would not even see it.

Keep this terminal window open. The server runs as long as the process is alive.

Connect From Your iPhone

Make sure Tailscale is active on your iPhone (the VPN toggle in Settings or the Tailscale app).
Open Safari and go to: http://100.122.133.96:7681 (using your Mac's Tailscale IP).
You should see a full terminal. Try ls or pwd to confirm you are on your Mac.

Now the trick that makes this feel native: tap the Share button in Safari, then tap "Add to Home Screen." Give it a name like "Mac Terminal." This creates a PWA-style shortcut that opens in full screen, no browser chrome. It looks and feels like an app.

Mirror the Session With tmux

Remobi runs inside a tmux session called main. This means you can attach to the same session from your Mac and see exactly what your iPhone is doing in real time.

Open a new terminal tab on your Mac and run:

tmux attach -t main

Both screens now show the same session. Type on your phone, it appears on your Mac. Type on your Mac, it appears on your phone. This is useful for debugging: run something from your phone while watching the output on a bigger screen.

On my home WiFi, keystrokes appear instantly. Over LTE from a cafe, I noticed maybe a half-second delay, but for running git commands or restarting services it never mattered.

To detach without killing the session, press Ctrl+B then D.

Keep Your Mac Awake

If your Mac goes to sleep, the Tailscale connection drops and Remobi dies. If you want to leave this running while you are away, you need to prevent sleep.

Option 1: System Settings

Go to System Settings > Displays > Advanced and enable "Prevent automatic sleeping when the display is off." Also check System Settings > Battery > Options and enable "Wake for network access."

Option 2: The caffeinate command

Run this in a separate terminal tab:

caffeinate -s

This keeps the Mac awake as long as the command is running. Kill it with Ctrl+C when you are done.

Option 3: Amphetamine

Amphetamine is a free app from the App Store that gives you fine-grained control over when your Mac stays awake. You can set it to stay awake only while Remobi is running.

How Secure Is This Actually?

Here is the honest breakdown:

Threat	Risk	Why
Random attacker from the internet	None	No ports are open on your router. There is nothing to find.
Someone on the same WiFi	None (if you bound to Tailscale IP)	The server only listens on the private Tailscale interface.
Someone on the same WiFi	Medium (if you used `0.0.0.0`)	They could find your local IP and access the terminal.
Tailscale account compromise	Extremely low	An attacker would need to steal your Tailscale identity.

The key takeaway: bind to your Tailscale IP, not 0.0.0.0. That single flag is the difference between a locked door and an open one.

All traffic between your iPhone and Mac is encrypted with WireGuard, a modern VPN protocol that has been formally verified and adopted by providers like Mullvad, Mozilla VPN, and Cloudflare WARP. Tailscale adds identity-based access control on top. Their security model is well documented.

When you are done, type exit on your phone to close the terminal session, then Ctrl+C on your Mac to stop the Remobi server.

It Works on Linux and Windows Too

Everything in this guide except the sleep prevention steps is OS-agnostic. Tailscale runs on Linux, Windows, and even Raspberry Pi. Remobi is just Node.js.

On Linux, replace the sleep prevention with:

systemd-inhibit --what=idle npx remobi@latest serve --host $(tailscale ip -4)

On Windows, install Tailscale from their website, run npx remobi@latest serve --host <your-tailscale-ip> in PowerShell, and connect from your phone the same way.

The Tailscale IP binding trick works identically on every platform. The private network does not care what OS either end is running.

Frequently Asked Questions

Does this work over mobile data or only on WiFi?

It works everywhere. Tailscale routes traffic through relay servers (called DERP) when a direct connection is not possible. You can be on cellular data on your iPhone and WiFi on your Mac. The connection goes through Tailscale's infrastructure, encrypted end-to-end. Latency is slightly higher over cellular, but for terminal use it is unnoticeable.

Can I use this with an Android phone?

Yes. Tailscale has an Android app. The browser-based terminal works in Chrome on Android the same way it works in Safari on iPhone. You can also add it to your home screen as a PWA.

Is Remobi safe to use? It runs via npx.

Remobi is open source (GitHub) and small enough to audit in an afternoon. It wraps ttyd, a well-known web terminal tool. Running it via npx means you always get the latest version. The security boundary is Tailscale, not Remobi: even if Remobi had a vulnerability, only devices on your Tailnet can reach it.

How K-Means Clustering Works (Explained by Extracting Colors from Images)

Francesco Di Donato — Thu, 09 Apr 2026 08:03:00 +0000

Every color palette extractor you've used runs K-Means clustering. Coolors, Canva, Adobe. They all use the same algorithm to find dominant colors. Most of them run it on a server. Ours runs it on your GPU, entirely in the browser.

We built a free Palette Extractor that processes 65,536 pixels in 12ms using a WebGL2 fragment shader. This post walks through how K-Means works, why color extraction is the perfect demo, and how 15 lines of GLSL turn the GPU into a parallel K-Means engine.

K-Means in 30 Seconds

The algorithm repeats two steps:

Assign every data point to the nearest centroid
Update each centroid to the mean of its assigned points

Loop until nothing changes. For color extraction, data points are pixels (RGB values) and centroids become your palette colors.

It's the most widely used clustering algorithm in ML (IBM), and it scales at O(n).

The Five Steps (With Colors)

Choose K: How many palette colors do you want? K=6 means 6 clusters.

Initialize: Pick K random pixels as starting centroids. Wrong guesses are fine. The algorithm fixes them.

Assign: Every pixel calculates Euclidean distance to every centroid in RGB space. Snaps to the nearest one. For a 256x256 image, that's 65,536 pixels x K centroids = a lot of distance calculations. Per iteration.

Update: Each centroid moves to the average color of its assigned pixels.

Converge: Repeat assign+update until centroids stop moving. Typical images converge in 5-15 iterations.

Why the GPU?

The assignment step is embarrassingly parallel. Each pixel's computation is independent. No pixel needs to know about any other pixel. That's exactly what GPUs do: run thousands of identical programs simultaneously.

When we first tried running K-Means in JavaScript on the CPU, anything above 256x256 was noticeably slow. Moving the assignment step to a WebGL2 fragment shader made it instant.

The Fragment Shader

This is the actual production code. Not pseudocode.

#version 300 es
precision highp float;
uniform sampler2D u_data;       // pixel colors as texture
uniform vec3 u_centroids[32];   // current centroid positions
uniform int u_k;                // number of clusters
uniform int u_numPoints;        // total pixel count
out vec4 outColor;

void main() {
  ivec2 texCoord = ivec2(gl_FragCoord.xy);
  int texWidth = textureSize(u_data, 0).x;
  int idx = texCoord.y * texWidth + texCoord.x;
  if (idx >= u_numPoints) { outColor = vec4(-1.0); return; }

  vec3 pt = texelFetch(u_data, texCoord, 0).rgb;
  float minDist = 999999.0;
  float bestK = -1.0;

  for (int i = 0; i < 32; i++) {
    if (i >= u_k) break;
    float d = distance(pt, u_centroids[i]);
    if (d < minDist) { minDist = d; bestK = float(i); }
  }

  outColor = vec4(bestK, pt.r, pt.g, pt.b);
}

The trick: pixel RGB values are packed into an RGBA32F floating-point texture. The shader runs once per texel, computes distance to each centroid, and outputs the cluster assignment. One drawArrays call processes all 65,536 pixels in parallel.

GPU K-Means achieves 100x+ speedup over CPU at scale (Springer, 2022).

The Hybrid Loop

The full K-Means loop isn't entirely on the GPU. Assignment parallelizes perfectly, but centroid update requires aggregation:

CPU uploads centroid positions as shader uniforms
GPU runs the fragment shader (assignment)
CPU reads results via readPixels (the bottleneck)
CPU accumulates sums per cluster, divides to get new centroids
Repeat until converged

readPixels stalls the pipeline (GPU-to-CPU transfer), but the parallel assignment step more than compensates.

Real Numbers

256x256 image, K=6: 5-8 iterations, 8-15ms
256x256 image, K=12: 8-12 iterations, 15-25ms
Max 50 iterations cap. Never seen an image need more than 20.

Try It

The Palette Extractor is free, runs in any browser with WebGL2 (92% support), and never uploads your images. Drop an image, pick K, get colors.

Full writeup with the interactive K-Means step-by-step visualizer: velocaption.com/blog/k-means-gpu-palette-extractor

We build browser-based tools at Velocaption. Our main product is a desktop video editor for silence removal and auto-captioning. If you're curious about browser performance, we also wrote about how we got 60fps video playback using a similar bypass-the-framework approach.

JSON-LD Structured Data for Blogs: A Real Implementation

Francesco Di Donato — Wed, 08 Apr 2026 07:40:00 +0000

Rich results achieve 82% higher click-through rates compared to standard search listings (Search Engine Journal, 2025). But in 2026, structured data is no longer just about rich snippets. It is how AI systems like Google AI Overviews, ChatGPT, and Perplexity decide whether your content is worth citing. According to Semrush's 2025 AI Overviews study, AI Overviews now appear in over 15% of Google searches, and pages with clear semantic structure are significantly more likely to be cited in those results.

I just added JSON-LD structured data to this very blog. In this post, I will walk through the exact code, the architectural decisions, and the verification steps. No toy examples, just production-ready implementation. If you care about HTTP caching headers or ETags for content freshness, you already understand the value of giving browsers and crawlers explicit signals. JSON-LD structured data does the same thing for search engines and AI systems.

This post is better to read on my website :)

What Is JSON-LD and Why Does Google Recommend It?

JSON-LD (JavaScript Object Notation for Linked Data) is a method of encoding structured data using JSON. Google explicitly states in their developer documentation: "Google recommends using JSON-LD for structured data whenever possible."

There are three formats for structured data on the web:

Microdata: attributes woven into your HTML elements. Tightly coupled to your markup, hard to maintain.
RDFa: similar to Microdata but more verbose. Used by some CMS platforms.
JSON-LD: a standalone <script> block in your <head>. Completely decoupled from your HTML.

JSON-LD wins because it lives separately from your content. You can add, remove, or modify your structured data without touching a single line of your page's HTML. For component-based frameworks like Astro, React, or Next.js, this is the natural choice. Your schema is just another data object.

<script type="application/ld+json">
  {
    "@context": "https://schema.org",
    "@type": "BlogPosting",
    "headline": "Your Article Title",
    "datePublished": "2026-04-07T00:00:00.000Z"
  }
</script>

Which BlogPosting Fields Actually Matter?

The schema.org BlogPosting type has dozens of properties, but not all of them are equal. Here is what Google actually uses for rich results and what AI systems look for when deciding whether to cite you.

Required for rich results:

headline: your article title
datePublished: ISO 8601 format
author: a Person or Organization with at least a name

Strongly recommended:

dateModified: signals freshness. 76% of top AI-cited content was updated within 30 days.
description: helps AI systems understand the article's scope
image: enables visual rich results
url: canonical URL of the article

Good to have:

publisher: for E-E-A-T signals. Can be the same as author for personal blogs.

Do not over-engineer it. A clean schema with the right fields beats a bloated one with properties Google ignores.

How Do You Build a JSON-LD Structured Data Component in Astro?

Here is the actual component I built for this blog. It lives at src/components/seo/json-ld.astro:

---
export interface Props {
  title: "string;"
  description: "string;"
  url: string;
  image?: string;
  datePublished: string;
  dateModified?: string;
  author?: string;
}

const {
  title,
  description,
  url,
  image,
  datePublished,
  dateModified,
  author = "Francesco Di Donato",
} = Astro.props;

const schema = {
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  headline: title,
  description,
  url,
  ...(image && { image }),
  datePublished,
  ...(dateModified && { dateModified }),
  author: {
    "@type": "Person",
    name: author,
    url: "https://didof.dev",
  },
  publisher: {
    "@type": "Person",
    name: author,
    url: "https://didof.dev",
  },
};
---

<script type="application/ld+json" set:html={JSON.stringify(schema)} />

Three things worth noting:

Conditional spreading: ...(image && { image }) only includes the image field when one exists. Same for dateModified. This avoids null or undefined values in your JSON-LD, which can trigger validation warnings.
The set:html directive: Astro's set:html safely injects the JSON string into the script tag. Never use template literals for this. set:html={JSON.stringify(schema)} handles escaping correctly and prevents XSS vectors if any prop contains user-controlled data.
Typed Props: the Props interface ensures TypeScript catches missing required fields at build time, not in production.

How Do You Wire JSON-LD Into Your Layout Conditionally?

The key architectural decision: JSON-LD should only render on blog posts, not on every page. The homepage, about page, and tools pages do not need BlogPosting schema.

In src/layouts/main.astro, I added an optional schema prop:

export interface Props {
  title?: string;
  description?: string;
  image?: string;
  footer?: boolean;
  header?: boolean;
  disableFloatingCal?: boolean;
  schema?: {
    datePublished: string;
    dateModified?: string;
  };
}

Then in the <head>, the component renders conditionally:

{schema && (
  <BlogJsonLd
    title={title || "didof.dev"}
    description={description}
    url={canonicalURL.toString()}
    image={new URL(image, Astro.site).toString()}
    datePublished={schema.datePublished}
    dateModified={schema.dateModified}
  />
)}

The blog post page (src/pages/[locale]/blog/[...slug].astro) passes the schema data from the content collection:

<Main
  title={post.data.title}
  description={post.data.description}
  image={ogImage?.src}
  schema={{
    datePublished: post.data.date.toISOString(),
    dateModified: post.data.update_date?.toISOString(),
  }}
>

Every blog post now gets structured data automatically. No manual JSON-LD per post, no forgetting to add it. If update_date is not set in the frontmatter, dateModified simply does not appear in the schema. Exactly the behavior we want.

How Do You Verify JSON-LD Structured Data Is Working?

After building, you can verify JSON-LD is present in the output:

# Check that blog posts contain JSON-LD
grep -l "application/ld+json" dist/en/blog/*/index.html | head -5

# Inspect the actual schema for one post
grep -o '<script type="application/ld+json">[^<]*</script>' \
  dist/en/blog/setup-n8n-and-searxng-locally/index.html  # any post works

The output should be valid JSON with @type: "BlogPosting", your headline, datePublished, and author fields.

For production validation, use two tools:

Schema Markup Validator: paste your URL to check for schema.org compliance
Google Rich Results Test: shows what Google can extract and whether you qualify for rich results

Why Does JSON-LD Structured Data Matter for AI Search in 2026?

Structured data is no longer optional SEO polish. It is infrastructure for AI visibility.

When Google AI Overviews, ChatGPT web search, or Perplexity crawl your page, they are trying to answer three questions:

What is this content about? headline, description, @type
Is it trustworthy? author, publisher, datePublished, dateModified
Is it current? dateModified is the strongest freshness signal

Without structured data, AI systems have to guess these answers from your HTML. With it, you are handing them the answers directly, in a format they are designed to consume.

JSON-LD structured data can increase your click-through rate by 35% even without a visual rich result, because search engines understand your content better and rank it more confidently. If you are building tools that interact with APIs, like setting up n8n and SearXNG locally, adding structured data helps those pages get discovered by the same AI systems you are building with.

FAQ

Do I need a separate JSON-LD block for each blog post?

No. With the component approach shown above, every blog post automatically gets its own JSON-LD block generated from the content collection data. You write the component once and it scales to every post.

Does JSON-LD affect page performance?

No measurable impact. The JSON-LD script block is a few hundred bytes of text. It does not execute as JavaScript. The browser ignores type="application/ld+json" scripts entirely. Only search engines and AI crawlers parse them.

Should I use the `astro-seo-schema` npm package instead?

It depends. The astro-seo-schema package provides TypeScript definitions from schema-dts, which gives you autocomplete for every schema.org property. For a simple BlogPosting schema, a hand-rolled component like the one above is lighter and gives you full control. For complex schemas with multiple nested types, the package can help prevent mistakes.

What about FAQ schema on this very page?

Google deprecated HowTo rich results in September 2023, but FAQPage schema remains supported. Google now shows FAQ rich results less frequently though. The value of FAQ sections in 2026 is primarily for AI citation: question-answer formats are the easiest structure for AI systems to extract and cite.

How to Use a Reverse Trie for Fast Disposable Email Domain Detection

Francesco Di Donato — Fri, 06 Dec 2024 11:25:36 +0000

Learn how to use a reverse Trie to efficiently detect disposable email domains. Optimize your domain lookups with a scalable, memory-efficient solution tailored for fast and precise results.

Read the article on my website
Use the Free Disposable Email Domain Detector

Disposable emails can cause issues like fake signups and spam. The user grabs an address from one of thousands of temporary email generators and hands it over. Not even the GOAT of email regex can save you here.

Personally, I find having a big list of all disposable email domains is the easiest yet most effective solution. But before you assemble that list and start a for ... of loop to check against it, think of the O(n) complexity!

A great way to identify them is by using a reverse Trie, an efficient data structure for fast lookups.

What Is a Reverse Trie?

First, let's grasp what a Trie is. It is a data structure where strings are:

chopped up, char per char
assembled in a tree structure

example, if we feed boa, bro, brie, it would assemble them using Map as:

b
 ├── o ── a
 └── r ── o  
     └─── i ── e

This approach allows direct lookups without cycling through the entire list. Each character guides the search deeper.

It trades memory for efficiency. The time it takes to find the string does not depend on the size of the list, but on the length of the string!

A reverse Trie stores strings in reverse order, ideal for domains:

mailinator.com becomes moc.rotanliam
trashmail.com becomes moc.liambhsart

Note on This Implementatin

By reversing domains, searches start at the TLD (e.g., .com), which is shared across many domains. To optimize further, it stores TLDs as a single key (com), rather than splitting them into characters. The rest of the domain follows a standard Trie structure.

Reverse Trie Domains Implementation

Since this is a tree structure, each node will reference its children:

type TrieNode = Map<string, TrieNode>;

First, a utility function to split the TLD from the rest of the domain:

private splitTLDFromRest(input: string) {
    const dot = input.lastIndexOf('.');
    const TLD = input.substring(dot + 1);
    const rest = input.substring(0, dot);
    return [TLD, rest];
}

Using lastIndexOf ensures subdomains like foo.bar.baz.com are handled correctly.

Next, the constructor will assemble the Trie:

export class ReverseTrieDomains {
    private root: TrieNode = new Map();

    // ...

    constructor(...domains: string[]) {
        for (const domain of domains) {
            // For "didof.dev"
            const [TLD, rest] = this.splitTLDFromRest(domain);
            // dev, didof

            // Keep the refence to the TLD node for final set
            let node = this.root.get(TLD);
            if (!node) node = new Map();

            // Start from TLD node, walk along the string in reverse
            let currentNode: TrieNode = node;
            for (let i = rest.length - 1; i >= 0; i--) {
                const char = rest[i];
                let childNode = currentNode.get(char);
                if (!childNode) {
                    childNode = new Map();
                    currentNode.set(char, childNode);
                }
                currentNode = childNode;
            }

            this.root.set(TLD, node);
        }
    }
}

To check if a domain is disposable, traverse the Trie:

export class ReverseTrieDomains {
    // ...

    public has(domain: string) {
        const [TLD, rest] = this.splitTLDFromRest(domain)

        const node = this.root.get(TLD)
        if (!node) return false

        let currentNode: TrieNode = node
        let isFullDomainFound = false
        for (let i = rest.length - 1; i >= 0; i--) {
            const char = rest[i]
            const childNode = currentNode.get(char)
            if (!childNode) return false
            currentNode = childNode
            if (i === 0) {
                isFullDomainFound = currentNode.size === 0;
            }
        }

        return isFullDomainFound
    }
}

Conclusion

Using a reverse Trie offers several benefits:

Fast Lookups: Traverse characters step-by-step for quick results.
Memory Efficiency: Common suffixes like .com are stored only once.
Scalability: Handles large domain lists effortlessly.

If you’re dealing with disposable emails, this is a smart, scalable solution to implement.

Throttling Explained: A Guide to Managing API Request Limits

Francesco Di Donato — Wed, 04 Dec 2024 18:15:00 +0000

When Should You Implement Throttling in Your Code?

For big projects, it’s usually best to use tools like Cloudflare Rate Limiting or HAProxy. These are powerful, reliable, and take care of the heavy lifting for you.

But for smaller projects—or if you want to learn how things work—you can create your own rate limiter right in your code. Why?

It’s Simple: You’ll build something straightforward that’s easy to understand.
It’s Budget-Friendly: No extra costs beyond hosting your server.
It Works for Small Projects: As long as traffic is low, it keeps things fast and efficient.
It’s Reusable: You can copy it into other projects without setting up new tools or services.

What You Will Learn

By the end of this guide, you’ll know how to build a basic throttler in TypeScript to protect your APIs from being overwhelmed. Here’s what we’ll cover:

Configurable Time Limits: Each blocked attempt increases the lockout duration to prevent abuse.
Request Caps: Set a maximum number of allowed requests. This is especially useful for APIs that involve paid services, like OpenAI.
In-Memory Storage: A simple solution that works without external tools like Redis—ideal for small projects or prototypes.
Per-User Limits: Track requests on a per-user basis using their IPv4 address. We’ll leverage SvelteKit to easily retrieve the client IP with its built-in method.

This guide is designed to be a practical starting point, perfect for developers who want to learn the basics without unnecessary complexity. But it is not production-ready.

Before starting, I want to give the right credits to Lucia's Rate Limiting section.

Throttler Implementation

Let’s define the Throttler class:

export class Throttler {
    private storage = new Map<string, ThrottlingCounter>();

    constructor(private timeoutSeconds: number[]) {}
}

The Throttler constructor accepts a list of timeout durations (timeoutSeconds). Each time a user is blocked, the duration increases progressively based on this list. Eventually, when the final timeout is reached, you could even trigger a callback to permanently ban the user’s IP—though that’s beyond the scope of this guide.

Here’s an example of creating a throttler instance that blocks users for increasing intervals:

const throttler = new Throttler([1, 2, 4, 8, 16]);

This instance will block users the first time for one second. The second time for two, and so on.

We use a Map to store IP addresses and their corresponding data. A Map is ideal because it handles frequent additions and deletions efficiently.

Pro Tip: Use a Map for dynamic data that changes frequently. For static, unchanging data, an object is better. (Rabbit hole ¹)

When your endpoint receives a request, it extracts the user's IP address and consults the Throttler to determine whether the request should be allowed.

How it Works

Case A: New or Inactive User

If the IP is not found in the Throttler, it’s either the user’s first request or they’ve been inactive long enough. In this case:
- Allow the action.
- Track the user by storing their IP with an initial timeout.
Case B: Active User

If the IP is found, it means the user has made previous requests. Here:
- Check if the required wait time (based on the timeoutSeconds array) has passed since their last block.
- If enough time has passed:
- Update the timestamp.
- Increment the timeout index (capped to the last index to prevent overflow).
- If not, deny the request.

In this latter case, we need to check if enough time is passed since last block. We know which of the timeoutSeconds we should refer thank to an index. If not, simply bounce back. Otherwise update the timestamp.

export class Throttler {
    // ...

    public consume(key: string): boolean {
        const counter = this.storage.get(key) ?? null;
        const now = Date.now();

        // Case A
        if (counter === null) {
            // At next request, will be found.
            // The index 0 of [1, 2, 4, 8, 16] returns 1.
            // That's the amount of seconds it will have to wait.
            this.storage.set(key, {
                index: 0,
                updatedAt: now
            });
            return true; // allowed
        }

        // Case B
        const timeoutMs = this.timeoutSeconds[counter.index] * 1000;
        const allowed = now - counter.updatedAt >= timeoutMs;
        if (!allowed) {
            return false; // denied
        }

        // Allow the call, but increment timeout for following requests.
        counter.updatedAt = now;
        counter.index = Math.min(counter.index + 1, this.timeoutSeconds.length - 1);
        this.storage.set(key, counter);

        return true; // allowed
    }
}

When updating the index, it caps to the last index of timeoutSeconds. Without it, counter.index + 1 would overflow it and next this.timeoutSeconds[counter.index] access would result in a runtime error.

Endpoint example

This example shows how to use the Throttler to limit how often a user can call your API. If the user makes too many requests, they’ll get an error instead of running the main logic.

const throttler = new Throttler([1, 2, 4, 8, 16, 30, 60, 300]);

export async function GET({ getClientAddress }) {
    const IP = getClientAddress();

    if (!throttler.consume(IP)) {
        throw error(429, { message: 'Too Many Requests' });
    }

    // Read from DB, call OpenAI - do the thing.

    return new Response(null, { status: 200 });
}

Note for Authentication

When using rate limiting with login systems, you might face this issue:

A user logs in, triggering the Throttler to associate a timeout with their IP.
The user logs out or their session ends (e.g., logs out immediately, cookie expires with session and browsers crashes, etc.).
When they try to log in again shortly after, the Throttler may still block them, returning a 429 Too Many Requests error.

To prevent this, use the user’s unique userID instead of their IP for rate limiting. Also, you must reset the throttler state after a successful login to avoid unnecessary blocks.

Add a reset method to the Throttler class:

export class Throttler {
    // ...

    public reset(key: string): void {
        this.storage.delete(key);
    }
}

And use it after a successful login:

const user = db.get(email);

if (!throttler.consume(user.ID)) {
    throw error(429);
}

const validPassword = verifyPassword(user.password, providedPassword);
if (!validPassword) {
    throw error(401);
}

throttler.reset(user.id); // Clear throttling for the user

Managing Stale IP Records with Periodic Cleanup

As your throttler tracks IPs and rate limits, it's important to think about how and when to remove IP records that are no longer needed. Without a cleanup mechanism, your throttler will continue to store records in memory, potentially leading to performance issues over time as the data grows.

To prevent this, you can implement a cleanup function that periodically removes old records after a certain period of inactivity. Here's an example of how to add a simple cleanup method to remove stale entries from the throttler.

export class Throttler {
    // ...

    public cleanup(): void {
        const now = Date.now()

        // Capture the keys first to avoid issues during iteration (we use .delete)
        const keys = Array.from(this.storage.keys())

        for (const key of keys) {
            const counter = this.storage.get(key)
            if (!counter) {
                // Skip if the counter is already deleted (handles concurrency issues)
                return
            }

            // If the IP is at the first timeout, remove it from storage
            if (counter.index == 0) {
                this.storage.delete(key)
                continue
            }

            // Otherwise, reduce the timeout index and update the timestamp
            counter.index -= 1
            counter.updatedAt = now
            this.storage.set(key, counter)
        }
    }
}

A very simple way (but probably not the best) way to schedule the cleanup is with setInterval:

const throttler = new Throttler([1, 2, 4, 8, 16, 30, 60, 300])
const oneMinute = 60_000
setInterval(() => throttler.cleanup(), oneMinute)

This cleanup mechanism helps ensure that your throttler doesn't hold onto old records indefinitely, keeping your application efficient. While this approach is simple and easy to implement, it may need further refinement for more complex use cases (e.g., using more advanced scheduling or handling high concurrency).

With periodic cleanup, you prevent memory bloat and ensure that users who haven’t attempted to make requests in a while are no longer tracked - this is a first step toward making your rate-limiting system both scalable and resource-efficient.

If you’re feeling adventurous, you may be interested into reading how properties are allocared and how it changes. Also, why not, about VMs optmizations like inline caches, which is particularly favored by monomorphism. Enjoy. ↩

Optimizing Three.js: 4 Key Techniques

Francesco Di Donato — Fri, 29 Nov 2024 13:50:56 +0000

Code can be art. Whether it's in clever syntax, elegant data structures, or refined interactions, there’s beauty only programmers see—and that’s fine.

But code can also create something visually stunning, something everyone can appreciate. This is where tools like Three.js shine. However, Three.js can be heavy, especially when used in a dynamic web page accessed by devices with varying computational power.

If you’re like me, adding multiple Three.js scenes to your site (as I do on didof.dev), you’ll need optimizations. Here are three practical techniques to keep performance in check.

Originally posted on my blog.

Load Scenes Only When Needed

Don’t load a scene if it’s not visible. This applies to any heavy graphical component. The best tool for this is IntersectionObserver, which detects when an element enters the viewport. Here's how I handle it in SvelteKit:

<script lang="ts">
    import { browser } from '$app/environment';
    import { onMount } from 'svelte';

    let ref: HTMLDivElement;
    let download = $state(false);
    if (browser)
        onMount(() => {
            const observer = new IntersectionObserver(([entry]) => {
                if (entry.isIntersecting) {
                    download = true;

                    // we need this once only
                    observer.disconnect();
                }
            });
            // ref has been bound by Svelte since we are in onMount
            observer.observe(ref);

            return () => observer.disconnect();
        });
</script>

<div bind:this={ref}>
    {#if download}
        <!-- let SvelteKit handle the code splitting -->
        {#await import('./three-scene.svelte')}
            Loading
        {:then module}
            <module.default />
        {:catch error}
            <div>{error}</div>
        {/await}
    {/if}
</div>

Pause Scenes Out of View

If a scene isn’t visible, stop rendering it. Most tutorials focus on a single fullscreen scene, but for sites with multiple scenes, pausing hidden ones saves resources.

Here’s a snippet using IntersectionObserver to control a scene’s animation loop:

function tick() {
    const elapsedTime = clock.getElapsedTime();

    // Update your scene (e.g. set uniforms, move/rotate geometries...)

    renderer.render(scene, camera);
}

// Start the rendering
renderer.setAnimationLoop(tick);

Once again, our friend IntersectionObserver comes to our aid.

let clock: THREE.Clock;
let renderer: THREE.WebGLRenderer;

if (browser)
    onMount(() => {
        const observer = new IntersectionObserver(([entry]) => {
            if (entry.isIntersecting) {
                clock.start();
                renderer.setAnimationLoop(tick); // resume
            } else {
                clock.stop();
                renderer.setAnimationLoop(null); // pause
            }
        });
        observer.observe(canvas);

        // Scene setup...

        return () => {
            observer.disconnect();

            // Other cleanup...
        };
    });

Adjust Shader Workload for Viewport Size

Devices with smaller screens are often less powerful. Adapt your shader’s computational workload accordingly. For example, reduce the number of octaves used in a fractal shader based on the viewport width:

from the browser...

<script lang="ts">
    import ThreeScene from "./three-scene.svelte";
    import { browser } from '$app/environment';

    const octaves = browser ? (window.innerWidth <= 680 ? 2 : 4) : 1
</script>

<ThreeScene {octaves} />

...through three.js...

const material = new THREE.ShaderMaterial({
    vertexShader,
    fragmentShader,
    uniforms: {
        uOctaves: new Three.Uniform(octaves) // coming as $prop
    }
});

...finally, in the shader.

uniform float uOctaves;

for(float i = 0.0; i <= uOctaves; i++)
{
    elevation += simplexNoise2d(warpedPosition * uPositionFrequency * pow(2.0, i)) /  pow(2.0, i + 1.0);
}

This approach dynamically balances performance and visual quality.

Let the Browser Handle Clean up

Here’s where things get tricky. Three.js doesn’t automatically clean up memory, and you need to manually track and dispose of objects like geometries, textures, and materials. If you skip this, memory usage grows every time you navigate away and back, eventually crashing the browser.

Let me share what I observed on my homepage:

Initial memory usage: 22.4MB

After soft-navigation to another page: 28.6MB (even though that page was static HTML).

After repeated navigation back and forth: Memory usage kept climbing until the browser crashed.

Why? Because Three.js objects weren’t being disposed of properly. And despite extensive research, I couldn’t find a reliable way to fully clean up memory in modern frameworks.

Here’s the simplest solution I found: force a hard-reload when leaving pages with Three.js scenes. A hard-reload lets the browser:

Create a new page context.
Perform garbage collection on the old page (leaving cleanup to the browser).

In SvelteKit, this is easy with data-sveltekit-reload. Just enable it for pages with scenes:

homepage's +server.page.ts

export function load() {
    return {
        sveltekitReload: true
    }
}

For navigation links, pass this value dynamically:

<script lang="ts">
    import { page } from '$app/stores';
</script>

<a href="/docs" data-sveltekit-reload={$page.data.sveltekitReload}>Docs</a>

If you use a generic <Link> component, you only need to implement this once.

This approach isn’t perfect—it disables smooth client-side routing for specific pages—but it keeps memory in check and prevents crashes. For me, that trade-off is worth it.

Final Thoughts

These optimizations have worked well for me, but the question remains: how do we properly clean up Three.js objects in modern frameworks? If you’ve found a reliable solution, I’d love to hear from you!

Radial Gradient Generator

Francesco Di Donato — Thu, 28 Nov 2024 12:37:09 +0000

After over five years in the IT industry, I've accumulated a wealth of internal tools and resources that I believe could benefit others. To share this knowledge, I've decided to launch a dedicated section on my personal website.

Today, I'm excited to introduce the Radial Gradient Generator—a simple, web-based tool that allows you to create stunning radial gradients effortlessly.

Go to Radial Gradient Generator

What it offers

Stackable Shades

Add as many shades as you like to create complex gradients.

Customizable Options

Define the color, position, and blur for each shade to achieve your desired look.

Easy Integration

With just one click, you can copy your gradient and paste it directly into your website. There are no dependencies of course.

Examples

These gradients serve as perfect placeholders or can be used to enhance your designs. I left some examples on my website.

Feel free to use the Radial Gradient Generator and let me know your thoughts! Your feedback is invaluable as I continue to improve this tool and share more resources in the future.

How to have Perfect Contrast of Text Color on Any Background in TailwindCSS

Francesco Di Donato — Fri, 17 May 2024 10:11:40 +0000

You can read the interactive version of this blog post!

The Problem

In recent years I have developed a good number of websites. The basic structure is usually similar among them, but there are some tasks that always require a lot of effort. And, coincidentally, they are precisely the most tedious and complicated ones. Especially styling and choosing the colors of the website.

There are quite a few palette generators around the web, but all of them leave you with just a bunch of hexs and rgbs — it’s up to you to join those into your system.

As if managing a theme was not enough, you were perhaps required to add the dark mode! The TailwindCSS team proposes to do this by wandering around the template, adding classes prefixed with dark: to instruct each element about its appearance when the selected theme is dark.

This is imho not optimal since, in addition to bloating the template even more, it would require manual work should I be asked to change some colors. And what if I want a third or even fourth theme?

The Real Problem

I’ve been living with this problem peacefully until, after spending too many days hunting for html tags to slightly change their shades, I realized that, alas, the text was no longer readable - it lacked contrast.

Lighthouse accessibility check, unconcerned about my emotional state, lowered the score.

I don’t want to have to think about this problem anymore.

The Solution

I have come up with a system that allows for an unlimited number of themes, each with an unlimited amount of colors. Most importantly, that ensures that the text is always readable on any color.

Basic usage involves configuring at least two themes, light mode and dark mode.

Each theme requires at least five colors. They are background, neutral (useful for card backgrounds), primary, secondary and accent.

No one is stopping you from adding others like success, warning, error… you name it — it is completely configurable!

For each of them, the TailwindCSS utilities and components are produced and available. It means you can not only add a bg-secondary-300 here and a border-t-neutral-500 there, but you get fancy stuff for free — IDE autocomplete included:

<div class="bg-gradient-to-br
  from-primary-300 via-accent-500 to-secondary-700
  shadow-accent-500"
/>

Text perfect contrast

Thanks to a simple plugin (no need to install anything), some contrast dedicated classes are generated (and available in the IDE autocomplete). They follow the pattern text-wacg-<color>-<shade>.

You can try real-time widgets on my blog post!

<div class="bg-primary-500 text-wacg-primary-500">
    This text will always be readable
</div>

This is easily obtainable with my free online tool.

Benefits

Read more about the other convenient benefits:

Framework agnostic

It is adoptable in any framework: React, Next.js, Vue, Nuxt, Angular, Svelte, SvelteKit, Sapper, Laravel, Spring, Rails, Django, Express, Hugo, Solid.js, Astro.js, Preact, Ember.js, Alpine.js, LitElement, JQuery and any other I may have omitted.

Zero dependencies

I have opted for a dependency-free solution. As a developer, I do not like to install packages unless it is strictly necessary. Mainly because I know how dangerous it can be — supply chain attack gettin’ real!

This solution is not a black box, and a few paragraph below you can appreciate how simple yet powerful it is.

CSS Only

This solution minimizes JavaScript usage at runtime, leveraging CSS for the majority of heavy lifting.

IDE autocomplete

All the palette colors are utilized to generate all the TailwindCSS utilities (bg-primary-500, border-l-neutral-300, etc…), complete with IDE autocompletion. Additionally, any unused elements are purged by TailwindCSS, ensuring they are not present in the final CSS output.

Browser support

The system is based on two CSS features:

var, which allows the declaration and usage of cascading variables in stylesheets, has support on 97.32% of browsers.
calc, which allows to calculate values directly into CSS, is supported in 98.19% of all browsers. Stay tuned to learn how it works — otherwise you can already use the free online tool.

FaQ

Q: Why do I have to explicitly set the text-wacg class? Couldn’t it be implicit in the background one?

A: It could, but I learned to appreciate explicitness.

Web Perf - Large Files

Francesco Di Donato — Tue, 28 Nov 2023 16:30:00 +0000

When you have a lot of information to show on the screen, there are two common choices:

pagination
streaming

But you know what? You can also just send the whole thing to the user. Let's explore this straightforward approach together.

Headers

We'll explore three crucial headers - Content-Length, Content-Encoding, and Transfer-Encoding - and see how different combinations of these headers can influence the rendering on the browser.

`Content-Length`

It specifies the size of the payload in bytes. It helps the recipient (in our case, the browser) know how much data to expect. It's like a heads-up, ensuring everyone is on the same page about the amount of content coming their way.

`Content-Encoding`

It tells the browser how the content is encoded or compressed. It's like a secret code that both the server and the browser understand. Common encodings include gzip and deflate. When the browser sees this header, it knows how to decode the content for a smooth display.

`Transfer-Encoding`

This less-known header handles the encoding of the message itself during transmission. It can be sent all at once (like a single big parcel) or in smaller pieces (like breaking it into multiple smaller packages).

Server

To see how the browser reacts to different combinations of these headers, let's set up a basic Node.js HTTP server.

The server is designed to handle incoming requests for any path, offering flexibility through optional query parameters:

content-length: If set to true, this parameter adds the Content-Length header to the response.
transfer: This parameter sets the Transfer-Encoding header, with options for:
- identity: Instruct the server to send the document as a whole.
- chunked: Directs the server to send the document in chunks.
gzip: If set to true, the server retrieves the zipped version of the file. In this case, the Content-Length (if set) reflects the size of the zipped version.

Support Code

index.mjs

import { createServer } from "http";
import { getView, combinations } from "./src/utils.mjs";

createServer(async (req, res) => {
  const { searchParams: sp } = new URL(req.url, "http://127.0.0.1:8000");

  // Ready query params
  const length = sp.get("content-length") === "true" || false;
  const gzip = sp.get("gzip") === "true" || false;
  const identity = sp.get("identity") === "true" || false;

  // Either index.html or index.html.gz
  let view = "index.html";
  if (gzip) view += ".gz";

  const [data, stats, _] = await getView(view);

  res.setHeader("Content-Type", "text/html");

  if (length) res.setHeader("Content-Length", stats.size);

  if (gzip) res.setHeader("Content-Encoding", "gzip");

  if (identity) res.setHeader("Transfer-Encoding", "identity")

  return res.writeHead(200).end(data);
}).listen(8000, "127.0.0.1", () => {
  console.info(combinations().join("\n"));
});

src/utils.mjs

import { resolve } from "path";
import { readFile, stat } from "fs/promises";

const root = resolve(new URL(".", import.meta.url).pathname, "..");

export async function getView(name, encoding) {
  const filepath = resolve(root, "src", "views", name);

  const [data, stats] = await Promise.allSettled([
    readFile(filepath, encoding),
    stat(filepath),
  ]);
  if (data.status === "rejected")
    return [null, null, new Error("could not retrieve data")];
  if (stats.status === "rejected")
    return [null, null, new Error("could not retrieve stats")];

  return [data.value, stats.value, null];
}

// Ignore if not running on your machine.
export function createURL(
  { gzip, length, identity } = {
    gzip: false,
    length: false,
    identity: false,
  }
) {
  // Use pathname so that in Developer Tools you can filter out the favicon.
  const url = new URL("big", "http://127.0.0.1:8000");
  if (gzip) url.searchParams.set("gzip", "true");
  if (length) url.searchParams.set("content-length", "true");
  if (identity) url.searchParams.set("identity", "true");
  return url.toString();
}

// Ignore if not running on your machine.
export function combinations() {
  const urls = [createURL()];
  for (const gzip of [false, true]) {
    for (const length of [false, true]) {
      for (const identity of [false, true]) {
        urls.push(
          createURL({
            gzip,
            length,
            identity,
          })
        );
      }
    }
  }
  return urls;
}

The content within the HTML files is not the focus; their substantial size is (AKA they're LARGE).

These files are maintained in two versions: plain and gzipped. While it's generally not a recommended practice for real servers to adopt dual storage, here the intent is to avoid introducing additional overhead in the case of zipping.

Testing

I'll now test the server using Firefox, monitoring how response times vary with changes in the headers. If you're following along on your machine, make sure to disable the cache and consider checking the 'Preserve logs' checkbox for a more accurate observation.

Initially, we make a request without query parameters, letting the Node.js HTTP server handle it by default. The default Transfer-Encoding observed is chunked, aligning with the behavior of passing ?transfer=chunked. Node.js aims to be non-blocking, and this choice ensures smoother processing.

Now, let's spice things up by passing the query parameter ?transfer=identity. This time, the request takes notably longer to complete.

To remedy this, we introduce the Content-Length header with ?content-length=true&identity=true, resulting in a significant reduction in duration. It's like mailing a package in one piece. Including the Content-Length header is the friendly note that says, 'Hey, your package is this big!'. Without it, the client might fumble guessing the size, leading to some awkward data processing moments.

🔑 message
In 'identity' mode, be a good server and always attach that Content-Length header.

As a final observation, we note that the presence of the Content-Length has no impact when the transfer method is set to chunked.

🔑 message
Not only there's no need for the Content-Length header`, but using both is actually contradictory.
In 'chunked' encoding, the size of each chunk is self-contained, and a final zero-size chunk does the job of marking the end of the response.

Compression

When using the gzip-compressed resource, the behavior aligns with what we've just explored. In the identity transfer mode, it remains crucial to provide information about the content length, regardless of the content encoding.

Now, let's talk about compression benefits and a trade-off. Opting for gzip compression offers two wins:

it conserves disk storage on your server.
it trims down on bandwidth usage.

However, there's a catch - the browser has to roll up its sleeves and put in a bit more effort to decompress.

If you are interested in Web Performance you definitely need to know about Web Caching (posts series).

Web Caching - Cache-Control max-age, stale-while-revalidate

Francesco Di Donato — Thu, 23 Nov 2023 17:00:00 +0000

Until now, thanks to Last-Modified/If-Modified-Since or ETag/If-None-Match we mainly saved on bandwidth. However, the server always had to process each request.

The server can instruct the client about using the stored resources for a certain duration, deciding if and when the client should revalidate the content and whether or not to do so in the background.

Support code

Real-world endpoints are not as instantaneous as those in this tutorial. The response may take milliseconds to generate, without even considering the location of the server relative to the requester!

Let's exacerbate the asynchronicity between server and client to highlight the need for the Cache-Control Header.

// src/utils.mjs
export async function sleep(duration) {
  return new Promise((resolve) => setTimeout(resolve, duration));
}

Based on the previously implemented /only-etag endpoint, register /cache-control-with-etag. For the time being, it's identical, except that it waits three seconds before responding.
Also, add some log before dispatching the response

export default async (req, res) => {
  console.info("Load on the server!");

  work; // computation;

  await sleep(3000) // simulate async.

  const etag = createETag(html);
  res.setHeader("ETag", etag);
  const ifNoneMatch = new Headers(req.headers).get("If-None-Match");
  if (ifNoneMatch === etag) {
    res.writeHead(304).end();
    return;
  }

  res.writeHead(200).end(html);
};

Let's visualize the problem. When you request a page from the browser, it enters a loading state for three seconds. Even if you refresh within that time, the browser makes the request anew, regardless of the ETag or the Last-Modified mechanisms. The page content persists because you're essentially staying on the same page. To observe the behavior more clearly, try reopening the page from a new tab or starting from a different site.

Most importantly, the server is hit on every request!

max-age

It is possible to instruct the browser to use the cached version for a certain duration. The server will set the Response Header Cache-Control with a value of max-age=<seconds>.

export default async (req, res) => {
  console.info("Load on the server!");

  work; // db retrieval and templating;

  await sleep(3000) // simulate async.

  // Instruct the browser to use the cached resource
  // for 60 * 60 seconds = 1 hour
  res.setHeader("Cache-Control", "max-age: 3600");

  etag; // as seen before
  // 200 or 304
};

Give it another try now, and request the page. The first request makes the browser load for three seconds. If you open the same page in another tab, you'll notice it's already there, and the server wasn't contacted.

This behavior persists for the specified seconds. If, after the cache expires, a new request returns a 304 Not Modified (thanks to the If-None-Match header), the resource will be newly cached for that amount of time.

➕ Better UX
➕ Less load on the server
❔ If the resource changes, the client remains unaware until the cache expires. After expiration, with a different Etag, a new version will be displayed and cached.

When attempting a refresh while staying on the page, you might observe the loading delay, indicating that the server is being contacted. Make sure you're not doing a hard refresh, as it overrides the described behavior.

stale-while-revalidate

If your application needs resource validation but you still want to show the cached version for a better user experience when available, you can use the stale-while-revalidate=<seconds> directive.

res.setHeader("Cache-Control",
   "max-age=120, stale-while-revalidate=300"
);

In this case, the browser is instructed to cache the response for 2 minutes. Once this period elapses, if the resource is requested within the next 5 minutes, the browser will use the cached resource (even if it's stale) but will perform a background validation call.

I want to emphasize the "even if stale" by playing around with the endpoint configured as above. Only soft refreshes are performed.

ℹ️ Info
Tap/click the next items to show the related graph.

1. On the initial page request, it takes 3 seconds to load, and the response is cached for 2 minutes with an associated ETag. The client will include this ETag in the If-None-Match header for subsequent requests.

2. Close and reopen the browser (or request from another page) within the 2-minute window: the page is instantly shown without hitting the server.

3. After the 2-minute cache expires, the server is contacted. The resource has not changed, the client receives 304 Not Modified. The cache expiry date is extended with the provided max-age value. No need to update what the user is seeing.

4. Now that the 2-minute window is open again, let's update the content of the resource using the db endpoint implemented in the previous blog post. Basically, next time the ETag will not match.

curl -X POST http://127.0.0.1:8000/db \
-d '{ "title": "ETag", "tag": "code" }'

5. Still within the 2-minute window, request the page again. Thanks to max-age, the browser shows it immediately. It proceeds with background validation as already seen in step 3. But this time the ETag does not match; the server responds with a 200 OK and provides a new ETag (which overrides the previous entry in the cache).

🔑 message
Although the displayed content is stale, the browser updates its cache silently, preserving the user experience.

Request the page anew; this time, it finally displays the latest stored version. If within the newly restarted 2-minute window, the server won't be contacted.

🔑 message
Any request outside the time window indicated by stale-while-revalidate (which I recall, starts from the expiration of that of max-age), will behave like step 1 - blank state.

Web Caching - ETag/If-None-Match

Francesco Di Donato — Tue, 21 Nov 2023 15:40:00 +0000

Support code

In the previous post, we explored the usefulness of the Last-Modified Response Header and If-Modified-Since Request Header. They work really well when dealing with an endpoint returning a file.

What about data retrieved from a database or assembled from different sources?

Request	Response	Value example
`Last-Modified`	`If-Modified-Since`	`Thu, 15 Nov 2023 19:18:46 GMT`
`ETag`	`If-None-Match`	`75e7b6f64078bb53b7aaab5c457de56f`

Also here, we have a tuple of headers. One must be provided by the requester (ETag), while the other is returned by the sender (If-None-Match). The value is a hash generated on the content of the response.

If you want to go directly to using headers, go to the endpoint. Otherwise, observe (but don't spend too much time on) the implementation.

Preparation

For simplicity, we use an in-memory DB. It is exposed via the endpoint /db. It contains a list of posts. Each post contains a title and a tag. Posts can be added via POST, and modified via PATCH.

Retrieval is via a GET function, which optionally filters by tag.

src/db.mjs

import { getJSONBody } from "./utils.mjs";

const POSTS = [
  { title: "Caching", tag: "code" },
  { title: "Headers", tag: "code" },
  { title: "Dogs", tag: "animals" },
];

export function GET(tag) {
  let posts = POSTS;
  if (tag) posts = posts.filter((post) => post.tag === tag);
  return posts;
}

export default async function db(req, res) {
  switch (req.method) {
    case "POST": {
      const [body, err] = await getJSONBody(req);
      if (err) {
        res.writeHead(500).end("Something went wrong");
        return;
      }

      POSTS.push(body);
      res.writeHead(201).end();
      return;
    }
    case "PATCH":
      const [body, err] = await getJSONBody(req);
      if (err) {
        res.writeHead(500).end("Something went wrong");
        return;
      }

      POSTS.at(body.index).title = body.title;
      res.writeHead(200).end();
      return;
  }
}

src/utils.mjs

export function getURL(req) {
  return new URL(req.url, `http://${req.headers.host}`);
}

export async function getJSONBody(req) {
  return new Promise((resolve) => {
    let body = "";
    req.on("data", (chunk) => (body += chunk));
    req.on("error", (err) => resolve([null, err]));
    req.on("end", () => resolve([JSON.parse(body), null]));
  });
}

Endpoint

By registering the db, we will be able to modify the content of the responses in real-time, appreciating the usefulness of ETag.
Also, let's register and create the /only-etag endpoint.

// src/index.mjs
import { createServer } from "http";
import db from ".src/db.mjs";
import onlyETag from "./src/only-etag.mjs";
import { getURL } from "./src/utils.mjs";

createServer(async (req, res) => {
  switch (getURL(req).pathname) {
    case "/only-etag":
      return await onlyETag(req, res);
    case "/db":
      return await db(req, res);
  }
}).listen(8000, "127.0.0.1", () =>
  console.info("Exposed on http://127.0.0.1:8000")
);

The onlyETag endpoint accepts an optional query parameter tag. If present, it is used to filter the retrieved posts.
Thus, the template is loaded in memory.

src/views/posts.html

<html>
  <body>
    <h1>Tag: %TAG%</h1>
    <ul>%POSTS%</ul>
    <form method="GET">
      <input type="text" name="tag" id="tag" autofocus />
      <input type="submit" value="filter" />
    </form>
  </body>
</html>

When submitted, the form uses as action the current route (/only-etag) appending as query parameter the name attribute. For example, typing code in the input and submitting the form would result in GET /only-etag?name=code), No JavaScript required!

And the posts are injected into it.

import * as db from "./db.mjs";
import { getURL, getView, createETag } from "./utils.mjs";

export default async (req, res) => {
  res.setHeader("Content-Type", "text/html");

  const tag = getURL(req).searchParams.get("tag");
  const posts = await db.GET(tag);

  let [html, errView] = await getView("posts");
  if (errView) {
    res.writeHead(500).end("Internal Server Error");
    return;
  }

  html = html.replace("%TAG%", tag ?? "all");
  html = html.replace(
    "%POSTS%",
    posts.map((post) => `<li>${post.title}</li>`).join("\n")
  );

  res.setHeader("ETag", createETag(html));

  res.writeHead(200).end(html);
};

As you notice, before dispatching the response, the ETag is generated and included under the ETag Response header.

// src/utils.mjs
import { createHash } from "crypto";

export function createETag(resource) {
  return createHash("md5").update(resource).digest("hex");
}

Changing the content of the resource changes the Entity Tag.

Performing the request from the browser you can inspect the Response Headers via the Network tab of the Developer Tools.

HTTP/1.1 200 OK
Content-Type: text/html
ETag: 4775245bd90ebbda2a81ccdd84da72b3

If you refresh the page, you'll notice the browser adding the If-None-Match header to the request. The value corresponds of course to the one it received before.

GET /only-etag HTTP/1.1
If-None-Match: 4775245bd90ebbda2a81ccdd84da72b3

As seen in the previous posts per Last-Modified and If-Modified-Since, let's instruct the endpoint to deal with If-None-Match.

export default async (req, res) => {
  res.setHeader("Content-Type", "text/html");

  retrieve (filtered) posts; // as seen before
  load html; // as seen before
  fill template; // as seen before

  const etag = createETag(html);
  res.setHeader("ETag", etag);
  const ifNoneMatch = new Headers(req.headers).get("If-None-Match");
  if (ifNoneMatch === etag) {
    res.writeHead(304).end();
    return;
  }

  res.writeHead(200).end(html);
};

Indeed, subsequent requests on the same resource return 304 Not Modified, instructing the browser to use previously stored resources. Let's request:

/only-etag three times in a row;
/only-etag?tag=code twice;
/only-etag?tag=animals twice;
/only-etag, without tag, once again;

The presence of the query parameter determines a change in response, thus in ETag.

Notice the last one. It does not matter that there have been other requests in the meantime; the browser keeps a map of requests (including the query parameters) and ETags.

Detect entity change

To further underscore the significance of this feature, let's add a new post to the DB from another process.

curl -X POST http://127.0.0.1:8000/db \
-d '{ "title": "ETag", "tag": "code" }'

And request again /only-etag?tag=code.

After the db has been updated, the same request generated a different ETag. Thus, the server sent the client a new version of the resource, with a newly generated ETag. Subsequent requests will fall back to the expected behavior.

The same happens if we modify an element of the response.

curl -X PATCH http://127.0.0.1:8000/db \
-d '{ "title": "Amazing Caching", "index": 0 }'

While ETag is a more versatile solution, applicable regardless of the data type since it is content-based, it should be considered that the server must still retrieve and assemble the response, then pass it into the hashing function and compare it with the received value.

Thanks to another header, Cache-Control, it is possible to optimize the number of requests the server has to process.

Forem: Francesco Di Donato

How I Turned 4 Sites and a Shared Lib Into One pnpm Workspace

Why pnpm, Not npm or Yarn

The Layout That Actually Works

pnpm-workspace.yaml: The Three-Line File That Starts It All

Sharing Code: workspace:*

Setting Up the Workspace From Scratch

Running Scripts with --filter

Subpath Exports Across Packages

Five Gotchas

1. pnpm deploy is a built-in, not your deploy script

2. pnpm add without -w puts deps in the wrong place

3. Vite's fs.allow narrows when you have multiple Astro apps

4. Native-binding packages need approve-builds

5. workspace:* does not work for dynamic import() from Node scripts

When to Reach for Turborepo or Nx

Troubleshooting

Frequently Asked Questions

Should I use pnpm workspaces for a two-package repo?

Do I need to publish @didof/shared to npm for the workspace to work?

What about CI? Does pnpm workspace break GitHub Actions?

Can I have different TypeScript versions per package?

Does workspace:* work with Yarn Berry or npm workspaces?

Closing

Remote Terminal: iPhone to Mac via Tailscale

What Are We Building?

What You Will Need

Set Up Tailscale on Both Devices

Launch the Terminal Server

Connect From Your iPhone

Mirror the Session With tmux

Keep Your Mac Awake

How Secure Is This Actually?

It Works on Linux and Windows Too

Frequently Asked Questions

Does this work over mobile data or only on WiFi?

Can I use this with an Android phone?

Is Remobi safe to use? It runs via npx.

How K-Means Clustering Works (Explained by Extracting Colors from Images)

K-Means in 30 Seconds

The Five Steps (With Colors)

Why the GPU?

The Fragment Shader

The Hybrid Loop

Real Numbers

Try It

JSON-LD Structured Data for Blogs: A Real Implementation

What Is JSON-LD and Why Does Google Recommend It?

Which BlogPosting Fields Actually Matter?

How Do You Build a JSON-LD Structured Data Component in Astro?

How Do You Wire JSON-LD Into Your Layout Conditionally?

How Do You Verify JSON-LD Structured Data Is Working?

Why Does JSON-LD Structured Data Matter for AI Search in 2026?

FAQ

Do I need a separate JSON-LD block for each blog post?

Does JSON-LD affect page performance?

Should I use the astro-seo-schema npm package instead?

What about FAQ schema on this very page?

How to Use a Reverse Trie for Fast Disposable Email Domain Detection

What Is a Reverse Trie?

Note on This Implementatin

Reverse Trie Domains Implementation

Conclusion

Throttling Explained: A Guide to Managing API Request Limits

When Should You Implement Throttling in Your Code?

What You Will Learn

Throttler Implementation

How it Works

Endpoint example

Note for Authentication

Managing Stale IP Records with Periodic Cleanup

Optimizing Three.js: 4 Key Techniques

Load Scenes Only When Needed

Pause Scenes Out of View

Adjust Shader Workload for Viewport Size

Let the Browser Handle Clean up

Final Thoughts

Radial Gradient Generator

What it offers

Stackable Shades

Sharing Code: `workspace:*`

Running Scripts with `--filter`

1. `pnpm deploy` is a built-in, not your `deploy` script

2. `pnpm add` without `-w` puts deps in the wrong place

3. Vite's `fs.allow` narrows when you have multiple Astro apps

4. Native-binding packages need `approve-builds`

5. `workspace:*` does not work for dynamic `import()` from Node scripts

Do I need to publish `@didof/shared` to npm for the workspace to work?

Does `workspace:*` work with Yarn Berry or npm workspaces?

Should I use the `astro-seo-schema` npm package instead?

`Content-Length`

`Content-Encoding`

`Transfer-Encoding`