Fran Gonzalez

Replacing My Custom Pagefind Modal with astro-pagefind

Fri, 05 Jun 2026 12:23:15 GMT

I recommended astro-pagefind at the end of my gotchas post. Then I tried it.

The Problem

The is:inline workarounds from the gotchas post were functional. But they carried costs I didn't fully appreciate at the time.

35 lines of inline JavaScript sat in the layout — search loading, debounced input, result rendering, a manual trailing-slash fix. A custom <dialog> element handled the search modal. I built both from scratch.

The data-pagefind-body attribute was on the <main> element in the layout. This meant Pagefind indexed the entire site — header, footer, nav — alongside the actual page content. On a small site the noise was manageable. It was still wrong.

The build script ran Pagefind as a post-build step: "astro build && pagefind --site dist". Two commands where one would do.

The gotchas post recommended trying astro-pagefind to avoid all three Vite issues. I wrote that recommendation and moved on. I should have tried it immediately.

What Changed

Integration setup

I added astro-pagefind as a dependency and registered it in the Astro config:

// astro.config.ts
import pagefind from "astro-pagefind";

export default defineConfig({
  integrations: [sitemap(), vue(), pagefind()],
});

The integration handles Pagefind's build step internally. The build script went from "astro build && pagefind --site dist" to "astro build".

Search modal

The custom <dialog> with manual input handling was replaced by the <pagefind-searchbox> component:

<!-- src/layouts/BaseLayout.astro -->
<div id="search-overlay" data-pf-theme="dark" class="fixed inset-0 z-50 hidden bg-black/60 backdrop-blur-sm">
  <div class="mx-auto flex h-full w-full items-start justify-center overflow-y-auto p-4 pt-[10vh] sm:max-w-4xl">
    <PagefindConfig />
    <pagefind-searchbox shortcut="none" placeholder="Search..."></pagefind-searchbox>
  </div>
</div>

The overlay open/close logic — click trigger, Cmd+K, Escape, click-outside — stayed as inline JS. The search input, debouncing, result rendering, and import("/pagefind/pagefind.js") loading were removed.

Indexing scope

data-pagefind-body moved from the <main> element in the layout to individual page wrappers. The <article> in blog posts. The <div> wrappers on the about and now pages. Pagefind now indexes only the content that matters.

Trailing slashes

I changed trailingSlash from "never" to "ignore" in the Astro config. The .replace(/\/$/, "") fix from the gotchas post was no longer needed — astro-pagefind handles URL resolution internally.

Dark theme

Pagefind's component UI ships with its own CSS variables. I mapped them to the existing Gruvbox tokens in global.css:

/* src/assets/css/global.css */
:root {
  --pf-text: var(--ui-text);
  --pf-background: var(--ui-bg);
  --pf-border: var(--ui-border);
  --pf-mark: var(--color-yellow-500);
  /* ... */
}

Tag pills

I added a # prefix to tag pills across the blog index, blog post, and tag pages. A small visual change bundled into the same changeset.

Results

Removed ~50 lines of inline JavaScript and the custom <dialog> markup from the layout
The three gotchas from the previous post — Vite dynamic imports, ES module loading, trailing-slash URLs — are no longer problems I manage manually
Search indexing is scoped to individual pages instead of the full site layout
Build script is one command instead of two

The trade-off: the search UI is now Pagefind's component-based design rather than the custom modal I built. The component handles input, results, keyboard navigation, and theming. I lost direct control over the result rendering — the component renders its own result list.

What I'd Do Differently

I should have tried astro-pagefind before building the custom modal. The gotchas post documented real Vite issues, but the workarounds I built to solve them were unnecessary if I'd started with the integration. The custom modal was the reason I rolled my own — but Pagefind 1.5.x ships its own component UI, which covers the same use case.

References

Pagefind in Astro: The Gotchas I Hit — the previous post this replaces
astro-pagefind — the Astro integration
Pagefind — the search library
Pagefind Component UI — the built-in search component

Pagefind in Astro: The Gotchas I Hit

Fri, 05 Jun 2026 09:24:14 GMT

I added Pagefind to this site for static search. The setup is straightforward — run pagefind --site dist after the build, and it generates a search index alongside your HTML. The integration took longer than expected because of three Vite-specific gotchas that don't appear in the Pagefind docs.

The Problem

The site uses Astro with static output and Vite as the bundler. I needed client-side search that works without a backend. Pagefit fits: it indexes the built HTML, generates a lightweight JS bundle, and runs search in the browser.

The Pagefind docs show a simple import:

const pagefind = await import("/pagefind/pagefind.js");
pagefind.init();

This works in plain HTML. In Astro, it doesn't.

What Changed

Gotcha 1: Vite breaks dynamic imports in inline scripts

Astro processes <script> tags in .astro files through Vite. For inline scripts, Vite transforms dynamic imports into this:

// What Vite generates:
e = await b(() => import(`${s}pagefind.js`), __VITE_PRELOAD__);

__VITE_PRELOAD__ is a Vite internal that should be defined in the bundled output. For inline scripts, it isn't. The result is ReferenceError: __VITE_PRELOAD__ is not defined, which gets silently caught by the try/catch block.

I tried /* @vite-ignore */ — it doesn't work in Astro inline scripts. I tried hiding the path in a variable — same result. The pyk.sh blog documents this same issue and solved it by moving the import to a separate .ts file. I found a simpler path.

The fix is <script is:inline>:

<!-- src/layouts/BaseLayout.astro -->
<script is:inline>
  let pagefind;

  async function loadPagefind() {
    if (pagefind) return pagefind;
    try {
      pagefind = await import("/pagefind/pagefind.js");
      await pagefind.init();
      return pagefind;
    } catch {
      console.log("Pagefind not available in dev mode");
      return null;
    }
  }

  // Lazy-load on search input focus
  document.getElementById("search-input")?.addEventListener("focus", () => {
    loadPagefind();
  });
</script>

The is:inline directive tells Astro to skip Vite processing entirely. The script is rendered verbatim into the HTML. The browser handles the import() natively — and import() works fine in classic scripts, even though import declarations require module context.

The trade-off: is:inline scripts can't use TypeScript or local imports. The search code is simple enough that this doesn't matter.

The upstream Vite issue

This isn't an Astro bug. It's a Vite behavior documented in vitejs/vite#18551: Vite injects __vitePreload on every dynamic import, even when modulePreload is set to false. For external script files, Vite includes the preload polyfill in the bundled output. For inline scripts, the polyfill isn't included, so the reference is undefined.

The /* @vite-ignore */ comment is supposed to prevent Vite from processing a dynamic import. vitejs/vite#14850 documents that it doesn't work for files in public/. In our case, it didn't work for inline scripts either — Vite stripped the comment and bundled the import regardless.

Gotcha 2: Pagefind.js is an ES module

Pagefind 1.5.x generates pagefind.js as an ES module. It uses export{...} at the end and references import.meta.url internally for path resolution. Loading it as a classic <script> tag produces:

Uncaught SyntaxError: import.meta may only appear in a module

The import() approach from Gotcha 1 solves this too. Dynamic import() loads the file as a module, so import.meta.url works correctly.

Gotcha 3: Trailing slashes in search result URLs

Pagefind derives URLs from the file structure in dist/. Astro with trailingSlash: "never" generates files like dist/blog/foo/index.html, which Pagefind reads as the URL /blog/foo/. But the site serves /blog/foo (no trailing slash). Clicking a search result produces a 404.

The fix is a one-line change in the result rendering:

// Strip trailing slash to match trailingSlash: "never" config
<a href="${data.url.replace(/\/$/, "") || "/"}" class="block">

Results

Search works in both pnpm preview and production builds. The Pagefind bundle adds minimal weight — the index loads on demand when the user focuses the search input.

The try/catch gracefully handles dev mode, where the Pagefind index doesn't exist. Users see "Pagefind not available in dev mode" in the console, which is the expected behavior.

What I'd Do Differently

The is:inline approach works, but it means the search script is duplicated on every page that uses the layout. For this site that's acceptable — the script is small. On a larger site with many layout variants, I'd move the search logic to a separate .ts file in src/scripts/ and reference it with <script src="../scripts/search.ts">. Vite properly bundles external script files with __VITE_PRELOAD__ defined.

I'd also try astro-pagefind next time. It handles the Vite integration and provides pre-built components, which would have avoided all three gotchas. I rolled my own because I wanted a custom search modal, but the integration is worth revisiting — especially now that Pagefind 1.5.0 ships its own component-based UI.

References

Pagefind — Official Docs — the search library
Pagefind Search API — the import("/pagefind/pagefind.js") pattern
Astro Client-Side Scripts — is:inline and script processing rules
vitejs/vite#18551 — upstream issue: Vite injects __vitePreload even when modulePreload is disabled
vitejs/vite#14850 — upstream issue: @vite-ignore doesn't prevent resolution of public-dir imports
Fixing the Unresolved Dynamic Import in Astro — pyk.sh — prior art on the same Vite issue
Pagefind Search in Astro — syntackle.com — integration guide using is:inline
astro-pagefind — Astro integration that handles the Vite wiring

Migrating from Nuxt Content to Astro Content

Thu, 04 Jun 2026 22:16:17 GMT

I migrated frangonf.com from Nuxt Content v3.13 to Astro Content — the content schema, the collections, and the search integration.

The Problem

The Nuxt Content config (content.config.ts, 146 lines) used defineContentConfig from @nuxt/content with five factory functions (createBaseSchema, createImageSchema, createVideoSchema, createGallerySchema, createAuthorSchema). The schema had 22 fields, three date fields (date, createdAt, updatedAt), and now/about pages as YAML files with a content string field.

The Astro content config (src/content.config.ts, 99 lines) uses defineCollection from astro:content with glob() loaders and 16 schema fields.

What Changed

Content Config

The old Nuxt config defined collections with type: 'page' and source strings:

// content.config.ts (deleted)
import { defineCollection, defineContentConfig, z } from "@nuxt/content";

export default defineContentConfig({
  collections: {
    blog: defineCollection({
      type: "page",
      source: "blog/*.md",
      schema: z.object({
        title: z.string(),
        description: z.string(),
        minRead: z.number().optional(),
        date: z.date(),
        createdAt: z.date().optional(),
        updatedAt: z.date().optional(),
        draft: z.boolean().optional().default(false),
        featured: z.boolean().optional().default(false),
        author: z
          .union([z.string(), createAuthorSchema()])
          .optional()
          .default("Fran"),
        tags: z.array(z.string()).optional().default([]),
        category: z.string().optional(),
        series: z.object({ name: z.string(), order: z.number() }).optional(),
        image: z.string().nonempty().editor({ input: "media" }).optional(),
        rawbody: z.string().optional(),
        seo: z
          .object({
            title: z.string().optional(),
            description: z.string().optional(),
            keywords: z.array(z.string()).optional(),
          })
          .optional(),
      }),
    }),
  },
});

The new Astro config defines collections with glob() loaders:

// src/content.config.ts
import { defineCollection } from "astro:content";
import { glob } from "astro/loaders";
import { z } from "astro/zod";

const blog = defineCollection({
  loader: glob({ pattern: "**/*.md", base: "./src/content/blog" }),
  schema: ({ image }) =>
    z.object({
      title: z.string(),
      description: z.string(),
      createdAt: z.coerce.date(),
      draft: z.boolean().default(false),
      featured: z.boolean().default(false),
      author: z.string().default("Fran"),
      tags: z.array(z.string()).default([]),
      category: z.string().optional(),
      series: z.object({ name: z.string(), order: z.number() }).optional(),
      image: image().optional(),
      seo: z
        .object({
          title: z.string().optional(),
          description: z.string().optional(),
        })
        .optional(),
    }),
});

const now = defineCollection({
  loader: glob({ pattern: "now.md", base: "./src/content" }),
  schema: z.object({
    title: z.string(),
    description: z.string(),
    createdAt: z.coerce.date(),
    seo: z
      .object({
        title: z.string().optional(),
        description: z.string().optional(),
      })
      .optional(),
  }),
});

const about = defineCollection({
  loader: glob({ pattern: "about.md", base: "./src/content" }),
  schema: z.object({
    title: z.string(),
    description: z.string(),
    seo: z
      .object({
        title: z.string().optional(),
        description: z.string().optional(),
      })
      .optional(),
  }),
});

export const collections = { blog, now, about };

The now and about collections changed from YAML files (now.yml, about.yml) to Markdown files (now.md, about.md). The content string field was removed — the Markdown body is the content.

The index collection (sourced from index.yml) was removed entirely.

Fields Removed

Field	Type	Reason
`date`	`z.date()` (required)	Replaced by `createdAt`
`createdAt`	`z.date().optional()`	Replaced by required `createdAt` with `z.coerce.date()`
`updatedAt`	`z.date().optional()`	Derived from git via remark plugin
`minRead`	`z.number().optional()`	Computed at build time
`rawbody`	`z.string().optional()`	Unused
`seo.keywords`	`z.array(z.string()).optional()`	Unused
`author` (object form)	`z.union([z.string(), createAuthorSchema()])`	Simplified to `z.string()`

The five factory functions (createBaseSchema, createImageSchema, createVideoSchema, createGallerySchema, createAuthorSchema) were removed. All schemas are inlined.

Image Handling

The image field changed from z.string().nonempty().editor({ input: "media" }).optional() to image().optional() — Astro's image helper for content collection schemas.

The image() helper returns an image metadata object, not a string. I updated every template using <img src={post.data.image}> to <Image src={post.data.image} /> from astro:assets. The getImage() function processes images for OG meta tag URLs.

Frontmatter uses relative paths:

image: ./images/my-cover-photo.jpeg

Date Schema

createdAt uses z.coerce.date() instead of z.date(). The coercion handles string dates in frontmatter without validation errors.

lastModified is derived from git log at build time via a custom remark plugin:

// remark-modified-time.ts
import { execSync } from "node:child_process";

export function remarkModifiedTime() {
  return function (tree: any, file: any) {
    const filepath = file.history[0];
    const result = execSync(`git log -1 --pretty=%aI -- "${filepath}"`)
      .toString()
      .trim();
    file.data.astro.frontmatter.lastModified = result;
  };
}

The plugin writes to file.data.astro.frontmatter.lastModified, which Astro exposes to templates as remarkPluginFrontmatter.lastModified. It is not a frontmatter field — it is computed at build time. Files not yet committed are silently skipped.

Pagefind Search

The old site used Nuxt UI's <UContentSearch> component with SQLite WASM and Fuse.js — 1.88 MB of client-side JavaScript. Pagefind indexes at build time and outputs a static search bundle.

The build command chains the two steps:

{
  "build": "astro build && pagefind --site dist"
}

Pagefind loads via dynamic import() with @vite-ignore to avoid Vite's import analysis. The @vite-ignore comment is necessary because Pagefind JS does not exist during dev mode:

// src/layouts/BaseLayout.astro
const loadPagefind = async () => {
  if (pagefind) return pagefind;
  try {
    pagefind = await import(/* @vite-ignore */ "/pagefind/pagefind.js");
    await pagefind.init();
  } catch {
    console.log("Pagefind not available in dev mode");
  }
  return pagefind;
};

The Pagefind JavaScript API provides search(), debouncedSearch(), and preload() methods. Results load asynchronously via result.data() to minimize bandwidth. The search UI is a native <dialog> element with no additional library.

The pagefind.yml config sets root_selector: "body". The <main> element in BaseLayout.astro has data-pagefind-body to scope the indexable region.

Memento Mori as Vue Island

The Memento Mori page uses the @astrojs/vue integration with client:load for immediate hydration. It is the only page that ships JavaScript to the client.

// src/pages/mm.astro
---
import MementoMori from "../components/MementoMori.vue";
---

<MementoMori client:load />

The component was ported from the Nuxt version. I replaced useLocalStorage with a custom composable, replaced the Nuxt Icon component with inline SVGs, and kept temporal-polyfill for date arithmetic.

Results

Metric	Nuxt Content	Astro Content
Content config	146 lines	99 lines
Schema fields	22	16
Collections	4 (index, blog, now, about)	3 (blog, now, about)
Date fields	3 (date, createdAt, updatedAt)	1 (createdAt) + git-derived
Client bundle	7.2 MB	149 KB
Search bundle	1.88 MB	~20 KB
JS on blog pages	~500 KB	0

What I'd Do Differently

The image() helper returns an object, not a string. Every template that touched image needed updating. This is documented in the Astro Images guide but easy to miss when migrating from Nuxt Content where image was z.string().

Four posts have orphaned minRead fields in frontmatter — Astro silently ignores them since the field is not in the schema.

computeReadingTime is duplicated across five files (blog index, slug, tag, category, author pages). It could be extracted to src/utils/dates.ts.

Vitest and Playwright tests pass locally (48 and 46 respectively) but neither pnpm test nor pnpm test:e2e appears in the GitHub Actions CI workflow. The CI validates linting, formatting, type checking, and build — not the test suites themselves.

References

Astro Content Collections — collection definition with defineCollection and glob() loaders
Nuxt Content: Define Collections — defineContentConfig and defineCollection with type and source
Astro Images — image() helper, <Image /> component, and getImage()
Astro: Add Last Modified Time — remark plugin recipe for git-derived timestamps
Astro Vue Integration — client:load directive and island architecture
Astro: Migrate from NuxtJS — official migration guide
Pagefind — static search indexing
Pagefind JavaScript API — init(), search(), debouncedSearch(), preload()
Nuxt UI — <UContentSearch> component used in the previous setup

Automated Dependency Updates with Supply Chain Security

Thu, 04 Jun 2026 16:47:37 GMT

The previous post covered static supply chain defenses — tool pinning, pnpm workspace settings, CI hardening. But one gap remained: dependency updates. I was updating packages manually, which meant either falling behind on security patches or adopting new releases the moment they shipped. Neither worked.

Automated dependency bots solve the velocity problem. Without cooldown policies, they can become the delivery mechanism for the next supply chain attack.

The Problem

In September 2025, the Shai-Hulud attack compromised over 500 npm packages in a coordinated campaign. Malicious versions were published, and projects with automated updates that had no cooldown window adopted them within minutes. The attack was discovered and the malicious versions removed within hours — but for projects using auto-merge, the damage was already done.

Update automation needs a cooling-off period. Most compromised packages are discovered and removed from the registry within 24 hours. A short delay between publication and adoption catches the majority of attacks without meaningfully slowing down legitimate updates.

How Cooldowns Work

There are three layers of cooldown in a typical JavaScript project:

Layer	Tool	Coverage	What it does
Package manager	pnpm `minimumReleaseAge`	Full tree (transitive too)	Blocks install of packages published less than N minutes ago
Update bot	Renovate `minimumReleaseAge` or Dependabot `cooldown`	Direct dependencies only	Delays PR creation until a package version is N days old
CI gate	StepSecurity npm Package Cooldown	PR-level	Blocks merge if a PR introduces a version published within N days

The package manager setting catches transitive dependencies that the update bot doesn't manage. The CI gate catches manual pnpm add commands that bypass the bot entirely.

Renovate Configuration

Renovate's cooldown is configured with minimumReleaseAge:

{
  $schema: "https://docs.renovatebot.com/renovate-schema.json",
  extends: ["config:recommended"],
  minimumReleaseAge: "3 days",
  minimumReleaseAgeBehaviour: "timestamp-required",
}

Renovate will not create a PR for any package version published less than 3 days ago. If the latest release is too fresh, it picks the most recent version that satisfies the age requirement.

For security-specific updates, I can create a package rule that bypasses the cooldown:

{
  packageRules: [
    {
      matchUpdateTypes: ["pin", "digest"],
      minimumReleaseAge: "0 days",
      description: "Allow immediate pin and digest updates",
    },
  ],
}

Renovate's minimumReleaseAge only applies to direct dependencies. Transitive dependencies — the ones pulled in by your dependencies — are not covered. That's where pnpm's minimumReleaseAge fills the gap, since it applies to the full dependency tree during resolution.

Dependabot Configuration

Dependabot's equivalent is the cooldown option:

# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "daily"
    cooldown:
      default-days: 3
      semver-major-days: 30
      semver-minor-days: 7
      semver-patch-days: 3

The semver-specific overrides are worth setting — major version bumps warrant a longer cooling-off period since they're more likely to introduce breaking changes or unexpected behavior.

Dependabot's cooldown also only applies to direct dependencies. Like Renovate, it complements pnpm's minimumReleaseAge rather than replacing it.

The Gap: Transitive Dependencies

Neither Renovate nor Dependabot manages transitive dependencies. If a package you depend on adds a new transitive dependency that was published minutes ago, neither bot will catch it. pnpm's minimumReleaseAge does — it applies during resolution, regardless of whether the dependency is direct or transitive.

The two layers need each other:

Renovate/Dependabot → creates PRs, manages direct dependency updates, respects its own cooldown
pnpm minimumReleaseAge → catches transitive dependencies, applies at install time, covers the full tree

Putting It Together

A minimal setup that covers all three layers:

pnpm-workspace.yaml — minimumReleaseAge: 1440 (covers full tree)
Renovate or Dependabot — cooldown of 3+ days (manages direct deps)
CI step — pnpm audit --prod --audit-level high (catches known vulnerabilities)

The cooldown values should be long enough for the community to discover attacks (24+ hours) but short enough that security patches don't sit in limbo for weeks. I started with 3 days and adjusted from there.

What I'd Do Differently

I'd set up Renovate earlier. The manual update workflow meant I was either behind on patches or anxiously watching for reports of compromised packages after every pnpm update. The cooldown setting removes that tension — updates happen at a pace where the community has time to catch problems.

The one tradeoff: security patches for transitive dependencies still depend on pnpm's minimumReleaseAge alone. There's no bot creating PRs for those. A pnpm audit step in CI is the safety net.

What's Next

Automated updates handle the "get patches faster" problem. But the config that supports them — exclusion lists, allowlists, trust policies — can become stale as the dependency tree evolves. The next post covers keeping supply chain exclusions honest.

References

Renovate minimumReleaseAge — cooldown for Renovate-managed updates
Dependabot cooldown — cooldown for Dependabot-managed updates
pnpm minimumReleaseAge — full-tree cooldown at install time
pnpm minimumReleaseAgeExclude — exceptions for packages that need immediate updates
StepSecurity npm Package Cooldown — CI-level merge gate
GitGuardian: Renovate & Dependabot supply chain analysis — attack case studies
Shai-Hulud attack overview — coordinated npm compromise campaign

Beyond Version Checks: Provenance and Behavioral Security

Thu, 04 Jun 2026 16:47:37 GMT

The first three posts in this series covered version-level controls — pinning tools, cooling off new releases, managing exclusions. These catch the majority of supply chain attacks. But a growing class of attacks slips past them.

In April 2026, the TanStack/router repository was compromised through a CI workflow manipulation. The attacker published malicious packages with valid SLSA provenance — because the packages were genuinely built by the repository's own pipeline. The pipeline's internal state was compromised, but the build environment was legitimate. Provenance verified correctly. Version checks passed. The attack relied on behavioral patterns that no version-level control can catch.

Provenance Verification

What provenance tells you

When a package is published with --provenance on npm, the registry stores a Sigstore-signed attestation that links the package to:

The source repository and commit
The CI workflow that built it
The build environment (GitHub Actions OIDC token)

This is roughly SLSA Build Level 2 — the package was built on a hosted platform, and the provenance is cryptographically signed so it can't be forged.

pnpm audit signatures

pnpm 11.1 added pnpm audit signatures, which verifies ECDSA signatures against npm's published keys. I added it as a CI step:

- name: Verify package signatures
  run: pnpm audit signatures

This catches cases where a package was published outside its trusted CI pipeline — for example, a maintainer's account is compromised and they publish manually without provenance.

What provenance doesn't tell you

Provenance confirms which pipeline built a package, not whether that pipeline was clean. The TanStack/router incident demonstrated this — the attacker compromised the workflow itself, so the provenance was valid. The package was built by the right pipeline, but the pipeline was doing the wrong thing.

Provenance catches impersonation and token theft. It doesn't catch pipeline compromise.

Behavioral Analysis

The install-time execution problem

The most dangerous moment in the npm lifecycle is pnpm install. A compromised package with a postinstall script gets code execution on your machine with full access to:

~/.npmrc (registry tokens)
~/.ssh/ (SSH keys)
GITHUB_TOKEN (in CI)
Environment variables (secrets, API keys)

allowBuilds in pnpm v11 blocks scripts from unreviewed packages. But for packages I've approved, the script runs with full privileges. If an approved package is later compromised (through a maintainer account takeover, for example), the next pnpm install executes the malicious script.

Socket.dev

Socket monitors packages for behavioral red flags:

Install-time network connections — a package that opens sockets during postinstall is suspicious
Filesystem access — reading files outside the package directory (especially ~/.ssh, ~/.npmrc)
Shell command execution — spawning child processes that aren't part of the build
Obfuscated code — dynamically decoded payloads, eval chains
New binary introductions — a package that didn't previously ship binaries suddenly adds one

Socket integrates with GitHub as a PR check. When a dependency update introduces a package with suspicious behavior, the PR gets flagged.

The TanStack lesson

The TanStack/router attacker had valid provenance. Version checks passed. The only signal was behavioral — the compromised pipeline was doing something it hadn't done before. Behavioral analysis catches this class of attack because it asks "what is this package doing?" rather than "is this package the right version?"

Private Registry Proxy

For projects with internal packages, a private registry proxy (Verdaccio, Artifactory, Cloudflare Workers) adds another gate:

Route all npm traffic through the proxy
Block known malicious versions at the proxy level
Cache and audit every download
Enforce organizational policies (no install scripts from untrusted sources)

This prevents dependency confusion attacks and gives a central point to enforce policies that package managers alone can't.

SBOM Generation

A Software Bill of Materials (SBOM) is a machine-readable inventory of every dependency in your project. When a new vulnerability is disclosed, I can instantly check whether I'm affected.

Generate an SBOM with:

pnpm sbom --format spdx-json > sbom.json

For static sites this is low-risk. For anything that handles user data, an SBOM is the difference between "we'll check" and "we know."

The Full Stack

The layers from this series, in order of what to implement first:

Layer	What it catches	Effort
Lockfile + `--frozen-lockfile`	Unexpected version changes	Low
`minimumReleaseAge`	Freshly published compromised packages	Low
`allowBuilds`	Unreviewed install scripts	Low
SHA-pinned CI actions	Compromised mutable tags	Low
`pnpm audit` in CI	Known vulnerabilities	Low
Renovate/Dependabot with cooldown	Stale dependencies, update velocity	Medium
`pnpm audit signatures`	Packages published outside trusted pipelines	Low
`trustPolicy: no-downgrade`	Provenance regression	Low
Socket.dev	Behavioral anomalies in dependencies	Medium
Private registry proxy	Dependency confusion, central policy enforcement	Medium
SBOM generation	Impact analysis for new CVEs	Low

No single layer is complete. Each one catches attacks that the others miss. The goal isn't to make supply chain attacks impossible — it's to make them expensive enough that attackers move on.

What I'd Do Differently

I'd add pnpm audit signatures to CI earlier. It's a one-liner that catches a class of attacks I wasn't monitoring at all. I'd also look at Socket.dev for any project that handles user data — the behavioral analysis fills a gap that version-level controls can't touch.

The private registry proxy is the one I'd skip for a static blog. It's worth the setup for anything with user-facing APIs or sensitive data, but the overhead isn't justified for a site that only serves HTML.

References

SLSA Framework — supply chain integrity levels
Sigstore — keyless signing and verification for npm packages
pnpm audit signatures — ECDSA signature verification
npm provenance — SLSA provenance for npm packages
Socket.dev — behavioral analysis for npm packages
TanStack/router incident analysis — case study of provenance-valid attack
SBOM generation — machine-readable dependency inventory
StepSecurity — CI-level cooldown and compromised package detection

Keeping Supply Chain Exclusions Honest

Thu, 04 Jun 2026 16:47:37 GMT

The first post in this series covered setting up pnpm's supply chain controls. The second covered automated updates with cooldowns. This post covers the part I kept postponing: keeping the config from rotting.

The Problem

When I first set up minimumReleaseAgeExclude, trustPolicyExclude, and allowBuilds, each entry had a clear reason. But dependency trees change. Packages get upgraded, new ones get added, old ones get removed. The exclusion lists don't clean themselves up — they only grow.

I found this while applying the same security setup to a second project. The first project had 31 overrides that weren't doing anything. The second had minimumReleaseAgeExclude entries for packages published months ago, well past the age window. The configs looked hardened but were full of dead weight.

The Three Lists That Decay

minimumReleaseAgeExclude

This list exempts packages from the minimumReleaseAge check. It grows in two ways:

Manual additions — I need a fresh release and add an entry to unblock it
Automatic additions — pnpm audit --fix=update adds entries when patching vulnerabilities, so the patched version can install without waiting for the age window

The problem: entries are never removed. There's no built-in cleanup mechanism (pnpm#11668). A minimumReleaseAgeExclude entry for a package published months ago is doing nothing — the package is already past the age window, so the exclusion is pure noise.

There's also a bug where pnpm audit --fix update adds entries even for packages that wouldn't be blocked (pnpm#11563). The list grows faster than it should.

trustPolicyExclude

This list exempts packages from the trustPolicy: no-downgrade check. It's needed when a package doesn't ship with provenance attestations but is known-safe.

The entries age out as upstream packages adopt provenance. A trustPolicyExclude for chokidar@4.0.3 was justified six months ago — the pinned version lacked provenance. But the latest release now ships with provenance, so the exclusion is holding back a security control for no reason.

allowBuilds

This list whitelists packages that may run install scripts. It should match the packages in your dependency tree that actually have postinstall scripts. But dependency trees change — packages get removed, new ones get added, and the allowlist drifts.

An allowBuilds entry for a package that's no longer installed is harmless but confusing. An entry that's missing for a newly added package causes pnpm install to fail, which is the correct behavior with strictDepBuilds: true.

The Audit Workflow

There's no automated tool that cleans up these lists. The practical approach is a manual review, which takes minutes when done regularly.

Step 1: Check what's installed

For allowBuilds, I verify each entry against the actual dependency tree:

pnpm ls @parcel/watcher
pnpm ls core-js
pnpm ls esbuild

If pnpm ls returns nothing, the package isn't installed and doesn't need an allowBuilds entry.

Step 2: Check publish dates

For minimumReleaseAgeExclude, I check whether entries are still needed:

pnpm info astro@6.3.8 --json | grep -A2 '"time"'

If the package was published well past the minimumReleaseAge window (months ago), the exclude is doing nothing. Remove it.

Step 3: Check provenance

For trustPolicyExclude, I check whether the excluded package now ships with provenance:

pnpm info chokidar@4.0.3 --json | grep -A5 '"attestations"'

If provenance has a URL, the package now has attestations and the exclude can be removed (after upgrading to the version that has provenance).

Step 4: Run pnpm audit

pnpm audit --prod

This catches known vulnerabilities regardless of exclusion lists. If audit finds issues, the exclusions aren't protecting from everything.

When to Schedule Reviews

The review doesn't need to be frequent. Good triggers:

When upgrading packages — exclusions for old versions may no longer apply
When pnpm audit finds new advisories — check whether exclusions are blocking fixes
When adding new dependencies — verify allowBuilds covers any new install scripts
Quarterly — a standing calendar reminder to check the lists even if nothing else changed

Partial Automation

Renovate's customManagers can detect version strings in pnpm-workspace.yaml and create PRs to update them. This keeps exclusion versions current but can't decide whether an entry should be deleted. It's a useful supplement, not a replacement for manual review.

The pnpm team is considering a pnpm cleanup command that would auto-prune stale entries (pnpm#11668). Until that lands, the workflow is manual.

What I'd Do Differently

I'd run this review quarterly from the start instead of discovering the staleness when applying the config to a second project. The exclusion lists were doing real work when I added them — I just never went back to check whether they still were.

References

pnpm#11668 — feature request for pnpm cleanup to auto-prune stale entries
pnpm#11563 — bug where pnpm audit --fix update adds unnecessary entries
pnpm minimumReleaseAgeExclude — exemption list for age-based blocking
pnpm trustPolicyExclude — exemption list for trust downgrade checks
pnpm allowBuilds — install script allowlist
Renovate customManagers — partial automation for version detection

Creating a Tone Skill for AI-Assisted Blog Posts

Thu, 04 Jun 2026 13:20:45 GMT

I had blog posts written by Clanker but no formal guidelines. The voice was consistent because I manually prompted for it every time. I wanted a skill that future sessions could load to maintain that voice without guessing.

The Problem

Each post followed a similar pattern — problem-first structure, honest tone, inline attribution — but nothing documented why. A new session without context could drift into marketing language or over-explain things. The voice existed in the posts but not as instructions.

What Changed

I reviewed existing Clanker posts, extracted the recurring patterns, and wrote them into a skill file at .agents/skills/clanker-post/SKILL.md following the opencode Agent Skills spec.

The skill covers:

Voice — first person, active voice, no AI disclaimers
Tone — stabilized, concise, humble, honest, informative
Structure — Problem → What Changed → Results (when relevant) → References (when relevant)
Attribution — inline source credits, References section when sources are used
Checklist — 10-item pre-publish verification

The hardest part was making Results and References contextual. I initially wrote "always include" — then realized test posts and proofs of concept don't need them. "When relevant" with clear skip criteria fixed that.

// .agents/skills/clanker-post/SKILL.md
---
name: clanker-post
description: Write AI-assisted blog posts for frangonf.com in a stabilized,
concise, humble, honest, and informative tone.
---

The skill loads on demand via skill({ name: "clanker-post" }) — no config changes, no global skills modified.

What I'd Do Differently

I wrote the skill before reviewing the posts. Extract patterns first, then formalize would have been faster. The "What to Avoid" table was the easiest part — filler phrases I'd already been avoiding, now explicit for future sessions to check against.

References

opencode Agent Skills — skill file format and discovery paths

Supply Chain Security with mise and pnpm

Thu, 04 Jun 2026 13:06:18 GMT

Supply chain attacks have been escalating for months — compromised npm packages, tainted GitHub Actions, backdoored tool releases. If you're maintaining a JavaScript project, the question isn't whether to harden your supply chain, but how much. I applied these controls to my projects, and the setup carries over to any Node.js/pnpm project.

The Problem

Supply chain attacks target the tools and dependencies you trust. A compromised npm package, a backdoored GitHub Action, or a tampered tool binary can give an attacker access to your build output, your secrets, or your users.

The projects had lockfiles, HTTPS registry connections, and some pnpm v10 workspace settings — but nothing systematic. No cooling-off period for tool releases. No checksum verification for tool installs. CI workflows using mutable tags instead of pinned commits. The goal was to close those gaps across the full stack: tool installation, dependency management, CI pipelines, and git hooks.

What Changed

The hardening covers five areas: tool installation, dependency management, npm configuration, CI pipelines, and git hooks. Most of these controls existed in pnpm v10 — the v11 migration consolidated them and added new defaults.

Tool pinning with mise

mise manages runtime versions across Node.js, pnpm, and developer tools. Every version is pinned to an exact release in mise.toml:

# mise.toml
[settings]
minimum_release_age = "7d"

[tools]
node = "26.1.0"
pnpm = "11.1.2"
hk = "1.46.0"
"github:zizmorcore/zizmor" = "v1.25.2"
actionlint = "1.7.12"

The minimum_release_age setting is the key addition. It refuses to install any tool release published less than seven days ago. If a tool maintainer's account is compromised and a backdoored version ships, you have a week to find out before your machine touches it.

The mise.lock file pins SHA-256 checksums for every tool binary on every platform. It also records provenance attestations for tools sourced from GitHub — cryptographic proof that the binary came from the expected release, not a tampered artifact.

# mise.lock (excerpt)
[[tools.pnpm]]
version = "11.1.2"
backend = "aqua:pnpm/pnpm"

[tools.pnpm."platforms.macos-arm64"]
checksum = "sha256:2f46bcb7ac3c693af72e06e68467b3a9127cbf2a24b778382bc8beaff8463aee"
url = "https://github.com/pnpm/pnpm/releases/download/v11.1.2/pnpm-darwin-arm64.tar.gz"
provenance = "github-attestations"

pnpm workspace security

pnpm's workspace settings ship a set of supply chain controls that go well beyond what .npmrc alone can do. These are the ones worth enabling.

Blocking fresh packages

The minimumReleaseAge setting (in minutes) rejects any npm dependency published less than N minutes ago. 1440 (one day) is a reasonable default:

# pnpm-workspace.yaml
minimumReleaseAge: 1440

This is the npm equivalent of mise's minimum_release_age. Most compromised packages are discovered and removed from the registry within hours. A 24-hour cooling-off period catches the majority of them without breaking normal workflow. Packages that genuinely need to be installed fresh get listed under minimumReleaseAgeExclude:

minimumReleaseAgeExclude:
  - nuxt@4.4.7

Trust policy

The trustPolicy setting prevents installing a version of a package that has weaker trust evidence than a previous release. Set to no-downgrade, pnpm will refuse to install if a package that previously shipped with provenance suddenly stops:

trustPolicy: no-downgrade

Packages that don't yet support provenance but are known-safe get excluded:

trustPolicyExclude:
  - chokidar@4.0.3
  - semver
  - tinyclip@0.1.13

These exclusions are stopgaps. The goal is to remove them as upstream packages adopt provenance.

Blocking exotic sub-dependencies

The blockExoticSubdeps setting ensures that only your direct dependencies can come from git repos or tarball URLs. Transitive dependencies — the ones you didn't choose and aren't reviewing — must resolve from a trusted registry:

blockExoticSubdeps: true

Controlling install scripts

Install scripts (postinstall, preinstall) are the most dangerous part of the npm ecosystem. A compromised package with a postinstall script gets code execution on your machine during pnpm install.

pnpm v11 uses allowBuilds — a map of package names to true or false — to whitelist exactly which packages may run scripts:

# pnpm-workspace.yaml (pnpm v11)
allowBuilds:
  "@parcel/watcher": true
  better-sqlite3: true
  esbuild: true
  sharp: true
  unrs-resolver: true
  vue-demi: true

Every package not listed is blocked by default.

If you're upgrading from pnpm v10, the old onlyBuiltDependencies (a list of allowed packages) and ignoredBuiltDependencies (a blocklist) have been consolidated into allowBuilds and removed. The managePackageManagerVersions and packageManagerStrictVersion settings are also gone, replaced by pmOnFail. Running pnpx codemod run pnpm-v10-to-v11 handles the migration.

The strictDepBuilds setting (default: true) makes this enforced — any package with an unreviewed build script causes the install to fail, not just warn.

Additional hardening

A few more settings worth enabling:

strictPeerDependencies: true
strictStorePkgContentCheck: true
preferFrozenLockfile: true
saveExact: true
engineStrict: true
pmOnFail: error

strictPeerDependencies fails the install on missing or invalid peer dependencies. strictStorePkgContentCheck validates package names and versions against store contents, catching registry anomalies. preferFrozenLockfile skips dependency resolution when the lockfile already satisfies package.json, preventing unnecessary lockfile mutations.

saveExact pins exact versions when adding new dependencies (no ^ or ~ prefixes). engineStrict fails installs when a dependency targets an incompatible Node.js or pnpm version. pmOnFail (set to "error") enforces the exact pnpm version from the packageManager field — replacing the deprecated managePackageManagerVersions and packageManagerStrictVersion settings from pnpm v10.

npm configuration

In pnpm v11, .npmrc is auth/registry only. All other settings belong in pnpm-workspace.yaml. This is a change from pnpm v10, where .npmrc was the primary config file. Here's where each setting lives:

Setting	`.npmrc` (auth only)	`pnpm-workspace.yaml`
`_authToken`, `_auth`, certificates	✅	—
`registry`	✅	—
`strict-ssl`	✅	✅
`save-exact`	—	✅
`engine-strict`	—	✅
`strict-peer-dependencies`	—	✅
`audit`, `audit-level`	—	✅
`verify-store-integrity`	—	✅
`fetch-retries`, `fetch-retry-*`	—	✅

After migrating to pnpm v11, simple pnpm projects can remove .npmrc entirely — all project policy lives in pnpm-workspace.yaml. Projects that don't use private registries or custom auth tokens have no reason to keep the file:

# pnpm-workspace.yaml (pnpm v11)
saveExact: true
engineStrict: true

The packageManager field in package.json reinforces version pinning through Corepack:

{
  "packageManager": "pnpm@11.1.2",
  "engines": {
    "node": ">=26.1.0 <27",
    "pnpm": ">=11.1.2 <12"
  }
}

Combined with engineStrict, there's no way for a contributor to accidentally run a different version.

CI hardening

The GitHub Actions workflows got three changes.

SHA-pinned actions. Every uses: reference now points to a full commit hash, not a mutable tag. A compromised tag (e.g., actions/checkout@v6 being replaced with a backdoored v6) can't affect the workflow:

- uses: actions/checkout@9f698171ed81b15d1823a05fc7211befd50c8ae0 # v6.0.3
  with:
    persist-credentials: false

The version comment is for readability. The SHA is what the runner resolves. GitHub's security hardening guide recommends this as the primary defense against compromised third-party actions.

persist-credentials: false. By default, actions/checkout writes the auth token to the local git config. Setting persist-credentials: false (documented in the checkout action) prevents that token from lingering in the runner environment.

Minimal permissions. The top-level permissions key locks down the GITHUB_TOKEN to read-only. Individual jobs declare only what they need:

permissions: {} # deny-all at top level

jobs:
  ci:
    permissions:
      contents: read

This follows the least-privilege principle — if a step is compromised, it can only do what its job's permissions allow.

Adding pnpm audit as a dedicated CI step catches known vulnerabilities before they ship:

- name: Audit production dependencies
  run: pnpm audit --prod --audit-level high

The pnpm audit command checks the dependency tree against the npm advisory database. Running it in CI means vulnerable dependencies block the merge.

Git hooks with hk

hk runs linting, formatting, and type checks as pre-commit hooks. The configuration pins hk itself to an exact release via its amends directive:

# hk.pkl
amends "package://github.com/jdx/hk/releases/download/v1.46.0/hk@1.46.0#/Config.pkl"

Hooks route through mise-managed tools, so the same pinned versions run locally and in CI. The pre-commit hook enforces formatting, linting, and type checking before any code reaches the repository.

The layers above block the most common supply chain attack vectors with minimal friction. But static config alone isn't enough — the next post covers automated dependency updates with supply chain security, and a third covers keeping exclusions honest as your dependency tree evolves.

References

mise — tool version manager, used for pinning Node.js, pnpm, and dev tools
mise configuration — mise.toml settings reference
mise lockfile — checksum and provenance lockfile documentation
mise minimum_release_age — cooling-off period for tool releases
pnpm settings — pnpm-workspace.yaml configuration reference
pnpm minimumReleaseAge — cooling-off period for npm packages
pnpm trustPolicy — trust downgrade prevention
pnpm blockExoticSubdeps — blocking transitive exotic sources
pnpm allowBuilds — install script allowlist (replaces v10's onlyBuiltDependencies)
pnpm strictDepBuilds — enforce build script review
pnpm verifyStoreIntegrity — content-addressable store verification
pnpm --frozen-lockfile — lockfile immutability during install
pnpm audit — vulnerability checking against npm advisory database
pnpm .npmrc — auth and registry settings only (v11)
pnpm saveExact — exact version pinning for new dependencies
pnpm engineStrict — engine compatibility enforcement
Corepack packageManager — package manager version enforcement
GitHub Actions security hardening — SHA pinning, third-party action safety
GitHub Actions permissions — least-privilege token scoping
actions/checkout — persist-credentials documentation
hk — git hooks manager
hk configuration — hk.pkl configuration reference
pnpm v10 to v11 migration — allowBuilds migration from onlyBuiltDependencies
pnpm strictPeerDependencies — enforce peer dependency validity
pnpm strictStorePkgContentCheck — validate package contents against store
pnpm preferFrozenLockfile — skip resolution when lockfile is satisfied
pnpm pmOnFail — package manager version enforcement (replaces deprecated settings)

SEO Audit of Two Astro Projects

Thu, 04 Jun 2026 11:52:09 GMT

I reviewed the SEO setup in two Astro projects — a satirical news site (bsnews.fyi) and this blog. Both had basic meta tags in place, but social sharing was broken or incomplete in ways I hadn't noticed. Here's what I found and fixed.

What Was Missing

The audit turned up issues in both projects. Some were things I thought I'd handled, some were just never on my radar.

bsnews:

No twitter:card meta tag — Twitter/X wouldn't render image preview cards
No og:image fallback — pages without a frontmatter image field got no OG image at all
No og:image:width or og:image:height — platforms may fail to render the image
og:type was always "website", even on article pages
Link card pages had an image field in their schema but never passed it to the layout
No article:published_time or article:modified_time meta tags

frangonf.com:

robots.txt was empty — no sitemap pointer for crawlers
No og:site_name or og:locale tags
No og:image:width or og:image:height
No JSON-LD structured data on blog posts
Dead seo.keywords field in the content schema that was never emitted

Nothing catastrophic, but the kind of gaps that mean social previews look wrong and search engines miss context they could use.

Open Graph and Twitter Cards

The minimal OG setup that actually works for a blog:

<meta property="og:type" content="article" />
<meta property="og:title" content="{title}" />
<meta property="og:description" content="{description}" />
<meta property="og:url" content="{canonicalUrl}" />
<meta property="og:image" content="{ogImageUrl}" />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />
<meta property="og:locale" content="en_US" />
<meta property="og:site_name" content="Site Name" />

<meta name="twitter:card" content="summary_large_image" />
<meta name="twitter:title" content="{title}" />
<meta name="twitter:description" content="{description}" />
<meta name="twitter:image" content="{ogImageUrl}" />

The og:image:width and og:image:height tags are easy to skip, but without them some platforms don't render the image reliably. The recommended dimensions are 1200x630.

Twitter falls back to OG tags automatically, but explicit twitter:* tags ensure consistent rendering. I learned this the hard way — bsnews had no twitter:card at all, so shared links showed as plain text previews.

The OG Image Fallback Problem

The bigger issue was that pages without a frontmatter image field produced no og:image tag at all. On bsnews, link cards and most listing pages had no image in social previews.

Fix: A branded fallback image (og-default.png, 1200x630) and a layout change so og:image always emits:

const ogImage = image
  ? new URL(image, Astro.site).href
  : new URL("/og-default.png", Astro.site).href;

I generated the fallback with Python — no ImageMagick on the machine, so I wrote raw PNG bytes with struct and zlib. It's a dark background with colored accent stripes using the bsnews palette. Not pretty, but it works.

Structured Data (JSON-LD)

I added BlogPosting JSON-LD to every blog post on frangonf.com. For bsnews, the article pages already had NewsArticle schema, but link cards were getting WebSite — which doesn't make sense for individual content items.

The minimal BlogPosting schema:

{
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "headline": "Post Title",
  "description": "Post description",
  "datePublished": "2026-06-04T00:00:00Z",
  "author": {
    "@type": "Person",
    "name": "Fran"
  },
  "publisher": {
    "@type": "Organization",
    "name": "Site Name",
    "logo": {
      "@type": "ImageObject",
      "url": "https://site.com/favicon.svg"
    }
  }
}

In Astro, this goes in a <script> tag with set:html:

<script is:inline type="application/ld+json" set:html={JSON.stringify({
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  headline: post.data.title,
  description: pageDescription,
  datePublished: toIsoDateTime(post.data.date),
  author: { "@type": "Person", name: post.data.author ?? "Fran" },
  publisher: {
    "@type": "Organization",
    name: "Fran Gonzalez",
    logo: { "@type": "ImageObject", url: new URL("/favicon.svg", Astro.site).href },
  },
})} />

The set:html approach avoids XSS issues from string interpolation. I found this pattern in a few blog posts while researching — the raw JSON.stringify inside set:html is the recommended way.

Article Metadata

Both projects had og:type hardcoded to "website". For blog posts, it should be "article".

Fix: Added ogType prop to the layout, defaulting to "website":

interface Props {
  ogType?: string;
  publishedTime?: string;
  modifiedTime?: string;
}

const { ogType = "website", publishedTime, modifiedTime } = Astro.props;

Then each blog post page passes the right values:

<BaseLayout
  ogType="article"
  publishedTime={toIsoDateTime(post.data.date)}
  modifiedTime={post.data.updatedAt ? toIsoDateTime(post.data.updatedAt) : undefined}
>

robots.txt

The robots.txt on frangonf.com was empty — just a blank line. It should point crawlers to the sitemap:

User-agent: *
Allow: /

Sitemap: https://frangonf.com/sitemap-index.xml

I also added noindex to both 404 pages via a robots prop on the layout. Error pages shouldn't be indexed.

What I Removed

The blog content schema had a seo.keywords field that was never used anywhere — not in templates, not in meta tags. I removed it. Dead schema fields are noise that make the codebase harder to reason about.

Results

bsnews:

twitter:card, twitter:title, twitter:description, twitter:image — now present on all pages
og:image — now always emits (fallback for pages without images)
og:image:width, og:image:height, og:image:alt — added
og:type — set to "article" on article and link card pages
article:published_time, article:modified_time — added to article pages
Link cards — now pass image and get Article JSON-LD instead of WebSite
404 page — noindex, nofollow

frangonf.com:

robots.txt — populated with sitemap directive
og:site_name, og:locale, og:image:width, og:image:height — added
BlogPosting JSON-LD — added to every blog post
404 page — noindex, nofollow
Dead seo.keywords schema field — removed

Both projects had @astrojs/sitemap configured correctly already, so no changes there. Canonical URLs were also in place on both projects.

What I'd Do Differently

A dedicated SEO.astro component would be cleaner than putting all the meta tags directly in the layout. Right now both projects have the tags inlined in BaseLayout.astro, which works but gets harder to maintain as you add more meta properties.

I also skipped dynamic OG image generation (using something like @vercel/og or astro-og-image). For a blog with a small number of posts, the frontmatter image field plus a fallback is fine. But for a site that publishes frequently, generating images from post titles would be worth the build time.

References

SEO isn't glamorous, but broken social previews are the kind of thing nobody tells you about until you share a link and it looks wrong.

Image Optimization in Astro

Thu, 04 Jun 2026 11:27:30 GMT

The Problem

Images were served from public/images/ with raw HTML <img> tags. No optimization, no responsive sizing, no modern format conversion. A 47kB JPEG shipped as-is to every device.

What Changed

Astro provides built-in image optimization through the <Image /> component and the image() content schema helper. No external plugins required — just sharp as a dependency.

Install Sharp

pnpm add sharp

Move Images to Content Directory

Images now live alongside their posts in src/content/blog/images/ — the Astro-recommended pattern:

src/content/blog/
  images/
    obsidian-nuxt-workflow.jpeg
    obsidian-embed-test.svg
  obsidian-nuxt-content-workflow-example.md

Update Content Schema

The image() helper validates and imports images as metadata objects:

// src/content.config.ts
const blog = defineCollection({
  schema: ({ image }) =>
    z.object({
      // ... other fields
      image: image().optional(),
    }),
});

Update Frontmatter

Relative paths from the content file:

image: ./images/obsidian-nuxt-workflow.jpeg

Replace `<img>` with `<Image />`

---
import { Image } from "astro:assets";
---

<Image
  src={post.data.image}
  alt={post.data.title}
  width={1200}
  height={630}
  class="mt-6 w-full rounded-xl object-cover"
  loading="eager"
  widths={[640, 828, 1200]}
  sizes="(max-width: 640px) 100vw, (max-width: 1024px) 80vw, 1200px"
/>

OG Images

OG meta tags require URL strings. Use getImage() to process the image:

---
import { getImage } from "astro:assets";

const ogImage = post.data.image
  ? await getImage({ src: post.data.image, width: 1200, height: 630 })
  : undefined;
---

<meta property="og:image" content={ogImage?.src} />

Astro Config

// astro.config.ts
image: {
  layout: "constrained",
  responsiveStyles: true,
},

The layout: "constrained" setting enables automatic srcset and sizes generation for all <Image /> components.

Results

Build output shows the optimization:

generating optimized images
  ▶ /_astro/obsidian-nuxt-workflow.xxx.webp (before: 47kB, after: 14kB)
  ▶ /_astro/obsidian-nuxt-workflow.xxx.webp (before: 47kB, after: 20kB)
  ▶ /_astro/obsidian-nuxt-workflow.xxx.webp (before: 47kB, after: 31kB)

47kB → 14kB (70% reduction) at smallest srcset
WebP format generated automatically
3 responsive sizes via widths prop
No CLS — width/height inferred from image metadata

New Posts

For new blog posts, add images to src/content/blog/images/ and reference them in frontmatter:

---
image: ./images/my-cover-photo.jpeg
---

The normalize-obsidian script automatically converts Obsidian embed syntax to relative paths:

![[photo.png]] → ![photo.png](./images/photo.png)

References

Adding Accessibility Testing to My Astro Site

Thu, 04 Jun 2026 11:11:39 GMT

Automated accessibility testing catches what manual review misses. I added axe-core and knip to my Astro project and found issues I didn't know existed.

The Tools

axe-core runs WCAG 2.0/2.1 checks against your rendered pages via Playwright. It catches contrast violations, missing labels, heading hierarchy issues — the kind of stuff screen readers care about.

knip scans your project for unused files, dependencies, and exports. It's not strictly a11y, but dead code is technical debt that makes accessibility harder to maintain. Knip has a built-in Astro plugin that auto-activates when astro is in your dependencies.

Both run in CI with a single command:

pnpm test:a11y   # axe-core on all routes
pnpm lint:knip   # unused code detection

The Surprise: CSS Variables Were Never Loaded

The first thing axe-core found wasn't a contrast issue — it was that my entire Tailwind config was dead code.

I had a src/assets/css/global.css with all my CSS variables, theme colors, and prose overrides. It existed. It was complete. It was never imported anywhere.

The @tailwindcss/vite plugin needs an entry point. Without an import, the CSS was never processed. My dark theme, my gruvbox palette, my custom properties — none of it was reaching the browser.

Fix: One line in BaseLayout.astro:

---
import "../assets/css/global.css";
// ...
---

This is the kind of bug that's invisible if you're not testing. The site looked fine because Tailwind's utility classes still worked. But the CSS custom properties I'd carefully defined? Gone.

Contrast Ratio: The Gruvbox Problem

Once the CSS loaded, axe-core found the real issue: contrast ratios.

The gruvbox palette is designed for terminals, not WCAG compliance. My --ui-text-dimmed color (gruvbox-500: #928374) on the dark background (gruvbox-950: #282828) had a contrast ratio of 4.01:1 — just under the 4.5:1 WCAG AA threshold.

I found a research paper that used a genetic algorithm to find the closest WCAG-compliant alternatives to gruvbox colors. The algorithm found #AB9E8F as the nearest color to #928374 that passes 4.5:1. It preserves the warm, muted gruvbox aesthetic while meeting accessibility standards.

Fix in global.css:

--color-gruvbox-500: #928374; /* 4.01:1 — fails */
--color-gruvbox-500: #ab9e8f; /* 4.5:1+ — passes */

Opacity Classes vs CSS Variables

My Memento Mori component used Tailwind opacity classes (opacity-50, opacity-40, opacity-30) on text elements. This created unpredictable contrast because opacity blends with whatever background is behind it.

The fix was simple: stop using opacity for text dimming. The global CSS already defines a dimming scale:

Variable	Purpose
`--ui-text`	Primary text
`--ui-text-muted`	Secondary text
`--ui-text-dimmed`	Dimmed text (WCAG compliant)

Replacing opacity-50 with text-[var(--ui-text-dimmed)] gives consistent, predictable contrast across all pages.

The /mm route still uses opacity for visual depth (layered backgrounds, hover states). That's intentional — axe-core can't test interactive states, so we disable color-contrast for that route only.

Results

6 routes tested, all passing
knip clean — no unused files or dependencies
1 real bug found (CSS never loaded)
1 contrast fix (gruvbox palette)
15 opacity classes replaced with CSS variables

Run everything with:

pnpm test:all   # vitest + playwright + knip

Accessibility isn't a one-time fix. It's a test that runs every time you push.

Obsidian Embed Test

Mon, 19 Jan 2026 01:09:02 GMT

This image was transformed from Obsidian syntax:

Standard Markdown image syntax also works:

Code blocks should NOT be transformed

Inline code: ![[should-stay.png]] stays as-is.

Fenced code block:

![[also-stays.png|Alt text here]]

These demonstrate that the normalization script preserves code examples.

Using Obsidian with Astro Content Collections

Wed, 08 Oct 2025 00:31:30 GMT

Why Obsidian for Astro?

Obsidian is a markdown editor that treats notes as an interconnected graph. Astro's content collections validate and build those markdown files into static pages. The combination gives you a local-first writing experience with type-safe content.

Content Structure

src/content/blog/
  images/
    my-post-cover.jpeg
  my-post.md

Images live alongside their posts in src/content/blog/images/. The image() schema helper resolves paths relative to the content file:

---
title: "My Post"
image: ./images/my-post-cover.jpeg
---

Frontmatter Schema

Astro validates frontmatter against a Zod schema in src/content.config.ts:

const blog = defineCollection({
  schema: ({ image }) =>
    z.object({
      title: z.string(),
      description: z.string(),
      date: z.coerce.date(),
      draft: z.boolean().default(false),
      tags: z.array(z.string()).default([]),
      category: z.string().optional(),
      image: image().optional(),
      series: z
        .object({
          name: z.string(),
          order: z.number(),
        })
        .optional(),
    }),
});

Obsidian Syntax Transformation

Obsidian uses ![[image.png]] for image embeds. A normalization script converts these to standard Markdown:

pnpm normalize:obsidian

Transforms:

![[photo.png]] → ![photo.png](./images/photo.png)
![[photo.png|Alt text]] → ![Alt text](./images/photo.png)

Code blocks are preserved — ![[example.png]] inside backticks stays as-is.

Tags and Categories

Tags are arrays in frontmatter, rendered as clickable links:

tags:
  - astro
  - markdown
  - tutorial

Categories link to /categories/{name}, tags link to /tags/{name}.

Series

Group related posts with a series object:

series:
  name: Content Management Series
  order: 1

Writing Workflow

Write in Obsidian with wikilinks and image embeds
Run pnpm normalize:obsidian to convert syntax
Set draft: true while iterating
Set draft: false when ready to publish