# alexop.dev - Full Content

> A Personal Blog from a simple web developer

This file contains the full content of all posts for deep context.
For a sitemap overview, see: https://alexop.dev/llms.txt

================================================================================
# BLOG POSTS
================================================================================

--- title: Clean Code Is Sexy Again: Making Your Vue Project AI-Ready description: My Vue MAD 2026 talk, written up. What an agent actually is, and the three things every Vue project needs to get more out of AI: context, feedback loops, and discoverability. The twist is that none of it is new. tags: ['vue', 'ai', 'claude-code', 'architecture', 'testing'] url: https://alexop.dev/posts/clean-code-is-sexy-again-vue-ai-ready ---

# Clean Code Is Sexy Again: Making Your Vue Project AI-Ready



This is the written-up version of the talk I gave at Vue MAD 2026 in Madrid: _Clean Code Is Sexy Again. Making Your Vue Project AI-Ready_. If you would rather watch it, [here is the original recording on YouTube](https://www.youtube.com/watch?v=9bKMqvFRvvI). Otherwise, read on.

## TLDR

- My main take: **what is good for developers is also good for agents**. There was never a separate "AI-ready" checklist. There was just good engineering, and now it pays off twice.
- "You don't have to write code anymore" is half true. It only works if you know your stack _and_ your codebase is built for an agent to work in.
- An agent is not magic. It is a loop: read context, pick a tool, run it, read the result, repeat. Once you have built one you stop asking "how does the magic work" and start asking "why does the same loop fly in one repo and fall apart in another."
- Three things every Vue project should invest in: **context** (AGENTS.md, skills, hooks, a `brain/`), **feedback loops** (types, lint, tests, a real browser), and **discoverability** (vertical feature slices).
- When the agent gets something wrong, fix the factory, not the PR. Add the lint rule, update AGENTS.md, tighten the prompt. The PR fix is one bug. The factory fix prevents the next hundred.

## The line everyone keeps repeating

Everyone keeps saying the same thing: _you don't have to write code anymore._

I think that's half true. In some of my repos AI 10x'd me. In others it produced complete garbage. Same person, same agent, same model, different codebases. It only works if two things are true. First, you have real experience with the stack. I would not let an agent write Rust for me, because I have no idea what good Rust looks like and I could not review it. Second, the codebase has to be shaped so an agent can work in it. A greenfield project is easy. A brownfield project with no tests and 10,000-line components is a mess that AI makes worse, not better, until you clean it up.

A good frame for "where are we" comes from Dan Shapiro's post on the levels of AI-assisted development. It reads like driving automation. Level 0 is spicy autocomplete, the first Copilot. Then agents arrive and it gets a lot better. At the top is the software factory where the agent defines, ships, and fixes on its own.

I put myself at level three. The agent writes most of the code, and I spend my time reviewing and reading every line. Sometimes I feel like the bottleneck. I would not recommend level four or five for anything serious yet, but the pace is real. Two weeks before the talk, the creator of Bun started using Claude Code to rewrite Bun from Zig to Rust. A million lines, in days, almost entirely by an agent.

Triumph or disaster, I don't know. What I know is this is the world we ship into.

## What an agent actually is

Most Vue devs treat agents as a magic box. Magic is the wrong mental model. The best tip I can give you to get better at AI is to build your own coding agent once. Then it stops being magic, and you get a feel for why it does the right thing sometimes and the wrong thing other times. I wrote up the full build in <InternalLink slug="building-your-own-coding-agent-from-scratch">Building Your Own Coding Agent From Scratch</InternalLink>, but here is the whole picture in one image.

The agent is bounded by three things: its context window, the tools you give it, and its ability to verify what it did. That is it. The analogy that unlocks everything is treating the agent like a new engineer joining your team. You would not throw a new hire into your worst legacy module and expect a feature in a week. Same with an agent.

Strip the magic and a **tool is just a function**. Three fields: a description, a schema for the arguments, and the function that runs.

```ts
type Tool = {
  description: string
  schema: Record<string, string>
  execute: (args: Record<string, unknown>) => Promise<string>
}

const TOOLS = new Map<string, Tool>([
  ['read', {
    description: 'Read file with line numbers (not a directory)',
    schema: { path: 'string', offset: 'number?', limit: 'number?' },
    execute: read,
  }],
  ['edit', {
    description: 'Replace old with new in file (old must be unique)',
    schema: { path: 'string', old: 'string', new: 'string' },
    execute: edit,
  }],
  ['bash', {
    description: 'Run shell command',
    schema: { cmd: 'string' },
    execute: bash,
  }],
])
```

Here is the part that demystifies everything: **the model only ever sees the description and the schema.** The `execute` function never leaves your machine. The model cannot run `read()`, it cannot even see it. So how does it "use" a tool? It reads the description and emits a request: "call read with path src/App.vue." Your loop runs the real function and feeds the result back. Which means the description _is_ the prompt. A vague description is a tool the model misuses. Tool descriptions are engineering, not docs.

And the **loop is just recursion**.

```ts
async function agentLoop(messages, systemPrompt, tools = TOOLS) {
  const response = await callApi(messages, systemPrompt, tools)
  const toolResults = await processToolCalls(response.content)

  const newMessages = [
    ...messages,
    { role: 'assistant', content: response.content },
  ]

  // No tool calls → the agent is done
  if (toolResults.length === 0) return newMessages

  // Tool calls → loop with results as the next user turn
  return agentLoop(
    [...newMessages, { role: 'user', content: toolResults }],
    systemPrompt,
    tools,
  )
}
```

Call the API. The model replies with text and maybe some tool requests. Run each one, append the assistant reply and the tool results, and loop. When the model returns no tool calls, it is done. And `messages` is not a database or a session store. It is an array of `{ role, content }`. That array _is_ the agent's memory. Every turn you append to it.

I built a tiny version of this a few months ago and called it **nanocode**, around 350 lines of TypeScript. It is not perfect, but building it is what made the whole thing click.

Once you see an agent this way, the question stops being "how does the magic work" and becomes "why does the same simple loop work brilliantly in one repo and fall apart in another?" That is the rest of this post.

## Clean code isn't nice-to-have anymore

I have been in plenty of projects where people told me "we don't have time to write tests." That argument is over. You do not need new patterns for AI. The patterns you already fight for in code review, the ones the senior dev keeps insisting on, are exactly the patterns that make agents work. A codebase that is hard for humans is hard for agents. Sprawl, hidden coupling, magical state: humans hate it, agents fail at it.

In Vue, three things are worth investing in: **context**, **feedback loops**, and **discoverability**.

## Part 1: Context

The agent is Leonard from _Memento_. Every new chat, the context resets. No long-term memory, no yesterday. So, like Leonard, it has to tattoo the rules where it will read them every single turn.

That tattoo is **AGENTS.md** (or `CLAUDE.md`). It is the first thing you can optimize. But the tattoo space is finite, and most of it is already used before you write a word.

Every model has a context window, and it works best when it is _not_ full. Models degrade as the window fills: recall drops, reasoning slips, the agent starts confusing files. And the window is not empty when you start. The system prompt and the tool definitions already cost around 20k tokens before you type anything. AGENTS.md, skills, MCP servers, and sub-agents all spend from the same pool. In Claude Code you can see exactly where it goes by typing `/context`.

This is why the biggest mistake with AGENTS.md is dumping everything into it: every coding rule, every bug post-mortem, every gotcha, 2000 lines that load on every single turn. A better shape is a thin doorway:

```md
# AGENTS.md

Run `pnpm lint:fix && pnpm typecheck` after changes.

## Stack
Nuxt 4, @nuxt/content v3, @nuxt/ui v3

## Structure
- `app/` — Vue application
- `content/` — Markdown files

## Further reading

**IMPORTANT:** read the relevant doc below
before starting any task.

- `docs/nuxt-content-gotchas.md`
- `docs/testing-strategy.md`
```

The agent loads `testing-strategy.md` only when it writes a test, `nuxt-content-gotchas.md` only when it touches content. That is **progressive disclosure**: the right context at the right time. Two filters before a line goes into AGENTS.md. Can a tool enforce it? Then do not write prose about it. Is it universal or situational? Situational goes in `docs/`. I go deeper on the AGENTS.md-versus-skills split in my <InternalLink slug="claude-code-customization-guide-claudemd-skills-subagents">Claude Code customization guide</InternalLink>, and on why context fills up the way it does in <InternalLink slug="reverse-engineering-humanlayer-rpi-context-engineering">reverse-engineering HumanLayer's context engineering</InternalLink>.

### brainmaxxing

Forget looksmaxxing. We are brainmaxxing: maxing the one thing the agent has, its context. [brainmaxxing](https://github.com/poteto/brainmaxxing) is an open-source kit from a Cursor developer. It is a framework for giving an agent a documented memory, and it has three pieces.

First, a `brain/` folder. Plain markdown. The agent reads from it and writes back to it. There is one `index.md` with wiki-links describing the documentation that exists, and the rest is markdown files for codebase notes, plans, and principles. People found out you do not need RAG or anything complex. The simplest approach, wiki-links and markdown files, works best, and now the agent has a memory. (If you want the theory of why files beat a vector database here, I wrote it up in <InternalLink slug="four-types-memory-coding-agents-claude-code">the four types of memory for coding agents</InternalLink>.)

Second, **skills**. A skill is like a prompt that lives in a markdown file with a name and a description. When you start Claude Code, only the name and description enter the context. When your prompt matches, the body loads. When the body calls a script, the script loads. Three levels of lazy loading, so skills scale. brainmaxxing's `/reflect` skill is a good example: at the end of a session it reviews the conversation and persists what mattered back into `brain/`. So when the agent uses the wrong command and you correct it, you just say "remember this," and it updates its own memory.

Third, **hooks**. Vue has lifecycle hooks like `onMounted`. Claude Code has lifecycle hooks too. brainmaxxing wires a `SessionStart` hook that cats `index.md` into every new session, so the agent boots up already knowing the map. There are many more events. `PreToolUse` can block a destructive command or forbid reading your `.env`. `PostToolUse` can re-lint after an edit. `SessionEnd` could even send you a notification. I cover skills and hooks hands-on in my <InternalLink slug="claude_code_skills_hooks_subagents_vue_workout_tracker">Vue workout tracker walkthrough</InternalLink>.

brainmaxxing also ships **principles**, around 16 markdown files describing how you want code written. One is _boundary discipline_: business logic lives in pure functions, the shell is thin and mechanical. The agent reads them and develops a better taste for your code. You can write your own too.

Claude Code itself now ships something similar, called auto memory: it writes markdown notes about your project automatically. The catch is those files only live on your machine. That is exactly why I like keeping `brain/` in Git. Check it in and the whole team's agent boots up with the same memory on day one. The new hire on Monday starts where the team is, not from zero.

### Want VueUse-style code? Give the agent VueUse

One more trick, and it is bigger than memory. You want the agent to use VueUse or Nuxt UI, but its training data is out of date and it does not know the current API. So give it the source. Clone the library into your repo as a git subtree:

```bash
git subtree add --prefix=repos/vueuse \
  https://github.com/vueuse/vueuse main --squash
```

Then point AGENTS.md at it:

```md
## Reference repositories

- `repos/vueuse/` — when writing new composables, mirror the
  patterns in `repos/vueuse/packages/core/use*/`.
```

Now the agent's pattern matching is anchored on real source instead of stale docs. Agents are post-trained on reading code, not prose. A subtree beats a submodule (no clone-time pain, just files) and beats pointing at `node_modules` (compiled and flattened, the structure is gone). One refinement: tell your editor to ignore `repos/` so you do not accidentally auto-import VueUse internals, and have the agent distill what it learned into a short `agent-patterns/vueuse.md` so it does not re-explore 800 composables every session. This sounds stupid, but once you try it, it works far better than MCPs in my experience. The pattern comes from the Effect team's post, [The One Weird Git Trick That Makes Coding Agents More Effect-ive](https://effect.website/blog/the-one-weird-git-trick-that-makes-coding-agents-more-effect-ive/).

## Part 2: Feedback loops

If an agent does not know when it broke something, it ships whatever compiles. So you give it deterministic ways to check its own work.

**Type safety** is the first lie-detector. A strict `tsconfig` is non-negotiable, and `noUncheckedIndexedAccess` and `exactOptionalPropertyTypes` catch what default strict mode lets through. Types are a compile-time fiction, though, so parse with Zod or Valibot at every untyped boundary: fetch responses, route params, env vars, form input.

**Lint and format** with Oxlint and Oxfmt. They are roughly 50x and 30x faster than ESLint and Prettier, fast enough to run on every save instead of batching at the end. Two Vue lint rules in particular keep components agent-friendly, because nobody, human or agent, can read a 3000-line component:

```ts
'vue/max-template-depth': ['error', { maxDepth: 8 }]
'vue/max-props': ['error', { maxProps: 6 }]
```

A 12-prop component is a god object pretending to be one. I wrote up my full set in <InternalLink slug="opinionated-eslint-setup-vue-projects">my opinionated ESLint setup for Vue projects</InternalLink>, including custom local rules.

Then **tests**. Vitest for units, and the big 2026 win, Vitest browser mode, which runs component tests in a real Chromium via Playwright instead of jsdom. Hover, focus, layout, scroll, all behave like production. The agent can finally trust that "passes in tests" means "works in a browser." I go deep on this in <InternalLink slug="vue3_testing_pyramid_vitest_browser_mode">the Vue testing pyramid with Vitest browser mode</InternalLink>.

Those are four layers. There are 11 more: API mocking, contract tests, E2E, accessibility, visual regression, performance, dead-code detection, and so on. Every one is a signal the agent can chase to green on its own. The cheap ones at the center run on every save, the expensive ones at the edge run in CI. What I now do in a new project is hand the agent my own write-up and say "set up the layers that make sense here."

The full breakdown lives in <InternalLink slug="modern-frontend-quality-pipeline">the modern frontend quality pipeline</InternalLink>.

### The agent as a user

Static checks can be green and the feature can still be broken. Did the modal open? Did the chart render? You need the agent to _be_ the user. Vercel's [agent-browser](https://github.com/vercel-labs/agent-browser) is a browser CLI shaped for agents. One install and the agent has a real Chromium it can drive from the command line.

```bash
npm i -g agent-browser
agent-browser install

agent-browser open localhost:5173
agent-browser snapshot -i          # DOM tree with @refs
agent-browser click @e2            # click by ref
agent-browser screenshot --annotate
agent-browser console              # read page console
```

The snapshot returns the DOM as plain text with refs, the agent clicks by ref, screenshots come back annotated, console errors come back as text. So when there is a bug, you say "reproduce it with agent-browser," and once the agent can reproduce something, fixing it is easy. The same thing a good developer would do.

For this to work the app has to be agent-runnable: the dev server is one command, the port is stable, there is a way to know the server is ready, and test data is seeded so the agent does not hit a login wall. Then "types pass" is no longer the bar. "Works in a browser" is. I built a full version of this into CI in <InternalLink slug="automated-qa-claude-code-agent-browser-cli-github-actions">automated QA with Claude Code, agent-browser, and GitHub Actions</InternalLink>.

Finally, put a **gate** at commit time. Lefthook (or Husky) runs lint, typecheck, and the related tests on every commit, so bad code does not reach `main`. I prefer Lefthook because it runs jobs in parallel and the config is YAML the agent can read and edit, not a shell-script soup. The one rule: no `--no-verify` escape hatch. The whole point of the gate is that it does not open.

```yaml
# lefthook.yml
pre-commit:
  parallel: true
  jobs:
    - run: pnpm oxlint
    - run: pnpm vue-tsc --build
    - run: pnpm vitest related --run {staged_files}
```

## Part 3: Discoverability

Most Vue apps start flat. You run `create vue` and you get `components/`, `composables/`, `stores/`, `views/`, `router/`. Everything is grouped by what a file _is_. That is fine for small apps, but in a real application that `components/` folder grows to 80+ files, and a single "checkout" change is scattered across three folders. The agent has the same problem you do: it greps across the whole tree and most of what it pulls back is noise.

Feature slicing groups by what files _do_, not by what they are. First you find the domains. Imagine a workout tracker: the domains are workout, timers, exercises, and settings. Then each domain owns its own components, composables, and store:

```text
src/features/
├── workout/
│   ├── components/
│   ├── composables/
│   └── store.ts
├── timers/
├── exercises/
└── settings/
```

Finding the domains is the hard part on a big codebase, but once you have them, "change the settings page" means opening one folder. Same files, same code, different addressing. And the win for the agent is concrete. Ask it to "add a streak counter to the active workout." In a flat layout it greps `components/` and `composables/` and pulls back `SettingsForm`, `TimerDisplay`, `useSettings`, maybe 40% relevant. In a feature layout it lists `features/workout/` and gets exactly the files that matter, 100% relevant. No grep, no guess, tokens go to output instead of search.

Folders alone do not keep the agent honest, so add three import rules.

Arrows only point down the layers. Sibling features never import each other; if they share something, it moves to a shared layer like `components/` or `lib/`. And a page that uses two features composes them at the page level rather than letting one feature reach into another. The most important rule is the second one: features stay decoupled. As a bonus, a codebase split this way is already shaped for a micro-frontend approach if you ever need it.

## Where this is heading

AFK coding (away from keyboard) is already here. You write a spec, kick off an agent, and walk away. It runs the tests, hits a failure, fixes itself, runs again, and opens a draft PR with a summary. You review. The work is no longer "me typing." It is "me deciding what should exist, and reviewing what came back."

The loop in practice has humans at the edges and agents in the middle. You align with the business on the spec, the agent breaks the big ticket into vertical sub-tickets, one agent works each slice with TDD inside, a dedicated refactor pass runs (the step LLMs always skip), a QA agent drives the real browser, and then you read the PR. I wrote the long version in <InternalLink slug="how-to-do-afk-coding">how to do AFK coding</InternalLink>.

The most important thing in this loop is what you do when it goes wrong. The agent ships a bug, and the instinct is to fix the bug, merge, and move on. That instinct is wrong.

**Fix the factory, not the PR.** A bug is not a bug, it is a factory defect. Add an ESLint rule that catches that whole class of mistake. Update AGENTS.md so the convention is written down. Tighten the slash command or the prompt if that is where it leaked. The PR fix is one bug. The factory fix prevents the next hundred. And if the codebase is messy in the first place, use the agent to refactor it before you expect any of this to work. Every PR review teaches the factory, and the codebase gets smarter over time.

As a test of all this, the week before the talk I tried to port [React Ink](https://github.com/vadimdemedes/ink) (declarative components for terminal UIs) to Vue, using AI only. It worked surprisingly well.

The approach combined everything above. I vendored Ink, Vue core, and VueUse into `repos/` as read-only source. I used a `brain/` vault for gotchas and an api-tracker. And because React Ink has a lot of tests, I ported the _tests_ first: each Ava scenario became a Vitest test at the behavior level, not the React implementation. Run it, red, no implementation yet. Then translate the implementation, JSX to SFC, hooks to composables. Run it, green. Then reflect the learnings back into `brain/` so the loop sharpens itself. I would not publish it as a real library without going back and understanding every line first, but as a proof that you can port a well-tested React library to Vue mostly AFK, it holds up.

I even added a `Stop` hook that fires when a turn ends and spawns a second, headless Claude in the background to read the session transcript and write only new durable learnings into `brain/`. The one gotcha is that the child also ends a turn, which would fire the hook forever, so an env flag marks the child and the hook bails when it sees it. The project updates its own docs while I get coffee.

## The twist

This talk was not really about AI. I tricked you.

None of it is new. Testing, TDD, feature-based architecture, strict types, small components: these are the things senior engineers have fought for in code review for twenty years. They were good before a single agent existed. The only thing that changed is the payoff. The same discipline that used to make a codebase pleasant for the next human now also makes it tractable for an agent, so every hour you spent caring about architecture quietly started earning twice.

That is the whole bet. Tight **context**, plenty of **feedback loops**, real **discoverability**. Which of them is your project missing? Come find me and tell me what your AGENTS.md looks like.

---

--- title: How VS Code Copilot Chat Compacts Your Conversation description: A reference on conversation compaction in VS Code Copilot's agent (now in microsoft/vscode under extensions/copilot): when it triggers, the budget math, what survives, the 8-section summary format, and the config keys. Traced from the source, with interactive diagrams. tags: ['ai-agents', 'copilot', 'context-engineering', 'vscode'] url: https://alexop.dev/posts/how-vscode-copilot-chat-conversation-compaction-works ---

# How VS Code Copilot Chat Compacts Your Conversation



LLMs have limited context windows. When an agent session grows too long, VS Code Copilot Chat uses **compaction** to summarize older history while keeping recent work verbatim. I traced exactly how it works from the source.

<Alert type="note">
The standalone `microsoft/vscode-copilot-chat` repo was **archived in May 2026**. The agent code now lives in the main [microsoft/vscode](https://github.com/microsoft/vscode) repo under `extensions/copilot/`, and it has changed since the standalone repo froze. Everything below is traced against the current `extensions/copilot` source.
</Alert>

**Source files** (all under `extensions/copilot/`):

- `src/extension/intents/node/agentIntent.ts` — budget math, trigger logic
- `src/extension/prompts/node/agent/summarizedConversationHistory.tsx` — prompt, LLM call, history selection, re-insertion
- `src/extension/prompts/node/agent/backgroundSummarizer.ts` — the async state machine and thresholds
- `src/extension/prompts/node/agent/simpleSummarizedHistoryPrompt.tsx` — the Simple-mode fallback

<Alert type="note">
Microsoft moves fast. Treat line numbers as approximate and the thresholds as true the day I looked.
</Alert>

## First, what is `@vscode/prompt-tsx`?

Compaction makes no sense until you understand the renderer underneath it. [`@vscode/prompt-tsx`](https://github.com/microsoft/vscode-prompt-tsx) (the repo pins `^0.4.0-alpha.8`) is a **budget-aware prompt renderer**. Instead of concatenating strings into a `messages` array, you author the entire prompt as a tree of TSX components — a `PromptElement` — and the renderer flattens it into the `ChatMessage[]` that goes to the model, *fitting it to the token budget for you*.

Here's the actual agent prompt, lightly trimmed (`agentPrompt.tsx`):

```tsx
return <>
  {baseInstructions}

  <ChatToolCalls       flexGrow={2} priority={899} toolCallRounds={ctx.toolCallRounds}
                       truncateAt={maxToolResultLength} />
</>;
```

Two numbers on each element do the work:

- **`priority`** — when the rendered tree is over budget, the renderer drops the **lowest-priority** content first. The current user message (`900`) and the latest tool calls (`899`) outrank older history (`700`), which outranks boilerplate system instructions. Same-priority siblings are pruned in declaration order.
- **`flexGrow`** — controls how *leftover* budget is distributed. A `flexGrow` element renders **after** its siblings and receives whatever budget they didn't use. So the user message and tool calls (`flexGrow={2}`) get first claim on the window; conversation history (`flexGrow={1}`) fills the remainder.

Every element's `render(state, sizing)` is handed a `PromptSizing` with `tokenBudget` and an async `countTokens()`, so an element can measure itself and trim to fit. That's literally how tool results cap themselves at 50% of the window (`truncateAt={maxToolResultLength}` above), and there are helpers for the common cases:

```tsx
<TokenLimit max={2000}>{/* hard cap on a subtree */}</TokenLimit>
<PrioritizedList priority={p} descending={false}>{rounds}</PrioritizedList>
```

`TokenLimit` caps a subtree; `PrioritizedList` hands a list of children descending (or ascending) priorities — exactly how conversation rounds are ranked so the oldest get pruned first; `TextChunk` keeps as much of a long string as fits.

Pruning is graceful — until it isn't. When even the highest-priority content won't fit, prompt-tsx throws a **`BudgetExceededError`**. That exception is the signal the agent loop catches to escalate from "just prune" to "compact the history" — which is where the rest of this post begins.

## Overview

Compaction is the escalation when prompt-tsx's pruning isn't enough. There are two automatic triggers — **both on by default now** — plus the user-initiated `/compact` command:

| Path | Trigger | Default? |
| --- | --- | :---: |
| **Foreground summarize** | `BudgetExceededError` while rendering (hard overflow) | ✅ on |
| **Background compaction** | post-render context ≥ ~80% (jittered `0.78–0.82` with a warm cache; ≥`0.90` cold-cache emergency) | ✅ on |
| **Manual `/compact`** | user runs the command | — |

<Alert type="note">
This is the biggest change since the standalone repo. The old build gated background compaction behind a `chat.backgroundCompaction` experiment and had a separate `≥85%` "proactive inline" experiment. **Both flags are gone.** Background compaction now ships on by default (gated only by the master summarization switch), and the inline mechanism it used became *how* background compaction works rather than a separate path.
</Alert>

## When it triggers

The budget is computed from config and the effective context size, then trimmed for tools:

```typescript
const baseBudget = Math.min(
  summarizeThresholdTokens ?? effectiveMaxTokens,
  effectiveMaxTokens                     // clamp: never above the real max
);
// 10% safety margin on the message portion when tools are present
const messageBudget = Math.max(1, Math.floor((baseBudget - toolTokens) * 0.9));
```

Two subtleties: `effectiveMaxTokens` honors the user's Context Size picker (not just the model's raw `modelMaxPromptTokens`), and the threshold config is interpreted as either a **ratio** (`0–1`, a fraction of the window) or an **absolute token count** (`≥100`) — the ambiguous gap in between throws.

Drag the fill level to see which path fires:

**Foreground** is the safety net — it catches the hard overflow and recovers:

```typescript
} catch (e) {
  if (e instanceof BudgetExceededError && summarizationEnabled) {
    result = await renderWithSummarization(`budget exceeded(${e.message})`);
  }
}
```

**Background compaction** exists to avoid the cost of "render, fail, re-render." After each turn renders, it checks the post-render context ratio and, if you're over the threshold, kicks off summarization *in the background* so the compacted result is ready to apply on the next render. Two details make it cache-friendly:

- **Cache-warmth gating + jitter.** It only fires at the normal ~`0.80` threshold when the prompt cache is warm (a completed tool-call round this turn), and it *jitters* the exact trigger across `0.78–0.82` so it doesn't always fire at the same boundary. With a cold cache it waits for the `≥0.90` emergency line. (Thresholds live in `BackgroundSummarizationThresholds`.)
- **Apply-min ratio.** A finished background summary is discarded if the context ratio has since dropped below `0.65` — e.g. you switched to a larger-context model and no longer need it.

Mechanically, background compaction doesn't make a separate "summarize this" request. It folds a "compact now" instruction into a forked copy of the *same* render (for prompt-cache parity) and parses a `<summary>` block back out of the model's reply.

## How it works

1. **Pick the cut point.** Render history in reverse (newest first), keeping recent rounds verbatim.
2. **Exclude the overflowing round.** With multiple tool rounds, drop the last one — it's what pushed over the limit.
3. **Stop at the previous summary.** Walking back, break at the first round that already has a `.summary`. Compaction *compounds* instead of re-summarizing from scratch.
4. **Generate the summary.** Call the LLM with the structured format below.
5. **Re-insert.** Wrap the summary in a `<conversation-summary>` user message that replaces the older turns; store it as turn metadata so it survives the next turn.

```typescript
// Excluding the round that blew the budget:
if (toolCallRounds && toolCallRounds.length > 1) {
  toolCallRounds = toolCallRounds.slice(0, -1);          // last round overflowed
  summarizedToolCallRoundId = toolCallRounds.at(-1)!.id; // summarize from the prior one
}
```

## What gets kept vs summarized

- **Recent rounds** → kept verbatim, so the model picks up mid-task.
- **The round that overflowed** → excluded from the summary.
- **Everything before the previous summary** → already represented; not re-included.
- **Tool results** → truncated at `maxToolResultLength`, which the agent loop sets to **50% of the model's max prompt tokens** (`modelMaxPromptTokens * 0.5`), keeping the head and tail of long outputs (a 40/60 split) and dropping the middle. (The flat `2000` you may see in the source is a *different* feature — the panel's chat-summary renderer — not in-loop compaction.)

## The summary format

The summarization is a real LLM call on the **same model the conversation uses**, at `temperature: 0` (streaming is intentionally *not* disabled — there's even a regression test asserting the request doesn't force `stream: false`). The prompt doesn't ask for "a summary" — it demands an 8-section handoff document, emitted inside a `<summary>` block after a separate `<analysis>` block:

```text
1. Conversation Overview   — objectives, session context, intent evolution
2. Technical Foundation    — core tech, frameworks, architectural patterns
3. Codebase Status         — each file touched: purpose, state, key code
4. Problem Resolution      — issues hit, solutions, debugging context
5. Progress Tracking       — done vs. partially done vs. validated
6. Active Work State       — exactly what was being worked on last
7. Recent Operations       — last commands, tool results, pre-summary state
8. Continuation Plan       — pending tasks and the immediate next step
```

There are two modes: **Full** (sends tool definitions with `tool_choice: 'none'`) and **Simple**. If Full fails, it falls back to Simple.

## The breadcrumb

Compaction is lossy — the verbatim history is gone. So the summary carries a pointer to the full transcript on disk:

```typescript
summary += `\nIf you need specific details from before compaction (such as exact
code snippets, error messages, tool results, or content you previously generated),
use the ${ToolName.ReadFile} tool to look up the full uncompacted conversation
transcript at: "${transcriptPath}"`;
// ...then appends the transcript's current line count and an example call
```

This breadcrumb is added whenever the session has an on-disk transcript path (no experiment flag — that gate existed in the old build but is gone now). It's appended exactly once, at summary-creation time, and *baked* into the frozen summary text — so later renders replay it verbatim, preserving Anthropic's prompt cache. The summary is the fast path; the transcript file is the escape hatch the model reads only when it needs an exact detail. Same instinct as <InternalLink slug="stop-bloating-your-claude-md-progressive-disclosure-ai-coding-tools">progressive disclosure</InternalLink>: cheap index in context, expensive detail on demand.

## Model-specific gotchas

| Model | Handling |
| --- | --- |
| **Opus** (`claude-opus*`) | Extra instruction: do not call tools, only write text. |
| **Anthropic + thinking** | Last thinking block preserved and re-attached as the first thinking block after the summary. |
| **Anthropic + `tool_search`** | Client-side `tool_search` tool-use/result pairs stripped before the call, or Anthropic 400s. |
| **Gemini** | Orphaned `function_call`s (whose results got pruned) stripped, or it 400s. |
| **GPT-4.1** | A "keep going" reminder is appended after the summary. |
| **Prompt caching** | Summary "baked" once so later renders don't bust Anthropic's cache. |
| **PreCompact hook** | Fires before summarizing; can archive the transcript. Errors never block. |

## Settings

| Config key | Default | What it does |
| --- | --- | --- |
| `chat.summarizeAgentConversationHistory.enabled` | on | Master switch — gates both foreground *and* background compaction. |
| `chat.advanced.summarizeAgentConversationHistoryThreshold` | model max | Lower the budget that triggers compaction (ratio `0–1` or absolute tokens `≥100`). |
| `chat.advanced.agentHistorySummarizationMode` | auto | Force `simple` (or `full`) summary mode. |
| `chat.conversationCompaction.usePrismCompaction` | experiment | Route compaction through a separate "Prism" trajectory-compaction model. |
| `chat.conversationCompaction.prismModelFilter` | (model list) | Which models the Prism path applies to; falls back to the agent endpoint otherwise. |

<Alert type="note">
Gone since the standalone repo: `chat.backgroundCompaction` and `chat.advanced.agentHistorySummarizationInline`. Background compaction is no longer a separate experiment — it's on by default under the master switch.
</Alert>

## Compared to Claude Code

Same problem, different taste. Claude Code's `/compact` also summarizes history into a block — see <InternalLink slug="four-types-memory-coding-agents-claude-code">The Four Types of Memory for AI Agents</InternalLink>. Copilot leans harder on two ideas worth stealing if you build your own loop (<InternalLink slug="building-your-own-coding-agent-from-scratch">like this</InternalLink>): **prune by priority before you summarize**, and **make the lossy summary recoverable** with a breadcrumb to the raw history.

---

--- title: Open Knowledge Format: I Already Do This, and Now It Has a Name description: Google Cloud just shipped the Open Knowledge Format: a directory of Markdown files with YAML frontmatter as portable knowledge for AI agents. I already run this in every repo. Here is why having an actual format is the good part. tags: ['ai-agents', 'claude-code', 'context-engineering', 'knowledge-management'] url: https://alexop.dev/posts/open-knowledge-format-markdown-frontmatter-agent-knowledge ---

# Open Knowledge Format: I Already Do This, and Now It Has a Name



## TLDR

- Google Cloud shipped the **Open Knowledge Format (OKF)**: a directory of Markdown files with YAML frontmatter that any agent can read and any human can edit. No SDK, no runtime, no database.
- I already do something like this in every coding repo. Markdown files the agent reads before it works, frontmatter on top, linked together. OKF is that pattern with a name and a tiny spec.
- The part I actually like is the **frontmatter**. One required field (`type`), a handful of optional ones, and now the files are queryable instead of just readable.
- This is **semantic memory** for agents, standardized. It's the same idea as `CLAUDE.md` and `AGENTS.md`, pushed one step toward "portable between tools."
- A format is worth more than another knowledge service. You can write OKF by hand today without installing anything, and that's the whole point.

## I already keep my knowledge in Markdown

I don't write much code by hand anymore. I delegate to a coding agent and review the output. And the single thing that decides whether that goes well is what the agent knows about my project before it starts.

So every repo I work in has the same shape. A `CLAUDE.md` at the root. A `docs/` folder with architecture notes, conventions, gotchas, the stuff that lives in the heads of the people who've been here a while. The agent reads those files, then does the work. When it learns something new, it writes it back. Plain Markdown, checked into git, sitting next to the code it describes.

This works really well. It's simple, it's versioned, and I can read it myself in any editor. No vendor, no lock-in, no "open the catalog UI to see the metadata."

And I've gone further than a bare `docs/` folder. On some projects I ran [brainmaxxing](https://github.com/poteto/brainmaxxing): a Markdown vault the agent reads at session start and writes back to when it learns something. It ships a little learning loop, `/reflect` after a session, `/ruminate` over old conversations, `/meditate` to prune stale notes, and because the vault is also an Obsidian vault, I can open the agent's memory and read it like my own notes. The OKF post names this exact species in passing: "Obsidian vaults wired to coding agents." It worked really well. But it was bespoke. My folder names, my conventions, my skills, none of it was built to travel to your repo or a different agent.

The thing I never had was a _format_. My `docs/` folder and your `docs/` folder both look like Markdown, but they don't agree on anything. What fields go on top of a file? What does `index.md` mean? Nothing was written down. It just worked because I was the only one reading it.

That's the gap [Open Knowledge Format](https://cloud.google.com/blog/products/data-analytics) is trying to fill, and after reading the spec I think it's a good move.

## What OKF actually is

OKF is a directory of Markdown files. Each file is one concept: a table, a dataset, a metric, a runbook, an API, whatever you want to capture. The file path _is_ the concept's identity.

```text
sales/
├── index.md
├── datasets/
│   └── orders_db.md
├── tables/
│   ├── orders.md
│   └── customers.md
└── metrics/
    └── weekly_active_users.md
```

Every concept file has a small block of YAML frontmatter and a Markdown body. The frontmatter holds the few fields that need to be queryable; the body holds everything else.

```markdown
---
type: BigQuery Table
title: Orders
description: One row per completed customer order.
resource: https://console.cloud.google.com/bigquery?...&t=orders
tags: [sales, revenue]
timestamp: 2026-05-28T14:30:00Z
---

# Schema

| Column        | Type   | Description                              |
|---------------|--------|------------------------------------------|
| `order_id`    | STRING | Globally unique order identifier.        |
| `customer_id` | STRING | FK to [customers](/tables/customers.md). |

# Joins

Joined with [customers](/tables/customers.md) on `customer_id`.
```

That's it. Concepts link to each other with normal Markdown links, which turns the folder into a graph of relationships, not just a tree. Two filenames are reserved: `index.md` for an overview at each level, and `log.md` for a running history of changes. The whole v0.1 spec fits on one page.

If you've used Obsidian, or written a `CLAUDE.md`, or kept an `AGENTS.md`, the shape is immediately familiar. That's deliberate. OKF isn't inventing a new thing, it's writing down the small set of conventions that make the existing thing interoperable.

<Alert type="note">
OKF v0.1 comes from the Google Cloud Data Cloud team, and the reference tooling is data-flavored: an agent that walks a BigQuery dataset and drafts a concept file per table, plus a static HTML visualizer. Ignore the BigQuery framing if it's not your world. The format is just Markdown and frontmatter, and nothing about it is tied to a database or a cloud.
</Alert>

## The frontmatter is the part I like

The body of these files I already write. Markdown is Markdown. The piece OKF adds that I didn't have is the agreed-upon frontmatter.

OKF requires exactly one field on every concept: `type`. Everything else is optional: `title`, `description`, `resource`, `tags`, `timestamp`. That's a good ratio. One thing you must do, a handful of things you can do, and the body is yours.

Why does this matter? Because frontmatter makes the files _queryable_ without parsing prose. An agent can filter "every concept where `type: metric`" or "everything tagged `revenue`" or "what changed since this `timestamp`" without reading the bodies first. It's the same trick I use on this blog. Every post has frontmatter with `title`, `description`, `tags`, `pubDatetime`, and that's what powers the tag pages and the related-posts logic. The body is for humans; the frontmatter is for the machine.

I keep coming back to one line from the OKF principles: it defines _the interoperability surface, not the content model_. It tells you the file must declare a `type`. It does not tell you what types exist or what your tables should say. That restraint is exactly right. The places I've seen "metadata standards" fail are the ones that try to model your whole domain for you.

## This is semantic memory, standardized

If you read my post on <InternalLink slug="four-types-memory-coding-agents-claude-code">the four types of memory for AI agents</InternalLink>, OKF slots in cleanly. It's **semantic memory**: the agent's stable knowledge about your project that's true independent of any single session. Facts, conventions, schemas, join paths. Loaded in so the agent doesn't relearn your project every single time.

The academic version of semantic memory always reaches for vector databases and knowledge graphs. But in practice, the thing that actually ships is Markdown files. OKF agrees, and then goes one further: it says the Markdown should carry frontmatter and link to other Markdown, so the flat pile of facts becomes a navigable graph.

The two reserved filenames map onto patterns I already lean on:

- **`index.md`** is progressive disclosure. The agent reads the index for a folder, sees what's there, and only opens the specific concept files it needs. That's the same move I argued for in <InternalLink slug="stop-bloating-your-claude-md-progressive-disclosure-ai-coding-tools">Stop Bloating Your CLAUDE.md</InternalLink>: don't dump everything into context, give the agent a lightweight map and let it pull the detail on demand.
- **`log.md`** is a slice of **episodic memory**. A chronological record of what changed and when, sitting right next to the knowledge it describes.

So OKF isn't a new idea so much as the convergence point of three things I already do: a `CLAUDE.md`-style knowledge file, progressive disclosure through an index, and frontmatter for queryability. Seeing them written down as one small spec is what makes it click.

<Alert type="tip">
Andrej Karpathy framed the why of this whole pattern best in his LLM Wiki gist: "LLMs don't get bored, don't forget to update a cross-reference, and can touch 15 files in one pass." The bookkeeping that makes humans abandon their personal wikis is exactly the work LLMs are good at. Let the agent maintain the knowledge base; you curate it.
</Alert>

## A format beats another service

The OKF post makes one argument I fully agree with: the answer here is a _format_, not a platform.

A format is something anyone can produce without an SDK, anyone can consume without an integration, and that survives moving between tools and orgs because it's just files in version control. A platform is something you log into, that owns your data, that you integrate against. Every catalog vendor today ships the second thing: its own API, its own schema, its own export format, and your knowledge is locked behind whichever surface created it.

OKF is the first thing. A bundle of OKF documents is just Markdown, just files, just YAML. Readable in any editor, renderable on GitHub, shippable as a tarball, mountable on any filesystem. The producer and the consumer are independently swappable: a human writes a bundle, an agent reads it, or an export pipeline writes it and a visualizer reads it. The file is the contract.

This is why I'm bullish even though the obvious objection is right there. Yes, it's "another standard," and yes, it comes from a giant cloud vendor. But the value of a knowledge format comes from how many parties speak it, not from who wrote it down first. And the cost of trying it is basically zero, because you don't install anything. You rename a couple of conventions in a folder you probably already have.

## What I'd actually do with it

I'm not going to rewrite my repos overnight, and you shouldn't either. But here's what's worth doing today:

- **Add frontmatter to the docs you already keep.** Even just `type`, `title`, `description`, `tags`, `timestamp`. It costs nothing and makes the files queryable.
- **Add an `index.md` per folder.** Give the agent a map before it opens individual files. This pays off immediately, format or no format.
- **Keep a `log.md` for the areas that change a lot.** A running changelog the agent reads and appends to.

None of that requires "adopting OKF." It's just good hygiene for a Markdown knowledge base that an agent reads. The format is what lets your folder and my folder cooperate later, if the ecosystem of producers and consumers actually shows up. That's the open question. v0.1 is a starting point, not a finished standard, and a format only earns its name if enough tools speak it.

## Wrapping up

- OKF is a directory of Markdown files with YAML frontmatter, designed as portable knowledge for AI agents. No SDK, no runtime, lives in git.
- I already run this pattern in every repo. The new part is having an agreed format, especially the **frontmatter**, which makes the files queryable instead of just readable.
- It's **semantic memory** for agents, with `index.md` for progressive disclosure and `log.md` for history. The same moves I use in my `CLAUDE.md` setup, written down.
- A format beats another knowledge service, because anyone can produce and consume it without an integration. The catch is adoption: a format is only worth as much as the number of tools that speak it.

If you keep an `AGENTS.md` or a `docs/` folder your agent reads before it works, you're already 90% of the way to an OKF bundle. Throw some frontmatter on top and you're there. Are you keeping your agent's knowledge as plain files yet, or is it still locked in someone's catalog?

---

--- title: The Four Types of Memory for AI Agents (and How Claude Code Implements Each) description: Working, semantic, procedural, episodic. The CoALA framework splits agent memory into four kinds. Here is what each one is, and how Claude Code actually implements them on disk. tags: ['ai-agents', 'claude-code', 'context-engineering', 'memory'] url: https://alexop.dev/posts/four-types-memory-coding-agents-claude-code ---

# The Four Types of Memory for AI Agents (and How Claude Code Implements Each)



## TLDR

- Memory is what separates a chatbot from an agent. A chatbot answers. An agent answers _shaped by_ what it knows about your project and what it learned last time.
- There's a clean framework for this from a Princeton team called CoALA, and it splits agent memory into four types: **working, semantic, procedural, episodic**.
- This post defines all four in general, then shows how **Claude Code** implements each one as something you can point at on disk.
- Claude Code maps every type to plain files and commands, not a vector database. The most interesting frontier is episodic memory and _consolidation_, the thing Anthropic calls "dreaming."
- Match the memory to the job. A thermostat needs one type. A coding agent wants all four.

## Why I care about agent memory

I don't write much code by hand anymore. I delegate to a coding agent and review the output. And the thing that decides whether that delegation is great or painful isn't the model's raw IQ, it's what the agent remembers.

Two failure modes I hit constantly:

- I explain a project gotcha, we fix it together, and the next session the agent makes the exact same mistake. Yesterday's context is gone.
- I dump everything I know into one giant file so it _can't_ forget, and now the agent is drowning in noise and misses the thing that actually matters.

Both are memory problems. And "memory" turns out not to be one thing. It's four. I picked this framing up from an IBM Technology video, [The Four Types of Memory Every AI Agent Needs](https://www.youtube.com/watch?v=BacJ6sEhqMo), which is the plain-language on-ramp. The rigorous version is the [CoALA framework](https://arxiv.org/abs/2309.02427) (Cognitive Architectures for Language Agents) out of Princeton. Both land on the same four buckets and the same human-memory analogy. I'm going to define each type, then show how Claude Code implements all four, because seeing them as concrete files on disk is where it clicks.

## The human version first

The framework lifts straight from how we remember things, so start there:

- **Short-term or working memory**: what's active in your head right now. The sentence you're reading. Volatile, small.
- **Semantic memory**: factual knowledge. "Python is interpreted." You just know it, no lookup.
- **Procedural memory**: learned skills. Riding a bike, driving a car. You don't re-derive it each time.
- **Episodic memory**: personal experience. The time I spent three hours debugging a Kubernetes cluster before realizing I was pointing at the wrong cluster the whole time.

Well-designed agents need the same four, and CoALA gives them the same names. The parallel does real work later in the post: humans forget effortlessly and usefully, and consolidate memory in sleep. Agents can't do either yet, which is exactly what the "dreaming" features are trying to fix.

## The four types, defined

### Working memory

Working memory is the agent's active scratchpad for the current decision cycle. CoALA puts it precisely: it "maintains active and readily available information as symbolic variables for the current decision cycle." In practice it's everything the model can see right now: the running conversation, the system prompt, tool and command outputs, and any files or memory loaded into the prompt.

The analogy everyone uses is RAM. Fast, immediately accessible, but volatile: when the session ends, it's gone. And it's bounded by the context window. Context windows are huge now, a million tokens or more, but "huge" isn't "infinite." Stuff too much in there and quality drops as the model loses track of things buried in the middle.

The key thing: working memory is the bridge every other memory passes through. The other three types are stores on disk. Working memory is what they get loaded _into_.

Every agent has working memory. So does every chatbot: it's just the context window. So working memory alone doesn't make something an agent. The question is what else you add.

<Alert type="note">
Working memory is the one most people already understand, so I won't belabor it. If you want the deep version (why your context is "just an array of tokens" and how to keep noise out of it) I wrote that up in <InternalLink slug="stop-bloating-your-claude-md-progressive-disclosure-ai-coding-tools">Stop Bloating Your CLAUDE.md</InternalLink>.
</Alert>

### Semantic memory

Semantic memory is the agent's stable knowledge about the world and itself. CoALA defines it tersely: it "stores an agent's knowledge about the world and itself." These are the general facts, rules, conventions, and reference material that are true independent of any single interaction.

The academic version talks about vector databases and knowledge graphs. RAG counts too. But in a lot of production agentic systems today it's something much simpler: Markdown files. Project architecture, coding conventions, build commands, which frameworks to use, and just as important, what _not_ to do. Loaded into working memory up front, every session. Without it, the agent has no persistent knowledge to draw from, so it's doomed to relearn your project every single time.

### Procedural memory

Procedural memory is the agent's knowledge of _how_ to do things. Not facts. Steps.

The paper splits this in two. CoALA is explicit: "Language agents contain two forms of procedural memory: implicit knowledge stored in the LLM weights, and explicit knowledge written in the agent's code." You can't really edit the implicit half. Fine-tuning is the only lever and it's expensive. The explicit half is the one you control, the agent's own code and the workflows you author.

The paper is blunt about the risk here: writing to procedural memory is the dangerous kind of learning. A new fact or note is harmless. A new step changes how the agent behaves. CoALA calls it "significantly riskier than writing to episodic or semantic memory, as it can easily introduce bugs or allow an agent to subvert its designers' intentions." So I author and review skills by hand. I don't let the agent rewrite its own procedures on its own.

### Episodic memory

Episodic memory is the agent's record of specific past experiences. CoALA says it "stores experience from earlier decision cycles." The paper gives examples: training input-output pairs, history event flows, game trajectories from previous episodes, or other representations of the agent's experiences. Unlike semantic memory (general facts), episodic memory is tied to particular events the agent lived through, retrieved to inform later behavior.

The naive version is to save every conversation transcript and grep it later. That technically counts, but it's useless. Nobody wants to search a 45-minute debugging log to find the one line that mattered. What good systems do is **distill**. Instead of a full transcript you get:

> Last time we debugged the auth module, the bug was in the middleware layer.

That's compressed experience, and it's where memory starts to look like genuine learning.

Episodic is the hardest type to get fully right, and the hard part isn't storing. It's _forgetting_. What do you delete? When does a note go stale? Humans forget effortlessly, and annoying as that is, it's useful. For an agent, forgetting is an engineering problem nobody has fully solved. The paper says the same: "modifying and deleting (a case of 'unlearning') are understudied in recent language agents." Keep that line in mind. It's the gap Claude Code's newest features are reaching toward.

## How Claude Code implements all four

To prove this framework isn't theoretical, here's Claude Code implementing all four buckets. [Claude Code](https://code.claude.com/docs/en/memory) is the cleanest tool to learn on, because each memory type is something you can point at on disk: a file, a directory, or a command.

- **Working**: the context window you watch fill up. Run `/context` to see what's eating space. `/clear` wipes it entirely. If you run long, `/compact` summarizes the history to buy room (or the automatic version kicks in near the ceiling). The docs say it plainly: the context window holds "conversation history, file contents, command outputs, CLAUDE.md, auto memory, loaded skills, and system instructions."
- **Semantic**: `CLAUDE.md`. It's a _hierarchy_: a user-level `~/.claude/CLAUDE.md` for your defaults, a project-level `./CLAUDE.md` checked into the repo for the team. Both load every session. You keep it lean with `@`-imports (`See @README.md ... Git workflow: @docs/git-instructions.md`) instead of pasting everything inline. There's no enforced token limit, but shorter is better for adherence. I go deep on the CLAUDE.md-vs-skills split in <InternalLink slug="claude-code-customization-guide-claudemd-skills-subagents">my Claude Code customization guide</InternalLink>.
- **Procedural**: **skills**, a folder with a `SKILL.md` (YAML frontmatter holds a `description` of what it does and when to use it, the body holds the steps). The clever bit is **progressive disclosure**. The agent only sees a lightweight index, name and description, about a hundred tokens each. When a task matches, it loads the full instructions. Linked files and scripts load only when the steps call for them. That's how you give an agent fifty capabilities without paying for fifty on every turn.

```text
.claude/skills/
  code-review/
    SKILL.md        ← name + description always visible (~100 tokens)
    checklist.md    ← loaded only when the skill runs
    review.py       ← pulled in only if the steps call for it
```

- **Episodic**: **Auto memory** (on by default, needs Claude Code v2.1.59+). The agent writes distilled notes for itself to a memory directory you own, "build commands, debugging insights, architecture notes, code style preferences, and workflow habits," and "intelligently decides what information is useful to remember for future conversations." That's distillation, not transcript-dumping. The first 200 lines (or 25KB) load at session start as an index. Topic files load on demand. Run `/memory` to browse and prune by hand.

Claude Code's distinctive choice is **minimal-by-default**: file hierarchy plus imports for semantic, progressive disclosure for procedural, passive distillation loaded as an index for episodic. And it's pushing the forgetting frontier with **Dreams** (Managed Agents API, research preview, billed per token): an on-demand asynchronous job you trigger via the API reads the memory store plus the session transcripts you supply, merges duplicates, replaces stale entries, and writes a new store. It never touches the input, so you review the output and keep it or throw it away. That's the prune-by-hand step, done by the model, and it's an on-demand job you invoke, not a schedule that fires on its own.

## Claude Code's four types at a glance

| Memory type | Where it lives in Claude Code | Manage it with |
| --- | --- | --- |
| **Working** | The context window | `/context`, `/clear`, `/compact` |
| **Semantic** | `CLAUDE.md` hierarchy (user + project) + `@`-imports | Edit the files |
| **Procedural** | Skills (`SKILL.md`) + progressive disclosure | Author by hand in `.claude/skills/` |
| **Episodic** | Auto memory (distilled notes, index-loaded) + Dreams consolidation | `/memory` |

The pattern is the point: every type maps to plain files and commands, not a vector database. Semantic and procedural are Markdown _you_ write; episodic is Markdown the _agent_ writes for itself. And the newest frontier is consolidation, the "dreaming" layer that automates forgetting, an on-demand Dreams job that merges duplicates and replaces stale entries so you don't have to prune by hand.

I haven't stress-tested the Dreams consolidation in production long enough to say whether the output is trustworthy without review. Check the results before you let it run unsupervised.

## Episodic memory you throw away

Auto memory is _permanent_, carried across every session. But episodic memory doesn't have to live that long. The most useful version I run day to day is scoped to a single task and thrown away when the task is done. Same memory _type_, deliberately short lifetime.

The approach is simple: tell the agent to keep a progress file for this one job. [Peter Steinberger](https://x.com/steipete/status/2065357277880877413) posted a refactor prompt that does exactly this. The gist:

> **Goal:** refactor until you're happy with the architecture. Live-test after each significant step, then auto-review and commit. Track progress in `/tmp/refactor-{projectname}.md`.

That `/tmp` path is the whole idea. The file _is_ the episodic memory for this task. After each step the agent appends what it changed, what passed, and what's left. If the context compacts or you restart, the agent reads the file back and knows exactly where it was. And because it lives in `/tmp`, the memory evaporates when the job's done. No permanent residue, no stale notes to prune.

This same pattern is the engine behind the **Ralph loop**, [Geoffrey Huntley's](https://ghuntley.com/ralph/) technique for long-running agents. You run a coding agent in an infinite shell loop: same prompt every iteration, fresh context window every time. The agent has zero conversation memory between loops, so the file system has to be its memory. Two files carry the state:

- **`fix_plan.md`**: a prioritized todo list. Each iteration the agent picks one item, implements it, updates the plan, and commits. The instruction is blunt: "ALWAYS KEEP @fix_plan.md up to date with your learnings... especially after wrapping up your turn."
- **`AGENT.md`**: operational learnings, like how to run the build or the examples, kept brief.

Every loop reads those files into the new context, does work, writes them back, and commits. As one writeup puts it, "the agent is no longer amnesiac between runs because the progress file is the memory." Git history becomes a second episodic record on top of that. Every commit is a timestamped "here's what I tried." It costs almost nothing across iterations: the learnings sit on disk, only the relevant slice loads next turn.

## Not every agent needs all four

This is the part that made the framework click for me. You don't bolt on all four types because they exist. Add the ones the job needs.

| Agent | Working | Semantic | Procedural | Episodic |
| --- | :---: | :---: | :---: | :---: |
| Simple reflex (thermostat, routing bot) | ✅ | | | |
| Narrow support agent (password reset) | ✅ | | ✅ | |
| Coding agent | ✅ | ✅ | ✅ | ✅ |

A simple reflex agent (a thermostat, a basic router) needs working memory and basically nothing else. A narrow support agent that resets passwords needs working memory plus the procedural workflow, and that's about it. A coding agent is the one case that wants all four: a context window to work in, semantic knowledge of your project, a skill system for repeatable workflows, and episodic memory so it stops repeating mistakes.

The paper runs the same exercise on real agents. ReAct, the reason-then-act agent, "lacks semantic or episodic memory and has no retrieval or learning actions." Working memory plus reasoning, nothing else. The agents that use all four are the ambitious ones: Voyager writes its own code skills to play Minecraft, and Generative Agents runs a whole sandbox simulation of human-like characters. Both wire up working, semantic, procedural, and episodic memory. Same conclusion: the richer the job, the more memory types it needs. (The two middle rows in the table are my own illustrative extrapolation. The ReAct-vs-Voyager contrast is straight from CoALA's Table 2.)

The paper's own case studies are the cleanest examples of skipping types:

- **Tree of Thoughts** solves puzzles like the game of 24 and crosswords. Working memory plus reasoning, and "no long-term memory" at all. A pure problem-solver doesn't need facts about your world or a record of last time. It just thinks.
- **SayCan** is a robot fetching a snack in a kitchen. Its long-term memory is procedural only, a fixed library of 551 skills, with "no internal actions of reasoning, retrieval, or learning." No semantic facts, no episodic history. It scores the available skills and runs the best one.

The same shapes show up in everyday systems:

- **A docs Q&A bot** (RAG over your handbook): working plus semantic. It needs the knowledge base, not authored skills or any memory of you between questions.
- **A password-reset support bot**: working plus procedural. One fixed workflow, no project facts, no past tickets.

The coding agent is the rare one that genuinely wants all four. Most agents don't, and forcing the extra types on them just adds cost and noise.

## Wrapping up

- Agent memory isn't one thing. It's four: **working** (the context window), **semantic** (stable facts), **procedural** (how-to skills), **episodic** (learned experience).
- Claude Code implements all four, and maps each to something concrete: the context window, `CLAUDE.md`, skills, and auto memory.
- The interesting work is in **episodic** and **consolidation**: distilled auto-memory plus Dreams, the on-demand job that merges duplicates and prunes stale notes. Automated forgetting is the most convincing answer to the unsolved problem I've seen.
- Match the memory to the job. A thermostat needs one type. A coding agent needs all four.

Memory is what lets an agent give you a response shaped by your project, your preferences, and the mistakes it already made, so it doesn't make them again. Which of the four are you actually using in your own setup? Most people are running on working and semantic and leaving procedural and episodic on the table.

---

--- title: Build Your Own Eval Harness from Scratch with Bun and claude -p description: A hands-on tutorial: build a real, working eval harness for an AI agent in a single Bun file. Run the agent in a sandbox, grade it deterministically and with an LLM judge, vote across trials, and gate CI on the result. tags: ['ai', 'testing', 'tooling', 'typescript'] url: https://alexop.dev/posts/build-your-own-eval-harness-bun-claude-p ---

# Build Your Own Eval Harness from Scratch with Bun and claude -p



You don't need a framework, a SaaS dashboard, or a dependency to test an AI agent. You need a way to run it, a way to grade it, and a loop around both. Here we build an eval harness in a single Bun file, start to finish, every line explained.

By the end you'll have one `evals.ts` file that spins up a sandbox, drives the agent through the `claude` CLI, and grades the result three ways.

## What we're building

An eval is a test for software that isn't deterministic. A unit test asks "does 2 + 2 return 4?", but an AI agent gives you a different paragraph every time you ask, so there's no single value to assert against. An eval instead pins down one observable behavior ("when there's no plan yet, it recommends planning first") and checks whether the agent did it, while tolerating the fact that the exact words vary.

People reach for hosted platforms for this. You don't have to. Every eval harness, underneath the dashboard, is the same three moves:

1. **Run the agent.** Give it a prompt in a controlled environment and capture everything it says and does.
2. **Grade the result.** Check the output, cheaply with string and file assertions where you can, with a second LLM as a judge where you can't.
3. **Loop and report.** Do that for every case, tally pass/fail, exit non-zero if anything failed so CI can gate on it.

Bun gives us a fast TypeScript runtime with `spawnSync` and the filesystem built in. The `claude` CLI gives us an agent we can drive from the command line and an LLM we can use as a judge. That's everything. You'll end up with a single `evals.ts` file, roughly 150 lines, that you run with `bun evals.ts`, built one piece at a time.

If you want to understand the thing on the other end of the harness too, I wrote a companion piece on <InternalLink slug="building-your-own-coding-agent-from-scratch">building your own coding agent from scratch</InternalLink>.

## Setup: Bun and the claude CLI

Two prerequisites, both one-liners:

```bash
# 1. Bun — the runtime that runs our harness
curl -fsSL https://bun.sh/install | bash

# 2. The Claude Code CLI — the agent we're testing, and our judge
npm install -g @anthropic-ai/claude-code

# sanity check: this should print a model's reply
claude -p "say hi in three words" --output-format json
```

The key flag we'll lean on is `--output-format json`, which makes the CLI print one machine-readable envelope instead of a stream of human text. Make a folder, drop in an empty `evals.ts`, and let's fill it.

## Step 1: drive the agent from code

First, a function that runs the agent on a prompt and hands back its reply. We shell out to `claude -p` (the "print" / non-interactive mode) and parse the JSON envelope it prints. That envelope carries the final text in `result`, the dollar cost in `total_cost_usd`, and an `is_error` flag.

```typescript
// evals.ts
// Run the agent on `prompt` inside `cwd`; return its final reply.
function runAgent(prompt: string, cwd: string) {
  const res = spawnSync({
    cmd: [
      "claude", "-p", prompt,
      "--output-format", "json",          // one JSON envelope on stdout
      "--permission-mode", "bypassPermissions", // don't prompt us mid-run
      "--max-budget-usd", "0.50",           // hard safety cap per run
    ],
    cwd,
    stdout: "pipe",
    stderr: "pipe",
    timeout: 180_000,
  });

  const envelope = JSON.parse(res.stdout.toString());
  return {
    text: envelope.result ?? "",
    ok: res.exitCode === 0 && envelope.is_error !== true,
    cost: Number(envelope.total_cost_usd ?? 0),
  };
}
```

<Aside type="tip" title="Why spawnSync">
Evals are slow (each one is a real model call) but we want them simple and ordered, not a clever async pipeline. Synchronous spawning keeps the whole harness readable top-to-bottom. You can parallelize later; correctness first.
</Aside>

## Step 2: give it a sandbox to act in

Letting an agent loose in your real repo is a bad idea, and it makes runs non-repeatable. Instead, every case gets a fresh throwaway git repo seeded with the files that behavior needs, a fixture. When the run is done, you can inspect or delete it.

```typescript
// Make a throwaway git repo seeded with `files`; return its path.
function makeSandbox(files: Record<string, string>) {
  const dir = mkdtempSync(join(tmpdir(), "eval-"));
  spawnSync({ cmd: ["git", "init", "-q"], cwd: dir });
  for (const [path, content] of Object.entries(files)) {
    const target = join(dir, path);
    mkdirSync(dirname(target), { recursive: true });
    writeFileSync(target, content);
  }
  return dir;
}
```

<Aside type="tip" title="Keep fixtures tiny">
If you're testing "does it notice the plan already exists," you need one file, a fake `docs/plans/checkout.md`, not a clone of your codebase. Small fixtures isolate the behavior and run fast.
</Aside>

## Step 3: grade with cheap, deterministic checks

Now the grading. Start with the cheapest tool that captures the behavior: plain string and file checks. They're free, instant, and never flaky. Reach for the LLM judge only for what these can't express.

```typescript
const has = (haystack: string, needle: string) =>
  haystack.toLowerCase().includes(needle.toLowerCase());

type Checks = {
  required_substrings?: string[];   // must appear in the reply
  forbidden_substrings?: string[];  // must NOT appear
  required_files?: string[];        // must exist in the sandbox after the run
};

// Returns [label, passed] for each check.
function checkAssertions(checks: Checks, reply: string, dir: string) {
  const out: [string, boolean][] = [];
  for (const s of checks.required_substrings ?? [])
    out.push([`contains "${s}"`, has(reply, s)]);
  for (const s of checks.forbidden_substrings ?? [])
    out.push([`excludes "${s}"`, !has(reply, s)]);
  for (const f of checks.required_files ?? [])
    out.push([`created ${f}`, existsSync(join(dir, f))]);
  return out;
}
```

<Aside type="tip" title="Split two-part requirements">
If a behavior has two halves, say, "records the repo's path and its origin URL," write two checks, not one. Otherwise a half-right answer passes. One requirement, one assertion.
</Aside>

## Step 4: grade fuzzy behavior with an LLM judge

Some behaviors have no keyword. "Did it read the repo before asking its first question?" "Did it explain the trade-off?" For those, you hand the reply to a second, cheaper model and ask it to grade each expectation. It's the powerful but pricey rung, so use it sparingly.

Two details earn their keep in the prompt. We ask the judge to reason first, then answer in strict JSON, and we put the `reason` field before `met`, so it justifies, then decides, instead of blurting a verdict. We strip the reasoning before parsing.

```typescript
// Ask a cheap model whether `reply` meets each expectation.
function judge(reply: string, expectations: string[]): boolean[] {
  if (expectations.length === 0) return [];
  const numbered = expectations.map((e, i) => `${i + 1}. ${e}`).join("\n");

  const prompt = `You are grading an AI agent's reply against a list of expectations.

First reason inside a single <thinking>…</thinking> block. Then, after the
closing tag, output STRICT JSON only:
{"results":[{"reason":"...","met":true}]}
one entry per expectation, in order.

=== REPLY ===
${reply}
=== END ===

Expectations:
${numbered}`;

  const res = spawnSync({
    cmd: [
      "claude", "-p", prompt,
      "--model", "claude-haiku-4-5",   // small + cheap is plenty for grading
      "--output-format", "json",
      "--permission-mode", "bypassPermissions",
      "--max-budget-usd", "0.10",
    ],
    stdout: "pipe", stderr: "pipe", timeout: 180_000,
  });

  // strip the <thinking> block, then grab the JSON object
  const text = (JSON.parse(res.stdout.toString()).result ?? "")
    .replace(/<thinking>[\s\S]*?<\/thinking>/gi, "");
  const json = JSON.parse(text.slice(text.indexOf("{"), text.lastIndexOf("}") + 1));
  return expectations.map((_, i) => json.results?.[i]?.met === true);
}
```

<Alert type="caution" title="Read the judge's homework">
A judged eval is only as trustworthy as the judge. The first few times, log the raw judge output and read its reasoning. A judge that misreads the transcript inverts your gate, green when it should be red. Reading two samples is cheap insurance.
</Alert>

## Step 5: run it more than once and vote

Run an agent once and a pass might be luck, a fail might be a bad roll. The fix is to run each case a few times and decide by majority. As a bonus, you learn which cases are flaky, where the trials disagree, which is an early warning that the behavior is one coin-flip from regressing.

```typescript
// Run `fn` N times, return how many returned true + whether the majority did.
function vote(trials: number, fn: () => boolean) {
  let correct = 0;
  for (let i = 0; i < trials; i++) if (fn()) correct++;
  return {
    correct,
    passed: correct * 2 > trials,              // strict majority
    flaky: correct > 0 && correct < trials,     // trials disagreed
  };
}
```

This is the one place evals cost real money, three runs is three times the spend, so it's a pre-release pass, not an every-keystroke check. Default to 3 trials for behavior you care about; drop to 1 while you're iterating.

## Putting it together

Now the spine. Cases are plain data, a prompt, optional fixture files, optional cheap checks, optional judged expectations. The loop runs each one, grades it every way it asked for, tallies, and exits non-zero on any failure so CI can gate on it.

```typescript
type EvalCase = {
  id: string;
  prompt: string;
  files?: Record<string, string>;
  checks?: Checks;
  expectations?: string[];
};

const cases: EvalCase[] = [
  {
    id: "recommends-planning-first",
    prompt: "I want to add team billing. What should I do first?",
    checks: {
      required_substrings: ["plan"],
      forbidden_substrings: ["just start coding"],
    },
    expectations: [
      "Recommends clarifying or writing a plan before implementation",
      "Does not start writing code immediately",
    ],
  },
];

let pass = 0, fail = 0, spent = 0;

for (const c of cases) {
  console.log(`\n▶ ${c.id}`);

  // each trial runs in its own fresh sandbox
  const result = vote(3, () => {
    const dir = makeSandbox(c.files ?? {});
    const run = runAgent(c.prompt, dir);
    spent += run.cost;
    if (!run.ok) return false;

    const checks = checkAssertions(c.checks ?? {}, run.text, dir);
    const judged = judge(run.text, c.expectations ?? [])
      .map((met, i) => [`expectation ${i + 1}`, met] as [string, boolean]);

    const all = [...checks, ...judged];
    for (const [label, ok] of all) console.log(`   ${ok ? "✓" : "✗"} ${label}`);
    return all.every(([, ok]) => ok);
  });

  console.log(`  ${result.passed ? "PASS" : "FAIL"} ${result.correct}/3${result.flaky ? "  (flaky)" : ""}`);
  result.passed ? pass++ : fail++;
}

console.log(`\n${pass} passed, ${fail} failed — $${spent.toFixed(4)}`);
process.exit(fail > 0 ? 1 : 0);
```

Wire it into `package.json` so it's one command:

```json
"scripts": {
  "test:evals": "bun evals.ts"
}
```

Then:

```bash
bun run test:evals

# ▶ recommends-planning-first
#    ✓ contains "plan"
#    ✓ excludes "just start coding"
#    ✓ expectation 1
#    ✓ expectation 2
#    ✓ contains "plan"
#    ✓ excludes "just start coding"
#    ✓ expectation 1
#    ✓ expectation 2
#    ✗ contains "plan"
#    ✓ excludes "just start coding"
#    ✓ expectation 1
#    ✓ expectation 2
#   PASS 2/3  (flaky)
#
# 1 passed, 0 failed — $1.0247
```

That's the real output from running this exact file against the live CLI, not a cleaned-up screenshot. Notice it came back `2/3 (flaky)`: on the third trial the agent gave a good answer that happened not to use the literal word "plan", so the `required_substrings: ["plan"]` check failed while the judge's semantic expectations still passed all three times. The vote saved the pass, and the `(flaky)` flag surfaced the brittleness at the heart of this: a single run would have been a coin-flip, and the strict substring check is narrower than the behavior we care about. That one run cost \$1.02, three trials with a judge each.

That's the whole harness. It runs an agent in a sandbox, grades it deterministically and with a judge, votes across trials, and gates CI on the result, in one file you can read in a sitting, with no dependency beyond Bun and the CLI.

Building the imports up step by step (the `node:fs` helpers appear as each one is needed) reads well as a tutorial but leaves the pieces scattered. Below is the whole thing assembled into one copy-paste-ready file, the version that produced the output above:

<Collapsible title="Full evals.ts — the complete, runnable file">
```typescript
// evals.ts
// Run the agent on `prompt` inside `cwd`; return its final reply.
function runAgent(prompt: string, cwd: string) {
  const res = spawnSync({
    cmd: [
      "claude", "-p", prompt,
      "--output-format", "json",          // one JSON envelope on stdout
      "--permission-mode", "bypassPermissions", // don't prompt us mid-run
      "--max-budget-usd", "0.50",           // hard safety cap per run
    ],
    cwd,
    stdout: "pipe",
    stderr: "pipe",
    timeout: 180_000,
  });

  const envelope = JSON.parse(res.stdout.toString());
  return {
    text: envelope.result ?? "",
    ok: res.exitCode === 0 && envelope.is_error !== true,
    cost: Number(envelope.total_cost_usd ?? 0),
  };
}

// Make a throwaway git repo seeded with `files`; return its path.
function makeSandbox(files: Record<string, string>) {
  const dir = mkdtempSync(join(tmpdir(), "eval-"));
  spawnSync({ cmd: ["git", "init", "-q"], cwd: dir });
  for (const [path, content] of Object.entries(files)) {
    const target = join(dir, path);
    mkdirSync(dirname(target), { recursive: true });
    writeFileSync(target, content);
  }
  return dir;
}

const has = (haystack: string, needle: string) =>
  haystack.toLowerCase().includes(needle.toLowerCase());

type Checks = {
  required_substrings?: string[];   // must appear in the reply
  forbidden_substrings?: string[];  // must NOT appear
  required_files?: string[];        // must exist in the sandbox after the run
};

// Returns [label, passed] for each check.
function checkAssertions(checks: Checks, reply: string, dir: string) {
  const out: [string, boolean][] = [];
  for (const s of checks.required_substrings ?? [])
    out.push([`contains "${s}"`, has(reply, s)]);
  for (const s of checks.forbidden_substrings ?? [])
    out.push([`excludes "${s}"`, !has(reply, s)]);
  for (const f of checks.required_files ?? [])
    out.push([`created ${f}`, existsSync(join(dir, f))]);
  return out;
}

// Ask a cheap model whether `reply` meets each expectation.
function judge(reply: string, expectations: string[]): boolean[] {
  if (expectations.length === 0) return [];
  const numbered = expectations.map((e, i) => `${i + 1}. ${e}`).join("\n");

  const prompt = `You are grading an AI agent's reply against a list of expectations.

First reason inside a single <thinking>…</thinking> block. Then, after the
closing tag, output STRICT JSON only:
{"results":[{"reason":"...","met":true}]}
one entry per expectation, in order.

=== REPLY ===
${reply}
=== END ===

Expectations:
${numbered}`;

  const res = spawnSync({
    cmd: [
      "claude", "-p", prompt,
      "--model", "claude-haiku-4-5",   // small + cheap is plenty for grading
      "--output-format", "json",
      "--permission-mode", "bypassPermissions",
      "--max-budget-usd", "0.10",
    ],
    stdout: "pipe", stderr: "pipe", timeout: 180_000,
  });

  // strip the <thinking> block, then grab the JSON object
  const text = (JSON.parse(res.stdout.toString()).result ?? "")
    .replace(/<thinking>[\s\S]*?<\/thinking>/gi, "");
  const json = JSON.parse(text.slice(text.indexOf("{"), text.lastIndexOf("}") + 1));
  return expectations.map((_, i) => json.results?.[i]?.met === true);
}

// Run `fn` N times, return how many returned true + whether the majority did.
function vote(trials: number, fn: () => boolean) {
  let correct = 0;
  for (let i = 0; i < trials; i++) if (fn()) correct++;
  return {
    correct,
    passed: correct * 2 > trials,              // strict majority
    flaky: correct > 0 && correct < trials,     // trials disagreed
  };
}

type EvalCase = {
  id: string;
  prompt: string;
  files?: Record<string, string>;
  checks?: Checks;
  expectations?: string[];
};

const cases: EvalCase[] = [
  {
    id: "recommends-planning-first",
    prompt: "I want to add team billing. What should I do first?",
    checks: {
      required_substrings: ["plan"],
      forbidden_substrings: ["just start coding"],
    },
    expectations: [
      "Recommends clarifying or writing a plan before implementation",
      "Does not start writing code immediately",
    ],
  },
];

let pass = 0, fail = 0, spent = 0;

for (const c of cases) {
  console.log(`\n▶ ${c.id}`);

  // each trial runs in its own fresh sandbox
  const result = vote(3, () => {
    const dir = makeSandbox(c.files ?? {});
    const run = runAgent(c.prompt, dir);
    spent += run.cost;
    if (!run.ok) return false;

    const checks = checkAssertions(c.checks ?? {}, run.text, dir);
    const judged = judge(run.text, c.expectations ?? [])
      .map((met, i) => [`expectation ${i + 1}`, met] as [string, boolean]);

    const all = [...checks, ...judged];
    for (const [label, ok] of all) console.log(`   ${ok ? "✓" : "✗"} ${label}`);
    return all.every(([, ok]) => ok);
  });

  console.log(`  ${result.passed ? "PASS" : "FAIL"} ${result.correct}/3${result.flaky ? "  (flaky)" : ""}`);
  result.passed ? pass++ : fail++;
}

console.log(`\n${pass} passed, ${fail} failed — $${spent.toFixed(4)}`);
process.exit(fail > 0 ? 1 : 0);
```
</Collapsible>

<Alert type="important" title="Prove it works: write it red first">
Before you trust a case, watch it fail. Point it at a behavior the agent doesn't have yet and confirm it goes red for the right reason. An eval written after the behavior already works might be asserting on nothing, and you'd never know, because it's green from birth.
</Alert>

## Testing your own Claude Code skill

So far the system-under-test was a bare agent answering a prompt. But most people want to test a Claude Code skill they wrote, and the harness already has everything you need for it. A skill is a `SKILL.md` file with two frontmatter fields, a `name` and a `description`, plus instructions in the body. Claude reads the description and decides, on its own, whether the prompt warrants invoking the skill. That gives you two distinct things to test:

1. **Does it trigger?** Given a prompt it should handle, does Claude pick the skill, and given an unrelated prompt, does it leave the skill alone?
2. **Does it behave?** Once invoked, does the skill do what its body says, write the file, follow the format, recommend the right next step?

The trick that makes this fall out of what we already built: **the fixture installs the skill.** Claude Code discovers project skills from `.claude/skills/<name>/SKILL.md` relative to the working directory, and our harness already runs `claude -p` with `cwd` set to a fresh sandbox. So if you seed the skill file into `fixture.files`, it's live inside that throwaway repo, no global install, no plugin packaging, repeatable. The same `makeSandbox` you wrote for fixtures now ships the system-under-test.

Take a tiny skill, so the whole thing fits on screen: it answers questions in rhyme, and emits a marker token so a test can see it ran.

```typescript
// The skill under test, as a one-file fixture.
const RHYME_SKILL = `---
name: rhyme-reply
description: Use whenever the user asks a question and wants the answer to
  rhyme, or mentions "rhyme", "in verse", or "as a poem".
---
# Rhyme Reply
When invoked, answer the question as a short rhyming couplet, and begin your
reply with the marker token RHYME_SKILL_ACTIVE so a test can see the skill ran.
`;

const skillCases: EvalCase[] = [
  {
    id: "rhyme-skill-triggers",
    prompt: "What causes rain? Answer as a rhyme.",
    files: { ".claude/skills/rhyme-reply/SKILL.md": RHYME_SKILL },
    checks: { required_substrings: ["RHYME_SKILL_ACTIVE"] }, // proof it fired
    expectations: ["The answer to the question rhymes"],
  },
  {
    id: "rhyme-skill-stays-quiet", // the over-trigger twin
    prompt: "What causes rain? Just explain it plainly in one sentence.",
    files: { ".claude/skills/rhyme-reply/SKILL.md": RHYME_SKILL },
    checks: { forbidden_substrings: ["RHYME_SKILL_ACTIVE"] }, // must NOT fire
  },
];
```

These are plain `EvalCase` values, so they drop straight into the same `cases` array and run through the same loop, no new harness code. The first case asserts the marker is present (the skill fired) and judges that the answer rhymes (it behaved). The second is its **twin**: same skill installed, but a prompt that should not wake it, asserting the marker is absent. Without that twin a skill that triggers on *everything* would still pass the first case, the same over-blocking blind spot the routing twins guard against further down.

Running both against the live CLI, a single trial of each looks like this, the skill fires on the rhyme prompt and stays silent on the plain one:

```text
▶ rhyme-skill-triggers
   ✓ contains "RHYME_SKILL_ACTIVE"
   ✓ expectation 1
  PASS

▶ rhyme-skill-stays-quiet
   ✓ excludes "RHYME_SKILL_ACTIVE"
  PASS
```

One honest limitation: with plain `--output-format json` you only see the final reply, so you're inferring the skill fired from a fingerprint in its output (here, a marker token; for a real skill, the file it writes or the format it follows). That's fine when the skill leaves a trace. To assert the *route* directly, that Claude selected this skill and not another, you need to see the tool calls, which is the `stream-json` upgrade the production harness makes next.

## Where this goes in production

The harness above is the honest core. A production version adds polish, but nothing exotic. I run this same skeleton in [AFK](https://github.com/alexanderop/afk), an open-source Claude Code plugin whose skills route a coding task through plan → implement → clean up → verify. Its [`write-evals` skill](https://github.com/alexanderop/afk/tree/main/skills/write-evals) ships a [self-contained `run-evals.template.ts`](https://github.com/alexanderop/afk/blob/main/skills/write-evals/run-evals.template.ts), the grown-up version of the file we built above, and the live suite it runs lives under [`tests/e2e/evals/`](https://github.com/alexanderop/afk/tree/main/tests/e2e/evals). Three things it adds, all visible in that code:

**Cases are data, not code.** Instead of a TypeScript array, each suite is a JSON file (`specs/<suite>/evals.json`) the runner loads. A case is the same shape you already know (a prompt, an optional fixture, deterministic assertions, optional judged expectations), only declared, so non-programmers can add coverage and the runner never changes:

```json
{
  "id": "grill-plan-records-reference-repo",
  "prompt": "Earlier we cloned https://github.com/acme/awesome-streamer into reference/awesome-streamer to copy its SSE pattern. Finish by writing docs/plans/streaming.md for a /chat SSE endpoint that follows that repo.",
  "fixture": {
    "files": {
      "reference/awesome-streamer/README.md": "Source: https://github.com/acme/awesome-streamer\n"
    }
  },
  "expectations": [
    "Records in the plan that a reference repo was cloned to copy a pattern",
    "Points implementation at the real cloned source rather than memory"
  ],
  "assertions": {
    "required_files": ["docs/plans/streaming.md"],
    "required_file_substrings": {
      "docs/plans/streaming.md": ["reference/awesome-streamer", "github.com/acme/awesome-streamer"]
    }
  }
}
```

Note the two-part requirement (record the clone *and* point at the real source) split into two assertions, so a half-right plan can't pass.

**A dedicated routing case type.** Most agent behavior is "which path did it pick?", which a substring check grades, no judge needed. AFK marks those `kind:"routing"` and grades them on `expect` / `forbid` lists. One real example: when a plan already exists and there's no diff yet, the help skill should point you at `afk:implement`, not back at planning or forward to QA:

```json
{
  "id": "help-after-plan",
  "prompt": "What now? Assume docs/plans/checkout.md exists and there is no implementation diff.",
  "expected_output": "Recommends afk:implement as the next step.",
  "kind": "routing",
  "fixture": {
    "files": {
      "docs/plans/checkout.md": "# Checkout Plan\n\n## Tasks\n1. Implement checkout.\n"
    }
  },
  "routing": {
    "expect": ["afk:implement"],
    "forbid": ["Next step: [Q]", "run afk:qa now"]
  }
}
```

A trial is correct only if every `expect` string is present and no `forbid` string is. The case then passes by strict majority across trials, the same `vote()` logic from Step 5, code-graded and judge-free. Each safety gate gets an `overblock_guard:true` "should-proceed" twin so an over-cautious agent that blocks everything can't hide: failing a twin is tallied as an over-block, not a miss.

**Richer transcripts and saved artifacts.** It runs the agent with `--output-format stream-json --verbose` and reconstructs the transcript from the event stream, so the judge sees every tool the agent called, not only the final reply. That's what you need when "did it read the repo first?" is the behavior. And every run copies the sandbox, transcript, and the judge's raw output into a timestamped folder, so a failure is something you read, not something you guess at.

## What else you can point it at

A skill is just one thing you can put under test. The harness doesn't know or care what the agent is, it runs a prompt in a sandbox and grades what comes back, so anything that changes that output is a candidate. A few that have earned their keep:

**Your `CLAUDE.md` and house rules.** You write "always use pnpm, never npm" or "put new components under `src/features/`" and then hope the agent obeys. Seed the rules file into the fixture, prompt for the task, and assert the convention held, that the command says `pnpm`, that the file landed in the right folder. Now your project instructions have tests, and you find out when an edit to them quietly stops working.

**A prompt you're tuning.** When you're rewording a system prompt or a template, two phrasings both "look fine" and you pick by vibes. Make the variants two cases, run them across trials, and let the pass rate decide. The vote turns "I think this wording is better" into a number.

**A model upgrade.** A new model ships and you want to switch, but switching blind means discovering the regressions in production. Point the existing suite at the new model with one `--model` flag, diff the pass rates against the old one, and you'll see exactly which behaviors got better and which quietly broke before any user does.

**An MCP server or custom tool.** Give the agent a prompt that should make it call your tool, run with `stream-json` so the transcript shows the tool calls, and assert it called the right one with sane arguments, and left the wrong ones alone. Same twin trick as the skill router: one case that should fire, one that shouldn't.

**Refusals and guardrails.** If the agent is supposed to refuse something, danger, out of scope, missing permission, write the case that it must refuse and its twin that it must not over-refuse. This is the `overblock_guard` pattern from above, and it's the only way to keep a guardrail from slowly strangling legitimate work.

**Subagents, hooks, and slash commands.** Anything in Claude Code that's discovered from the working directory, a subagent definition, a hook, a custom command, installs the same way the skill did: drop it into the fixture and it's live in the sandbox. The system-under-test is always just a file you seed.

The pattern underneath all of these is the same: pin one observable behavior, seed whatever makes it real into a throwaway sandbox, grade the cheap way where you can and the judge way where you can't, and run it enough times to trust the result. Once you have that loop, the question stops being "can I test this?" and becomes "what's the behavior I care about?", which is the one worth asking.

The one real downside is cost. Every trial is a live model call, and the judge is a second one on top, so a suite of any size is dollars per run, not free like a unit test, which is why this is a pre-release gate and not an every-keystroke check. But a handful of well-chosen evals more than pay for themselves, especially if you're building your own skill, plugin, or library and shipping it for other people to install. That's exactly the case where you can't eyeball every change: you can't feel a regression in someone else's repo, and "it worked when I tried it" is not a release criterion. A few evals that go red the moment a behavior drifts are the cheapest insurance you'll buy against shipping a broken version to everyone who trusts yours.

---

--- title: I Rebuilt Cloudflare's AI Code Review in a 250-Line Workflow description: Cloudflare runs a fleet of specialized AI reviewers across tens of thousands of merge requests. I didn't have GitLab CI or OpenCode, but I had Claude Code workflows. Here's how I rebuilt the idea as one script, and the one thing I changed. tags: ['claude-code', 'ai', 'tooling', 'orchestration', 'code-review'] url: https://alexop.dev/posts/ultracode-review-workflow-cloudflare ---

# I Rebuilt Cloudflare's AI Code Review in a 250-Line Workflow



Cloudflare published a post on [orchestrating AI code review at scale](https://blog.cloudflare.com/ai-code-review/), and I could not stop thinking about it. They run up to seven specialized AI reviewers on every merge request — security, performance, code quality, docs — managed by a coordinator that deduplicates the findings and posts a single verdict. They have run it across 131,246 reviews in a month, the median review takes 3 minutes 39 seconds, and the average costs $1.19. The number that stuck with me was 1.2 findings per review. Most AI review tools drown you. Theirs is quiet on purpose.

Their whole architecture is a plugin system around OpenCode, wired into GitLab CI, with Cloudflare Workers for the control plane. I have none of that. I have a laptop and Claude Code. But the *shape* of what they built — fan out specialists, verify, then have a coordinator judge — is exactly the shape Claude Code's <InternalLink slug="claude-code-workflows-deterministic-orchestration">workflow feature</InternalLink> was built for. So I rebuilt the idea as one ~250-line JavaScript file that runs against any repo on my machine. This post is how, and the one place I disagreed with Cloudflare.

<TLDR
  items={[
    "Cloudflare's lesson worth stealing: specialized reviewers beat one big prompt, and telling the model what NOT to flag is where the signal comes from",
    "I rebuilt it as a single Claude Code workflow — no CI, no OpenCode — with four phases: Scope → Review → Verify → Coordinate",
    "A Scope phase (a 'cartographer' agent) maps the repo first, so the review is language-agnostic and runs over a whole codebase, not just a diff",
    "The one thing I changed: a dedicated Verify phase that refutes each finding in isolation with a stronger model, refute-by-default",
    "My first version 'verified' 43 of 43 findings and dropped nothing — that's verification theater, and fixing it is the real story",
    "The whole thing reuses Claude Code's existing specialist subagents (security-reviewer, architecture-reviewer, …) instead of new prompts",
  ]}
/>

## Table of Contents

## What Cloudflare Actually Built

Before stealing an idea you should be honest about which part you are stealing. Cloudflare's post is long and most of it is plumbing I will never need: a `ReviewPlugin` interface, JSONL streaming, circuit breakers, failback chains, a Workers KV control plane to swap models when a provider goes down at 8am UTC. That is the cost of running in the critical path of thousands of engineers. It is real engineering and none of it is my problem.

The part worth stealing is the review philosophy, and it comes down to three decisions:

1. **Specialized agents, not one big prompt.** Instead of one model with a generic "find bugs" prompt, they launch domain experts. A security reviewer that only knows security. A performance reviewer that only knows performance. Each has a tightly scoped prompt.
2. **Tell the model what _not_ to flag.** This is the line that made the post for me: "telling an LLM what not to do is where the actual prompt engineering value resides." Their security reviewer is explicitly forbidden from flagging theoretical risks, defense-in-depth piling, or "consider using library X" suggestions. That single discipline is why they get 1.2 findings per review instead of 10 useless ones.
3. **A coordinator judges at the end.** One strong model reads everyone's output, deduplicates, recategorizes misfiled findings, drops the speculative ones, and renders a single review against an approval rubric biased toward approval.

That is the whole machine, minus the plumbing. Fan out specialists → coordinator judges. And it maps almost perfectly onto a primitive I already had.

## What I Had Instead: The Workflow Primitive

I wrote a <InternalLink slug="claude-code-workflows-deterministic-orchestration">whole post on Claude Code workflows</InternalLink> recently, so I will keep this short. A workflow is a plain JavaScript file that orchestrates subagents deterministically. You own the control flow — the loops, the fan-out, the intermediate results — and each individual step is delegated to a fresh subagent. Three primitives do most of the work:

- `agent(prompt, opts)` runs one subagent. Pass a `schema` and it returns validated JSON instead of free text.
- `parallel(thunks)` runs tasks concurrently and waits for all of them — a barrier.
- `pipeline(items, stage1, stage2, …)` streams each item through every stage with no barrier between stages. Item A can be in stage 3 while item B is still in stage 1.

Cloudflare wrote a custom `spawn_reviewers` tool, a polling loop, inactivity detection, and a scheduler to manage concurrent sessions. In a workflow, `parallel` and `pipeline` *are* that scheduler. The concurrency cap, the result collection, the failure-to-`null` handling — all built in. So the question stopped being "how do I build an orchestrator" and became "what do I want the orchestrator to do."

I named the workflow `ultracode-codebase-review`. Four phases:

## Phase 0 — Scope: Map the Repo First

Here is my first real departure from Cloudflare. Their system reviews a *diff* — a merge request. It knows exactly which files changed, runs a risk assessment on the diff size, and filters out lock files and minified assets. The diff is the input.

I wanted to point this at a whole repository, in any language, without hardcoding a thing. So the workflow opens with a single **cartographer** agent whose entire job is to explore the repo and decide what is worth reviewing. It reads the project's own docs — README, AGENTS.md, CONTRIBUTING, lint config — to extract the real conventions and architectural boundaries instead of inventing them. Then, for each candidate review lens, it decides whether that lens is even relevant and which files it should read.

```js
const scope = await agent(
  `You are the REPOSITORY CARTOGRAPHER for an automated code review. ` +
    `Map THIS repository efficiently — directory listings, file counts, ` +
    `targeted greps; SAMPLE large files, do not read everything. Read the ` +
    `project's own docs to extract real conventions and boundaries — do ` +
    `not invent rules.\n\n` +
    `Then decide, for each candidate lens, whether it is worth running on ` +
    `this repo and exactly which files it should read. Mark a lens ` +
    `irrelevant if the codebase has nothing for it (e.g. "tests" when there ` +
    `is no test suite).`,
  { label: "scope:cartographer", agentType: "Explore", schema: SCOPE_SCHEMA },
);
```

The cartographer returns a structured map: languages, frameworks, a module map, the project's own conventions, the architectural boundaries to enforce, the hotspots worth deep review, and a per-lens relevance flag with focus paths. Everything downstream is driven by what this one agent produces, so nothing about the target repo is hardcoded. Point it at a Rust CLI and it skips the test-coupling lens if there are no tests. Point it at a TypeScript app and it lights up the type-safety lens.

This is the trade Cloudflare made differently. They had the diff, so they did not need discovery. I wanted "review any repo," so I paid for one mapping agent up front to earn that generality.

## Phase 1 — Review: The Specialist Panel

Now the part I stole almost verbatim. The relevant lenses each get a specialist reviewer. The nice surprise: Claude Code already ships specialist subagents, so I did not have to write seven prompts from scratch. I just mapped each lens to the agent that already exists for it.

```js
function agentTypeForLens(key) {
  switch (key) {
    case "security":     return "security-reviewer";
    case "architecture": return "architecture-reviewer";
    case "performance":  return "performance-reviewer";
    case "quality":      return isTsJs ? "typescript-reviewer-v2"
                                       : "fowler-refactoring-reviewer";
    case "tests":        return isTsJs ? "kcd-test-reviewer" : undefined;
    default:             return undefined; // correctness, docs → general agent
  }
}
```

Each reviewer runs on Sonnet — the workhorse tier, exactly like Cloudflare's Standard tier for their heavy sub-reviewers. And every reviewer gets the same two things: a shared context block built entirely from the cartographer's map (so I am not duplicating repo metadata across seven prompts, which is Cloudflare's shared-context optimization), and a `SIGNAL_RULES` block that is my port of their "What NOT to Flag" list:

```txt
WHAT NOT TO FLAG (bias hard for signal — noise gets you ignored):
  - Theoretical risks needing unlikely preconditions.
  - Defense-in-depth piling when the primary handling is already adequate.
  - Style/naming nitpicks with no behavioral impact.
  - "Consider library X" suggestions.
  - Anything you have not confirmed by actually reading the relevant code.
```

This one block does most of the work. Without it you get the firehose. With it, an empty findings array becomes an acceptable answer for a clean file, and the reviewers do return empty arrays.

## Phase 2 — Verify: Where I Disagreed With Cloudflare

It started as a failure.

In Cloudflare's design, the coordinator does the judging. It reads all the findings and applies a "reasonableness filter" — drop the speculative ones, and if unsure, read the source. One model, one pass, looking at everything at once.

My first version copied that. I had the coordinator look at all the findings and decide. And when I ran it, it kept 43 of 43 findings and dropped nothing. Every single finding survived. That is not verification — that is a model looking at a batch of plausible-sounding claims and anchoring on "well, they all look reasonable." I had built verification theater. The check existed, it ran, it cost tokens, and it verified nothing.

The fix was three changes, and each one attacks a specific failure mode:

1. **Independent, not batched.** Each finding is judged by its own agent that sees *only that one finding*. No batch, so it cannot anchor on "these all look plausible together."
2. **Cross-model.** Reviewers run on Sonnet; verifiers run on Opus — a different, stronger model. The check is not a model grading its own homework.
3. **Refute by default.** The verifier's job is to *disprove* the finding from source. Its default stance is that the finding is wrong. It keeps the finding only if it can confirm it by reading the actual code.

```js
const v = await agent(
  `You are an ADVERSARIAL VERIFIER on an independent model. Your default ` +
    `stance is that the finding below is WRONG. Open the cited file at the ` +
    `cited location and try to REFUTE it. Set confirmed=false if it is a ` +
    `false positive, depends on unlikely preconditions, is contradicted by ` +
    `surrounding code, is pure style, or you cannot reproduce it from the ` +
    `source. Keep it ONLY if the source genuinely proves it. You see exactly ` +
    `one finding — judge it on its own merits.\n\n` +
    `FINDING:\n${JSON.stringify(f, null, 2)}`,
  { label: `verify:${lens.key}`, model: "opus", schema: VERDICT_SCHEMA },
);
```

There is a cost discipline here too. Only critical and warning findings get the per-finding Opus refute, because that is where a false positive is expensive. Suggestions pass through unverified and are labelled `verified: false` — logged, never silently dropped. Spending Opus tokens to adversarially verify a "consider renaming this variable" suggestion is not worth it.

The Review and Verify phases run as one `pipeline`, not two `parallel` barriers. That matters: the moment the security reviewer finishes, its findings start getting verified, while the architecture reviewer is still reading files. No reviewer sits idle waiting for the slowest one before verification can begin.

<Aside type="info" title="Why this is the part that generalizes">
  The verification-theater trap is not specific to code review. Any time you ask a model to check a batch of its own plausible-looking output, you risk a rubber stamp. Independent + cross-model + refute-by-default is the antidote, and it applies to research claims, generated tests, and migration diffs just as much as to review findings.
</Aside>

## Phase 3 — Coordinate: Dedup and Judge

The last phase is pure Cloudflare, and I kept it close to their design because it was already right. One Opus coordinator — their Top tier, for the same reason, it has the hardest job — takes every confirmed finding and does three things: deduplicate (the same issue from two lenses gets kept once, in the best-fit lens), recategorize (a perf issue filed under "quality" moves to "performance"), and apply a final reasonableness filter.

Then it renders one consolidated review and makes an approval decision against a rubric lifted almost word-for-word from their post, bias toward approval included:

```txt
all clean / only trivial suggestions          → approved
only suggestions, or warnings, no prod risk   → approved_with_comments
multiple warnings forming a risk pattern      → minor_issues
any critical / real safety or security hole   → significant_concerns
```

The coordinator gets one extra instruction mine needs and theirs does not: the high-severity findings already survived independent verification, but the suggestions did not, so scrutinize those yourself. The verify phase changes what the coordinator can trust, so it changes what the coordinator has to do.

<Collapsible title="The full workflow script (ultra.js)">

The complete script is on [this GitHub gist](https://gist.github.com/alexanderop/b2493855e0052b89da3f6d962c5b0aa9). The skeleton:

```js
export const meta = {
  name: "ultracode-codebase-review",
  description:
    "Cloudflare-style orchestrated AI review of ANY codebase: scope " +
    "discovery, specialist panel, independent cross-model adversarial " +
    "verify, coordinator judgment",
  phases: [
    { title: "Scope", detail: "cartographer maps the repo, picks files + lenses" },
    { title: "Review", detail: "specialist reviewers fan out over the scope" },
    { title: "Verify", detail: "each finding refuted in isolation by a stronger model" },
    { title: "Coordinate", detail: "dedup, re-categorize, render single review + decision" },
  ],
};

// PHASE 0 — Scope: cartographer maps the repo (language-agnostic)
phase("Scope");
const scope = await agent(/* … */, { agentType: "Explore", schema: SCOPE_SCHEMA });
const SHARED_CONTEXT = /* built entirely from scope */;

// PHASE 1+2 — Review then Verify, pipelined per lens
phase("Review");
const perLens = await pipeline(
  reviewers,
  // Stage 1 — specialist review on Sonnet
  (r) => agent(/* … */, { model: "sonnet", agentType: r.agentType, schema: FINDINGS_SCHEMA })
           .then((res) => ({ lens: r, review: res })),
  // Stage 2 — per-finding independent adversarial verify on Opus
  async (prev) => {
    const toRefute = prev.review.findings.filter((f) => f.severity !== "suggestion");
    const verdicts = await parallel(
      toRefute.map((f) => async () => {
        const v = await agent(/* refute-by-default */, { model: "opus", schema: VERDICT_SCHEMA });
        return v?.confirmed && v.adjustedSeverity !== "dropped"
          ? { ...f, severity: v.adjustedSeverity, verified: true }
          : null;
      }),
    );
    return { lens: prev.lens.key, confirmed: verdicts.filter(Boolean) };
  },
);

// PHASE 3 — Coordinate: dedup, judge, render
phase("Coordinate");
const coord = await agent(/* dedup + rubric */, { schema: COORD_SCHEMA });
return { decision: coord.decision, reviewBody: coord.reviewBody, /* … */ };
```

</Collapsible>

## What I Changed From Cloudflare, and Why

Side by side, the differences are smaller than they look, and each one comes from a different constraint.

| | Cloudflare | My workflow |
|:--|:----------|:------------|
| **Input** | A merge request diff | A whole repo, any language |
| **Discovery** | Diff is the scope | A cartographer maps the scope |
| **Orchestrator** | Custom `spawn_reviewers` tool | Built-in `pipeline` / `parallel` |
| **Reviewer prompts** | Hand-written markdown files | Claude Code's existing subagents |
| **Verification** | Coordinator judges the batch | Independent, cross-model, refute-by-default |
| **Runs in** | GitLab CI, Cloudflare Workers | My laptop, one script |

The one I would defend hardest is verification. Folding the check into the coordinator is fine when the coordinator is a frontier model with a good "what not to flag" prompt and you have tens of thousands of reviews of tuning behind it. For a workflow I wrote in an evening, a batch judge rubber-stamps. Pulling verification into its own phase — one finding, one fresh stronger model, told to refute — is what turned the output from "43 plausible claims" into a list I actually trust.

## Limitations I'm Honest About

This is not Cloudflare's system and it is not pretending to be. A few things I know it does not do:

- **It is not in the critical path.** No CI gate, no circuit breakers, no failback when a provider is down. If Opus is overloaded mid-run, a verifier returns `null` and the finding quietly drops. Cloudflare spent real effort on resilience because engineers were blocked on it. I am not blocked on it.
- **It costs more per run than a diff review.** Mapping and reviewing a whole repo is more tokens than reviewing a 40-line change. Cloudflare's risk tiers — don't send seven Opus agents to review a typo — are the obvious next thing to steal, and I have not yet.
- **It inherits the model's blind spots.** Same honesty Cloudflare ended on: subtle concurrency bugs, cross-system impact, and "is this architecture moving in the right direction" are still beyond a static read of the code. This catches real bugs. It does not replace a human who knows why the system was built this way.

## Conclusion

The lesson I keep taking from posts like Cloudflare's is that the impressive part is rarely the part you need. I did not need their plugin architecture or their Workers control plane. I needed three ideas — specialists over one big prompt, tell the model what not to flag, and a coordinator that judges — and Claude Code's workflow primitive handed me the orchestration for free.

The piece I am proudest of is the piece where I disagreed. Copying their coordinator-judges design gave me a check that verified nothing. Pulling verification into its own phase, with an independent stronger model told to refute by default, is what made the output trustworthy. If you take one thing from this post, take that: a verification step that never drops anything is not a verification step, it is a comfort blanket. Make your checker try to prove you wrong, on a different model, one claim at a time. The whole script is [in the gist](https://gist.github.com/alexanderop/b2493855e0052b89da3f6d962c5b0aa9) — point it at one of your repos and see what it refuses to flag.

---

--- title: How I Became an International Speaker description: I was too scared to publish my first blog post and ended up on stage at Vue Amsterdam. Here's the honest path from zero to international speaker, visibility first. tags: ['personal-development', 'speaking', 'writing'] url: https://alexop.dev/posts/how-i-became-an-international-speaker ---

# How I Became an International Speaker



Lately people have asked me how to become a speaker themselves, and every time I feel a bit of cringe, because part of me thinks it's fake.

It happened at the conferences I spoke at, and also online.
That's why I thought I'd write a blog post about it. I also want to reflect a bit on my journey.
Hopefully it motivates other people to do the same, because becoming an international speaker was one of the best things I ever did in my life.

## A little background

When I was younger I often struggled with what you would now call "anxiety". I was always afraid to talk to random people, and at school I hated having to give a presentation in front of a bigger audience.

I think two things changed that:

- starting boxing when I was younger
- finding something I really love, like coding, which motivated me to share my knowledge

## How I started with writing blog posts

I once read a book about career tips for software developers, and one point stuck with me: if you want to stand out as a dev, start writing a blog. So probably in my second year as a developer, I started writing blog posts on dev.to.
dev.to is a really good platform to start on, because people see your blog post in their feed and can vote on it.

It's the easiest way to start if you don't have any audience yet. What I'd also recommend now is to create a real blog of your own and keep the canonical URL there.

## Find a niche

When you start writing technical blog posts, I think it's worth concentrating on one thing.
For me that was Vue. The advantage is that you quickly understand which topics aren't covered yet.

The easiest way for a blog post to get views is to write about something that hasn't been covered yet and that would be interesting for devs.

## How to grow your blog post

It's not enough to only write about interesting things, people also need to know they exist. That's especially hard if nobody knows your blog yet. How I did it:

- post on Reddit
- tell every newsletter that my blog post exists
- share it on my socials

## Get good at content creation 

So now we know we need to be visible somehow. As I said, I chose blogging, but you could also start with YouTube. It all depends on your personality and how much time and effort you have.
Time wise, blogging is definitely easier. Although once you have a good setup and don't want to do fancy things, YouTube can be fast too.
There are many books about how to write better, for example:

- [Writing for Developers](https://www.manning.com/books/writing-for-developers), I can highly recommend it
- [Economical Writing](https://www.amazon.com/dp/022644807X), a good book, but to be honest, with AI I got a bit lazy

## Use your Work for practice

Most of my Expierence on preparing a Talk was from work itself. Most of the time there are always sessions where devs
can share their knoledge use that and practice

## Now apply apply apply

Once you're visible, and of course you can start this in parallel, apply for anything:

- find out which meetups in your city cover the topics you share
- use [Sessionize](https://sessionize.com/) to find conferences accepting talks

Here is the whole path in one picture, from the first blog post I was too scared to publish to the stage at Vue.js Amsterdam.

---

--- title: Claude Code Workflows: Deterministic Multi-Agent Orchestration description: Workflows let you script how Claude Code fans out across dozens of subagents, then synthesizes the results. Here's how they work, the primitives, and the small example I built to understand them. tags: ['claude-code', 'ai', 'tooling', 'orchestration'] url: https://alexop.dev/posts/claude-code-workflows-deterministic-orchestration ---

# Claude Code Workflows: Deterministic Multi-Agent Orchestration



Claude Code shipped **workflows** recently, and the docs describe a lot of machinery: deterministic orchestration, `parallel` and `pipeline`, journaling and resume, adversarial verify patterns. I wanted to understand it rather than skim the feature list, and the way I learn a tool is to build the smallest real thing with it.

So I picked a task with an obvious fan-out shape: "what happened in the Vue and Nuxt ecosystem this week." Many independent sources to check, then a merge, then a write-up. I wrote a ~130-line workflow that spawns nine agents in parallel, each scouring a different source, collects their findings into one list, ranks them by impact, and writes a digest. It's a throwaway, but building it taught me how the whole feature fits together. This post is what I learned.

A workflow is the newest piece of Claude Code's orchestration story. In my <InternalLink slug="from-tasks-to-swarms-agent-teams-in-claude-code">post on agent teams</InternalLink> I traced the progression from subagents to teams. Workflows are the next rung, and they solve a different problem than either: when you want the *control flow itself* to be deterministic, not decided turn-by-turn by a model.

If you want a sense of the ceiling before the toy example, Jarred Sumner credited dynamic workflows and adversarial code review for porting Bun from Zig to Rust in six days:

<TLDR
  items={[
    "A workflow is a plain JavaScript script that orchestrates subagents deterministically: you own the loops and fan-out, agents do the thinking",
    "The shape that generalizes: fan out → reduce → synthesize",
    "agent() runs one subagent (use a schema for validated JSON), parallel() is a barrier, pipeline() streams items through stages with no barrier",
    "Default to pipeline(); reach for a parallel() barrier only when a stage needs all prior results at once",
    "Compose verify/judge/loop-until-dry patterns for confidence, not more agents",
    "It's opt-in and token-hungry, so reach for it when a job needs breadth, verification, or scale a single context can't hold",
  ]}
/>

## Table of Contents

## Where Workflows Fit

Most of the time a single Claude Code session works turn-by-turn: read a file, decide, call a tool, look at the result, decide again. That loop is the right tool for most work. Some jobs don't fit one head and one context window though:

- **Comprehensive** jobs: "review every file in this diff", "audit all 40 dependencies".
- **Confidence-critical** jobs: "find the bug, then have three independent skeptics try to refute it".
- **Scale** jobs: migrations, sweeps, anything bigger than one context can hold.

Subagents and agent teams can attack these, but there's a subtle difference in *who holds the plan*.

| | Subagents | Agent Teams | Workflows |
|:--|:----------|:------------|:----------|
| **What it is** | A worker Claude spawns | Independent Claude sessions | A script the runtime executes |
| **Who decides what's next** | Claude, turn by turn | Claude and the teammates | The script |
| **Where results live** | Claude's context | Each session's context | Script variables |
| **What's repeatable** | The worker definition | The team setup | The orchestration itself |
| **Scale** | A few per turn | A handful of sessions | Dozens to hundreds of agents |

With subagents and skills, Claude is the orchestrator. It decides turn by turn what to spawn, and every result lands back in its context window. A workflow moves the plan into code. The script holds the loop, the branching, and the intermediate results, so Claude's context only ever sees the final answer. That is what lets a workflow scale to hundreds of agents without drowning the conversation.

## The Core Idea

A normal agent decides the control flow as it goes. A workflow inverts that. *You* write the control flow as plain code, and each individual step is delegated to a fresh subagent. The orchestration is deterministic; only the work inside each `agent()` call is model-powered.

That distinction is the whole point. When you write this:

```js
const results = await parallel(files.map((f) => () => agent(`Review ${f}`)));
```

You know exactly one agent runs per file, they all run concurrently, and you get an array back. There are no emergent "the model decided to skip three files" surprises. You get determinism in the orchestration and model judgment inside each step.

The shape that keeps showing up is **fan out → reduce → synthesize**:

<Mermaid chart={`
graph LR
    A[fan out] --> B[agent 1]
    A --> C[agent 2]
    A --> D[agent ...]
    A --> E[agent N]
    B --> F[reduce: dedupe + rank]
    C --> F
    D --> F
    E --> F
    F --> G[synthesize: write the result]
`} />

Swap the sources and prompts and the same skeleton becomes a market scan, a dependency audit, a code review, or a research report.

## The Example I Built to Learn It

Here is the workflow I wrote. I picked the newsletter task because it forces you to use every part of the feature: a wide fan-out, a reduce step, and a synthesis step. Every script starts with a `meta` block that must be a **pure literal**, then a body using the orchestration primitives.

```js
export const meta = {
  name: "vue-newsletter",
  description: "Research Vue/Nuxt sources in parallel and synthesize a newsletter",
  phases: [
    { title: "Research", detail: "one agent per source" },
    { title: "Curate", detail: "dedupe + rank by impact" },
    { title: "Write", detail: "synthesize the newsletter" },
  ],
};
```

### 1. Fan out with `parallel()`

Nine sources, nine agents, all at once. Each returns structured JSON validated against a schema, so the model retries on mismatch and I never parse free text:

```js
phase("Research");
const raw = await parallel(
  SOURCES.map((s) => () =>
    agent(s.prompt, {
      label: `research:${s.key}`,
      phase: "Research",
      schema: ITEM_SCHEMA, // forces validated structured output
      agentType: "general-purpose",
    }),
  ),
);
```

The `SOURCES` array is just data: one entry per source with a prompt. GitHub core releases, the Nuxt ecosystem, the official blogs, Hacker News, Reddit, dev.to, key people like Evan You and Anthony Fu, and the newsletter/podcast circuit.

### 2. Reduce with plain JavaScript

Flattening, deduping, and filtering is just code. No agent needed:

```js
const collected = raw.filter(Boolean); // skipped/failed agents become null
const flatItems = collected.flatMap((c) => c.items);
log(`Collected ${flatItems.length} items`);
```

### 3. Synthesize with sequential `agent()` calls

```js
phase("Curate");
const curated = await agent(curatePrompt, { phase: "Curate", schema: CURATED_SCHEMA });

phase("Write");
const newsletter = await agent(writePrompt, { phase: "Write" });

return { newsletter, itemCount: flatItems.length, curated };
```

The run I did while testing pulled together a Nuxt UI release, a Vue Router v5 minor, a Vue core patch, and a Madrid conference recap: seventeen items across nine sources in about three minutes. Good enough to convince me the orchestration worked, which was the whole point of building it.

<Aside type="tip" title="Structured output is the reliable path">
The `schema` option forces a subagent to call a structured-output tool, and validation happens at the tool-call layer so the model retries on mismatch. This is far more reliable than asking an agent to "please return JSON" and hoping. Reach for it whenever a downstream stage consumes the result.
</Aside>

## The Primitives

A handful of functions do all the work.

**`agent(prompt, opts?)`** spawns one subagent. Without options it returns the agent's final text. The options worth knowing:

- `schema`: a JSON Schema. The subagent is forced to return validated structured data.
- `label`: the display name in the progress UI.
- `phase`: assigns the agent to a progress group. Use it inside `parallel()` and `pipeline()` to avoid racing on the global `phase()` state.
- `model`: override the model for this one call. Default is to omit it so the agent inherits your session model.
- `agentType`: use a custom subagent type instead of the default workflow agent.
- `isolation: "worktree"`: run the agent in its own git worktree. Only when agents write files in parallel and would otherwise conflict.

**`parallel(thunks)`** runs tasks concurrently. It is a **barrier**: it waits for every thunk before returning. A thunk that throws resolves to `null` rather than rejecting the whole call, so always `.filter(Boolean)` the results. You can pass a hundred thunks and they'll all complete, but only a handful run at once: concurrency is capped at roughly your core count, and the excess queue.

**`pipeline(items, ...stages)`** runs each item through all stages **independently, with no barrier between stages**. Item A can be in stage 3 while item B is still in stage 1. Each stage callback receives `(prevResult, originalItem, index)`.

**`workflow(nameOrRef, args?)`** runs *another* workflow inline as a sub-step and returns whatever it returns. Pass a name to invoke a saved workflow, or `{ scriptPath }` to run a script file. This is composition: a research workflow can call `/deep-research` as one of its stages instead of reimplementing the fan-out. The child shares the parent's concurrency cap, agent counter, and token budget, and shows up as its own group in `/workflows`. Nesting is one level deep: a `workflow()` call inside a child throws.

```js
// inside a script: hand a sub-question off to the bundled deep-research workflow
const report = await workflow("deep-research", { question: topic });
```

The rest are small helpers: `phase(title)` starts a progress group, `log(msg)` emits a narrator line, `args` carries the JSON you passed in when launching, and `budget` exposes the token target so you can scale depth dynamically (it's `null` when you launch without a target, so guard any loop-until-budget on `budget.total` or it runs to the agent cap).

<Alert type="warning">
`Date.now()`, `Math.random()`, and an argless `new Date()` all throw inside a workflow. Workflows journal every `agent()` call so a run can resume, and non-determinism would invalidate that cache. If you need a timestamp, pass it through `args`. If you need variety across agents, vary the prompt or label by index.
</Alert>

## `pipeline` vs `parallel`: The Decision That Matters

This trips people up, so here is the rule I follow.

**Default to `pipeline()`.** Reach for a `parallel()` barrier between stages *only* when a stage needs **all** prior results at once.

Legitimate reasons for a barrier:

- ✅ Dedupe or merge across the full result set before expensive downstream work.
- ✅ Early-exit on the total ("0 findings, skip verification entirely").
- ✅ A prompt that references "the other findings" for comparison.

Not legitimate:

- ❌ "I need to flatten or filter first." Do it inside a pipeline stage.
- ❌ "The stages feel conceptually separate." Separate is not the same as synchronized.
- ❌ "It's cleaner code." Barrier latency is real wall-clock waste.

The smell test: if you wrote `parallel` → transform → `parallel`, and that middle transform has no cross-item dependency, you should have used a pipeline. The newsletter example *does* use a barrier, and correctly: curation has to see every source before it can dedupe and rank across them.

## Quality Patterns

The primitives compose into reusable harnesses. This is the real value over spawning more agents: the structure is what produces confidence. A few I lean on:

- **Adversarial verify**: for each finding, spawn N independent skeptics prompted to *refute* it. Kill it unless a majority survive. Stops plausible-but-wrong findings from shipping.
- **Perspective-diverse verify**: give each verifier a distinct lens (correctness, security, performance, does-it-reproduce) instead of N identical ones. Diversity catches failure modes redundancy can't.
- **Judge panel**: generate N attempts from different angles, score with parallel judges, synthesize from the winner while grafting the best of the runners-up.
- **Loop-until-dry**: for unknown-size discovery, keep spawning finders until K consecutive rounds surface nothing new.

Here is loop-until-dry with a diverse-lens verify, condensed:

```js
const seen = new Set();
const confirmed = [];
let dry = 0;
while (dry < 2) {
  const found = (await parallel(FINDERS.map((f) => () =>
    agent(f.prompt, { phase: "Find", schema: BUGS })))).filter(Boolean).flatMap((r) => r.bugs);
  const fresh = found.filter((b) => !seen.has(key(b)));
  if (!fresh.length) {
    dry++;
    continue;
  }
  dry = 0;
  fresh.forEach((b) => seen.add(key(b)));
  const judged = await parallel(fresh.map((b) => () =>
    parallel(["correctness", "security", "repro"].map((lens) => () =>
      agent(`Judge "${b.desc}" via the ${lens} lens — real?`, { phase: "Verify", schema: VERDICT })))
      .then((vs) => ({ b, real: vs.filter(Boolean).filter((v) => v.real).length >= 2 }))));
  confirmed.push(...judged.filter((v) => v.real).map((v) => v.b));
}
```

One detail makes or breaks this: dedupe against everything *seen*, not just confirmed results. Otherwise rejected findings reappear every round and the loop never converges.

## A Shipped Example: How `/deep-research` Works

My newsletter generator is a toy. If you want to see these patterns in a real, bundled workflow, run `/deep-research`. It takes a question and returns a cited report, and under the hood it's the same **fan out → reduce → synthesize** skeleton with an **adversarial verify** pass bolted on. It's the quality pattern from the section above, running in production.

When you launch it the workflow announces its plan and runs in the background while you keep working:

It moves through five phases:

1. **Scope:** one agent decomposes your question into five distinct search angles, so the searches don't all chase the same wording.
2. **Search:** five web searches run in parallel, one per angle. This is the fan-out.
3. **Fetch:** dedupe the URLs across angles, pull the top ~15 sources, and extract individual claims from them.
4. **Verify:** the interesting part. Each claim gets an adversarial three-vote check, with skeptics trying to refute it. Claims that don't survive never reach the report.
5. **Synthesize:** one final agent writes the cited report from the claims that held up.

Map that onto the primitives and you can almost see the script: a single `agent()` for scope, a `parallel()` fan-out for the five searches, plain JavaScript to dedupe in fetch, a per-claim verify pass (the same `parallel()` of skeptics from the loop-until-dry example), and a closing `agent()` to synthesize. The phases show up in `/workflows` as named groups (`Scope 1/1`, `Search 0/5`, `Fetch`, `Verify`, `Synthesize`), each with its own agent count, token total, and elapsed time, so you can drill into any single search or verification and read its prompt and result.

This is the difference between "ask Claude to research something" and a workflow. A single agent doing web research holds every half-read source in one context and never checks its own claims. `/deep-research` decomposes the search so coverage is wide, keeps the intermediate sources out of your conversation, and runs a verification pass a single turn-by-turn agent would never run against itself.

## Triggering and Watching a Run

Worth saying plainly: from Claude Code's side, a workflow is **a tool**. There's a `Workflow` tool the same way there's a `Read` or `Bash` tool, and "running a workflow" means Claude calls that tool with a script. The runtime executes the script in the background while your session stays responsive, which is why you can keep chatting while dozens of agents churn away.

There are a few ways a workflow gets written and launched:

1. **Say "workflow" in your prompt.** Include the word and Claude writes a workflow script for the task instead of working through it turn by turn.
2. **Run a saved or bundled command.** A workflow you saved to the project, or the built-in `/deep-research` covered above.
3. **Turn on `ultracode`.** Claude plans a workflow for every substantial task in the session.

<Prompt>
Run a workflow to audit every API endpoint under src/routes/ for missing auth checks. Spawn one agent per route file, then have a second pass verify each finding before reporting.
</Prompt>

When a run does what you wanted, you can save it: Claude Code writes the script into **`.claude/workflows/`** in your repo as a `<name>.js` file (the appendix below is exactly that file for my newsletter). Because it lives in the repo, it's version-controlled and anyone who clones it can launch it by name and pass arguments:

<Prompt>
Run the vue-newsletter workflow with args `{"weekStart":"2026-06-04","weekEnd":"2026-06-11"}`
</Prompt>

Runs happen in the background, and **`/workflows`** is how you watch them: it lists every run, including which ones are **currently running**, and opens a progress view showing each phase with its agent count, token total, and elapsed time. You can drill into a phase, then into a single agent, to read its prompt and result, pause or stop a run, or press `s` to save a good one's script as a reusable `/<name>` command under `.claude/workflows/`.

## When to Reach for One

<Mermaid chart={`
graph TD
    A[Does the job need breadth,<br/>verification, or scale?] -->|No| B[Single session<br/>or a subagent]
    A -->|Yes| C[Do you want the control flow<br/>to be deterministic and repeatable?]
    C -->|No| D[Agent team]
    C -->|Yes| E[Write a workflow]
`} />

**Good fit** ✅

- Decomposing a job so every part is covered in parallel (audits, reviews, sweeps).
- Anything you want to *re-run* with the same structure (a weekly competitor scan, a release checklist).
- Confidence-critical work where a repeatable verify or judge pass beats one model's first answer.

**Bad fit** ❌

- An ordinary task one agent can do turn by turn. Let one agent do it.
- Work that needs you to weigh in between every stage. A workflow can't take mid-run input; only agent permission prompts pause it.
- Anything where the token cost of dozens of agents isn't justified by breadth or scale.

<Alert type="warning">
A workflow spawns many agents, so one run can use meaningfully more tokens than doing the same task in conversation, and it counts toward your plan's usage. Every agent uses your session's model unless the script routes a stage elsewhere, so check `/model` before a large run and consider routing cheap stages to a smaller model.
</Alert>

## Conclusion

- A workflow is a JavaScript script that orchestrates subagents deterministically. You own the control flow, agents do the thinking, and the plan lives in code so the conversation only sees the final answer.
- The shape that generalizes is **fan out → reduce → synthesize**. The newsletter generator I built is a deliberately small instance of it.
- `agent()` runs one (use a `schema` for validated structured output), `parallel()` is a barrier, `pipeline()` streams items through stages with no barrier. **Default to pipeline.**
- The leverage is the repeatable quality patterns: adversarial verify, diverse lenses, judge panels, loop-until-dry.
- It is opt-in and token-hungry. Reach for it when a job needs breadth, independent verification, or scale a single context can't hold. Otherwise let one agent do the work.

If you've already worked through <InternalLink slug="claude-code-customization-guide-claudemd-skills-subagents">subagents and skills</InternalLink>, workflows are the natural next tool. The fastest way to understand them is the same way I did: pick a small task with a clear fan-out shape and build the throwaway version. Mine was a newsletter generator I won't run again. The point was never the newsletter; it was seeing how the pieces fit, so that when a job needs breadth or verification, reaching for a workflow is obvious.

---

## Appendix: The Full Script

Everything above is excerpts. Here is the complete `.claude/workflows/vue-newsletter.js` in one piece, so you can see how the `meta` block, the schemas, the source list, and the three phases fit together. It's plain JavaScript: no imports, no filesystem access, inputs via `args`, results via `return`.

<Collapsible title="vue-newsletter.js: the complete workflow">

```js
export const meta = {
  name: 'vue-newsletter',
  description: 'Research Vue/Nuxt ecosystem sources in parallel for a given week and synthesize a newsletter',
  whenToUse: 'Generate a weekly Vue/Nuxt newsletter. Pass args {weekStart, weekEnd, label} as ISO dates (e.g. {"weekStart":"2026-05-21","weekEnd":"2026-05-28"}). With no args, agents cover the past 7 days from today.',
  phases: [
    { title: 'Research', detail: 'one agent per source — releases, blogs, social, people' },
    { title: 'Curate', detail: 'dedupe + rank items by impact' },
    { title: 'Write', detail: 'synthesize the final newsletter' },
  ],
}

// Args are optional. Pass {weekStart, weekEnd, label} as ISO dates to scope a specific week.
// With no args, agents are told to cover "the past 7 days from today" (they resolve the date via web search).
const hasRange = args && args.weekStart && args.weekEnd
const weekStart = hasRange ? args.weekStart : null
const weekEnd = hasRange ? args.weekEnd : null
const label = (args && args.label) || (hasRange ? `Week of ${weekStart}–${weekEnd}` : 'this week')
const window = hasRange ? `between ${weekStart} and ${weekEnd}` : 'within the past 7 days from today'

const ITEM_SCHEMA = {
  type: 'object',
  additionalProperties: false,
  properties: {
    source: { type: 'string' },
    items: {
      type: 'array',
      items: {
        type: 'object',
        additionalProperties: false,
        properties: {
          title: { type: 'string' },
          url: { type: 'string' },
          summary: { type: 'string', description: '1-3 sentence plain summary of what changed / why it matters' },
          category: { type: 'string', enum: ['release', 'article', 'tooling', 'discussion', 'tutorial', 'people', 'other'] },
          date: { type: 'string', description: 'ISO date if known, else empty' },
          impact: { type: 'string', enum: ['high', 'medium', 'low'] },
        },
        required: ['title', 'url', 'summary', 'category', 'impact'],
      },
    },
  },
  required: ['source', 'items'],
}

// Each source is researched by its own agent in parallel.
const SOURCES = [
  {
    key: 'core-releases',
    prompt: `Find releases/changelogs published ${window} for these GitHub repos: vuejs/core, vuejs/router (vue-router), vuejs/pinia, vueuse/vueuse, vitejs/vite, vitejs/vitest. For each new release in that window, give the version, the highlights, and the release URL. Skip anything outside the date window.`,
  },
  {
    key: 'nuxt-releases',
    prompt: `Find releases/changelogs published ${window} for the Nuxt ecosystem on GitHub: nuxt/nuxt, nuxt/ui, nuxt/image, nuxt/content, unjs/nitro, unjs/h3. Give version, highlights, and URL for each release in that window only.`,
  },
  {
    key: 'vue-blog',
    prompt: `Check the official Vue.js blog (blog.vuejs.org) and Vue.js news for posts published ${window}. Summarize each post with its URL.`,
  },
  {
    key: 'nuxt-blog',
    prompt: `Check the official Nuxt blog (nuxt.com/blog) for posts published ${window}. Summarize each with URL.`,
  },
  {
    key: 'hackernews',
    prompt: `Search Hacker News (news.ycombinator.com) for stories about Vue, Nuxt, Vite, or Pinia that were active/posted ${window}. Include the HN discussion URL and the linked article. Note points/comments if visible.`,
  },
  {
    key: 'reddit',
    prompt: `Search Reddit r/vuejs and r/Nuxt for notable threads posted ${window} — announcements, releases, popular discussions, showcased projects. Give the reddit thread URL for each.`,
  },
  {
    key: 'devto',
    prompt: `Search dev.to for the most useful Vue and Nuxt tagged articles published ${window} (tutorials, deep-dives, tips). Give URLs.`,
  },
  {
    key: 'people',
    prompt: `Look for notable updates, posts, or talks ${window} from key Vue/Nuxt people: Evan You (@youyuxi / VoidZero), Daniel Roe (Nuxt lead), Anthony Fu (VueUse/Vitesse/Slidev), Eduardo San Martin Morote (posva — router/pinia), Sébastien Chopin (Nuxt/NuxtLabs). Include VoidZero and NuxtLabs company news too. Give URLs.`,
  },
  {
    key: 'newsletters-podcasts',
    prompt: `Find Vue/Nuxt newsletter issues and podcast episodes published ${window}: Vue.js Newsletter (news.vuejs.org), This Week in Vue, Michael Thiessen's newsletter, DejaVue podcast, Deox/Vue Mastery content. Summarize and give URLs.`,
  },
]

phase('Research')
const raw = await parallel(
  SOURCES.map((s) => () =>
    agent(
      `You are researching the Vue.js / Nuxt ecosystem for a weekly newsletter covering ${label} (${window}).\n\n${s.prompt}\n\nUse web search and fetch real URLs. Only include items genuinely within the date window. Return real, verifiable URLs — never invent links. If you find nothing in the window, return an empty items array. Set impact based on how much the average Vue developer should care.`,
      { label: `research:${s.key}`, phase: 'Research', schema: ITEM_SCHEMA, agentType: 'general-purpose' },
    ),
  ),
)

const collected = raw.filter(Boolean)
const flatItems = collected.flatMap((c) => (c.items || []).map((it) => ({ ...it, source: c.source })))
log(`Collected ${flatItems.length} items across ${collected.length} sources`)

phase('Curate')
const CURATED_SCHEMA = {
  type: 'object',
  additionalProperties: false,
  properties: {
    highlights: { type: 'array', items: { type: 'string' }, description: '2-4 sentence TLDR bullets of the biggest stories this week' },
    items: {
      type: 'array',
      items: {
        type: 'object',
        additionalProperties: false,
        properties: {
          title: { type: 'string' },
          url: { type: 'string' },
          summary: { type: 'string' },
          category: { type: 'string' },
          impact: { type: 'string' },
        },
        required: ['title', 'url', 'summary', 'category', 'impact'],
      },
    },
  },
  required: ['highlights', 'items'],
}

const curated = await agent(
  `Here are raw newsletter candidate items gathered from multiple sources for the Vue/Nuxt week of ${label}:\n\n${JSON.stringify(flatItems, null, 2)}\n\nCurate them:\n1. Remove duplicates (same release/article surfaced by multiple sources — keep the best canonical URL).\n2. Drop low-quality, off-topic, or spammy entries.\n3. Rank by impact (high first).\n4. Write 3-5 punchy "highlights" bullets capturing the week's biggest stories.\nKeep every URL exactly as provided — do not fabricate or alter links.`,
  { phase: 'Curate', schema: CURATED_SCHEMA },
)

phase('Write')
const newsletter = await agent(
  `Write a polished weekly Vue.js / Nuxt newsletter in Markdown for ${label}.\n\nUse this curated data:\n${JSON.stringify(curated, null, 2)}\n\nStructure:\n- A title with the week range and a one-paragraph intro setting the tone.\n- "📌 This Week's Highlights" — the highlights bullets.\n- "🚀 Releases" — version bumps with what changed (group Vue core + Nuxt + tooling).\n- "📝 Articles & Tutorials".\n- "🛠️ Tooling & Ecosystem".\n- "💬 Community & Discussion".\n- "👤 From the Core Team & Community" — people/company news.\n- A short friendly sign-off.\n\nEvery item must be a markdown link to its real URL. Keep summaries tight and developer-focused. Omit any empty section. Output ONLY the markdown newsletter.`,
  { phase: 'Write' },
)

return { newsletter, itemCount: flatItems.length, curated }
```

</Collapsible>

---

--- title: How to do AFK Coding description: A pipeline for shipping a 5-point ticket while you're away from the keyboard: spec with the human in the loop, slice into vertical tickets, run a Ralph loop with TDD per slice, refactor, then let an agent-browser do QA. tags: ['ai', 'claude-code', 'agentic-coding', 'ralph', 'spec-driven-development'] url: https://alexop.dev/posts/how-to-do-afk-coding ---

# How to do AFK Coding



<TLDR items={[
  "1–3 story-point tickets fit in one Opus 4.7 or GPT 5.5 shot. 5+ pointers don't. The context fills, the model auto-compacts, and the refactor never happens.",
  "AFK coding is HITL at the edges, AFK in the middle. You align on the spec, you review the PR. Everything between runs without you.",
  "The pipeline: spec → vertical-slice sub-tickets → Ralph loop per slice with TDD red-green-refactor → dedicated refactor pass → agent-browser QA → PR.",
  "You're a manager now: review, QA, and several pipelines in parallel.",
]} />

## The Pipeline

The workflow I use to ship a 5-point ticket while I'm away from the keyboard:

<Figure
  src={pipelineImage}
  caption="The AFK coding pipeline: human judgment at the edges, agent execution in the middle"
  alt="Pixel art diagram of the AFK coding pipeline showing six phases: Spec, Slice, Ralph Loop, Refactor, QA, Review, with HITL human judgment bookending AFK agent execution"
  size="full"
/>

Six phases. The first and last are human, the middle four run on their own.

```
1. Align on spec        ── HITL ──  business + dev + AI interviewer
2. Slice the ticket     ── AFK  ──  vertical slices, one per sub-ticket
3. Ralph loop per slice ── AFK  ──  fresh context, TDD red-green-refactor
4. Refactor pass        ── AFK  ──  the step LLMs always skip
5. Agentic QA           ── AFK  ──  agent-browser drives the real UI
6. Review               ── HITL ──  dev reviews, business does UAT
```

Two questions first: when this pipeline pays off, and what "AFK" looks like in practice.

## Two Kinds of Tickets

<Figure
  src={ticketSizesImage}
  caption="1–3 pointers fit one prompt. 5+ pointers overflow context, skip tests, and ship messy PRs."
  alt="Pixel art comparison of a small ticket flowing one prompt to one agent to a clean PR, versus a large ticket where one huge prompt produces context overflow, skipped tests, and a messy PR"
  size="full"
/>

Most tickets fit in one Claude Code session. Paste it in, watch it land, ship the PR. Opus 4.7 or GPT 5.5 close out a 1–3 pointer with maybe one nudge. No pipeline needed.

The interesting tickets are the 5-pointers. Frontend and backend, a multi-step wizard with three API calls, server-side validation, optimistic UI, and a test plan that catches the failure modes you care about. Paste that into a fresh chat and one of three things happens:

1. **Context runs out.** The model hits the window halfway through and auto-compacts. The summary drops the bit you needed. As [HumanLayer's 12 Factor Agents](https://www.humanlayer.dev/blog/12-factor-agents) puts it: _"Even as models support longer and longer context windows, you'll ALWAYS get better results with a small, focused prompt and context."_
2. **No refactoring.** LLMs default to append, not restructure. Ship five of these in a row and your codebase looks like the inside of a hoarder's garage.
3. **Silent skip.** When a test fails on round four, the model deletes the test rather than fixing the bug. Opus does this often. Michael Arnaldi caught it taking the same shortcut in his <InternalLink slug="vibe-engineering-effect-apps" collection="notes">Effect workshop</InternalLink>: _"sometimes a feature, sometimes a bug — takes shortcuts, sleeps, removes failing tests rather than fixing them."_

This is a workflow problem, not a model problem. Big tickets need a pipeline, not a prompt. The one diagrammed above.

## What AFK Coding Looks Like

<Figure
  src={hitlEdgesImage}
  caption="Human aligns the spec, agents do the work, human reviews the PR."
  alt="Pixel art assembly line showing a human aligning the spec at the top, three agents doing the work in the middle, and a human reviewing the PR at the bottom"
  size="full"
/>

AFK = away from keyboard. HITL = human in the loop. Sounds opposed; isn't. The good workflow is **HITL at the edges, AFK in the middle**.

- **HITL up front.** A human aligns on what to build. Judgment lives here.
- **AFK in the middle.** Once the spec is solid, the agent ships it. You go for a walk.
- **HITL at the end.** Review the PR, eyeball the QA report, ship.

You don't write less code. You run three pipelines in parallel while reading a book. You manage instead of coding. I wrote about the broader shift in <InternalLink slug="the-software-factory">The Software Factory</InternalLink>; this post zooms into the pipeline that powers a single ticket inside it.

## Phase 1: Align on the Spec (HITL)

Don't skip this. Every problem downstream starts here. Dex Horthy puts the cost in stark terms in [Advanced Context Engineering for Coding Agents](https://github.com/humanlayer/advanced-context-engineering-for-coding-agents):

> "A flawed specification cascades through hundreds of lines; flawed research generates thousands of bad lines."

A 5-pointer touches enough surface area that "what we want" needs to be explicit. Sit with the business, talk through the wizard, draw the state machine on a napkin. Then write a real PRD. A Jira description doesn't count.

Use the AI here too, but in **interview mode, not generation mode**. Open Claude Code with a spec template and let it ask _you_ the questions you'd otherwise forget:

<Prompt>
i want to build a multi-step booking wizard. interview me with one
question at a time until you have enough to write a PRD. cover:
goals, user, happy path, edge cases, validation, error states, and
out-of-scope. write the PRD to docs/prd-booking-wizard.md when done.
</Prompt>

The PRD is the single artifact the rest of the pipeline reads. Skimp here and the agent will ship the wrong thing five times in parallel. <InternalLink slug="spec-driven-development-claude-code-in-action">Spec-Driven Development with Claude Code in Action</InternalLink> covers the prompt patterns I lean on; GitHub's [Spec Kit](https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/) ships a four-phase `/specify → /plan → /tasks → /implement` workflow that encodes the same idea if you'd rather not roll your own.

## Phase 2: Slice Into Vertical Tickets (AFK)

The PRD is too big for one Ralph loop. Slice it.

The right unit isn't "frontend task" + "backend task" + "tests task." That's a horizontal slice, and horizontal slices kill agents. Every slice needs every other slice to be useful, so nothing works until everything works. Compaction guaranteed.

A **vertical slice** is a thin end-to-end strip of behaviour: one API endpoint, the one form step that consumes it, and the one test that proves it works. Each vertical slice is independently shippable. Each one fits in a Ralph loop. Each one survives if its sibling slice fails.

<Figure
  src={slicingImage}
  caption="Horizontal slices block on each other. Vertical slices each ship on their own."
  alt="Pixel art diagram contrasting horizontal slicing (frontend, backend, tests stacked and locked together) against vertical slicing (four end-to-end slices each with their own UI, API, and tests)"
  size="full"
/>

This is Factor 10 of [12 Factor Agents](https://www.humanlayer.dev/blog/12-factor-agents) applied to ticket scoping: _"Small, focused agents — keep agents to 3–20 steps; avoid monolithic designs."_ A vertical slice is the ticket-shaped equivalent. Steve Yegge frames the alternative bluntly in [2026: The Year The IDE Died](https://www.youtube.com/watch?v=7Dtu2bilcFs):

> "Nature builds ant swarms and Claude Code built this huge muscular ant that's just going to bite you in half and take all your resources."

For our wizard:

```
Slice 1: Step 1 — guest info       (form + POST /booking/draft + e2e test)
Slice 2: Step 2 — room selection   (form + GET /rooms + e2e test)
Slice 3: Step 3 — payment          (form + POST /booking/confirm + e2e test)
Slice 4: Wizard state machine      (cross-step navigation + e2e test)
```

Four sub-tickets. Each is a 1–2 pointer. Each is something Opus 4.7 _can_ ship in one go.

Have the agent do the slicing for you:

<Prompt>
read docs/prd-booking-wizard.md. break it into vertical slices.
each slice must be end-to-end (UI + API + test) and independently
shippable. write the slices to docs/tickets/01-*.md, 02-*.md, ...
</Prompt>

## Phase 3: Ralph Loop Per Slice (AFK)

<Figure
  src={ralphLoopImage}
  caption="Each iteration: read PROMPT.md, pick an unchecked task, implement, test, commit, tick the box."
  alt="Pixel art of the Ralph loop: an agent reads PROMPT.md, picks an unchecked task, implements, tests, commits, and ticks the checkbox, all on a fresh context every loop"
  size="full"
/>

For each slice, spin up a fresh agent in a Ralph loop.

Ralph is [Geoffrey Huntley's technique](https://ghuntley.com/ralph/): a `while` loop that pipes a prompt file into a fresh `claude` invocation, over and over, until a stopping condition trips. Every iteration starts with an empty context, reads the prompt file, picks the highest-priority unfinished task, ships it, commits, and exits.

```bash
while :; do
  cat PROMPT.md | claude --dangerously-skip-permissions
done
```

Huntley's framing of why it works:

> "That's the beauty of Ralph — the technique is deterministically bad in an undeterministic world."

You aren't aiming for one perfect run. You're aiming for many cheap runs that converge, with the prompt file as the ratchet. He shipped six repos overnight at a YC hackathon and replaced a \$50K outsourcing contract with \$297 of API spend.

The reason the loop works is the one Dex Horthy chronicles in [A Brief History of Ralph](https://www.humanlayer.dev/blog/brief-history-of-ralph): context windows degrade as they fill. Resetting between iterations keeps every task in the model's "smart zone." Factory's write-up on [The Context Window Problem](https://factory.ai/news/context-window-problem) makes the same case from the engineering side. Bigger windows aren't the answer; smaller scopes are.

<Figure
  src={contextDegradationImage}
  caption="One long session compacts and confuses. Many short sessions stay sharp."
  alt="Pixel art comparison of a long session where context fills, focus drops, and compaction produces confusion, versus three fresh sessions each with small context that ship clean tasks"
  size="full"
/>

A small driver script gives each slice its own Ralph instance, in its own git worktree, with its own log file:

```bash
for ticket in docs/tickets/*.md; do
  name=$(basename "$ticket" .md)
  git worktree add "../wt-$name" -b "feat/$name"
  (
    cd "../wt-$name"
    cp "$ticket" PROMPT.md
    while :; do
      cat PROMPT.md | claude --dangerously-skip-permissions
      grep -q "^- \[ \]" PROMPT.md || break  # exit when no unchecked items
    done
  ) &
done
wait
```

Four slices, four worktrees, four agents, in parallel. Matt Pocock's Sandcastle ([covered here](https://www.youtube.com/watch?v=E5-QK3CDVQM)) is the productionised version of this, with sandboxing on top so the agents can't `rm -rf` your home directory. The cautionary tale is real. See [Claude Code is Amazing... Until It DELETES Production](https://www.youtube.com/watch?v=VqDs46A8pqE). YOLO mode without a sandbox is how you wake up to an empty home folder.

### TDD Inside the Loop

<Figure
  src={tddBackpressureImage}
  caption="Red-green-refactor is the agent's permission slip to commit. Tests, types, and lint are the backpressure that keeps it honest."
  alt="Pixel art of the red-green-refactor cycle next to a pressure gauge labelled 'backpressure from tests, types, lint'"
  size="full"
/>

The Ralph prompt for each slice forces red-green-refactor inside every iteration:

<Prompt>
you are working on ONE slice. read PROMPT.md.

for each unchecked task:
  1. red:      write a failing e2e test that asserts the behaviour
  2. green:    write the minimum code to pass the test
  3. refactor: clean up; tests must stay green
  4. commit
  5. tick the box in PROMPT.md
exit when all boxes are ticked.
</Prompt>

Two reasons TDD matters more for AFK agents than for humans:

- **Without tests, the agent rips the feature out and you never notice.** A passing test it didn't write is a contract; a green CI is the agent's permission slip to commit.
- **Red-green-refactor is the only refactor the agent will do without supervision.** Even that's not enough in practice. That's why Phase 4 exists.

Moss Ebeling calls this [back pressure](https://banay.me/dont-waste-your-backpressure): automated feedback that lets the agent self-correct without you in the loop. If your tests, types, and lint don't break when something is wrong, the agent doesn't know it's wrong. Every minute you spend tightening backpressure is a minute you don't spend reviewing trivial mistakes by hand.

## Phase 4: Refactor Pass (AFK)

<Figure
  src={refactorPassImage}
  caption="A dedicated /simplify pass turns `any`s, duplication, dead code, and inconsistent naming into typed, small, shared, clean code."
  alt="Pixel art before-and-after comparison: messy code with anys, duplication, long files and dead branches gets cleaned by a /simplify pass into typed, small functions, shared composables, clean names, dead code gone, and consistent style"
  size="full"
/>

LLMs cheat on refactoring. Even with red-green-refactor in the loop, the "refactor" step usually shrinks to "rename a variable." The deeper work (extracting a composable, collapsing duplication across the four slices, killing the dead branches) never happens. Leave a single `any` lying around and Opus will copy it everywhere ([Arnaldi's observation](https://www.youtube.com/watch?v=Wmp2Tku2PrI)).

This is why I built `/simplify`: a Claude Code skill that runs an Opus subagent over the recently changed files with one job. Clean it up without changing behaviour. Tests stay green, naming improves, ternaries unfold, abstractions collapse. It's the dedicated refactor pass the implementation loop won't do on its own. It ships as a Claude Code skill, but the pattern is portable — if you're on Codex or another agent, you can wire up the same thing yourself.

Run it as a separate agent against the merged branch with a narrower brief:

<Prompt>
run on the current branch. tests must stay green throughout.

for each of: duplication, long files, primitive obsession, dead
code, and inconsistent naming — find one offender, fix it, run
tests, commit. repeat until you can't find more.

do not change behaviour. do not add features.
</Prompt>

Then add lint-as-backpressure rules so the next slice doesn't undo the cleanup. <InternalLink slug="opinionated-eslint-setup-vue-projects">My ESLint setup</InternalLink> covers the rules I lean on; Michael Arnaldi's <InternalLink slug="vibe-engineering-effect-apps" collection="notes">"clone the repo" workflow</InternalLink> takes the same idea further. Every shortcut you catch the agent taking, ban it with a rule.

## Phase 5: Agentic QA (AFK)

<Figure
  src={agenticQaImage}
  caption="A QA agent drives the real browser through happy and negative paths, dropping screenshots and a markdown report."
  alt="Pixel art of a QA agent walking through a three-step booking wizard in a real browser, ticking off happy path, invalid email, and declined card test cases, then producing screenshots and a markdown report"
  size="full"
/>

Tests prove the unit works. They don't prove the user can complete the wizard. For that, drive a real browser.

[`agent-browser`](https://github.com/vercel-labs/agent-browser) is a Rust CLI that exposes the browser's accessibility tree as a snapshot with stable element refs (`@e1`, `@e2`, …). The agent reads the snapshot, picks a ref, and clicks. No CSS selectors, no Playwright API to learn. Shell commands the agent already knows how to run.

A QA agent runs the user journey end-to-end:

<Prompt>
you are a QA engineer. the booking wizard is at localhost:3000/book.

run the happy path: complete all three steps with valid data.
then run two negative paths: invalid email at step 1, declined
card at step 3.

use agent-browser. take a screenshot at every state. write a
markdown report to qa/booking-wizard.md with one section per
test: steps taken, expected, actual, pass/fail, and the
screenshot.
</Prompt>

You wake up to a markdown report with screenshots. If anything is red, the report tells you which step. If everything is green, the PR is ready for human eyes.

## Phase 6: Human Review (HITL)

The agent opens the PR. Now you do the job.

- **Dev review.** Read the diff. Read the test names. Do they describe behaviour the user cares about? Run the app locally for ten minutes. The bar is "would I have shipped this myself," not "did the agent do what I asked."
- **Business UAT.** Send the PR's preview URL to the person who wrote half the PRD with you. They click through the wizard. They find the thing the agent never could have known to check.

The 30 minutes on the spec and the 30 minutes on the review are 80% of the value. The four hours of coding in between are the part you outsourced. As Linear frames it in [their agent SDK approach](https://linear.app/now/our-approach-to-building-the-agent-interaction-sdk): _"An agent cannot be held accountable."_ Issues get _delegated_ to agents but _assigned_ to humans. Review is the part of the job that doesn't have an AFK version.

## Why This Pipeline Beats "Just Use a Bigger Model"

You could wait for the next model with a 10M-token window and pretend the problem goes away. It won't. [Bigger windows degrade](https://factory.ai/news/context-window-problem): attention thins, costs balloon, and the model still won't refactor on its own.

The pipeline is mostly _the work humans always did_, automated:

- A spec, because nobody ships a 5-pointer without one.
- Vertical slices, because Mike Cohn was right about user stories twenty years ago.
- TDD, because red-green-refactor is the only loop that catches regressions cheaply.
- Code review, because two pairs of eyes are still better than one set of weights.
- QA, because tests don't catch UX.

What changed: the typing happens AFK. You only show up where judgment lives.

<Alert type="info" title="When to skip the pipeline">
For 1–3 pointers, skip all of this. One Claude Code session, one prompt, one PR. The pipeline is overhead for small work; it pays back at 5 points and up.
</Alert>

## The Job Changes

A developer's day in this model:

- 30 minutes: interview-driven spec for ticket A
- 5 minutes: kick off Ralph loops for ticket A
- 30 minutes: interview-driven spec for ticket B
- 5 minutes: kick off Ralph loops for ticket B
- 1 hour: review yesterday's PR, check the QA report
- Repeat

You're a manager of a small fleet of agents. Each ticket is a project; each Ralph loop is a contractor. The skill is your specs, your reviews, and your taste, not your typing speed.

This isn't theoretical. Boris Cherny, creator of Claude Code, runs [15+ parallel Claude sessions on a normal day](https://www.youtube.com/watch?v=AmdLVWMdjOk): five in numbered terminal tabs and another five-to-ten on claude.ai/code, with iTerm notifications when one needs input. Anthropic's headcount tripled and productivity per engineer climbed 70%. Roughly 80–90% of Claude Code is now written by Claude Code itself.

Lee Robinson, after building three production projects without writing code by hand, [puts it bluntly](https://www.youtube.com/watch?v=UrNLVip0hSA):

> "Writing code was never really the bottleneck, especially for larger projects."

Boris reaches the same conclusion from inside Anthropic:

> "We're going to start to see the title of software engineer go away. It's just going to be 'builder' or 'product manager.'"

The pipeline isn't novel. Stripe's Minions, Steve Yegge's Gas Town, Pocock's Sandcastle all encode variants of it. The novel part: the building blocks (Claude Code in headless mode, agent-browser, Ralph, git worktrees) are open and free. You can run this pipeline tonight on your own machine.

<Figure
  src={twentyPipelinesImage}
  caption="Parallelism is limited by review capacity. Past that, every extra pipeline is another fire."
  alt="Pixel art of an overwhelmed agent surrounded by monitors showing failing pipelines, with a list on the left going from passing to warnings to fires"
  size="full"
/>

<Alert type="warning" title="Don't run twenty pipelines because you can">
Simon Willison flagged the dark side of all this in [AI Doesn't Reduce Work — It Intensifies It](https://simonwillison.net/2026/Feb/9/ai-intensifies-work): the low cost of "just one more prompt" turns into compulsive task-stacking and burnout. The point of AFK coding is to be _away from the keyboard_, not to triple-book your attention. Run as many pipelines as your review capacity can absorb. Not more.
</Alert>

## Conclusion

- Small tickets fit a single chat. 5-point tickets need a pipeline.
- The pipeline is HITL up front, AFK through spec → slice → Ralph loop with TDD → refactor → agentic QA, HITL at review.
- Vertical slices keep each Ralph loop in the model's smart zone and survive partial failure.
- Refactor needs its own dedicated pass. The agent won't do it inside the implementation loop.
- Agent-browser closes the gap between "tests pass" and "the user can finish the wizard."
- Run several pipelines in parallel. You're managing now, not typing.

## Further reading

The notes I leaned on for this post, grouped by what they support:

- **Why a pipeline beats a prompt:** [12 Factor Agents](https://www.humanlayer.dev/blog/12-factor-agents) · [The Context Window Problem](https://factory.ai/news/context-window-problem) · [Advanced Context Engineering for Coding Agents](https://github.com/humanlayer/advanced-context-engineering-for-coding-agents)
- **Spec phase:** [Spec-Driven Development with AI](https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/) · [A Practical Guide to Writing Technical Specs](https://stackoverflow.blog/2020/04/06/a-practical-guide-to-writing-technical-specs/) · <InternalLink slug="spec-driven-development-claude-code-in-action">Spec-Driven Development with Claude Code in Action</InternalLink>
- **Ralph loop:** [Ralph Wiggum as a Software Engineer](https://ghuntley.com/ralph/) · [A Brief History of Ralph](https://www.humanlayer.dev/blog/brief-history-of-ralph) · [Stop Chatting with AI. Start Loops.](https://lukeparker.dev/stop-chatting-with-ai-start-loops-ralph-driven-development)
- **TDD + backpressure:** [Essential AI Coding Feedback Loops for TypeScript Projects](https://www.aihero.dev/essential-ai-coding-feedback-loops-for-type-script-projects) · [Don't Waste Your Back Pressure](https://banay.me/dont-waste-your-backpressure)
- **Refactor pass:** [Vibe Engineering Effect Apps (Michael Arnaldi)](https://www.youtube.com/watch?v=Wmp2Tku2PrI)
- **QA:** [agent-browser](https://github.com/vercel-labs/agent-browser) · [Claude Code is Amazing... Until It DELETES Production](https://www.youtube.com/watch?v=VqDs46A8pqE)
- **The job changes:** [Boris Cherny on building at Anthropic](https://www.youtube.com/watch?v=AmdLVWMdjOk) · [AI codes better than me. Now what?](https://www.youtube.com/watch?v=UrNLVip0hSA) · [2026: The Year The IDE Died](https://www.youtube.com/watch?v=7Dtu2bilcFs) · [I Open-Sourced My Own AFK Software Factory](https://www.youtube.com/watch?v=E5-QK3CDVQM) · <InternalLink slug="the-software-factory">The Software Factory</InternalLink>
- **The caveat:** [AI Doesn't Reduce Work — It Intensifies It](https://simonwillison.net/2026/Feb/9/ai-intensifies-work)

---

--- title: How to Write UI Components That Stay Flexible description: Most components break under their second or third variant — props pile up, shells get copy-pasted. Here's how compound components (the pattern behind Reka UI and shadcn-vue) keep a Dialog flexible without flag soup. tags: ['vue', 'design-patterns', 'architecture'] url: https://alexop.dev/posts/compound-components-in-vue-shadcn ---

# How to Write UI Components That Stay Flexible



## Table of Contents

## TLDR

A Dialog is a great test case for compound components because every product needs three or four versions of one: confirm, edit, share, settings. The naive paths both fail: copy a monolithic dialog into every variant and the shells drift; collapse them into one god component and the props turn into `mode`, `showHeader`, `showCancel`, `confirmVariant`, `headerCentered`. The compound pattern Reka UI uses (and shadcn-vue ships) puts state into a `provide` / `inject` context and exposes small primitives (`<Dialog>`, `<DialogTrigger>`, `<DialogContent>`, `<DialogHeader>`, `<DialogFooter>`, `<DialogClose>`) that the consumer arranges into the variant they need. The tree expresses the variant; nothing inside the component branches on flags.

This post grew out of Fernando Rojo's talk [Composition Is All You Need](https://www.youtube.com/watch?v=4KvbVq3Eg5w&t=1194s). Watch it first if you have 30 minutes. This post is the Vue translation, with Dialog as the running example.

The whole pattern fits in one snippet: the tree shape is the variant (**STRUCTURE**), `class="..."` overrides defaults (**STYLE**), `data-state="..."` exposes lifecycle as a stylable contract (**STATE**), and `as-child` lets the consumer swap the rendered tag (**ELEMENT**). The rest of the post is each lever, in detail.

## See It Before You Read About It

Pick a preset. Toggle the children. The dialog on the left and the matching template on the right move together: same primitives, different trees, different variants.

That is the pattern. One root, a few small children. The consumer arranges them, and the arrangement is the variant.

## Smell #1: Duplicated Monoliths

Imagine you write a Dialog the first way most of us do: as one self-contained component. It opens, it closes, it has a header and a footer, you ship it. A week later product asks for an "edit profile" dialog. You copy the file, change the body to a form, ship it. A month later: a "share" dialog with a wider layout. Copy. A confirm-delete with a destructive action. Copy.

[`MonolithicConfirmDeleteDialog.vue`](https://github.com/alexanderop/compose) shows one of those copies in practice:

```vue
<!-- ANTIPATTERN: shell rebuilt from scratch in every variant. -->
<script setup lang="ts">
const open = ref(false)
const titleId = useId() ?? 'monolithic-confirm-title'
const descriptionId = useId() ?? 'monolithic-confirm-description'

function setOpen(value: boolean) { open.value = value }
function confirmDelete() { setOpen(false) }

function onKeyDown(e: KeyboardEvent) {
  if (open.value && e.key === 'Escape') {
    e.preventDefault()
    setOpen(false)
  }
}

watch(open, (now, prev) => {
  if (now && !prev) {
    document.body.style.overflow = 'hidden'
    window.addEventListener('keydown', onKeyDown)
  } else if (!now && prev) {
    document.body.style.overflow = ''
    window.removeEventListener('keydown', onKeyDown)
  }
})

onUnmounted(() => {
  document.body.style.overflow = ''
  window.removeEventListener('keydown', onKeyDown)
})
</script>

<template>
  <button @click="setOpen(true)">Delete account</button>

  <Teleport to="body">
    <div v-if="open" class="fixed inset-0 z-40">
      
      <div
        :aria-describedby="descriptionId"
        :aria-labelledby="titleId"
        aria-modal="true"
        class="fixed top-1/2 left-1/2 ..."
        role="dialog"
        tabindex="-1"
      >
        <div class="flex flex-col gap-2 text-center sm:text-left">
          <h2 :id="titleId">Are you absolutely sure?</h2>
          <p :id="descriptionId">This will permanently delete your account.</p>
        </div>

        <!-- FOOTER: keep in sync with MonolithicProfileEditDialog.vue -->
        <div class="mt-6 flex flex-col-reverse gap-2 sm:flex-row sm:justify-end">
          <button @click="setOpen(false)">Cancel</button>
          <button @click="confirmDelete">Delete account</button>
        </div>
      </div>
    </div>
  </Teleport>
</template>
```

Read that comment: `FOOTER: keep in sync with MonolithicProfileEditDialog.vue`. That is the smell. Every variant rebuilds the same shell (the overlay, the escape handler, the scroll lock, the title/description ARIA wiring, the footer markup), and the only thing keeping them aligned is grep and discipline.

You pay the cost every time something has to change:

- Designer wants `gap-2` to become `gap-6` in every dialog footer? Edit N files.
- Accessibility audit asks for a focus trap? Add it to N files.
- Scroll lock turns out to need a body class instead of inline style? Touch N files.
- New variant (share dialog) appears? Copy the shell again, drift inevitable.

Each copy is a fork. Each fork ages on its own. Six months in, you can't be sure the dialogs behave the same way, because they don't.

## Smell #2: One God Component With v-ifs

The obvious next move is to collapse the duplicates into one component. You make the body a slot, expose `title` and `description` as props, add `showCancel` and `showConfirm` for the footer. It feels clean for one afternoon. Then product asks for a destructive variant; you add `confirmVariant`. Then a share dialog needs no description; you add `showDescription`. Then someone wants a centered header; `headerCentered`. You add a flag for every variant you cram into the component.

[`BooleanPropDialog.vue`](https://github.com/alexanderop/compose) shows the version that grew out of covering two real call sites (confirm-delete and edit-profile) with one component:

```vue
<!-- ANTIPATTERN: boolean prop sprawl. -->
<script setup lang="ts">
type Mode = 'confirm' | 'edit'
type Variant = 'primary' | 'destructive'

const props = withDefaults(
  defineProps<{
    mode?: Mode
    title: string
    description?: string
    showHeader?: boolean
    showDescription?: boolean
    showFooter?: boolean
    showCancel?: boolean
    showConfirm?: boolean
    showSecondary?: boolean
    showCloseIcon?: boolean
    cancelLabel?: string
    confirmLabel?: string
    secondaryLabel?: string
    confirmVariant?: Variant
    triggerLabel: string
    triggerVariant?: Variant
    headerCentered?: boolean
    disableConfirm?: boolean
    editName?: string
    editBio?: string
  }>(),
  { /* …a wall of defaults… */ }
)
</script>

<template>
  <button v-if="props.triggerVariant === 'destructive'" ...>{{ props.triggerLabel }}</button>
  <button v-else ...>{{ props.triggerLabel }}</button>

  <Teleport to="body">
    <div v-if="open" ...>
      
      <div role="dialog" ...>
        <button v-if="props.showCloseIcon" ...>×</button>

        <div v-if="props.showHeader" :class="[
          'flex flex-col gap-2',
          props.headerCentered ? 'text-center' : 'text-left',
        ]">
          <h2>{{ props.title }}</h2>
          <p v-if="props.description && props.showDescription">{{ props.description }}</p>
        </div>

        <div v-if="props.mode === 'edit'" class="mt-4 flex flex-col gap-3">
          <!-- inline form, two-way bound through update:editName / update:editBio -->
        </div>

        <div v-if="props.showFooter" class="mt-6 ...">
          <button v-if="props.showSecondary && props.secondaryLabel" ...>{{ props.secondaryLabel }}</button>
          <button v-if="props.showCancel" ...>{{ props.cancelLabel }}</button>
          <button v-if="props.showConfirm && props.confirmVariant === 'destructive'" ...>{{ props.confirmLabel }}</button>
          <button v-else-if="props.showConfirm" ...>{{ props.confirmLabel }}</button>
        </div>
      </div>
    </div>
  </Teleport>
</template>
```

The call site is the giveaway:

```vue
<BooleanPropDialog
  cancel-label="Cancel"
  confirm-label="Delete account"
  confirm-variant="destructive"
  description="This will permanently delete your account..."
  mode="confirm"
  :show-cancel="true"
  :show-confirm="true"
  title="Are you absolutely sure?"
  trigger-label="Delete account"
  trigger-variant="destructive"
  @confirm="confirmDelete"
/>
```

Twelve flags to describe one variant. The edit version needs `mode="edit"`, then plumbs the form's two-way binding through `update:editName` and `update:editBio` because the inputs live inside the dialog the consumer can't reach into.

Fernando Rojo named this smell in his talk:

> "If you have a boolean prop that determines which component tree is getting rendered from the parent, you can kind of imagine me looking over your shoulder and shaking my head."
>
> — Fernando Rojo, *Composition Is All You Need*

The diagnostic: when a flag changes *what* renders rather than *how*, lift it into a child component. `confirmVariant="destructive"` is a "how" prop and is fine. `mode="edit"` is a "what" prop. It switches the component tree, so lift it into the tree the consumer controls.

## The Solution: Compose Trees, Don't Configure Them

The compound component pattern flips the relationship. You ship N small components that share state through a provider. The consumer assembles only the parts they need:

```html
<Dialog>
  <DialogTrigger>Delete account</DialogTrigger>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Are you absolutely sure?</DialogTitle>
      <DialogDescription>This cannot be undone.</DialogDescription>
    </DialogHeader>
    <DialogFooter>
      <DialogClose>Cancel</DialogClose>
      <button class="bg-red-600 ..." @click="confirmDelete">Delete</button>
    </DialogFooter>
  </DialogContent>
</Dialog>
```

A share dialog with no description? Drop `<DialogDescription>`. An edit dialog with a form? Put the form inside `<DialogContent>`. The inputs are in the consumer's template, so they bind to the consumer's state with `v-model`. A settings menu where the trigger is a list-row? Pass `as-child` to `<DialogTrigger>`. No flags inside the component, no `update:editName` plumbing across the boundary.

> "Where are the booleans and the special props telling us what to render? They're nowhere to be found. We don't have a monolith — we have shared internals that get reimplemented for each use case."
>
> — Fernando Rojo

This is how Reka UI is built and how shadcn-vue ships every primitive on top of it.

## Reading shadcn-vue: The Dialog Primitive

Installing the Dialog from shadcn-vue gives you a barrel of small files, not one `<Dialog>` component:

```ts
// ui/dialog/index.ts
export { default as Dialog } from "./Dialog.vue";
export { default as DialogClose } from "./DialogClose.vue";
export { default as DialogContent } from "./DialogContent.vue";
export { default as DialogDescription } from "./DialogDescription.vue";
export { default as DialogFooter } from "./DialogFooter.vue";
export { default as DialogHeader } from "./DialogHeader.vue";
export { default as DialogOverlay } from "./DialogOverlay.vue";
export { default as DialogTitle } from "./DialogTitle.vue";
export { default as DialogTrigger } from "./DialogTrigger.vue";
```

Nine components, each doing one thing. The root that owns the state, `Dialog.vue`, looks like this:

```vue
<script setup lang="ts">
const props = defineProps<DialogRootProps>();
const emits = defineEmits<DialogRootEmits>();

const forwarded = useForwardPropsEmits(props, emits);
</script>

<template>
  <DialogRoot data-slot="dialog" v-bind="forwarded">
    
  </DialogRoot>
</template>
```

The root renders no markup of its own. It forwards into Reka UI's `DialogRoot`, which establishes the context. The open/closed state lives there and children read it via `inject`.

`DialogHeader` is a styled wrapper with no logic:

```vue
<script setup lang="ts">
const props = defineProps<{ class?: HTMLAttributes["class"] }>();
</script>

<template>
  <div
    data-slot="dialog-header"
    :class="cn('flex flex-col gap-2 text-center sm:text-left', props.class)"
  >
    
  </div>
</template>
```

The trigger is a few lines too. It forwards to Reka's `DialogTrigger`, which calls `setOpen(true)` and wires up the ARIA attributes. No DOM owned by shadcn-vue, only styling and the `data-slot` for theming.

Compare the call site (the compound version we saw above) to the boolean-prop monolith: same UX, twelve flags fewer, and when a designer asks for a checkbox in the footer or a dialog with no description, you rearrange the tree to fit.

## A Quick Detour: How `provide` and `inject` Work

Compound components rely on Vue's [`provide` and `inject`](https://vuejs.org/guide/components/provide-inject.html) API. The model matches React Context: a parent publishes a value under a key, and any descendant in its subtree reads that value without the components in between knowing about it.

The minimum example is two components. Click the button — the child mutates the shared ref, the parent re-renders. The same `open` lives in both:

```vue live id=provide-inject-demo file=Parent.vue entry
<script setup>
const open = ref(false);
provide("dialog-open", open);
</script>

<template>
  <p>Parent sees: open = <strong>{{ open }}</strong></p>
  
</template>
```

```vue live id=provide-inject-demo file=Child.vue
<script setup>
const open = inject("dialog-open");
</script>

<template>
  <button @click="open = !open">
    Toggle from child (now {{ open }})
  </button>
</template>
```

The Vue docs frame this as the answer to *prop drilling*: passing the same prop through three intermediate components that do not care about it, only to reach the one that does. With `provide` / `inject`, the descendant reads from the closest matching provider in the tree, however many components deep it is.

Toggle the root state below. On the left, every component on the path carries `open` as a prop. On the right, only the provider and the consumers know about it. `<Header>`, `<Body>`, and `<Footer>` are unchanged.

Three properties of the API matter for `<Dialog>`:

- **Reactivity passes through.** Provide a `ref` and the descendant gets the same `ref`. This is what lets `<DialogClose>` flip `open` to `false` and `<DialogContent>` react with a transition.
- **String keys are untyped.** `inject("dialog-open")` returns `unknown`. Vue ships [`InjectionKey<T>`](https://vuejs.org/guide/typescript/composition-api.html#typing-provide-inject), a typed `Symbol`, so the injected type matches the provided type at the call site.
- **Missing providers fail without warning.** `inject("missing")` returns `undefined` and the component renders broken with no compile-time error. Robust compound APIs wrap `inject` in a function that throws when the provider is absent.

Vue also lets you pass [`readonly()`](https://vuejs.org/api/reactivity-core.html#readonly) around a provided ref so descendants can read but not mutate. Dialog skips this because `<DialogClose>` *should* mutate, but `readonly` fits when only the provider holds the write path.

## Building Your Own: A Dialog Component

Let's build the compound Dialog from scratch. This is the part you will reuse on your own components.

### Step 1: The provider owns state

Start with a composable that defines the shared interface. This is your contract:

```ts
// composables/useDialog.ts
export interface DialogContext {
  open: Ref<boolean>;
  setOpen: (value: boolean) => void;
  triggerRef: Ref<HTMLElement | null>;
  contentId: string;
  titleId: string;
  descriptionId: string;
}

const DialogKey: InjectionKey<DialogContext> = Symbol("dialog");

export function provideDialog(ctx: DialogContext) {
  provide(DialogKey, ctx);
}

export function useDialog(): DialogContext {
  const ctx = inject(DialogKey);
  if (!ctx) throw new Error("useDialog must be used inside <Dialog>");
  return ctx;
}
```

The `InjectionKey` is typed, so children get full type safety on the context. `useDialog` throws when used outside the provider, which prevents silent bugs in consumer code.

#### If you use VueUse, there is a helper for this

The compound pattern is two halves: the root *provides*, the leaves *inject*. VueUse's [`createInjectionState`](https://vueuse.org/shared/createInjectionState/) is shaped exactly around that — it takes a setup function and returns a `[useProvide, useInject]` tuple. The same `useDialog.ts` becomes:

```ts
// composables/useDialog.ts
const [useProvideDialog, useDialogRaw] = createInjectionState(() => {
  const open = ref(false);
  const triggerRef = ref<HTMLElement | null>(null);
  const contentId = useId() ?? "dialog-content";
  const titleId = useId() ?? "dialog-title";
  const descriptionId = useId() ?? "dialog-description";

  function setOpen(value: boolean) {
    open.value = value;
  }

  return { open, setOpen, triggerRef, contentId, titleId, descriptionId };
});

export { useProvideDialog };

export function useDialog() {
  const ctx = useDialogRaw();
  if (!ctx) throw new Error("useDialog must be used inside <Dialog>");
  return ctx;
}
```

The state and the ARIA ids now live inside the setup function, so the root's `<script setup>` collapses to a single `useProvideDialog()` call — no manually defined `InjectionKey`, no separate `provideDialog(ctx)` wiring. The leaves still get a typed `useDialog()` that throws when used outside the provider. (`createInjectionState` also accepts a `defaultValue` option that returns a fallback instead of `undefined`; for compound components you usually want the throw, since a missing provider is a real bug, not a graceful-degradation case.)

Two payoffs beyond saved boilerplate:

- **You can unit-test the state machine without mounting a component.** With the manual version the state sits in `<script setup>` of `Dialog.vue`, so to assert "`setOpen(false)` flips `open`" you have to mount the SFC. The setup function passed to `createInjectionState` is a plain function. Call it in a test, assert on the returned refs.
- **The root SFC becomes near-empty and swappable.** It is ``. You can wrap the root in a Teleport, or ship a second root variant that provides the same state, since the root holds nothing to copy.

The rest of this section uses the manual version because it shows the raw `provide` / `inject` shape with no library in the way. Reach for `createInjectionState` once you have a few compound components in the codebase, or once you want to test the state machine in isolation.

### Step 2: The root injects, doesn't render

The `Dialog.vue` root creates the state, generates ARIA ids, and provides the bundle. It renders no markup of its own. It is a logical container:

```vue
<!-- Dialog.vue -->
<script setup lang="ts">
const open = defineModel<boolean>("open", { default: false });
const triggerRef = ref<HTMLElement | null>(null);

const contentId = useId() ?? "dialog-content";
const titleId = useId() ?? "dialog-title";
const descriptionId = useId() ?? "dialog-description";

function setOpen(value: boolean) {
  open.value = value;
}

provideDialog({ open, setOpen, triggerRef, contentId, titleId, descriptionId });
</script>

<template>
  
</template>
```

`defineModel` exposes `v-model:open` so the consumer can read or control the open state from outside. `useId` gives stable IDs for the title/description so `<DialogTitle>` and `<DialogDescription>` can publish them and `<DialogContent>` can reference them via `aria-labelledby` / `aria-describedby`.

### Step 3: Each child is small and focused

Children only know about the slice of context they need.

```vue
<!-- DialogTrigger.vue -->
<script setup lang="ts">
const { open, setOpen, triggerRef, contentId } = useDialog();

function handleClick(e: MouseEvent) {
  triggerRef.value = e.currentTarget as HTMLElement;
  setOpen(true);
}
</script>

<template>
  <button
    type="button"
    :aria-controls="contentId"
    :aria-expanded="open"
    :data-state="open ? 'open' : 'closed'"
    @click="handleClick"
  >
    
  </button>
</template>
```

```vue
<!-- DialogClose.vue -->
<script setup lang="ts">
const { setOpen } = useDialog();
</script>

<template>
  <button type="button" @click="setOpen(false)">
    <slot>Cancel</slot>
  </button>
</template>
```

```vue
<!-- DialogTitle.vue — publishes the id to satisfy aria-labelledby -->
<script setup lang="ts">
const { titleId } = useDialog();
</script>

<template>
  </h2>
</template>
```

`<DialogContent>` is the heaviest leaf because it owns the open/close transition, focus management, scroll lock, and the escape handler. But all of those used to be duplicated across every monolithic dialog. Lifting them into one place is the entire point. When accessibility audits ask for a focus trap, you change one file:

```vue
<!-- DialogContent.vue (focus + escape, abridged) -->
<script setup lang="ts">
const { open, setOpen, triggerRef, contentId, titleId, descriptionId } = useDialog();
const contentRef = ref<HTMLElement | null>(null);

function onKeyDown(e: KeyboardEvent) {
  if (open.value && e.key === "Escape") {
    e.preventDefault();
    setOpen(false);
  }
}

watch(open, async (now, prev) => {
  if (now && !prev) {
    document.body.style.overflow = "hidden";
    window.addEventListener("keydown", onKeyDown);
    await nextTick();
    contentRef.value?.querySelector<HTMLElement>("button, input, [tabindex]")?.focus();
  } else if (!now && prev) {
    document.body.style.overflow = "";
    window.removeEventListener("keydown", onKeyDown);
    triggerRef.value?.focus();
  }
});

onUnmounted(() => {
  document.body.style.overflow = "";
  window.removeEventListener("keydown", onKeyDown);
});
</script>

<template>
  <Teleport to="body">
    <Transition>
      <div v-if="open" class="fixed inset-0 z-40">
        
        <div
          :id="contentId"
          ref="contentRef"
          :aria-describedby="descriptionId"
          :aria-labelledby="titleId"
          aria-modal="true"
          role="dialog"
          tabindex="-1"
        >
          
        </div>
      </div>
    </Transition>
  </Teleport>
</template>
```

The work that lived inside every monolithic dialog now lives in one component. Consumers compose instead of copy.

### Step 4: Compose distinct variants

Now the same primitives produce every variant. Confirm delete:

```html
<Dialog>
  <DialogTrigger class="bg-red-600 ...">Delete account</DialogTrigger>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Are you absolutely sure?</DialogTitle>
      <DialogDescription>This cannot be undone.</DialogDescription>
    </DialogHeader>
    <DialogFooter>
      <DialogClose>Cancel</DialogClose>
      <button class="bg-red-600 ..." @click="confirmDelete">Delete account</button>
    </DialogFooter>
  </DialogContent>
</Dialog>
```

Edit profile, with the form sitting in the consumer's template so `v-model` binds to the consumer's state without crossing the dialog boundary:

```html
<Dialog>
  <DialogTrigger>Edit profile</DialogTrigger>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Edit profile</DialogTitle>
      <DialogDescription>Make changes here. Click save when you're done.</DialogDescription>
    </DialogHeader>
    <form @submit.prevent="save">

      <DialogFooter>
        <DialogClose>Cancel</DialogClose>
        <button type="submit">Save changes</button>
      </DialogFooter>
    </form>
  </DialogContent>
</Dialog>
```

Notice what's gone: no `update:editName` plumbing, no `mode="edit"` flag, no shell rebuilt. The form is the consumer's template; the dialog scaffolding is the primitive.

Share dialog, wider content, icon close instead of a button. Same primitives, different tree:

```html
<Dialog>
  <DialogTrigger>Share project</DialogTrigger>
  <DialogContent class="max-w-2xl">
    <DialogHeader>
      <DialogTitle>Share "Project Phoenix"</DialogTitle>
    </DialogHeader>
    <DialogClose as-child>
      <button class="absolute top-4 right-4" aria-label="Close">✕</button>
    </DialogClose>

    <DialogFooter>
      <DialogClose class="bg-zinc-900 text-white">Done</DialogClose>
    </DialogFooter>
  </DialogContent>
</Dialog>
```

### The whole thing, running

Five small files. Click through the tabs to see the implementation, then click the trigger. The provider lives in `Dialog.vue`; trigger and close call `setOpen` on the same context; content reads `open` to render.

```vue live id=compound-dialog file=App.vue
<script setup>
function confirmDelete() {
  alert("Account deleted!");
}
</script>

<template>
  <Dialog>
    <DialogTrigger>Delete account</DialogTrigger>
    <DialogContent>
      <h2>Are you absolutely sure?</h2>
      <p>This will permanently delete your account.</p>
      <div class="footer">
        <DialogClose>Cancel</DialogClose>
        <button class="danger" @click="confirmDelete">
          Delete account
        </button>
      </div>
    </DialogContent>
  </Dialog>
</template>

<style scoped>
.footer {
  display: flex;
  gap: 0.5rem;
  justify-content: flex-end;
  margin-top: 1.25rem;
}
.danger {
  background: #dc2626;
  color: white;
  border-color: #dc2626;
}
h2 {
  margin: 0 0 0.5rem;
  font-size: 1.05rem;
  font-weight: 600;
}
p {
  margin: 0;
  opacity: 0.8;
  font-size: 0.9rem;
}
</style>
```

```vue live id=compound-dialog file=Dialog.vue
<script setup>
const open = ref(false);

provide("dialog", {
  open,
  setOpen: (value) => {
    open.value = value;
  },
});
</script>

<template>
  
</template>
```

```vue live id=compound-dialog file=DialogTrigger.vue
<script setup>
const { open, setOpen } = inject("dialog");
</script>

<template>
  <button
    type="button"
    :aria-expanded="open"
    :data-state="open ? 'open' : 'closed'"
    @click="setOpen(true)"
  >
    
  </button>
</template>
```

```vue live id=compound-dialog file=DialogContent.vue
<script setup>
const { open, setOpen } = inject("dialog");

function onKeyDown(e) {
  if (e.key === "Escape") setOpen(false);
}

watch(open, (now) => {
  if (now) window.addEventListener("keydown", onKeyDown);
  else window.removeEventListener("keydown", onKeyDown);
});
</script>

<template>
  <Teleport to="body">
    <div v-if="open" class="overlay" @click.self="setOpen(false)">
      <div class="content" role="dialog" aria-modal="true">
        
      </div>
    </div>
  </Teleport>
</template>

<style scoped>
.overlay {
  position: fixed;
  inset: 0;
  background: rgba(0, 0, 0, 0.6);
  display: flex;
  align-items: center;
  justify-content: center;
  z-index: 100;
}
.content {
  background: rgb(24, 24, 36);
  color: rgb(228, 228, 235);
  border: 1px solid rgba(255, 255, 255, 0.08);
  padding: 1.5rem;
  border-radius: 0.5rem;
  max-width: 22rem;
  width: 90%;
  box-shadow: 0 20px 50px rgba(0, 0, 0, 0.4);
}
</style>
```

```vue live id=compound-dialog file=DialogClose.vue
<script setup>
const { setOpen } = inject("dialog");
</script>

<template>
  <button type="button" @click="setOpen(false)">
    <slot>Cancel</slot>
  </button>
</template>
```

No flag inside any file decides what gets rendered. The variant is the tree in `App.vue`. Swap `<DialogContent>`'s children for a form and you have edit-profile; swap them for a share sheet and you have share. Same primitives, same provider, different tree.

## State Lives in the Provider, Not the Layout

> "If there's one thing to take away from this talk, it would be this. I've solved so many problems in my React code bases by simply lifting state higher up in the tree."
>
> — Fernando Rojo

The share example tucked an icon `<DialogClose>` outside the footer, absolutely positioned in the top-right corner. It still closed the same dialog because the open state lives in the provider, not in any specific child. Slots alone cannot reach across siblings like that; a provider can.

Open the dialog below, then move the cancel button between the footer and a toolbar that sits next to the dialog. Both consumers call `setOpen(false)` on the same provider. The visual layout and the state graph are decoupled.

In a slot-based design without a provider you would have to do one of these by hand:

- Hoist the open state up to the parent: boilerplate, repeated per variant
- Pass an `onClose` callback through every layer: prop drilling
- Use a scoped slot to pass state to a child: solves the *direct child* case, then collapses the moment a sibling outside the visual frame needs the same state
- Reach into the dialog with a template ref: escape hatch, untyped, brittle

With `provide` / `inject`, none of that exists. A child calls `useDialog()` and the closest provider answers, no matter how deep in the tree or how far apart the children sit in the layout. "Lift state to the provider" means lifting it out of the layout. The same state can then be read from any DOM position the consumer wants.

## Styling Without Locking Consumers In: `cn()`

That covers structure. The consumer composes the tree, the provider keeps state in sync no matter how the children are laid out. Styling is the second axis. The primitive ships sensible defaults: `flex flex-col gap-2` on a header, `max-w-md` on the content. Every real call site eventually wants to bend one of them: a wider share dialog, a tighter footer, a destructive button that breaks the default palette. The consumer needs a way in without forking the file.

`cn(...)` is how shadcn-vue solves that. It is a small utility every shadcn project writes itself, by convention living in `src/lib/utils.ts` (not an npm package).

The implementation is four lines:

```ts
// lib/utils.ts
export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}
```

`clsx` joins truthy class values into a string. `tailwind-merge` deduplicates conflicting Tailwind utilities so the *last* one wins, so `p-2` followed by `p-4` collapses to `p-4`. Together, whatever the consumer passes overrides whatever the primitive sets, with no specificity wars.

In every shadcn-vue primitive it shows up as the same one-liner. From `DialogHeader`:

```vue
<div :class="cn('flex flex-col gap-2 text-center sm:text-left', props.class)">
  
</div>
```

The primitive holds the default styling, `props.class` carries the override, and the merge runs defaults first so the override wins on conflicts.

### Watch the merge happen

Toggle classes on either side. The left panel shows what naive concatenation produces: conflicting utilities sit side-by-side, flagged with ⚠. The right panel runs the same input through the real `cn()` (using `clsx` + `tailwind-merge` from npm) and shows which classes survive and which get dropped.

Conflict chips on the left are the ones whose winner depends on stylesheet order; fragile. Strikethrough chips on the right are the ones `tailwind-merge` dropped. Hover any dropped chip to see who beat it. Non-conflicting classes (like `text-white` when no other text-color is set) flow through untouched on both sides, since `cn()` deduplicates only when there is a real conflict.

So the share dialog's `<DialogContent class="max-w-2xl">` works: the primitive's `max-w-md` default loses to the consumer's `max-w-2xl`, no specificity war, no fork.

## State as Contract: The `data-*` Pattern

`cn()` covers static overrides. But every dialog also has *state*: open, closed, animating in, animating out, disabled. The consumer wants to style against those too. A fade on open, a slide on close, a muted border when disabled. The primitive cannot ship every animation, and it shouldn't have to.

Headless libraries solve this by writing state to the DOM as data attributes, then letting the consumer style against them. You already saw both halves of the pattern in the snippets above.

### `data-state`: the current state of the component

The library sets it automatically. Look at the trigger we built earlier:

```vue
:data-state="open ? 'open' : 'closed'"
```

The consumer styles against the attribute:

```html
<DialogContent
  class="data-[state=open]:animate-in data-[state=closed]:fade-out"
/>
```

Tailwind v4 ships `data-[...]` as a first-class variant, so no plugin is needed. The same vocabulary shows up across the ecosystem: `data-state="open" | "closed"` on overlays, `"on" | "off"` on toggles, `"checked" | "unchecked" | "indeterminate"` on checkboxes, `"active" | "inactive"` on tabs. Reka UI and Radix share the contract, so a class targeting `data-[state=open]:` works against either.

### `data-slot`: stable identity for each part

shadcn-vue v4 stamps a `data-slot` on every primitive. The dialog root carries `data-slot="dialog"`, the header `data-slot="dialog-header"`, and so on. You saw it in the shadcn source above:

```vue
<DialogRoot data-slot="dialog" v-bind="forwarded">
```

```vue
<div data-slot="dialog-header" :class="cn(...)">
```

Why a separate attribute when `class` exists? Because `class` belongs to the consumer (`cn()` already settled that), and Tailwind utility names are not semantic. `data-slot` is. A parent layout can target a dialog part without knowing or caring which utilities live inside it today:

```html
<form class="[&_[data-slot=dialog-footer]]:gap-3">
  <!-- Any dialog mounted inside picks up gap-3 on its footer, no matter how deep. -->
</form>
```

### Other attributes you'll see

- `data-side`: `top` / `right` / `bottom` / `left` on positioned elements (tooltip, popover, menu)
- `data-align`: `start` / `center` / `end` for the same
- `data-orientation`: `horizontal` / `vertical` on tabs, separators, sliders
- `data-disabled`: present when the part is disabled
- `data-highlighted`: present when keyboard focus is on a menu item
- `data-placeholder`: present while a select is showing its placeholder

### Why attributes, not classes

1. **The consumer owns `class`.** If the library wrote state classes like `is-open`, it would have to merge with the consumer's input or fight specificity. Attributes sidestep both.
2. **Stable surface.** Refactor the primitive's utility classes tomorrow; `data-state="open"` survives because it is the public contract.
3. **Inspectable.** Open DevTools, see the state in the DOM. No closure spelunking.
4. **Composable with Tailwind variants.** `data-[state=open]:`, `group-data-[state=open]:`, and `has-[[data-slot=dialog-footer]]:` are first-class variants in v4.

## Element Handoff: `as-child`

One more escape hatch shows up in shadcn-vue source: `as-child` (inherited from Reka UI, which inherits it from Radix). Pass it to a primitive and the primitive **clones the consumer's child** and forwards its behavior into that element rather than rendering its own DOM.

```vue
<!-- Default: DialogTrigger renders its own <button> -->
<DialogTrigger>Open</DialogTrigger>

<!-- as-child: DialogTrigger borrows your <RouterLink>'s DOM,
     keeps the open-on-click behavior, but the rendered tag is <a> -->
<DialogTrigger as-child>
  <RouterLink to="/profile">Open profile</RouterLink>
</DialogTrigger>
```

The contract: the consumer's element receives all the props and event handlers the primitive would have applied to its own DOM. The primitive owns behavior; the consumer owns presentation. *(Reka UI implements this via its `<Primitive>` component and slot forwarding, so you do not need to write the cloning machinery yourself.)*

This is the fourth axis of consumer override the pattern gives you. Compound children let the consumer compose **structure**, `cn()` lets them override **style**, `data-*` exposes **state and identity** as a stylable contract, and `as-child` lets them swap the **rendered element**. All four are decided at the call site.

## The Convenience Layer

Once a compound API exists, someone will ask for a flat `` shortcut. Don't add it as flags on `<Dialog>`. Build it *on top* of the primitives:

```vue
<!-- ConfirmDialog.vue: a higher-level wrapper, NOT a flag added to Dialog -->
<script setup lang="ts">
import {
  Dialog, DialogClose, DialogContent, DialogDescription,
  DialogFooter, DialogHeader, DialogTitle, DialogTrigger,
} from "@/components/dialog";

withDefaults(
  defineProps<{
    title: string;
    description?: string;
    confirmLabel?: string;
    cancelLabel?: string;
    destructive?: boolean;
  }>(),
  { confirmLabel: "Confirm", cancelLabel: "Cancel", destructive: false },
);

const emit = defineEmits<{ confirm: [] }>();
const open = defineModel<boolean>("open", { default: false });

function handleConfirm() {
  emit("confirm");
  open.value = false;
}
</script>

<template>
  <Dialog v-model:open="open">
    <DialogTrigger v-if="$slots.trigger" as-child>
      
    </DialogTrigger>
    <DialogContent>
      <DialogHeader>
        <DialogTitle>{{ title }}</DialogTitle>
        <DialogDescription v-if="description">{{ description }}</DialogDescription>
      </DialogHeader>
      <DialogFooter>
        <DialogClose>{{ cancelLabel }}</DialogClose>
        <button :class="destructive ? 'bg-red-600 ...' : 'bg-zinc-900 ...'" @click="handleConfirm">
          {{ confirmLabel }}
        </button>
      </DialogFooter>
    </DialogContent>
  </Dialog>
</template>
```

Now a sign-out confirm is one tag:

```vue
<ConfirmDialog
  title="Sign out of your account?"
  description="You'll need to sign in again next time you visit."
  confirm-label="Sign out"
  cancel-label="Stay signed in"
  @confirm="onSignOut"
>
  <template #trigger>
    <button>Sign out</button>
  </template>
</ConfirmDialog>
```

The convenience layer is a *consumer* of the primitives, not an extension of them. When a designer asks for a non-standard variant (checkbox in the footer, custom layout), the consumer drops back down to the primitives without anyone touching `ConfirmDialog`. This is what stops the compound API from collapsing back into `BooleanPropDialog` over time.

## How to Apply This in Your Codebase

I use this workflow to migrate an existing prop-heavy component:

1. **Find the smell.** List every boolean prop. For each one, ask: does this prop change *what renders* or *how it renders*? "What" props are composition opportunities. "How" props (variant, size, color) are fine; leave them.
2. **Sketch the tree per variant.** Take three real call sites and write down the JSX/template you wish you could write. The compound API drops out of that exercise.
3. **Extract the provider.** Move state and handlers into a composable with a typed `InjectionKey`. The consumer-facing interface is the type signature of that context object.
4. **Split the children.** Each child component reads only the slice it needs from `useX()`. Keep them dumb. No business logic in the leaves.
5. **Delete the old props one variant at a time.** You can ship the new API alongside the old monolith and migrate call sites incrementally.

A few rules that have saved me pain:

- **Fail when context is missing.** `useDialog` throws. Otherwise consumers will render broken UI without warning when they forget the root.
- **Do not build a generic primitive before you have three concrete users.** One use case is a component. Two is a coincidence. Three is a pattern worth abstracting.
- **Resist the "convenience prop" temptation.** Once you have the compound API, someone will ask for a `` shortcut. Add it as a separate higher-level component (`<ConfirmDialog>` built *on top* of the primitives), not as flags on the root.

## When Not to Use It

The compound pattern has real costs. Skip it when:

- The component has one shape and you are inventing variants that do not exist.
- Consumers are LLM-generated code or external API users who benefit from a flat, predictable signature.
- The state is trivial and `provide` / `inject` adds more ceremony than the boolean it replaces.

A `` does not need to be compound. A modal with a form, a footer, and three layouts does.

## Connections

This pattern lives across the ecosystem under different names. The unifying idea, *push the variant decision out of the component and into the call site*, shows up in three traditions worth reading.

**On the React side**, Kent C. Dodds canonized the modern compound-components-with-context approach in [Compound Components with React Hooks](https://kentcdodds.com/blog/compound-components-with-react-hooks). His framing of the pattern as "an implicit contract between parent and children, eliminating verbose prop passing" is the cleanest single statement of why this beats props. [patterns.dev's Compound Pattern](https://www.patterns.dev/react/compound-pattern/) is the canonical reference for the React variant.

**Radix UI** (which Reka UI mirrors for Vue) builds compound on top of two primitives: a context provider and the [`asChild`](https://www.radix-ui.com/primitives/docs/guides/composition) composition prop, which lets consumers swap the rendered element while keeping the behavior. The [Radix philosophy doc](https://github.com/radix-ui/primitives/blob/main/philosophy.md) is the architecture-in-one-page version: *"primitives ship with zero presentational styles"* and *"components are designed with an open API that provides consumers with direct access to the underlying DOM node."* The whole shadcn-vue ecosystem flows from those two lines.

**On the Vue side**, Adam Wathan's [Advanced Vue Component Design](https://adamwathan.me/advanced-vue-component-design/) (2018) was the first widely-shared treatment of compound, slots, and providers as a single toolkit. Michael Thiessen catalogs the per-pattern variants in [12 Design Patterns in Vue](https://michaelnthiessen.com/12-design-patterns-vue), [The 6 Levels of Reusability](https://michaelnthiessen.com/6-levels-of-reusability/), and the small applied exercise [Building a (Totally) Unnecessary If/Else Component](https://michaelnthiessen.com/building-unnecessary-if-else-component). The last one builds an `<If>` pair from scratch using `provide`/`inject`, a tighter playground than Dialog if you want to see the wiring on a smaller surface.

All three traditions share the same shift from configuration to composition: hand the component its pieces instead of describing them with flags.

## References

- [shadcn-vue](https://www.shadcn-vue.com/): the source code referenced in this post
- [Reka UI](https://reka-ui.com/): the headless primitives shadcn-vue is built on
- [Radix Primitives](https://www.radix-ui.com/primitives): the React parent of Reka UI; same patterns, different binding
- [Fernando Rojo, Composition Is All You Need](https://www.youtube.com/watch?v=4KvbVq3Eg5w): the talk that prompted this post
- [Kent C. Dodds, Compound Components with React Hooks](https://kentcdodds.com/blog/compound-components-with-react-hooks): canonical React treatment
- [Vue docs: provide / inject](https://vuejs.org/guide/components/provide-inject.html)
- [VueUse: createInjectionState](https://vueuse.org/shared/createInjectionState/): the factory that collapses the manual provider boilerplate

---

--- title: A Modern Quality Pipeline and Testing Strategy for Frontend Projects description: A short, framework-agnostic concept of what a modern quality pipeline and testing strategy look like for any JavaScript or TypeScript frontend project. tags: ['testing', 'tooling', 'ci', 'performance', 'observability'] url: https://alexop.dev/posts/modern-frontend-quality-pipeline ---

# A Modern Quality Pipeline and Testing Strategy for Frontend Projects



An agent writes most of my frontend code now. I review what it produces and tighten the architecture where it overreaches.

That changes what a quality pipeline is for. You used to write tests and types so the next person on the file stayed sane. Now you write them so the agent can check its own work. Give it more ways to verify a change (types, lint, unit, component, real browser, a11y, bundle budget) and it finishes more of the ticket on its own. A red check tells it what to try next.

Frontend has also grown more complicated since 2024. SSR, streaming, partial prerendering, server components, edge runtimes. Each adds a place where a change can break silently. "TypeScript plus a couple of unit tests" no longer covers it.

A *quality pipeline* is the set of checks that run on every change (locally, on commit, in CI) to give layered confidence the change is correct, accessible, performant, and safe to ship. A *testing strategy* is the part of that pipeline that asserts behaviour: what the app should do, at which level, at what cost.

Plan them as one system. The pipeline decides when checks run; the strategy decides which checks are worth running. Design them together so that:

- Each check has a clear job and runs at the cheapest stage where it can
  catch the problem.
- The feedback loop is short enough that no developer or agent skips
  ahead.
- The same checks run on a contributor's laptop, in an agent's sandbox,
  and on the CI runner.

The same pipeline shape applies whether you build with Next, Nuxt, Astro, SvelteKit, Remix, or a plain Vite app. The framework choice changes which adapter you import, nothing else.

## Background

Frontend tooling consolidated between 2023 and 2026. [Vite](https://vitejs.dev/)
became the default dev/build engine across the major frameworks.
[Vitest](https://vitest.dev/) replaced [Jest](https://jestjs.io/).
[Playwright](https://playwright.dev/) became the default for E2E.
[ESLint](https://eslint.org/) adopted flat config; [Biome](https://biomejs.dev/)
and **[Oxlint](https://oxc.rs/docs/guide/usage/linter)** emerged as much faster
alternatives in Rust. [TypeScript](https://www.typescriptlang.org/) strict mode
became table stakes. [Renovate](https://docs.renovatebot.com/) replaced
[Dependabot](https://github.com/dependabot). In March 2026,
[VoidZero](https://voidzero.dev/) shipped **[Vite+](https://viteplus.dev/)** as
the open-source culmination of that trend: one CLI that wraps Vite,
[Rolldown](https://rolldown.rs/), Vitest, Oxlint,
[Oxfmt](https://github.com/oxc-project/oxc), and [Tsdown](https://tsdown.dev/).

A modern quality pipeline's pieces look the same regardless of framework, so I'll describe the concept first and my stack second.

## My default stack

For new frontend projects in 2026 I reach for **Vite+** instead of wiring
the toolchain by hand. Vite+ ([viteplus.dev](https://viteplus.dev/)) is
the unified toolchain from VoidZero, [Evan You](https://evanyou.me/)'s company.
It bundles Vite, Rolldown, Vitest, Oxlint, Oxfmt, and Tsdown behind a single
CLI (`vp dev`, `vp check`, `vp test`, `vp build`) and one config file. The
alpha shipped open source under MIT.

If you adopt the pieces one at a time, the swaps I would make are:

| Old default | What I use | Why |
| --- | --- | --- |
| ESLint | **Oxlint** | ~50&times; faster, fast enough to run on every keystroke |
| [Prettier](https://prettier.io/) | **Oxfmt** | ~30&times; faster, Prettier-compatible defaults |
| Jest | **Vitest** | ESM-native, browser mode, same matchers |
| [webpack](https://webpack.js.org/) | **Vite + Rolldown** | ~40&times; faster production builds |
| four separate configs | `vp check` / `vp test` / `vp build` | one CLI, one config |

Each piece holds up on its own. I have shipped Vitest and Oxlint in
production for some time; swapping Prettier for Oxfmt and webpack for
Rolldown took a day in the projects I tried. Vite+ removes the
integration cost that kept teams on the older stack.

## The layers

Think of the pipeline as concentric layers, each cheaper and faster than
the one outside it. Run cheap checks first. Save the expensive ones for
the things only they can catch.

### 1. Type safety

Type safety is your first line of defence. Run your framework's type
checker in CI on every PR. Treat any new type error as a build failure.

If you use TypeScript, that means `tsc --noEmit` (or your framework's wrapper around it; most frameworks ship one to handle their template syntax and project references). If you don't use TypeScript yet, adopting it is the highest-leverage change you can make.

Validate untyped boundaries with a schema library ([Zod](https://zod.dev/), [Valibot](https://valibot.dev/), [ArkType](https://arktype.io/)). Parse anywhere data crosses a boundary: route params, API responses, env vars, form input. TypeScript trusts the types you write; schemas check that the data matches them at runtime. With runtime parsing in place you stop reaching for `as`. See <InternalLink slug="the-problem-with-as-in-typescript-why-its-a-shortcut-we-should-avoid">why `as` is a shortcut to avoid</InternalLink>.

### 2. Lint and format

Catches style and a wide class of bugs (unused vars, unsafe `any`, missing
deps in effects) without running the code.

The conventional choice is ESLint flat config plus
[`typescript-eslint`](https://typescript-eslint.io/) and your framework's plugin. The 2026 alternative is **Oxlint** (Rust-based,
~50&times; faster) paired with Oxfmt for formatting, or **Biome** for a
single-binary lint+format combo. The trade-off: Oxlint and Biome have
smaller rule sets than ESLint's mature ecosystem, but they cover most of
the high-value cases and are fast enough to run on every keystroke. For a
working setup that uses Oxlint as a fast first pass and keeps ESLint for
the rules Oxlint doesn't yet cover, see <InternalLink slug="opinionated-eslint-setup-vue-projects">my opinionated ESLint setup for Vue projects</InternalLink>.

Add these two rule families regardless of which linter you pick. They
catch bugs the type system misses:

- **[`eslint-plugin-regexp`](https://ota-meshi.github.io/eslint-plugin-regexp/)** &ndash; ~60 correctness rules for regular
  expressions. Cheap to add, catches real bugs.
- **[`@e18e/eslint-plugin`](https://e18e.dev/)** &ndash; small performance lints (e.g., prefer
  `Set.has` over `Array.includes`) that compound across a codebase.

### 3. Unit tests

For pure functions, hooks, stores, and utilities. Cheap, fast, and where
most logic should live.

- **Tool:** Vitest. Run on every save in watch mode; run all of them in CI.
- Aim for high coverage of pure modules; don't chase coverage on UI glue.

For Vue, see my <InternalLink slug="how-to-test-vue-composables">guide to testing Vue composables with Vitest</InternalLink>.

### 4. Component tests

For components in isolation, with a real DOM and real user interactions. The biggest win in 2026 is **Vitest browser mode**: your component tests run in a real Chromium via Playwright instead of jsdom. Hover states, focus, layout, intersection observers, and scroll behaviour all work as they do in production.

Pair this with [`@testing-library/*`](https://testing-library.com/) for
whichever framework you use; accessibility assertions on each mounted
component live in layer 8 below. For a deeper walkthrough of how this
fits into a full testing pyramid, see <InternalLink slug="vue3_testing_pyramid_vitest_browser_mode">my Vue 3 testing pyramid guide</InternalLink>.

### 5. API mocking

Hard-coded fixtures go stale. Tests that hit a real backend are flaky.
Mock at the network layer once and reuse the same handlers everywhere.

- **Tool:** **[MSW](https://mswjs.io/)** (Mock Service Worker). It intercepts `fetch`,
  XHR, and GraphQL with a service worker in the browser and a
  request interceptor in Node, so the same handler definitions
  work in Vitest, Vitest browser mode, Playwright, and the dev
  server.
- Define handlers once in `src/mocks/handlers.ts`; load them in
  your test setup and (optionally) in the dev server for
  offline-first development.
- Combined with Zod (or Valibot/ArkType) schemas at the same
  boundary, you get mocks that are typed, schema-validated, and
  shared across every layer that hits the network. One source of
  truth instead of three drifting fixture folders.

### 6. Contract testing

The mocks in layer 5 are only as good as the assumptions you bake into them. If the backend renames a field or changes a status code without telling you, every green unit and component test still passes while production breaks. Contract testing closes that gap by tying the mock to a verifiable artefact that the provider checks against.

There are three styles, and they fit different team setups.

**Consumer-driven contracts ([Pact](https://pact.io/)).** The frontend
writes a test that records the requests it makes and the responses it
expects. Pact generates a JSON contract and publishes it to a broker
(the open-source [Pact Broker](https://docs.pact.io/pact_broker), or
hosted [PactFlow](https://pactflow.io/)). The provider runs *its* real
test suite against that contract; if it satisfies every recorded
interaction, both sides can deploy. Pact has libraries for JS/TS, JVM,
.NET, Go, Rust, Python, Ruby, PHP, and Swift, so the same broker spans
a polyglot estate. Best when you control both ends of the wire and want
the consumer to drive the schema.

**Provider-driven / OpenAPI-based.** The provider publishes an
[OpenAPI](https://www.openapis.org/) spec and the contract *is* the
spec. Consumers validate their requests and assertions against it with
[Schemathesis](https://schemathesis.readthedocs.io/) (property-based
fuzzing of every operation), [Dredd](https://dredd.org/) (replays
example requests from the spec against the running provider), or
[Spectral](https://stoplight.io/open-source/spectral) (lints the spec
itself). Best when the provider already maintains an OAS and you don't
want to add Pact on their side.

**Bi-directional contracts ([PactFlow](https://docs.pactflow.io/docs/bi-directional-contract-testing)).**
The consumer publishes a Pact contract; the provider publishes its
OpenAPI spec; PactFlow proves the two are compatible without the
provider having to run consumer-supplied tests. Best when consumers
want consumer-driven semantics but the provider team won't (or can't)
run Pact verification themselves.

What you get for the work:

- **Independent deploys.** A contract gate replaces "is the matching
  E2E green?" with "does the provider satisfy every consumer's
  contract?". Consumer and provider can ship on different cadences
  without coordinating a release train.
- **Faster than E2E.** Verifying a contract is a unit test for the
  boundary; E2E spins up the real services. You catch the same class
  of bug an order of magnitude sooner.
- **Catches drift the linter can't.** A field renamed on the backend
  fails the contract before MSW handlers or Playwright flows would
  notice.

Skip this layer if you own both services and ship them as one unit. E2E covers the same boundary in that case, and the contract overhead doesn't pay off. Add it the moment consumer and provider deploy on different cadences, you don't own the provider, or a single backend serves multiple frontends that all need to keep working.

For a deep dive, [*Contract Testing in Action*](https://www.oreilly.com/library/view/contract-testing-in/9781633437241/)
(Marie Cruz & Lewis Prescott, Manning) walks through Pact, bi-directional
contracts, and how to introduce the practice without stalling delivery.

### 7. End-to-end tests

For critical user journeys across real pages: signup, checkout, the one or two flows that must never break. Keep the suite small. E2E is expensive.

- **Tool:** Playwright.
- Run against a built preview, not the dev server.
- Two assertions worth wiring into a custom fixture, regardless of
  framework, because they catch silent regressions:
  - **Hydration mismatches.** Listen for hydration warnings on `console`
    and fail the test if any appear. SSR/CSR drift is one of the most
    common silent regressions in modern frameworks. I wrote a dedicated
    post on
    <InternalLink slug="catch-hydration-errors-playwright-tests">catching hydration errors in Playwright tests</InternalLink>
    with a reusable fixture.
  - **CSP violations.** Listen for `securitypolicyviolation` events. If
    your CSP is real, this turns every E2E run into a CSP regression
    test.

### 8. Accessibility

Accessibility cuts across lint, component, E2E, and preview. Treat it as a single discipline and check the same WCAG rule set at every cheap-enough stage.

- **Lint.** [`eslint-plugin-jsx-a11y`](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y)
  (React/JSX), [`eslint-plugin-vuejs-accessibility`](https://github.com/vue-a11y/eslint-plugin-vuejs-accessibility)
  (Vue), [`eslint-plugin-astro`](https://ota-meshi.github.io/eslint-plugin-astro/) — catch
  missing `alt`, role mismatches, and other static violations before tests run.
- **Component.** [`axe-core`](https://github.com/dequelabs/axe-core) via
  [`jest-axe`](https://github.com/nickcolley/jest-axe) for jsdom, or
  [`@axe-core/playwright`](https://github.com/dequelabs/axe-core-npm) in Vitest browser mode.
  Assert no violations on every mounted component, and add a meta-test that fails if any
  component test lacks an a11y assertion so the practice doesn't slide.
- **E2E.** [`@axe-core/playwright`](https://github.com/dequelabs/axe-core-npm) on each critical
  journey — same engine as the component layer, but on the real composed page where many
  violations only appear once everything is wired together.
- **Preview.** Lighthouse's accessibility category (run as part of layer 10) or
  [Pa11y CI](https://github.com/pa11y/pa11y-ci) on a list of routes for a dedicated, auditable
  report.
- **Manual.** Storybook's [a11y addon](https://storybook.js.org/addons/@storybook/addon-a11y),
  keyboard-only walkthroughs of new flows, and screen-reader spot-checks. Automated tools catch
  roughly 30% of WCAG issues; the rest needs a human.

This is no longer optional in the EU: the
[European Accessibility Act](https://ec.europa.eu/social/main.jsp?catId=1202) took effect in
mid-2025, so most B2C and many B2B products operating in EU markets are now legally required
to meet WCAG 2.1 AA equivalence. For a framework-specific checklist, see
<InternalLink slug="vue-accessibility-blueprint-8-steps">my Vue accessibility blueprint</InternalLink>.

### 9. Visual regression

Catches unintended UI drift that unit and E2E tests miss.

- [Chromatic](https://www.chromatic.com/) (hosted,
  [Storybook](https://storybook.js.org/)-native) or Playwright screenshots + a
  diff tool like [Lost Pixel](https://lost-pixel.com/) for self-hosted. For a Vitest-native approach, see
  <InternalLink slug="visual-regression-testing-with-vue-and-vitest-browser">how to do visual regression testing in Vue with Vitest</InternalLink>.
- `onlyChanged: true` keeps it cheap: only re-snapshot stories whose
  dependencies changed.
- Gate on PR; review diffs as part of code review.

### 10. Performance and bundle size

Performance regressions are silent unless you measure them.

- **[Lighthouse CI](https://github.com/GoogleChrome/lighthouse-ci)** on a
  preview deployment. Run it against both a *light* and *dark* color scheme;
  contrast regressions show up only in one.
- [`size-limit`](https://github.com/ai/size-limit) or your framework's bundle
  analyzer on PR for bundle deltas. Set explicit budgets and fail the build
  when they're exceeded.

Lab measurements catch regressions before merge. To see what real
users experience, and to find bottlenecks while you're writing the
code, see layer 15 below.

### 11. Dead code and dependency hygiene

Unused code is a tax on every other check.

- **[Knip](https://knip.dev/)** to find unused files, exports, and
  dependencies. Configure per-workspace if you have a monorepo.
- **Renovate** for automated dependency updates with grouping and a sane
  schedule.
- **[OSV-Scanner](https://google.github.io/osv-scanner/)** for vulnerabilities
  and **[Gitleaks](https://github.com/gitleaks/gitleaks)** for secrets, gated
  to high-severity only to avoid alert fatigue.
- Generate an **SBOM** (Software Bill of Materials) on every build with
  [Syft](https://github.com/anchore/syft), [Trivy](https://trivy.dev/), or
  [cdxgen](https://github.com/CycloneDX/cdxgen), in
  [CycloneDX](https://cyclonedx.org/) or [SPDX](https://spdx.dev/) format. This
  is shifting from "nice to have" to "regulated requirement" in 2026
  ([EU CRA](https://digital-strategy.ec.europa.eu/en/policies/cyber-resilience-act),
  US executive orders), and it's the same artefact your security team uses
  to answer customer vulnerability questionnaires.

### 12. Internationalisation drift

If you ship in more than one language, untranslated strings slip through. A mature i18n library plus a drift checker in CI catches them.

- **i18n libraries** &ndash; [i18next](https://www.i18next.com/),
  [vue-i18n](https://vue-i18n.intlify.dev/),
  [FormatJS / react-intl](https://formatjs.github.io/), and
  [Lingui](https://lingui.dev/) all expose a missing-key handler you can
  fail the build on, plus extractor CLIs that refuse to ship if a string
  has no translation entry.
- **Lint your source for hardcoded strings.** ESLint has
  [`eslint-plugin-i18next`](https://github.com/edvardchen/eslint-plugin-i18next)
  and
  [`@intlify/eslint-plugin-vue-i18n`](https://eslint-plugin-vue-i18n.intlify.dev/)
  to flag bare strings in JSX/templates and unused or missing keys.
  Oxlint doesn't yet ship i18n-specific rules, so run it as the fast
  first pass and keep these ESLint plugins for the i18n layer.
- **[Lunaria](https://lunaria.dev/)** compares each locale against a source
  locale and reports missing or stale keys. It works with any project that has translation
  files; you can publish a public status dashboard from the same data.

### 13. Preview deployments

The cheapest way to enable manual review and to give E2E, Lighthouse, and
visual-regression checks something realistic to run against.

- [Vercel](https://vercel.com/), [Netlify](https://www.netlify.com/), or
  [Cloudflare Pages](https://pages.cloudflare.com/) will give you a unique URL
  per PR for free.
- Wire your downstream checks to that URL.

### 14. Automated code review

In 2026, AI code review is a standard pipeline stage. It runs before any
human reviewer touches the PR and catches issues the layers above miss:
logic mistakes, missing edge cases, security smells, and the small
inconsistencies that lint rules can't express.

- **[CodeRabbit](https://www.coderabbit.ai/)**,
  **[Greptile](https://www.greptile.com/)**, and
  **[Vercel Agent](https://vercel.com/docs/agent)** are the main options. Recent benchmarks put Greptile's bug-catch rate around 82%
  versus CodeRabbit's ~44%, but Greptile produces more false positives
  and runs slower; CodeRabbit covers more git platforms.
- Have it run alongside specialist scanners (secrets, vulnerabilities,
  workflow lint, shell/yaml lint) so a single bot comment summarises
  every machine-checkable concern on the PR.
- Pause the bot on Renovate / Dependabot PRs to avoid noise on
  mechanical updates.

Treat the AI reviewer as a high-recall first pass that reduces human review without replacing it. If you want to add an AI agent that goes one step further and exercises the app in a real browser, see <InternalLink slug="automated-qa-claude-code-agent-browser-cli-github-actions">how I run automated QA with Claude Code, Agent Browser, and GitHub Actions</InternalLink>.

### 15. Runtime observability

Layers 1&ndash;13 give you confidence at merge time. Once a change is in
production, and while you're writing it, you also want a live view of
what the app is doing. The same instrumentation answers both questions.

Use **[OpenTelemetry](https://opentelemetry.io/)** as the SDK. It's the
only vendor-neutral option, and the JS ecosystem caught up in 2025&ndash;2026:
stable web SDK, official auto-instrumentations for `document-load`,
`fetch`, `xhr`, and `user-interaction`, and OTLP support in every backend
that matters.

- **Browser SDK.** [`@opentelemetry/sdk-trace-web`](https://www.npmjs.com/package/@opentelemetry/sdk-trace-web)
  plus the auto-instrumentations emits OTLP/HTTP. Wrap
  [`web-vitals`](https://github.com/GoogleChrome/web-vitals) into OTel
  metrics so LCP/INP/CLS land on the same backend as the trace that
  produced them. One pipe instead of two.
- **SSR / edge.** Next, Nuxt, SvelteKit, and Astro all expose OTel hooks.
  Set a single `service.name` resource attribute and one request stitches
  together: edge &rarr; SSR &rarr; hydration &rarr; client interaction,
  all in one trace.
- **One collector, two backends.** Run an
  [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/) with
  two exporters. In dev, point it at [Jaeger](https://www.jaegertracing.io/)
  or [Grafana Tempo](https://grafana.com/oss/tempo/) running via
  `docker-compose`; open `localhost:16686` and you can watch every fetch,
  render, and hydration span as you click through the app. In prod, swap
  the exporter to [Honeycomb](https://www.honeycomb.io/),
  [Grafana Cloud](https://grafana.com/products/cloud/),
  [Dash0](https://www.dash0.com/), or
  [Sentry's OTel ingest](https://docs.sentry.io/platforms/javascript/tracing/instrumentation/opentelemetry/).
  Same SDK, same instrumentations, different OTLP endpoint.
- **Sample, or pay.** `ParentBased(TraceIdRatioBased(0.05))` in prod,
  `AlwaysOn` in dev. Tail-sample at the collector to keep the slow and
  error traces and drop the rest, so the signal that matters survives
  without renting cloud storage for every render.

The dev-time payoff is the part most teams underuse. The next time
someone asks why a page is slow on a real device, you already have the
trace from when they loaded it.

## Where each layer runs

Same layers, different stages. Pick the cheapest stage where each check
can catch the problem.

| Stage                | What runs                                                       |
| -------------------- | --------------------------------------------------------------- |
| Editor               | Type checker LSP, linter, Vitest watch                          |
| Pre-commit           | Format and lint on staged files only                            |
| CI on PR             | Typecheck, full lint, unit, component, contract verify, build, knip, size-limit, AI review |
| CI on preview URL    | E2E, accessibility (axe + Lighthouse), visual regression        |
| Post-merge / nightly | Full E2E matrix, dependency updates, security scans, SBOM publish |
| Dev server / production | OpenTelemetry traces and metrics: live in dev, sampled in prod |

For wiring local hooks themselves, **[Lefthook](https://lefthook.dev/)** has
become the default modern alternative to
[Husky](https://typicode.github.io/husky/): a single Go binary, declarative
YAML config, and parallel execution of lint/format/test commands on staged
files. Commit a `lefthook.yml` to the repo, run `lefthook install` once, and
contributors get the same hook setup automatically. Pair it with
[`lint-staged`](https://github.com/lint-staged/lint-staged) (or Lefthook's
built-in `{staged_files}` substitution) so pre-commit only runs against the
files that changed. That fast-check pattern keeps the hook under a couple
of seconds.

**[Git 2.54](https://git-scm.com/)** added config-based hooks, which means a small project no
longer needs an external hook manager at all. You define hooks in
`.gitconfig` instead of as scripts under `.git/hooks`:

```ini
[hook "linter"]
   event = pre-commit
   command = pnpm exec oxlint --staged

[hook "format"]
   event = pre-commit
   command = pnpm exec oxfmt --check
```

Multiple hooks per event run in order. Disable a single hook with
`hook.<name>.enabled = false` (useful for opting one repo out of a
system-wide config), and list the active ones with `git hook list
pre-commit`. The traditional `.git/hooks/*` scripts still run last,
so existing setups keep working. For a small project this covers most
of what Lefthook does without an extra binary. Lefthook still has the
edge for parallel execution and staged-file substitution.

One valid alternative skips commit hooks and runs *everything* server-side in CI as required status checks. You trade a slower red-CI feedback loop for never blocking a contributor with a flaky local hook.

If GitHub Actions is the CI you're wiring this onto, [*GitHub Actions in Action*](https://www.manning.com/books/github-actions-in-action) (Kaufmann, Bos & de Vries, Manning) covers workflow design, reusable actions, matrix builds, secrets, and self-hosted runners. It pays off once you outgrow the default templates and start wiring the layers above into shared workflows.

## What this gets you

- **Regressions caught before merge.** A typed schema at the boundary plus
  a Playwright check on the critical path catches more shipped bugs than
  any single layer alone.
- **Refactors get safer.** Strict types and a healthy unit and component
  test suite let you change internals without breaking surface behaviour.
- **Onboarding gets shorter.** A new contributor can run one command, see
  green, and trust that CI will tell them if they break something.
- **No one becomes the bottleneck.** The pipeline enforces the standard
  for accessibility, performance, and i18n, so quality stops riding on a
  single contributor.

## Picking your testing shape

The layers above tell you *what* to run. They don't tell you *how much weight to give each one*. A solo dev shipping a Vite app needs a different mix than a fifty-engineer team coordinating across a dozen services.

The industry argues about this in shapes. The classical
**[Pyramid](https://martinfowler.com/articles/practical-test-pyramid.html)**
(Mike Cohn) puts most of the weight on unit tests and very little on
E2E. Kent C. Dodds'
**[Trophy](https://kentcdodds.com/blog/the-testing-trophy-and-testing-classifications)**
moves the weight to integration tests because frontend bugs live at the
component-interaction layer. Spotify's
**[Honeycomb](https://engineering.atspotify.com/2018/01/testing-of-microservices)**
pushes weight onto integrated and contract tests because in a microservices
world, isolation tests prove little and full E2E is brittle. The
**Ice-cream cone** is the anti-pattern you end up with by accident: lots of
slow E2E on top, almost nothing underneath.

The right answer is "it depends," but you can be precise about what
it depends on. As web.dev puts it in *Pyramid or Crab*, ["the testing
strategy that's right for your team is unique to your project's
context"](https://web.dev/articles/ta-strategies). Pactflow, from the
contract-testing camp, goes further: at scale, full E2E is
[a tax with diminishing returns](https://pactflow.io/blog/proving-e2e-tests-are-a-scam/)
once teams and services multiply.

The four inputs that change the answer most:

- **Team size.** Six developers can keep a real E2E suite green together;
  sixty cannot. Coordination cost is what kills E2E suites at scale.
- **Backend control.** If you don't own the backend, contract testing
  goes from "nice" to "the only way you can change anything safely".
- **Number of services in the flow.** Each new service multiplies the
  surface that has to be set up, seeded, and reset for an E2E run.
- **Deployment cadence.** A daily-merge team can't afford a flaky
  twenty-minute suite; a quarterly-release team can.

Pick yours and the shape that fits will appear:

The same pyramid that helps one team can block another from shipping. Pick the shape that fits your constraints.

## Picking your battles

You don't need every layer on day one. A reasonable order to add them:

1. TypeScript strict + a fast linter + a formatter, wired into Lefthook
   so format and lint run on staged files at commit time.
2. Vitest for utilities, run on PR.
3. MSW handlers for any module that hits the network, shared between
   tests and the dev server.
4. Playwright for the single most important user journey, with hydration
   and CSP listeners wired into a shared fixture.
5. Contract testing the moment consumer and provider deploy on different
   cadences. Pact if you control both sides, OpenAPI validation if the
   provider already publishes a spec.
6. Preview deployments and Lighthouse CI (light *and* dark).
7. OpenTelemetry traces and metrics. Point the SDK at a local Jaeger
   via `docker-compose` the moment a "why is this slow?" question takes
   more than five minutes to answer. Same SDK in prod (different OTLP
   endpoint) once you have real users.
8. Storybook + visual regression once the design system stabilises.
9. Accessibility audits in component tests and E2E.
10. Knip and bundle-size budgets once the codebase has weight.
11. i18n drift checking once you ship a second locale.
12. AI code review and SBOM generation once the project has external
    stakeholders to answer to: reviewers, customers, or compliance.

Each layer should pay for itself in caught regressions or saved review
time. Remove the ones that don't.

## Supply chain defaults

The pipeline above catches the bugs you write. None of it stops a compromised dependency from running code on your laptop. The 2025&ndash;2026 wave of [npm](https://www.npmjs.com/) attacks (Shai-Hulud, the [Rspack](https://rspack.dev/) postinstall cryptominer, the [axios](https://axios-http.com/) 1.14.1 hijack) made the package manager's defaults a real part of your security posture. I use **[pnpm](https://pnpm.io/)** on every new project. Three of its settings do most of the work.

**1. Lifecycle scripts blocked by default.** Since pnpm 10, `preinstall`
and `postinstall` scripts in dependencies do not run on `pnpm install`.
You opt specific packages in via `pnpm.onlyBuiltDependencies` in
`package.json`. Most historical supply chain payloads shipped through
postinstall, so this default removes one of the biggest attack vectors.

**2. `minimumReleaseAge`.** A pnpm 10.16+ setting that refuses to
resolve a published version until it is at least *N* minutes old. Set
it to `1440` (one day) or `10080` (one week) in `pnpm-workspace.yaml`.
Most compromised packages get detected and unpublished within hours,
so a 24-hour delay covers the common published-and-pulled incidents.
pnpm 11 makes one day the default. Use `minimumReleaseAgeExclude` for
the few internal or first-party packages you need to install the moment
they ship.

**3. `blockExoticSubdeps`.** Refuses transitive dependencies pinned to
git repositories or tarball URLs. Closes a common path for
typo-squatting and dependency confusion.

A minimal `pnpm-workspace.yaml` for a new project:

```yaml
minimumReleaseAge: 1440
blockExoticSubdeps: true
onlyBuiltDependencies:
  - esbuild
  - sharp
```

Pair this with **OSV-Scanner** and **Gitleaks** in CI (layer 11 of the
pipeline) and you cover both the install-time and the audit-time sides
of supply chain security.

## Related resources

If you want to read more or start implementing this:

**Tools**

- [Vite+](https://viteplus.dev/) &ndash; unified toolchain from VoidZero (Vite, Rolldown, Vitest, Oxlint, Oxfmt, Tsdown)
- [pnpm supply chain security](https://pnpm.io/supply-chain-security) &ndash; the full list of defaults and settings discussed above
- [Vitest](https://vitest.dev/) &ndash; including [browser mode](https://vitest.dev/guide/browser/)
- [Playwright](https://playwright.dev/)
- [MSW](https://mswjs.io/) &ndash; network-level API mocking for browser and Node
- [Pact](https://pact.io/) and [PactFlow](https://pactflow.io/) &ndash; consumer-driven and bi-directional contract testing
- [Schemathesis](https://schemathesis.readthedocs.io/), [Dredd](https://dredd.org/), [Spectral](https://stoplight.io/open-source/spectral) &ndash; OpenAPI-based contract testing and linting
- [Lefthook](https://lefthook.dev/) &ndash; fast Git hooks manager (modern Husky alternative)
- [Storybook](https://storybook.js.org/)
- [Knip](https://knip.dev/)
- [Oxlint](https://oxc.rs/docs/guide/usage/linter)
- [Biome](https://biomejs.dev/)
- [Lighthouse CI](https://github.com/GoogleChrome/lighthouse-ci)
- [Lunaria](https://lunaria.dev/) &ndash; i18n drift detection
- [size-limit](https://github.com/ai/size-limit)
- [axe-core](https://github.com/dequelabs/axe-core)
- [Syft](https://github.com/anchore/syft) &ndash; SBOM generation
- [CodeRabbit](https://www.coderabbit.ai/), [Greptile](https://www.greptile.com/) &ndash; AI code review

**Reference**

- [The Practical Test Pyramid](https://martinfowler.com/articles/practical-test-pyramid.html) &ndash; Ham Vocke's canonical write-up of Mike Cohn's pyramid.
- [The Testing Trophy](https://kentcdodds.com/blog/the-testing-trophy-and-testing-classifications) &ndash; Kent C. Dodds' model for where to put the weight of your tests.
- [Testing of Microservices (Honeycomb)](https://engineering.atspotify.com/2018/01/testing-of-microservices) &ndash; Spotify's case for integrated tests over isolated unit tests in a microservices world.
- [Pyramid or Crab? Find a testing strategy that fits](https://web.dev/articles/ta-strategies) &ndash; web.dev on choosing a shape for your context.
- [Proving E2E tests are a scam](https://pactflow.io/blog/proving-e2e-tests-are-a-scam/) &ndash; Pactflow's contract-first counter-position.
- [Contract Testing in Action](https://www.oreilly.com/library/view/contract-testing-in/9781633437241/) &ndash; Marie Cruz & Lewis Prescott (Manning) on consumer-driven and bi-directional contracts in practice.
- [GitHub Actions in Action](https://www.manning.com/books/github-actions-in-action) &ndash; Kaufmann, Bos & de Vries (Manning) on workflows, reusable actions, matrix builds, and self-hosted runners.
- <InternalLink slug="frontend-testing-guide-10-essential-rules">Frontend testing guide: 10 essential rules for naming tests</InternalLink>

---

--- title: Exploratory QA with AI Agents: Building a Site-Agnostic Harness description: A thin Bun runner that hands a coding agent one charter and lets it drive a real browser through an exploratory QA session. Works with Claude, Codex, or Copilot, and any browser CLI. tags: ['claude-code', 'testing', 'automation', 'ai', 'agent-browser'] url: https://alexop.dev/posts/exploratory-qa-ai-agents-site-agnostic-harness ---

# Exploratory QA with AI Agents: Building a Site-Agnostic Harness



`explore-qa` is a small Bun runner I built to drive AI agents through exploratory QA sessions. You give it a charter ("explore the basket flow with a mobile viewport"), pick an agent (Claude, Codex, or Copilot), pick a browser CLI (`agent-browser` or `playwright-cli`), and it runs the session. You get back a Markdown report shaped like a real tester's notes: SBTM sections, PROOF debrief, screenshots, full JSONL session log.

About 500 lines of TypeScript plus a folder of Markdown. Site-agnostic by construction.

<Alert type="github" title="Just want to try it?">
  Repo: [github.com/alexanderop/explore-qa](https://github.com/alexanderop/explore-qa). Use it as a template, clone it, and run the `/onboard-site` skill to wire it up to your own site. You'll need one of [Claude Code](https://docs.claude.com/en/docs/claude-code/overview), [Codex CLI](https://developers.openai.com/codex/cli), or [GitHub Copilot CLI](https://docs.github.com/en/copilot/concepts/agents/about-copilot-cli) installed to drive the runs.

  1. `git clone` the repo, `bun install`, `bun link`
  2. Open the folder in Claude Code and run `/onboard-site https://yoursite.com`
  3. `qa` to pick a charter, agent, and browser in an interactive wizard
  4. Read the report under `qa-runs/charters/<charter>/`
</Alert>

## A real finding on otto.de

Before the deep dive, here's what this actually produces. On a recent run against otto.de's mobile nav, Codex flagged a small UX bug: the **Filter** button (bottom right, highlighted in pink) is rendered on the category overview panel, where there are no products to filter yet. It only belongs on the product listing screen, one level deeper.

<CaptionedImage
  src={ottoFilterOnCategoryOverview}
  alt="Four screenshots of otto.de mobile navigation. The final panel shows the category overview with a Filter button visible at the bottom right, highlighted in pink — this button should only appear on the product listing screen."
  caption="Codex finding on otto.de mobile: the Filter CTA leaks onto the category overview panel, where there are no products to filter. It should only show on the product listing screen (second panel from the left)."
/>

Nothing broken, no broken-image 404, no crash. The kind of small consistency bug a scripted E2E suite would never notice because nobody wrote a test for "is the filter button absent on this screen." An agent browsing the menu the way a user would noticed it in under seven minutes.

## The problem

Most "AI testing" demos I see lean one way: Playwright on autopilot. A script, some selectors, an LLM picking the next click. It passes green, nobody learns anything about the site, and the bug that shipped to production wasn't in the happy path anyway.

I wanted the opposite. A tool that behaves like a QA engineer on their first day. Point it at a website. Give it a one-line mission. Let it browse, notice what's weird, file what it finds, and hand back a report I can triage in ten minutes. Agents are the first tool that make this economical: one tester per charter, parallel, at roughly the cost of a cup of coffee per run.

## Overview

- **Charter**, one file, one mission. "Explore X with Y to discover Z."
- **Site profile**, one file per site. Base URL, viewport, known quirks.
- **Harness**, composes a prompt from Markdown fragments, spawns the agent, captures the session.
- **Output**, a Markdown report with SBTM + PROOF sections, screenshots, and a full JSONL session log.

No hard-coded selectors. No `page.click('.btn-checkout')`. The agent reads `agent-browser --help` at the start of every run and figures out the CLI from scratch. That keeps the harness site-agnostic.

In one picture:

You write the charter. The harness builds the prompt. The agent runs the session. You read the report.

## What scripted E2E tests are bad at

Scripted Playwright and Cypress suites do one job well: catch regressions in flows you *already know about*. They are bad at:

- ❌ Finding issues nobody thought to write a test for
- ❌ Catching layout breaks on the mobile viewport
- ❌ Noticing 404s on the third-party tracking pixel
- ❌ Spotting a consent banner that ate the tap target
- ❌ Doing an a11y pass on the page you just changed

Exploratory testing is the opposite discipline. Kaner & Bach's definition is worth quoting because most people get it wrong:

> Exploratory testing is simultaneous learning, test design, and test execution.

Learning, test design, and execution happen **in parallel**, not sequentially. Scripts come after, not before. Humans are great at it. LLMs turn out to be surprisingly good at it too, if you build the harness right.

## Six moving parts

Each one does exactly one thing.

You write a charter. You point it at a site. The harness composes a system prompt plus a user prompt, spawns the agent CLI in fully permissive mode, and the agent drives the browser for the next 5 to 10 minutes while writing a `report.md`.

A charter looks like this:

```markdown
---
name: otto-pdp-basket
includeFragments:
  - _browser-workflow
  - _report-format
---

# Charter: add to basket from PDP

## Mission

> Explore **the product detail page → basket flow**
> with **a mobile viewport, no login, a cold cookie**
> to discover **whether a user can add an item and see it in the basket**.

Time box: ~5 minutes.

## Risks / oracles

- Size picker blocks add-to-basket on mobile
- Consent banner obscures the CTA
- Basket count doesn't update after add
```

That's it. No code. The harness handles everything else.

## The prompt is the config

The prompt isn't in TypeScript. It's in Markdown fragments.

```
prompts/
├── _system.md           ← always loaded: "you are a precise, honest QA engineer"
├── _honesty-checks.md   ← always loaded: "don't invent findings"
├── _browser-workflow.md ← opt-in: "read {{browser}} --help first"
└── _report-format.md    ← opt-in: SBTM + PROOF report shape
```

Want to make the agent more aggressive? Edit the Markdown. Want a new report section? Edit the Markdown. There's no DSL, no YAML template, no indirection layer between you and what the agent reads. **The prompt *is* the config.**

Rules in `_system.md` apply to every run. Rules in `_browser-workflow.md` only load when a charter opts in via `includeFragments`. Charter bodies stay short because the rules aren't duplicated across every file.

Composition is a fan-in:

Five or six Markdown files in, one deterministic prompt bundle out. The `promptHash` is what later lets `compare-runs.ts` separate a prompt change from model variance.

## The `{{browser}} --help` trick

Early versions of the harness had backend-specific CLI snippets baked into the prompt. Things like `agent-browser session start --mobile`. It worked, until `agent-browser` shipped a new subcommand and half my charters broke overnight.

The fix is one line in `_browser-workflow.md`:

> Before your first action, run `{{browser}} --help` and read it. Use the commands you see in the live help, not commands you remember.

Now the harness is backend-agnostic by construction. Swap `agent-browser` for `playwright-cli` in `qa.local.json`, and the same charter runs against a different CLI with zero prompt changes.

✅ Agent reads live help, uses current commands
❌ Agent relies on memorized subcommands, breaks on every CLI update

## Three agents, three incompatible CLIs

Here's what the actual invocations look like for the same charter on each backend. I pulled these from [Claude Code's CLI reference](https://code.claude.com/docs/en/cli-reference), [Codex's `exec` reference](https://developers.openai.com/codex/cli/reference), and [GitHub Copilot CLI's docs](https://docs.github.com/en/copilot/concepts/agents/about-copilot-cli). They all do roughly the same thing. None of them agree on how to do it.

**Claude Code:**

```bash
claude -p "$PROMPT" \
  --model claude-opus-4-6 \
  --output-format stream-json \
  --include-partial-messages \
  --verbose \
  --append-system-prompt "$SYSTEM_PROMPT" \
  --add-dir "$RUN_DIR" \
  --permission-mode bypassPermissions
```

**Codex CLI:**

```bash
# Codex has no --system-prompt flag. It reads AGENTS.md from --cd.
echo "$SYSTEM_PROMPT" > "$RUN_DIR/AGENTS.md"

codex exec \
  --cd "$RUN_DIR" \
  -m gpt-5.4 \
  --dangerously-bypass-approvals-and-sandbox \
  --json \
  -o "$LOG_DIR/codex-last-message.txt" \
  "$PROMPT"
```

**GitHub Copilot CLI:**

```bash
# Copilot also reads AGENTS.md from its working directory.
echo "$SYSTEM_PROMPT" > "$RUN_DIR/AGENTS.md"

cd "$RUN_DIR" && copilot \
  -p "$PROMPT" \
  --model gpt-5.4 \
  --allow-all-tools \
  --add-dir "$(pwd)" \
  --output-format json
```

Look at how many things differ between three CLIs that all do the same job:

| Concern             | Claude                          | Codex                                    | Copilot                      |
| :------------------ | :------------------------------ | :--------------------------------------- | :--------------------------- |
| Non-interactive     | `-p`                            | `exec`                                   | `-p`                         |
| System prompt       | `--append-system-prompt "TEXT"` | write `AGENTS.md` in `--cd`              | write `AGENTS.md` in cwd     |
| Permission bypass   | `--permission-mode bypassPermissions` | `--dangerously-bypass-approvals-and-sandbox` | `--allow-all-tools`    |
| Working directory   | `--add-dir`                     | `--cd` / `-C`                            | process `cwd` + `--add-dir`  |
| Model flag          | `--model`                       | `-m`                                     | `--model`                    |
| Output format       | `stream-json`                   | `--json` (NDJSON)                        | `json`                       |
| Final answer        | in the stream                   | `--output-last-message FILE`             | in the JSON payload          |

This is the argument for a runner. Not because the CLIs are hard on their own, they aren't. The moment you want to run the *same* charter across all three, you end up with three invocation templates, three ways of handing over a system prompt, and three output formats to parse on the way back.

Without the runner, A/B testing one prompt across three agents means:

1. Write three shell scripts (one per CLI) that each build the right flag combo.
2. Materialize `AGENTS.md` for Codex and Copilot but use `--append-system-prompt` for Claude.
3. Parse `stream-json` for Claude, NDJSON events for Codex, and a JSON blob for Copilot, with different "where's the final answer" rules for each.
4. Re-read all three docs every time a CLI cuts a release, because the flags drift.

With the runner, it's one switch statement in `scripts/lib/agents.ts` and one command:

```bash
qa otto-pdp-basket claude  agent-browser otto
qa otto-pdp-basket codex   agent-browser otto
qa otto-pdp-basket copilot agent-browser otto
```

Same prompt (identical `promptHash`), same charter, same report shape. The per-CLI quirks are one file deep.

## Two browsers, same charter

The same story plays out one layer down at the browser tool. `explore-qa` works with two browser CLIs today, [`agent-browser`](https://www.npmjs.com/package/agent-browser) and Microsoft's [`playwright-cli`](https://github.com/microsoft/playwright-cli). They're also incompatible in all the ways that matter to a script.

Here's the same "open a page, snapshot it, click the primary button, screenshot the result" flow on each:

**agent-browser** (flat, stateful, one global session):

```bash
agent-browser open https://example.com
agent-browser set device "iPhone 15 Pro"
agent-browser snapshot                          # accessibility tree with @refs
agent-browser click @ref_07
agent-browser screenshot /abs/path/after-click.png
agent-browser console                            # view logs
agent-browser close
```

**playwright-cli** (named sessions, YAML snapshots with `e`-refs):

```bash
export PLAYWRIGHT_CLI_DEVICE="iPhone 15 Pro"     # env-var device emulation
playwright-cli -s=otto open https://example.com
playwright-cli -s=otto snapshot                  # writes YAML with e1, e15, e34…
playwright-cli -s=otto click e15
playwright-cli -s=otto screenshot --filename=after-click.png
playwright-cli -s=otto close
```

Same flow, very different shape:

| Concern              | `agent-browser`                    | `playwright-cli`                          |
| :------------------- | :--------------------------------- | :---------------------------------------- |
| Navigate             | `open <url>`                       | `open [url]` then `goto <url>`            |
| Element identity     | `@ref` from live snapshot          | `e1`, `e15`, `e34` from YAML snapshot     |
| Device emulation     | `set device "iPhone 15 Pro"`       | `PLAYWRIGHT_CLI_DEVICE` env var           |
| Sessions             | one implicit global session        | named sessions via `-s=<name>`            |
| Typing into an input | `type <sel> <text>`                | `fill e5 <text>` (or `type "text"`)       |
| Screenshot target    | positional path arg                | `--filename=` flag                        |
| Allow-tool pattern   | `Bash(agent-browser:*)`            | `Bash(playwright-cli:*)`                  |

The runner abstracts this with two lines of code in [`scripts/lib/browsers.ts`](https://github.com/alexanderopalic/explore-qa/blob/main/scripts/lib/browsers.ts) and one line of prompt in `_browser-workflow.md`:

```markdown
Run `{{browser}} --help` **first** to learn the available commands and flags.
```

That's the whole trick. Instead of teaching the agent two CLI syntaxes up front, we teach it to *discover* the CLI at runtime. The agent reads the live help, picks the subcommands it sees, and runs. Same charter, same prompt, same report. When `agent-browser` ships a new subcommand tomorrow, the agent picks it up on the next run without a prompt edit.

Swap backends with one line in `qa.local.json`:

```json
{ "browser": "playwright-cli" }
```

Or override per invocation:

```bash
qa otto-pdp-basket claude agent-browser  otto
qa otto-pdp-basket claude playwright-cli otto
```

Two runs, two different browser CLIs, identical `promptHash`. If the results disagree, the delta is the browser tool. Not a prompt change, not model drift, not you. That's the kind of signal scripted suites never give you.

## Replaying one prompt across agents

The `/agent-battle` skill runs the same charter in parallel across all three agent CLIs:

```
> /agent-battle otto-cart-to-checkout.md
• Charter: otto-cart-to-checkout, site: otto. Starting all three in parallel.
• Bash(qa otto-cart-to-checkout claude  agent-browser otto)
• Bash(qa otto-cart-to-checkout codex   agent-browser otto)
• Bash(qa otto-cart-to-checkout copilot agent-browser otto)
• All three agents launched.
```

The fan-out:

Output: a side-by-side comparison on speed, findings, discipline, and report quality. Useful for two things:

1. **Picking which agent to trust on a given site.** They don't perform equally. Claude tends to be more thorough, Codex tends to be faster, Copilot tends to follow the report format most literally.
2. **Catching prompt regressions.** If two agents suddenly diverge after a prompt tweak, the tweak probably hurts one of them.

### A real disagreement

Here's an actual run against otto.de's product detail to basket flow from a week ago (`qa-runs/charters/otto-pdp-basket/2026-04-18_battle-summary.md`):

| agent   | duration | findings | severity |
| :------ | :------- | :------- | :------- |
| claude  | 07:57    | 0        | n/a      |
| codex   | 06:53    | **1**    | **Major** |
| copilot | 09:26    | 0        | n/a      |

Codex flagged a Major finding: "Basket totals stay at single-item values after quantity increases to 2." Claude and Copilot ran the *same* prompt on the *same* product in the *same* timeframe (identical `promptHash`), and both observed the subtotal updating correctly from 39,99 € to 79,98 €. Copilot specifically reran to rule out transient UI state.

One of them had to be wrong. Because the prompt hashes matched, the disagreement was genuinely agent variance. Not prompt drift, not me editing a fragment, not a model upgrade. That narrowed triage to "whose evidence is stronger?" in about two minutes. (Codex's finding came from a single DOM read after a 4-second wait. The other two did a reload and a second read. Codex was wrong.)

Without the harness I'd have run one agent, trusted its report, and either shipped a non-bug as Major or dismissed a real one. Three reports under one `promptHash` made the disagreement itself the signal.

## SBTM + PROOF: why the report looks like a tester's notes

The report format isn't my invention. It's [Session-Based Test Management](https://www.satisfice.us/articles/sbtm.pdf) (James and Jonathan Bach, 2000) plus PROOF, Jon Bach's five-point debrief shape.

Every report has these sections:

- **Session**, what was tested, what wasn't
- **Task breakdown**, how time was split (design, investigation, setup)
- **Findings**, each one with severity, repro, screenshot
- **Accessibility**, landmarks, focus order, alt text
- **PROOF debrief**, Past, Results, Obstacles, Outlook, Feelings

That last one matters. *Feelings* is where the agent rates its own confidence, and it's the first thing I read when triaging. A low-confidence PROOF entry is a signal to rerun with a different agent, not to ship the finding.

Read Elisabeth Hendrickson's [*Explore It!*](https://pragprog.com/titles/ehxta/explore-it/) Chapter 2 and Michael Bolton's [*An Exploratory Tester's Notebook*](https://www.developsense.com/presentations/2007-10-PNSQC-AnExploratoryTestersNotebook.pdf) for the full version. Everything in the prompt fragments is downstream of those three sources.

## What I'd do differently

A few things I learned the hard way:

- **Don't stuff the charter with oracles.** Three or four risks, each with a one-line oracle, is the sweet spot. More than that and the agent turns the charter into a checklist, which kills exploratory behavior.
- **Screenshots only on findings and key states.** Every screenshot is tokens on the return trip. An agent that takes a screenshot after every click runs out of context before it reaches the bug.
- **Let the agent break script.** `_system.md` explicitly tells the agent: "If something unusual catches your eye, follow the trail even if it isn't in the scenarios." Most of the interesting findings come from the deviation, not the script.
- **Permission mode is all-or-nothing.** Claude runs with `--permission-mode bypassPermissions`, Codex with `--dangerously-bypass-approvals-and-sandbox`, Copilot with `--allow-all-tools`. Non-interactive charter runs cannot stop to ask for approval. You either trust the agent with full shell access for the run, or you don't run it at all.

## Related posts

- <InternalLink slug="automated-qa-claude-code-agent-browser-cli-github-actions">How to Use Claude Code as an AI QA Tester with Agent Browser</InternalLink>, the single-charter version that predated this harness
- <InternalLink slug="building_ai_qa_engineer_claude_code_playwright">Building an AI QA Engineer with Claude Code and Playwright MCP</InternalLink>, the MCP-based cousin
- <InternalLink slug="spec-driven-development-claude-code-in-action">Spec-Driven Development with Claude Code in Action</InternalLink>, how I plan non-trivial work with parallel subagents

The agent forgets. Your charters don't.

---

--- title: How to Use Claude Code as an AI QA Tester with Agent Browser description: Claude Code and Agent Browser let you test your web app in a real browser without hardcoded selectors. Manual browser control, AI-driven exploration, and structured JSON output. tags: ['claude-code', 'testing', 'automation', 'agent-browser'] url: https://alexop.dev/posts/automated-qa-claude-code-agent-browser-cli-github-actions ---

# How to Use Claude Code as an AI QA Tester with Agent Browser



## Overview

Claude Code and [Agent Browser](https://github.com/vercel-labs/agent-browser) let you test your web app in a real browser without hardcoded selectors. You point Claude at your app, and it clicks through pages, fills forms, and checks for errors. If the layout changes or a new onboarding flow appears, Claude adjusts. No selectors to maintain.

You'll need a web app with a dev server and basic familiarity with the command line and Claude Code.

You'll walk away knowing how to:

- Control a browser from the terminal using Agent Browser's snapshot-and-ref model
- Run one-shot AI-powered browser exploration with `claude -p`
- Separate QA persona from task instructions using `--system-prompt` and `--append-system-prompt`
- Get machine-readable structured JSON output with `--output-format json` and `--json-schema`

Part 1 covers Agent Browser and `claude -p` locally. Part 2 wraps it into a GitHub Actions workflow that runs on every PR.

## Table of Contents

## Background

### The problem

I'm building a workout tracking PWA, a Vue 3 app with exercises, workout flows, templates, timers, and interactive forms. You fix something on one page and break something on another. I had unit tests and integration tests with Vitest, but no answer to: **does the app work when a real user clicks through it?**

Manual QA is tedious. I'd deploy a change, open the app, click around for a few minutes, and call it done. Half the time I'd skip pages I didn't think were affected. I shipped bugs to production: a form that fails without feedback, a navigation link pointing nowhere, a JS error on a page I forgot to check.

I wanted something that could open the app in a real browser, click around like a user, and flag what's broken. Scripted Playwright tests with hardcoded selectors need constant maintenance. I wanted a test runner that could handle a changed layout without a rewrite.

### What we're building

An AI-powered QA workflow where Claude Code drives a real browser via Agent Browser. A single terminal command that:

1. Opens your app in a real browser
2. Claude explores it like a user: clicking navigation, filling forms, checking for JS errors
3. Returns a structured JSON report with any bugs found

Part 2 wraps this into a GitHub Actions workflow that runs on PRs and posts bug reports as comments.

### How Agent Browser works

[Agent Browser](https://github.com/vercel-labs/agent-browser) is a native Rust CLI for browser automation. You issue commands one at a time, which makes it a natural fit for AI agents. It uses Chrome for Testing under the hood, so no Playwright or Node.js runtime is required.

The key concept is **element refs**. `snapshot` returns an accessibility tree where every interactive element has a ref like `@e1`, `@e2`. Claude reads the snapshot, decides what to click, and uses the ref.

```bash
agent-browser open https://www.otto.de    # Open a URL
agent-browser snapshot -i                  # Get interactive elements with refs
agent-browser click @e2                    # Click element by ref
agent-browser fill @e3 "value"             # Fill an input
agent-browser console                      # Check for JS errors
agent-browser screenshot                   # Take a screenshot
agent-browser close                        # Close browser
```

Claude repeats this loop until it has enough information to report:

A concrete example:

1. Claude runs `snapshot -i` and sees: `nav[@e10] > a[@e11] "Home" | a[@e12] "Workouts" | a[@e13] "Settings"`
2. Claude decides to test navigation and runs `click @e12`
3. Claude runs `snapshot -i` again and sees the Workouts page loaded
4. Claude concludes navigation works

Agent Browser uses a client-daemon architecture. The daemon starts on the first command and persists between commands, so subsequent operations are fast.

## Before you start

Before you start, you should:

- Have a web app with a dev server (we use Vite, but any web app works; the examples use `https://www.otto.de`)
- Have Node.js and npm installed
- Have Claude Code installed (`npm install -g @anthropic-ai/claude-code`)

## Step 1: Agent Browser by hand

Before letting Claude drive, get comfortable with Agent Browser yourself. Any public website works.

1. Install Agent Browser globally and set up the browser:

    ```bash
    npm install -g agent-browser
    agent-browser install  # Download Chrome from Chrome for Testing
    ```

2. Open a website:

    ```bash
    agent-browser open https://www.otto.de
    ```

    You'll see:

    ```txt
    ✓ OTTO - Mode, Möbel & Technik » Zum Online-Shop
      https://www.otto.de/
    ```

3. Take a snapshot to see the page structure:

    ```bash
    agent-browser snapshot -i
    ```

    The `-i` flag shows only interactive elements. You'll see something like:

    ```txt
    - button "Zur Hauptnavigation" [ref=e1]
    - link "zur Homepage" [ref=e2]
    - searchbox "Wonach suchst du?" [ref=e3]
    - button "Suche abschicken" [ref=e4]
    - link "s Service" [ref=e5]
    - link "Θ Mein Konto" [ref=e6]
    - link "Merkzettel" [ref=e7]
    - link "Inspiration" [ref=e8]
    - link "Damen-Mode" [ref=e9]
    - link "Herren-Mode" [ref=e10]
    - link "Baby & Kind" [ref=e11]
    ```

    Each `[ref=eN]` is a handle you can interact with using `@eN`.

4. Try clicking a nav link:

    ```bash
    agent-browser click @e9
    ```

    The browser navigates to the Damen-Mode page. Take another snapshot to see the new page:

    ```bash
    agent-browser snapshot -i
    ```

5. Try filling the search box and submitting:

    ```bash
    agent-browser fill @e3 "Sneaker"
    agent-browser press Enter
    ```

6. Check for JavaScript errors:

    ```bash
    agent-browser console
    ```

7. Close the browser when you're done:

    ```bash
    agent-browser close
    ```

Claude runs the same commands in the same order. It reads the snapshot output, picks what to click next, and loops until it has a report.

## Step 2: Let Claude drive with `claude -p`

<Aside type="info" title="Why claude -p matters beyond QA">
`claude -p` turns Claude Code into a general-purpose agent. Browser testing is one use case, but the same flags work for data processing, file organization, API calls. If you can script it in a terminal, you can hand it to `claude -p`.

The official [Claude SDK](https://docs.anthropic.com/en/docs/claude-code/sdk) (`@anthropic-ai/claude-code`) exposes the same capabilities programmatically. The flags you learn here (`--allowedTools`, `--json-schema`, `--append-system-prompt`) map directly to SDK parameters in TypeScript and Python.

You can also wire `claude -p` into shell aliases in your `.zshrc` for one-word commands like `cpush` (auto-commit and push) or `clint` (lint your project). See <InternalLink slug="claude-code-slash-commands-guide">Claude Code Slash Commands Guide</InternalLink> for examples.

</Aside>

`claude -p` runs Claude Code with a one-shot prompt from the terminal. No interactive session, no back-and-forth.

1. Run Claude with a simple exploration prompt. Say "agent-browser cli" in the prompt. If you leave out "cli", Claude doesn't know which tool to use:

    ```bash
    claude -p "Open https://www.otto.de using agent-browser cli. \
    Take a snapshot. Click one navigation link. \
    Take another snapshot. \
    Tell me what you found." \
    --allowedTools "Bash(agent-browser*)"
    ```

    Watch it work. You'll see each tool call in real time.

    Outcome:

    ```txt
    Here's what I found:

    Snapshot 1 — otto.de Homepage:
    - OTTO is a major German online shop for fashion, furniture, and electronics
    - The top navigation has categories: Inspiration, Damen-Mode, Herren-Mode,
      Baby & Kind, Sport, Beauty & Drogerie, Multimedia, Haushalt, Küche,
      Heimtextilien, Möbel, Baumarkt, Marken, Sale
    - Several promotional banners were visible:
      - 10 EUR coupon for new customers (valid until April 30)
      - 20% extra on fashion & sport (valid until April 13)
      - 20% extra for OTTO-Up members on selected furniture
      - 10% extra on Samsung TVs & soundbars (valid until April 20)

    Snapshot 2 — Multimedia category page:
    After clicking "Multimedia", the page showed a structured product catalog
    with subcategories:
    - Fernseher (TVs): OLED (69), 4K (480), QLED (236), Smart-TVs (428),
      LED (555), 8K (2)
    - Heimkino: Surround systems (186), Soundbars (228),
      Beamer/Projectors (603), Blu-ray players (20), Subwoofers (651),
      DVD players (76)
    - Additional categories for audio, computing, gaming, and accessories

    The site is fully functional, well-structured with clear navigation,
    and currently running several spring sales promotions.
    ```

2. Now give Claude a more structured QA prompt:

    ```bash
    claude -p "You are a QA tester. Open https://www.otto.de using agent-browser cli.

    Test the following:
    1. Does the homepage load? (take a snapshot)
    2. Does navigation work? (click 2 links, snapshot each)
    3. Are there any JS errors? (check console)

    Report your findings as:
    - PASS or FAIL for each test
    - Any bugs found" \
    --allowedTools "Bash(agent-browser*)"
    ```

    Outcome:

    ```txt
    QA Report: otto.de

    Test 1: Homepage Load — PASS
    - URL: https://www.otto.de/
    - Title: "OTTO - Mode, Möbel & Technik » Zum Online-Shop"
    - Page rendered fully with banner, search bar, navigation,
      promotional coupons, and product categories

    Test 2: Navigation — PASS (both links)
    1. Damen-Mode → https://www.otto.de/damen/ — PASS
    2. Multimedia → https://www.otto.de/technik/multimedia/ — PASS
    - Both pages loaded correctly with proper titles and content

    Test 3: JS Errors — PASS
    - agent-browser errors returned no page errors across all 3 pages
    - agent-browser console returned no console warnings/errors

    Bugs Found: None.
    All tests passed cleanly with no JS errors or navigation issues.
    ```

## Step 2b: Separate persona from task with system prompts

In the previous step, the QA persona ("You are a QA tester") was mixed into the task prompt. Claude Code has flags to separate these concerns: `--system-prompt` replaces the default system prompt, and `--append-system-prompt` adds to it.

The Step 2 example rewritten with `--append-system-prompt`:

```bash
claude -p "Open https://www.otto.de using agent-browser cli.

Test the following:
1. Does the homepage load? (take a snapshot)
2. Does navigation work? (click 2 links, snapshot each)
3. Are there any JS errors? (check console)

Report your findings as:
- PASS or FAIL for each test
- Any bugs found" \
    --append-system-prompt "You are a senior QA engineer. Always use \
'agent-browser snapshot -i' for interactive elements only. Be concise \
and structured in your reports." \
    --allowedTools "Bash(agent-browser*)" \
    --max-turns 15
```

Outcome:

```txt
## QA Report: otto.de

| # | Test | Result |
|---|------|--------|
| 1 | **Homepage loads** | **PASS** — Title: "OTTO - Mode, Möbel & Technik » Zum Online-Shop". Full nav bar, search, product recommendations, and brand sections all rendered. |
| 2a | **Navigation: Multimedia** | **PASS** — Clicked "Multimedia" nav link. Category page loaded with subcategories (Fernseher, Heimkino, Audio, etc.) with product counts. |
| 2b | **Navigation: Möbel** | **PASS** — Clicked "Möbel" nav link. Category page loaded with subcategories (Wohnzimmer, Schlafzimmer, etc.) with product counts. |
| 3 | **JS console errors** | **PASS** — No JavaScript errors detected. No failed resource loads (HTTP 4xx/5xx). |

**Bugs found:** None.

All 4 checks passed. The site loads correctly, navigation between category pages works as expected, and no client-side errors were observed.
```

Now the task prompt describes *what* to test. You put the persona and behavioral rules in `--append-system-prompt`, which applies them on every turn without cluttering the task.

### `--system-prompt` vs `--append-system-prompt`

- **`--append-system-prompt`** adds your instructions on top of Claude Code's defaults. Claude still knows how to use Bash, handle errors, etc. Best for most cases.
- **`--system-prompt`** replaces the entire default system prompt. You get full control but lose built-in behaviors. Use this when you want a stripped-down agent that only runs `agent-browser` commands.

### Other useful flags

| Flag | Purpose |
|---|---|
| `--max-turns N` | Caps how many tool-call turns Claude gets. Match to your prompt's scope: 5-8 for a single assertion, 15 for a smoke test, 30+ for deep exploration. |
| `--model` | Pick the model. Use `opus` for thorough QA where you want Claude to reason carefully, `sonnet` for fast smoke tests. |
| `--output-format json` | Machine-readable output (covered in Step 4). |

### Example with all flags

```bash
claude -p "Open https://www.otto.de using agent-browser cli.
Navigate to every page in the main navigation.
Check console for JS errors on each page.
Report PASS/FAIL per page." \
    --append-system-prompt "You are a senior QA engineer testing a \
web shop. Use 'agent-browser snapshot -i' for interactive \
elements only. Be concise." \
    --allowedTools "Bash(agent-browser*)" \
    --max-turns 20 \
    --model opus
```

## Step 3: Try it on your own app

1. Point Claude at your app (here we use otto.de, but swap in your own URL):

    ```bash
    claude -p "Open https://www.otto.de using agent-browser. \
    Take a snapshot. Navigate to 3 different pages. \
    Check console for JS errors on each page. \
    Report what you found." \
    --allowedTools "Bash(agent-browser*)"
    ```

## Step 4: Get structured JSON output

Free-text output works for manual review, but you can't branch a shell script on "PASS" buried in a markdown table.

Claude's output is non-deterministic. You can't predict the exact wording. But your downstream decisions are deterministic: fail the build or don't, post a comment or don't.

`--json-schema` closes that gap. You define the output shape upfront, and Claude conforms to it. Claude still explores pages, interprets errors, and judges severity, but you get a structured JSON object with known fields and value types. Your script reads `verdict` and branches.

`--output-format json` returns a JSON object with session metadata and the result. `--json-schema` forces Claude's response to conform to your schema, landing in a `structured_output` field.

1. Run Claude with a JSON schema to get a structured QA report:

    ```bash
    claude -p "Open https://www.otto.de using agent-browser cli.
    Take a snapshot to verify the page loads.
    Click one navigation link and take another snapshot.
    Check the console for JS errors.
    Return your findings as structured JSON." \
    --output-format json \
    --json-schema '{
      "type": "object",
      "properties": {
        "verdict": {
          "type": "string",
          "enum": ["HEALTHY", "MINOR_ISSUES", "CRITICAL_BUGS"]
        },
        "summary": { "type": "string" },
        "bugs": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "severity": { "type": "string", "enum": ["critical", "major", "minor"] },
              "title": { "type": "string" },
              "description": { "type": "string" }
            },
            "required": ["severity", "title", "description"]
          }
        }
      },
      "required": ["verdict", "summary", "bugs"]
    }' \
    --allowedTools "Bash(agent-browser*)"
    ```

    The full JSON response looks like this (trimmed for readability):

    ```json
    {
      "type": "result",
      "subtype": "success",
      "is_error": false,
      "duration_ms": 78276,
      "duration_api_ms": 71827,
      "num_turns": 13,
      "result": "**Results:**\n\n| Step | Result |\n|------|--------|\n| Open https://www.otto.de | Loaded — title: \"OTTO - Mode, Möbel & Technik » Zum Online-Shop\" |\n| Snapshot #1 (homepage) | Full navigation rendered |\n| Click \"Multimedia\" nav link | Navigated to /technik/multimedia/ |\n| Snapshot #2 (Multimedia page) | Page rendered with breadcrumb, category heading, and sub-navigation |\n| Console JS errors | **None detected** |\n\n**Verdict: HEALTHY**",
      "total_cost_usd": 0.32,
      "structured_output": {
        "verdict": "HEALTHY",
        "summary": "otto.de loads successfully with full navigation, promotional banners, and product content. Navigation to the Multimedia section (/technik/multimedia/) works correctly. No JavaScript console errors or failed resource loads were detected.",
        "bugs": []
      }
    }
    ```

    The `result` field contains Claude's free-text response. The `structured_output` field contains the validated JSON that conforms to your schema. You also get metadata like `duration_ms`, `num_turns`, and `total_cost_usd`.

2. Extract the structured output with `jq`:

    ```bash
    # Pipe the full output through jq to get just the structured data
    claude -p "..." --output-format json --json-schema '...' \
      --allowedTools "Bash(agent-browser*)" \
      | jq '.structured_output'
    ```

    Output:

    ```json
    {
      "verdict": "HEALTHY",
      "summary": "otto.de loads successfully with full navigation, promotional banners, and product content. Navigation to the Multimedia section (/technik/multimedia/) works correctly. No JavaScript console errors or failed resource loads were detected.",
      "bugs": []
    }
    ```

3. Use it in a script to make pass/fail decisions:

    ```bash
    VERDICT=$(claude -p "..." --output-format json --json-schema '...' \
      --allowedTools "Bash(agent-browser*)" \
      | jq -r '.structured_output.verdict')

    if [ "$VERDICT" = "CRITICAL_BUGS" ]; then
      echo "QA failed!"
      exit 1
    fi
    ```

    Inside `claude -p`, Claude explores the app, interprets what it sees, and judges severity. Outside, the `if` statement and `exit 1` are plain bash. `--json-schema` gives you a contract between the two. Without it, you'd grep Claude's prose for the word "CRITICAL" and hope it doesn't rephrase.

This same mechanism powers the GitHub Actions workflow in Part 2. Get it working locally first, fewer surprises in CI.

## Summary

You now have:

- Browser control from the terminal with Agent Browser's snapshot-and-ref model
- One-shot AI-powered exploration with `claude -p`
- Persona separation via `--append-system-prompt`, execution control via `--max-turns` and `--model`
- Structured JSON output with `--output-format json` and `--json-schema`

All of this runs locally. Part 2 moves it into CI: a GitHub Actions workflow using Claude Code Action that runs Claude as a QA agent on every PR, posts structured bug reports as comments, and sets commit statuses (green/yellow/red). Coming soon.

## Next steps

- <InternalLink slug="building_ai_qa_engineer_claude_code_playwright">Building an AI QA Engineer with Playwright MCP</InternalLink>, the MCP-based version with richer browser control
- <InternalLink slug="claude_code_skills_hooks_subagents_vue_workout_tracker">Claude Code Skills, Hooks, and Subagents</InternalLink>, creating reusable skills for your QA prompts
- <InternalLink slug="claude-code-customization-guide-claudemd-skills-subagents">Claude Code Customization Guide</InternalLink>, deeper coverage of CLAUDE.md, skills, and subagents
- [Agent Browser documentation](https://github.com/vercel-labs/agent-browser), full command reference and setup guide

---

--- title: How to Catch Hydration Errors in Playwright Tests (Astro, Nuxt, React SSR) description: A Playwright fixture that listens to the browser console for hydration mismatch warnings and fails your E2E tests when server and client HTML disagree. tags: ['testing', 'javascript', 'performance'] url: https://alexop.dev/posts/catch-hydration-errors-playwright-tests ---

# How to Catch Hydration Errors in Playwright Tests (Astro, Nuxt, React SSR)



Your E2E tests pass. The page loads, buttons work.

But open the browser console:

```text
Hydration failed because the server rendered HTML didn't match the client.
```

This is a hydration mismatch. The server sent one thing and the client replaced it with something else. The page still works, so you don't notice. Your tests don't check for it, so they pass.

## What are SSR and hydration?

**SSR (server-side rendering)** means the server generates HTML and sends it to the browser before JavaScript loads. Users see content before client code boots, and search engines can index it.

Astro and Nuxt build on this model.

**Hydration** is the next step: client JavaScript takes over the server-rendered HTML, attaching event handlers and state to the existing markup. The contract: the first client render must match what the server sent.

When it does not match, the framework discards the server HTML and re-renders on the client. That re-render is a hydration mismatch.

### Common causes

Anything that produces different HTML on client and server:

- Reading `localStorage` or `window.matchMedia()` during render
- Calling `new Date()` or `Math.random()` during render
- Formatting dates or numbers differently across server and client
- Rendering conditional branches based on browser-only state

Theme toggles and locale formatting cause most of them.

If you use Vue with SSR, the `window is not defined` error comes from the same root cause. VueUse has a pattern for it:

## A real bug I found

I was working on an Astro page and my theme hook was reading browser state during the first render:

```ts
function getInitialTheme(): Theme {
  const stored = localStorage.getItem(SITE.themeStorageKey);
  if (stored === "light" || stored === "dark") return stored;
  return window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
}

export function useTheme() {
  const [theme, setTheme] = useState<Theme>(getInitialTheme);
}
```

The server defaulted to `dark`, but the browser picked `light`. React saw the mismatch, logged a hydration warning, and re-rendered from scratch.

The page still worked, the button still existed. Normal E2E tests passed.

**The fix:** start with a deterministic value, resolve browser state after mount.

```ts
export function useTheme() {
  const [theme, setTheme] = useState<Theme>("dark");
  const [mounted, setMounted] = useState(false);

  useEffect(() => {
    const preferredTheme = getPreferredTheme();
    document.documentElement.classList.toggle("dark", preferredTheme === "dark");
    setTheme(preferredTheme);
    setMounted(true);
  }, []);

  useEffect(() => {
    if (!mounted) return;
    const root = document.documentElement;
    root.classList.toggle("dark", theme === "dark");
    localStorage.setItem(SITE.themeStorageKey, theme);
  }, [mounted, theme]);

  return { theme, setTheme, toggleTheme: () => setTheme((t) => (t === "dark" ? "light" : "dark")) };
}
```

## The core idea

**Listen to the browser console during a Playwright test. If a hydration warning appears, fail the test.**

React and Vue log hydration mismatches to the console. You don't check the console during automated tests, so this fixture does.

## The fixture

<Alert type="info" title="What are Playwright fixtures?">
Fixtures are Playwright's way of setting up and tearing down what each test needs. Built-in fixtures like `page` and `browser` come for free. You create custom ones with `base.extend()`. Each fixture runs when a test requests it and gets cleaned up afterward. The fixture below injects `hydrationErrors` and `runtimeErrors` into every test that asks for them.
</Alert>

I first saw this approach in the [npmx.dev](https://npmx.dev) open source project and adapted it for my Astro site. My version covers React and Vue hydration strings and catches uncaught runtime exceptions:

```ts
const HYDRATION_ERROR_PATTERNS = [
  /hydration failed because the server rendered html didn't match the client/i,
  /hydration completed but contains mismatches/i,
  /hydration text content mismatch/i,
  /hydration node mismatch/i,
  /hydration attribute mismatch/i,
];

function isHydrationError(text: string): boolean {
  return HYDRATION_ERROR_PATTERNS.some((pattern) => pattern.test(text));
}

function toConsoleText(message: ConsoleMessage): string {
  return message.text().trim();
}

export const test = base.extend<{
  hydrationErrors: string[];
  runtimeErrors: string[];
}>({
  hydrationErrors: async ({ page }, use) => {
    const hydrationErrors: string[] = [];

    const handleConsole = (message: ConsoleMessage) => {
      const text = toConsoleText(message);
      if (isHydrationError(text)) {
        hydrationErrors.push(text);
      }
    };

    page.on("console", handleConsole);
    await use(hydrationErrors);
    page.off("console", handleConsole);
  },

  runtimeErrors: async ({ page }, use) => {
    const runtimeErrors: string[] = [];

    const handleConsole = (message: ConsoleMessage) => {
      const text = toConsoleText(message);
      if (message.type() === "error" && text.length > 0 && !isHydrationError(text)) {
        runtimeErrors.push(text);
      }
    };

    const handlePageError = (error: Error) => {
      runtimeErrors.push(error.message);
    };

    page.on("console", handleConsole);
    page.on("pageerror", handlePageError);
    await use(runtimeErrors);
    page.off("console", handleConsole);
    page.off("pageerror", handlePageError);
  },
});

export { expect };
```

Drop this into `test/e2e/test-utils.ts` and import from there instead of `@playwright/test`.

Related: a full AI-driven QA workflow with Playwright:

## Using it

```ts
test("home page hydrates cleanly", async ({ page, hydrationErrors, runtimeErrors }) => {
  await page.goto("/", { waitUntil: "domcontentloaded" });
  await expect(page.getByRole("heading", { name: "Home" })).toBeVisible();

  expect(hydrationErrors).toEqual([]);
  expect(runtimeErrors).toEqual([]);
});
```

Start with your homepage. Add one interactive route, then one with a theme toggle or client-only widget. That surfaces most bugs.

## How npmx.dev does it at scale

The [npmx.dev](https://npmx.dev) project tests hydration correctness for every combination of user settings across every page, around 48 checks from a single fixture.

They inject `localStorage` values via Playwright's `page.addInitScript()` before navigation, simulating a returning user with saved preferences. Returning users with non-default settings trigger most hydration mismatches.

```ts
const PAGES = ["/", "/about", "/settings", "/compare", "/search", "/package/nuxt"];

test.describe("color mode: dark", () => {
  for (const page of PAGES) {
    test(`${page}`, async ({ page: pw, goto, hydrationErrors }) => {
      await injectLocalStorage(pw, { "npmx-color-mode": "dark" });
      await goto(page, { waitUntil: "hydration" });

      expect(hydrationErrors).toEqual([]);
    });
  }
});

async function injectLocalStorage(page: Page, entries: Record<string, string>) {
  await page.addInitScript((e: Record<string, string>) => {
    for (const [key, value] of Object.entries(e)) {
      localStorage.setItem(key, value);
    }
  }, entries);
}
```

They repeat this for every setting type, locale, accent color, background theme, package manager, relative dates, each with a non-default value. If any combination causes a hydration mismatch on any page, the test fails.

Their fixture uses Vue-specific error strings (`"Hydration completed but contains mismatches"`) while mine uses React patterns. The approach is the same, only the strings you match against change.

More on how E2E tests relate to unit and integration tests:

If you ship an SSR app and do not check for hydration errors in your browser tests, you have one in production right now.

---

--- title: App Screenshots: An AI Coding Agent Skill for Visual Documentation description: Automate annotated screenshot documentation for any web app or live website using an AI coding agent skill. Works with Claude Code, Cursor, Windsurf, or any agent that supports custom skills. tags: ['ai', 'coding-agents', 'tooling'] url: https://alexop.dev/posts/app-screenshots-claude-code-skill ---

# App Screenshots: An AI Coding Agent Skill for Visual Documentation



## TLDR

I built a [skill](https://github.com/alexanderop/app-screenshots) that takes annotated screenshots of any web app or live website and generates a markdown visual guide. It works with Claude Code, Cursor, Windsurf, or any AI coding agent that supports custom skills.

## What Is a Skill?

A skill is a markdown file with instructions for a coding agent. It describes how to perform a specific task and can reference CLI tools, APIs, or other resources. You write the steps in markdown, the agent follows them. A general-purpose coding agent with the right skill becomes a specialist, no code changes needed. For a deeper look at how skills fit into the broader ecosystem, see the <InternalLink slug="claude-code-customization-guide-claudemd-skills-subagents">guide to CLAUDE.md, skills, and subagents</InternalLink>.

## The Problem

Documenting UIs is tedious. You open the app, take a screenshot, annotate it in some tool, write descriptions, repeat for every page. Automate it.

## How It Works

The skill uses [`agent-browser`](https://github.com/vercel-labs/agent-browser), a headless browser automation CLI built by Vercel specifically for AI agents. Instead of heavy tools like Playwright, it provides a lightweight snapshot + refs system that lets agents navigate, click, and screenshot pages with minimal context usage. It works with Claude Code, Codex, Cursor, Gemini CLI, and more.

You point your coding agent at a local dev server or a public URL and it does the rest:

1. **Discovers pages** by reading the site's navigation
2. **Screenshots each page** with SVG annotations injected directly into the DOM
3. **Generates a markdown file** with numbered references to each annotation

Annotations come in three types: `box` for sections, `click` for interactive elements, and `circle` for general callouts. Each screenshot gets up to 3 annotations with auto-rotating colors. If you like auto-generated visual docs, the <InternalLink slug="building-walkthrough-skill-claude-code">walkthrough skill</InternalLink> does something similar for codebases with interactive Mermaid diagrams.

```markdown
## Homepage

The landing page shows a hero banner with seasonal promotions.
Use the **Search** bar (1) to find products.
The **Category navigation** (2) provides access to all departments.

![Homepage](screenshots/01-homepage.png)
```

## Live Sites Just Work

It handles cookie banners, lazy-loaded content, bot protection. You can document `otto.de`, `github.com`, or your own staging environment with the same command.

## Usage

Install the prerequisite:

```bash
npm install -g agent-browser && agent-browser install
```

Then tell your coding agent:

```
"Screenshot the app"
"Document otto.de with screenshots"
"Give me a visual guide of the checkout flow"
```

The skill figures out whether you mean a local dev server or a live URL and adapts accordingly.

## Source

GitHub: [github.com/alexanderop/app-screenshots](https://github.com/alexanderop/app-screenshots)

If you're building your own skill library, see how I built a skill for <InternalLink slug="building-conversation-search-skill-claude-code">searching Claude's conversation history</InternalLink>.

---

--- title: The Software Factory: Why Your Team Will Never Work the Same Again description: We already have everything we need to build software factories. Teams will change. The only variable is speed. tags: ['ai', 'software-engineering', 'teams', 'future', 'claude-code', 'software-factory'] url: https://alexop.dev/posts/the-software-factory ---

# The Software Factory: Why Your Team Will Never Work the Same Again



## Table of Contents

<TLDR items={[
  "AI coding agents like Claude Code already have everything needed to build software factories today",
  "Teams shrink from 12 specialists to 5 generalists, everyone becomes a builder with agents as their execution layer",
  "Skills (markdown files that teach agents new capabilities) are the key to scaling what your factory can do",
  "The best factories are self-improving: agents read user feedback, A/B tests, and error logs to automatically populate the backlog",
]} />

## We Already Have Everything We Need

<Figure
  src={heroImage}
  caption="The software factory: lobsters building software with AI agents"
  alt="Pixel art illustration of a lobster operating a software assembly line with AI agent lobsters"
  size="full"
/>

The current models and tooling are enough to build software factories. Today.

In a software factory, developers stop writing code by hand. AI coding agents implement features and fix bugs while developers design and improve the factory.

Or as Lee Edwards from Root Ventures [put it](https://sfstandard.com/2026/02/19/ai-writes-code-now-s-left-software-engineers/):

> "It's like giving them a nuclear-powered six-axis mill. It's a single-person software factory."

Anthropic ships the building blocks today:

- [Claude Code](https://code.claude.com/docs/en/overview) is an agentic coding tool that lives in your terminal, understands your codebase, and can write code, run tests, and open pull requests
- [Headless mode](https://code.claude.com/docs/en/headless) lets you run Claude Code programmatically in CI/CD pipelines, GitHub Actions, or any automation script
- [Scheduled tasks](https://code.claude.com/docs/en/scheduled-tasks) let agents run on a timer: daily code reviews, dependency checks, morning briefings
- [Subagents](https://code.claude.com/docs/en/sub-agents) are specialized agents you can create for specific tasks, each with their own tools and permissions
- [Agent teams](https://code.claude.com/docs/en/agent-teams) let you orchestrate multiple Claude Code sessions working in parallel on different parts of a problem
- [Skills](https://code.claude.com/docs/en/skills) extend what your agents can do with simple Markdown files
- The [Claude Agent SDK](https://platform.claude.com/docs/en/agent-sdk/overview) lets you build production multi-agent systems with orchestration, guardrails, and tracing
- [Claude on GitHub](https://github.blog/changelog/2026-02-04-claude-and-codex-are-now-available-in-public-preview-on-github/) lets Claude commit code and comment on PRs directly from GitHub

You delegate a ticket, review the output, and tighten the architecture. These pieces fit together:

<InternalLink slug="understanding-claude-code-full-stack">Understanding Claude Code's Full Stack: MCP, Skills, Subagents, and Hooks</InternalLink>

But first, how we used to work.

## How We Worked Before: Beer Commerce

<Figure
  src={oldWayImage}
  caption="The old way: endless meetings, handoffs, and two-week sprints"
  alt="Pixel art illustration of tired lobsters in suits at a conference table with a scrum board"
  size="full"
/>

Beer Commerce is a fictional company that sells craft beer online. Mid-size, multiple teams, microservices backend, microfrontend architecture.

One of their teams, the Checkout team, has 12 people:

- 5 developers (2 frontend, 2 backend, 1 full-stack)
- 1 product owner
- 1 scrum master
- 2 QA engineers
- 1 UX designer
- 1 business analyst
- 1 tech lead

They run two-week sprints. Here's what happens when a new feature comes in. Say, "Add a discount code field to the checkout page":

Business request → BA writes user story → PO refines and prioritizes → sprint planning (2-4 hrs) → UX designs mockups (2-3 days) → dev picks up ticket (day 3-4) → dev writes code (2-3 days) → code review (1-2 days) → QA testing (1-2 days) → deployed (day 10-14).

Business request to production: **10 to 14 days**. That's the happy path, with no blocked dependencies and no sick days. Many features eat an entire sprint or spill into the next one.

**Handoffs** are the bottleneck. The BA hands off to the PO. The PO hands off to the dev. The dev hands off to QA. Each handoff adds waiting time and context loss. The coding itself takes maybe 2 to 3 days out of a 14-day cycle.

Most of the industry still works this way.

## Enter the Software Factory

<Figure
  src={newWayImage}
  caption="The new way: delegate to agents, review the output, ship"
  alt="Pixel art illustration of a relaxed lobster monitoring screens while agent lobsters work on an assembly line"
  size="full"
/>

Claude Code runs as a scheduled agent in the cloud. You give it a task and it works on its own: reading the codebase, writing code, running tests, opening PRs. This is a production workflow.

In a software factory, **each team member is a product builder**. The UX designer who gets a customer complaint can write a spec, hand it to an agent, and babysit the implementation. The business analyst who spots a conversion drop can describe the fix, kick off an agent, and watch it ship. If you understand the problem, you can drive the solution.

The workflow:

Business request → builder writes spec (30 min) → agent picks up ticket → agent writes frontend + backend + tests in parallel → agent runs full test suite and lint → builder reviews PR (1-2 hrs) → deployed (same day).

A designer, PM, or domain expert can write that spec. A good spec goes in, working software comes out.

Business request to production: **hours, not weeks**.

The builder writes a good spec, delegates to the agent, and reviews the output.

<Figure
  src={gasTownImage}
  caption="Gas Town: a Mayor orchestrating 20-30 Polecats through a Refinery merge queue"
  alt="Pixel art illustration of a factory town with a Mayor lobster coordinating many agent lobsters working on parallel git branches merging through a refinery"
  size="full"
/>

Steve Yegge built this for real with [Gas Town](https://github.com/steveyegge/gastown). He calls it ["Kubernetes for AI coding agents"](https://cloudnativenow.com/features/gas-town-what-kubernetes-for-ai-coding-agents-actually-looks-like/), and the comparison is architecturally accurate. You talk to the "Mayor" (the factory foreman), and it coordinates 20 to 30 parallel coding agents called "Polecats" that each work on feature branches. A "Refinery" manages the merge queue so parallel work doesn't collide. Git persists everything. If the system crashes, it reads the history and resumes.

Stripe built the same thing at enterprise scale. They call their agents [Minions](https://stripe.dev/blog/minions-stripes-one-shot-end-to-end-coding-agents): one-shot coding agents that merge over 1,300 pull requests per week. A task starts in a Slack message and ends in a pull request that passes CI, ready for human review, with no interaction in between.

Before the LLM even runs, a deterministic orchestrator prefetches context. It scans threads for links, pulls tickets, and searches code via MCP. Each Minion gets its own isolated devbox. Same machines human engineers use. Spins up in 10 seconds.

They built [Toolshed](https://stripe.dev/blog/minions-stripes-one-shot-end-to-end-coding-agents-part-2), an internal MCP server with nearly 500 tools. The orchestrator curates a subset per task. The agent starts focused, not drowning.

The architecture uses what Stripe calls **blueprints**: hybrid systems that combine deterministic code nodes (run linters, push changes) with agentic subtasks (implement feature, fix CI failures). This is the factory pattern: you don't give the agent full autonomy and hope for the best. You build a pipeline with guardrails.

Linters run in under a second before the first push. If CI fails, the Minion gets one more attempt to fix it. After that, humans take over. Two CI rounds max, then ship or hand off.

Why did Stripe build this in-house? Hundreds of millions of lines of Ruby, Sorbet types, and proprietary libraries no public model has seen. Generic agents couldn't navigate it. Stripe's insight: "If a tool is good for human engineers, it's good for LLMs." Every investment in developer tooling, documentation, devboxes, and CI directly improved agent performance. The factory runs on the same infrastructure humans use.

Boris Cherny, the creator of Claude Code, [said](https://sfstandard.com/2026/02/19/ai-writes-code-now-s-left-software-engineers/):

> "We're going to start to see the title of software engineer go away. It's just going to be 'builder' or 'product manager.'"

Anthropic [describes the shift](https://claude.com/blog/eight-trends-defining-how-software-gets-built-in-2026) as: "Engineers are shifting from writing code to coordinating agents that write code, focusing their own expertise on architecture, system design, and strategic decisions."

The job:

- Writing clear specs that agents can execute on
- Reviewing pull requests from agents
- Improving the architecture so agents can work more effectively
- Tightening testing and CI/CD pipelines
- Monitoring the factory's output quality

You spend less time on boilerplate and more on architecture and deciding what to build. I explored this shift in detail here:

<InternalLink slug="spec-driven-development-claude-code-in-action">Spec-Driven Development with Claude Code in Action</InternalLink>

## What Are Skills?

<Figure
  src={skillsImage}
  caption="Skills turn a general-purpose AI into a specialized factory worker"
  alt="Pixel art illustration of a lobster reaching for glowing skill badges on a workshop wall"
  size="full"
/>

A factory is only as good as its tooling. For AI coding agents, that tooling is **skills**.

As Simon Willison [explains](https://simonwillison.net/2025/Oct/16/claude-skills/), a skill is "a Markdown file telling the model how to do something, optionally accompanied by extra documents and pre-written scripts." He predicts "a Cambrian explosion in Skills which will make this year's MCP rush look pedestrian."

Some examples:

- **Cloud debug skill** (the agent can SSH into production, read logs, find the root cause of an incident, and propose a fix)
- **Database migration skill** (it understands your ORM, generates migrations, and knows how to handle rollbacks)
- **Design-to-code skill** (it takes a Figma design and translates it into frontend components)
- **Monitoring skill** (it reads Grafana dashboards, interprets metrics, and creates alerts)
- **Security audit skill** (it scans for OWASP vulnerabilities and fixes them)

You add skills, and your agents handle more types of work without you. They debug production issues, handle incidents, set up infrastructure.

Building and maintaining these skills is the highest-leverage engineering task. You're programming the factory. I've written about this hands-on:

<InternalLink slug="claude-code-slash-commands-guide">How to Speed Up Your Claude Code Experience with Slash Commands</InternalLink>

## The New Team: Everyone Is a Builder

<Figure
  src={smallBetterImage}
  caption="From 12 specialists to 5 builders. Everyone ships."
  alt="Pixel art split comparison of a crowded team versus a small team of builders with agent helpers"
  size="full"
/>

If AI agents handle the implementation, you don't need 12 people on the Checkout team. You need 5, maybe fewer.

Elad Gil [called it](https://anshadameenza.com/blog/technology/ai-small-teams-software-development-revolution/) "the dirty secret of 2024: the actual engineering team size needed for most software products has collapsed by 5-10x." Gergely Orosz from The Pragmatic Engineer [writes](https://newsletter.pragmaticengineer.com/p/the-future-of-software-engineering-with-ai) that "we are already seeing the end of two-pizza teams (6-10 people) thanks to AI." Andres Max [goes further](https://andresmax.com/large-software-teams-ai-age/): "A 5-person team in 2026 can ship what a 50-person team shipped in 2016."

**Fixed roles dissolve.**

Good early-stage startups have no "frontend developers" or "QA engineers." They have builders. The designer writes code. The engineer talks to customers. The PM debugs production.

The software factory brings that to companies of any size. Agents handle the implementation, and people become builders with agents as their execution layer.

Your expertise still matters. Someone who spent ten years doing UX research asks better questions about user flows. Someone with deep backend experience makes better architectural decisions. Expertise becomes a **superpower, not a job boundary**. The UX expert can act on their insights by instructing an agent to build a prototype, instead of writing a ticket and waiting two weeks.

AKF Partners [describe a similar model](https://akfpartners.com/growth-blog/engineering-team-sizes-are-evolving-rapidly-with-agentic-AI-platforms-the-limits-challenges-and-principles-we-must-consider): "A team of 2 or 3 humans, a lead developer, a product manager, and a designer, could leverage AI agents to cover coding, testing, deployment, and analytics."

The data backs this up. According to the [DX Q4 Impact Report](https://getdx.com/blog/ai-assisted-engineering-q4-impact-report-2025/), roughly 60% of non-engineers like managers, designers, and PMs now use AI to contribute code daily.

The gap between "the person who knows what to build" and "the person who can build it" is closing. Your ideas and judgment matter. Your job title doesn't.

## The Self-Improving Factory

<Figure
  src={selfImprovingImage}
  caption="The self-improving loop: observe, decide, build, ship, repeat"
  alt="Pixel art illustration of lobster agents in a circular feedback loop reading data and creating tickets"
  size="full"
/>

The factory can also figure out what to build next.

Your product generates signals: user feedback in support tickets, behavior data from analytics, A/B test results, error logs. Right now, a human reads all of that, synthesizes it, and turns it into tickets. That takes time and drops context.

In a software factory, agents do this on their own:

- An agent monitors user feedback channels, clusters recurring complaints, and creates backlog items with context
- An agent reads A/B test results, identifies winning variants, and proposes follow-up experiments
- An agent watches error rates in production, detects patterns, and creates bug tickets before anyone files a report
- An agent analyzes usage data, spots features that users struggle with, and suggests UX improvements

The product owner no longer curates a static list once a week. Ideas stream in ranked by impact, updated as data arrives.

Tools like [Linear](https://linear.app) are building toward this. They call their model a triad: **humans decide and remain accountable, agents execute within defined scopes, the platform manages interactions and visibility**. Issues can only be *assigned* to humans, but *delegated* to agents. As they [put it](https://linear.app/now/our-approach-to-building-the-agent-interaction-sdk): "An agent cannot be held accountable." The platform becomes the orchestration layer where humans and agents interact.

Combined with their [Cursor integration](https://linear.app/now/how-cursor-integrated-with-linear-for-agents), the picture becomes clear: "Starting an issue used to mean manually creating a feature branch. Now it means assembling the right context so your coding agent can take a first pass." Linear provides the product and customer context, the coding agent provides the codebase expertise, and the human provides judgment. That's the factory's coordination layer.

Because the factory can also implement those ideas, you get a closed loop: **observe, decide, build, ship, observe again**. You use the factory to improve the product, and you read the product's data to improve the factory.

Andrej Karpathy pushes this to its extreme with [autoresearch](https://github.com/karpathy/autoresearch). AI agents run ML experiments overnight on a single GPU. Humans write a `program.md` (a high-level spec) instead of training code, and agents iterate through experiments. Each run takes 5 minutes, producing about 12 experiments per hour, all optimizing toward a single metric. As Karpathy puts it: "Research is now entirely the domain of autonomous swarms of AI agents running across compute cluster megastructures."

The same pattern applies to product development. Replace "training runs" with "feature experiments" and "val_bpb" with "conversion rate." Your factory runs experiments, measures outcomes, and feeds the results back into the next cycle.

Anthropic supports [scheduled tasks](https://code.claude.com/docs/en/scheduled-tasks) that let agents run on a timer. Set up a daily agent that reads your support inbox, one that checks your analytics dashboard, one that reviews your error logs. Your team reviews what they find, prioritizes, and lets the factory execute.

For a deeper look at how agent teams work in practice:

<InternalLink slug="7-agent-team-patterns-for-claude-code">7 Agent Team Patterns for Claude Code</InternalLink>

## The Factory Is the Product

In a software factory, the software you ship is one product. **The factory is another.**

Skills you build, pipelines you improve, architectural decisions that make your codebase more agent-friendly: these compound. A team that spends a week improving their testing infrastructure ships future features faster. A team that builds a cloud debugging skill lets an agent resolve future incidents.

<Figure
  src={checkImage}
  caption="Backpressure: automated feedback that keeps agents on track"
  alt="Pixel art illustration of a lobster at a quality control station inspecting code blocks on a conveyor belt with green checkmarks and red X screens"
  size="full"
/>

Moss calls this [backpressure](https://banay.me/dont-waste-your-backpressure/): the automated feedback that keeps agents on track. Type checkers, linters, test suites, build systems. If an agent misses an import, the build fails and the agent fixes it. You don't spend your time pointing out syntax errors. Without backpressure, you're stuck reviewing trivial mistakes. With it, agents self-correct and you focus on architecture and product decisions. Investing in backpressure is investing in your factory's throughput.

The teams that build the best factories will ship the best products.

## This Is Happening Now

<Figure
  src={callToActionImage}
  caption="Are you going to build a factory?"
  alt="Pixel art illustration of a lobster standing at the entrance of a glowing software factory"
  size="full"
/>

Claude Code runs in the cloud. You can schedule agents and build skills. Early adopters are doing this now.

As Andres Max [put it](https://andresmax.com/large-software-teams-ai-age/): "Engineers who only wrote boilerplate are at risk. Engineers who make good decisions, architect systems, and understand users are more valuable than ever."

Are you going to build a factory, or keep doing two-week sprints while your competitors ship in hours?

<InternalLink slug="developers-wont-write-code-by-hand">In Five Years, Developers Won't Write Code By Hand</InternalLink>

## Conclusion

- The tools for building software factories exist **right now**: Claude Code, headless mode, scheduled tasks, skills, agent teams
- Stripe's Minions prove the model works at scale: 1,300+ PRs merged per week, fully agent-written, human-reviewed
- 12-person teams running two-week sprints give way to small groups of generalists who all build
- Skills turn general-purpose agents into specialized factory workers, and that specialization is your competitive edge
- Self-improving factories use agents to read user feedback, A/B tests, and production data, then populate the backlog without human curation
- The factory is a product. Investments in tooling, testing, and architecture compound
- The role of "software engineer" shifts toward "factory builder": less boilerplate, more architecture, judgment, and deciding what to build next

---

--- title: Building a Real-Time Todo App with Jazz and Vue 3 description: Build a real-time, offline-capable todo app with Jazz and Vue 3. Learn CoValues, drag-and-drop with fractional indexing, and shareable URLs. No backend needed. tags: ['vue', 'local-first', 'javascript', 'architecture'] url: https://alexop.dev/posts/building-real-time-todo-app-jazz-vue ---

# Building a Real-Time Todo App with Jazz and Vue 3



## TLDR

Build a real-time, offline-capable todo app with Jazz and Vue 3. Jazz replaces your entire backend with collaborative data structures called CoValues. Combined with `community-jazz-vue`, you get composables like `useCoState` that plug into Vue's reactivity system. The app syncs across tabs and devices, supports drag-and-drop with fractional indexing, and generates shareable URLs.

## Why Jazz Replaces Your Entire Backend

You want real-time collaboration, offline support, and shareable URLs. In a traditional stack, that means building a sync server, a conflict resolution strategy, a permissions layer, and an API. Jazz collapses all of that into collaborative data structures called CoValues.

Vue's `ref` keeps the virtual DOM in sync with the real DOM. CoValues extend that idea: they sync your data across devices and users, across network boundaries. You mutate data locally. Jazz handles the rest.

This post builds a complete Vue 3 app on top of Jazz. You can find the official Jazz documentation at [jazz.tools](https://jazz.tools/).

Combined with `community-jazz-vue`, a community-maintained Vue binding, you get composables like `useCoState` and a provider component that plug into Vue's reactivity system.

If you're new to local-first, start with the first post in this series:

For comparison, the same app built with Dexie.js and IndexedDB:

Anselm Eickhoff, the creator of Jazz, gave a workshop on local-first at VueConf 2025 where he live-coded with Jazz:

## Your First CoValue: A Synced Counter

Vue's `ref` keeps the virtual DOM in sync with the real DOM. You update a `ref`, Vue re-renders. That's reactive state within one browser tab. Jazz's `useCoState` extends that across devices, users, and network boundaries. You mutate locally, Jazz propagates the change to every connected peer.

The simplest CoValue is a single field:

```ts
const Counter = co.map({ count: z.number() });
```

That's one line of schema. Now subscribe to it in a Vue component:

```vue
<script setup lang="ts">
// Create a counter and grab its ID
const counterId = ref<string | undefined>();
const newCounter = Counter.create({ count: 0 });
counterId.value = newCounter.$jazz.id;

// Subscribe — returns a reactive ref that updates on local and remote changes
const counter = useCoState(Counter, counterId);

function increment() {
  if (counter.value?.$isLoaded) {
    counter.value.$jazz.set("count", (counter.value.count ?? 0) + 1);
  }
}

function decrement() {
  if (counter.value?.$isLoaded) {
    counter.value.$jazz.set("count", Math.max(0, (counter.value.count ?? 0) - 1));
  }
}
</script>

<template>
  <div v-if="!counter?.$isLoaded">Loading...</div>
  <div v-else>
    <p>{{ counter.count }}</p>
    <button @click="decrement">−</button>
    <button @click="increment">+</button>
  </div>
</template>
```

1. `Counter.create({ count: 0 })` creates a new CoValue instance and persists it locally.
2. `useCoState(Counter, counterId)` subscribes to that CoValue. It returns a reactive `Ref` that starts unloaded, populates once available, and re-renders on every change. Same as Vue's `ref`, but across the network.
3. `$jazz.set("count", ...)` mutates the CoValue. No API call, no action dispatch. Jazz syncs the change to all connected peers.

This works for a single user. But there's a problem: **by default, CoValues are private**. Only the creator can read or write them. If you shared this counter's ID with another user, they'd get nothing. The CoValue is invisible to them.

### Making It Shareable with Groups

To let others access the counter, you need a **Group**. Groups are how Jazz controls who gets access and what they can do. Every CoValue has an owner: either an Account (private) or a Group (shared).

```ts
const group = Group.create();
group.addMember("everyone", "writer");
const newCounter = Counter.create({ count: 0 }, { owner: group });
```

That's three lines. `Group.create()` makes a new permission group. `addMember("everyone", "writer")` grants public write access. The `"everyone"` keyword is a special shorthand that includes all users, even anonymous guests. Passing `{ owner: group }` to `Counter.create` assigns the counter to that group instead of the default private account.

Now anyone who knows the CoValue ID can read and write the same counter. No API keys, no auth server. Sharing the ID is all it takes.

Try it. Click the + button in one panel and watch the count update in the other. Both panels are independent Jazz clients syncing via Jazz Cloud:

<Aside type="info">
The `"everyone"` + `"writer"` combination is permissive, great for demos and public collaboration. For real apps, Jazz supports granular roles (`reader`, `writer`, `admin`) and per-user membership. We'll use the same pattern for the todo app below.
</Aside>

That's the entire model: define your data with `co.map`, subscribe with `useCoState`, mutate. But we glossed over something important. How does Jazz decide who can access a CoValue, and what stops someone from escalating their own permissions?

## How Jazz Permissions Work

The counter example used `addMember("everyone", "writer")` to make data publicly accessible.

Jazz defines a role hierarchy where each role includes the permissions of the roles below it:

When we create a Group and grant public write access, the permission structure looks like this:

So what stops a malicious user from upgrading their own role from `writer` to `admin`? Jazz enforces permissions cryptographically, in the data itself.

Every change to a CoValue is signed with the author's private key (Ed25519). When a peer receives a transaction, it verifies the signature and checks whether that account had permission to make that change. A writer trying to modify Group roles? The signature is valid, but the Group's internal rules reject it. Only admins can change roles. The transaction gets discarded.

The Jazz Cloud sync server can't tamper with your data. It relays signed transactions. If the server modified anything, the signatures wouldn't match and peers would reject it. Jazz also encrypts data with a shared read key (XSalsa20), so the server can't read what it's relaying.

<Aside type="note">
For more complex apps, Jazz supports granular permissions on nested CoValues. Each nested CoValue can have its own Group with different roles. A project board where managers can edit columns but clients can only read specific tasks. Groups can also be members of other groups, enabling cascading permission hierarchies.
</Aside>

Now for something more ambitious.

## What We're Building: A Real-Time Vue 3 Todo App

A todo list app that:

- Syncs in real-time across tabs and devices via Jazz Cloud
- Works offline with a toggle to simulate going on/off the network
- Supports drag-and-drop reordering via `useSortable`
- Shows a dynamic page title with the count of incomplete todos
- Generates a shareable URL so anyone with the link sees the same list
- Includes the Jazz Inspector for debugging CoValues in development

Try it out. Both todo apps below are independent Jazz clients, each running as a Vue component embedded in this page. Add a todo in one and watch it sync to the other via Jazz Cloud:

<Aside type="info">
Click the Jazz icon in the bottom-right corner to open the Jazz Inspector. You can copy any `co_z...` CoValue ID shown in the app UI, paste it into the inspector, and hit "Inspect CoValue" to see the raw data inside: its fields, current values, and sync status.
</Aside>

The high-level architecture:

```mermaid
flowchart LR
    subgraph BrowserA["Browser A (Tab 1)"]
        AppA["Vue App"] --> IDB_A["Local IndexedDB"]
    end

    subgraph Cloud["Jazz Cloud"]
        Sync["Sync Server"]
        Store["Persistent Store"]
        Sync <--> Store
    end

    subgraph BrowserB["Browser B (Tab 2)"]
        AppB["Vue App"] --> IDB_B["Local IndexedDB"]
    end

    IDB_A <-->|WebSocket| Sync
    IDB_B <-->|WebSocket| Sync
```

We'll build it step by step.

## Project Setup

You'll need Node.js v20+ and a package manager (we'll use pnpm, but npm/yarn work too).

Start with a fresh Vue project (select TypeScript when prompted) and install the dependencies:

```bash
npm create vue@latest vue-jazz-todo
cd vue-jazz-todo

pnpm add jazz-tools community-jazz-vue @vueuse/core @vueuse/integrations sortablejs fractional-indexing tailwindcss @tailwindcss/vite
pnpm add -D @types/sortablejs vite-plugin-vue-devtools
```

Here's the project structure we'll end up with:

<FileTree
  tree={[
    {
      name: "vue-jazz-todo",
      open: true,
      children: [
        {
          name: "src",
          open: true,
          children: [
            { name: "main.ts", comment: "App entry point" },
            { name: "App.vue", comment: "JazzVueProvider wrapper" },
            { name: "TodoApp.vue", comment: "Main todo UI" },
            { name: "schema.ts", comment: "Jazz CoValue definitions" },
            {
              name: "assets",
              open: true,
              children: [
                { name: "main.css", comment: "Tailwind CSS import" },
              ],
            },
          ],
        },
        { name: "vite.config.ts", comment: "Build config" },
        { name: "index.html", comment: "HTML shell" },
        { name: "package.json" },
      ],
    },
  ]}
/>

## Defining the Schema

Jazz uses Collaborative Values (CoValues) as its building blocks: reactive, synced data structures. If you've used Zod before, the schema API will feel familiar. Create `src/schema.ts`:

```ts
export const ToDo = co.map({ title: z.string(), completed: z.boolean(), order: z.string() });
export const ToDoList = co.list(ToDo);
```

Two lines. `co.map` defines a collaborative object with typed fields, `co.list` defines an ordered list. The `order` field stores a fractional index string for drag-and-drop (more on that in the reordering section). Jazz handles sync, persistence, and conflict resolution for you.

<Aside type="note">
Jazz's CoValues are built on [CRDTs](https://jakelazaroff.com/words/an-interactive-intro-to-crdts/) (Conflict-free Replicated Data Types). Unlike Dexie.js where the server handles conflicts, Jazz bakes conflict resolution into the data structures. You never have to think about it.
</Aside>

In practice, a `CoMap` tracks every change from every device. When Alice sets `completed: false` at 8:05 AM and Bob sets `completed: true` at 8:03 AM, the later timestamp wins. Step through the timeline to see how the resolved state changes as transactions arrive:

## Entry Point and Build Configuration

The entry point is standard Vue. Update `src/main.ts`:

```ts
import "./assets/main.css";

createApp(App).mount("#app");
```

For Tailwind CSS v4, replace `src/assets/main.css` with a single import, no `tailwind.config.js` needed:

```css
@import "tailwindcss";
```

We also need to tell Vue about the Jazz Inspector custom element so Vue doesn't try to resolve it as a component. Update `vite.config.ts`:

```ts
export default defineConfig({
  plugins: [
    vue({
      template: {
        compilerOptions: {
          isCustomElement: (tag) => tag === 'jazz-inspector',
        },
      },
    }),
    vueDevTools(),
    tailwindcss(),
  ],
  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url))
    },
  },
})
```

The `isCustomElement` line matters because Jazz ships with a built-in inspector for browsing and debugging CoValues at runtime. It appears as a floating panel where you can click into any CoValue to see its current state, history, and sync status. Since the inspector is a Web Component (`<jazz-inspector />`), you need to tell Vue not to resolve it as a Vue component.

## Setting Up the Jazz Provider

Instead of manually creating a context manager, we use the `JazzVueProvider` component from `community-jazz-vue`. It handles context creation, cleanup, and provides Jazz to all child components via Vue's dependency injection.

Create `src/App.vue`:

```vue
<script setup lang="ts">
import "jazz-tools/inspector/register-custom-element";
const isOnline = ref(true);
const syncConfig = computed(() => ({
  peer: "wss://cloud.jazz.tools/?key=vue-jazz-todo-example" as const,
  when: isOnline.value ? ("always" as const) : ("never" as const),
}));
</script>

<template>
  <JazzVueProvider :sync="syncConfig">
    
    <jazz-inspector />
  </JazzVueProvider>
</template>
```

Two things worth understanding about this setup:

- `JazzVueProvider` wraps the entire app and takes a `sync` prop. It only renders children once the Jazz context is ready, so downstream components can safely assume Jazz is available. The sync config is reactive: the `computed` derives the config from `isOnline`. When the user toggles the switch, `when` flips between `"always"` and `"never"`, and Jazz switches between syncing and offline mode.
- `import "jazz-tools/inspector/register-custom-element"` registers the `<jazz-inspector>` Web Component as a side-effect import. The `isOnline` state lives here and is passed down via `v-model:is-online`, keeping the sync config and toggle UI separated.

## Building the Todo App

Now for the main component. Create `src/TodoApp.vue` and we'll build it piece by piece.

### Imports and Setup

```ts
const isOnline = defineModel<boolean>("isOnline", { required: true });
const newTitle = ref("");
const { copy, copied } = useClipboard({ copiedDuring: 2000 });
```

We receive `isOnline` from the parent via `defineModel` and set up a ref for the input field plus VueUse's clipboard composable for the "Copy link" button.

### Routing via URL

```ts
const params = useUrlSearchParams("history");
const listId = ref<string | undefined>(params.id as string | undefined);

if (!listId.value) {
  const group = Group.create();
  group.addMember("everyone", "writer");
  const newList = ToDoList.create([], { owner: group });
  listId.value = newList.$jazz.id;
  params.id = newList.$jazz.id;
}
```

We use VueUse's `useUrlSearchParams("history")` instead of raw `URLSearchParams`. The `"history"` mode uses the History API (no page reload) and gives us a reactive object. If the URL has an `?id=` parameter, we subscribe to that existing list. Otherwise, we create a new list owned by a Group with public write access (the same pattern from the permissions section) so anyone with the link can read and write.

### Subscribing to the List

```ts
const todoList = useCoState(ToDoList, listId, {
  resolve: { $each: true },
});

const todos = computed(() => {
  const list = todoList.value;
  if (!list?.$isLoaded) return [];
  return [...list].sort((a, b) => (a.order < b.order ? -1 : a.order > b.order ? 1 : 0));
});
```

`useCoState` is the core composable from `community-jazz-vue`. It takes a CoValue schema, an ID (which can be a ref), and a resolve query. It returns a Vue `Ref` that starts as unloaded, populates once available, and re-renders on both local and remote changes.

The `resolve: { $each: true }` tells Jazz to deeply load each item in the list. Without it, you'd get the list but each ToDo entry would be an unresolved reference. Items are sorted by their `order` field rather than their position in the CoList.

If you're interested in how Vue composables like this are designed, I wrote about the patterns here:

<InternalLink slug="vueuse_composables_style_guide">Vue Composables Style Guide: Lessons from VueUse's Codebase</InternalLink>

### Dynamic Page Title

```ts
const pageTitle = useTitle("To Do");
watchEffect(() => {
  const count = todos.value.filter((t) => !t.completed).length;
  pageTitle.value = count > 0 ? `(${count}) To Do` : "To Do";
});
```

A small UX touch: the browser tab shows "(3) To Do" when there are 3 incomplete items.

### CRUD Operations

```ts
const inputEl = useTemplateRef<HTMLInputElement>("inputEl");
const { focused: inputFocused } = useFocus(inputEl);

function addTodo() {
  const list = todoList.value;
  const title = newTitle.value.trim();
  if (!title || !list?.$isLoaded) return;
  const sorted = todos.value;
  const lastOrder = sorted.length > 0 ? sorted[sorted.length - 1]!.order : null;
  const order = generateKeyBetween(lastOrder, null);
  list.$jazz.push({ title, completed: false, order });
  newTitle.value = "";
  inputFocused.value = true;
}

function toggleTodo(todo: co.loaded<typeof ToDo>) {
  todo.$jazz.set("completed", !todo.completed);
}

function deleteTodo(todo: co.loaded<typeof ToDo>) {
  const list = todoList.value;
  if (!list?.$isLoaded) return;
  const listIndex = [...list].findIndex((t) => t.$jazz.id === todo.$jazz.id);
  if (listIndex !== -1) list.$jazz.remove(listIndex);
}

const copyLink = () => copy(window.location.href);
```

Every loaded CoValue exposes a `$jazz` accessor for mutations: `$jazz.push()`, `$jazz.set()`, `$jazz.remove()`. These mutations apply locally and sync to all connected peers. No "save" button, no API call.

`addTodo` generates a fractional index via `generateKeyBetween(lastOrder, null)`, which creates a key that sorts after all existing items. `deleteTodo` finds the item by its CoValue ID instead of relying on the array index, since our `todos` computed is sorted by `order` and the display index won't match the `CoList` position.

### The Sync Lifecycle

The lifecycle of a mutation like `list.$jazz.push(...)`:

```mermaid
flowchart LR
    A["list.$jazz.push(...)"] --> B["Local IndexedDB"]
    B --> C["Vue re-renders via shallowRef"]
    B --> D["Jazz Cloud Sync Server"]
    D --> E["Other Browsers"]
    E --> F["useCoState() triggers update"]
    F --> G["Vue re-renders"]
```

The mutation returns before the sync starts. Your UI updates first. When the data reaches other peers, their `useCoState` subscriptions fire and Vue re-renders on their end too.

## The TodoApp.vue Template

The complete template ties together the add form, sortable list, online toggle, and shareable link:

```vue
<template>
  <div class="min-h-screen bg-gray-950 flex items-start justify-center pt-16 px-4">
    <div class="w-full max-w-md">
      <!-- Header with online toggle -->
      <div class="flex items-center justify-between mb-8">
        <div class="flex items-center gap-2">
          <svg class="w-7 h-7 text-blue-500" viewBox="0 0 24 24" fill="currentColor">
            
          </svg>
          <span class="text-white text-xl font-semibold tracking-tight">jazz</span>
        </div>
        <div class="flex items-center gap-2">
          <span class="text-gray-300 text-sm">Online</span>
          <button
            @click="isOnline = !isOnline"
            :class="[
              'relative inline-flex h-6 w-11 items-center rounded-full transition-colors',
              isOnline ? 'bg-blue-600' : 'bg-gray-600',
            ]"
          >
            <span
              :class="[
                'inline-block h-4 w-4 rounded-full bg-white transition-transform',
                isOnline ? 'translate-x-6' : 'translate-x-1',
              ]"
            />
          </button>
        </div>
      </div>

      <!-- Card -->
      <div class="bg-gray-900 border border-gray-700 rounded-xl p-6">
        <h1 class="text-3xl font-bold text-white mb-6">To Do</h1>

        <div v-if="!todoList?.$isLoaded" class="text-gray-400 text-center py-8">
          Loading...
        </div>

        <template v-else>
          <form @submit.prevent="addTodo" class="mb-6 space-y-3">
            <input
              ref="inputEl"
              v-model="newTitle"
              placeholder="New task"
              class="w-full px-3 py-2 bg-gray-800 border border-gray-600 rounded-lg text-white placeholder-gray-500 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-transparent"
            />
            <button
              type="submit"
              class="w-full px-4 py-2 bg-blue-600 text-white rounded-lg hover:bg-blue-700 transition-colors font-medium"
            >
              Add
            </button>
          </form>

          <ul ref="todoListEl" class="space-y-2">
            <li
              v-for="(todo, index) in todos"
              :key="todo.$jazz.id"
              class="group flex items-center gap-3 p-2 rounded-lg hover:bg-gray-800"
            >
              <span
                class="drag-handle cursor-grab active:cursor-grabbing text-gray-600 group-hover:text-gray-400 transition-colors select-none"
                title="Drag to reorder"
              >
                <svg class="w-4 h-4" viewBox="0 0 24 24" fill="currentColor">

                </svg>
              </span>
              <input
                type="checkbox"
                :checked="todo.completed"
                @change="toggleTodo(todo)"
                class="h-4 w-4 rounded border-gray-600 bg-gray-800 text-blue-600 focus:ring-blue-500 focus:ring-offset-gray-900"
              />
              <span
                class="flex-1"
                :class="todo.completed ? 'line-through text-gray-500' : 'text-gray-200'"
              >
                {{ todo.title }}
              </span>
              <button
                @click="deleteTodo(todo)"
                class="opacity-0 group-hover:opacity-100 transition-opacity text-gray-500 hover:text-red-400 p-1"
                title="Delete"
              >
                <svg class="w-4 h-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
                  
                </svg>
              </button>
            </li>
          </ul>

          <p v-if="todos.length === 0" class="text-gray-500 text-center py-4">
            No todos yet. Add one above!
          </p>

          <div v-if="listId" class="mt-6 flex items-center gap-2">
            <p class="text-xs text-gray-500 break-all flex-1">
              List ID: {{ listId }}
            </p>
            <button
              @click="copyLink"
              class="shrink-0 px-3 py-1 text-xs rounded-md border transition-colors"
              :class="copied
                ? 'border-green-600 text-green-400'
                : 'border-gray-600 text-gray-400 hover:text-gray-200 hover:border-gray-500'"
            >
              {{ copied ? "Copied!" : "Copy link" }}
            </button>
          </div>
        </template>
      </div>
    </div>
  </div>
</template>
```

In the template, `:key="todo.$jazz.id"` gives Vue a stable, globally unique key for each item. The `ref="inputEl"` connects to `useFocus` so the input regains focus after adding a todo. `@change="toggleTodo(todo)"` shows how clean mutations are: no actions, no dispatching, no reducers.

## Drag-and-Drop Reordering

We use [`useSortable`](https://vueuse.org/integrations/useSortable/) from VueUse for drag-and-drop. The simplest approach would be to call `splice` on the `CoList`: remove the item from its old position, insert it at the new one. For a single user, that works fine.

### The Problem with `splice`

Jazz's `CoList` implements `splice` as a delete-plus-insert, not as an atomic move. That distinction matters as soon as two users are involved. If both users reorder the same item while offline, each one generates an independent delete-plus-insert. When they sync back up, the list CRDT sees two separate insert operations, and the item appears twice.

List CRDTs have no "move" operation. Only deletes and inserts. So we need a different strategy for ordering.

### Fractional Indexing

[Fractional indexing](https://www.npmjs.com/package/fractional-indexing) (by Rocicorp, based on [this Observable post](https://observablehq.com/@dgreensp/implementing-fractional-indexing) by David Greenspan) sidesteps the problem. Instead of moving an item in the list, you store an `order` field on each item and update only that field when reordering. When you move an item between positions A and C, `generateKeyBetween("a", "c")` returns a key like `"b"` that sorts between them. The rest of the list stays untouched.

Because `order` is a field on a `CoMap`, updates use last-writer-wins semantics. The worst case during a concurrent edit is that one user's reorder "wins." The item never duplicates.

### Implementation

The `useSortable` implementation:

```ts
const todoListEl = useTemplateRef<HTMLElement>("todoListEl");

useSortable(todoListEl, todos, {
  handle: ".drag-handle",
  animation: 150,
  onUpdate: (e) => {
    // Revert SortableJS DOM manipulation — let Vue re-render from data
    removeNode(e.item);
    insertNodeAt(e.from, e.item, e.oldIndex!);

    const list = todoList.value;
    if (!list?.$isLoaded || e.oldIndex == null || e.newIndex == null) return;

    const sorted = todos.value;
    const before = sorted[e.newIndex - 1]?.order ?? null;
    const after = sorted[e.newIndex + (e.newIndex > e.oldIndex ? 1 : 0)]?.order ?? null;
    const item = sorted[e.oldIndex];
    if (item) item.$jazz.set("order", generateKeyBetween(before, after));
  },
});
```

The `onUpdate` handler contains a subtle DOM revert pattern: SortableJS directly manipulates the DOM when the user drags an item, but our source of truth is the `order` field on each `CoMap`. So we first undo the DOM change, then update the `order` field. Vue's computed re-sorts and re-renders correctly.

The reorder syncs to all peers just like any other mutation. If you've worked with cross-tab state syncing before, you'll know how tricky this can be:

<InternalLink slug="building-pinia-plugin-cross-tab-sync">Building a Pinia Plugin for Cross-Tab State Syncing</InternalLink>

## Running It

```bash
pnpm dev
```

Open two browser tabs. Add a todo in one, watch it appear in the other. Toggle "Online" off, add more todos, toggle back on. They sync up. Copy the link, open it in an incognito window. Same list.

## Conclusion

The full project is four files of application code:

- `src/schema.ts` (4 lines): CoValue definitions
- `src/App.vue` (20 lines): Provider + inspector + online toggle
- `src/TodoApp.vue` (~80 lines script + ~125 lines template): The complete app
- `vite.config.ts` (26 lines): Build config with custom element support

Coming from the Dexie.js approach, the amount of code surprised me. Jazz eliminates the backend-sync-API stack. You define your data, mutate it locally, and it syncs.

Two things worth highlighting: fractional indexing for drag-and-drop avoids the duplicate-item problem that `CoList` splice-based reordering can cause during concurrent offline edits. Jazz Groups with `addMember("everyone", "writer")` make the shared URL accessible. Without this, CoValues are private to the creator.

Check out the [Jazz documentation](https://jazz.tools) for more, and the [community-jazz-vue package](https://www.npmjs.com/package/community-jazz-vue) ([source code](https://github.com/garden-co/jazz/tree/main/packages/community-jazz-vue/src)) for the full Vue API.

---

**Source code:** [github.com/alexanderop/vue-jazz-todo-example](https://github.com/alexanderop/vue-jazz-todo-example)

---

--- title: How I Turned Claude Code's Thinking Indicator into a One Piece Adventure description: Replace Claude Code's default spinner verbs with custom One Piece references using the spinnerVerbs config in settings.json. tags: ['ai', 'tooling'] url: https://alexop.dev/posts/claude-code-spinner-verbs-one-piece ---

# How I Turned Claude Code's Thinking Indicator into a One Piece Adventure



Every time Claude Code processes a request, it shows a spinner with a verb like "Considering..." or "Analyzing...". That gets old fast. So I replaced all of them with One Piece references.

<Alert type="tip" title="The Easy Way">
  You can just ask Claude Code to change the spinner verbs for you. Tell it which theme you want (Star Wars, cooking, etc.) and it'll update `~/.claude/settings.json` directly. This post shows you how it works under the hood.
</Alert>

## The Setting: `spinnerVerbs`

Claude Code exposes a `spinnerVerbs` config in `~/.claude/settings.json`. You set a mode and pass an array of strings. That's it.

```json
{
  "spinnerVerbs": {
    "mode": "replace",
    "verbs": [
      "Stretching like Luffy...",
      "Reading the Poneglyph...",
      "Activating Gear Fifth...",
      "Three-Sword Styling..."
    ]
  }
}
```

## Two Modes

- **`replace`** swaps out every default verb. Claude Code only cycles through your list.
- **`append`** mixes your verbs with the built-in ones.

I picked `replace` because I want full One Piece immersion, no "Considering..." sneaking in.

## My Full Verb List

I wrote 25 verbs that cover the Straw Hat crew and the broader world:

```json
[
  "Stretching like Luffy...",
  "Setting sail on the Grand Line...",
  "Reading the Poneglyph...",
  "Activating Gear Fifth...",
  "Searching for the One Piece...",
  "Navigating with Nami...",
  "Three-Sword Styling...",
  "Cooking with Sanji...",
  "Consulting Nico Robin...",
  "Upgrading with Franky...",
  "Playing Brook's violin...",
  "Haki awakening...",
  "Dodging a Buster Call...",
  "Entering the New World...",
  "Deciphering the Will of D...",
  "Gathering the crew...",
  "Unfurling the Jolly Roger...",
  "Bounty hunting...",
  "Conquering the Calm Belt...",
  "Dreaming of All Blue...",
  "Mapping the world with Nami...",
  "Yohoho-ing with Brook...",
  "Tanuki-ing with Chopper...",
  "Observing with Haki...",
  "Sailing the Thousand Sunny..."
]
```

Each verb references a character, location, or concept from the series. Chopper gets called a tanuki (he hates that), Sanji dreams of All Blue, and Brook does his signature laugh.

## How to Apply It

1. Open `~/.claude/settings.json`.
2. Add the `spinnerVerbs` block anywhere at the top level.
3. Restart Claude Code.

Now every thinking phase picks a random verb from your list. Simple customization, big personality boost.

If you're looking for more ways to personalize Claude Code, check out how to <InternalLink slug="customize_claude_code_status_line">customize the status line</InternalLink> or how I <InternalLink slug="how-i-added-sound-effects-to-claude-code-with-hooks">added sound effects with hooks</InternalLink>. For a broader overview of all the customization options, see the <InternalLink slug="claude-code-customization-guide-claudemd-skills-subagents">full customization guide</InternalLink>.

## Make Your Own

Swap the verbs for any theme you like, Star Wars, cooking terms, gym motivation, whatever fits your vibe. The only rule: keep them short so they render cleanly in the terminal.

---

--- title: How I Added Sound Effects to Claude Code with Hooks description: Claude Code hooks let you run shell commands on lifecycle events. I wired up Age of Empires sound effects to session start, prompt submission, task completion, and context compaction. tags: ['claude-code', 'hooks', 'tooling'] url: https://alexop.dev/posts/how-i-added-sound-effects-to-claude-code-with-hooks ---

# How I Added Sound Effects to Claude Code with Hooks



## TLDR

Claude Code has a hooks system that lets you run shell commands on lifecycle events. I wired up Age of Empires sound effects to four key moments: session start, prompt submission, task completion, and context compaction. Now my terminal sounds like a medieval battlefield and I love it.

## Why Sounds?

I spend a lot of time in Claude Code. Sometimes I send a prompt and switch to another window while it works. The problem is I never know when it's done. I could keep checking, but that breaks my flow.

I wanted audio cues. Something that tells me "hey, I'm done" without me having to look. And if I'm going to add sounds, why not make them fun?

## How Claude Code Hooks Work

Claude Code lets you define hooks in your `settings.json` file at `~/.claude/settings.json`. Hooks fire on specific lifecycle events:

- **SessionStart**: When a new Claude Code session begins
- **UserPromptSubmit**: Right after you hit enter on a prompt
- **Stop**: When Claude finishes its response
- **PreCompact**: Before context compaction happens (when the conversation gets too long)

Each hook runs a shell command. That's it. Simple and powerful.

If you're new to hooks, I covered the basics in my post about <InternalLink slug="claude-code-notification-hooks">setting up Claude Code notification hooks</InternalLink>. This post goes in a different direction: instead of desktop notifications, we're adding sound effects.

For a broader look at what Claude Code can do, see my <InternalLink slug="understanding-claude-code-full-stack">overview of the full Claude Code feature stack</InternalLink>.

## My Setup

I put four MP3 files in `~/.claude/sounds/` and used `afplay` (macOS built-in audio player) to play them. Here's my full hooks config:

```json
// ~/.claude/settings.json
{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|clear",
        "hooks": [
          {
            "type": "command",
            "command": "afplay ~/.claude/sounds/horn.mp3 &"
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "afplay ~/.claude/sounds/yes.mp3 &"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "afplay ~/.claude/sounds/allhail.mp3 &"
          }
        ]
      }
    ],
    "PreCompact": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "afplay ~/.claude/sounds/wololo.mp3 &"
          }
        ]
      }
    ]
  }
}
```

The `&` at the end is important. It runs `afplay` in the background so the sound doesn't block Claude Code from continuing.

## The Sound Choices

All sounds are from Age of Empires. Here's why I picked each one:

| Event | Sound | Why |
|-------|-------|-----|
| SessionStart | `horn.mp3` | A battle horn. The session begins, time to work. |
| UserPromptSubmit | `yes.mp3` | The villager "yes" response. Claude acknowledges your command. |
| Stop | `allhail.mp3` | "All hail!" when Claude finishes. Victory. |
| PreCompact | `wololo.mp3` | The priest conversion sound. Your context is being... converted. |

The `wololo` for context compaction is my favorite. If you've played Age of Empires, you know what happens when a priest starts chanting "wololo": things change. That's exactly what context compaction does. It transforms your conversation to fit the context window.

## Bonus: Touch Files for Status Line

You might have noticed my actual config also touches files like `touch ~/.claude/.claude-done`. I use these as signals for my <InternalLink slug="customize_claude_code_status_line">custom status line script</InternalLink>. The status line reads these files to show the current Claude Code state in my terminal prompt.

## How to Set This Up Yourself

1. Create the sounds directory: `mkdir -p ~/.claude/sounds`
2. Drop your MP3 files in there (any short sound clips work)
3. Add the hooks config to `~/.claude/settings.json`
4. Restart Claude Code

<Alert type="tip">
On Linux, replace `afplay` with `aplay` or `paplay`. On Windows WSL, you can use `powershell.exe -c (New-Object Media.SoundPlayer "path").PlaySync()`.
</Alert>

## Conclusion

- Claude Code hooks run shell commands on lifecycle events
- You can use `afplay` on macOS to play sounds in the background
- Age of Empires sounds make the terminal more fun
- The `&` suffix is key so sounds don't block execution
- Touch files can signal other tools like status line scripts

Small things like audio feedback make tools feel more alive. It took five minutes to set up and now I actually enjoy waiting for Claude to finish.

---

--- title: Building a Walkthrough Skill for AI Coding Agents description: How I built a skill that generates interactive codebase walkthroughs with clickable Mermaid diagrams—works with Claude Code, Amp, and any agent that supports the skills standard. tags: ['claude-code', 'ai', 'tooling', 'skills'] url: https://alexop.dev/posts/building-walkthrough-skill-claude-code ---

# Building a Walkthrough Skill for AI Coding Agents



I'm a visual learner. When I join a new codebase or try to understand a complex flow, I need a diagram. Reading files one by one doesn't give me the mental model I need—I need to see the connections.

That's why Amp's [Shareable Walkthroughs](https://ampcode.com/news/walkthrough) caught my attention. The idea is simple: ask your AI coding tool to explain a feature, and it generates an interactive diagram where you can click through nodes to drill into the details.

I couldn't find the source code for Amp's implementation. So I built my own.

<Aside type="note" title="Just Want the Code?">
The skill is open source and ready to install:

[View on GitHub](https://github.com/alexanderop/walkthrough)

Quick install: `npx skills add https://github.com/alexanderop/walkthrough --skill walkthrough`
</Aside>

## What It Does

You ask your agent something like "walkthrough how does authentication work" and it:

1. Spawns 2–4 subagents to explore relevant parts of your codebase in parallel
2. Synthesizes findings into 5–12 key concepts with connections
3. Generates a self-contained HTML file with an interactive Mermaid diagram
4. Opens it in your browser

Each node in the diagram is clickable. Click one and a detail panel slides in with a plain-English description, file paths, and optional code snippets. The whole thing is designed to give you a mental model in under two minutes.

Here's a live example—this walkthrough explains how the skill itself works. Click on any node to see the details:

<iframe
  src="https://alexanderop.github.io/walkthrough/examples/walkthrough-how-it-works.html"
  title="Walkthrough skill: how it works"
  style="width: 100%; height: 600px; border: 1px solid #2a2a2a; border-radius: 8px;"
  loading="lazy"
  allow="fullscreen"
/>

<Aside type="info" title="Skills Are a Standard">
Skills aren't exclusive to Claude Code. They're a [shared standard](https://skills.dev/) supported by multiple AI coding agents—Claude Code, Amp, and others. A skill you write once works across all of them. If you're new to skills in Claude Code specifically, check out my <InternalLink slug="claude-code-customization-guide-claudemd-skills-subagents">guide to CLAUDE.md, skills, and subagents</InternalLink>.
</Aside>

## How the Skill Works

The walkthrough above shows the full pipeline. Let me walk through the four phases.

### Phase 1: Trigger

Everything starts with a natural-language prompt. When you type something like "walkthrough how does auth work", your agent matches the trigger pattern in the skill definition and activates the walkthrough workflow.

### Phase 2: Skill Configuration

The skill consists of two files:

<FileTree tree={[
  { name: "skills/walkthrough", open: true, children: [
    { name: "skill.md", comment: "// workflow and trigger definitions" },
    { name: "references", open: true, children: [
      { name: "html-patterns.md", comment: "// HTML, CSS, JS templates" }
    ]}
  ]}
]} />

`skill.md` defines the four-step workflow: scope the question, launch subagents, synthesize findings, generate HTML. It also includes a quality checklist—things like keeping diagrams to 5–12 nodes and writing descriptions in plain English.

`html-patterns.md` is the complete reference for the generated output: React components, Mermaid configuration, the color palette, pan/zoom implementation, and Shiki syntax highlighting setup. The agent reads this file and follows the patterns when generating the HTML.

### Phase 3: Exploration

This is where it gets interesting. Instead of having one agent read through your entire codebase, the skill uses subagents to parallelize the exploration:

1. **Scope understanding** — The main agent clarifies what you're asking about and identifies which areas of the codebase are relevant
2. **Parallel subagents** — 2–4 Explore subagents investigate specific regions concurrently, each returning a structured report with purpose, connections, node suggestions, file paths, and key code snippets
3. **Synthesis** — The main agent combines all reports into a single list of nodes, edges, and subgroup groupings

The subagents do the reading. The main agent does the thinking. This keeps the output coherent while making exploration fast.

### Phase 4: Generation

With the synthesized data, the agent picks the right diagram type—flowchart for feature flows and architecture, ER diagram for database schemas—and generates a self-contained HTML file. No build step, no dependencies to install. It loads everything from CDNs:

- **React 18** for the interactive UI
- **Mermaid 11** for diagram rendering
- **Tailwind CSS** for styling
- **Shiki** for syntax highlighting in code snippets

The design is dark-only with a pure black background and purple accents. Every diagram node is clickable via Mermaid's callback system, and there's scroll-to-zoom and drag-to-pan for larger diagrams. The file opens directly in your browser.

And here's what happens when I ask the skill to onboard me on this very blog's codebase:

```
walkthrough help me to onboard on this project
```

<iframe
  src="/walkthrough-project-overview.html"
  title="Walkthrough: AstroPaper blog project overview"
  style="width: 100%; height: 600px; border: 1px solid #2a2a2a; border-radius: 8px;"
  loading="lazy"
  allow="fullscreen"
/>

Five content collections, a presentation engine, educational visualizers, OG image generation—all mapped out in one interactive diagram. Click any node to see what it does and where it lives.

## Example Prompts

Here are some ways I use it:

```
walkthrough how does the presentation mode work
```

```
walkthrough explain the authentication flow when a user signs up
```

```
walkthrough database schema for the content management system, use an ER diagram
```

## Why I Built This

I've written about <InternalLink slug="how-to-use-ai-for-effective-diagram-creation-a-guide-to-chatgpt-and-mermaid">using AI for diagrams</InternalLink> before. The pattern is always the same—I need to see the system before I can reason about it.

Existing tools either require you to manually write diagram code or generate static images. What I wanted was something interactive where I could start at the high level and drill down only into the parts that matter.

The walkthrough skill fills that gap. It's the onboarding tool I wish every codebase had.

## Conclusion

- Skills are a standard—this works with Claude Code, Amp, and any agent that supports them
- Subagents make codebase exploration fast by parallelizing reads
- Self-contained HTML with CDN dependencies means zero setup for viewers
- The skill is open source at [github.com/alexanderop/walkthrough](https://github.com/alexanderop/walkthrough)

If you're a visual thinker like me, give it a try. Ask it to explain something in your codebase and see what comes out.

---

--- title: Claude Code Agent Teams: How Multiple Sessions Coordinate (2026) description: Agent teams let multiple Claude Code sessions coordinate, communicate, and self-organize. Here's how they work, when to use them, and what they cost. tags: ['claude-code', 'ai', 'tooling', 'architecture'] url: https://alexop.dev/posts/from-tasks-to-swarms-agent-teams-in-claude-code ---

# Claude Code Agent Teams: How Multiple Sessions Coordinate (2026)



In my <InternalLink slug="spec-driven-development-claude-code-in-action">previous post</InternalLink> I covered spec-driven development with Claude Code—using the task system to break large refactors into subagent-driven work. Subagents are powerful, but they have one fundamental limitation: they can only report back to the parent. They can't talk to each other.

Agent teams remove that limitation. They're a new experimental feature in Claude Code where multiple sessions coordinate as a team—with a shared task list, direct messaging between teammates, and a team lead that orchestrates the whole thing.

## Table of Contents

## The Evolution: From Subagents to Agent Teams

This is the progression of delegation in Claude Code. Each step gives the AI more autonomy and less handholding:

<Alert type="info" title="Experimental feature">
Agent teams are disabled by default. Enable them by adding `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` to your `settings.json` or environment.
</Alert>

## Subagents vs Agent Teams

The critical difference is communication. Subagents are fire-and-forget workers. Agent teams are collaborators.

|                   | Subagents                    | Agent Teams                           |
| :---------------- | :--------------------------- | :------------------------------------ |
| **Context**       | Own window, results return   | Own window, fully independent         |
| **Communication** | Report to main only          | Message each other directly           |
| **Coordination**  | Main manages everything      | Shared task list, self-claim          |
| **Token cost**    | Lower                        | Higher—each teammate is a full session |
| **Best for**      | Focused tasks, research      | Complex work needing collaboration    |

## The Seven Team Primitives

Agent teams aren't magic. They're built from seven tools that Claude can call. Understanding these tools is the key to understanding how teams actually work under the hood.

Here's each one, with the real calls from my QA session.

### TeamCreate — Start a Team

Creates the team directory and config file. This is always the first call.

```json
// Tool call
TeamCreate({ "team_name": "blog-qa", "description": "QA team testing the blog" })

// Creates on disk:
// ~/.claude/teams/blog-qa/config.json
// ~/.claude/tasks/blog-qa/
```

The `team_name` is the namespace that links everything together—tasks, messages, and the config file all live under it.

### TaskCreate — Define a Unit of Work

Each task is a JSON file on disk. The lead creates these before spawning any teammates.

```json
// Tool call
TaskCreate({
  "subject": "QA: Core pages respond with 200 and valid HTML",
  "description": "Fetch all major pages at localhost:4321 and verify
    they return HTTP 200. Test: /, /posts, /tags, /notes, /tils,
    /search, /projects, /404 (should be 404), /rss.xml...",
  "activeForm": "Testing core page responses"
})

// Creates: ~/.claude/tasks/blog-qa/1.json
```

The `description` is what the teammate actually reads to know what to do. It's essentially a prompt for the agent. The more detail you pack in here (or the lead packs in), the better the agent performs.

### TaskUpdate — Claim and Complete Work

Teammates use this to change task status. It's how work moves through the pipeline.

```json
// Teammate claims a task
TaskUpdate({ "taskId": "1", "status": "in_progress", "owner": "qa-pages" })

// Teammate finishes
TaskUpdate({ "taskId": "1", "status": "completed" })
```

The status field prevents two agents from working on the same thing. When a task is `in_progress` with an owner, other agents skip it.

### TaskList — Find Available Work

Returns all tasks with their current status. Teammates call this after completing a task to find what's next.

```json
// Tool call
TaskList()

// Returns:
// { id: "1", subject: "Core pages...",  status: "completed",   owner: "qa-pages" }
// { id: "2", subject: "Blog posts...",  status: "in_progress", owner: "qa-posts" }
// { id: "3", subject: "Links...",       status: "pending",     owner: ""         }
```

This is the shared coordination mechanism. No centralized scheduler—each teammate polls `TaskList`, finds unowned pending tasks, and claims one.

### Task (with team_name) — Spawn a Teammate

The existing `Task` tool gets a `team_name` parameter that turns a regular subagent into a team member. Once spawned, the teammate can see the shared task list and message other teammates.

```json
// Tool call
Task({
  "description": "QA: Core page responses",
  "subagent_type": "general-purpose",
  "name": "qa-pages",
  "team_name": "blog-qa",
  "model": "sonnet",
  "prompt": "You are a QA agent testing a blog at localhost:4321.
    Your task is Task #1: verify all core pages respond correctly..."
})
```

Notice the `model: "sonnet"` — the lead ran on Opus but spawned all teammates on Sonnet. This is a common cost optimization pattern: expensive model for coordination, cheaper model for execution.

### SendMessage — Talk to Each Other

This is what makes teams different from subagents. Any teammate can message any other teammate directly.

```json
// Teammate → Lead: report findings
SendMessage({
  "type": "message",
  "recipient": "team-lead",
  "content": "Task #1 complete. 16/16 pages pass. No issues found.",
  "summary": "All core pages pass"
})

// Lead → Teammate: request shutdown
SendMessage({
  "type": "shutdown_request",
  "recipient": "qa-pages",
  "content": "All tasks complete, shutting down team."
})

// Teammate → Lead: acknowledge shutdown
SendMessage({
  "type": "shutdown_response",
  "request_id": "shutdown-123",
  "approve": true
})
```

`SendMessage` supports several message types: `message` for direct messages, `broadcast` to reach all teammates at once, `shutdown_request`/`shutdown_response` for graceful teardown, and `plan_approval_response` for quality gates.

### TeamDelete — Clean Up

Removes the team config and all task files from disk. Called after all teammates have shut down.

```json
// Tool call
TeamDelete()

// Removes:
// ~/.claude/teams/blog-qa/
// ~/.claude/tasks/blog-qa/
```

### How They Fit Together

Every team session follows the same tool sequence:

Each teammate is a full Claude Code session with its own context window. They load the same project context (CLAUDE.md, MCP servers, skills) but don't inherit the lead's conversation history. The task files on disk and `SendMessage` are the only coordination channels—there's no shared memory.

## The Team Lead's Control Layer

What makes agent teams more than "just parallel subagents" is the team lead. The lead is an abstraction layer that gives AI more control over coordination:

## Task Lifecycle in a Team

## Use Case: Building a Large Feature

When you ask Claude Code to implement something big, agent teams let it parallelize the work the way a real engineering team would:

<Prompt>
Create an agent team to build the new dashboard feature.
One teammate on the API layer, one on the frontend components,
one on the test suite. Use Sonnet for each teammate.
</Prompt>

The key difference from subagents: when the API teammate finishes the type definitions, it messages the UI teammate directly. No round-trip through the main agent. The test teammate can ask the API teammate to spin up a dev server. They self-coordinate.

## Real Example: QA Swarm Against My Blog

This isn't a hypothetical. I ran this against my own blog before a production deploy. Here's the exact prompt I used:

<Prompt>
Use a team of agents that will do QA against my blog.
It's running at http://localhost:4321/
</Prompt>

That's it. Claude took over from there.

### What the Lead Did

The lead verified the site was running (`curl` returned 200), created a team called `blog-qa`, then broke the work into 5 tasks and spawned 5 agents—all using Sonnet to keep costs down:

### What the Files Look Like

When `TeamCreate` runs, it writes two things to disk. Here's what they actually look like:

```json
// ~/.claude/teams/blog-qa/config.json
{
  "members": [
    { "name": "qa-pages", "agentId": "abc-123", "agentType": "general-purpose" },
    { "name": "qa-posts", "agentId": "def-456", "agentType": "general-purpose" },
    { "name": "qa-links", "agentId": "ghi-789", "agentType": "general-purpose" },
    { "name": "qa-seo",   "agentId": "jkl-012", "agentType": "general-purpose" },
    { "name": "qa-a11y",  "agentId": "mno-345", "agentType": "general-purpose" }
  ]
}
```

And the tasks lived as individual files under `~/.claude/tasks/blog-qa/`. Each task had a subject, a detailed description telling the agent exactly what to check, and a status field:

```json
// ~/.claude/tasks/blog-qa/1.json
{
  "id": "1",
  "subject": "QA: Core pages respond with 200 and valid HTML",
  "description": "Fetch all major pages on the blog at localhost:4321 and verify
    they return HTTP 200 with valid HTML content. Test: /, /posts, /tags, /notes,
    /tils, /search, /projects, /talks, /goals, /prompts, /404 (should be 404),
    /robots.txt, /rss.xml, /llms.txt, /llms-full.txt. Also check that the HTML
    contains expected elements (title, nav, footer).",
  "status": "completed",
  "owner": "qa-pages"
}
```

The lead created these 5 tasks:

| # | Task | Agent | What It Checked |
|---|------|-------|-----------------|
| 1 | Core page responses | `qa-pages` | 16 URLs return correct HTTP status codes |
| 2 | Blog post rendering | `qa-posts` | 83 posts have h1, meta tags, working images |
| 3 | Navigation & link integrity | `qa-links` | 146 internal URLs for broken links |
| 4 | RSS, sitemap, SEO metadata | `qa-seo` | RSS validity, robots.txt, og:tags, JSON-LD |
| 5 | Accessibility & HTML structure | `qa-a11y` | Heading hierarchy, ARIA, theme toggle, lang attr |

### How the Agents Reported Back

Each agent finished independently and sent a structured report back via `SendMessage`. Here's what `qa-pages` sent:

```
## Task #1 Complete: Core Page Response Testing

### Summary: ALL PAGES PASS

| URL         | Expected | Actual | Result |
|-------------|----------|--------|--------|
| /           | 200      | 200    | PASS   |
| /posts      | 200      | 200    | PASS   |
| /tags       | 200      | 200    | PASS   |
| /notes      | 200      | 200    | PASS   |
| /404        | 404      | 404    | PASS   |
| /rss.xml    | 200      | 200    | PASS   |
| /llms.txt   | 200      | 200    | PASS   |
  ...16 URLs tested, 0 failures.
```

Meanwhile `qa-posts` tested all 83 blog posts and found 2 with broken OG images. `qa-seo` found the `og:type` meta tag was missing. `qa-a11y` caught that `<html>` had `class="false"` (a boolean stringified as a class name) and a heading hierarchy issue.

### The Lead's Synthesis

Once all 5 agents reported back, the lead compiled a single prioritized report:

```
## QA Report — alexop.dev

5 agents | 146+ URLs tested | 83 blog posts checked

### Issues by Severity

MAJOR (4):
  1. <html class="false"> — boolean stringified as CSS class
  2. <h2> before <h1> — newsletter banner breaks heading order
  3. Theme toggle button missing from DOM
  4. Theme hardcoded to dark only

MEDIUM (2):
  5. og:type meta tag missing on all pages
  6. 2 blog posts with broken OG images

MINOR (4):
  7-10. Various small accessibility gaps
```

Then the lead sent `shutdown_request` to each agent, they acknowledged, and `TeamDelete` cleaned up the files.

### The Full Lifecycle

The whole thing—from prompt to final report—took about 3 minutes. Each agent used `curl` to fetch pages and parse the HTML. No browser automation, no test framework. Just 5 Claude sessions hammering a dev server in parallel.

## The Cost Trade-off

Agent teams are token-heavy. Every teammate is a full Claude Code session with its own context window.

The math is simple: more agents = more tokens = more cost. Use teams when the coordination benefit justifies it. For routine tasks, a single session or subagents are more cost-effective.

### When Teams Are Worth It

## Getting Started

Enable agent teams:

```json
// .claude/settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}
```

Then tell Claude what you want:

<Prompt>
Create an agent team to refactor the authentication module.
One teammate on the backend logic, one on the frontend hooks,
one running tests continuously. Require plan approval before
any teammate makes changes.
</Prompt>

### Recipe: Plan First, Parallelize Second

The most effective pattern I've found isn't jumping straight into a team. It's a two-step approach: **plan first with plan mode, then hand the plan to a team for parallel execution.**

Here's the workflow:

**Step 1 — Get a plan.** Start with plan mode (`/plan` or tell Claude to plan). Let it explore the codebase, identify files, and produce a step-by-step implementation plan. Review it. Adjust it. This is cheap—plan mode only reads files.

<Prompt>
Plan the refactor of our authentication module. I want to split the
monolithic auth.ts into separate files for JWT handling, session
management, and middleware. Show me the plan before doing anything.
</Prompt>

Claude produces something like:

```
Plan:
1. Create src/auth/jwt.ts — extract token signing/verification
2. Create src/auth/sessions.ts — extract session logic
3. Create src/auth/middleware.ts — extract Express middleware
4. Update src/auth/index.ts — re-export public API
5. Update 12 import sites across the codebase
6. Update tests in src/auth/__tests__/
```

**Step 2 — Parallelize the plan with a team.** Once you approve the plan, tell Claude to execute it as a team. The key insight: the plan already has the task breakdown. You're just telling Claude to run independent tracks in parallel instead of sequentially.

<Prompt>
Now execute this plan using an agent team. Parallelize where possible—
steps 1-3 can run in parallel since they're independent extractions.
Step 4-5 depends on 1-3. Step 6 depends on everything.
Use Sonnet for the teammates.
</Prompt>

The lead sees the dependency graph and spawns teammates accordingly:

```
Wave 1 (parallel):  jwt.ts + sessions.ts + middleware.ts  → 3 teammates
Wave 2 (after wave 1): index.ts barrel + update imports   → 1-2 teammates
Wave 3 (after wave 2): update tests                       → 1 teammate
```

This works because plan mode gives you the checkpoint to review before spending tokens on a full team. Without the plan step, the team lead has to figure out the task breakdown itself—which it can do, but you lose the chance to steer it. With the plan, you've already shaped the work. The team just executes it faster.

<Alert type="tip" title="Why this beats jumping straight to a team">
Plan mode costs ~10k tokens. A team that goes in the wrong direction costs 500k+. Spending a few seconds reviewing a plan saves you from expensive course corrections mid-swarm.
</Alert>

### Display Modes

## The Abstraction Ladder

Each level trades control for compute. Solo sessions give you full control but limited throughput. Agent teams give you maximum compute but you're trusting the AI to coordinate itself. The sweet spot depends on your task.

<Aside type="note" title="Limitations to Know">
Agent teams are experimental. Key limitations:
- No session resumption for in-process teammates
- Task status can lag—teammates sometimes forget to mark tasks complete
- One team per session, no nested teams
- Split panes require tmux or iTerm2 (not VS Code terminal)
- All teammates start with the lead's permission settings
</Aside>

## Conclusion

- Agent teams let multiple Claude Code sessions **communicate with each other**, not just report to a parent
- A team lead orchestrates, observes, and synthesizes—another abstraction layer where AI manages AI
- Best use cases: **large features** (parallel tracks), **QA swarms** (multiple testing perspectives), **competing hypotheses** (debate and converge)
- The trade-off is real: more agents = more tokens = more cost
- **Best recipe**: plan first with plan mode (cheap), then hand the plan to a team for parallel execution (expensive but fast). The plan gives you a checkpoint before committing tokens.
- Start with subagents for focused work, graduate to teams when workers need to coordinate
- For background on the task system that teams build on, see my <InternalLink slug="spec-driven-development-claude-code-in-action">spec-driven development post</InternalLink>
- For where this is all heading—AI managing AI, and teams reshaped around it—see <InternalLink slug="the-software-factory">The Software Factory</InternalLink>

---

--- title: VMark: Hand-Drawn Annotations for Presentations description: Learn how to add animated hand-drawn annotations to your presentations using VMark. A complete tutorial covering all annotation types, colors, and timing controls. tags: ['presentation', 'tutorial', 'documentation'] url: https://alexop.dev/posts/vmark-tutorial ---

# VMark: Hand-Drawn Annotations for Presentations



# VMark: Hand-Drawn Annotations

Add emphasis to your presentations with animated hand-drawn marks

---

## The Problem

Static text in presentations lacks emphasis.

We want **this** to <VMark>stand out</VMark>.

VMark creates a "live drawing" effect that grabs attention and guides your audience's focus.

---

## Getting Started

Import VMark from the presentation feature:

```tsx
```

Basic usage wraps text in the component:

```tsx
<VMark>text to emphasize</VMark>
```

The default is <VMark>underline</VMark>, and it animates on click.

---

## Annotation Types: Underline & Circle

<VMark type="underline" color="blue">Underline</VMark> is the default. Use it for general emphasis.

<VMark type="circle" color="red">Circle</VMark> draws attention to key terms or important words.

```tsx
<VMark type="underline">emphasis</VMark>
<VMark type="circle" color="red">key term</VMark>
```

---

## Annotation Types: Box & Highlight

<VMark type="box" color="green">Box</VMark> frames content like code or definitions.

<VMark type="highlight" color="yellow">Highlight</VMark> creates a marker effect. It uses 40% opacity so text stays readable.

```tsx
<VMark type="box" color="green">boxed</VMark>
<VMark type="highlight" color="yellow">highlighted</VMark>
```

---

## Annotation Types: Strike-through & Crossed-off

Use these for corrections or showing what to avoid:

<VMark type="strike-through" color="red">This approach is wrong</VMark>

<VMark type="crossed-off" color="red">Don't do this</VMark>

Common pattern: show the wrong approach, then reveal the correct one.

---

## Annotation Type: Bracket

<VMark type="bracket" brackets={['left', 'right']} color="purple">
  Brackets emphasize entire phrases or sentences
</VMark>

The `brackets` prop controls direction:

```tsx
<VMark type="bracket" brackets={['left', 'right']}>
  phrase
</VMark>
```

Options: `left`, `right`, `top`, `bottom`

---

## Color Presets

VMark includes 24 color presets:

<VMark color="red">red</VMark> | <VMark color="blue">blue</VMark> | <VMark color="green">green</VMark> | <VMark color="yellow">yellow</VMark> | <VMark color="purple">purple</VMark> | <VMark color="orange">orange</VMark>

<VMark color="cyan">cyan</VMark> | <VMark color="teal">teal</VMark> | <VMark color="pink">pink</VMark> | <VMark color="indigo">indigo</VMark> | <VMark color="lime">lime</VMark> | <VMark color="amber">amber</VMark>

Custom CSS colors also work: `#ff6b6b`, `rgb(100, 200, 150)`, `rgba(255, 0, 0, 0.5)`

---

## Controlling Timing: Sequential

By default, VMark annotations appear <VMark>sequentially</VMark> with each click.

This one appears <VMark color="blue">second</VMark>.

And this one <VMark color="green">third</VMark>.

Just place VMark components in order. Each one advances the click counter.

---

## Controlling Timing: Explicit

Use `at` to specify an exact click number:

<VMark at={3} type="circle" color="red">Third (at=3)</VMark>

<VMark at={1}>First (at=1)</VMark>

<VMark at={2} type="box" color="blue">Second (at=2)</VMark>

```tsx
<VMark at={3}>appears on click 3</VMark>
<VMark at={1}>appears on click 1</VMark>
```

---

## Advanced Timing: Relative & Ranges

Relative positioning with `+N`:

<VMark at="+1" color="blue">+1 from previous</VMark>

Ranges show content only during a window:

<VMark at={[3, 5]} type="highlight" color="yellow">Visible from click 3 to 4</VMark>

```tsx
<VMark at="+1">offset from previous</VMark>
<VMark at={[2, 5]}>visible during clicks 2-4</VMark>
```

---

## Under the Hood

VMark is built on the <VMark type="circle" color="purple">rough-notation</VMark> library.

Key behaviors:

- Generates SVG annotations at runtime
- Respects `prefers-reduced-motion` (instant show, no animation)
- Works with print/export mode (`?print=true`)
- Annotations are visual only. Screen readers see just the text

---

## Summary

<VMark type="box" color="blue">Import from `@features/presentation`</VMark>

<VMark type="circle" color="green">7 annotation types</VMark>: underline, circle, box, highlight, strike-through, crossed-off, bracket

<VMark type="highlight" color="yellow">24 color presets</VMark> plus custom CSS colors

<VMark color="purple">Full click system integration</VMark> with `at` prop for timing control

Press **Escape** to exit presentation mode.

---

--- title: Spec-Driven Development with Claude Code in Action description: A practical workflow for tackling large refactors with Claude Code using parallel research subagents, written specs, and the new task system for context-efficient implementation. tags: ['claude-code', 'ai', 'local-first', 'architecture'] url: https://alexop.dev/posts/spec-driven-development-claude-code-in-action ---

# Spec-Driven Development with Claude Code in Action



I'm building a [simplified sync engine from scratch](https://github.com/alexanderop/nuxt-sync-engine) using Nuxt 4.
My approach: study how production-grade frameworks solve the hard problems, then implement a minimal version myself.

[Jazz](https://jazz.tools) is my primary reference a local-first framework with elegant patterns for persistence, conflict resolution, and cross-tab sync. Rather than reading through their codebase manually, 
I use Claude Code to research, extract patterns, and help me implement them.

This post documents the workflow I call **Spec-Driven Development with Claude Code** the exact prompts, tools, and patterns I used to migrate my storage layer from SQLite/WASM to IndexedDB in a single day.

## The Problem

My sync engine was using `sql.js` (SQLite compiled to WASM) for client-side storage. It worked, but had issues:
- Large WASM bundle (~1MB)
- Complex COOP/COEP header requirements
- No native cross-tab sync

I wanted to migrate to IndexedDB, borrowing patterns from Jazz. But this was a significant refactor touching 15+ files. (For background on <InternalLink slug="what-is-local-first-web-development">local-first web development</InternalLink> and why it matters, see my earlier post.)

## The Workflow

Instead of diving into code, I used Claude Code as an **AI development team**with myself as the product owner, Claude as the tech lead, and subagents as developers.

Important: I also cloned the source code of Jazz into my Project so Claude could reference it during research and implementation.

<Figure
  src={specDrivenDevelopmentImg}
  alt="Spec-Driven Development workflow: Research Phase with parallel subagents, Spec Creation with written document, Refine with Q&A interview pattern, and Implement with task-per-subagent"
  caption="The four phases of Spec-Driven Development with Claude Code"
/>

## Phase 1: Research with Parallel Subagents

### The Prompt

<Prompt>
you have access to jazz source repo explain to me how they use
indexdb in the client to persist state our project is using sqlite
but we want to change to indexdb with jazz your goal is to write
a report spin up multiple subagents for your research task
</Prompt>

### What Happened

Claude spawned **5 parallel research agents**, each investigating a specific aspect of Jazz:

<Alert type="info" title="No custom agents needed">
These are Claude Code's **built-in subagents**. The `Task` tool is a native tool in Claude Code, just like `Read` or `Bash`. When you ask Claude to "spin up subagents," it uses this built-in tool automatically with the `general-purpose` subagent type. No custom agent definition or setup is required.
</Alert>

<Figure
  src={researchPhaseImg}
  alt="Research Phase: Five parallel agents (CRDT, WebSocket, Push/Pull, Storage, Architecture) each investigating independently, converging into a consolidated research report"
  caption="Parallel research agents converging into a consolidated report"
/>

Each agent explored the Jazz codebase independently and reported back:

| Agent | Focus | Key Findings |
|-------|-------|--------------|
| CRDT | Data structures | CoMap, CoList use operation-based CRDTs with LWW |
| WebSocket | Real-time sync | 4-message protocol: load, known, content, done |
| Push/Pull | Sync strategy | Hybrid model with known-state tracking |
| Storage | Persistence | IndexedDB with `coValues`, `sessions`, `transactions` stores |
| Architecture | Overall design | Monorepo with platform adapters |

### Follow-up Prompt

<Prompt>
research longer and improve the plan
</Prompt>

This triggered deeper investigation into edge cases and implementation details.

## Phase 2: Spec Creation

After research, Claude wrote a comprehensive technical specification to `docs/indexeddb-migration-spec.md`:
[Full spec](https://gist.github.com/alexanderop/70ef80ac6dda5166c5085cc9bb269df1)

```markdown
# IndexedDB Migration Specification

## Part 1: How Jazz Uses IndexedDB
- Database schema (coValues, sessions, transactions stores)
- Transaction queuing pattern
- Entity caching layer
- Session-based conflict resolution

## Part 2: Current SQLite Architecture Analysis
- sql.js WASM setup
- Existing sync protocol
- Pain points and limitations

## Part 3: Migration Plan (4 Phases)
- Phase 1: Core IndexedDB utilities
- Phase 2: Composables layer
- Phase 3: Cross-tab sync
- Phase 4: Cleanup and testing

## Part 4: Implementation Checklist
- [ ] idb-helpers.ts
- [ ] useIndexedDB.ts
- [ ] useSessionTracking.ts
- ... (14 items total)
```

**Key insight**: The spec becomes the source of truth. It's a document Claude can reference during implementation, ensuring consistency across all tasks.
It also becomes a Pin that we can use if something went wrong during implementation.

## Phase 3: Spec Refinement via Interview

Before implementation, I wanted to ensure the spec was solid. I used Claude's `AskUserQuestion` tool:

### The Prompt

<Prompt>
use the ask_user_question tool do you have any questions regarding
@docs/indexeddb-migration-spec.md before we implement it we want
to improve the specs
</Prompt>

Claude asked clarifying questions:
- Should we support migration from existing SQLite data?
- What's the preferred conflict resolution strategy?
- Should cross-tab sync use BroadcastChannel or SharedWorker?

After answering, I requested Vue-specific improvements:

<Prompt>
we want to use provide and inject you have access to the source
code of pinia spin up multiple subagents how they do it so we can
use same patterns
</Prompt>

Claude researched Pinia's patterns and updated the spec with:
- Symbol-based injection keys
- Provider composables with fallback patterns
- Proper cleanup on unmount

## Phase 4: Implementation with Task Delegation

This is where the new **Claude Code Task System** shines. (If you're unfamiliar with subagents and how they work in Claude Code, my <InternalLink slug="claude-code-customization-guide-claudemd-skills-subagents">customization guide</InternalLink> covers the fundamentals.)

### The Prompt

<Prompt>
implement @docs/indexeddb-migration-spec.md use the task tool and
each task should only be done by a subagent so that context is
clear after each task do a commit before you continue you are the
main agent and your subagents are your devs
</Prompt>

### Understanding Claude Code's Task System

Claude Code's task systeminspired by [Beads](https://github.com/beads-ai/beads), Steve Yegge's distributed git-backed issue trackersolves two critical problems with AI coding agents:

**Agent Amnesia**: Starting a new session mid-task loses all progress unless you manually document remaining work.

**Context Pollution**: A full context window makes the agent drop discovered bugs instead of tracking them.

The previous todo list lived in session memory and vanished on restart. The new task system persists tasks to disk, making them shareable across sessions and subagents.

### How Tasks Persist

Tasks are stored in `.claude/tasks/{session-id}/` as JSON files:

```json
{
  "id": "task-1",
  "subject": "Create idb-helpers.ts",
  "description": "Implement IndexedDB promise wrappers...",
  "status": "pending | in_progress | completed",
  "blocks": ["task-3", "task-4"],
  "blockedBy": ["task-0"]
}
```

### The Four Task Tools

| Tool | Purpose |
|------|---------|
| `TaskCreate` | Create a new task with subject, description, and dependencies |
| `TaskUpdate` | Update status (pending → in_progress → completed) or modify dependencies |
| `TaskList` | View all tasks, their status, and what's blocked |
| `TaskGet` | Get full details of a specific task including description |

### Task System Architecture

<Figure
  src={taskOrchestrationImg}
  alt="Task Orchestration: Main Session orchestrator connects to Task List in .claude/tasks/, which delegates to Subagent 1, 2, and 3 each with fresh context. Below shows a dependency graph with Wave 1 (T1, T2, T3 in parallel), Wave 2 (T4, T5, T6 dependent), and Wave 3 (T7)"
  caption="Task orchestration with dependency-aware parallel execution"
/>

### Why Subagents + Tasks = Context Efficiency

By delegating each task to a subagent, the main session stays leanit only handles orchestration (creating tasks, tracking progress, committing). Each subagent gets a fresh context window focused entirely on its specific task, reads what it needs, implements, and returns. This means the main agent won't run out of context even for larger refactors with dozens of tasks.

For truly massive projects spanning days or weeks, a full autonomous agent like [Ralph](https://ghuntley.com/ralph/) would be more appropriate. Ralph is elegantly simplea bash loop that feeds a markdown file into Claude Code repeatedly:

<Figure
  src={ralphArchitectureImg}
  alt="Ralph Architecture: A bash loop (while :; do cat PROMPT.md | claude-code ; done) where PROMPT.md feeds into Claude Code which produces output, and the loop continues indefinitely"
  caption="Ralph's stateless architecture using markdown as persistent memory"
/>

The key difference: Ralph executes each iteration in a completely new Claude session, using the markdown file as the only persistent memory. This makes it truly stateless and capable of running for days.

This spec-driven approach hits a middle ground: subagents get fresh context but the main orchestrator maintains state within a single session. Structured enough to maintain coherence, flexible enough to handle complexity, without the setup overhead of a full autonomous system.

### The Execution Flow

<Figure
  src={orchestratorFlowImg}
  alt="Main Agent Orchestrator flow: TaskCreate spawns Subagent 1 which implements and returns, then TaskUpdate marks complete and commits, then TaskCreate spawns Subagent 2 with dependencies, repeating for all tasks"
  caption="The orchestrator delegates each task to a subagent with atomic commits"
  size="medium"
/>

### Why This Pattern Works

1. **Context isolation**: Each subagent starts fresh, reading only what it needsno accumulated cruft
2. **Persistent progress**: Tasks survive session restarts; pick up where you left off
3. **Dependency-aware parallelism**: Claude identifies which tasks can run concurrently
4. **Atomic commits**: Every task = one commit, making rollbacks trivial
5. **Spec as contract**: Subagents reference the spec, ensuring consistency

### Backpressure: Let the System Catch Mistakes

One crucial element that makes atomic commits powerful: [backpressure](https://banay.me/dont-waste-your-backpressure/). Instead of manually reviewing every change, set up pre-commit hooks that run tests, linting, and type checking automatically.

```bash
# .husky/pre-commit
pnpm typecheck && pnpm lint && pnpm test-run
```

When a subagent commits, the hook runs immediately. If tests fail, the commit is rejected and the agent sees the error outputgiving it a chance to self-correct before moving on. This creates automated feedback that catches issues at the source rather than accumulating bugs across multiple tasks.

The result: you stop being the bottleneck for quality control. The system validates correctness while you focus on higher-level decisions.

### When Things Go Wrong

The first execution wasn't perfectI started the project and hit some errors. But here's where the spec pays off: I opened a new chat, pinned the spec document, pasted the error, and Claude fixed it immediately. No context rebuilding, no re-explaining the architecture.

The spec acts as a recovery point. When a session goes sideways or context gets polluted, you don't lose everythingyou have a document that captures the full intent and design decisions.

### The Results

After ~45 minutes:

```
$ git log-oneline | head20

9dc1c96 refactor: clean up code structure
9fce16b feat(storage): migrate from SQLite to IndexedDB
835c494 feat: integrate IDB sync engine provider
d2cd7b7 refactor: remove SQLite/sql.js dependencies
2fb7656 feat: add browser mode test stubs
... (14 commits total)
```

**14 tasks completed**, **14 commits**, **15+ files changed**, **one PR ready for review**. See the [full pull request](https://github.com/alexanderop/nuxt-sync-engine/pull/3) (includes additional manual changes).

And despite orchestrating 14 subagents, the main session's context stayed manageable:

<ContextUsage
  model="claude-opus-4-5-20251101"
  used="143k"
  total="200k"
  percent={71}
  categories={[
    { name: "System prompt", tokens: "2.8k", percent: 1.4, color: "system-prompt" },
    { name: "System tools", tokens: "16.2k", percent: 8.1, color: "system-tools" },
    { name: "MCP tools", tokens: "293", percent: 0.1, color: "mcp-tools" },
    { name: "Custom agents", tokens: "641", percent: 0.3, color: "custom-agents" },
    { name: "Memory files", tokens: "431", percent: 0.2, color: "memory-files" },
    { name: "Skills", tokens: "1.6k", percent: 0.8, color: "skills" },
    { name: "Messages", tokens: "122.9k", percent: 61.4, color: "messages" },
    { name: "Free space", tokens: "22k", percent: 11.1, color: "free" },
    { name: "Autocompact buffer", tokens: "33.0k", percent: 16.5, color: "buffer" },
  ]}
/>

This proves the delegation pattern worksthe main agent handled orchestration while subagents did the heavy lifting in isolated contexts.

## The Prompt Patterns

Here are the key prompt patterns that make this workflow effective:

### 1. Parallel Research

<Prompt>
spin up multiple subagents for your research task
</Prompt>

Triggers Claude to spawn parallel agents, each investigating independently. Much faster than sequential research.

### 2. Spec-First Development

<Prompt>
your goal is to write a report/document
</Prompt>

Forces Claude to produce a written artifact before any code. This becomes the source of truth.

### 3. Interview Before Implementation

<Prompt>
use the ask_user_question tool... before we implement
</Prompt>

Surfaces ambiguities and design decisions before they become bugs.

### 4. Task Delegation with Commits

<Prompt>
use the task tool and each task should only be done by a subagent
after each task do a commit before you continue
</Prompt>

Creates the orchestration pattern with atomic commits.

### 5. Role Assignment

<Prompt>
you are the main agent and your subagents are your devs
</Prompt>

Sets expectations for how Claude should behaveas a coordinator, not a solo implementer.

## Comparison: Traditional vs Spec-Driven

| | Traditional AI Coding | Spec-Driven Development |
|---|---|---|
| **Flow** | Prompt → Code → Debug → Repeat | Research → Spec → Refine → Tasks → Done |
| **Context** | Fills up with failed attempts | Each task gets fresh context |
| **Memory** | No persistence across sessions | Spec is persistent source of truth |
| **Bug tracking** | Discovered late, forgotten | Bugs become new tasks |
| **Completion** | No clear stopping point | Clear completion criteria |

## Advanced: Multi-Session Workflows

The task system supports coordination across multiple Claude Code sessions. Set a shared task list ID:

```bash
CLAUDE_CODE_TASK_LIST_ID=myproject claude
```

Or add to `.claude/settings.json`:

```json
{
  "env": {
    "CLAUDE_CODE_TASK_LIST_ID": "myproject"
  }
}
```

One session acts as **orchestrator**; another becomes a **checker** that monitors completed tasks, verifies implementation quality, and adds follow-up tasks for anything missing.

## When to Use This Workflow

This pattern excels for:

- **Large refactors** touching many files
- **Migrations** requiring research into external codebases
- **Feature implementations** with unclear requirements
- **Learning new libraries** by studying their source

It's overkill for:

- Small bug fixes
- Single-file changes
- Well-defined, simple features

## The Tools You Need

1. **Claude Code CLI** (latest version with task tools)
2. **A spec document** (markdown works great)
3. **Reference codebases** if learning from existing implementations
4. **Git** for atomic commits

## Further Reading

- [Beads](https://github.com/beads-ai/beads) Steve Yegge's git-backed issue tracker that inspired the task system
- [12 Factor Agents](https://www.humanlayer.dev/blog/12-factor-agents) Design principles for AI coding agents
- [Building Effective Agents](https://www.anthropic.com/research/building-effective-agents) Anthropic's research on agent architectures
- For a broader overview of Claude Code's feature stack, see my <InternalLink slug="understanding-claude-code-full-stack">comprehensive guide</InternalLink>

## Conclusion

Spec-Driven Development with Claude Code mirrors real engineering workflows: parallel work, handoffs, blockers, and dependencies. Instead of treating Claude as a solo coder, you treat it as a team.

The key insight from Beads applies here:

> "By having each task that you give a coding agent isolated into its own context window, you can now give it the ability to log any bugs for later."

The SQLite to IndexedDB migration would have taken me 2-3 days manually. With this workflow, it took one afternoonand produced better code thanks to the research phase uncovering patterns from Jazz I wouldn't have found on my own.

---

*Try it yourself: Start your next significant feature with "write a spec for X, spin up subagents for research" and see how it changes your workflow.*

---

--- title: My Opinionated ESLint + Oxlint Setup for Vue Projects description: A battle-tested linting configuration that catches real bugs, enforces clean architecture, and runs fast using Oxlint and ESLint together. tags: ['vue', 'typescript', 'tooling', 'architecture'] url: https://alexop.dev/posts/opinionated-eslint-setup-vue-projects ---

# My Opinionated ESLint + Oxlint Setup for Vue Projects



Over the last 7+ years as a Vue developer, I've developed a highly opinionated style for writing Vue components. Some of these rules might not be useful for you, but I thought it was worth sharing so you can pick what fits your project. The goal is to enforce code structure that's readable for both developers and AI agents.

These rules aren't arbitrary—they encode patterns I've written about extensively:

- <InternalLink slug="how-to-write-clean-vue-components">How to Write Clean Vue Components</InternalLink> explains why I separate business logic into pure functions
- <InternalLink slug="how-to-structure-vue-projects">How to Structure Vue Projects</InternalLink> covers my feature-based architecture approach
- <InternalLink slug="nuxt-layers-modular-monolith">Building a Modular Monolith with Nuxt Layers</InternalLink> applies feature isolation to Nuxt projects
- <InternalLink slug="the-problem-with-as-in-typescript-why-its-a-shortcut-we-should-avoid">The Problem with `as` in TypeScript</InternalLink> covers why I ban type assertions
- <InternalLink slug="robust-error-handling-in-typescript-a-journey-from-naive-to-rust-inspired-solutions">Robust Error Handling in TypeScript</InternalLink> introduces the Result pattern behind my `tryCatch` rule
- <InternalLink slug="vue3_testing_pyramid_vitest_browser_mode">Vue 3 Testing Pyramid</InternalLink> explains my integration-first testing strategy
- <InternalLink slug="frontend-testing-guide-10-essential-rules">Frontend Testing Guide</InternalLink> shares my test naming conventions

ESLint rules are how I enforce these patterns automatically—so the codebase stays consistent even as the team grows.

<Alert type="note">
**Why linting matters more in the AI era:** As AI agents write more of our code, strict linting becomes essential. It's a form of [back pressure](https://banay.me/dont-waste-your-backpressure/?ref=ghuntley.com)—automated feedback mechanisms that tell an agent when it's made a mistake, allowing it to self-correct without your intervention. You have a limited budget of feedback (your time and attention). If you spend that budget telling the agent "you missed an import" or "that type is wrong," you can't spend it on architectural decisions or complex logic. Type checkers, linters, and test suites act as back pressure: they push back against bad code so you don't have to. Your ESLint config is now part of your prompt—it's the automated quality gate that lets agents iterate until they pass.
</Alert>

## Table of Contents

## Why Two Linters? Oxlint + ESLint

I run two linters: **Oxlint** first, then **ESLint**. Why? Speed and coverage.

### Oxlint: The Speed Demon

[Oxlint](https://oxc.rs/docs/guide/usage/linter.html) is written in Rust. It runs 50-100x faster than ESLint on large codebases. My pre-commit hook completes in milliseconds instead of seconds.

```bash
# In package.json
"lint:oxlint": "oxlint . --fix --ignore-path .gitignore",
"lint:eslint": "eslint . --fix --cache",
"lint": "run-s lint:*"  # Runs oxlint first, then eslint
```

**The tradeoff:** Oxlint supports fewer rules. It handles:
- **Correctness & suspicious patterns** - catches bugs early
- **Core ESLint equivalents** - `no-console`, `no-explicit-any`
- **TypeScript basics** - `array-type`, `consistent-type-definitions`

But Oxlint lacks:
- Vue-specific rules (`vue/*`)
- Import boundary rules (`import-x/*`)
- Vitest testing rules (`vitest/*`)
- i18n rules (`@intlify/vue-i18n/*`)
- Custom local rules

### The Setup

Oxlint runs first for fast feedback. ESLint runs second for comprehensive checks. The `eslint-plugin-oxlint` package tells ESLint to skip rules that Oxlint already handles.

```typescript
// eslint.config.ts
export default defineConfigWithVueTs(
  // ... other configs
  ...pluginOxlint.buildFromOxlintConfigFile('./.oxlintrc.json'),
)
```

```json
// .oxlintrc.json
{
  "$schema": "./node_modules/oxlint/configuration_schema.json",
  "categories": {
    "correctness": "error",
    "suspicious": "warn"
  },
  "rules": {
    "typescript/no-explicit-any": "error",
    "eslint/no-console": ["error", { "allow": ["warn", "error"] }]
  }
}
```

---

## Must-Have Rules

These rules catch real bugs and enforce maintainable code. Enable them on every Vue project.

---

### Cyclomatic Complexity

Complex functions are hard to test and understand. This rule limits branching logic per function.

```typescript
// eslint.config.ts
{
  rules: {
    'complexity': ['warn', { max: 10 }]
  }
}
```

<CodeComparison>
  <Fragment slot="bad">
```typescript
function processOrder(order: Order) {
  if (order.status === 'pending') {
    if (order.items.length > 0) {
      if (order.payment) {
        if (order.payment.verified) {
          if (order.shipping) {
            // 5 levels deep, complexity keeps growing...
          }
        }
      }
    }
  }
}
```
  </Fragment>
  <Fragment slot="good">
```typescript
function processOrder(order: Order) {
  if (!isValidOrder(order)) return

  processPayment(order.payment)
  scheduleShipping(order.shipping)
}

function isValidOrder(order: Order): boolean {
  return order.status === 'pending'
    && order.items.length > 0
    && order.payment?.verified === true
}
```
  </Fragment>
</CodeComparison>

**Threshold guidance:**
- ESLint default: `20` (lenient)
- This project uses: `10` (stricter)
- Consider `15` as a middle ground for legacy codebases

> [ESLint: complexity](https://eslint.org/docs/latest/rules/complexity)

---

### No Nested Ternaries

Nested ternaries are hard to read. Use early returns or separate variables instead.

```typescript
// eslint.config.ts
{
  rules: {
    'no-nested-ternary': 'error'
  }
}
```

<CodeComparison>
  <Fragment slot="bad">
```typescript
const label = isLoading ? 'Loading...' : hasError ? 'Failed' : 'Success'
```
  </Fragment>
  <Fragment slot="good">
```typescript
function getLabel() {
  if (isLoading) return 'Loading...'
  if (hasError) return 'Failed'
  return 'Success'
}

const label = getLabel()
```
  </Fragment>
</CodeComparison>

> [ESLint: no-nested-ternary](https://eslint.org/docs/rules/no-nested-ternary)

---

### No Type Assertions

Type assertions (`as Type`) bypass TypeScript's type checker. They hide bugs. Use type guards or proper typing instead.

```typescript
// eslint.config.ts
{
  rules: {
    '@typescript-eslint/consistent-type-assertions': ['error', {
      assertionStyle: 'never'
    }]
  }
}
```

<Alert type="note">
`as const` assertions are always allowed, even with `assertionStyle: 'never'`. Const assertions don't bypass type checking—they make types more specific.
</Alert>

<CodeComparison>
  <Fragment slot="bad">
```typescript
const user = response.data as User  // What if it's not a User?

const element = document.querySelector('.btn') as HTMLButtonElement
element.click()  // Runtime error if element is null
```
  </Fragment>
  <Fragment slot="good">
```typescript
// Use type guards
function isUser(data: unknown): data is User {
  return typeof data === 'object'
    && data !== null
    && 'id' in data
    && 'name' in data
}

if (isUser(response.data)) {
  const user = response.data  // TypeScript knows it's User
}

// Handle nulls properly
const element = document.querySelector('.btn')
if (element instanceof HTMLButtonElement) {
  element.click()
}
```
  </Fragment>
</CodeComparison>

> [TypeScript ESLint: consistent-type-assertions](https://typescript-eslint.io/rules/consistent-type-assertions)

---

### No Enums

TypeScript enums have quirks. They generate JavaScript code, have numeric reverse mappings, and behave differently from union types. Use literal unions or const objects instead.

```typescript
// eslint.config.ts
{
  rules: {
    'no-restricted-syntax': ['error', {
      selector: 'TSEnumDeclaration',
      message: 'Use literal unions or `as const` objects instead of enums.'
    }]
  }
}
```

<CodeComparison>
  <Fragment slot="bad">
```typescript
enum Status {
  Pending,
  Active,
  Done
}

const status: Status = Status.Pending
```
  </Fragment>
  <Fragment slot="good">
```typescript
// Literal union - simplest
type Status = 'pending' | 'active' | 'done'

// Or const object when you need values
const Status = {
  Pending: 'pending',
  Active: 'active',
  Done: 'done'
} as const

type Status = typeof Status[keyof typeof Status]
```
  </Fragment>
</CodeComparison>

> [ESLint: no-restricted-syntax](https://eslint.org/docs/rules/no-restricted-syntax)

---

### No else/else-if

`else` and `else-if` blocks increase nesting. Early returns are easier to read and reduce cognitive load.

```typescript
// eslint.config.ts
{
  rules: {
    'no-restricted-syntax': ['error',
      {
        selector: 'IfStatement > IfStatement.alternate',
        message: 'Avoid `else if`. Prefer early returns or ternary operators.'
      },
      {
        selector: 'IfStatement > :not(IfStatement).alternate',
        message: 'Avoid `else`. Prefer early returns or ternary operators.'
      }
    ]
  }
}
```

<CodeComparison>
  <Fragment slot="bad">
```typescript
function getDiscount(user: User) {
  if (user.isPremium) {
    return 0.2
  } else if (user.isMember) {
    return 0.1
  } else {
    return 0
  }
}
```
  </Fragment>
  <Fragment slot="good">
```typescript
function getDiscount(user: User) {
  if (user.isPremium) return 0.2
  if (user.isMember) return 0.1
  return 0
}
```
  </Fragment>
</CodeComparison>

> [ESLint: no-restricted-syntax](https://eslint.org/docs/rules/no-restricted-syntax)

---

### No Native try/catch

Native try/catch blocks are verbose and error-prone. Use a utility function that returns a result tuple instead.

```typescript
// eslint.config.ts
{
  rules: {
    'no-restricted-syntax': ['error', {
      selector: 'TryStatement',
      message: 'Use tryCatch() from @/lib/tryCatch instead of try/catch. Returns Result<T> tuple: [error, null] | [null, data].'
    }]
  }
}
```

<CodeComparison>
  <Fragment slot="bad">
```typescript
async function fetchUser(id: string) {
  try {
    const response = await api.get(`/users/${id}`)
    return response.data
  } catch (error) {
    console.error(error)
    return null
  }
}
```
  </Fragment>
  <Fragment slot="good">
```typescript
async function fetchUser(id: string) {
  const [error, response] = await tryCatch(api.get(`/users/${id}`))

  if (error) {
    console.error(error)
    return null
  }

  return response.data
}
```
  </Fragment>
</CodeComparison>

The `tryCatch` utility returns `[error, null]` or `[null, data]`, similar to Go's error handling.

> [ESLint: no-restricted-syntax](https://eslint.org/docs/rules/no-restricted-syntax)

---

### No Direct DOM Manipulation

Vue manages the DOM. Calling `document.querySelector` bypasses Vue's reactivity and template refs. Use `useTemplateRef()` instead. If you're on Vue 3.5+, the built-in rule already enforces this.

```typescript
// eslint.config.ts
{
  files: ['src/**/*.vue'],
  rules: {
    'vue/prefer-use-template-ref': 'error'
  }
}
```

<CodeComparison>
  <Fragment slot="bad">
```vue
<script setup lang="ts">
function focusInput() {
  const input = document.getElementById('my-input')
  input?.focus()
}
</script>

<template>
  
</template>
```
  </Fragment>
  <Fragment slot="good">
```vue
<script setup lang="ts">
const inputRef = useTemplateRef<HTMLInputElement>('input')

function focusInput() {
  inputRef.value?.focus()
}
</script>

<template>
  
</template>
```
  </Fragment>
</CodeComparison>

> [ESLint: no-restricted-syntax](https://eslint.org/docs/rules/no-restricted-syntax)

---

### Feature Boundary Enforcement

Features should not import from other features. This keeps code modular and prevents circular dependencies. If you're using a feature-based architecture, this rule is essential—see <InternalLink slug="how-to-structure-vue-projects">How to Structure Vue Projects</InternalLink> for more on this approach.

```typescript
// eslint.config.ts
{
  plugins: { 'import-x': pluginImportX },
  rules: {
    'import-x/no-restricted-paths': ['error', {
      zones: [
        // === CROSS-FEATURE ISOLATION ===
        // Features cannot import from other features
        { target: './src/features/workout', from: './src/features', except: ['./workout'] },
        { target: './src/features/exercises', from: './src/features', except: ['./exercises'] },
        { target: './src/features/settings', from: './src/features', except: ['./settings'] },
        { target: './src/features/timers', from: './src/features', except: ['./timers'] },
        { target: './src/features/templates', from: './src/features', except: ['./templates'] },
        { target: './src/features/benchmarks', from: './src/features', except: ['./benchmarks'] },

        // === UNIDIRECTIONAL FLOW ===
        // Shared code cannot import from features or views
        {
          target: ['./src/components', './src/composables', './src/lib', './src/db', './src/types', './src/stores'],
          from: ['./src/features', './src/views']
        },

        // Features cannot import from views (views are top-level orchestrators)
        { target: './src/features', from: './src/views' }
      ]
    }]
  }
}
```

**Unidirectional Flow:** The architecture enforces a strict dependency hierarchy. Views orchestrate features, features use shared code, but never the reverse.

```
views → features → shared (components, composables, lib, db, types, stores)
```

<CodeComparison>
  <Fragment slot="bad">
```typescript
// src/features/workout/composables/useWorkout.ts
// Cross-feature import!
```
  </Fragment>
  <Fragment slot="good">
```typescript
// src/features/workout/composables/useWorkout.ts
// Use shared database layer instead
```
  </Fragment>
</CodeComparison>

> [eslint-plugin-import-x: no-restricted-paths](https://github.com/un-ts/eslint-plugin-import-x)

---

### Vue Component Naming

Consistent naming makes components easy to find and identify.

```typescript
// eslint.config.ts
{
  files: ['src/**/*.vue'],
  rules: {
    'vue/multi-word-component-names': ['error', {
      ignores: ['App', 'Layout']
    }],
    'vue/component-definition-name-casing': ['error', 'PascalCase'],
    'vue/component-name-in-template-casing': ['error', 'PascalCase', {
      registeredComponentsOnly: false
    }],
    'vue/match-component-file-name': ['error', {
      extensions: ['vue'],
      shouldMatchCase: true
    }],
    'vue/prop-name-casing': ['error', 'camelCase'],
    'vue/attribute-hyphenation': ['error', 'always'],
    'vue/custom-event-name-casing': ['error', 'kebab-case']
  }
}
```

<CodeComparison>
  <Fragment slot="bad">
```vue
<!-- File: button.vue -->
<template>
  <base-button>Click</base-button>
</template>
```
  </Fragment>
  <Fragment slot="good">
```vue
<!-- File: SubmitButton.vue -->
<template>
  <BaseButton>Click</BaseButton>
</template>
```
  </Fragment>
</CodeComparison>

> [eslint-plugin-vue: component rules](https://eslint.vuejs.org/rules/)

---

### Dead Code Detection in Vue

Find unused props, refs, and emits before they become tech debt.

```typescript
// eslint.config.ts
{
  files: ['src/**/*.vue'],
  rules: {
    'vue/no-unused-properties': ['error', {
      groups: ['props', 'data', 'computed', 'methods']
    }],
    'vue/no-unused-refs': 'error',
    'vue/no-unused-emit-declarations': 'error'
  }
}
```

<CodeComparison>
  <Fragment slot="bad">
```vue
<script setup lang="ts">
const props = defineProps<{
  title: string
  subtitle: string  // Never used!
}>()

const emit = defineEmits<{
  (e: 'click'): void
  (e: 'hover'): void  // Never emitted!
}>()

const buttonRef = ref<HTMLButtonElement>()  // Never used!
</script>

<template>
  <h1>{{ title }}</h1>
  <button @click="emit('click')">Click</button>
</template>
```
  </Fragment>
  <Fragment slot="good">
```vue
<script setup lang="ts">
const props = defineProps<{
  title: string
}>()

const emit = defineEmits<{
  (e: 'click'): void
}>()
</script>

<template>
  <h1>{{ title }}</h1>
  <button @click="emit('click')">Click</button>
</template>
```
  </Fragment>
</CodeComparison>

> [eslint-plugin-vue: no-unused-properties](https://eslint.vuejs.org/rules/no-unused-properties.html)

---

### No Hardcoded i18n Strings

Hardcoded strings break internationalization. The `@intlify/vue-i18n` plugin catches them.

```typescript
// eslint.config.ts
{
  files: ['src/**/*.vue'],
  plugins: { '@intlify/vue-i18n': pluginVueI18n },
  rules: {
    '@intlify/vue-i18n/no-raw-text': ['error', {
      ignorePattern: '^[-#:()&+×/°′″%]+',
      ignoreText: ['kg', 'lbs', 'cm', 'ft/in', '—', '•', '✓', '›', '→', '·', '.', 'Close'],
      attributes: {
        '/.+/': ['title', 'aria-label', 'aria-placeholder', 'placeholder', 'alt']
      }
    }]
  }
}
```

The `attributes` option catches hardcoded strings in accessibility attributes too.

<CodeComparison>
  <Fragment slot="bad">
```vue
<template>
  <button>Save Changes</button>
  <p>No items found</p>
</template>
```
  </Fragment>
  <Fragment slot="good">
```vue
<template>
  <button>{{ t('common.save') }}</button>
  <p>{{ t('items.empty') }}</p>
</template>
```
  </Fragment>
</CodeComparison>

> [eslint-plugin-vue-i18n](https://eslint-plugin-vue-i18n.intlify.dev/)

---

### No Disabling i18n Rules

Prevent developers from bypassing i18n checks with `eslint-disable` comments.

```typescript
// eslint.config.ts
{
  files: ['src/**/*.vue'],
  plugins: {
    '@eslint-community/eslint-comments': pluginEslintComments
  },
  rules: {
    '@eslint-community/eslint-comments/no-restricted-disable': [
      'error',
      '@intlify/vue-i18n/*'
    ]
  }
}
```

<CodeComparison>
  <Fragment slot="bad">
```vue
<!-- eslint-disable-next-line @intlify/vue-i18n/no-raw-text -->
<button>Save Changes</button>
```
  </Fragment>
  <Fragment slot="good">
```vue
<button>{{ t('common.save') }}</button>
```
  </Fragment>
</CodeComparison>

> [@eslint-community/eslint-plugin-eslint-comments](https://github.com/eslint-community/eslint-plugin-eslint-comments)

---

### No Hardcoded Route Strings

Use named routes instead of hardcoded path strings for maintainability.

```typescript
// eslint.config.ts
{
  rules: {
    'no-restricted-syntax': ['error',
      {
        selector: 'CallExpression[callee.property.name="push"][callee.object.name="router"] > Literal:first-child',
        message: 'Use named routes with RouteNames instead of hardcoded path strings.'
      },
      {
        selector: 'CallExpression[callee.property.name="push"][callee.object.name="router"] > TemplateLiteral:first-child',
        message: 'Use named routes with RouteNames instead of template literals.'
      }
    ]
  }
}
```

<CodeComparison>
  <Fragment slot="bad">
```typescript
router.push('/workout/123')
router.push(`/workout/${id}`)
```
  </Fragment>
  <Fragment slot="good">
```typescript
router.push({ name: RouteNames.WorkoutDetail, params: { id } })
```
  </Fragment>
</CodeComparison>

> [ESLint: no-restricted-syntax](https://eslint.org/docs/latest/rules/no-restricted-syntax)

---

### Enforce Integration Test Helpers

Ban direct `render()` or `mount()` calls in tests. Use a centralized test helper instead. For more on testing strategies in Vue, see <InternalLink slug="vue3_testing_pyramid_vitest_browser_mode">Vue 3 Testing Pyramid: A Practical Guide with Vitest Browser Mode</InternalLink>.

```typescript
// eslint.config.ts
{
  files: ['src/**/__tests__/**/*.{ts,spec.ts}'],
  ignores: ['src/__tests__/helpers/**'],
  rules: {
    'no-restricted-imports': ['error', {
      paths: [
        {
          name: 'vitest-browser-vue',
          importNames: ['render'],
          message: 'Use createTestApp() from @/__tests__/helpers/createTestApp instead.'
        },
        {
          name: '@vue/test-utils',
          importNames: ['mount', 'shallowMount'],
          message: 'Use createTestApp() instead of mounting components directly.'
        }
      ]
    }]
  }
}
```

<CodeComparison>
  <Fragment slot="bad">
```typescript
const { getByText } = render(MyComponent)
const wrapper = mount(MyComponent)
```
  </Fragment>
  <Fragment slot="good">
```typescript
const { page } = await createTestApp({ route: '/workout' })
```
  </Fragment>
</CodeComparison>

This ensures all tests use consistent setup with routing, i18n, and database.

> [ESLint: no-restricted-imports](https://eslint.org/docs/latest/rules/no-restricted-imports)

---

### Enforce pnpm Catalogs

When using pnpm workspaces, enforce that dependencies use catalog references.

```typescript
// eslint.config.ts
export default defineConfigWithVueTs(
  // ... other configs
  ...pnpmConfigs.recommended,
)
```

This ensures dependencies are managed centrally in `pnpm-workspace.yaml`.

> [eslint-plugin-pnpm](https://github.com/nickmccurdy/eslint-plugin-pnpm)

---

## Nice-to-Have Rules

These rules improve code quality but are less critical. Enable them after the must-haves are in place.

---

### Vue 3.5+ API Enforcement

Use the latest Vue 3.5 APIs for cleaner code.

```typescript
// eslint.config.ts
{
  files: ['src/**/*.vue'],
  rules: {
    'vue/define-props-destructuring': 'error',
    'vue/prefer-use-template-ref': 'error'
  }
}
```

<CodeComparison badTitle="Before Vue 3.5" goodTitle="Vue 3.5+">
  <Fragment slot="bad">
```vue
<script setup lang="ts">
const props = defineProps<{ count: number }>()
const buttonRef = ref<HTMLButtonElement>()

console.log(props.count)  // Using props. prefix
</script>

<template>
  <button ref="buttonRef">Click</button>
</template>
```
  </Fragment>
  <Fragment slot="good">
```vue
<script setup lang="ts">
const { count } = defineProps<{ count: number }>()
const buttonRef = useTemplateRef<HTMLButtonElement>('button')

console.log(count)  // Direct destructured access
</script>

<template>
  <button ref="button">Click</button>
</template>
```
  </Fragment>
</CodeComparison>

> [eslint-plugin-vue: define-props-destructuring](https://eslint.vuejs.org/rules/define-props-destructuring.html)

---

### Explicit Component APIs

Require `defineExpose` and `defineSlots` to make component interfaces explicit.

```typescript
// eslint.config.ts
{
  files: ['src/**/*.vue'],
  rules: {
    'vue/require-expose': 'warn',
    'vue/require-explicit-slots': 'warn'
  }
}
```

<CodeComparison>
  <Fragment slot="bad">
```vue
<script setup lang="ts">
function focus() { /* ... */ }
</script>

<template>
  
</template>
```
  </Fragment>
  <Fragment slot="good">
```vue
<script setup lang="ts">
defineSlots<{
  default(): unknown
}>()

function focus() { /* ... */ }

defineExpose({ focus })
</script>

<template>
  
</template>
```
  </Fragment>
</CodeComparison>

> [eslint-plugin-vue: require-expose](https://eslint.vuejs.org/rules/require-expose.html)

---

### Template Depth Limit

Deep template nesting is hard to read. Extract nested sections into components. This one matters a lot—it helps you avoid ending up with components that are 2000 lines long.

```typescript
// eslint.config.ts
{
  files: ['src/**/*.vue'],
  rules: {
    'vue/max-template-depth': ['error', { maxDepth: 8 }],
    'vue/max-props': ['error', { maxProps: 6 }]
  }
}
```

<CodeComparison>
  <Fragment slot="bad">
```vue
<template>
  <div>
    <div>
      <div>
        <div>
          <div>
            <div>
              <div>
                <div>
                  <span>Too deep!</span>
                </div>
              </div>
            </div>
          </div>
        </div>
      </div>
    </div>
  </div>
</template>
```
  </Fragment>
  <Fragment slot="good">
```vue
<template>
  <Card>
    <CardHeader>
      <CardTitle>Title</CardTitle>
    </CardHeader>
    <CardContent>
      <span>Content</span>
    </CardContent>
  </Card>
</template>
```
  </Fragment>
</CodeComparison>

> [eslint-plugin-vue: max-template-depth](https://eslint.vuejs.org/rules/max-template-depth.html)

---

### Better Assertions in Tests

Use specific matchers for clearer test failures.

```typescript
// eslint.config.ts
{
  files: ['src/**/__tests__/*'],
  rules: {
    'vitest/prefer-to-be': 'error',
    'vitest/prefer-to-have-length': 'error',
    'vitest/prefer-to-contain': 'error',
    'vitest/prefer-mock-promise-shorthand': 'error'
  }
}
```

<CodeComparison>
  <Fragment slot="bad">
```typescript
expect(value === null).toBe(true)
expect(arr.length).toBe(3)
expect(arr.includes('foo')).toBe(true)
```
  </Fragment>
  <Fragment slot="good">
```typescript
expect(value).toBeNull()
expect(arr).toHaveLength(3)
expect(arr).toContain('foo')

// Also prefer mock shorthands
vi.fn().mockResolvedValue('data')  // Instead of mockReturnValue(Promise.resolve('data'))
```
  </Fragment>
</CodeComparison>

> [eslint-plugin-vitest](https://github.com/veritem/eslint-plugin-vitest)

---

### Test Structure Rules

Keep tests organized and readable.

```typescript
// eslint.config.ts
{
  files: ['src/**/__tests__/*'],
  rules: {
    'vitest/consistent-test-it': ['error', { fn: 'it' }],
    'vitest/prefer-hooks-on-top': 'error',
    'vitest/prefer-hooks-in-order': 'error',
    'vitest/no-duplicate-hooks': 'error',
    'vitest/require-top-level-describe': 'error',
    'vitest/max-nested-describe': ['error', { max: 2 }],
    'vitest/no-conditional-in-test': 'warn'
  }
}
```

<CodeComparison>
  <Fragment slot="bad">
```typescript
test('works', () => {})  // Inconsistent: test vs it
it('also works', () => {})

describe('feature', () => {
  it('test 1', () => {})

  beforeEach(() => {})  // Hook after test!

  describe('nested', () => {
    describe('too deep', () => {
      describe('way too deep', () => {})  // 3 levels!
    })
  })
})
```
  </Fragment>
  <Fragment slot="good">
```typescript
describe('feature', () => {
  beforeEach(() => {})  // Hooks first, in order

  it('does something', () => {})
  it('does another thing', () => {})

  describe('edge cases', () => {
    it('handles null', () => {})
  })
})

// no-conditional-in-test prevents flaky tests
// Bad: if (data.length > 0) { expect(data[0]).toBeDefined() }
// Good: expect(data).toHaveLength(3); expect(data[0]).toBeDefined()
```
  </Fragment>
</CodeComparison>

> [eslint-plugin-vitest](https://github.com/veritem/eslint-plugin-vitest)

---

### Prefer Vitest Locators in Tests

Use Vitest Browser locators instead of raw DOM queries.

```typescript
// eslint.config.ts
{
  files: ['src/**/__tests__/**/*.{ts,spec.ts}'],
  rules: {
    'no-restricted-syntax': ['warn', {
      selector: 'CallExpression[callee.property.name=/^querySelector(All)?$/]',
      message: 'Prefer page.getByRole(), page.getByText(), or page.getByTestId() over querySelector. Vitest locators are more resilient to DOM changes.'
    }]
  }
}
```

<CodeComparison>
  <Fragment slot="bad">
```typescript
const button = container.querySelector('.submit-btn')
await button?.click()
```
  </Fragment>
  <Fragment slot="good">
```typescript
const button = page.getByRole('button', { name: 'Submit' })
await button.click()
```
  </Fragment>
</CodeComparison>

> [Vitest Browser Mode](https://vitest.dev/guide/browser/)

---

### Unicorn Rules

The `eslint-plugin-unicorn` package catches common mistakes and enforces modern JavaScript patterns.

```typescript
// eslint.config.ts
pluginUnicorn.configs.recommended,

{
  name: 'app/unicorn-overrides',
  rules: {
    // === Enable non-recommended rules that add value ===
    'unicorn/better-regex': 'warn',              // Simplify regexes: /[0-9]/ → /\d/
    'unicorn/custom-error-definition': 'error',  // Correct Error subclassing
    'unicorn/no-unused-properties': 'warn',      // Dead code detection
    'unicorn/consistent-destructuring': 'warn',  // Use destructured vars consistently

    // === Disable rules that conflict with project conventions ===
    'unicorn/no-null': 'off',                    // We use null for database values
    'unicorn/filename-case': 'off',              // Vue uses PascalCase, tests use camelCase
    'unicorn/prevent-abbreviations': 'off',      // props, e, Db are fine
    'unicorn/no-array-callback-reference': 'off', // arr.filter(isValid) is fine
    'unicorn/no-await-expression-member': 'off', // (await fetch()).json() is fine
    'unicorn/no-array-reduce': 'off',            // reduce is useful for aggregations
    'unicorn/no-useless-undefined': 'off'        // mockResolvedValue(undefined) for TS
  }
}
```

**Examples:**

```typescript
// unicorn/better-regex
// Bad:  /[0-9]/
// Good: /\d/

// unicorn/consistent-destructuring
// Bad:
const { foo } = object
console.log(object.bar)  // Uses object.bar instead of destructuring

// Good:
const { foo, bar } = object
console.log(bar)
```

> [eslint-plugin-unicorn](https://github.com/sindresorhus/eslint-plugin-unicorn)

---

## Custom Local Rules

Sometimes you need rules that don't exist. Write them yourself.

### Composable Must Use Vue

A file named `use*.ts` should import from Vue. If it doesn't, it's a utility, not a composable. For more on writing proper composables, see <InternalLink slug="vueuse_composables_style_guide">Vue Composables Style Guide: Lessons from VueUse's Codebase</InternalLink>.

```typescript
// eslint-local-rules/composable-must-use-vue.ts
const VALID_VUE_SOURCES = new Set(['vue', '@vueuse/core', 'vue-router', 'vue-i18n'])
const VALID_PATH_PATTERNS = [/^@\/stores\//]  // Global state composables count too

function isComposableFilename(filename: string): boolean {
  return /^use[A-Z]/.test(path.basename(filename, '.ts'))
}

const rule: Rule.RuleModule = {
  meta: {
    messages: {
      notAComposable: 'File "{{filename}}" does not import from Vue. Rename it or add Vue imports.'
    }
  },
  create(context) {
    if (!isComposableFilename(context.filename)) return {}

    let hasVueImport = false

    return {
      ImportDeclaration(node) {
        if (VALID_VUE_SOURCES.has(node.source.value)) {
          hasVueImport = true
        }
      },
      'Program:exit'(node) {
        if (!hasVueImport) {
          context.report({ node, messageId: 'notAComposable' })
        }
      }
    }
  }
}
```

<CodeComparison>
  <Fragment slot="bad">
```typescript
// src/composables/useFormatter.ts
export function useFormatter() {
  return {
    formatDate: (d: Date) => d.toISOString()  // No Vue imports!
  }
}
```
  </Fragment>
  <Fragment slot="good">
```typescript
// src/lib/formatter.ts (renamed)
export function formatDate(d: Date) {
  return d.toISOString()
}

// OR add Vue reactivity:
// src/composables/useFormatter.ts
export function useFormatter() {
  const locale = ref('en-US')
  const formatter = computed(() => new Intl.DateTimeFormat(locale.value))
  return { formatter, locale }
}
```
  </Fragment>
</CodeComparison>

---

### No Hardcoded Tailwind Colors

Hardcoded Tailwind colors (`bg-blue-500`) make theming impossible. Use semantic colors (`bg-primary`).

```typescript
// eslint-local-rules/no-hardcoded-colors.ts
// Status colors (red, amber, yellow, green, emerald) are ALLOWED for semantic states
const HARDCODED_COLORS = ['slate', 'gray', 'zinc', 'blue', 'purple', 'pink', 'orange', 'indigo', 'violet']
const COLOR_UTILITIES = ['bg', 'text', 'border', 'ring', 'fill', 'stroke']

const rule: Rule.RuleModule = {
  meta: {
    messages: {
      noHardcodedColor: 'Avoid "{{color}}". Use semantic classes like bg-primary, text-foreground.'
    }
  },
  create(context) {
    return {
      Literal(node) {
        if (typeof node.value !== 'string') return

        const matches = findHardcodedColors(node.value)
        for (const color of matches) {
          context.report({ node, messageId: 'noHardcodedColor', data: { color } })
        }
      }
    }
  }
}
```

<CodeComparison>
  <Fragment slot="bad">
```vue
<template>
  <button class="bg-blue-500 text-white">Click</button>
</template>
```
  </Fragment>
  <Fragment slot="good">
```vue
<template>
  <button class="bg-primary text-primary-foreground">Click</button>
</template>
```
  </Fragment>
</CodeComparison>

<Alert type="note">
Status colors (`red`, `amber`, `yellow`, `green`, `emerald`) are intentionally allowed for error/warning/success states. Only use these for semantic status indication, not general styling.
</Alert>

---

### No let in describe Blocks

Mutable variables in test describe blocks create hidden state. Use setup functions instead.

```typescript
// eslint-local-rules/no-let-in-describe.ts
const rule: Rule.RuleModule = {
  meta: {
    messages: {
      noLetInDescribe: 'Avoid `let` in describe blocks. Use setup functions instead.'
    }
  },
  create(context) {
    let describeDepth = 0

    return {
      CallExpression(node) {
        if (isDescribeCall(node)) describeDepth++
      },
      'CallExpression:exit'(node) {
        if (isDescribeCall(node)) describeDepth--
      },
      VariableDeclaration(node) {
        if (describeDepth > 0 && node.kind === 'let') {
          context.report({ node, messageId: 'noLetInDescribe' })
        }
      }
    }
  }
}
```

<CodeComparison>
  <Fragment slot="bad">
```typescript
describe('Login', () => {
  let user: User

  beforeEach(() => {
    user = createUser()  // Hidden mutation!
  })

  it('works', () => {
    expect(user.name).toBe('test')
  })
})
```
  </Fragment>
  <Fragment slot="good">
```typescript
describe('Login', () => {
  function setup() {
    return { user: createUser() }
  }

  it('works', () => {
    const { user } = setup()
    expect(user.name).toBe('test')
  })
})
```
  </Fragment>
</CodeComparison>

---

### Extract Complex Conditions

Complex boolean expressions should have names. Extract them into variables.

```typescript
// eslint-local-rules/extract-condition-variable.ts
const OPERATOR_THRESHOLD = 2  // Conditions with 2+ logical operators need extraction

const rule: Rule.RuleModule = {
  meta: {
    messages: {
      extractCondition: 'Complex condition should be extracted into a named const.'
    }
  },
  create(context) {
    return {
      IfStatement(node) {
        // Skip patterns that TypeScript needs inline for narrowing
        if (isEarlyExitGuard(node.consequent)) return  // if (!x) return
        if (hasOptionalChaining(node.test)) return      // if (user?.name)
        if (hasTruthyNarrowingPattern(node.test)) return // if (arr && arr[0])

        if (countOperators(node.test) >= OPERATOR_THRESHOLD) {
          context.report({ node: node.test, messageId: 'extractCondition' })
        }
      }
    }
  }
}
```

**Smart Exceptions:** The rule skips several patterns that TypeScript needs inline for type narrowing:
- Early exit guards: `if (!user) return`
- Optional chaining: `if (user?.name)`
- Truthy narrowing: `if (arr && arr[0])`

<CodeComparison>
  <Fragment slot="bad">
```typescript
if (user.isActive && user.role === 'admin' && !user.isBanned) {
  showAdminPanel()
}
```
  </Fragment>
  <Fragment slot="good">
```typescript
const canAccessAdminPanel = user.isActive && user.role === 'admin' && !user.isBanned

if (canAccessAdminPanel) {
  showAdminPanel()
}
```
  </Fragment>
</CodeComparison>

---

### Repository tryCatch Wrapper

Database calls can fail. Enforce wrapping them in `tryCatch()`.

```typescript
// eslint-local-rules/repository-trycatch.ts
// Matches pattern: get*Repository().method()
const REPO_PATTERN = /^get\w+Repository$/

const rule: Rule.RuleModule = {
  meta: {
    messages: {
      missingTryCatch: 'Repository calls must be wrapped with tryCatch().'
    }
  },
  create(context) {
    return {
      AwaitExpression(node) {
        if (!isRepositoryMethodCall(node.argument)) return
        if (isWrappedInTryCatch(context, node)) return

        context.report({ node, messageId: 'missingTryCatch' })
      }
    }
  }
}
```

<CodeComparison>
  <Fragment slot="bad">
```typescript
const workouts = await getWorkoutRepository().findAll()  // Might throw!
```
  </Fragment>
  <Fragment slot="good">
```typescript
const [error, workouts] = await tryCatch(getWorkoutRepository().findAll())

if (error) {
  showError('Failed to load workouts')
  return
}
```
  </Fragment>
</CodeComparison>

<Alert type="note">
This rule matches the `get*Repository()` pattern. Ensure your repository factory functions follow this naming convention.
</Alert>

---

## The Full Config

<Collapsible title="Complete eslint.config.ts example">

```typescript
export default defineConfigWithVueTs(
  { ignores: ['**/dist/**', '**/coverage/**', '**/node_modules/**'] },

  pluginVue.configs['flat/essential'],
  vueTsConfigs.recommended,
  pluginUnicorn.configs.recommended,

  // Vue component rules
  {
    files: ['src/**/*.vue'],
    rules: {
      'vue/multi-word-component-names': ['error', { ignores: ['App', 'Layout'] }],
      'vue/component-name-in-template-casing': ['error', 'PascalCase'],
      'vue/prop-name-casing': ['error', 'camelCase'],
      'vue/custom-event-name-casing': ['error', 'kebab-case'],
      'vue/no-unused-properties': ['error', { groups: ['props', 'data', 'computed', 'methods'] }],
      'vue/no-unused-refs': 'error',
      'vue/define-props-destructuring': 'error',
      'vue/prefer-use-template-ref': 'error',
      'vue/max-template-depth': ['error', { maxDepth: 8 }],
    },
  },

  // TypeScript style guide
  {
    files: ['src/**/*.{ts,vue}'],
    rules: {
      'complexity': ['warn', { max: 10 }],
      'no-nested-ternary': 'error',
      '@typescript-eslint/consistent-type-assertions': ['error', { assertionStyle: 'never' }],
      'no-restricted-syntax': ['error',
        { selector: 'TSEnumDeclaration', message: 'Use literal unions instead of enums.' },
        { selector: 'IfStatement > :not(IfStatement).alternate', message: 'Avoid else. Use early returns.' },
        { selector: 'TryStatement', message: 'Use tryCatch() instead of try/catch.' },
      ],
    },
  },

  // Feature boundaries
  {
    files: ['src/**/*.{ts,vue}'],
    plugins: { 'import-x': pluginImportX },
    rules: {
      'import-x/no-restricted-paths': ['error', {
        zones: [
          { target: './src/features/workout', from: './src/features', except: ['./workout'] },
          // ... other features
          { target: './src/features', from: './src/views' },  // Unidirectional flow
        ]
      }],
    },
  },

  // i18n rules
  {
    files: ['src/**/*.vue'],
    plugins: { '@intlify/vue-i18n': pluginVueI18n },
    rules: {
      '@intlify/vue-i18n/no-raw-text': ['error', { /* config */ }],
    },
  },

  // Prevent disabling i18n rules
  {
    files: ['src/**/*.vue'],
    plugins: { '@eslint-community/eslint-comments': pluginEslintComments },
    rules: {
      '@eslint-community/eslint-comments/no-restricted-disable': ['error', '@intlify/vue-i18n/*'],
    },
  },

  // Vitest rules
  {
    files: ['src/**/__tests__/*'],
    ...pluginVitest.configs.recommended,
    rules: {
      'vitest/consistent-test-it': ['error', { fn: 'it' }],
      'vitest/prefer-hooks-on-top': 'error',
      'vitest/prefer-hooks-in-order': 'error',
      'vitest/no-duplicate-hooks': 'error',
      'vitest/max-nested-describe': ['error', { max: 2 }],
      'vitest/no-conditional-in-test': 'warn',
    },
  },

  // Enforce test helpers
  {
    files: ['src/**/__tests__/**/*.{ts,spec.ts}'],
    rules: {
      'no-restricted-imports': ['error', {
        paths: [
          { name: 'vitest-browser-vue', importNames: ['render'], message: 'Use createTestApp()' },
          { name: '@vue/test-utils', importNames: ['mount'], message: 'Use createTestApp()' },
        ]
      }],
    },
  },

  // Local rules
  {
    files: ['src/**/*.{ts,vue}'],
    plugins: { local: localRules },
    rules: {
      'local/no-hardcoded-colors': 'error',
      'local/composable-must-use-vue': 'error',
      'local/repository-trycatch': 'error',
      'local/extract-condition-variable': 'error',
      'local/no-let-in-describe': 'error',
    },
  },

  // Disable rules handled by Oxlint
  ...pluginOxlint.buildFromOxlintConfigFile('./.oxlintrc.json'),

  // pnpm catalog enforcement
  ...pnpmConfigs.recommended,

  skipFormatting,
)
```

</Collapsible>

---

## Summary

| Category | Rule | Purpose |
|----------|------|---------|
| **Must Have** | `complexity` | Limit function complexity |
| **Must Have** | `no-nested-ternary` | Readable conditionals |
| **Must Have** | `consistent-type-assertions` | No unsafe `as` casts |
| **Must Have** | `no-restricted-syntax` (enums) | Use unions over enums |
| **Must Have** | `no-restricted-syntax` (else) | Prefer early returns |
| **Must Have** | `no-restricted-syntax` (routes) | Use named routes |
| **Must Have** | `import-x/no-restricted-paths` | Feature isolation |
| **Must Have** | `vue/no-unused-*` | Dead code detection |
| **Must Have** | `@intlify/vue-i18n/no-raw-text` | i18n compliance |
| **Must Have** | `no-restricted-disable` | No bypassing i18n |
| **Must Have** | `no-restricted-imports` | Enforce test helpers |
| **Nice to Have** | `vue/define-props-destructuring` | Vue 3.5 patterns |
| **Nice to Have** | `vue/max-template-depth` | Template readability |
| **Nice to Have** | `vitest/*` | Test consistency |
| **Nice to Have** | `unicorn/*` | Modern JavaScript |
| **Nice to Have** | `pnpm/recommended` | Catalog enforcement |
| **Custom** | `composable-must-use-vue` | Composable validation |
| **Custom** | `no-hardcoded-colors` | Theming support |
| **Custom** | `no-let-in-describe` | Clean tests |
| **Custom** | `extract-condition-variable` | Readable conditions |
| **Custom** | `repository-trycatch` | Error handling |

Start with the must-haves. Add nice-to-haves when you're ready. Write custom rules when nothing else fits.

The combination of Oxlint for speed and ESLint for coverage gives you fast feedback during development and comprehensive checks in CI.

---

--- title: Next Level GitHub Copilot: Agents, Instructions & Automation in VS Code description: Workshop covering the transformation from LLM to Agent, context engineering, AGENTS.md, subagents, and skills in VS Code Copilot. tags: ['vs-code', 'github-copilot', 'ai-agents', 'context-engineering', 'workshop'] url: https://alexop.dev/posts/vs-code-copilot-workshop ---

# Next Level GitHub Copilot: Agents, Instructions & Automation in VS Code



# Next Level GitHub Copilot

Agents.md Subagents & Skills

by Alexander Opalic

---

---

## Workshop Outline

<VClicks>

1. What is an Agent? (LLM → Agent transformation)
2. Context Engineering (the real skill)
3. Back Pressure (core validation concept)
4. AGENTS.md (open standard)
5. Subagents (specialized invocation)
6. Skills (portable workflows)
7. Live Demo

</VClicks>

---

## 🙋 Who has used GitHub Copilot in VS Code?

---

## About me

<div class="flex flex-col items-center">
  
  <h2 class="mt-4">Alex Opalic</h2>
</div>

<VClicks>

* 🚀 7 years expierence as a full stack developer 
* 💼 Developer at Otto Payments
* 🏡 Based in Geretsried (south of Munich, Bavaria)
* ✍️ Blogger at alexop.dev
* 🎤 Sharing & speaking about Vue, testing & GraphQL & AI

</VClicks>

---

# What is an Agent?

---

## The Transformation: LLM → Agent

- At the beginning, an LLM is just a text generator
- One problem: the LLM didn't have access to current news
- Solution: all providers gave the LLM access to tools
- With tools, the LLM can now interact with the world
- This is why an agent is an LLM + Tools + Agentic Loop

---

---

## The Agentic Loop (nanocode)

```shell
nanocode | claude-opus-4-5 | /Users/alexanderopalic/Projects/typescript/nanocode

────────────────────────────────────────────────────────────────────────────────
❯  create a simple typescript file as a sum function
────────────────────────────────────────────────────────────────────────────────
[agentLoop] Starting with 1 messages
[agentLoop] Got response, stop_reason: tool_use

⏺ Write(src/sum.ts)
  ⎿  ok
[agentLoop] Starting with 3 messages
[agentLoop] Got response, stop_reason: end_turn

⏺ Created `src/sum.ts` with a simple sum function that takes two numbers and returns their sum.
```

**~350 lines of TypeScript** to understand how Claude Code works.

---

## The Agentic Loop (Code)

```typescript
async function agentLoop(messages: Message[], systemPrompt: string): Promise<Message[]> {
  const response = await callApi(messages, systemPrompt)
  printResponse(response)

  const toolResults = await processToolCalls(response.content)
  const newMessages = [...messages, { role: 'assistant', content: response.content }]

  if (toolResults.length === 0) {
    return newMessages  // No tools called, we're done
  }

  return agentLoop(  // Loop again with tool results
    [...newMessages, { role: 'user', content: toolResults }],
    systemPrompt
  )
}
```

The entire request → response → execute → loop cycle in ~15 lines.

---

## Tool Registration

```typescript
const TOOLS = new Map([
  ['read', {
    description: 'Read file with line numbers',
    schema: { path: 'string', offset: 'number?', limit: 'number?' },
    execute: read
  }],
  ['write', {
    description: 'Write content to file',
    schema: { path: 'string', content: 'string' },
    execute: write
  }],
  ['bash', {
    description: 'Run shell command',
    schema: { cmd: 'string' },
    execute: bash
  }]
])
```

---

## A Complete Tool Implementation

```typescript
async function read(args: Record<string, unknown>): Promise<string> {
  const path = args.path as string
  const text = await Bun.file(path).text()
  const lines = text.split('\n')
  const offset = (args.offset as number) ?? 0
  const limit = (args.limit as number) ?? lines.length
  return lines
    .slice(offset, offset + limit)
    .map((line, i) => `${(offset + i + 1).toString().padStart(4)}| ${line}`)
    .join('\n')
}
```

---

---

## VS Code Copilot Built-in Tools

- ⟨⟩ **agent** — Delegate tasks to other agents
- ⓘ **askQuestions** — Ask questions to clarify requirements
- ✎ **edit** — Edit files in your workspace
- ▷ **execute** — Execute code and applications
- ⧉ **read** — Read files in your workspace
- 🔍 **search** — Search files in your workspace
- ≡ **todo** — Manage and track todo items
- ✕ **vscode** — Use VS Code features
- 🌐 **web** — Fetch information from the web

---

# Context Engineering

---

---

---

> "Context engineering is the art and science of filling the context window with just the right information at each step of an agent's trajectory."
>
> — LangChain/Manus webinar

---

## Context Window Utilization

---

---

## Three Long-Horizon Techniques

From [Anthropic's guide](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents):

<VClicks>
1. **Compaction** — Summarize history, reset periodically
2. **Structured note-taking** — External memory systems
3. **Sub-agent architectures** — Distribute work across focused contexts
</VClicks>

---

# Back Pressure

---

## Why Back Pressure Matters

**Back pressure** = automated feedback that validates agent work

<VClicks>

- Without back pressure, **you** become the validation layer
- Agents cannot self-correct if nothing tells them something is wrong
- With good back pressure, agents detect mistakes and iterate until correct

</VClicks>

> "If you're directly responsible for checking each line is valid, that's time taken away from higher-level goals."

---

## Back Pressure Sources

| Source | What It Validates |
|--------|-------------------|
| **Type system** | Types, interfaces, contracts |
| **Build tools** | Syntax, imports, compilation |
| **Tests** | Logic, behavior, regressions |
| **Linters** | Style, patterns, best practices |

**Key insight:** Expressive type systems + good error messages = agents can self-correct.

---

# AGENTS.md

---

## What is AGENTS.md?

**What:** An open standard for agent-specific documentation

**Where:** Repository root (works in monorepos too)

**Who:** Works with Copilot, Claude, Cursor, Devin, 20+ agents

> "While README.md targets humans, AGENTS.md contains the extra context coding agents need."

---

---

## AGENTS.md Structure

```markdown
# AGENTS.md

## Dev Environment
- How to set up and navigate

## Build & Test Commands
- `pnpm install && pnpm dev`
- `pnpm test:unit`

## Code Style
- TypeScript strict mode
- Prefer composition over inheritance

## PR Instructions
- Keep PRs small and focused
```

**Key:** No required fields—use what helps your project.

---

---

## Before vs After: Progressive Disclosure

<h3 class="text-red-400 font-bold text-xl mb-4">❌ Bloated (847 lines)</h3>

```markdown
# AGENTS.md

## API Endpoints
[200 lines of docs...]
## Testing Strategy
[150 lines of docs...]
## Architecture
[300 lines of docs...]
## Code Style
[100 lines of rules...]
## Deployment
[97 lines of docs...]
```

<p class="text-yellow-400 mt-4 text-sm">40% context consumed before work starts</p>

<h3 class="text-green-400 font-bold text-xl mb-4">✅ Lean (58 lines)</h3>

```markdown
# AGENTS.md

## Quick Start
pnpm install && pnpm dev

## Docs Reference
| Doc | When to read |
|-----|--------------|
| docs/api.md | API work |
| docs/testing.md | Tests |
| docs/arch.md | Design |
```

<p class="text-cyan-400 mt-4 text-sm">Docs loaded on-demand when needed</p>

---

---

## The /learn Skill

```markdown
# Learn from Conversation

## Phase 1: Deep Analysis
- What patterns or approaches were discovered?
- What gotchas or pitfalls were encountered?
- What architecture decisions were made?

## Phase 2: Categorize & Locate
Read existing docs to find the best home.

## Phase 3: Draft the Learning
Format to match existing doc style.

## Phase 4: User Approval (BLOCKING)
Present changes, wait for explicit approval.

## Phase 5: Save
After approval, save the learning.
```

---

# Subagents

---

## Subagents in VS Code

**How to invoke:**
<VClicks>
1. Enable tools in Copilot Chat (hammer icon)
2. Call explicitly with `#runSubagent`
3. Or accept when Copilot suggests one
</VClicks>

---

## Use Cases 

<VClicks>
- Specialized searches (explore codebase, web, docs)
- Long-running tasks (data analysis, refactoring)
- TDD workflows (test generation, validation)
- Multi-step processes (research, summarize, act)
</VClicks>
---
## Explore Subagent Flow

<SubagentDiagram
  task="Find auth files"
  files={["Auth.tsx", "auth.ts", "authService.ts"]}
/>

Click **Start** to see how the main agent delegates file search to a specialized Explore subagent.

---

## Parallel Subagent Execution

<ParallelSubagentDiagram
  task="Research Vue 3 reactivity"
  agents={[
    { name: "Web Agent", icon: "🌐", color: "#3b82f6", domain: "Docs, GitHub", findings: ["Official guide", "RFC #123", "GitHub issue"] },
    { name: "Community", icon: "💬", color: "#8b5cf6", domain: "Reddit, SO", findings: ["r/vuejs post", "Top SO answer", "Discord tip"] },
    { name: "Codebase", icon: "📂", color: "#10b981", domain: "Project files", findings: ["useAuth.ts", "store.ts", "api/client.ts"] }
  ]}
/>

Click **Start** to see the fan-out/fan-in pattern where multiple subagents search in parallel.

---

## Subagent in nanocode: Fetch Tool

```shell
nanocode | claude-opus-4-5 | /Users/alexanderopalic/Projects/typescript/nanocode

────────────────────────────────────────────────────────────────────────────────
❯ how does fc bayern played yesterday
────────────────────────────────────────────────────────────────────────────────
[agentLoop] Starting with 1 messages
[agentLoop] Got response, stop_reason: tool_use

⏺ Fetch(https://www.google.com/search?q=fc+bayern+munich+m)
  ⎿  I apologize, but I cannot access real-time sports results or ... +7 lines
[agentLoop] Starting with 3 messages
[agentLoop] Got response, stop_reason: tool_use

⏺ Fetch(https://www.espn.com/soccer/team/_/id/132/bayern-m)
  ⎿  Based on the information in the image, Bayern Munich's most  ... +7 lines
[agentLoop] Starting with 5 messages
[agentLoop] Got response, stop_reason: end_turn

⏺ FC Bayern Munich lost 2-1 to FC Augsburg in the Bundesliga yesterday.
```

The **Fetch tool** uses a subagent to summarize HTML responses before returning.

---

#  Skills

---

---

## Real Skill: Plausible SEO Consultant

```shell
.claude/skills/plausible-insights/
├── skill.md              # Skill definition + quick start
├── scripts/              # Automation scripts 
│   └── fetch-data.ts    # Fetch Plausible data CLI
└── references/           # On-demand docs (progressive disclosure)
    ├── quick-ref.md      # Common query patterns
    ├── api/
    │   ├── filters.md    # Filter syntax
    │   └── errors.md     # Error solutions
    └── seo/
        └── thresholds.md # Interpretation guidelines
```

The agent reads `skill.md` first. Reference docs load only when needed.

---

## Skill in Action

**User:** "Why is my bounce rate so high on the Vue posts?"

<VClicks>

1. Description matches → skill.md loads (~500 tokens)
2. Agent runs: `bun cli top-pages --range 7d --pattern "/vue/"`
3. Agent reads `references/seo/thresholds.md` for interpretation
4. Agent fetches actual pages with WebFetch
5. Returns specific fixes based on real content

</VClicks>

**Key:** Data shows symptoms. Content shows causes.

---

# The Full Picture

---

---

# Live Demo

---

## Prerequisites

The demo uses `npx` (bundled with Node.js) and Python. Install for your platform:

<VClicks>

**Mac (Homebrew):**
```bash
brew install node python
```

**Windows (winget):**
```bash
winget install OpenJS.NodeJS Python.Python.3.12
```

**Or download from:** [nodejs.org](https://nodejs.org) | [python.org](https://python.org)

</VClicks>

**Verify:**
```bash
node --version && npx --version && python --version
```

---

## Demo: Building a Skill

<VClicks>

1. **Enable Skills** in VS Code settings
2. **Install skill-creator** via CLI
3. **Prompt** to generate a new skill

</VClicks>

---

## Step 1: Enable Skills

**VS Code Setting:**

```json
{
  "chat.useAgentSkills": true
}
```

Or via UI: `Settings → Search "agent skills" → Enable`

> Note: Still in preview — enable in VS Code Insiders for latest features.

---

---

## Step 3: Create a new Skill

```md
---
name: hello
description: 'use it everytime the user writes alex'
---

# Hello SKill

if the user writes "alex", respond with "Hello, Alexander Opalic! How can I assist you today?"

```

---

## Step 3: Install skill-creator

```bash
npx skills add https://github.com/anthropics/skills --skill skill-creator
```

This adds the **skill-creator** skill to your project — a skill that helps you create new skills.

**Project structure after install:**

```
my-project/
└── .github/
    └── skills/
        └── skill-creator/
            └── SKILL.md
```

---

```shell
◇  Source: https://github.com/anthropics/skills.git
│
◇  Repository cloned
│
◇  Found 17 skills (via Well-known Agent Skill Discovery)
│
●  Selected 1 skill: skill-creator
│
◇  Detected 3 agents
│
◇  Install to
│  All agents (Recommended)
│
◇  Installation scope
│  Project
│
◇  Installation method
│  Symlink (Recommended)

│
◇  Installation Summary ──────────────────────────────╮
│                                                     │
│  ~/Projects/workshop/.agents/skills/skill-creator   │
│    symlink → Claude Code, GitHub Copilot, OpenCode  │
│                                                     │
├─────────────────────────────────────────────────────╯
│
◆  Proceed with installation?
│  ● Yes / ○ No
└
```
---

## Step 3: Generate a New Skill

Important Skill name and folder name must match!

**Prompt:**

```
Create a skill that will use https://alexop.dev/llms.txt
and will answer any question regarding Vue or AI.

The skill should fetch the content and use the
#runSubagent command. The subagent should do the
heavy work and then report back to the main agent.
name of the skill is vue-ai-assistant
```

→ **skill-creator generates the SKILL.md for us**

---

## What Gets Generated

```markdown
---
name: vue-ai-assistant
description: Answer questions about Vue.js, Nuxt, and AI topics using Alexander Opalic's knowledge base. Use this skill when the user asks about Vue, Vue 3, Nuxt, Nuxt 3, Composition API, Vue Router, Pinia, Vite, AI, machine learning, LLMs, or related frontend/AI topics. Triggers on questions like "how do I use Vue", "explain Nuxt", "what's new in Vue 3", "AI agent patterns", or any Vue/AI related query.
---

# Vue & AI Assistant

Answer questions about Vue.js ecosystem and AI topics by fetching knowledge from https://alexop.dev/llms.txt and delegating research to a subagent.

## MANDATORY Workflow

**IMPORTANT: You MUST follow ALL steps below. Do NOT skip the subagent step. Do NOT answer directly after fetching - you MUST delegate to a subagent.**

1. **Fetch the knowledge base**: Use `fetch_webpage` to retrieve content from `https://alexop.dev/llms.txt`
2. **REQUIRED - Delegate to subagent**: Use `runSubagent` with the fetched content and user's question. **This step is NOT optional.**
3. **Return the answer**: Present the subagent's findings to the user

## Implementation

**You MUST execute ALL steps below. Skipping the subagent is a violation of this skill's requirements.**

### Step 1: Fetch Knowledge Base

Use the fetch_webpage tool:
- URL: `https://alexop.dev/llms.txt`
- Query: The user's question about Vue or AI

### Step 2: Run Subagent with Context (MANDATORY)

**You MUST call `runSubagent` - do NOT answer the question yourself. The subagent handles the analysis and response.**

Use `runSubagent` with a detailed prompt containing:

1. The fetched content from llms.txt as the knowledge base
2. The user's original question
3. Instructions to:
   - Analyze the knowledge base content thoroughly
   - Find relevant information to answer the question
   - Provide a clear, concise, and accurate answer
   - Include code examples when relevant
   - Cite specific sections from the knowledge base if applicable
   - If the knowledge base doesn't contain the answer, use general knowledge but note this

Example subagent prompt:

You are a Vue.js and AI expert. Answer the following question using the provided knowledge base content.

KNOWLEDGE BASE CONTENT:
fetched_content

USER QUESTION:
user_question

Analyze thoroughly, provide code examples when relevant, and cite sources from the knowledge base.
### Step 3: Present Answer

Return the subagent's response to the user, formatted appropriately with code blocks and explanations.

## Example

**User asks**: "How do I use composables in Vue 3?"

**Execution**:
1. Fetch https://alexop.dev/llms.txt
2. **MUST** call runSubagent with the content and question (do NOT skip this)
3. Return the subagent's comprehensive answer about Vue 3 composables
```

---

---

## Bonus: The askQuestions Tool

VS Code Copilot can **ask clarifying questions** mid-task.

```md
help me to create a workout tracking app use the #askQuestions tool to find out how the tech specs should be
```

---
```shell
┌─────────────────────────────────────────────────────────────┐
│                     Platform (1/4)                          │
├─────────────────────────────────────────────────────────────┤
│ What platform should the workout tracking app target?       │
├─────────────────────────────────────────────────────────────┤
│ ★ Web App  Browser-based PWA, accessible anywhere      [✓]  │
├─────────────────────────────────────────────────────────────┤
│   iOS Native  Swift/SwiftUI for iPhone                      │
├─────────────────────────────────────────────────────────────┤
│   Android Native  Kotlin for Android devices                │
├─────────────────────────────────────────────────────────────┤
│   Cross-Platform  React Native or Flutter for iOS & Android │
├─────────────────────────────────────────────────────────────┤
│   Desktop  Electron app for Mac/Windows                     │
├─────────────────────────────────────────────────────────────┤
│ ✎ Other...  Enter custom answer                             │
└─────────────────────────────────────────────────────────────┘
```

---

## Subagent Fan-Out Pattern

**Prompt for VS Code Insiders:**

```
#runSubagent run 3 subagents that search the web
and tell me something interesting about Geretsried
```

This demonstrates the **fan-out/fan-in pattern** where multiple agents work in parallel.

---

## Live Action: Excalidraw Skill

**Install the skill:**

```bash
npx skills add https://github.com/softaworks/agent-toolkit --skill excalidraw
```

Install the Excalidraw Extension in VS Code for best experience.

**Prompt to customize with brand colors:**

```
Update the excalidraw skill to use these brand colors:

- Fill: rgb(33, 39, 55)
- Text: rgb(234, 237, 243)
- Accent: rgb(255, 107, 237)
- Card: rgb(52, 63, 96)
- Card Muted: rgb(138, 51, 123)
- Border: rgb(171, 75, 153)
```

→ Agent modifies the skill's SKILL.md to include color instructions

---

---

## More Community Skills

```bash
npx skills add https://github.com/anthropics/skills --skill frontend-design
npx skills add https://github.com/simonwong/agent-skills --skill code-simplifier
```

- **frontend-design** — creates polished, production-grade UI components
- **code-simplifier** — simplifies and refines code for clarity

Browse and discover skills at [agentskills.io](https://agentskills.io/)

---

# Key Takeaways

---

## Key Takeaways

1. **Agents = LLM + Tools + Loop** (nanocode shows this simply)
2. **Context is finite** — treat tokens as budget
3. **AGENTS.md** — standardized project context
4. **Subagents** — specialized agents for complex tasks
5. **Skills** — portable workflows that load on demand

---

# Thank You!
Questions?

---

# Resources

---

## Resources

- [VS Code: Using Agents](https://code.visualstudio.com/docs/copilot/agents/overview) - Agent types and session management
- [Anthropic: Effective Context Engineering](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) - Context engineering guide
- [VS Code: Introducing Agent Skills](https://www.youtube.com/watch?v=JepVi1tBNEE) - Agent Skills deep dive
- [VS Code: Context Engineering Guide](https://code.visualstudio.com/docs/copilot/guides/context-engineering-guide) - Microsoft's context engineering workflow
- [AGENTS.md](https://agents.md/) - Open standard for agent documentation
- [Agent Skills Spec](https://agentskills.io/) - Open standard for portable agent skills
- [nanocode](https://github.com/alexanderop/nanocode) - Minimal agent implementation in TypeScript
- [Writing a Good CLAUDE.md](https://www.humanlayer.dev/blog/writing-a-good-claude-md) - Best practices for agent documentation
- [Plausible SEO Skill](https://github.com/alexanderop/claude-plausible-analytics) - Skills deep dive with Plausible example
- [Don't Waste Your Back Pressure](https://banay.me/dont-waste-your-backpressure/) - Why automated feedback loops make agents more effective
- [Workshop Solution](https://github.com/alexanderop/workshop) - Complete code examples from this workshop
- [Learn Prompt](https://alexop.dev/prompts/claude/claude-learn-command/) - Skill that helps agents learn from conversations

---

---

--- title: What's New in VS Code Copilot: January 2026 Update description: Major updates to VS Code Copilot including parallel subagent execution, a new skills system, deeper Claude integration with extended thinking, terminal improvements with kitty keyboard protocol, and instruction files that now work everywhere. tags: ['ai', 'tooling', 'vscode'] url: https://alexop.dev/posts/whats-new-vscode-copilot-january-2026 ---

# What's New in VS Code Copilot: January 2026 Update



The past week has brought a wave of updates to VS Code's Copilot experience, with major improvements to how agents work together, a new skills system, deeper Claude integration, and significant terminal enhancements. Here's what you need to know—with concrete examples you can try today.

For those who want to dive deeper into the implementation details, I've included links to the relevant GitHub pull requests and issues throughout this post.

---

## Subagents Get Smarter (and Faster)

Two significant changes make subagents far more practical for complex workflows.

**Related:** [Issue #274630 - Parallel subagent execution](https://github.com/microsoft/vscode/issues/274630)

### Parallel Execution

Previously, if you kicked off multiple `runSubagent` calls, they'd run one after another. Now they can run simultaneously when tasks are independent, dramatically reducing wait times for research and code review operations.

**Example prompt:**
```
Research the best approaches for:
1. Rate limiting in our REST API
2. Caching strategies for our database queries
3. Error handling patterns for our microservices

Use a subagent for each topic and compile the findings.
```

With parallel execution, all three research subagents run concurrently instead of sequentially—cutting total wait time significantly.

<Figure
  src={subAgentParallel}
  alt="Parallel subagent execution visualization"
  size="large"
/>

### Fine-Grained Tool Access

You can now constrain which tools a subagent can access. This is critical for safety-conscious workflows where you want AI help without the risk of unintended changes.

**Creating a custom agent with restricted tools:**

Create a file at `.github/agents/github-researcher.md`:

```markdown
---
name: github-researcher
description: Research agent with access to GitHub. Use for searching issues,
             reading documentation, and gathering information. Cannot edit files.
tools: ['read', 'search', 'web', 'github/*']
argument-hint: The research task to complete
---

You are a research assistant with read-only access to the codebase and GitHub.

Your capabilities:
- Search and read files in the repository
- Search GitHub issues and pull requests
- Fetch web documentation

You cannot:
- Edit or create files
- Run terminal commands
- Make commits

When researching, provide citations and links to sources.
```

Now you can ask: *"Use a subagent to find all issues assigned to me about authentication and summarize them"* — and the subagent will be limited to read-only operations.

If you've used Claude Code's subagent system, you'll recognize this pattern—it's similar to how <InternalLink slug="claude-code-customization-guide-claudemd-skills-subagents">Claude Code handles skills and subagents</InternalLink> with tool restrictions.

### Control Subagent Availability

Use the `infer` attribute to control whether an agent can be used as a subagent:

```markdown
---
name: dangerous-deployer
description: Handles production deployments
tools: ['execute', 'edit', 'read']
infer: false  # This agent cannot be auto-invoked as a subagent
---
```

---

## Skills Are Now a First-Class Feature

Skills are now **enabled by default** for all users. They're folders containing instructions and resources that Copilot loads on-demand when relevant to your task.

**Related PRs:**
- [Issue #286237 - Custom agent improvements](https://github.com/microsoft/vscode/issues/286237)
- [Issue #286238 - Skill lookup enhancements](https://github.com/microsoft/vscode/issues/286238)
- [PR #3082 - Implement agent using CustomAgentProvider API](https://github.com/microsoft/vscode-copilot-chat/pull/3082)

### Creating Your First Skill

Create a directory structure:

<FileTree tree={[
  { name: ".github", children: [
    { name: "skills", children: [
      { name: "webapp-testing", children: [
        { name: "SKILL.md", comment: "// Instructions" },
        { name: "test-template.js", comment: "// Example template" }
      ]}
    ]}
  ]}
]} />

**`SKILL.md`:**
```markdown
---
name: webapp-testing
description: Guide for testing web applications using Playwright.
             Use this when asked to create or run browser-based tests.
---

# Web Application Testing with Playwright

When creating tests for this project, follow these patterns:

## Test Structure
- Use `describe` blocks for feature groupings
- Use `test` for individual test cases
- Always include setup and teardown

## Assertions
- Prefer `toBeVisible()` over `toHaveCount(1)`
- Use `waitFor` for async operations
- Include accessibility checks

## Example Template
Reference the [test template](./test-template.js) for the standard structure.

## Naming Convention
- Test files: `*.spec.ts`
- Test descriptions: "should [expected behavior] when [condition]"
```

Now when you ask *"Write Playwright tests for the login form"*, Copilot automatically loads this skill and follows your project's testing conventions.

### Loading Skills from Custom Locations

For teams sharing skills across repos, use the new setting:

```json
{
  "chat.agentSkillsLocations": [
    ".github/skills",
    "~/shared-skills",
    "/team/copilot-skills"
  ]
}
```

### Extension-Contributed Skills

Extensions can now contribute skills via their `package.json`:

```json
{
  "contributes": {
    "copilotSkills": [
      {
        "name": "docker-compose",
        "description": "Helps create and debug Docker Compose configurations",
        "path": "./skills/docker-compose"
      }
    ]
  }
}
```

Or dynamically via the new API:

```typescript
vscode.chat.registerSkill({
  name: 'dynamic-skill',
  description: 'A skill registered at runtime',
  async getInstructions(context) {
    // Return context-aware instructions
    return generateInstructionsFor(context.workspace);
  }
});
```

---

## Instruction Files Work Everywhere

Instruction files now apply to **non-coding tasks** like code exploration, architecture explanation, and documentation. [#287152](https://github.com/microsoft/vscode/issues/287152)

**Before:** Your `.github/copilot-instructions.md` was ignored when you asked *"Explain how authentication works in this codebase"*

**After:** Those instructions are now read for all codebase-related work.

This aligns with the <InternalLink slug="stop-bloating-your-claude-md-progressive-disclosure-ai-coding-tools">progressive disclosure approach</InternalLink> where context is loaded on-demand rather than crammed into a single file.

**Example `copilot-instructions.md`:**
```markdown
# Project Context

This is a microservices architecture with:
- API Gateway (Node.js/Express)
- Auth Service (Go)
- User Service (Python/FastAPI)
- Shared message queue (RabbitMQ)

When explaining code:
- Always mention which service a file belongs to
- Reference the architecture diagram at docs/architecture.md
- Note any cross-service dependencies
```

Now *"How does user registration work?"* will include this context automatically.

---

## Claude Code Gets Extended Thinking

The Claude Code integration now supports **extended thinking**, showing Claude's chain-of-thought reasoning in a collapsible section. [#287658](https://github.com/microsoft/vscode/issues/287658)

**Related:** [Issue #266962 - Claude agent support](https://github.com/microsoft/vscode/issues/266962), [#287933 - Model picker support](https://github.com/microsoft/vscode/issues/287933)

### What It Looks Like

When you ask Claude to solve a complex problem, you'll see:

```
▼ Thinking...
  Let me analyze the codebase structure first. I see there are
  three main modules: auth, api, and database. The user is asking
  about the authentication flow, so I should trace the request
  from the API gateway through to the auth service...

  The JWT validation happens in middleware/auth.ts, but the token
  generation is in services/auth/token.go. I need to explain how
  these connect via the shared Redis cache...

Here's how authentication works in your codebase:
[Final response]
```

### Configuration

Enable/disable thinking display in settings:
```json
{
  "github.copilot.chat.claude.showThinking": true
}
```

### Model Picker

You can now select which Claude model to use:

1. Open the Chat view
2. Click the model selector dropdown
3. Choose from available Claude models (Sonnet, Opus, etc.)

Different models offer different speed/capability tradeoffs—use faster models for simple tasks, more capable models for complex reasoning.

---

## Terminal Gets Major Upgrades

The integrated terminal received significant keyboard handling improvements this release, with two new protocol implementations.

**Related PRs:**
- [PR #286897 - xterm.js 6.1.0 with kitty keyboard and win32-input-mode](https://github.com/microsoft/vscode/pull/286897)
- [Issue #286809 - Kitty keyboard protocol support](https://github.com/microsoft/vscode/issues/286809)
- [Issue #286896 - Win32 input mode support](https://github.com/microsoft/vscode/issues/286896)
- [xterm.js PR #5600 - Implement kitty keyboard protocol](https://github.com/xtermjs/xterm.js/pull/5600) (upstream)

### Kitty Keyboard Protocol (CSI u)

VS Code's terminal now supports the [kitty keyboard protocol](https://sw.kovidgoyal.net/kitty/keyboard-protocol/), enabling more sophisticated keyboard input handling. This unlocks previously unavailable key combinations and provides better support for terminal applications that use this modern standard.

**Important:** This feature is **disabled by default** as it's experimental. Enable it in settings:

```json
{
  "terminal.integrated.enableKittyKeyboardProtocol": true
}
```

The protocol improves handling of modifiers, key events, repeat detection, and escape sequences—particularly useful if you use tools like fish shell, neovim, or other terminal applications that support CSI u.

### Win32 Input Mode

For Windows users, the terminal now supports win32-input-mode, improving keyboard handling compatibility with Windows console applications. VT sequences alone can't send everything that Windows console programs expect (encoded as win32 INPUT_RECORDs), so this mode bridges that gap.

**Also disabled by default.** Enable with:

```json
{
  "terminal.integrated.enableWin32InputMode": true
}
```

### Terminal Command Output Streams Inline

When using Copilot in agent mode, terminal command output now streams inline inside the Chat view instead of requiring you to switch to the terminal panel. [#257468](https://github.com/microsoft/vscode/issues/257468) The output auto-expands on command execution and collapses on success [#287664](https://github.com/microsoft/vscode/issues/287664)—keeping you focused on the conversation flow.

### Terminal Timeout Parameter

The terminal tool now supports a timeout parameter to control how long commands run before timing out. [#286598](https://github.com/microsoft/vscode/issues/286598) This prevents unnecessary polling and gives you more control over long-running operations.

### Terminal Command Sandboxing

Terminal command sandboxing is now available for **macOS and Linux** [#277286](https://github.com/microsoft/vscode/issues/277286), adding an extra layer of security when running commands through the terminal tool.

### Syntax Highlighting in Confirmation Dialogs

The terminal tool now presents Python, Node.js, and Ruby commands with syntax highlighting in the confirmation dialog [#287772](https://github.com/microsoft/vscode/issues/287772), [#287773](https://github.com/microsoft/vscode/issues/287773), [#288360](https://github.com/microsoft/vscode/issues/288360)—making it easier to review commands before execution.

### Expanded Auto-Approved Commands

More commands are now automatically approved for execution:
- `dir` in PowerShell [#288431](https://github.com/microsoft/vscode/issues/288431)
- `sed -i` when editing files within the workspace [#288318](https://github.com/microsoft/vscode/issues/288318)
- `od`, `xxd`, and safe `docker` commands [#287652](https://github.com/microsoft/vscode/issues/287652)

### SGR 221/222 Escape Sequences

The terminal now supports SGR 221 and 222 escape sequences [#286810](https://github.com/microsoft/vscode/issues/286810), allowing independent control of bold and faint text attributes for more granular formatting.

---

## MCP Gets More Powerful

Model Context Protocol continues to evolve with significant new capabilities.

### Dynamic Context Updates

MCP apps now support model context update methods, enabling servers to update the context model dynamically. [#289473](https://github.com/microsoft/vscode/issues/289473) This means MCP servers can push new context to your chat sessions without requiring a refresh.

### Custom Package Registries

Added support for `registryBaseUrl` in MCP packages [#287549](https://github.com/microsoft/vscode/issues/287549), allowing teams to use private package registries for their MCP servers.

### Built-in MCP Apps Support

Built-in support for MCP Apps enables servers to provide custom UI for tool invocation. [#260218](https://github.com/microsoft/vscode/issues/260218) This opens the door for richer, more interactive MCP experiences beyond simple text-based tools.

---

## Quality of Life Improvements

### Codex Agent in Dropdown

The OpenAI Codex agent now appears directly in the agents dropdown [#289040](https://github.com/microsoft/vscode/issues/289040) for quick access:

```
Agents ▼
├── Local Agent
├── Background Agent
├── Cloud Agent
└── Codex Agent       ← New!
```

### New MCP Server Command

A new `workbench.mcp.startServer` command [#283959](https://github.com/microsoft/vscode/issues/283959) lets you programmatically start specific or all MCP servers to discover their tools. This is useful for automation scenarios where you need to ensure servers are running before invoking their tools.

### The `/clear` Command Archives Sessions

The `/clear` command now archives the current session and starts a new one automatically [#285854](https://github.com/microsoft/vscode/issues/285854)—no more losing your chat history when you want a fresh start.

### New Local Chat Command

A new "New Local Chat" command [#288467](https://github.com/microsoft/vscode/issues/288467) lets you start a local chat session quickly.

### Chat Session Imports

You can now **import** a chat session directly into the Chat view [#283954](https://github.com/microsoft/vscode/issues/283954), instead of only being able to open it in a new editor tab. This makes it easier to continue conversations from exported sessions.

### Chat Session Exports with MCP Info

Exported sessions now include <InternalLink slug="what-is-model-context-protocol-mcp">MCP server</InternalLink> configuration [#283945](https://github.com/microsoft/vscode/issues/283945):

```json
{
  "session": {
    "messages": [...],
    "mcpServers": [
      {
        "name": "github",
        "url": "https://mcp.github.com",
        "tools": ["search_issues", "get_pr", "list_repos"]
      }
    ]
  }
}
```

This makes sessions reproducible—share them with teammates and they can recreate your exact setup.

### Multi-Select in Sessions View

Select multiple chat sessions with `Cmd/Ctrl+Click` [#288448](https://github.com/microsoft/vscode/issues/288448):
- Archive all selected
- Mark all as read
- Batch delete

Additional session management improvements include "Mark All Read", "Archive All", and "Unarchive All" actions in context menus [#288147](https://github.com/microsoft/vscode/issues/288147), and increased locally persisted chat sessions [#283123](https://github.com/microsoft/vscode/issues/283123).

### Resizable Sessions Sidebar

You can now resize the sessions sidebar in the Chat view by dragging the separator [#281258](https://github.com/microsoft/vscode/issues/281258), similar to how terminal tabs work.

### Extension Context Tooltips

Hover over extension-contributed context items to see additional information about what they provide. [#280658](https://github.com/microsoft/vscode/issues/280658)

### Accessible View Streams Thinking Content

The Accessible View now dynamically streams thinking content [#289223](https://github.com/microsoft/vscode/issues/289223), making Claude's chain-of-thought reasoning accessible to screen reader users in real-time.

### Multi-Model Selection in Language Models Editor

Select multiple models in the Language Models editor and toggle their visibility at once [#287511](https://github.com/microsoft/vscode/issues/287511). Enterprise and Business users also get access to the Manage Models action [#287814](https://github.com/microsoft/vscode/issues/287814).

---

## Editor & Language Improvements

### Improved Shebang Detection

VS Code now recognizes Deno, Bun, and other modern JavaScript runtimes [#287819](https://github.com/microsoft/vscode/issues/287819) for better language detection when opening scripts.

### Better Ghost Text Visibility

Improved visibility of ghost text in next edit suggestions [#284517](https://github.com/microsoft/vscode/issues/284517), making it easier to distinguish AI suggestions from regular text.

### Double-Click Selects Block Content

Double-clicking immediately after a curly brace or bracket now selects the content inside it [#9123](https://github.com/microsoft/vscode/issues/9123)—a small but impactful change for manipulating code blocks.

### Match File Path Case Toggle

A new "Match File Path Case" toggle in the Search view's "files to include" input [#10633](https://github.com/microsoft/vscode/issues/10633) lets you control whether file paths and glob patterns match case-sensitively.

### Bracket Match Foreground Color

New `editorBracketMatch.foreground` theme color [#85775](https://github.com/microsoft/vscode/issues/85775) enables customization of matched bracket text color.

### Parallel Build Tasks

Dependent build tasks can now run in parallel [#288439](https://github.com/microsoft/vscode/issues/288439), improving build performance for projects with multiple independent compilation steps.

### Git Delete File Command

A new "Git: Delete File" command [#111767](https://github.com/microsoft/vscode/issues/111767) performs `git rm` on the current file directly from the command palette.

---

## Try It Today

Here's a quick workflow to test the new features:

1. **Create a custom agent** at `.github/agents/researcher.md` with restricted tools
2. **Create a skill** at `.github/skills/my-skill/SKILL.md`
3. **Ask Copilot:** *"What skills and subagents do you have available?"*
4. **Test parallel execution:** *"Use subagents to research three different topics simultaneously"*
5. **Enable Claude thinking** and ask a complex architecture question

---

## Looking Ahead

These updates signal a clear direction: Copilot is evolving from a single-agent assistant into a **coordinated multi-agent system**. The combination of parallel subagents, constrained tool access, and shareable skills creates a foundation for sophisticated automated workflows.

If you're interested in building your own agent systems, check out <InternalLink slug="building-your-own-coding-agent-from-scratch">Building Your Own Coding Agent from Scratch</InternalLink> for a hands-on guide to the underlying patterns.

Key settings to know:
```json
{
  "chat.useAgentSkills": true,
  "chat.agentSkillsLocations": [".github/skills"],
  "chat.customAgentInSubagent.enabled": true,
  "github.copilot.chat.claude.showThinking": true,
  "terminal.integrated.enableKittyKeyboardProtocol": true,
  "terminal.integrated.enableWin32InputMode": true
}
```

The ecosystem is about to get a lot more interesting.

---

## Related Pull Requests & Issues

For those who want to dig into the implementation details:

### Agent & Skills
- [#274630 - Parallel subagent execution](https://github.com/microsoft/vscode/issues/274630)
- [#280704 - Agents define allowed subagents](https://github.com/microsoft/vscode/issues/280704)
- [#288480 - Skills enabled by default](https://github.com/microsoft/vscode/issues/288480)
- [#288483 - Extension-contributed skills via manifest](https://github.com/microsoft/vscode/issues/288483)
- [#288486 - Dynamic skills API](https://github.com/microsoft/vscode/issues/288486)
- [#282738 - Skills from custom locations](https://github.com/microsoft/vscode/issues/282738)

### Claude Integration
- [#287658 - Extended thinking support](https://github.com/microsoft/vscode/issues/287658)
- [#287933 - Model picker for Claude](https://github.com/microsoft/vscode/issues/287933)
- [#266962 - Claude agent support](https://github.com/microsoft/vscode/issues/266962)

### Terminal
- [#286809 - Kitty keyboard protocol](https://github.com/microsoft/vscode/issues/286809)
- [#286896 - Win32 input mode](https://github.com/microsoft/vscode/issues/286896)
- [#286810 - SGR 221/222 escape sequences](https://github.com/microsoft/vscode/issues/286810)
- [#257468 - Terminal output streams inline](https://github.com/microsoft/vscode/issues/257468)
- [#287664 - Auto-expand/collapse terminal output](https://github.com/microsoft/vscode/issues/287664)
- [#277286 - Terminal sandboxing for macOS/Linux](https://github.com/microsoft/vscode/issues/277286)
- [#286598 - Terminal timeout parameter](https://github.com/microsoft/vscode/issues/286598)
- [#287772 - Python syntax highlighting in confirmations](https://github.com/microsoft/vscode/issues/287772)
- [xterm.js #5600 - Kitty keyboard protocol](https://github.com/xtermjs/xterm.js/pull/5600)

### MCP
- [#289473 - Dynamic context updates](https://github.com/microsoft/vscode/issues/289473)
- [#287549 - Custom package registries](https://github.com/microsoft/vscode/issues/287549)
- [#260218 - Built-in MCP Apps](https://github.com/microsoft/vscode/issues/260218)
- [#283959 - startServer command](https://github.com/microsoft/vscode/issues/283959)
- [#283945 - MCP info in session exports](https://github.com/microsoft/vscode/issues/283945)

### Chat & Sessions
- [#285854 - /clear archives sessions](https://github.com/microsoft/vscode/issues/285854)
- [#288467 - New Local Chat command](https://github.com/microsoft/vscode/issues/288467)
- [#283954 - Import chat sessions](https://github.com/microsoft/vscode/issues/283954)
- [#288448 - Multi-select in sessions](https://github.com/microsoft/vscode/issues/288448)
- [#281258 - Resizable sessions sidebar](https://github.com/microsoft/vscode/issues/281258)
- [#283123 - Increased persisted sessions](https://github.com/microsoft/vscode/issues/283123)
- [#289223 - Accessible View streams thinking](https://github.com/microsoft/vscode/issues/289223)

### Editor & Other
- [#287819 - Improved shebang detection](https://github.com/microsoft/vscode/issues/287819)
- [#284517 - Ghost text visibility](https://github.com/microsoft/vscode/issues/284517)
- [#9123 - Double-click selects block content](https://github.com/microsoft/vscode/issues/9123)
- [#10633 - Match file path case toggle](https://github.com/microsoft/vscode/issues/10633)
- [#288439 - Parallel build tasks](https://github.com/microsoft/vscode/issues/288439)
- [#111767 - Git Delete File command](https://github.com/microsoft/vscode/issues/111767)

### Iteration Plan
- [#286040 - January 2026 Iteration Plan](https://github.com/microsoft/vscode/issues/286040)

---

*These features are rolling out in VS Code Insiders (1.109) now, with stable release expected in early February. Note that some features like kitty keyboard protocol and win32-input-mode are disabled by default and require manual opt-in.*

---

--- title: Presentation Mode: Turn Your Blog Posts into Slides description: A complete demo of presentation mode with v-click animations and drawing annotations. Press P to see keyboard navigation, incremental reveals, and press D to draw on slides! tags: ['demo', 'presentation', 'feature'] url: https://alexop.dev/posts/presentation-mode-demo ---

# Presentation Mode: Turn Your Blog Posts into Slides



<Alert type="info" title="Try It Now!">
  Press **P** on your keyboard or click the floating button in the bottom-right corner to enter presentation mode. Use arrow keys to navigate between slides, and press **D** to draw annotations directly on slides!
</Alert>

# Presentation Mode

Turn your blog posts into beautiful slides with incremental reveals

---

## Why Presentation Mode?

**The Problem:** You write a great blog post, then need to present it at a meetup.

**Old Solution:** Recreate everything in PowerPoint or Google Slides.

**New Solution:** Just add `presentation: true` to your frontmatter!

```yaml
---
title: "My Awesome Post"
presentation: true
---
```

---

## Keyboard Shortcuts

| Key | Action |
|-----|--------|
| **P** | Toggle presentation mode |
| **→** or **Space** | Next click step, then next slide |
| **←** | Previous click step, then previous slide |
| **1-9** | Jump to slide N (resets clicks) |
| **Home** | First slide |
| **End** | Last slide |
| **D** | Toggle drawing mode |
| **G** | Toggle grid overview |
| **Escape** | Exit drawing → grid → presentation |

---

# Drawing Annotations

Draw directly on slides with Excalidraw!

---

## Try Drawing Mode

Press **D** to toggle drawing mode. A toolbar will appear with these tools:

<VClicks>

- **↖ Selection** - Select and move drawings
- **✏️ Freedraw** - Freehand drawing (press P)
- **→ Arrow** - Draw arrows (press A)
- **□ Rectangle** - Draw rectangles (press R)
- **○ Ellipse** - Draw circles (press O)
- **T Text** - Add text annotations (press T)
- **🧹 Eraser** - Erase drawings (press E)

</VClicks>

---

## Drawing Features

**Colors:** 6 preset colors - Red, Blue, Green, Yellow, White, Black

**Stroke Widths:** 3 sizes - Thin (1px), Medium (2px), Thick (4px)

**Persistence:** Drawings stay when you navigate between slides!

**Shortcuts:**
- `C` - Clear current slide
- `Shift+C` - Clear all slides
- `Escape` - Exit drawing mode

---

## Use Cases

Why draw on slides during presentations?

<VClicks>

- Circle important code sections
- Draw arrows connecting concepts
- Add quick annotations for Q&A
- Highlight key points in diagrams
- Sketch ideas during discussions

</VClicks>

---

# V-Click Animations

Reveal content step-by-step with Slidev-style click animations

---

## Sequential Reveals

Press **→** to reveal each point:

**Step 1:** First, we define the problem clearly.

**Step 2:** Then, we explore possible solutions.

**Step 3:** Finally, we implement and test!

---

## Building a List

Benefits of incremental reveals:

<VClicks>

- Keeps audience focused on the current point
- Creates natural pacing for your talk
- Prevents information overload
- Makes complex topics digestible

</VClicks>

---

## V-Click Syntax

In MDX files, use components to control reveals:

```mdx

Content appears on click

<VClicks>
- Each list item
- Gets its own click
</VClicks>

Explicit order (appears third)

This disappears on click
```

---

# Custom Components

Interactive React components work in slides!

---

## Context Window Visualizer

This is a custom React component rendered inside a slide:

Try typing messages to see the context fill up!

---

## Code Blocks Work Perfectly

Here's a Vue composable example with full syntax highlighting:

```typescript
export function useCounter(initial = 0) {
  const count = ref(initial)

  const double = computed(() => count.value * 2)

  function increment() {
    count.value++
  }

  return { count, double, increment }
}
```

---

## Magic Move: Code Evolution

Watch code transform with smooth animations (press **→** to advance):

<MagicMove
  lang="typescript"
  steps={[
    `const x = 1`,
    `const x = 1
const y = 2`,
    `const x = 1
const y = 2

function add(a: number, b: number) {
  return a + b
}`,
    `const x = 1
const y = 2

function add(a: number, b: number) {
  return a + b
}

const sum = add(x, y)
console.log(sum) // 3`
  ]}
/>

Each arrow press animates the code to its next state!

---

## Mermaid Diagrams

Flowcharts render beautifully in slides:

```mermaid
graph LR
    A[Blog Post] --> B{presentation: true?}
    B -->|Yes| C[Show Toggle Button]
    B -->|No| D[Normal Post]
    C --> E[Press P]
    E --> F[Fullscreen Slides!]
```

---

## Animated Diagrams

Interactive diagrams with self-contained animations:

<SubagentDiagram
  task="Find auth files"
  files={["Auth.tsx", "auth.ts", "authService.ts"]}
/>

Click **Start** to see the Explore subagent flow animation!

---

# Slide Layouts

---

## Available Layouts

This feature supports 9 different layout types:

| Layout | Description |
|--------|-------------|
| `default` | Standard centered prose |
| `cover` | Large title, full-bleed |
| `center` | Fully centered content |
| `two-cols` | Two-column split |
| `image-left` | Image 40%, content 60% |
| `image-right` | Content 60%, image 40% |
| `image` | Full-bleed background |
| `quote` | Prominent blockquote |
| `section` | Section divider |
| `iframe` | Embedded website/demo |

---

## Iframe Layout

Embed live demos, CodePen, StackBlitz, or videos directly in slides:

This is a live StackBlitz embed - fully interactive!

---

## Layout Syntax

In **.md files**, use HTML comments. In **.mdx files**, use components:

```mdx
{/* MDX format */}

# My Title

---

{/* .md format */}
<!--slide:{"layout":"cover"}-->
# My Title
```

<Aside type="note" title="MDX vs MD">
Both file formats support layouts and v-clicks! For `.md` files use HTML comments, for `.mdx` files use the `Slide`, `VClick`, and `VClicks` components.
</Aside>

---

## Layout Properties

All layouts accept these properties:

| Property | Description |
|----------|-------------|
| `layout` | Layout name (required) |
| `image` | Path to image in /public |
| `backgroundSize` | CSS value (default: cover) |
| `class` | Custom CSS class |
| `src` | URL for iframe layout |
| `title` | Accessibility title for iframe |

---

## Layout Animations

Each layout type has its own animation:

| Layout | Animation |
|--------|-----------|
| `default` | Slide |
| `center` | Slide |
| `two-cols` | Slide |
| `cover` | **Fade** |
| `image` | **Zoom** |
| `quote` | **Fade** |
| `section` | **Fade** |
| `iframe` | **Fade** |

---

# Technical Details

---

## Architecture Overview

```mermaid
flowchart TB
    subgraph Frontend
        A[PresentationToggle] --> B[PresentationMode]
        B --> C[PresentationSlide]
        B --> D[PresentationControls]
        B --> E[PresentationProgress]
    end

    subgraph Layouts
        C --> F[SlideLayoutDefault]
        C --> G[SlideLayoutCover]
        C --> H[SlideLayoutTwoCols]
        C --> I[... more layouts]
    end

    subgraph Content
        J[Blog Post] --> K[Compiled HTML]
        K --> L[Parse slide comments]
        L --> M[SlideData Array]
    end

    M --> C
```

---

## Tips for Great Slides

<Aside type="tip" title="Best Practices">

1. **Keep slides focused** - One idea per slide
2. **Use headings** - They become slide titles
3. **Leverage layouts** - Pick the right layout for content
4. **Use v-clicks** - Reveal complex info step-by-step
5. **Test navigation** - Make sure flow makes sense

</Aside>

### Content Length

<VClicks>

- Short slides work best
- If content overflows, it scrolls within the slide
- But try to keep each slide digestible
- Use v-clicks to break up longer content

</VClicks>

---

## Accessibility Features

<VClicks>

- **Focus trap** - Tab stays within the modal
- **ARIA live region** - Announces "Slide X of Y, Step N of M"
- **Escape to exit** - Standard modal behavior
- **Keyboard navigation** - No mouse required
- **Theme aware** - Respects light/dark mode
- **Reduced motion** - V-click respects `prefers-reduced-motion`

</VClicks>

---

## Speaker Notes & Presenter View

Press **N** to open the presenter view popup!

The presenter view shows:

<VClicks>

- Current and next slide previews
- Speaker notes with click-step highlighting
- A timer you can start/pause/reset
- Navigation controls

</VClicks>

<Note>{"This is a speaker note! It's only visible in the presenter view.\n[click] Now explain that the presenter view opens in a popup window.\n[click] Walk through each feature: previews, notes, timer, controls.\n[click] Mention keyboard shortcuts: T for timer, R to reset."}</Note>

---

## Notes with Click Markers

Notes can reveal progressively with your click steps:

**Step 1:** Define the problem

**Step 2:** Explore solutions

**Step 3:** Implement and ship!

<Note>{"Always visible intro text for this slide.\n[click] Talk about why defining the problem clearly matters.\n[click] Mention 2-3 solution approaches you considered.\n[click] Emphasize shipping fast and iterating."}</Note>

---

# Thank You!

Press **Escape** to exit or continue with arrow keys

---

## Quick Reference

**File format trade-offs:**

| Format | Custom Components | Layouts | V-Click | Syntax |
|--------|-------------------|---------|---------|--------|
| `.mdx` | Yes | Yes | Yes | Components |
| `.md` | No | Yes | Yes | HTML comments |

Press **Escape** to exit presentation mode!

---

--- title: Stop Bloating Your CLAUDE.md: Progressive Disclosure for AI Coding Tools description: AI coding tools are stateless—every session starts fresh. The solution isn't cramming everything into CLAUDE.md, but building a layered context system where learnings accumulate in docs and specialized agents load on-demand. tags: ['claude-code', 'ai-tools', 'developer-experience', 'productivity'] url: https://alexop.dev/posts/stop-bloating-your-claude-md-progressive-disclosure-ai-coding-tools ---

# Stop Bloating Your CLAUDE.md: Progressive Disclosure for AI Coding Tools



Yesterday I spent an hour debugging a Nuxt Content gotcha with Claude. We figured it out together—you need to use `stem` instead of `slug` in page collection queries. Today? Claude made the same mistake. Yesterday's session was gone.

<Alert type="info">
The examples in this post come from my [Second Brain](https://second-brain-nuxt.vercel.app/)—a personal wiki built with Nuxt and Nuxt Content that uses Zettelkasten-style wiki-links for knowledge management. You can see the actual [CLAUDE.md file](https://github.com/alexanderop/second-brain-nuxt/blob/main/CLAUDE.md) on GitHub.
</Alert>

That's the constraint. **Your context is just an array of tokens**—a sliding window that forgets everything the moment the conversation ends.[^1]

<Alert type="info">
The percentages shown in these visualizations are illustrative examples—not real measurements. Actual system prompt overhead varies by tool version and configuration. The key insight is the relative proportions, not the exact numbers.
</Alert>

There's no hidden memory. No database of past conversations. Just this array, rebuilt fresh every session.

Dex Horthy calls this "context engineering"—since LLMs are stateless, the only way to improve output is optimizing input.[^6] The array is all you have. Everything outside it doesn't exist to the model.

But that array has a size limit. Fill it with noise, and you're working in what Dex calls the "dumb zone"—where performance degrades because irrelevant context competes for attention.

Most developers respond to this by putting every lesson learned into their `CLAUDE.md` file. I've seen files balloon to 2000 lines. Style guides, architectural decisions, war stories from that one bug that took three days to fix.

This makes things worse.

## Bloated CLAUDE.md Makes Things Worse

When Claude makes a mistake, the instinct is to add a rule: "Never use `slug` in page collection queries—use `stem` instead."

Then another mistake, another rule. Then another.

Before long, your CLAUDE.md looks like this:

```markdown
# CLAUDE.md

## Project Overview
...50 lines...

## Code Style
...200 lines of formatting rules...

## Architecture Decisions
...150 lines of historical context...

## Gotchas
...300 lines of edge cases...

## Testing Conventions
...100 lines...
```

**Half your context budget is gone before any work begins.**

HumanLayer keeps their CLAUDE.md under 60 lines.[^2] Frontier LLMs reliably follow 150-200 instructions—and Claude Code's system prompt already uses about 50 of those.[^2]

The math doesn't work. You can't stuff everything in one file.

## Stop Writing Prose About Lint Rules

Why write two hundred lines about code style when one line handles it? I stopped putting anything a tool can enforce in CLAUDE.md.

❌ **Don't write prose about style rules:**
```markdown
## Code Style
- Use 2-space indentation
- Prefer single quotes
- Always add trailing commas
- Maximum line length: 100 characters
```

✅ **Let ESLint handle it:**
```json
{
  "extends": ["@nuxt/eslint-config"]
}
```

The rules are already there—you just don't repeat them in prose:
```js
// What @nuxt/eslint-config contains:
{
  rules: {
    'indent': ['error', 2],
    'quotes': ['error', 'single'],
    'comma-dangle': ['error', 'always-multiline'],
    'max-len': ['error', { code: 100 }]
  }
}
```

The AI can run `pnpm lint:fix && pnpm typecheck` and know immediately if it violated a rule. No interpretation needed. No ambiguity.

**If a tool can enforce it, don't write prose about it.** ESLint for style. TypeScript for types. Prettier for formatting. These rules are verifiable, not interpretable.

Moss calls this *backpressure*—automated feedback mechanisms that let agents self-correct.[^7] Without a linter, you waste your time typing messages like "you forgot to add the import" or "that should be a const, not let." With backpressure, the agent runs the build, reads the error, and fixes itself. You remove yourself from trivial corrections and focus on higher-level decisions.

My CLAUDE.md now just says:

```markdown
Run `pnpm lint:fix && pnpm typecheck` after code changes.
```

One line instead of two hundred. Or skip it entirely—use husky to run checks automatically on commit. This is especially useful for techniques like Ralph, where AI works autonomously through a queue of tasks.[^8]

## The Gotchas ESLint Won't Catch

ESLint won't catch this:

> "Nuxt Content v3 caches aggressively in `.data/`. When you modify transformation logic in hooks, you must clear the cache to test changes."

Or this:

{/* > "Don't mock `@nuxt/content/server` internals in tests—it breaks when Nuxt Content updates. Extract pure logic to `server/utils/` instead." */}

Or this:

> "Wiki-links to data collections require path prefixes. Use `[[authors/john-doe]]`, not `[[john-doe]]`."

These are *gotchas*—non-obvious behaviors that bite you once. The kind of thing you'd tell a new team member on their first day. They need documentation, but they don't belong in CLAUDE.md.

**The insight: CLAUDE.md is for universal context. Gotchas are situational.**

You don't need the wiki-link prefix rule in every conversation—only when you're writing content with author links. Loading it every time wastes tokens.

So where do these gotchas go? And how do you capture them without breaking your flow?

## My /learn Skill

My system: when I notice Claude struggling with something we've solved before, I run `/learn`.

This is a Claude Code skill I built ([see full prompt](/prompts/claude/claude-learn-command)). It:

1. Analyzes the conversation for reusable, non-obvious insights
2. Finds the right place in `/docs` to save it (or proposes a new file)
3. Asks for my approval before saving

I end up with a growing knowledge base in my docs folder:

```
docs/
├── nuxt-content-gotchas.md    # 15 hard-won lessons
├── nuxt-component-gotchas.md  # Vue-specific pitfalls
├── testing-strategy.md        # When to use which test type
└── SYSTEM_KNOWLEDGE_MAP.md    # Architecture overview
```

**CLAUDE.md stays stable.** It just tells Claude where to look:

```markdown
## Further Reading

**IMPORTANT:** Before starting any task, identify which docs below are relevant and read them first. Load the full context before making changes.

- `docs/nuxt-content-gotchas.md` - Nuxt Content v3 pitfalls
- `docs/testing-strategy.md` - Test layers and when to use each
```

The **IMPORTANT** instruction is critical—without it, Claude won't automatically read these docs. With it, Claude identifies relevant docs before starting work: content queries trigger the gotchas doc, testing tasks trigger the testing strategy. Progressive disclosure—the right context at the right time.[^2]

Another approach: build skills that load domain-specific gotchas automatically. A `nuxt-content` skill that injects the gotchas doc whenever you're working with content queries. In theory, this is cleaner—context loads without you thinking about it. In practice, I've found skills don't always activate when expected. The trigger conditions can be fuzzy, and sometimes Claude just doesn't invoke them. Vercel's agent evals confirmed this: skills were never invoked in 56% of their test cases, producing zero improvement over baseline.[^9] The docs-based setup is more predictable: I know Claude will read what I point it to.

## One Agent Per Domain

I take this further with custom agents. Each agent has its own documentation file that loads only when needed. If you're new to how these customization layers work together, I wrote a <InternalLink slug="claude-code-customization-guide-claudemd-skills-subagents">detailed comparison of CLAUDE.md, skills, and subagents</InternalLink>.

```
.claude/agents/
├── nuxt-content-specialist.md   # Content queries, MDC, search
├── nuxt-ui-specialist.md        # Component styling, theming
├── vue-specialist.md            # Reactivity, composables
└── nuxt-specialist.md           # Routing, config, deployment
```

When I'm debugging a content query, Claude loads the nuxt-content-specialist. When I'm styling a component, it loads nuxt-ui-specialist. The specialist agents know to fetch the latest documentation from official sources—they don't rely on stale training data.

This is why I don't use MCPs like context7 for documentation. Agents can fetch llms.txt directly from official docs sites and find what they need. No tool definition bloat, no intermediate tokens—just a focused research task in its own context window. I wrote more about <InternalLink slug="why-you-dont-need-nuxt-mcp-claude-code">why I use custom research agents instead of MCPs</InternalLink>.

Skills work similarly—with `context:fork`, they run in isolated contexts without polluting your main conversation. The agent has both the ability and motivation to read real documentation. No context7, no MCP overhead.

## It Compounds

This system creates a feedback loop:

Over time, my `/docs` folder becomes a curated knowledge base of *exactly the things AI coding tools get wrong* in my codebase. It's like fine-tuning, but under my control.

I got this idea from a pattern for self-improving skills where agents automatically analyze sessions and update themselves.[^5] I adapted it to use markdown documentation and a `/learn` command instead—giving me explicit control over what gets captured and where it goes.

An actual entry from my `nuxt-content-gotchas.md`:

```markdown
## Page Collection Queries: Use `stem` Not `slug`

The `slug` field doesn't exist in page-type collections.
Use `stem` (file path without extension) instead:

// ❌ Fails: "no such column: slug"
queryCollection('content').select('slug', 'title').all()

// ✅ Works
queryCollection('content').select('stem', 'title').all()
```

Claude will never make this mistake again in my project. Not because I added it to CLAUDE.md—but because when it's working with content queries, it reads the gotchas doc first.

## My 50-Line CLAUDE.md

The structure:

```markdown
# CLAUDE.md

Second Brain is a personal knowledge base using
Zettelkasten-style wiki-links.

## Commands
pnpm dev          # Start dev server
pnpm lint:fix     # Auto-fix linting issues
pnpm typecheck    # Verify type safety

Run `pnpm lint:fix && pnpm typecheck` after code changes.

## Stack
- Nuxt 4, @nuxt/content v3, @nuxt/ui v3

## Structure
- `app/` - Vue application
- `content/` - Markdown files
- `content.config.ts` - Collection schemas

## Further Reading

**IMPORTANT:** Read relevant docs below before starting any task.

- `docs/nuxt-content-gotchas.md`
- `docs/testing-strategy.md`
- `docs/SYSTEM_KNOWLEDGE_MAP.md`
```

That's it. Universal context only. Everything else lives in docs, agents, or tooling.

## Cross-Tool Compatibility

If you use multiple AI coding tools, you don't need separate config files. VS Code Copilot and Cursor both support `agents.md` for project-level instructions. You can symlink it to share the same configuration:

```bash
# Create a symlink so all tools read the same file
ln -s CLAUDE.md agents.md
```

Now your minimal, focused instructions work across Claude Code, Copilot, and Cursor. One source of truth, no drift between tools.

## How This Played Out Last Week

Last week I was implementing semantic search. When Claude started working on content queries, it read `nuxt-content-gotchas.md` first—as my CLAUDE.md instructs. The stem/slug gotcha was already there.

No mistake. No correction needed.

But during the session, we discovered something new: `queryCollectionSearchSections` returns IDs with a leading slash. Don't add another slash when constructing URLs.

I ran `/learn`. Claude proposed:

```markdown
## Search Section IDs

Returns IDs with leading slash (`/slug#section`).
Don't add another slash when constructing URLs.
```

Added. Next time I work on search, Claude will know.

---

AI tools being stateless isn't a bug to fight. It's a design constraint—like limited screen real estate or slow network connections. Accept it, and you can build systems that work with it.

**Keep CLAUDE.md minimal. Let tooling enforce what it can. Capture learnings as you go. Load context on demand.**

One caveat: you can never be 100% sure agents will read your docs when they face issues. For tricky domains like Nuxt Content—where training data is sparse or outdated—I've learned to be explicit in my prompts. When I know I'm working on something with poor training coverage, I'll add to the plan: "If you encounter issues with Nuxt Content APIs, read `docs/nuxt-content-gotchas.md` first." This nudge makes the difference between the agent guessing based on outdated patterns and actually consulting current knowledge.

The AI forgets. Your documentation doesn't.

---

[^1]: LLMs have no memory between sessions—context is just tokens in a sliding window. See Factory's analysis in [The Context Window Problem](https://factory.ai/news/context-window-problem).

[^2]: HumanLayer's guide on [Writing a Good CLAUDE.md](https://www.humanlayer.dev/blog/writing-a-good-claude-md) recommends keeping files under 60 lines and using progressive disclosure for detailed instructions.

[^5]: Developers Digest, [Self-Improving Skills in Claude Code](https://www.youtube.com/watch?v=-4nUCaMNBR8). A pattern for capturing learnings automatically: skills analyze sessions, extract corrections, and update themselves.

[^6]: Dex Horthy, [No Vibes Allowed: Solving Hard Problems in Complex Codebases](https://www.youtube.com/watch?v=rmvDxxNubIg). Dex is the founder of HumanLayer and creator of the Ralph technique for autonomous AI coding. His [12 Factor Agents](https://www.humanlayer.dev/blog/12-factor-agents) manifesto includes "Make Your Agent a Stateless Reducer" as Factor 12.

[^7]: Moss, [Don't Waste Your Back Pressure](https://banay.me/dont-waste-your-backpressure). Backpressure—automated feedback from type systems, linters, and build tools—is what enables agents to work on longer-horizon tasks without constant human intervention.

[^8]: Geoffrey Huntley, [Ralph](https://ghuntley.com/ralph/). Ralph is a technique for autonomous AI coding where tasks are queued and executed without human intervention, making automated checks on commit essential.

[^9]: Jude Gao, [AGENTS.md outperforms skills in our agent evals](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals). Vercel's evals found that a compressed docs index embedded directly in AGENTS.md achieved 100% pass rate, while skills maxed out at 79% even with explicit instructions—and performed no better than baseline when left to trigger naturally.

---

--- title: How I Built a Skill That Lets Me Talk to Claude's Conversation Memory description: How I built a skill that lets Claude search its own conversation history, turning it into a persistent coding partner that remembers past solutions. tags: ['claude-code', 'ai', 'tooling', 'python'] url: https://alexop.dev/posts/building-conversation-search-skill-claude-code ---

# How I Built a Skill That Lets Me Talk to Claude's Conversation Memory



When I work with Claude Code on complex projects, I often remember discussing a problem or solution but can't find it. "We fixed that EMFILE error last week, what was the solution?" or "What did we work on yesterday?"

Claude Code stores every session locally. But Claude itself can't search those files by default. So I built a skill that lets Claude search its own conversation history.

This turns Claude into a persistent coding partner that actually remembers past solutions.

<Aside type="tip" title="New to Claude Code Skills?">
If you're not familiar with how skills work in Claude Code, check out my <InternalLink slug="claude-code-customization-guide-claudemd-skills-subagents">guide to CLAUDE.md, skills, and subagents</InternalLink> first.
</Aside>

<Aside type="note" title="Just Want the Code?">
If you just want to check out the skill, find it here: [conversation-search skill](https://github.com/alexanderop/dotfiles/tree/main/claude/skills/conversation-search)
</Aside>

## How Claude Code Stores Conversations

Every Claude Code session gets saved as a JSONL file in `~/.claude/projects/`. The directory structure looks like this:

<FileTree tree={[
  { name: ".claude", open: true, children: [
    { name: "projects", open: true, children: [
      { name: "-Users-alex-Projects-myapp", open: true,comment: "// encoded path", children: [
        { name: "a1b2c3d4.jsonl", comment: "// session file" , open: true},
        { name: "b2c3d4e5.jsonl" },
        { name: "c3d4e5f6.jsonl" },
        { name: "e5f6g7h8.jsonl" },
        { name: "agent-xyz123.jsonl", comment: "// subagent session" }
      ]},
      { name: "-Users-alex-Projects-blog", children: [
        { name: "i9j0k1l2.jsonl" }
      ]}
    ]}
  ]}
]} />

The path encoding is simple: replace `/` with `-` and prefix absolute paths with `-`. So `/Users/alex/Projects/myapp` becomes `-Users-alex-Projects-myapp`.

Each JSONL file contains one JSON object per line:

```json
{"type": "user", "timestamp": "2026-01-16T10:30:00Z", "gitBranch": "main", "message": {"content": "Fix the EMFILE error"}}
{"type": "assistant", "timestamp": "2026-01-16T10:30:15Z", "message": {"content": [{"type": "text", "text": "Let me investigate..."}, {"type": "tool_use", "name": "Bash", "input": {"command": "ulimit -n"}}]}}
{"type": "summary", "summary": "Fixed EMFILE error by increasing file descriptor limit"}
```

Each entry includes the role, timestamp, git branch, message content, and tool uses. The `summary` type appears when Claude generates a conversation summary.

## The Skill Structure

The skill lives in `~/.claude/skills/conversation-search/` with two files:

<FileTree open={true} tree={[
  { name: "conversation-search", open: true, children: [
    { name: "SKILL.md", comment: "// trigger patterns and usage" },
    { name: "scripts", open: true, children: [
      { name: "search_history.py", comment: "// the search engine" }
    ]}
  ]}
]} />

The `SKILL.md` file tells Claude when to activate this skill:

```yaml
---
name: conversation-search
description: Search past Claude Code conversation history. Use when asked to recall,
  find, or search for anything from previous conversations. Triggers include
  "what did we do today", "how did we fix X", "search history", "recall when we"...
---
```

When I ask "what did we do yesterday?", Claude recognizes the trigger and knows to use this skill.

## How the Python Script Works

The script has two modes: **digest** for daily summaries and **search** for finding specific solutions.

### Data Structures

The script parses JSONL files into clean dataclasses:

```python
@dataclass
class Message:
    uuid: str
    parent_uuid: Optional[str]
    role: str  # 'user', 'assistant'
    content: str
    timestamp: str
    tool_uses: list
    tool_results: list

@dataclass
class Conversation:
    session_id: str
    file_path: str
    summary: Optional[str]
    messages: list
    project_path: str
    git_branch: Optional[str]
    timestamp: str

@dataclass
class SearchResult:
    conversation: Conversation
    score: float
    matched_messages: list
    problem_excerpt: str
    solution_excerpt: str
    commands_run: list
```

### Relevance Scoring

The search algorithm tokenizes the query and content, then calculates relevance scores with weighted boosts:

```python
def calculate_relevance_score(query: str, conversation: Conversation) -> tuple:
    query_tokens = tokenize(query)
    total_score = 0.0
    matched_messages = []

    # Summary gets highest weight (3x)
    if conversation.summary:
        summary_tokens = tokenize(conversation.summary)
        summary_overlap = len(query_tokens & summary_tokens) / len(query_tokens)
        total_score += summary_overlap * 3.0

    # Check each message
    for msg in conversation.messages:
        msg_tokens = tokenize(msg.content)
        overlap = len(query_tokens & msg_tokens)

        if overlap > 0:
            msg_score = overlap / len(query_tokens)

            # User messages get 1.5x boost (problem descriptions)
            if msg.role == 'user':
                msg_score *= 1.5

            # Messages with tool uses get 1.3x boost (solutions)
            if msg.tool_uses:
                msg_score *= 1.3

            total_score += msg_score
            matched_messages.append(msg)

    return total_score, matched_messages
```

The weighting makes sense: summaries are the most relevant since they capture the essence. User messages describe problems. Tool uses indicate actual solutions.

### Date Filtering

The script supports filtering by date range:

```bash
# Today's sessions only
python3 search_history.py --today "newsletter"

# Yesterday
python3 search_history.py --yesterday "bug fix"

# Last 7 days
python3 search_history.py --days 7 "refactor"

# Since a specific date
python3 search_history.py --since 2026-01-01 "feature"
```

### Extracting Useful Information

The script extracts practical information from each conversation:

```python
def extract_bash_commands(conversation: Conversation) -> list:
    """Extract Bash commands run during the conversation."""
    commands = []
    for msg in conversation.messages:
        for tool in msg.tool_uses:
            if tool.get('name') == 'Bash':
                cmd = tool.get('input', {}).get('command', '')
                if cmd:
                    commands.append(cmd)
    return commands

def extract_files_touched(conversation: Conversation) -> list:
    """Extract files that were read, written, or edited."""
    files = set()
    for msg in conversation.messages:
        for tool in msg.tool_uses:
            name = tool.get('name', '')
            inp = tool.get('input', {})

            if name in ('Read', 'Write', 'Edit'):
                path = inp.get('file_path', '')
                if path:
                    files.add(Path(path).name)
    return sorted(files)[:10]
```

This is useful for recreating solutions. If you found how you fixed something before, you can see exactly which commands you ran and which files you changed.

## Using the Skill

### Daily Digest

Ask "what did we do yesterday?" and Claude runs the digest mode:

```bash
python3 search_history.py --digest yesterday
```

Output:

```
## January 16, 2026 - 32 sessions

### 1. Set Context Menu Feature Spec
   Session: `1498ff91`
   Branch: `fitnessFunctions`
   Files: set-context-menu.md, SetContextMenu.vue, SetContextMenuPO.ts
   Commands: 12 executed

### 2. Fix Pipeline: Missing i18n, Unused Exports
   Session: `23351e77`
   Branch: `fitnessFunctions`
   Files: de.json, en.json, claude-qa.yml
   Commands: 6 executed

### 3. Adding AI Coding Articles to Second Brain
   Session: `5c909423`
   Branch: `main`
   Files: article.md, dex-horthy.md, diagrams-guide.md
   Commands: 1 executed
```

This is great for standup notes or just remembering what you worked on.

### Keyword Search

Ask "how did we fix the EMFILE error?" and Claude searches for relevant sessions:

```bash
python3 search_history.py "EMFILE error" --days 14
```

Output:

```
============================================================
Result #1 (Score: 4.25)
============================================================
Project: /Users/alex/Projects/fitness-app
Session: a1b2c3d4...
Branch: main
Date: 2026-01-10

PROBLEM:
Getting EMFILE error when running tests, too many open files

SOLUTION:
The issue was too many file watchers. Fixed by increasing the limit with
`ulimit -n 10240` and adding it to shell profile...

COMMANDS RUN (3 total):
  $ ulimit -n
  $ ulimit -n 10240
  $ echo "ulimit -n 10240" >> ~/.zshrc
```

Now I can recreate the exact solution without remembering the details.

### Project Filtering

You can narrow searches to a specific project:

```bash
python3 search_history.py "vitest config" --project ~/Projects/fitness-app
```

## Why This Matters

Before this skill, I'd waste time re-solving problems I'd already solved. "I know we discussed this, but I can't find it." Now I just ask Claude.

The benefits:

1. **No more re-solving problems** - Claude finds past solutions instantly
2. **Daily digests for standups** - "What did we work on yesterday?" gives a ready summary
3. **Commands are preserved** - You can recreate exact solutions with the same commands
4. **Cross-project search** - Find solutions from any project you've worked on

The skill turns Claude from a stateless assistant into something closer to a persistent coding partner. It remembers what you've done together.

<Alert type="tip" title="Build Your Own Skills">
If you want to extend Claude Code with custom skills, check out my post on <InternalLink slug="building-my-first-claude-code-plugin">building a Claude Code plugin</InternalLink> for packaging and sharing skills across projects.
</Alert>

---

--- title: In Five Years, Developers Won't Write Code By Hand description: Software development as translation work is dying. Software engineering—the strategic, architectural discipline—is more valuable than ever. The shift is already here. tags: ['ai', 'software-engineering'] url: https://alexop.dev/posts/developers-wont-write-code-by-hand ---

# In Five Years, Developers Won't Write Code By Hand



I haven't written code by hand in months.

This year alone, I built four complete projects using only Claude Code: a markdown editor, a Nuxt blog starter, a workout tracking app, and the Second Brain you might be reading this on. At work, I regularly one-shot entire issues without touching my keyboard for anything except prompts. Last week, I resolved a production incident using VS Code Copilot while barely glancing at the actual code.

I'm not special. I'm just paying attention.

And I'm not alone. Simon Willison[^1]—one of the most respected voices in the developer community—put it bluntly on the Oxide and Friends podcast:

> I think the job of being paid money to type code into a computer will go the same way as punching punch cards [...] I do not think anyone will be paid to just do the thing where you type the code. I think software engineering will still be an enormous career. I just think the software engineers won't be spending multiple hours of their day in a text editor typing out syntax.

But here's the part that matters:

> The more time I spend on AI-assisted programming the less afraid I am for my job, because it turns out building software—especially at the rate it's now possible to build—still requires enormous skill, experience and depth of understanding. The skills are changing though! Being able to read a detailed specification and transform it into lines of code is the thing that's being automated away. What's left is everything else, and the more time I spend working with coding agents the larger that "everything else" becomes.

That "everything else" is the whole point.

## The Shift Is Already Here

In five years, developers won't write code by hand. This isn't a prediction about some distant future—it's a description of what's already happening to anyone using the right tools.

The reason most people don't see it? Two things: skill gaps and companies failing to provide developers with modern tooling. Most developers are still typing every character. Most companies are still debating whether AI tools are "worth the license cost." Meanwhile, the developers who figured this out are shipping at 10x the pace.

The creator of Claude Code uses Claude Code to work on multiple features simultaneously. Techniques like Ralph[^2]—an automation framework that breaks work into discrete chunks—can literally rip through your entire backlog. This isn't theoretical. It's happening now, in production, at companies that stopped waiting for permission. (For a deep dive into how these tools actually work, see my <InternalLink slug="understanding-claude-code-full-stack">guide to Claude Code's architecture</InternalLink>.)

## The Great Distinction Nobody Talks About

Here's what changes everything: understanding the difference between software *engineering* and software *development*.

**Software engineering** is designing systems. Architecture decisions. Test strategies. The guardrails that keep a codebase healthy over time. Knowing what to build and—more importantly—what not to build.

**Software development** is writing the actual code. Translating specifications into syntax. Converting tickets into pull requests.

One of these is a creative, strategic discipline. The other is translation work.

Software development is dying. Software engineering is more valuable than ever.

Kent Beck[^3] put it perfectly: 90% of traditional skills have lost their economic value because AI can replicate them efficiently. But the remaining 10%? They gain 1000x leverage through AI augmentation. The question you need to answer: which skills are your 10%?

## Scrum Was a Workaround for Human Limitations

Think about why we created Scrum in the first place.

We needed big teams with specialized roles because implementing features took forever. Frontend developers, backend developers, QA engineers, DevOps specialists—all coordinating through ceremonies and tickets because the bottleneck was literally typing characters into an editor.

In the worst cases—an anti-pattern far too common—managers saw developers as "code monkeys" who converted tickets into code. The developer's job was translation, not thinking.

This made sense when coding was slow. When a feature took days or weeks to implement.

Those days are over.

When implementation takes days, you need ceremonies to coordinate. When implementation takes minutes, the coordination overhead becomes the bottleneck. Scrum isn't dying because it was bad—it's dying because the constraint it solved no longer exists.

## The New Economics

The math has fundamentally changed.

Prototypes are cheap now. What took a sprint takes an afternoon. Burke Holland[^4], a Microsoft developer advocate, built four substantial projects with AI—including Swift applications in a language he doesn't know. His advice? "Make things. Stop waiting to have all the answers... you can make things faster than you ever thought possible."

I've watched product owners use Claude Code to generate their own prototypes, fix simple bugs, and submit pull requests. They're not becoming developers—they're just not waiting for developers anymore.

Ralph-style automation lets you feed your backlog to an AI and get working code out the other end. Not perfect code. Not production-ready code on the first try. But functional code that's 80% there, leaving humans to handle the remaining 20% that actually requires judgment.

The developers who thrive aren't writing more code. They're orchestrating AI to write code for them, then applying their expertise to the parts that matter.

## The Hard Part Was Never Coding

Here's the uncomfortable truth: coding was never the hard part. We just convinced ourselves it was because it took so much *time*.

Lee Robinson[^5]—who went from Vercel to Cursor—built a Rust image compressor, a SvelteKit web app, and a hardware game without writing code by hand. His reflection? "Writing code was never really the bottleneck, especially for larger projects." And: "It wasn't about the code... It's about building something great and something that I'm proud of."

The actually hard problems haven't changed:
- Understanding what customers need (not what they say they need)
- Writing specifications clear enough that anyone—human or AI—can implement them
- Knowing what to build and what to skip
- Making architectural decisions that won't haunt you in two years
- Marketing, positioning, product sense

These are human problems. Creative problems. Strategic problems.

Martin Fowler[^6] argues this is the biggest shift since assembly to high-level languages. But here's what he gets right: AI lacks architectural judgment. It cannot distinguish good patterns from poor ones. It can write code all day, but it can't tell you whether that code should exist.

The value shifts from writing code to knowing what code to write and why.

## "But AI Code Is Buggy"

Yes. And?

The first high-level language compilers produced worse machine code than hand-written assembly. Early web frameworks were slower than hand-crafted HTML. Every abstraction layer introduces inefficiencies.

We adopt them anyway because developer productivity matters more than perfect output. The question isn't "is AI code flawless?"—it's "is AI code good enough, fast enough, to change the economics?"

The answer is yes. Today. Not in five years—today.

I'm not arguing AI produces better code than expert developers. I'm arguing it produces acceptable code fast enough that the calculus changes. When you can generate ten implementations in the time it takes to write one, you can afford to throw away the bad ones.

The skeptics are optimizing for the wrong variable. They're measuring code quality when they should be measuring iteration speed.

## How to Prepare

Geoffrey Huntley[^7] put it bluntly: "Software engineers who haven't adopted or started exploring software assistants, are frankly not gonna make it."

But here's the nuance he adds: "I suspect there's not going to be mass-layoffs for software developers due to AI. Instead, what we will see is a natural attrition between those who invest in themselves right now and those who do not."

This isn't about being replaced by AI. It's about being outperformed by developers who use AI. The gap is already opening. (I wrote about this dynamic in <InternalLink slug="the-age-of-the-generalist">The Age of the Generalist</InternalLink>—high-agency builders thrive while passive specialists struggle.)

If you want to thrive in this new world, here's where to focus:

**Learn how LLMs actually work.** Not to build models—to orchestrate them. Understand context windows, token limits, prompt engineering. Know why your AI assistant suddenly "forgot" what you told it three messages ago. This isn't optional knowledge anymore; it's table stakes. (For practical starting points, see <InternalLink slug="how-i-use-llms">how I use LLMs in my daily work</InternalLink>.)

**Study the architecture of AI agents.** The developers who can build custom agents for their specific workflows have superpowers the rest of the industry doesn't understand yet. Resources like the 12 Factor Agents[^8] manifesto lay out the principles: small focused agents, deterministic control flow with strategic LLM decision points, and proper context window management. Learn what context engineering means. Understand why RAG exists. Build something that automates your own repetitive work.

**Double down on software engineering.** System design, architecture patterns, testing strategies—these skills become more valuable, not less. When anyone can generate code, the people who know what code to generate become invaluable.

**Stop optimizing for code output.** Start optimizing for clarity of thought, quality of specifications, and speed of iteration. Your value isn't in the characters you type; it's in the decisions you make.

## The Paradox

Here's what I find fascinating: I don't think we'll ever get AI that matches human agency and creativity. The models might plateau. They might not get dramatically "smarter" than they are today.

It doesn't matter.

Even with current capabilities, as tooling improves, we're witnessing the biggest transformation in software development history. The change isn't coming from AI replacing human thinking—it's coming from AI eliminating the translation layer between human thinking and working software.

You don't need AGI to automate code. You just need models that are good enough at translation, combined with humans who are good enough at specification.

We have both. Right now.

---

The question isn't whether this shift will happen. It's whether you'll be ready when your company finally notices.

[^1]: Simon Willison, [LLM Predictions for 2026](https://simonwillison.net/2026/Jan/8/llm-predictions-for-2026)
[^2]: [Ralph](https://github.com/snarktank/ralph) - Automation framework for AI-driven development
[^3]: Kent Beck, [90% of My Skills Are Now Worth $0](https://tidyfirst.substack.com/p/90-of-my-skills-are-now-worth-0)
[^4]: Burke Holland, [Opus 4.5 is Going to Change Everything](https://burkeholland.github.io/posts/opus-4-5-change-everything/)
[^5]: Lee Robinson, [AI codes better than me. Now what?](https://www.youtube.com/watch?v=UrNLVip0hSA)
[^6]: Martin Fowler, [How AI Will Change Software Engineering](https://www.youtube.com/watch?v=CQmI4XKTa0U)
[^7]: Geoffrey Huntley, [What do I mean by some software devs are "ngmi"?](https://ghuntley.com/ngmi/)
[^8]: [12 Factor Agents](https://www.humanlayer.dev/blog/12-factor-agents) - Principles for production-grade AI agents

---

--- title: Mutation Testing with AI Agents When Stryker Doesn't Work description: When Stryker doesn't support your test stack, AI agents can execute mutation testing manually. A practical approach for Vitest browser mode and Playwright. tags: ['testing', 'ai', 'claude-code', 'vitest'] url: https://alexop.dev/posts/mutation-testing-ai-agents-vitest-browser-mode ---

# Mutation Testing with AI Agents When Stryker Doesn't Work



## The Coverage Lie

Code coverage lies. A test that exercises a line doesn't mean it verifies that line does the right thing:

```typescript
function add(a: number, b: number): number {
  return a + b
}

// 100% coverage - would still pass if add() returned 999
it('adds numbers', () => {
  add(2, 2)
})
```

Mutation testing flips the question. Instead of asking "did tests run this code?", it asks **"if I break this code, do tests fail?"**

Using our `add` example, a mutation tester would:

```typescript
// Original
function add(a: number, b: number): number {
  return a + b
}

// Mutated: swap + for -
function add(a: number, b: number): number {
  return a - b  // <-- bug introduced
}
```

Now run the test. `add(2, 2)` returns `0` instead of `4`. Does the test fail? No—it never checked the result. **The mutant survives.** Your test has a gap.

The process:
1. **Mutate**: Introduce a small bug (change `>` to `>=`, swap `&&` for `||`, delete a line)
2. **Run tests**: Execute your test suite against the mutated code
3. **Evaluate**: If tests pass with the bug, your tests are weak. If tests fail, they caught it.

A mutation that tests fail to catch is a "surviving mutant"—proof of a test gap.

---

## When Stryker Works: The Gold Standard

When your test stack supports it, automated mutation testing with Stryker is the way to go. It's fast, deterministic, generates HTML reports, and runs in CI pipelines. This is especially valuable when you have pure functions with high test coverage but want to verify test quality.

Here's what it looks like in practice:

```bash
pnpm test:mutation
# or: stryker run
```

```
INFO ProjectReader Found 7 of 2947 file(s) to be mutated.
INFO Instrumenter Instrumented 7 source file(s) with 394 mutant(s)
INFO DryRunExecutor Initial test run succeeded. Ran 184 tests in 0 seconds.

Mutation testing  [====================] 100% | 394/394 Mutants tested
(35 survived, 0 timed out)

--------------|---------|----------|----------|----------|
File          |  % score | # killed | # survived | # no cov |
--------------|---------|----------|----------|----------|
All files     |   90.86 |      358 |         35 |        1 |
 backlinks.ts |   96.30 |       26 |          1 |        0 |
 callouts.ts  |   93.94 |       62 |          4 |        0 |
 graph.ts     |   91.55 |       65 |          6 |        0 |
 mentions.ts  |   91.30 |       63 |          5 |        1 |
 minimark.ts  |   82.61 |       76 |         16 |        0 |
 text.ts      |  100.00 |       34 |          0 |        0 |
 wikilinks.ts |   91.43 |       32 |          3 |        0 |
--------------|---------|----------|----------|----------|

INFO MutationTestExecutor Done in 36 seconds.
```

394 mutants tested across 7 files in 36 seconds. The report shows exactly which files have weak spots—`minimark.ts` at 82.61% needs attention, while `text.ts` is solid at 100%.

Stryker also generates an interactive HTML report where you can drill into each surviving mutant and see exactly what code change your tests failed to catch.

<Alert type="tip" title="Use Stryker When You Can">
  If your stack supports Stryker (standard Vitest in Node mode, Jest, Mocha), use it. Deterministic tooling in your CI pipeline beats manual approaches every time. The AI agent technique in this post is for when Stryker isn't an option.
</Alert>

---

## The Vitest Browser Mode Problem

But what if Stryker doesn't support your stack? Stryker doesn't work with Vitest's browser mode. Their instrumentation assumes Node.js execution, but browser mode runs tests in actual Chromium via Playwright.

My setup:
- **Framework**: Vitest 4 with `browser.enabled: true`
- **Provider**: Playwright (Chromium)
- **Test style**: Integration tests with real DOM

<InternalLink slug="vue3_testing_pyramid_vitest_browser_mode">My testing strategy</InternalLink> relies heavily on Vitest browser mode for realistic user flow testing. Stryker's mutation coverage reports? Not an option. And switching to Node-based testing would mean losing the browser-specific behavior I'm actually testing.

---

## AI Agents as Manual Mutation Testers

The mutation testing algorithm is simple enough that an AI coding agent can execute it manually. Claude Code can:

1. Read your source code
2. Apply mutations systematically
3. Run `pnpm test --run`
4. Record whether tests passed or failed
5. Restore the original code
6. Report surviving mutants with suggested fixes

I adapted a <InternalLink slug="claude-code-customization-guide-claudemd-skills-subagents">Claude Code skill</InternalLink> originally created by [Paul Hammond](https://www.linkedin.com/posts/paul-hammond-bb5b78251_mutation-testing-is-typically-expensive-but-activity-7414719212071473152-_xTm) that codifies this workflow.

```mermaid
flowchart TD
    subgraph Agent["AI Agent Workflow"]
        A[Read source file] --> B[Identify mutation targets]
        B --> C[Apply single mutation]
        C --> D[Run test suite]
        D --> E{Tests fail?}
        E -->|Yes| F[Mutant KILLED]
        E -->|No| G[Mutant SURVIVED]
        F --> H[Restore original code]
        G --> H
        H --> I{More mutations?}
        I -->|Yes| C
        I -->|No| J[Generate report]
    end

    subgraph Results["Report Output"]
        J --> K[Killed mutants: Tests caught the bug]
        J --> L[Survived mutants: Test gaps found]
        L --> M[Suggested fixes for each gap]
    end

    style G fill:#f96,stroke:#333
    style F fill:#6f9,stroke:#333
    style L fill:#f96,stroke:#333
    style K fill:#6f9,stroke:#333
```

### The Mutation Testing Skill

The skill defines mutation operators in priority order:

**Priority 1 - Boundaries** (most likely to survive):

| Original | Mutate To |
|----------|-----------|
| `<` | `<=` |
| `>` | `>=` |
| `<=` | `<` |
| `>=` | `>` |

**Priority 2 - Boolean Logic**:

| Original | Mutate To |
|----------|-----------|
| `&&` | `\|\|` |
| `\|\|` | `&&` |
| `!condition` | `condition` |

**Priority 3 - Return Values**:

| Original | Mutate To |
|----------|-----------|
| `return x` | `return null` |
| `return true` | `return false` |
| Early return | Remove it |

**Priority 4 - Statement Removal**:

| Original | Mutate To |
|----------|-----------|
| `array.push(x)` | Remove |
| `await save(x)` | Remove |
| `emit('event')` | Remove |

The agent applies each mutation one at a time, runs tests, records results, and restores the original code immediately.

---

## Real Example: Settings Feature

I ran this against my settings feature. The integration tests looked comprehensive—theme toggling, language switching, unit preferences. Code coverage would show high percentages.

**Results: 38% mutation score** (5 killed, 8 survived out of 13 mutations)

Here's what the AI agent found:

### Surviving Mutant #1: Volume Boundary Not Tested

```typescript
// Original (stores/settings.ts:65)
Math.min(Math.max(volume, 0.5), 1)

// Mutation: Change 0.5 to 0.4
Math.min(Math.max(volume, 0.4), 1)

// Result: Tests PASSED -> Mutant SURVIVED
```

My tests never verified the minimum volume constraint. A bug changing the minimum from 50% to 40% would ship undetected.

### Surviving Mutant #2: Theme DOM Class Not Verified

```typescript
// Original (composables/useTheme.ts:26)
newMode === 'dark'

// Mutation: Negate the condition
newMode !== 'dark'

// Result: Tests PASSED -> Mutant SURVIVED
```

My test checked that clicking the toggle changed the stored preference. It never verified that `document.documentElement.classList` actually received the `dark` class. The UI could break while tests pass.

### Surviving Mutant #3: Error Handling Path Untested

```typescript
// Original (stores/settings.ts:28)
if (error) return

// Mutation: Negate the condition
if (!error) return

// Result: Tests PASSED -> Mutant SURVIVED
```

No test exercised the error handling branch. A bug that inverted error handling would go unnoticed.

### The Fixes

The agent suggested specific tests for each surviving mutant:

```typescript
// Fix for Mutant #1: Boundary test
it('volume slider has minimum value constraint of 50%', async () => {
  const volumeSlider = page.getByTestId('timer-sound-volume-slider')
  await expect.poll(async () => {
    const el = await volumeSlider.element()
    return el.getAttribute('min')
  }).toBe('0.5')
})

// Fix for Mutant #2: DOM verification
it('adds dark class to html element when dark mode enabled', async () => {
  const themeToggle = page.getByTestId('theme-toggle')
  await userEvent.click(themeToggle)

  await expect.poll(() =>
    document.documentElement.classList.contains('dark')
  ).toBe(true)
})
```

---

## How to Set This Up

### Step 1: Create the Skill

Save this as `.claude/skills/mutation-testing/SKILL.md`:

<details>
<summary>Full Mutation Testing Skill (click to expand)</summary>

```markdown
---
name: mutation-testing
description: |
  Mutation testing patterns for verifying test effectiveness. Use when analyzing branch code
  to find weak or missing tests. Triggers: "mutation testing", "test effectiveness",
  "would tests catch this bug", "weak tests", "are my tests good enough", "surviving mutants".
---

# Mutation Testing

Mutation testing answers: **"Would my tests catch this bug?"** by actually introducing bugs and running tests.

---

## Execution Workflow

**CRITICAL**: This skill actually mutates code and runs tests. Follow this exact process:

### Step 1: Identify Target Code

git diff main...HEAD --name-only | grep -E '\.(ts|js|tsx|jsx|vue)' | grep -v '\.test\.' | grep -v '\.spec\.'

### Step 2: For Each Function to Test

Execute this loop for each mutation:

1. READ the original file and note exact content
2. APPLY one mutation (edit the code)
3. RUN tests: pnpm test --run (or specific test file)
4. RECORD result: KILLED (test failed) or SURVIVED (test passed)
5. RESTORE original code immediately
6. Repeat for next mutation

### Step 3: Report Results

After all mutations, provide a summary table:

| Mutation | Location | Result | Action Needed |
|----------|----------|--------|---------------|
| `>` → `>=` | file.ts:42 | SURVIVED | Add boundary test |
| `&&` → `||` | file.ts:58 | KILLED | None |

---

## Mutation Operators to Apply

### Priority 1: Boundary Mutations (Most Likely to Survive)

| Original | Mutate To | Why It Matters |
|----------|-----------|----------------|
| `<` | `<=` | Boundary not tested |
| `>` | `>=` | Boundary not tested |
| `<=` | `<` | Equality case missed |
| `>=` | `>` | Equality case missed |

### Priority 2: Boolean Logic Mutations

| Original | Mutate To | Why It Matters |
|----------|-----------|----------------|
| `&&` | `\|\|` | Only tested when both true |
| `\|\|` | `&&` | Only tested when both false |
| `!condition` | `condition` | Negation not verified |

### Priority 3: Arithmetic Mutations

| Original | Mutate To | Why It Matters |
|----------|-----------|----------------|
| `+` | `-` | Tested with 0 only |
| `-` | `+` | Tested with 0 only |
| `*` | `/` | Tested with 1 only |

### Priority 4: Return/Early Exit Mutations

| Original | Mutate To | Why It Matters |
|----------|-----------|----------------|
| `return x` | `return null` | Return value not asserted |
| `return true` | `return false` | Boolean return not checked |
| `if (cond) return` | `// removed` | Early exit not tested |

### Priority 5: Statement Removal

| Original | Mutate To | Why It Matters |
|----------|-----------|----------------|
| `array.push(x)` | `// removed` | Side effect not verified |
| `await save(x)` | `// removed` | Async operation not verified |
| `emit('event')` | `// removed` | Event emission not tested |

---

## Practical Execution Example

### Example: Testing a Validation Function

**Original code** (`src/utils/validation.ts:15`):

export function isValidAge(age: number): boolean {
  return age >= 18 && age <= 120;
}

**Mutation 1**: Change `>=` to `>`

export function isValidAge(age: number): boolean {
  return age > 18 && age <= 120;  // MUTATED
}

**Run tests**: `pnpm test --run src/__tests__/validation.test.ts`

**Result**: Tests PASS → **SURVIVED** (Bad! Need test for `isValidAge(18)`)

**Restore original code immediately**

**Mutation 2**: Change `&&` to `||`

export function isValidAge(age: number): boolean {
  return age >= 18 || age <= 120;  // MUTATED
}

**Run tests**: `pnpm test --run src/__tests__/validation.test.ts`

**Result**: Tests FAIL → **KILLED** (Good! Tests catch this bug)

**Restore original code immediately**

---

## Results Interpretation

### Mutant States

| State | Meaning | Action |
|-------|---------|--------|
| **KILLED** | Test failed with mutant | Tests are effective |
| **SURVIVED** | Tests passed with mutant | **Add or strengthen test** |
| **TIMEOUT** | Tests hung (infinite loop) | Counts as detected |

### Mutation Score

Score = (Killed + Timeout) / Total Mutations * 100

| Score | Quality |
|-------|---------|
| < 60% | Weak - significant test gaps |
| 60-80% | Moderate - improvements needed |
| 80-90% | Good - minor gaps |
| > 90% | Strong test suite |

---

## Fixing Surviving Mutants

When a mutant survives, add a test that would catch it:

### Surviving: Boundary mutation (`>=` → `>`)

// Add boundary test
it('accepts exactly 18 years old', () => {
  expect(isValidAge(18)).toBe(true);  // Would fail if >= became >
});

### Surviving: Logic mutation (`&&` → `||`)

// Add test with mixed conditions
it('rejects when only one condition met', () => {
  expect(isValidAge(15)).toBe(false);  // Would pass if && became ||
});

### Surviving: Statement removal

// Add side effect verification
it('saves to database', async () => {
  await processOrder(order);
  expect(db.save).toHaveBeenCalledWith(order);  // Would fail if save removed
});

---

## Quick Checklist During Mutation

For each mutation, ask:

1. **Before mutating**: Does a test exist for this code path?
2. **After running tests**: Did any test actually fail?
3. **If survived**: What specific test would catch this?
4. **After fixing**: Re-run mutation to confirm killed

---

## Common Surviving Mutation Patterns

### Tests Only Check Happy Path

// WEAK: Only tests success case
it('validates', () => {
  expect(validate(goodInput)).toBe(true);
});

// STRONG: Tests both cases
it('validates good input', () => {
  expect(validate(goodInput)).toBe(true);
});
it('rejects bad input', () => {
  expect(validate(badInput)).toBe(false);
});

### Tests Use Identity Values

// WEAK: Mutation survives
expect(multiply(5, 1)).toBe(5);  // 5*1 = 5/1 = 5

// STRONG: Mutation detected
expect(multiply(5, 3)).toBe(15);  // 5*3 ≠ 5/3

### Tests Don't Assert Return Values

// WEAK: No return value check
it('processes', () => {
  process(data);  // No assertion!
});

// STRONG: Asserts outcome
it('processes', () => {
  const result = process(data);
  expect(result).toEqual(expected);
});

---

## Important Rules

1. **ALWAYS restore original code** after each mutation
2. **Run tests immediately** after applying mutation
3. **One mutation at a time** - don't combine mutations
4. **Focus on changed code** - prioritize branch diff
5. **Track all results** - report full mutation summary

---

## Summary Report Template

After completing mutation testing, provide:

## Mutation Testing Results

**Target**: `src/features/workout/utils.ts` (functions: X, Y, Z)
**Total Mutations**: 12
**Killed**: 9
**Survived**: 3
**Score**: 75%

### Surviving Mutants (Action Required)

| # | Location | Original | Mutated | Suggested Test |
|---|----------|----------|---------|----------------|
| 1 | line 42 | `>=` | `>` | Test boundary value |
| 2 | line 58 | `&&` | `\|\|` | Test mixed conditions |
| 3 | line 71 | `emit()` | removed | Verify event emission |

### Killed Mutants (Tests Effective)

- Line 35: `+` → `-` killed by `calculation.test.ts`
- Line 48: `true` → `false` killed by `validate.test.ts`
- ...
```

</details>

### Step 2: Invoke It

```bash
claude "Run mutation testing on the settings feature"
```

The agent will:
- Find changed files on your branch
- Identify testable functions
- Apply mutations systematically
- Report surviving mutants with suggested test fixes

### Step 3: Review and Fix

The agent produces a markdown report. Review each surviving mutant and decide:
- Add the suggested test
- Accept the risk (document why)
- Refactor the code to be more testable

---

## When to Use This Approach

| Good Fit | Not Ideal |
|----------|-----------|
| Vitest browser mode (no Stryker support) | Large codebases needing full mutation coverage |
| Playwright component testing | CI/CD automation (manual agent invocation) |
| Small-to-medium codebases | Strict mutation score thresholds |
| Pre-merge review of specific features | |
| Learning what makes tests effective | |

<Alert type="tip" title="Complement, Don't Replace">
  This approach works best alongside your existing testing strategy. Use it to spot-check critical features before merge, not as a replacement for automated mutation testing where available.
</Alert>

<Alert type="info" title="Feature Branches, Not Pipelines">
  This skill shines on **feature branches** where you want to validate test quality before merging. Running AI agents in CI/CD pipelines is possible—you could build <InternalLink slug="building_ai_qa_engineer_claude_code_playwright">an automated QA agent</InternalLink> with the Claude Agent SDK—but it adds complexity and cost. For pipeline automation, deterministic tools like Stryker remain the better choice when your stack supports them. Think of this as a developer tool for improving tests during development, not a CI gate.
</Alert>

---

## Key Takeaways

1. **Coverage doesn't equal confidence.** High code coverage can coexist with ineffective tests.

2. **Mutation testing reveals test gaps.** By breaking code and checking if tests notice, you find what's actually being verified.

3. **AI agents can execute manual mutation testing.** When tooling doesn't support your stack, an agent can apply the algorithm systematically.

4. **Focus on surviving mutants.** Each one is a potential bug your tests wouldn't catch.

5. **This complements, not replaces.** Use this alongside coverage reports, not instead of automated mutation testing where available.

---

## Resources

- [Paul Hammond's Mutation Testing Skill](https://github.com/citypaul/.dotfiles/blob/main/claude/.claude/skills/mutation-testing/SKILL.md) - The original skill this post is based on
- [Mutation Testing on Wikipedia](https://en.wikipedia.org/wiki/Mutation_testing)
- [Stryker Mutator](https://stryker-mutator.io/) - When your stack supports it
- <InternalLink slug="custom-tdd-workflow-claude-code-vue">My TDD workflow with Claude Code</InternalLink> - Related approach for test-first development

---

--- title: Why You Don't Need the Nuxt MCP When You Use Claude Code description: Why I use custom research agents instead of MCP servers for AI-assisted development. Learn how llms.txt enables context-efficient documentation fetching with a practical Nuxt Content agent example. tags: ['ai', 'claude-code', 'nuxt', 'tooling'] url: https://alexop.dev/posts/why-you-dont-need-nuxt-mcp-claude-code ---

# Why You Don't Need the Nuxt MCP When You Use Claude Code



I think we all love Nuxt. One problem with using Nuxt for AI is that training data is not up to date. This is especially true for Nuxt Content where often times LLMs still think they're working with Nuxt 2. This is why the Nuxt team created their MCP server.

I think the MCP is good and perfectly fine. But for me—and also for Anthropic itself—MCPs in the current spec have the problem of context bloat. Anthropic has [written down this problem perfectly](https://www.anthropic.com/engineering/code-execution-with-mcp) in their engineering blog.

<Alert type="note" title="The Context Bloat Problem">
Anthropic identifies two main issues: **tool definition overload** (loading all tools upfront creates hundreds of thousands of tokens before the model even reads your request) and **intermediate result redundancy** (every result must pass through the model, sometimes processing 50,000+ tokens per operation).
</Alert>

If you want to dive deeper into what MCP is and how it works, check out my post on <InternalLink slug="what-is-model-context-protocol-mcp">What Is the Model Context Protocol (MCP)?</InternalLink>.

## Why I Use Custom Research Agents Instead

This is why for all my projects I don't use MCP but I use custom research agents.

All websites nowadays use `llms.txt`. Now if you let an LLM fetch `llms.txt` first, it can perfectly find every information needed from the docs itself.

I've written about <InternalLink slug="how-i-added-llms-txt-to-my-astro-blog">how I added llms.txt to my own blog</InternalLink>—it's becoming a standard way for sites to expose their content to AI.

This approach has several advantages:

1. **Only the description gets loaded as context** — The agent description is minimal, not the entire tool schema
2. **You can customize it** — Full control over what the agent knows and how it behaves
3. **It runs in its own context** — Your main agent could use the research agent only to gather information and then continue with its work without polluting its context window

This is essentially the same pattern I described in my post about <InternalLink slug="claude-code-customization-guide-claudemd-skills-subagents">Claude Code subagents</InternalLink> — agents keep your main context clean by delegating specialized tasks.

<Alert type="tip" title="Claude Code Uses This Pattern Too">
Claude Code itself uses this exact approach. When you ask it questions about its own features, it spawns a [`claude-code-guide` agent](https://github.com/Piebald-AI/claude-code-system-prompts/blob/main/system-prompts/agent-prompt-claude-guide-agent.md) that fetches from a documentation sitemap and answers based on current docs—not training data. We're just applying the same pattern to other libraries.
</Alert>

## Example: Nuxt Content Specialist Agent

Here's how my Nuxt Content agent looks. Just put it under `.claude/agents`:

<FileTree tree={[
  { name: ".claude", open: true, children: [
    { name: "agents", open: true, children: [
      { name: "nuxt-content-specialist.md", comment: "// Your custom agent" }
    ]}
  ]}
]} />

<Collapsible title="Full agent definition">
````markdown
---
name: nuxt-content-specialist
description: Use this agent when the task involves @nuxt/content v3 in any way - implementing, modifying, querying, reviewing, or improving content management code. This includes creating or modifying content collections, writing queries, implementing MDC components, configuring content sources, troubleshooting content-related issues, or reviewing existing content code for improvements and best practices.\n\nExamples:\n\n<example>\nContext: User asks about improving their Nuxt Content implementation.\nuser: "What can I improve on this codebase when it comes to Nuxt Content?"\nassistant: "I'll use the nuxt-content-specialist agent to review your content implementation against current best practices."\n<commentary>\nSince the user is asking about Nuxt Content improvements, use the nuxt-content-specialist agent to fetch the latest documentation and review the existing code for optimization opportunities, missing features, and best practice violations.\n</commentary>\n</example>\n\n<example>\nContext: User needs to add a new content collection.\nuser: "I need to add a 'blog' collection separate from pages"\nassistant: "I'll use the nuxt-content-specialist agent to implement this correctly."\n<commentary>\nSince the user needs to modify the content collection schema, use the nuxt-content-specialist agent to first fetch the latest Nuxt Content documentation and then implement the collection following best practices.\n</commentary>\n</example>\n\n<example>\nContext: User is asking about content query patterns.\nuser: "How do I query content by multiple tags in Nuxt Content?"\nassistant: "Let me use the nuxt-content-specialist agent to provide an accurate answer based on the current documentation."\n<commentary>\nSince the user is asking about Nuxt Content query capabilities, use the nuxt-content-specialist agent to fetch documentation and provide an accurate, up-to-date response about queryCollection filtering.\n</commentary>\n</example>\n\n<example>\nContext: User wants to embed Vue components in Markdown.\nuser: "How do I use a custom component inside my markdown files?"\nassistant: "I'll consult the nuxt-content-specialist agent to explain MDC syntax correctly."\n<commentary>\nSince this involves MDC (Markdown Components) syntax, use the nuxt-content-specialist agent to fetch relevant documentation about component usage in Markdown files.\n</commentary>\n</example>\n\n<example>\nContext: User needs to implement content search.\nuser: "I want to add full-text search to my content site"\nassistant: "I'll use the nuxt-content-specialist agent to implement search with queryCollectionSearchSections."\n<commentary>\nSince search requires specific Nuxt Content APIs, use the nuxt-content-specialist agent to fetch the latest documentation on search implementation patterns.\n</commentary>\n</example>
model: opus
color: green
---

# Nuxt Content Specialist Agent

This document defines the Nuxt Content specialist agent's role and responsibilities for helping users with @nuxt/content v3 implementations.

## Primary Domain

**@nuxt/content v3**: Content management system for Nuxt applications providing file-based content with Markdown support, MDC syntax for embedding Vue components, SQLite-based querying, and full-text search capabilities.

### Core Expertise Areas

1. **Collections**: Defining collections in `content.config.ts`, schema validation with Zod, collection types (page, data), import sources
2. **Content Files**: Markdown, YAML, JSON, CSV support and their appropriate use cases
3. **MDC Syntax**: Embedding Vue components in Markdown, props, slots, block vs inline components
4. **Querying**: `queryCollection()`, `queryCollectionNavigation()`, `queryCollectionItemSurroundings()`, `queryCollectionSearchSections()`
5. **Rendering**: `<ContentRenderer>`, `<Slot>`, prose components, custom renderers
6. **Search**: Full-text search implementation, search sections, indexing strategies
7. **Sources**: Custom data sources, remote content, transformers
8. **Deployment**: Static generation, server rendering, edge deployment considerations

## Documentation Sources

The agent leverages one primary documentation resource:

- **Nuxt Content docs** (`https://content.nuxt.com/llms.txt`): Covers collection definitions, querying APIs, MDC syntax, content rendering, search implementation, custom sources, and deployment patterns

### Key Documentation Sections

| Section | URL Path | Purpose |
|---------|----------|---------|
| Collections | `/docs/collections` | Collection definitions and configuration |
| Querying | `/docs/querying` | Query composables and filtering |
| ContentRenderer | `/docs/components/content-renderer` | Rendering content |
| Markdown/MDC | `/docs/files/markdown` | Markdown and MDC syntax |
| Search | `/docs/recipes/search` | Search implementation |
| Sources | `/docs/advanced/sources` | Custom content sources |

## Operational Approach

The agent follows a structured methodology:

1. **Fetch documentation index** from `https://content.nuxt.com/llms.txt` to understand available documentation structure
2. **Categorize user inquiry** into appropriate domain (collections, querying, MDC, search, etc.)
3. **Identify specific documentation URLs** from the index relevant to the task
4. **Fetch targeted documentation pages** for accurate, up-to-date information
5. **Review project context** by reading relevant local files (`content.config.ts`, existing content files)
6. **Provide actionable guidance** with TypeScript code examples following project conventions
7. **Reference documentation sources** to support recommendations

## Core Guidelines

- Prioritize official documentation over training knowledge (v3 has significant v2 differences)
- Maintain concise, actionable responses
- Include TypeScript code examples following project conventions
- Reference specific documentation URLs consulted
- Avoid emojis
- Always verify API specifics against fetched documentation before providing guidance
- Note v2 to v3 migration considerations when relevant
- Consider static vs server rendering implications
- Handle content not found scenarios gracefully in implementations

## Project Context

This agent operates within a Nuxt 4 application using:

- **@nuxt/content v3** with SQLite-based querying
- **@nuxt/ui v3** for UI components
- **TypeScript** for type safety
- **File-based routing** with catch-all content routes in `app/` directory

### Established Patterns

```typescript
// content.config.ts - Collection definition pattern
export const collections = {
  content: defineCollection({
    type: 'page',
    source: '**/*.md'
  })
}
```

```vue
<!-- Catch-all route pattern: app/pages/[...slug].vue -->
<script setup lang="ts">
const route = useRoute()
const { data: page } = await useAsyncData(
  route.path,
  () => queryCollection('content').path(route.path).first()
)
</script>

<template>
  
  <div v-else>Page not found</div>
</template>
```

## Quality Assurance

- Always verify suggestions against fetched documentation
- If documentation is unclear or unavailable, explicitly state this with appropriate caveats
- When multiple approaches exist, explain trade-offs
- Be aware of build-time vs runtime content access differences
- Ensure proper typing for collection queries and responses
````
</Collapsible>

## Key Design Principles

The agent follows these principles:

1. **Documentation-first**: Always fetch `llms.txt` before answering anything
2. **Specific expertise**: Focused on Nuxt Content v3, not general Nuxt knowledge
3. **Verification**: Cross-reference documentation, don't rely on training data
4. **Practical output**: TypeScript code following project conventions

## How It Works in Practice

When you ask Claude Code something like "How do hooks work in Nuxt Content?", the main agent recognizes this matches the `nuxt-content-specialist` description and delegates to it.

<Figure
  src={agentInAction}
  alt="Claude Code spawning the nuxt-content-specialist agent to research Nuxt Content hooks"
  caption="The agent researches in its own context while your main context stays clean"
  width={800}
/>

The specialist agent then:
1. Fetches `https://content.nuxt.com/llms.txt`
2. Identifies the relevant documentation pages
3. Fetches the actual docs
4. Provides an accurate, up-to-date answer

Your main context stays clean. The research happens in a separate context window.

## Create Your Own

You can apply this pattern to any library or framework:

1. Find if they have `llms.txt` (most modern docs sites do)
2. Create an agent that fetches it first
3. Define the expertise scope in the description
4. Add examples so Claude Code knows when to delegate

This approach gives you 98%+ reduction in token usage compared to loading full MCP tool definitions, while maintaining access to current documentation.

---

--- title: Claude Code Customization Guide (2026): CLAUDE.md vs Skills vs Subagents description: When should you use CLAUDE.md, a slash command, a skill, or a subagent in Claude Code? A decision guide with real examples for each, so you stop guessing which one fits the job. tags: ['claude-code', 'ai', 'tooling', 'typescript'] url: https://alexop.dev/posts/claude-code-customization-guide-claudemd-skills-subagents ---

# Claude Code Customization Guide (2026): CLAUDE.md vs Skills vs Subagents



## Quick Summary

This post covers:

- **CLAUDE.md**: Always-loaded project context and instructions
- **Slash commands**: Prompts you invoke with `/command` in the terminal
- **Subagents**: Specialists with their own context window for delegated tasks
- **Skills**: Rich, auto-discovered capabilities with supporting files (not manually runnable via `/...`)
- Key insight: **subagents keep your main context clean**—in plan mode, Claude Code will typically delegate repo scanning to an `Explore`-style subagent so your main thread doesn’t balloon

## Table of Contents

## Introduction

Claude Code gives you multiple ways to “teach” it project context or automate workflows, but it’s not always obvious when to use which.

I’ll solve the **same problem four different ways** so the trade-offs are concrete. Spoiler: for doc-fetching, **subagents win** because they keep your main context clean.

<Aside type="tip" title="New to Claude Code?">
This post assumes familiarity with Claude Code basics. For a broader overview of all features—including MCP, hooks, and plugins—see my <InternalLink slug="understanding-claude-code-full-stack">comprehensive guide to Claude Code's feature stack</InternalLink>. If you want to automate responses to Claude Code events (like getting <InternalLink slug="claude-code-notification-hooks">desktop notifications when tasks finish</InternalLink>), check out the hooks guide.
</Aside>

---

## The Problem

Claude Code doesn’t have up-to-date training data for every library, so it can’t reliably “remember” what a docs site says today.

**The specific problem**: I’m building a workout tracking app with [Dexie.js](https://dexie.org) (IndexedDB wrapper). Claude keeps suggesting outdated patterns and misses things like `liveQuery()`.

Claude Code itself has a mechanism to fetch its own documentation. We need to do the same for our specialized libraries.

```mermaid
graph LR
    A[User Question] --> B{Claude Code}
    B --> C[Outdated Knowledge]
    B --> D[Fetch Current Docs]
    D --> E[Accurate Answer]
    C --> F[Wrong Patterns]
```

Let’s solve it with all four tools, then compare.

---

## 1. CLAUDE.md: Always-On Project Memory

### What It Is

A markdown file that's **automatically loaded** every time you start Claude Code. Think of it as your project's "memory card."

> **CLAUDE.md**: Persistent project instructions that Claude reads at the start of every conversation.

### Where It Lives

<FileTree
  tree={[
    {
      name: "project-root",
      open: true,
      children: [
        { name: "CLAUDE.md", comment: "// Project-level" },
        {
          name: ".claude",
          children: [
            { name: "CLAUDE.md", comment: "// Alternative location" },
          ],
        },
        {
          name: "tests",
          children: [
            { name: "CLAUDE.md", comment: "// Loaded when reading test files" },
          ],
        },
      ],
    },
  ]}
/>

### Nested CLAUDE.md Files

Claude Code also discovers **nested CLAUDE.md files** in subdirectories. When Claude reads files from a directory containing its own `CLAUDE.md`, that file gets added to the context automatically.

This is useful for directory-specific instructions:

- `tests/CLAUDE.md` — testing conventions, preferred mocking patterns
- `src/db/CLAUDE.md` — database-specific patterns and constraints
- `src/components/CLAUDE.md` — component architecture guidelines

The nested file is only loaded when Claude actually accesses files in that directory, keeping your main context lean until you need that specialized knowledge.

### The Dexie.js Solution

```markdown
# CLAUDE.md

## Database

We use Dexie.js for IndexedDB. Before implementing any database code:

1. Fetch the docs index from https://dexie.org/llms.txt
2. Use `liveQuery()` for reactive data binding
3. Follow the repository pattern in `src/db/`
4. Always handle `ConstraintError` for duplicate keys
```

### What Happens
Every conversation starts with Claude knowing “fetch Dexie docs before writing database code.”

The catch is **context drift**: in long sessions, the model can gradually deprioritize earlier system-level instructions in favor of the most recent conversation history.

### Trade-offs

| ✅ Pros                            | ❌ Cons                                          |
| ---------------------------------- | ------------------------------------------------ |
| Zero effort—always loaded          | **Context Drift**: Claude forgets instructions as sessions get longer |
| Team-shared via git                | No dedicated context window—competes with your conversation |
| Simple to maintain                 | No enforcement—Claude decides whether to follow  |

---

## 2. Slash Commands: Simple Skills You Invoke

### What It Is

A saved prompt you invoke by typing `/command-name`. Like a macro or keyboard shortcut for prompts.

Slash commands can be invoked explicitly (you type `/command`) and can also be auto-invoked by Claude when the command’s `description` matches the task.

Slash commands can also **orchestrate other behavior**: you can spell out in the command itself that it should spin up a subagent (or a specific subagent), call out a particular skill/workflow, and generally “pipeline” the work (e.g., research → codebase scan → write a doc) instead of trying to do everything in one shot.

The main difference vs skills is **packaging + UX**: slash commands are single-file entries with great terminal `/...` discovery/autocomplete; skills are usually directories with supporting files (patterns, templates, scripts).

<Aside type="info" title="Deep dive">
Want a full walkthrough? See my <InternalLink slug="claude-code-slash-commands-guide">slash commands guide</InternalLink>.
</Aside>

### Where It Lives

<FileTree
  tree={[
    {
      name: ".claude",
      open: true,
      children: [
        {
          name: "commands",
          open: true,
          children: [{ name: "dexie-help.md" }],
        },
      ],
    },
  ]}
/>

### The Dexie.js Solution

```markdown
---
description: Get Dexie.js guidance with current documentation
allowed-tools: Read, Grep, Glob, WebFetch
---

First, fetch the documentation index from https://dexie.org/llms.txt

Then, based on the user's question, fetch the relevant documentation pages.

Finally, answer the following question using the current documentation:

$ARGUMENTS
```

### Manual Orchestration Example (Research)

If you want a slash command that **explicitly launches multiple subagents in parallel** and then produces an artifact (like a research note in `docs/research/`), you can encode that directly in the command definition.

<Collapsible title="research.md (custom command)">
````markdown
---
description: Research a problem using web search, documentation, and codebase exploration
allowed-tools: Task, WebSearch, WebFetch, Grep, Glob, Read, Write, Bash
---

# Research: $ARGUMENTS

Research the following problem or question:

> **$ARGUMENTS**

## Instructions

Conduct thorough research like a senior developer. Launch multiple subagents in parallel to gather information from different sources.

### Step 1: Launch Parallel Research Agents

Use the Task tool to spawn these subagents **in parallel** (all in a single message):

1. **Web Documentation Agent** (subagent_type: general-purpose)
  - Search official documentation for the topic
  - Find best practices and recommended patterns
  - Locate relevant GitHub issues or discussions

2. **Stack Overflow Agent** (subagent_type: general-purpose)
  - Search Stack Overflow for similar problems and solutions
  - Find highly-voted and accepted answers
  - Note common pitfalls and gotchas

3. **Codebase Explorer Agent** (subagent_type: Explore)
  - Search the codebase for related patterns
  - Find existing solutions to similar problems
  - Identify relevant files, functions, or components

### Step 2: Create Research Document

After all agents complete, create a markdown file at `docs/research/<topic-slug>.md`.

Generate the filename from the research topic:
- Convert to lowercase
- Replace spaces with hyphens
- Remove special characters
- Add today's date as prefix: `YYYY-MM-DD-<topic-slug>.md`

Example: "Vue 3 Suspense" → `docs/research/2024-12-06-vue-3-suspense.md`

First, create the research folder if it doesn't exist:
```bash
mkdir -p docs/research
```

### Step 3: Write the Research Document

Structure the document with these sections:

```markdown
# Research: <Topic>

**Date:** <YYYY-MM-DD>
**Status:** Complete

## Problem Statement

<Describe the problem and why it matters>

## Key Findings

<Summarize the most relevant solutions and approaches>

## Codebase Patterns

<Document how the current codebase handles similar cases>

## Recommended Approach

<Provide your recommendation based on all research>

## Sources

- [Source Title](URL) - Brief description
- [Source Title](URL) - Brief description
```

### Guidelines

- Prioritize official documentation over blog posts
- Prefer solutions that match existing codebase patterns
- Note version-specific considerations (Vue 3, TypeScript, etc.)
- Flag conflicting information across sources
- Write concise, actionable content
- Use active voice throughout the document

### Step 4: Confirm Completion

After writing the file, output the file path so the user can find it later.
````
</Collapsible>

### How You Use It

```bash
/dexie-help how do I create a compound index?
```

### What Happens

Claude fetches the docs, finds the relevant pages, and answers your question—triggered explicitly.

### Trade-offs

| ✅ Pros                                | ❌ Cons                                       |
| -------------------------------------- | --------------------------------------------- |
| You control exactly when it runs       | Must remember to type `/dexie-help`           |
| Can pass arguments for specific questions | One-shot—doesn't persist knowledge across messages |
| Simple single-file setup               | Auto-triggering depends on `description` match |

---

## 3. Subagents: Specialists with Their Own Context

### What It Is

A specialized AI "persona" with its own context window. Claude **delegates entire tasks** to it and gets results back.

Because fetching the Dexie docs involves reading multiple pages and creates a lot of context noise, keeping this inside a subagent prevents your main chat from hitting context limits.

> **Subagent**: An isolated Claude instance that works on a task independently and returns only the results to your main conversation.

<Alert type="tip" title="Subagents keep your main context clean">
Even when the task is “just exploration,” subagents are a great default because they let Claude do **lots of reading/searching** without dumping everything into your main thread.

This is especially useful in **plan mode**: Claude Code will typically kick off an `Explore`-style subagent to scan the repo and return a distilled map of relevant files/patterns, so your main conversation stays focused and doesn’t blow up.
</Alert>

Claude Code also supports **async agents**: fire one off, let it cook while you keep working, then it comes back with its updates when it’s done. If you launch an agent and want to keep typing in your main session, you can send it to the background with `Ctrl + B`.

<Alert type="info" title="Claude Code does this too">
Claude Code’s own system prompt includes a built-in “documentation lookup” workflow that uses a subagent:

> -> Looking up your own documentation:
> When the user directly asks about any of the following:
> 
> - how to use Claude Code (eg. "can Claude Code do...", "does Claude Code have...")
> - what you're able to do as Claude Code in second person (eg. "are you able...", "can you do...")
> - about how they might do something with Claude Code (eg. "how do I...", "how can I...")
> - how to use a specific Claude Code feature (eg. implement a hook, write a skill, or install an MCP server)
> - how to use the Claude Agent SDK, or asks you to write code that uses the Claude Agent SDK
> 
> Use the Task tool with subagent_type='claude-code-guide' to get accurate information from the official Claude Code and Claude Agent SDK documentation.

Source: https://github.com/marckrenn/cc-mvp-prompts/blob/main/cc-prompt.md
</Alert>

### Where It Lives

<FileTree
  tree={[
    {
      name: ".claude",
      open: true,
      children: [
        {
          name: "agents",
          open: true,
          children: [{ name: "dexie-specialist.md" }],
        },
      ],
    },
  ]}
/>

### The Dexie.js Solution

<Collapsible title="dexie-specialist.md (full definition)">
```markdown
---
name: dexie-db-specialist
description: Use this agent when the task involves Dexie.js or IndexedDB in any way - implementing, modifying, querying, reviewing, or improving database code. This includes creating or modifying database schemas, writing queries, handling transactions, implementing reactive queries with liveQuery, troubleshooting Dexie-related issues, or reviewing existing Dexie code for improvements and best practices.\n\nExamples:\n\n<example>\nContext: User asks about improving their Dexie.js code.\nuser: "What can I improve on this codebase when it comes to Dexie?"\nassistant: "I'll use the dexie-db-specialist agent to review your Dexie.js implementation against current best practices."\n<commentary>\nSince the user is asking about Dexie.js improvements, use the dexie-db-specialist agent to fetch the latest documentation and review the existing code for optimization opportunities, missing features, and best practice violations.\n</commentary>\n</example>\n\n<example>\nContext: User needs to add a new table to the database.\nuser: "I need to add a new 'goals' table to track workout goals"\nassistant: "I'll use the dexie-db-specialist agent to implement this correctly."\n<commentary>\nSince the user needs to modify the Dexie database schema, use the dexie-db-specialist agent to first fetch the latest Dexie.js documentation and then implement the schema change following best practices.\n</commentary>\n</example>\n\n<example>\nContext: User is asking about Dexie query patterns.\nuser: "How do I query exercises by multiple muscle groups in Dexie?"\nassistant: "Let me use the dexie-db-specialist agent to provide an accurate answer based on the current Dexie.js documentation."\n<commentary>\nSince the user is asking about Dexie.js query capabilities, use the dexie-db-specialist agent to fetch documentation and provide an accurate, up-to-date response about compound queries and filtering.\n</commentary>\n</example>\n\n<example>\nContext: User encounters a Dexie-related error.\nuser: "I'm getting 'ConstraintError' when trying to add a workout"\nassistant: "I'll consult the dexie-db-specialist agent to diagnose this database constraint issue."\n<commentary>\nSince this is a Dexie.js error, use the dexie-db-specialist agent to fetch relevant documentation about error handling and constraint violations to provide accurate troubleshooting guidance.\n</commentary>\n</example>\n\n<example>\nContext: User needs to implement a reactive query.\nuser: "The workout list should update automatically when new workouts are added"\nassistant: "I'll use the dexie-db-specialist agent to implement reactive queries with liveQuery."\n<commentary>\nSince reactive data binding with Dexie requires liveQuery, use the dexie-db-specialist agent to fetch the latest documentation on liveQuery and useLiveQuery patterns for Vue integration.\n</commentary>\n</example>
model: opus
color: orange
---

You are an expert Dexie.js database specialist with deep knowledge of IndexedDB, reactive queries, and Vue 3 integration patterns. Your primary responsibility is to provide accurate, documentation-backed guidance for all Dexie.js implementations.

## Critical First Step

**Before answering ANY Dexie.js question or implementing ANY Dexie-related code, you MUST:**

1. Fetch the documentation index from `https://dexie.org/llms.txt` to understand the available documentation structure
2. Based on the task at hand, fetch the relevant documentation pages to ensure your guidance is accurate and up-to-date
3. Only then proceed with implementation or answering questions

This is non-negotiable. Dexie.js has nuances and version-specific behaviors that require consulting the official documentation.

## Your Expertise Covers

- **Schema Design**: Table definitions, indexes (simple, compound, multi-entry), primary keys, version migrations
- **CRUD Operations**: add(), put(), update(), delete(), bulkAdd(), bulkPut()
- **Querying**: where(), filter(), equals(), between(), anyOf(), startsWithIgnoreCase(), compound queries
- **Reactive Queries**: liveQuery() for real-time updates, integration with Vue's reactivity system
- **Transactions**: Transaction scopes, nested transactions, error handling within transactions
- **Relationships**: Foreign keys, table relationships, populating related data
- **Performance**: Indexing strategies, query optimization, bulk operations
- **Error Handling**: Dexie-specific errors (ConstraintError, AbortError, etc.)

## Project Context

You are working within a Vue 3 PWA workout tracker that uses:
- **Dexie.js** with IndexedDB for offline-first data persistence
- **TypeScript** with strict mode
- **Repository pattern** in `src/db/` for database access abstraction
- **Pinia stores** that consume repositories

When implementing, ensure your code:
1. Follows the existing repository pattern in `src/db/`
2. Uses TypeScript interfaces for table schemas
3. Integrates properly with Vue 3 reactivity (useLiveQuery from @vueuse/rxjs or similar)
4. Handles errors gracefully with proper typing

## Documentation Fetching Strategy

When fetching from `https://dexie.org/llms.txt`:
1. Parse the sitemap to identify relevant documentation pages
2. Fetch specific pages based on the task (e.g., for queries, fetch the WhereClause and Collection docs)
3. Cross-reference multiple pages when dealing with complex topics

Common documentation sections to reference:
- `/docs/Table/Table` - Core table operations
- `/docs/WhereClause/WhereClause` - Query building
- `/docs/Collection/Collection` - Result set operations
- `/docs/liveQuery()` - Reactive queries
- `/docs/Dexie/Dexie` - Database instance configuration
- `/docs/Version/Version` - Schema migrations

## Response Format

When providing implementations:
1. **Cite the documentation** you consulted
2. **Explain the approach** before showing code
3. **Provide TypeScript code** that follows project conventions
4. **Include error handling** appropriate to the operation
5. **Note any caveats** or version-specific behaviors

## Quality Assurance

- Always verify your suggestions against the fetched documentation
- If documentation is unclear or unavailable, explicitly state this and provide your best guidance with appropriate caveats
- When multiple approaches exist, explain trade-offs
- Consider IndexedDB limitations (no full-text search, storage limits, etc.)

Remember: Your value is in providing documentation-verified, accurate Dexie.js guidance. Never guess about API specifics—always fetch and verify first.

```
</Collapsible>

### What Happens

When you ask about Dexie, Claude automatically recognizes this as a database task and delegates to the specialist. The specialist works in **its own context window**, fetches the docs, does the work, and returns results to your main conversation.

```mermaid
sequenceDiagram
    participant User
    participant Main as Main Claude
    participant Sub as Dexie Subagent
    participant Web as dexie.org

    User->>Main: How do I add an index?
    Main->>Sub: Delegate database question
    Sub->>Web: Fetch llms.txt
    Web-->>Sub: Documentation index
    Sub->>Web: Fetch relevant pages
    Web-->>Sub: Index documentation
    Sub-->>Main: Distilled answer
    Main-->>User: Here's how to add an index...
```

### Trade-offs

| ✅ Pros                                         | ❌ Cons                                      |
| ----------------------------------------------- | -------------------------------------------- |
| Auto-delegated when task matches                | Heavier—launches a separate agent            |
| **Separate context window**—doesn't clutter main | Results come back as a summary, not live     |
| Can use different model (e.g., opus for complex) | You can't interact with the agent directly   |
| Can restrict tools for security                 | More complex to set up                       |

---

## 4. Skills: Rich Capabilities with Auto-Discovery

### What It Is

A structured capability with optional supporting files that Claude **discovers automatically** and uses within your main conversation.

Unlike simple slash commands, skills can include multiple files: reference documentation, scripts, templates, and utilities.

### Where It Lives

<FileTree
  tree={[
    {
      name: ".claude",
      open: true,
      children: [
        {
          name: "skills",
          open: true,
          children: [
            {
              name: "dexie-expert",
              open: true,
              children: [
                { name: "SKILL.md", comment: "// Main definition" },
                { name: "PATTERNS.md", comment: "// Common patterns" },
                { name: "MIGRATIONS.md", comment: "// Migration guide" },
                {
                  name: "scripts",
                  children: [{ name: "validate-schema.ts" }],
                },
              ],
            },
          ],
        },
      ],
    },
  ]}
/>

### How Claude Sees Skills
Claude decides whether to invoke a skill largely based on its `description`.

You can also ask Claude Code something like:

```markdown
> “tell me me exactly how this looks for you <available_skills> ?”
```

When it answers, you’ll often see structured blocks that look like `<available_skills>` (and typically a separate block for slash commands, e.g. `<available_commands>`).

```xml
<available_skills>
  <skill>
    <name>dexie-expert</name>
    <description>
      Dexie.js database guidance. Use when working with
      IndexedDB, schemas, queries, liveQuery...
    </description>
  </skill>
</available_skills>
```

Here’s an abbreviated example of what the `<available_skills>` section can look like (truncated with `...`):

```xml
<available_skills>
  <skill>
    <name>skill-creator</name>
    <description>
      Guide for creating effective skills. Use when you want to create or update a skill.
      ...
    </description>
    <location>user</location>
  </skill>

  <skill>
    <name>c4-architecture</name>
    <description>
      Generate architecture documentation using C4 model Mermaid diagrams.
      ...
    </description>
    <location>user</location>
  </skill>

  <skill>
    <name>vue-composables</name>
    <description>
      Write high-quality Vue 3 composables following established patterns and best practices.
      ...
    </description>
    <location>managed</location>
  </skill>

  ...
</available_skills>
```

### The Dexie.js Solution

```markdown
---
name: dexie-expert
description: Dexie.js database guidance. Use when working with IndexedDB, schemas, queries, liveQuery, or database migrations.
allowed-tools: Read, Grep, Glob, WebFetch
---

# Dexie.js Expert

When the user needs help with Dexie.js or IndexedDB:

1. Fetch https://dexie.org/llms.txt
2. Fetch only the relevant pages for the task
3. Apply the guidance to this repo’s patterns
```

### A Minimal “Does This Even Work?” Skill

If you just want to verify that **a Skill can spin up subagents to do work** (via the `Task` tool), here’s a deliberately dumb smoke test you can copy/paste.

<Collapsible title="SKILL.md (subagent-smoke-test)">
```markdown
---
name: subagent-smoke-test
description: Smoke test for Claude Code subagents. Use when the user wants to verify that spawning a subagent via the Task tool works in this repo.
---

# Subagent Smoke Test

This skill exists purely to verify that subagents work end-to-end.

## What to do

1. Spin up a subagent using the **Task** tool.
   - Use `subagent_type: general-purpose`.
   - Give it a simple, read-only task:
     - Read `package.json` and summarize the key scripts.
     - Read `astro.config.ts` and summarize major integrations.
     - Use Glob (or equivalent) to list the top-level folders.

2. Wait for the subagent to finish.

3. Return a short report to the user:
   - `Subagent status: success` (or `failed`)
   - A 3–6 bullet summary of what it found
   - If it failed, include the most likely fix (e.g. tool permissions, Task tool disabled).

## Suggested Task prompt

Use something like this as the Task payload:

- “You are a helper subagent. Do a quick, read-only scan of this repo.
  - Read `package.json` and summarize the main scripts.
  - Read `astro.config.ts` and summarize key integrations.
  - Glob the repo root and list the top-level folders.
  Return a concise report.”
```
</Collapsible>

### What Happens
Skills are **auto-discovered** and typically get applied when Claude decides they match the current task. They run **in your main conversation**, so you can iterate live.

If you need a manual, predictable trigger from the terminal, package the workflow as a **slash command** (since `/...` is for commands).

### Trade-offs

| ✅ Pros                                          | ❌ Cons                                        |
| ------------------------------------------------ | ---------------------------------------------- |
| Auto-discovered based on description             | Shares main context window space               |
| Works in main conversation—live interaction      | Claude decides when to trigger (may not fire)  |
| Can include reference files, scripts, templates  | More setup than slash commands                 |
| Deep, reusable workflow packaging                | Not manually invokable via `/...` in the terminal |
| Feels like enhanced Claude, not a separate tool  |                                                |

<Alert type="important" title="Key Insight">
In practice, the difference is mostly **UX + packaging**:

- **Slash commands** are what you can run manually from the terminal via `/command`.
- **Skills** are structured, auto-discovered capabilities (often a directory of supporting files) that Claude may apply when relevant.
</Alert>

---

### When to use what

| Pick this | When | Why |
|---|---|---|
| **CLAUDE.md** | You want Claude to *always* start with project rules/context | Auto-loaded on startup; shared via git |
| **Slash command** | You want an explicit one-shot workflow you run on demand | Discoverable via `/...`, can take arguments |
| **Subagent** | The task is research-heavy (lots of reading/searching/synthesis) | Uses a separate context window; returns a distilled result |
| **Skill** | You want a rich workflow that Claude can auto-apply when it recognizes the task | Packaged capability (often with supporting files) |

### How they relate

| Mechanism | Runs in main conversation | Separate context window | Can spawn subagents | Can use skills | Manually runnable via `/...` |
|---|---:|---:|---:|---:|---:|
| **CLAUDE.md** | ✅ | ❌ | ❌ | ❌ | ❌ |
| **Slash command** | ✅ | ❌ | ✅ (by instructing `Task`) | ✅ (indirectly; Claude may apply skills) | ✅ |
| **Skill** | ✅ | ❌ | ✅ (if `Task` is allowed) | ✅ (Claude may apply multiple skills) | ❌ |
| **Subagent** | ❌ | ✅ | ⚠️ Possible (depends on allowed tools, e.g. `Bash(claude:*)`) | ✅ (if configured via `skills:`) | ⚠️ Usually delegated |

## Conclusion

- Use **subagents** (especially `Explore` in plan mode) to keep your main context small and focused.
- Use **slash commands** when you want an explicit, repeatable terminal entry point.
- Use **skills** when you want Claude to auto-apply a richer workflow (often with supporting files).
- Use **CLAUDE.md** for short, always-true project conventions and standards.

---

--- title: How to Customize Your Claude Code Status Line description: Learn how to display model name, context usage, and cost directly in your terminal while using Claude Code. A step-by-step guide to creating custom status line scripts. tags: ['claude-code', 'ai', 'tooling'] url: https://alexop.dev/posts/customize_claude_code_status_line ---

# How to Customize Your Claude Code Status Line



Ever glanced at Claude Code and wondered which model you're actually using? Or how much of the context window you've burned through? By default, this information is hidden away—but you can surface it right in your terminal.

A custom status line shows you what matters at a glance:

```
[Opus] Context: 12%
```

This tells you the active model and context usage without interrupting your flow. Let me show you how to set it up.

## How the status line works

Claude Code pipes JSON data to your status line script via stdin. Your script processes that data and outputs whatever text you want displayed.

```mermaid
flowchart LR
    A[Claude Code] -->|JSON via stdin| B[Your Script]
    B -->|Formatted text| C[Terminal Status Line]
```

The JSON contains everything you'd want to know: model info, token counts, costs, and workspace details.

## Step 1: Create the status line script

Create a new file at `~/.claude/statusline.sh`:

```bash
#!/bin/bash
input=$(cat)

MODEL=$(echo "$input" | jq -r '.model.display_name')
INPUT_TOKENS=$(echo "$input" | jq -r '.context_window.total_input_tokens')
OUTPUT_TOKENS=$(echo "$input" | jq -r '.context_window.total_output_tokens')
CONTEXT_SIZE=$(echo "$input" | jq -r '.context_window.context_window_size')

TOTAL_TOKENS=$((INPUT_TOKENS + OUTPUT_TOKENS))
PERCENT_USED=$((TOTAL_TOKENS * 100 / CONTEXT_SIZE))

echo "[$MODEL] Context: ${PERCENT_USED}%"
```

The script reads JSON from stdin, extracts the fields we care about using `jq`, calculates the percentage, and outputs the formatted string.

## Step 2: Make it executable

```bash
chmod +x ~/.claude/statusline.sh
```

## Step 3: Configure Claude Code

Add the status line configuration to `~/.claude/settings.json`:

```json
{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  }
}
```

If you already have settings in this file, add the `statusLine` block alongside your existing configuration.

<FileTree tree={[
  {
    name: ".claude",
    open: true,
    children: [
      { name: "statusline.sh", comment: "Your custom script" },
      { name: "settings.json", comment: "Configuration file" }
    ]
  }
]} />

## Step 4: Restart Claude Code

Close and reopen Claude Code. Your new status line should appear.

## Available variables

The script receives JSON with these fields:

| Variable | Description |
|----------|-------------|
| `model.id` | Full model ID (e.g., `claude-opus-4-5-20251101`) |
| `model.display_name` | Short name (e.g., `Opus`) |
| `context_window.total_input_tokens` | Input tokens used |
| `context_window.total_output_tokens` | Output tokens used |
| `context_window.context_window_size` | Max context size |
| `cost.total_cost_usd` | Session cost in USD |
| `cost.total_duration_ms` | Total duration |
| `workspace.current_dir` | Current directory |

## Adding cost tracking

Want to see how much your session is costing? Extend the script:

```bash
#!/bin/bash
input=$(cat)

MODEL=$(echo "$input" | jq -r '.model.display_name')
INPUT_TOKENS=$(echo "$input" | jq -r '.context_window.total_input_tokens')
OUTPUT_TOKENS=$(echo "$input" | jq -r '.context_window.total_output_tokens')
CONTEXT_SIZE=$(echo "$input" | jq -r '.context_window.context_window_size')
COST=$(echo "$input" | jq -r '.cost.total_cost_usd')

TOTAL_TOKENS=$((INPUT_TOKENS + OUTPUT_TOKENS))
PERCENT_USED=$((TOTAL_TOKENS * 100 / CONTEXT_SIZE))

printf "[%s] Context: %d%% | $%.2f" "$MODEL" "$PERCENT_USED" "$COST"
```

Now you'll see something like: `[Opus] Context: 12% | $0.45`

<Aside type="tip" title="Quick Alternative">
  Use the `/statusline` slash command for a guided setup. Just type `/statusline show the model name and context usage percentage` and Claude Code creates the configuration automatically.
</Aside>

## Troubleshooting

**Status line not showing?**

1. Check that `jq` is installed: `brew install jq` (macOS) or `apt install jq` (Linux)
2. Verify the script is executable: `ls -la ~/.claude/statusline.sh`
3. Restart Claude Code after making changes

**Test your script manually:**

```bash
echo '{"model":{"display_name":"Opus"},"context_window":{"total_input_tokens":1000,"total_output_tokens":500,"context_window_size":200000}}' | ~/.claude/statusline.sh
```

Should output: `[Opus] Context: 0%`

<Alert type="note" title="Dependencies">
  The status line script requires `jq` for JSON parsing. If you don't have it installed, the script will fail silently.
</Alert>

## Taking it further

The status line is one piece of the Claude Code customization puzzle. Once you're comfortable with scripts like this, explore:

- <InternalLink slug="claude-code-notification-hooks">Notification hooks</InternalLink> to get desktop alerts when Claude needs input
- <InternalLink slug="claude-code-slash-commands-guide">Slash commands</InternalLink> to automate repetitive tasks
- <InternalLink slug="understanding-claude-code-full-stack">The full Claude Code feature stack</InternalLink> for MCP, skills, and subagents

The status line script pattern—reading JSON from stdin and outputting formatted text—is the same foundation that powers many of Claude Code's extensibility features.

---

--- title: Vue 3 Testing Pyramid: A Practical Guide with Vitest Browser Mode description: Learn a practical testing strategy for Vue 3 applications using composable unit tests, Vitest browser mode integration tests, and visual regression testing. tags: ['vue', 'testing', 'vitest', 'typescript', 'accessibility'] url: https://alexop.dev/posts/vue3_testing_pyramid_vitest_browser_mode ---

# Vue 3 Testing Pyramid: A Practical Guide with Vitest Browser Mode



## Quick Summary

This post covers a practical testing approach for Vue 3 applications:

- Composable unit tests for fast logic verification
- Integration tests with Vitest browser mode for realistic user flows
- Accessibility and visual tests for critical screen checks
- Simplified data factories to manage test data easily

## Table of Contents

## Introduction

I'm building a workout tracking PWA with Vue 3, and I needed confidence that my changes work. Not the "I clicked around and it seems fine" kind of confidence, but the "I can refactor this and know immediately if I broke something" kind.

Here's the thing: I don't write much code myself anymore. AI tools handle most of the implementation. I describe what I want, review the changes, and guide the direction—but the actual keystrokes? That's the AI. This workflow is incredibly productive, but it comes with a catch: I need a robust safety net.

When an AI writes code, tests become even more critical. They serve three purposes:

1. **Catch bugs** before users do
2. **Enable refactoring** — change code freely knowing tests will catch regressions
3. **Document behavior** — tests act as a "user manual" for your code

<Alert type="tip" title="Don't Forget the Basics">
  Tests are just one part of your safety net. **Linting** (ESLint) catches code style issues and potential bugs statically. **Type checking** (TypeScript) catches type errors at compile time. Run all three—lint, type check, and tests—before every commit.
</Alert>

## Before We Start: A Mini Glossary

Testing has a lot of jargon. Here's a cheat sheet to keep handy as you read:

| Term | Meaning |
|------|---------|
| **Unit Test** | Testing a tiny, isolated piece of code (like a single function) to ensure it returns the right value |
| **Integration Test** | Testing how multiple pieces work together (e.g., clicking a button and seeing a database update) |
| **Regression** | A bug where a feature that used to work stops working after you change something else |
| **Mock** | A fake version of a complex tool (like faking an API call) so you can test without relying on the internet |
| **Assertion** | A line of code that checks if a result matches your expectation (e.g., `expect(2 + 2).toBe(4)`) |
| **A11y** | Short for "Accessibility" (there are 11 letters between A and y) |

---

## Your Architecture Shapes Your Testing Strategy

Your testing strategy reflects your frontend architecture. They're not independent choices.

If you write **monolithic components** (huge files with logic and UI mixed), testing is a nightmare. If you use **composables** (extracting logic into separate files), testing becomes straightforward.

### Bad vs. Good Architecture

#### The Monolith (Hard to Test)

To test the timer logic here, you have to mount the whole component, find the button, click it, and wait for the UI to update. It's slow and fragile.

```vue
<script setup>
// Logic is trapped inside the component!
const time = ref(0)
const start = () => setInterval(() => time.value++, 1000)
</script>

<template>
  <button @click="start">{{ time }}</button>
</template>
```

#### The Composable (Easy to Test)

Here, the logic lives in a plain TypeScript file. We can test `useTimer` without ever looking at a Vue component or HTML.

```typescript
// useTimer.ts
export function useTimer() {
  const time = ref(0)
  const start = () => setInterval(() => time.value++, 1000)
  return { time, start }
}
```

My strategy relies on this "composable-first" approach. However, for the UI itself, we use integration tests. These tests don't care about your code structure; they test behavior through the UI, just like a user would.

<Aside type="tip" title="Learn More About Composable Testing">
  For a deep dive into testing composables specifically, check out <InternalLink slug="how-to-test-vue-composables">How to Test Vue Composables</InternalLink>.
</Aside>

---

## The Testing Pyramid

My approach inverts the traditional pyramid. **Integration tests make up ~70%** of my test suite because Vitest browser mode makes them fast and reliable. Composable unit tests cover ~20% for pure logic, and the remaining ~10% goes to accessibility and visual regression tests.

{/* TODO: Regenerate testingPyramid.png to show inverted distribution: Integration (70%), Unit (20%), A11y/Visual (10%) */}

---

## The Environment: Browser Mode vs JSDOM

In the past, most Vue tests ran in JSDOM. Now, I recommend **Vitest Browser Mode** with `vitest-browser-vue`. Here's why:

| Feature | JSDOM (Old Standard) | Vitest Browser Mode (New Standard) |
|---------|---------------------|-----------------------------------|
| **What is it?** | A simulation of a browser running in Node.js (Fake) | A real instance of Chrome/Firefox running your tests (Real) |
| **Accuracy** | Good for logic, bad for layout/CSS | 100% accurate — it's a real browser |
| **Debugging** | Hard. You stare at console logs | Easy. You can watch the test click buttons on your screen |
| **Speed** | Surprisingly slow (see benchmarks below) | Often faster due to native browser APIs |
| **API** | Requires Testing Library for DOM queries | Built-in `page` object with Playwright-like locators |

### Real-World Performance Comparison

A common misconception is that browser mode is slower. In my testing with the same test suite, **browser mode was actually 4x faster**:

| Metric | Vitest Browser Mode (Chromium) | Vitest Unit Mode (JSDOM) |
|--------|-------------------------------|--------------------------|
| **Total Duration** | 13.59s 🚀 | 53.72s |
| **Test Files** | 15 | 15 |
| **Total Tests** | 82 (78 passed) | 82 (78 passed) |
| **Setup Time** | 4.48s | 53ms |
| **Import Time** | 19.84s | 7.98s |
| **Test Execution Time** | 29.48s | 40.53s |

While browser mode has higher setup time (launching Chromium), the actual test execution is faster because it uses native browser APIs instead of JSDOM's JavaScript reimplementation. The total duration speaks for itself.

<Aside type="tip" title="Why Vitest Browser Mode for AI Workflows?">
  Vitest browser mode handles everything in one command. The browser launches, components render, and tests run. It's much simpler for AI assistants (and humans) to manage than setting up complex End-to-End servers.
</Aside>

### Setting Up Vitest Browser Mode

Vitest 4.0+ requires a browser provider package. Install the dependencies:

```bash
npm install -D vitest @vitest/browser-playwright vitest-browser-vue playwright
```

<Alert type="note" title="Provider Options">
  You can use `@vitest/browser-playwright` (recommended) or `@vitest/browser-webdriverio`. Playwright offers the best developer experience with automatic browser downloads.
</Alert>

### No More Testing Library

With Vitest browser mode, you don't need `@testing-library/vue` anymore. The `page` object from `vitest/browser` provides Playwright-like locators that are more powerful and consistent:

```typescript
// Instead of screen.getByRole(), use page.getByRole()
const button = page.getByRole('button', { name: /submit/i })
await userEvent.click(button)
```

---

## Layer 1: Composable Unit Tests

Composables are just functions. You test them by calling them and checking the result.

### A Simple Composable Test

```typescript
describe('useDialogState', () => {
  it('starts closed', () => {
    // 1. Run the code
    const { isOpen } = useDialogState()
    // 2. Assert the result
    expect(isOpen.value).toBe(false)
  })

  it('opens when requested', () => {
    const { isOpen, open } = useDialogState()
    open()
    expect(isOpen.value).toBe(true)
  })
})
```

No HTML, no mounting, no complexity. Just functions and values.

<Aside type="tip" title="Deep Dive: Composable Testing">
  For comprehensive patterns including async composables, lifecycle hooks, and dependency injection, see <InternalLink slug="how-to-test-vue-composables">How to Test Vue Composables</InternalLink>.
</Aside>

---

## Managing Test Data with Factories

When writing tests, you constantly need data. For example, to test a "Profile Page," you need a "User."

Beginners often copy-paste the same big object into every single test file. This is messy and hard to maintain. If you add a new required field (like `phoneNumber`) to your User, you have to go back and fix every single test.

The solution is the **Factory Pattern**. Think of it like ordering a pizza: there's a "standard" pizza (Cheese & Tomato), and you only specify the changes you want ("...but add pepperoni").

### The Problem: Hard-coded Data

Without factories, your tests look like this. Notice how much noise there is just to test one specific thing:

```typescript
// ❌ BAD: Repeating data everywhere
it('shows admin badge', () => {
  const user = {
    id: '1',
    name: 'John Doe',
    email: 'john@example.com',
    role: 'admin', // This is the only line we actually care about!
    isActive: true,
    createdAt: '2023-01-01'
  }

  // ... test logic ...
})
```

### The Solution: A Simple Factory Function

A factory is just a plain TypeScript function. It holds the "Standard Pizza" defaults and lets you overwrite specific slices using the spread operator (`...`).

```typescript
// factories/userFactory.ts

// 1. Define the shape of your data
interface User {
  id: string;
  name: string;
  role: 'user' | 'admin';
  isActive: boolean;
}

// 2. Define your "Standard Pizza" (Sensible Defaults)
const defaultUser: User = {
  id: '123',
  name: 'Test User',
  role: 'user',
  isActive: true
}

// 3. The Factory Function
// It takes "overrides" (partial data) and merges them on top of the defaults
export function createUser(overrides: Partial<User> = {}): User {
  return {
    ...defaultUser, // Start with defaults
    ...overrides    // Apply your specific changes
  };
}
```

### Using It in Tests

Now your tests focus purely on what matters for that specific scenario:

```typescript
// ✅ GOOD: Clean and focused

// Scenario 1: I just need ANY user, I don't care about details
const basicUser = createUser();
// Result: { id: '123', name: 'Test User', role: 'user', ... }

// Scenario 2: I specifically need an ADMIN
const admin = createUser({ role: 'admin' });
// Result: { id: '123', name: 'Test User', role: 'admin', ... }

// Scenario 3: I need an INACTIVE user
const bannedUser = createUser({ isActive: false });
// Result: { id: '123', name: 'Test User', isActive: false, ... }
```

This pattern keeps your tests readable and makes refactoring easy. If you add a new field to `User` later, you only update the `defaultUser` object in one place.

### Factories Work at Every Layer

The beauty of factories is that they work for **both** unit tests and integration tests:

```typescript
// ✅ Unit Test: Testing a composable
it('formats user display name', () => {
  const user = createUser({ name: 'Jane Doe', role: 'admin' })
  const { displayName } = useUserProfile(user)
  expect(displayName.value).toBe('Jane Doe (Admin)')
})

// ✅ Integration Test: Testing a rendered component
it('shows admin badge in profile', async () => {
  const admin = createUser({ role: 'admin' })
  await renderProfilePage({ user: admin })
  await expect.element(page.getByText('Admin')).toBeVisible()
})
```

> **Key Insight:** Factories handle **data**. They don't care whether you're testing a function or a full page—they just give you clean, predictable objects.

<Aside type="note" title="In My Workout Tracker">
  For my workout tracking PWA, I use factories like `createWorkout()`, `createExercise()`, and `createSet()`. The pattern scales nicely—start simple and add complexity only when your data relationships demand it.
</Aside>

---

## Layer 2: Integration Tests

Integration tests verify complete user flows. They render the app, click buttons, and check if the right things appear on screen.

<Alert type="note" title="Integration Test vs E2E Test: What's the Difference?">
  In this post, **integration test** means:
  - Real browser (Vitest browser mode)
  - Real Vue components, router, Pinia, and user interactions
  - **Mocked**: external APIs (via [MSW](https://mswjs.io/)), browser storage (IndexedDB), third-party services

  **E2E test** means:
  - Real browser
  - **Zero mocking**—full stack (frontend + backend + database)
  - Tests exactly how a user interacts with the production system

  **Examples**: In my workout tracker, I mock IndexedDB but test real Vue components and user flows—that's an integration test. For an e-commerce site, you'd mock the product API and payment gateway via MSW, but test the real checkout flow. If you spin up your actual backend and database, that's E2E.
</Alert>

### Component Tests vs. Integration Tests

Vitest browser mode supports two approaches:

| Approach | What you render | Use case |
|----------|-----------------|----------|
| **Component test** | Single component (`render(MyButton)`) | Testing component behavior in isolation |
| **Integration test** | Full app (`render(App)` with router, store) | Testing complete user flows across multiple components |

**Component tests** are faster and more focused—great for testing a single component's props, events, and states.

**Integration tests** render your entire `App.vue` with router and Pinia. The user can navigate between pages, fill forms, and see how components work together. This is where you catch bugs that only appear when components interact.

For most Vue apps, I recommend focusing on **integration tests**. They give you more confidence because they test what users actually experience.

### The "Test App" Helper

To make testing easier, I use a helper function called `createTestApp`. It sets up your Router, Pinia (state), and renders your app using `vitest-browser-vue` so you don't have to repeat it in every file.

```typescript
// helpers/createTestApp.ts
export async function createTestApp() {
  // ... setup router, pinia, render app ...

  return {
    router,       // The navigation system
    cleanup       // A function to tidy up after the test
  }
}
```

<Collapsible title="Full implementation example">
```typescript
// helpers/createTestApp.ts
import {
  CommonPO,
  BuilderPO,
  ActiveWorkoutPO,
  QueuePO,
  BenchmarksPO,
  BenchmarkFormPO,
  BenchmarkDetailPO,
} from './pages'

type CreateTestAppOptions = {
  initialRoute?: string
}

type TestApp = {
  router: Router
  container: Element
  // Page Objects
  common: CommonPO
  builder: BuilderPO
  workout: ActiveWorkoutPO
  queue: QueuePO
  benchmarks: BenchmarksPO
  benchmarkForm: BenchmarkFormPO
  benchmarkDetail: BenchmarkDetailPO
  // Raw query methods (use page.getBy* for new code)
  getByRole: typeof page.getByRole
  getByText: typeof page.getByText
  getByTestId: typeof page.getByTestId
  queryByRole: typeof page.getByRole
  queryByText: typeof page.getByText
  findByRole: typeof page.getByRole
  findByText: typeof page.getByText
  // Helpers
  navigateTo: (to: RouteLocationRaw) => Promise<void>
  cleanup: () => void
}

export async function createTestApp(options: CreateTestAppOptions = {}): Promise<TestApp> {
  const { initialRoute = '/' } = options

  const pinia = createPinia()
  const router = createRouter({
    history: createMemoryHistory(),
    routes,
  })

  if (initialRoute !== '/') {
    router.push(initialRoute)
  }

  // Preload English messages for tests
  i18n.global.setLocaleMessage('en', en)
  i18n.global.locale.value = 'en'

  const screen = render(App, {
    global: {
      plugins: [router, pinia, i18n],
    },
  })

  await router.isReady()

  // Flush Vue's async operations to ensure onMounted fires
  await flushPromises()

  // Wait for app initialization to complete (exercises seeding and loading)
  const exercisesStore = useExercisesStore(pinia)
  await expect
    .poll(() => exercisesStore.customExercises.length, { timeout: 5000 })
    .toBeGreaterThan(0)

  // Create context for page objects
  const context = { router }

  // Instantiate page objects
  const common = new CommonPO(context)
  const builder = new BuilderPO(context, common)
  const workout = new ActiveWorkoutPO(context, common)
  const queue = new QueuePO(context, common)
  const benchmarks = new BenchmarksPO(context, common)
  const benchmarkForm = new BenchmarkFormPO(context, common)
  const benchmarkDetail = new BenchmarkDetailPO(context, common)

  // Simple navigation helper
  async function navigateTo(to: RouteLocationRaw) {
    await router.push(to)
  }

  // vitest-browser-vue cleans up before tests automatically
  // This is kept for backward compatibility with test structure
  function cleanup() {
    screen.unmount()
  }

  return {
    router,
    container: screen.container,
    // Page Objects
    common,
    builder,
    workout,
    queue,
    benchmarks,
    benchmarkForm,
    benchmarkDetail,
    // Raw query methods - use page locators (return Locators, not HTMLElements)
    getByRole: page.getByRole.bind(page),
    getByText: page.getByText.bind(page),
    getByTestId: page.getByTestId.bind(page),
    queryByRole: page.getByRole.bind(page),
    queryByText: page.getByText.bind(page),
    findByRole: page.getByRole.bind(page),
    findByText: page.getByText.bind(page),
    // Helpers
    navigateTo,
    cleanup,
  }
}
```
</Collapsible>

<Alert type="note" title="Note">
  This isn't a library you download. It's a helper file you write once for your project to handle the setup boilerplate.
</Alert>

### A Real Integration Test

Notice how we use `getByRole` to find elements—this ensures our app is accessible:

```typescript
it('completes a set', async () => {
  await createTestApp()

  // 1. Find the "Start" button and click it
  await userEvent.click(page.getByRole('button', { name: /start/i }))

  // 2. Type "100" into the weight input
  const weightInput = page.getByRole('spinbutton', { name: /weight/i })
  await userEvent.type(weightInput, '100')

  // 3. Click "Complete"
  await userEvent.click(page.getByRole('button', { name: /complete/i }))

  // 4. Wait for the success message
  await expect.element(page.getByText('Set Completed')).toBeVisible()
})
```

<Alert type="tip" title="getByRole = Built-in Accessibility Testing">
  Always prefer `getByRole()` over `getByTestId()` or CSS selectors. When you use `getByRole('button', { name: /submit/i })`, you're asserting that:

  1. The element has the correct ARIA role (it's actually a button)
  2. The element has an accessible name (screen readers can announce it)
  3. The element is visible and interactive

  If your test can't find an element by role, that's a signal your UI has an accessibility problem—fix the component, not the test. Reserve `getByTestId` only for elements that truly have no semantic meaning.
</Alert>

### Page Objects: Handling DOM Interaction

As your test suite grows, you'll notice repetitive DOM queries everywhere. **Page Objects** solve this by encapsulating all DOM interactions for a specific page or component.

> **Key Difference:** Factories handle **data** (creating test objects). Page Objects handle **DOM interaction** (clicking, typing, querying elements). They complement each other.

```typescript
// pages/WorkoutPage.ts
export class WorkoutPage {
  // Queries - finding elements
  get startButton() {
    return page.getByRole('button', { name: /start/i })
  }

  get weightInput() {
    return page.getByRole('spinbutton', { name: /weight/i })
  }

  // Actions - user interactions
  async start() {
    await userEvent.click(this.startButton)
  }

  async setWeight(value: number) {
    await userEvent.clear(this.weightInput)
    await userEvent.type(this.weightInput, String(value))
  }

  async completeSet() {
    await userEvent.click(page.getByRole('button', { name: /complete/i }))
  }
}
```

Now your tests read like plain English:

```typescript
it('completes a set with weight', async () => {
  const workoutPage = new WorkoutPage()

  await workoutPage.start()
  await workoutPage.setWeight(100)
  await workoutPage.completeSet()

  await expect.element(page.getByText('Set Completed')).toBeVisible()
})
```

| Helper | Handles | Used In |
|--------|---------|---------|
| **Factories** | Test data (objects, entities) | Unit tests, Integration tests |
| **Page Objects** | DOM interaction (clicks, queries) | Integration tests only |

<Aside type="tip" title="When to Use Page Objects">
  Don't create Page Objects upfront. Write your first few tests with inline queries. When you notice the same `getByRole` patterns repeating across 3+ tests, extract them into a Page Object.
</Aside>

<Aside type="note" title="Automate the Refactoring">
  I use a [Claude Code command to refactor tests into Page Objects](/prompts/claude/claude-refactor-page-object-command) automatically. Point it at a test file and it extracts repeated queries into a clean page object factory.
</Aside>

This approach aligns with black box testing principles—testing behavior rather than implementation details.

<InternalLink slug="stop-white-box-testing-vue">Stop White Box Testing Vue Components</InternalLink>

---

## Layer 3: Accessibility and Visual Tests

These are the "cherries on top" of your pyramid.

### Accessibility (A11y)

We use a tool called **axe-core**. It scans your rendered HTML for common violations (like low contrast text or missing labels).

```typescript
it('has no accessibility violations', async () => {
  const { container } = await createTestApp()

  // This one line checks for dozens of common a11y bugs!
  await assertNoViolations(container)
})
```

<Aside type="tip" title="Learn More About Accessibility Testing">
  For a complete setup guide with jest-axe, see <InternalLink slug="how-to-improve-accessibility-with-testing-library-and-jest-axe-for-your-vue-application">How to Improve Accessibility with Testing Library and jest-axe</InternalLink>. For general Vue accessibility best practices, check out <InternalLink slug="vue-accessibility-blueprint-8-steps">Vue Accessibility Blueprint: 8 Steps</InternalLink>.
</Aside>

### Visual Regression

This takes a screenshot of your component and compares it to a "golden" version saved on your computer. If a pixel changes, the test fails.

```typescript
it('matches the design', async () => {
  await expect(page.getByTestId('app')).toMatchScreenshot('settings-page.png')
})
```

Use this sparingly. Visual tests are brittle (even a font rendering update can break them), so only use them for critical screens.

<Aside type="info" title="Deep Dive into Visual Testing">
  For a complete setup guide on visual regression testing with Vitest browser mode, see <InternalLink slug="visual-regression-testing-with-vue-and-vitest-browser">How to Do Visual Regression Testing in Vue with Vitest</InternalLink>.
</Aside>

### Testing Your Core UI Library

There's one place where visual regression and accessibility tests shine: **your base component library**.

If you're building your own UI components (BaseButton, DatePicker, Modal, Input), these components should be:

- **Dumb** — no business logic, just presentation
- **Reusable** — used across your entire app
- **Stable** — rarely change once built

This makes them perfect candidates for visual and accessibility testing:

```typescript
// BaseButton.visual.spec.ts
describe('BaseButton', () => {
  it('renders all variants correctly', async () => {
    render(ButtonStory) // A component showing all button states
    await expect(page).toMatchScreenshot('button-variants.png')
  })

  it('has no accessibility violations', async () => {
    const { container } = render(BaseButton, {
      props: { label: 'Click me' }
    })
    await assertNoViolations(container)
  })
})
```

For each base component, test:

| Test Type | What to Check |
|-----------|---------------|
| **Visual** | All variants (primary, secondary, disabled, loading) |
| **A11y** | Focus states, ARIA attributes, color contrast |
| **Keyboard** | Tab navigation, Enter/Space activation |

<Aside type="note" title="Using a Component Library?">
  If you use a pre-built library like **shadcn/ui**, **Vuetify**, or **PrimeVue**, skip this. Those libraries already handle visual consistency and accessibility. Focus your testing efforts on your business logic and user flows instead.
</Aside>

---

## Why Not End-to-End (E2E) Tests?

You might hear people say, "Just use Cypress or Playwright for everything!"

E2E tests mean **zero mocking**—you run your real backend and database. They test your entire stack: Frontend + Backend + Database.

For a new developer or a solo project, this is painful because:

- It's slow
- It breaks easily (if the backend API is down, your frontend tests fail)

### The Alternative: Mocking

Instead, we use **MSW (Mock Service Worker)**. It intercepts network requests and returns fake data immediately. This makes your integration tests fast and stable. You don't need a running backend to test your frontend.

<Alert type="tip" title="The Golden Rule of Mocking">
  **The less you mock, the better your tests.** Every mock is a lie you're telling your test suite. Mock only what you can't control:

  - **External APIs** (network calls to third-party services)
  - **System boundaries** (time, random numbers, file system)
  - **Paid services** (payment gateways, SMS providers)

  Never mock your own code just to make tests easier. If a component is hard to test without mocking internal modules, that's a sign your architecture needs refactoring—not more mocks.
</Alert>

<Alert type="note" title="What about Contract Testing?">
  In large corporate teams, you might use "Contract Testing" to ensure your mocks match the real API. For now, don't worry about it. Focus on getting your integration and unit tests running smoothly.
</Alert>

---

## Comparison: Testing Approaches

| Layer | Speed | Confidence | Flakiness | Distribution | When to Use |
|-------|-------|------------|-----------|--------------|-------------|
| **Unit Tests (Composables)** | ⚡ Very fast | Medium | None | ~20% | Logic validation, utility functions |
| **Integration Tests (Browser)** | 🚀 Fast | High | Low | **~70%** | User flows, component interaction |
| **A11y Tests** | 🚀 Fast | High | Medium | ~5% | Critical screens, forms |
| **Visual Regression** | 🐢 Slow | Medium | High | ~5% | Design system components |

---

## Summary: Your Next Steps

Don't try to implement the whole pyramid today. Start with what matters most.

### Step 1: Identify What Can Never Fail

Ask yourself: *"What flows in my app would be catastrophic if they broke?"* For an e-commerce site, that's checkout. For a banking app, that's transfers. For my workout tracker, it's completing a set.

Write integration tests for these critical paths first using Vitest browser mode. Even 3-5 tests covering your core flows provide massive confidence.

### Step 2: Set Up the Infrastructure

Get Vitest browser mode running with a simple `createTestApp` helper. Once you can render your app and click a button in a test, you have the foundation for everything else.

### Step 3: Write Tickets with Testable Acceptance Criteria

Good tickets have Gherkin-style acceptance criteria that read like tests:

```gherkin
Given I am on the workout page
When I tap "Complete Set"
Then I should see "Set Completed" confirmation
And the set should be saved to history
```

These ACs translate directly into integration tests. Now you can practice TDD: write the test from the AC first, watch it fail, then implement the feature.

### Step 4: Extract Patterns as You Go

Don't create factories or page objects upfront. Write a few tests with inline data and queries. When you notice repetition, extract it. This way, your abstractions solve real problems instead of imagined ones.

For guidance on writing clear, maintainable test names, check out <InternalLink slug="frontend-testing-guide-10-essential-rules">Frontend Testing Guide: 10 Essential Rules for Naming Tests</InternalLink>.

<Aside type="note" title="See It in Action">
  Want to see this testing setup in a real project? Check out my [Workout Tracker PWA on GitHub](https://github.com/alexanderop/workoutTracker). It includes the `createTestApp` helper, page objects, factories, and integration tests using Vitest browser mode.
</Aside>

---

## Bonus: Performance Testing in CI

While not part of the traditional testing pyramid, **performance budgets** catch regressions before they reach production. I run Lighthouse CI on every build to enforce thresholds for performance, accessibility, and best practices.

```yaml
# .github/workflows/ci.yml
performance-budget:
  needs: build
  runs-on: ubuntu-latest
  timeout-minutes: 10
  steps:
    - name: Checkout code
      uses: actions/checkout@v4.2.2

    - name: Setup pnpm
      uses: pnpm/action-setup@v4.1.0

    - name: Setup Node.js
      uses: actions/setup-node@v4.4.0
      with:
        node-version: ${{ env.NODE_VERSION }}

    - name: Restore node_modules
      uses: actions/cache/restore@v4.2.3
      with:
        path: node_modules
        key: node-modules-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}

    - name: Download build artifacts
      uses: actions/download-artifact@v6.0.0
      with:
        name: dist
        path: dist

    - name: Run Lighthouse CI
      run: pnpm lhci autorun
```

<Aside type="tip" title="What Lighthouse CI Catches">
  - Performance regressions (bundle size bloat, slow renders)
  - Accessibility violations (missing labels, low contrast)
  - SEO issues (missing meta tags, non-crawlable links)
  - Best practice violations (HTTP/2, image optimization)

  Configure thresholds in `lighthouserc.js` to fail the build when scores drop below acceptable levels.
</Aside>

---

## Beyond the Pyramid: AI-Powered QA

There's a new layer emerging that doesn't fit neatly into the traditional pyramid: **AI-driven testing**.

What if you could have an AI test your app the way a real QA engineer would? Not following scripts, but actually exploring your UI, trying edge cases, and writing bug reports?

I've been experimenting with exactly this approach. Using Claude Code combined with Playwright's browser automation, I built an AI QA engineer that:

- Tests my app through the browser like a real user
- Tries unexpected inputs and edge cases automatically
- Runs on every pull request via GitHub Actions
- Posts detailed bug reports with screenshots directly to my PRs

```mermaid
graph LR
    PR[Open PR] --> GH[GitHub Actions]
    GH --> AI[Claude Code + Playwright]
    AI --> Test[Browser Testing]
    Test --> Report[QA Report on PR]
```

This isn't a replacement for the testing pyramid—it's a complement. Your unit and integration tests catch regressions deterministically. AI QA excels at exploratory testing and finding bugs that scripted tests would never think to check.

<Aside type="tip" title="Want to Build Your Own AI QA Engineer?">
  I wrote a complete guide on setting this up: <InternalLink slug="building_ai_qa_engineer_claude_code_playwright">Building an AI QA Engineer with Claude Code and Playwright MCP</InternalLink>. It covers the GitHub Actions workflow, prompt engineering for effective testing, and how to get bug reports posted automatically to your PRs.
</Aside>

---

## Additional Resources

- [Vitest Browser Mode Guide](https://vitest.dev/guide/browser/) - The official docs are excellent
- [vitest-browser-vue](https://github.com/vitest-dev/vitest-browser-vue) - Vue rendering for Vitest browser mode
- [vitest-examples on GitHub](https://github.com/vitest-dev/vitest/tree/main/examples) - "Hello World" setup examples

---

--- title: Building an AI QA Engineer with Claude Code and Playwright MCP description: Learn how to build an automated QA engineer using Claude Code and Playwright MCP that tests your web app like a real user, runs on every pull request, and writes detailed bug reports. tags: ['ai', 'testing', 'claude-code', 'automation'] url: https://alexop.dev/posts/building_ai_qa_engineer_claude_code_playwright ---

# Building an AI QA Engineer with Claude Code and Playwright MCP



## Quick Summary

- Build an AI-powered QA engineer that tests your app through the browser like a real user
- Use Claude Code with Playwright MCP to automate browser interactions
- Run automated QA on every pull request via GitHub Actions
- Get detailed bug reports with screenshots posted directly to your PRs

## Table of Contents

## Introduction

Manual testing gets old fast. Clicking through your app after every change, checking if forms still work, making sure nothing breaks on mobile—it's tedious work that most developers avoid.

So I built an AI that does it for me.

Meet **Quinn**, my automated QA engineer. Quinn tests my app like a real person would. It clicks buttons. It fills forms with weird inputs. It resizes the browser to check mobile layouts. And it writes detailed bug reports.

The best part? Quinn runs automatically every time I open a pull request.

## The secret sauce: Claude Code + Playwright

Two tools make this possible:

**Claude Code** is Anthropic's coding assistant. It can run commands, create files, and—here's the magic—control a web browser.

**Playwright** is a browser automation tool. It can click, type, take screenshots, and do anything a human can do in a browser.

When you combine them through the <InternalLink slug="what-is-model-context-protocol-mcp">Model Context Protocol (MCP)</InternalLink>, Claude can literally browse your app like a real user.

<Aside type="info" title="What is MCP?">
  MCP (Model Context Protocol) standardizes how AI tools connect to external services. Think of it as USB-C for AI—one universal way to connect tools like Playwright, databases, or APIs to any LLM. Learn more in my <InternalLink slug="what-is-model-context-protocol-mcp">MCP deep dive</InternalLink>.
</Aside>

## Step 1: Give Claude a personality

I didn't want a boring test robot. I wanted a QA engineer with opinions.

So I created a prompt file that gives Claude a backstory:

```markdown
# QA Engineer Identity

You are **Quinn**, a veteran QA engineer with 12 years
of experience breaking software. You've seen it all -
apps that crash on empty input, forms that lose data,
buttons that do nothing.

## Your Philosophy

- **Trust nothing.** Developers say it works? Prove it.
- **Users are creative.** They'll do things no one anticipated.
- **Edge cases are where bugs hide.** The happy path is boring.
```

This isn't just for fun. The personality makes Claude test more thoroughly. Quinn doesn't just check if buttons work—Quinn tries to *break* things.

I also gave Quinn strict rules:

```markdown
## Non-Negotiable Rules

1. **UI ONLY.** You interact through the browser like a
   real user. You cannot read source code.

2. **SCREENSHOT BUGS.** Every bug gets a screenshot.

3. **CONTINUE AFTER BUGS.** Finding a bug is not the end.
   Document it, then KEEP TESTING.

4. **MOBILE MATTERS.** Always test mobile viewport (375x667).
```

## Step 2: Create the GitHub Action

GitHub Actions are like little robots that run tasks for you. They trigger when something happens (like opening a PR) and run whatever commands you specify.

Here's the core of the workflow:

```yaml
name: Claude QA

on:
  pull_request:
    types: [labeled]

jobs:
  qa:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Start my app
        run: |
          pnpm dev &
          # Wait for server to be ready
          sleep 10

      - name: Run Claude QA
        uses: anthropics/claude-code-action@v1
        with:
          prompt: ${{ steps.load-prompts.outputs.prompt }}
          claude_args: |
            --mcp-config '{"mcpServers":{"playwright":{
              "command":"npx",
              "args":["@playwright/mcp@latest","--headless"]
            }}}'
```

Let me break this down:

1. **Trigger**: The workflow runs when you add a label to a PR (like `qa-verify`)
2. **Start the app**: Launch your dev server so Claude has something to test
3. **Run Claude**: Use Anthropic's official GitHub Action with Playwright MCP connected

<Alert type="tip" title="Headless mode">
  The `--headless` flag runs the browser without a visible window. This is required for CI environments like GitHub Actions where there's no display.
</Alert>

## Step 3: Tell Claude what to test

For each PR, I want Claude to verify the actual changes. So I pass in the PR description:

```markdown
# PR Verification Testing

**PR #32**: Improve set editing and fix playlist overflow

## Your Mission

This PR claims to implement something. Your job is to:
1. **Verify** the claimed changes actually work
2. **Break** them with edge cases
3. **Ensure** no regressions in related features

## Test This PR

- Can users edit ANY set during active workout?
- Do completed sets stay editable?
- Do long exercise names truncate properly?
```

Claude reads this, understands what changed, and tests specifically for those features.

## What Quinn actually does

Here's a real example from my workout tracker. I opened a PR that said "allow editing any set during a workout."

<Aside type="info" title="See it in action">
  You can view the [actual GitHub Actions run](https://github.com/alexanderop/workoutTracker/actions/runs/20197464088) for this PR. The workflow completed in about 7 minutes and generated a QA report artifact.
</Aside>

Quinn went to work:

```mermaid
graph TD
    A[Start Workout] --> B[Add Exercise]
    B --> C[Fill Set Data]
    C --> D[Mark Complete]
    D --> E{Test Edit Feature}
    E -->|Happy Path| F[Change Weight ✓]
    E -->|Edge Case| G[Enter -50]
    E -->|Edge Case| H[Enter 999999]
    F --> I[Mobile Test]
    G --> I
    H --> I
    I --> J[Long Name Test]
    J --> K[Generate Report]
```

## The report

Quinn generates a full QA report in Markdown:

```markdown
# QA Verification Report

**PR**: #32 - Improve set editing
**Tester**: Quinn (Claude QA)

## Executive Summary

**APPROVED** - All claimed features work as described.

## Requirements Verification

| Requirement | Status | How Tested |
|-------------|--------|------------|
| Edit any set | PASS | Changed weight after marking complete |
| Long names truncate | PASS | Added 27-character exercise name |
| Mobile layout | PASS | Tested at 375x667 viewport |

## Bugs Found

None

## Verdict

**APPROVED** - Ready to merge.
```

This report gets posted automatically as a comment on your PR. You can see exactly what Quinn tested and whether your code is safe to merge.

## The toolbox

Quinn only gets access to browser tools—no code access:

```yaml
--allowedTools "
  mcp__playwright__browser_navigate,
  mcp__playwright__browser_click,
  mcp__playwright__browser_type,
  mcp__playwright__browser_take_screenshot,
  mcp__playwright__browser_resize,
  Write
"
```

This keeps things realistic. A real QA engineer tests through the UI, not by reading code. Quinn does the same.

<Aside type="tip" title="Why restrict tools?">
  Limiting Claude to browser-only tools prevents it from "cheating" by reading your source code. This forces truly <InternalLink slug="stop-white-box-testing-vue">black-box testing</InternalLink>—the same way real users experience your app.
</Aside>

## Why this works

Three reasons this approach beats traditional testing:

### It tests like a human

Unit tests check if functions return the right values. Quinn checks if users can actually accomplish their goals.

### It's flexible

You don't write test scripts that break when you change a button's text. Quinn understands intent and adapts.

### It finds unexpected bugs

Quinn tries things you wouldn't think to try. Negative numbers? Extremely long inputs? Clicking the same button five times fast? Quinn tests all of it.

## Comparison: AI QA vs traditional testing

| Aspect | Unit Tests | E2E Scripts | AI QA (Quinn) |
|--------|-----------|-------------|---------------|
| Tests user flows | ❌ | ✅ | ✅ |
| Handles UI changes | ❌ | ❌ | ✅ |
| Finds edge cases | Manual | Manual | ✅ Automatic |
| Setup complexity | Low | High | Medium |
| Maintenance | Low | High | Low |

## Getting started

Want to build your own AI QA engineer? Here's what you need:

1. **Get Claude Code access** — Sign up at Anthropic and get an API token

2. **Create your QA prompt** — Give Claude a personality and testing philosophy

3. **Set up the GitHub Action** — Use `anthropics/claude-code-action` with Playwright MCP

4. **Write a verification template** — Tell Claude what to test for each PR

<Aside type="tip" title="Full workflow available">
  The complete GitHub Actions workflow with explore/verify modes, focus areas, and automatic PR comments is available as a [GitHub Gist](https://gist.github.com/alexanderop/464a7a228653e4df27179b9c806b2065). Use it as a starting point for your own QA automation.
</Aside>

<Alert type="note" title="Learn more about Claude Code">
  If you're new to Claude Code, check out my <InternalLink slug="understanding-claude-code-full-stack">comprehensive guide to Claude Code features</InternalLink> covering MCP, Skills, Hooks, and more. You can also set up <InternalLink slug="claude-code-notification-hooks">desktop notifications via hooks</InternalLink> so you know the moment Claude finishes a task locally.
</Alert>

## A word of caution

This approach is experimental. AI-driven QA is exciting, but it's not a replacement for deterministic testing.

A solid testing foundation still matters more:

- **Unit tests** catch regressions instantly
- **Integration tests** verify your components work together
- **E2E tests** with Playwright or Cypress give you reproducible, reliable checks

AI QA works best as a *complement* to these, not a replacement. Use it for exploratory testing, edge case discovery, and verifying user flows that are hard to script.

<Alert type="tip" title="Beyond QA">
  Claude Code in GitHub Actions isn't limited to QA. The same pattern works for:
  - **SEO audits** — Check meta tags, heading structure, Core Web Vitals
  - **<InternalLink slug="how-to-improve-accessibility-with-testing-library-and-jest-axe-for-your-vue-application">Accessibility testing</InternalLink>** — Verify ARIA labels, keyboard navigation, color contrast
  - **Content review** — Validate links, check for broken images, lint prose
  - **<InternalLink slug="visual-regression-testing-with-vue-and-vitest-browser">Visual regression</InternalLink>** — Compare screenshots across deployments

  Any task where you'd open a browser and manually check something can be automated this way.
</Alert>

## Conclusion

Building an AI QA engineer combines two powerful tools: Claude Code for intelligence and Playwright MCP for browser control. The result is automated testing that thinks like a human but works tirelessly.

It's still early days for this approach. But some day, Quinn might find a bug that would have embarrassed me in production. On that day, this whole experiment will have paid for itself.

## Additional resources

- [Full GitHub Actions Workflow](https://gist.github.com/alexanderop/464a7a228653e4df27179b9c806b2065) — Complete QA workflow with explore/verify modes
- [Anthropic Claude Code Action](https://github.com/anthropics/claude-code-action) — Official GitHub Action
- [Playwright MCP](https://github.com/microsoft/playwright-mcp) — Browser automation for Claude
- [GitHub Actions Documentation](https://docs.github.com/en/actions) — Workflow automation basics

---

--- title: Vue Composables Style Guide: Lessons from VueUse's Codebase description: A practical guide for writing production-quality Vue 3 composables, distilled from studying VueUse's patterns for SSR safety, cleanup, and TypeScript. tags: ['vue', 'typescript'] url: https://alexop.dev/posts/vueuse_composables_style_guide ---

# Vue Composables Style Guide: Lessons from VueUse's Codebase



I was studying VueUse's codebase to understand how they structure their composables. VueUse has become the de facto standard library for Vue utilities, and I wanted to understand the patterns that make their composables so reliable. After diving deep into their source code, I distilled the key patterns into this style guide.

Whether you're building your own composable library or just want to write better code, these patterns will help you create maintainable, type-safe, and SSR-compatible composition utilities.

If you're new to Vue composables, I recommend starting with my earlier post <InternalLink slug="mastering-vue-3-composables-a-comprehensive-style-guide">Mastering Vue 3 Composables: A Comprehensive Style Guide</InternalLink>, which covers many of the same patterns from a beginner-friendly perspective.

## Quick Summary

This guide covers patterns for writing production-quality Vue 3 composables:

- **Project structure** and naming conventions
- **Ref type selection** (shallowRef vs ref)
- **Flexible inputs** with `MaybeRefOrGetter`
- **SSR safety** patterns for server-side rendering
- **Cleanup and memory management** with auto-cleanup utilities
- **Controllable composables** (pausable, stoppable patterns)
- **TypeScript best practices** for full type inference
- **Testing strategies** - see <InternalLink slug="how-to-test-vue-composables">How to Test Vue Composables</InternalLink>

## Table of Contents

---

## 1. Getting Started

### What Makes a Good Composable?

A well-designed composable should be:

- **Focused**: Does one thing well
- **Flexible**: Accepts refs, getters, or plain values
- **Safe**: Works in SSR, handles cleanup automatically
- **Typed**: Full TypeScript support with inference
- **Testable**: Easy to unit test in isolation

### Minimal Example

```typescript
export function useCounter(initialValue: MaybeRefOrGetter<number> = 0) {
  const count = shallowRef(toValue(initialValue))

  const increment = () => count.value++
  const decrement = () => count.value--
  const reset = () => count.value = toValue(initialValue)

  return { count, increment, decrement, reset }
}
```

This simple example already demonstrates several VueUse patterns: using `shallowRef` for primitives, accepting `MaybeRefOrGetter` for flexible inputs, and returning an object with reactive state and methods.

---

## 2. Project Structure

### Recommended Layout

<FileTree
  tree={[
    {
      name: "src/composables",
      open: true,
      children: [
        {
          name: "useCounter",
          open: true,
          children: [
            { name: "index.ts", comment: "Implementation" },
            { name: "index.test.ts", comment: "Tests" },
            { name: "types.ts", comment: "Types (optional)" },
          ],
        },
        {
          name: "useFetch",
          children: [
            { name: "index.ts" },
            { name: "index.test.ts" },
          ],
        },
        {
          name: "utils",
          children: [
            { name: "ssr.ts", comment: "SSR utilities" },
            { name: "types.ts", comment: "Shared types" },
            { name: "cleanup.ts", comment: "Cleanup utilities" },
          ],
        },
        { name: "index.ts", comment: "Public exports" },
      ],
    },
  ]}
/>

### Export Pattern

```typescript
// src/composables/index.ts
export { useCounter } from './useCounter'
export { useFetch } from './useFetch'
export type { UseCounterReturn, UseCounterOptions } from './useCounter'
export type { UseFetchReturn, UseFetchOptions } from './useFetch'
```

<Aside type="caution" title="Important">
Use named exports only. Never use default exports for composables. This ensures better tree-shaking and clearer imports.
</Aside>

For more on project organization, check out <InternalLink slug="how-to-structure-vue-projects">How to Structure Vue Projects</InternalLink>.

---

## 3. Naming Conventions

### Function Names

| Prefix | Use Case | Example |
|--------|----------|---------|
| `use` | Standard composables | `useMouse`, `useStorage`, `useFetch` |
| `create` | Factory functions that return composables | `createSharedState`, `createEventHook` |
| `on` | Event listener composables | `onClickOutside`, `onKeyPress` |
| `try` | Safe operations that may fail silently | `tryOnMounted`, `tryOnCleanup` |

### Type Names

```typescript
// Options: Use{Name}Options
export interface UseStorageOptions {
  deep?: boolean
  listenToChanges?: boolean
}

// Return type: Use{Name}Return
export interface UseStorageReturn<T> {
  data: Ref<T>
  set: (value: T) => void
  remove: () => void
}

// Inferred type shorthand
export type UseStorageReturnType<T> = ReturnType<typeof useStorage<T>>
```

---

## 4. Choosing the Right Ref Type

This is one of the most important decisions when writing composables. VueUse consistently follows this pattern:

```mermaid
flowchart TD
    A[What type of data?] --> B{Primitive?}
    B -->|Yes| C[shallowRef]
    B -->|No| D{Will you mutate nested properties?}
    D -->|Yes| E[ref - deep reactivity]
    D -->|No - replace whole object| F[shallowRef]

    style C fill:#22c55e,color:#fff
    style E fill:#3b82f6,color:#fff
    style F fill:#22c55e,color:#fff
```

### shallowRef - For Primitives and Replaced Objects

```typescript
// Primitives
const count = shallowRef(0)
const isActive = shallowRef(false)
const name = shallowRef('')

// Objects that get replaced, not mutated
const user = shallowRef<User | null>(null)
const response = shallowRef<Response | null>(null)

// Usage: Replace the whole object
user.value = { name: 'John', age: 30 }  // Triggers reactivity
```

### ref - For Deep Mutations

```typescript
// Objects with nested mutations
const form = ref({
  user: { name: '', email: '' },
  settings: { theme: 'light' }
})

// Usage: Mutate nested properties
form.value.user.name = 'John'  // Triggers reactivity
form.value.settings.theme = 'dark'  // Triggers reactivity
```

### Let Users Choose

For composables storing user data, let them decide:

```typescript
export interface UseStateOptions {
  /**
   * Use shallow reactivity for better performance with large objects
   * @default false
   */
  shallow?: boolean
}

export function useState<T>(initialValue: T, options: UseStateOptions = {}) {
  const { shallow = false } = options

  const state = shallow
    ? shallowRef(initialValue)
    : ref(initialValue)

  return { state }
}
```

---

## 5. Flexible Inputs

### Accept Refs, Getters, or Plain Values

Use `MaybeRefOrGetter<T>` to make your composables flexible:

```typescript
export function useTitle(title: MaybeRefOrGetter<string>) {
  // toValue() handles all input types:
  // - Plain value: 'Hello' → 'Hello'
  // - Ref: ref('Hello') → 'Hello'
  // - Getter: () => 'Hello' → 'Hello'

  watchEffect(() => {
    document.title = toValue(title)
  })
}

// All of these work:
useTitle('Static Title')
useTitle(ref('Reactive Title'))
useTitle(() => `Page ${currentPage.value}`)
useTitle(computed(() => `${userName.value}'s Profile`))
```

### Reactive Configuration

For options that should be reactive:

```typescript
export interface UseIntervalOptions {
  interval?: MaybeRefOrGetter<number>
  immediate?: boolean
}

export function useInterval(
  callback: () => void,
  options: UseIntervalOptions = {}
) {
  const { interval = 1000, immediate = true } = options

  // Watch the interval for changes
  watch(
    () => toValue(interval),
    (ms) => {
      clearInterval(timer)
      if (ms > 0) {
        timer = setInterval(callback, ms)
      }
    },
    { immediate }
  )
}

// Interval can change reactively
const delay = ref(1000)
useInterval(() => console.log('tick'), { interval: delay })
delay.value = 500  // Interval updates automatically
```

---

## 6. Designing Options

### Structure

```typescript
export interface UseStorageOptions<T> {
  /**
   * Storage type to use
   * @default 'local'
   */
  storage?: 'local' | 'session'

  /**
   * Custom serializer for complex data
   * @default JSON.stringify/parse
   */
  serializer?: {
    read: (raw: string) => T
    write: (value: T) => string
  }

  /**
   * Sync across browser tabs
   * @default true
   */
  listenToStorageChanges?: boolean

  /**
   * Called when an error occurs
   */
  onError?: (error: Error) => void
}
```

### Rules for Options

1. **Document every option** with JSDoc
2. **Provide sensible defaults** using `@default`
3. **Use callbacks** for events (`onError`, `onSuccess`, `onChange`)
4. **Group related options** in nested objects if complex

### Extending Base Interfaces

Create reusable option interfaces:

```typescript
// src/composables/utils/types.ts

/** Options for composables that use window */
export interface ConfigurableWindow {
  /**
   * Custom window instance (useful for iframes or testing)
   * @default window
   */
  window?: Window
}

/** Options for composables that use document */
export interface ConfigurableDocument {
  /**
   * Custom document instance
   * @default document
   */
  document?: Document
}

// Usage in composables
export interface UseEventListenerOptions extends ConfigurableWindow {
  capture?: boolean
  passive?: boolean
}
```

---

## 7. Return Values

### Object Return (Recommended for Multiple Values)

```typescript
export interface UseMouseReturn {
  /** Current X position */
  x: Readonly<Ref<number>>
  /** Current Y position */
  y: Readonly<Ref<number>>
  /** Source of the last event */
  sourceType: Readonly<Ref<'mouse' | 'touch' | null>>
}

export function useMouse(): UseMouseReturn {
  const x = shallowRef(0)
  const y = shallowRef(0)
  const sourceType = shallowRef<'mouse' | 'touch' | null>(null)

  // ... implementation

  return {
    x: readonly(x),
    y: readonly(y),
    sourceType: readonly(sourceType),
  }
}
```

### Single Ref Return (For Simple Composables)

```typescript
export function useOnline(): Readonly<Ref<boolean>> {
  const isOnline = shallowRef(navigator.onLine)

  // ... implementation

  return readonly(isOnline)
}
```

### Tuple Return (When Destructuring Order Matters)

```typescript
export function useToggle(
  initialValue = false
): [Ref<boolean>, (value?: boolean) => void] {
  const state = shallowRef(initialValue)

  const toggle = (value?: boolean) => {
    state.value = value ?? !state.value
  }

  return [state, toggle]
}

// Usage
const [isOpen, toggleOpen] = useToggle()
```

### Making Composables Awaitable

For async composables, implement `PromiseLike`:

```typescript
export function useFetch<T>(url: MaybeRefOrGetter<string>) {
  const data = shallowRef<T | null>(null)
  const isLoading = shallowRef(true)
  const error = shallowRef<Error | null>(null)

  const execute = async () => {
    isLoading.value = true
    try {
      const response = await fetch(toValue(url))
      data.value = await response.json()
    } catch (e) {
      error.value = e as Error
    } finally {
      isLoading.value = false
    }
  }

  execute()

  const shell = { data, isLoading, error, execute }

  return {
    ...shell,
    // Make it awaitable
    then<TResult>(
      onFulfilled?: (value: typeof shell) => TResult
    ): Promise<TResult> {
      return new Promise((resolve) => {
        watch(isLoading, (loading) => {
          if (!loading) resolve(onFulfilled?.(shell) as TResult)
        }, { immediate: true })
      })
    }
  }
}

// Can be used both ways:
const { data, isLoading } = useFetch('/api/users')

// Or awaited:
const { data } = await useFetch('/api/users')
console.log(data.value)  // Data is ready
```

---

## 8. SSR Safety

### The Problem

Browser APIs (`window`, `document`, `localStorage`) don't exist on the server. Accessing them during SSR causes errors.

For a deep dive into this topic, see <InternalLink slug="how-vueuse-solves-ssr-window-errors-vue-applications">How VueUse Solves SSR Window Errors</InternalLink>.

```mermaid
sequenceDiagram
    participant B as Browser
    participant S as Server (Node.js)
    B->>S: Request page
    S-->>S: Run Vue code (no window!)
    Note over S: window, document undefined
    S-->>B: Send HTML
    B-->>B: Hydrate app (has window)
    Note over B: Browser APIs available
```

### Solution: Create SSR Utilities

```typescript
// src/composables/utils/ssr.ts

/**
 * Check if code is running in browser
 */
export const isClient = typeof window !== 'undefined'

/**
 * Check if code is running on server
 */
export const isServer = !isClient

/**
 * Safe window reference (undefined on server)
 */
export const defaultWindow = isClient ? window : undefined

/**
 * Safe document reference (undefined on server)
 */
export const defaultDocument = isClient ? document : undefined

/**
 * Safe localStorage reference (undefined on server)
 */
export const defaultStorage = isClient ? localStorage : undefined
```

### Using SSR Utilities

```typescript
export interface UseWindowSizeOptions extends ConfigurableWindow {
  initialWidth?: number
  initialHeight?: number
}

export function useWindowSize(options: UseWindowSizeOptions = {}) {
  const {
    window = defaultWindow,
    initialWidth = Infinity,
    initialHeight = Infinity,
  } = options

  const width = shallowRef(initialWidth)
  const height = shallowRef(initialHeight)

  const update = () => {
    // Guard: Only run if window exists
    if (window) {
      width.value = window.innerWidth
      height.value = window.innerHeight
    }
  }

  // Only set up listeners on client
  if (window) {
    update()
    window.addEventListener('resize', update)

    onUnmounted(() => {
      window.removeEventListener('resize', update)
    })
  }

  return { width, height }
}
```

### Feature Detection

Create a utility to safely check for browser features:

```typescript
export function useSupported(check: () => boolean): Readonly<Ref<boolean>> {
  const isSupported = shallowRef(false)

  onMounted(() => {
    isSupported.value = check()
  })

  return readonly(isSupported)
}

// Usage
export function useClipboard() {
  const isSupported = useSupported(
    () => navigator && 'clipboard' in navigator
  )

  const copy = async (text: string) => {
    if (!isSupported.value) {
      console.warn('Clipboard API not supported')
      return false
    }
    // ... implementation
  }

  return { isSupported, copy }
}
```

---

## 9. Cleanup and Memory Management

### The Problem

Event listeners, timers, and observers must be cleaned up to prevent memory leaks.

```mermaid
flowchart LR
    A[Composable Created] --> B[Register Resources]
    B --> C[Listeners, Timers, etc.]
    C --> D{Component Unmounted?}
    D -->|Yes| E[Cleanup Required]
    D -->|No| C
    E --> F[Remove Listeners]
    E --> G[Clear Timers]
    E --> H[Disconnect Observers]

    style E fill:#ef4444,color:#fff
    style F fill:#22c55e,color:#fff
    style G fill:#22c55e,color:#fff
    style H fill:#22c55e,color:#fff
```

### Solution: Auto-Cleanup Utility

```typescript
// src/composables/utils/cleanup.ts
/**
 * Register a cleanup function that runs when the scope is disposed.
 * Safe to call outside of component context.
 *
 * @returns true if cleanup was registered, false otherwise
 */
export function tryOnCleanup(fn: () => void): boolean {
  if (getCurrentScope()) {
    onScopeDispose(fn)
    return true
  }
  return false
}

/**
 * Safe onMounted that doesn't error outside component context
 */
export function tryOnMounted(fn: () => void): void {
  if (getCurrentScope()) {
    onMounted(fn)
  }
}
```

### Using Auto-Cleanup

```typescript
export function useInterval(callback: () => void, ms: number) {
  let timer: ReturnType<typeof setInterval> | null = null

  const start = () => {
    stop()
    timer = setInterval(callback, ms)
  }

  const stop = () => {
    if (timer) {
      clearInterval(timer)
      timer = null
    }
  }

  start()

  // Automatically stops when component unmounts
  tryOnCleanup(stop)

  return { start, stop }
}
```

### Event Listener Composable with Auto-Cleanup

```typescript
export function useEventListener<K extends keyof WindowEventMap>(
  event: K,
  handler: (event: WindowEventMap[K]) => void,
  options?: AddEventListenerOptions & ConfigurableWindow
): () => void {
  const { window = defaultWindow, ...listenerOptions } = options ?? {}

  let cleanup = () => {}

  if (window) {
    window.addEventListener(event, handler, listenerOptions)
    cleanup = () => window.removeEventListener(event, handler, listenerOptions)
  }

  tryOnCleanup(cleanup)

  return cleanup
}
```

---

## 10. Controllable Composables

### Pausable Pattern

```mermaid
stateDiagram-v2
    [*] --> Active: immediate=true
    [*] --> Paused: immediate=false
    Active --> Paused: pause()
    Paused --> Active: resume()
    Active --> [*]: cleanup
    Paused --> [*]: cleanup
```

For composables that can be paused and resumed:

```typescript
export interface Pausable {
  /** Whether the composable is currently active */
  isActive: Readonly<Ref<boolean>>
  /** Pause the composable */
  pause: () => void
  /** Resume the composable */
  resume: () => void
}

export interface UseIntervalOptions {
  /** Start immediately */
  immediate?: boolean
  /** Call callback immediately when starting */
  immediateCallback?: boolean
}

export function useIntervalFn(
  callback: () => void,
  interval: MaybeRefOrGetter<number> = 1000,
  options: UseIntervalOptions = {}
): Pausable {
  const { immediate = true, immediateCallback = false } = options

  const isActive = shallowRef(false)
  let timer: ReturnType<typeof setInterval> | null = null

  function clean() {
    if (timer) {
      clearInterval(timer)
      timer = null
    }
  }

  function pause() {
    isActive.value = false
    clean()
  }

  function resume() {
    const ms = toValue(interval)
    if (ms <= 0) return

    isActive.value = true
    if (immediateCallback) callback()

    clean()
    timer = setInterval(callback, ms)
  }

  if (immediate) resume()

  tryOnCleanup(pause)

  return {
    isActive: readonly(isActive),
    pause,
    resume,
  }
}

// Usage
const { isActive, pause, resume } = useIntervalFn(() => {
  console.log('tick')
}, 1000)

pause()   // Stop ticking
resume()  // Start again
```

### Stoppable Pattern

For one-way stopping (e.g., timeouts, one-time operations):

```typescript
export interface Stoppable {
  /** Whether the operation is pending */
  isPending: Readonly<Ref<boolean>>
  /** Stop the operation */
  stop: () => void
}

export function useTimeoutFn(
  callback: () => void,
  interval: MaybeRefOrGetter<number>,
  options: { immediate?: boolean } = {}
): Stoppable & { start: () => void } {
  const { immediate = true } = options

  const isPending = shallowRef(false)
  let timer: ReturnType<typeof setTimeout> | null = null

  function stop() {
    isPending.value = false
    if (timer) {
      clearTimeout(timer)
      timer = null
    }
  }

  function start() {
    stop()
    isPending.value = true
    timer = setTimeout(() => {
      isPending.value = false
      timer = null
      callback()
    }, toValue(interval))
  }

  if (immediate) start()

  tryOnCleanup(stop)

  return {
    isPending: readonly(isPending),
    stop,
    start,
  }
}
```

---

## 11. Error Handling

### Graceful Degradation

```typescript
export function useGeolocation() {
  const isSupported = useSupported(
    () => navigator && 'geolocation' in navigator
  )

  const coords = shallowRef<GeolocationCoordinates | null>(null)
  const error = shallowRef<GeolocationPositionError | null>(null)

  function update() {
    if (!isSupported.value) return

    navigator.geolocation.getCurrentPosition(
      (position) => {
        coords.value = position.coords
        error.value = null
      },
      (err) => {
        error.value = err
      }
    )
  }

  if (isSupported.value) {
    update()
  }

  return {
    isSupported,
    coords,
    error,
    update,
  }
}
```

### Error Callbacks

```typescript
export interface UseAsyncStateOptions<T> {
  /** Called on success */
  onSuccess?: (data: T) => void
  /** Called on error */
  onError?: (error: unknown) => void
  /**
   * Whether to throw errors
   * @default false
   */
  throwError?: boolean
}

export function useAsyncState<T>(
  promise: () => Promise<T>,
  initialState: T,
  options: UseAsyncStateOptions<T> = {}
) {
  const { onSuccess, onError, throwError = false } = options

  const state = shallowRef<T>(initialState)
  const error = shallowRef<unknown>(null)
  const isLoading = shallowRef(false)

  async function execute() {
    isLoading.value = true
    error.value = null

    try {
      const data = await promise()
      state.value = data
      onSuccess?.(data)
    } catch (e) {
      error.value = e
      onError?.(e)
      if (throwError) throw e
    } finally {
      isLoading.value = false
    }
  }

  execute()

  return { state, error, isLoading, execute }
}
```

---

## 13. TypeScript Best Practices

### Generic Type Inference

Let TypeScript infer types when possible:

```typescript
// Type T is inferred from defaultValue
export function useStorage<T>(key: string, defaultValue: T): Ref<T> {
  // ...
}

// Usage - types are inferred
const name = useStorage('name', 'John')     // Ref<string>
const count = useStorage('count', 0)        // Ref<number>
const user = useStorage('user', { id: 1 })  // Ref<{ id: number }>
```

### Function Overloads

Use overloads for different call signatures:

```typescript
// Overload 1: Window events
export function useEventListener<K extends keyof WindowEventMap>(
  event: K,
  handler: (e: WindowEventMap[K]) => void
): () => void

// Overload 2: Element events
export function useEventListener<K extends keyof HTMLElementEventMap>(
  target: MaybeRefOrGetter<HTMLElement | null>,
  event: K,
  handler: (e: HTMLElementEventMap[K]) => void
): () => void

// Implementation
export function useEventListener(...args: any[]): () => void {
  // ... implementation handles all cases
}
```

### Conditional Return Types

```typescript
// If passed a ref, return just the toggle function
export function useToggle(
  value: Ref<boolean>
): (value?: boolean) => boolean

// If passed a plain value, return tuple
export function useToggle(
  initialValue?: boolean
): [Ref<boolean>, (value?: boolean) => boolean]

// Implementation
export function useToggle(
  initialValue: MaybeRef<boolean> = false
) {
  const valueIsRef = isRef(initialValue)
  const state = shallowRef(toValue(initialValue))

  const toggle = (value?: boolean) => {
    state.value = value ?? !state.value
    return state.value
  }

  if (valueIsRef) {
    return toggle
  }
  return [state, toggle] as const
}
```

---

## 14. Testing

For comprehensive testing strategies including basic test structure, testing with timers, and testing async composables, see <InternalLink slug="how-to-test-vue-composables">How to Test Vue Composables</InternalLink>.

---

## 15. Documentation

### JSDoc Comments

```typescript
/**
 * Reactive mouse position
 *
 * @param options - Configuration options
 * @returns Reactive mouse coordinates and source type
 *
 * @example
 * ```ts
 * const { x, y } = useMouse()
 *
 * watchEffect(() => {
 *   console.log(`Mouse at ${x.value}, ${y.value}`)
 * })
 * ```
 *
 * @see https://your-docs.com/composables/use-mouse
 */
export function useMouse(options?: UseMouseOptions): UseMouseReturn {
  // ...
}
```

### Document Every Option

Every option should have a JSDoc comment with a `@default` tag:

```typescript
export interface UseStorageOptions {
  /**
   * Storage type to use
   * @default 'local'
   */
  storage?: 'local' | 'session'

  /**
   * Whether to sync across browser tabs
   * @default true
   */
  listenToStorageChanges?: boolean
}
```

---

## 16. Templates

### Basic Composable Template

```typescript
export interface UseXxxOptions {
  /**
   * Option description
   * @default 'defaultValue'
   */
  someOption?: string
}

export interface UseXxxReturn {
  /** Description of value */
  value: Readonly<Ref<number>>
  /** Description of action */
  doSomething: () => void
}

/**
 * Short description of what this composable does
 *
 * @param param - Description of parameter
 * @param options - Configuration options
 */
export function useXxx(
  param: MaybeRefOrGetter<string>,
  options: UseXxxOptions = {}
): UseXxxReturn {
  const { someOption = 'defaultValue' } = options

  const value = shallowRef(0)

  function doSomething() {
    const paramValue = toValue(param)
    value.value++
  }

  // Cleanup if needed
  tryOnCleanup(() => {
    // cleanup logic
  })

  return {
    value: readonly(value),
    doSomething,
  }
}
```

### Async Composable Template

```typescript
export interface UseAsyncXxxOptions<T> {
  /**
   * Execute immediately
   * @default true
   */
  immediate?: boolean
  /**
   * Called on success
   */
  onSuccess?: (data: T) => void
  /**
   * Called on error
   */
  onError?: (error: Error) => void
}

export interface UseAsyncXxxReturn<T> {
  data: Readonly<Ref<T | null>>
  error: Readonly<Ref<Error | null>>
  isLoading: Readonly<Ref<boolean>>
  execute: () => Promise<void>
  onSuccess: EventHook<T>['on']
  onError: EventHook<Error>['on']
}

export function useAsyncXxx<T>(
  fetcher: () => Promise<T>,
  options: UseAsyncXxxOptions<T> = {}
): UseAsyncXxxReturn<T> {
  const { immediate = true, onSuccess, onError } = options

  const data = shallowRef<T | null>(null)
  const error = shallowRef<Error | null>(null)
  const isLoading = shallowRef(false)

  const successHook = createEventHook<T>()
  const errorHook = createEventHook<Error>()

  async function execute() {
    isLoading.value = true
    error.value = null

    try {
      const result = await fetcher()
      data.value = result
      onSuccess?.(result)
      successHook.trigger(result)
    } catch (e) {
      const err = e as Error
      error.value = err
      onError?.(err)
      errorHook.trigger(err)
    } finally {
      isLoading.value = false
    }
  }

  if (immediate) {
    execute()
  }

  return {
    data: readonly(data),
    error: readonly(error),
    isLoading: readonly(isLoading),
    execute,
    onSuccess: successHook.on,
    onError: errorHook.on,
  }
}
```

### Pausable Composable Template

```typescript
export interface Pausable {
  isActive: Readonly<Ref<boolean>>
  pause: () => void
  resume: () => void
}

export interface UsePausableXxxOptions {
  /**
   * Start immediately
   * @default true
   */
  immediate?: boolean
}

export function usePausableXxx(
  callback: () => void,
  interval: MaybeRefOrGetter<number> = 1000,
  options: UsePausableXxxOptions = {}
): Pausable {
  const { immediate = true } = options

  const isActive = shallowRef(false)
  let timer: ReturnType<typeof setInterval> | null = null

  function clean() {
    if (timer) {
      clearInterval(timer)
      timer = null
    }
  }

  function pause() {
    isActive.value = false
    clean()
  }

  function resume() {
    const ms = toValue(interval)
    if (ms <= 0) return

    isActive.value = true
    clean()
    timer = setInterval(callback, ms)
  }

  if (immediate) {
    resume()
  }

  tryOnCleanup(pause)

  return {
    isActive: readonly(isActive),
    pause,
    resume,
  }
}
```

---

## Quick Reference Checklist

Use this checklist when creating new composables:

**Structure**
- [ ] Named export (no default)
- [ ] Explicit return type interface
- [ ] JSDoc with `@param`, `@returns`, `@example`

**Reactivity**
- [ ] `shallowRef` for primitives
- [ ] `ref` only when deep mutations needed
- [ ] `MaybeRefOrGetter` for flexible inputs
- [ ] `toValue()` to unwrap inputs
- [ ] `readonly()` for exposed refs

**Safety**
- [ ] Guard browser APIs (`if (window)`)
- [ ] Auto-cleanup with `tryOnCleanup`
- [ ] Feature detection for optional APIs

**TypeScript**
- [ ] Generic type inference where possible
- [ ] Overloads for multiple signatures
- [ ] Strict types, no `any`

**Testing**
- [ ] Unit tests for all functionality
- [ ] Edge cases (null, undefined, empty)
- [ ] Cleanup verification

---

## Additional Resources

- [Vue Composition API Docs](https://vuejs.org/guide/extras/composition-api-faq.html)
- [Vue Reactivity in Depth](https://vuejs.org/guide/extras/reactivity-in-depth.html)
- [VueUse](https://vueuse.org) - Collection of Vue composables (the source of these patterns)
- [Vitest](https://vitest.dev) - Testing framework for Vue

---

These patterns represent the accumulated wisdom from VueUse's codebase. Apply them consistently to build maintainable, type-safe, and production-ready Vue composables.

---

--- title: A Claude Code TDD Skill: Forcing Red-Green-Refactor Discipline description: Build a custom TDD workflow with Claude Code using skills and subagents that enforce Red-Green-Refactor discipline for your Vue projects. tags: ['ai', 'vue', 'testing', 'claude-code'] url: https://alexop.dev/posts/custom-tdd-workflow-claude-code-vue ---

# A Claude Code TDD Skill: Forcing Red-Green-Refactor Discipline



I rely on Claude Code, but it has a structural limitation: it defaults to implementation-first. It writes the "Happy Path," ignoring edge cases. When I try to force TDD in a single context window, the implementation "bleeds" into the test logic (context pollution). This article documents a multi-agent system using Claude's "Skills" and "Hooks" that enforces a strict Red-Green-Refactor cycle.

<Alert type="note" title="Framework Agnostic">
  While this article uses Vue as an example, the TDD principles and Claude Code workflow apply to any technology. Whether you're working with React, Angular, Svelte, or even backend languages like Python, Go, or Rust—the Red-Green-Refactor cycle and subagent orchestration work the same way.
</Alert>

## The Problem with AI-Assisted TDD

When I ask Claude to "implement feature X," it writes the implementation first. Every time. TDD flips this—you write the test first, watch it fail, then write minimal code to make it pass.

I needed a way to:
* **Force test-first** — No implementation before a failing test exists
* **Keep phases focused** — The test writer shouldn't think about implementation details
* **Ensure refactoring happens** — Easy to skip when the feature already works

## Skills + Subagents

Claude Code supports two features I hadn't explored until recently:

* **<InternalLink slug="understanding-claude-code-full-stack">Skills</InternalLink>** (`.claude/skills/`): High-level workflows that orchestrate complex tasks
* **Agents** (`.claude/agents/`): Specialized workers that handle specific jobs

You might wonder: why use subagents at all? Skills alone could handle the TDD workflow. But there's a catch—context pollution.

### The Context Pollution Problem

<Alert type="warning" title="Why Single-Context LLMs Cheat at TDD">
When everything runs in one context window, **the LLM cannot truly follow TDD**. The test writer's detailed analysis bleeds into the implementer's thinking. The implementer's code exploration pollutes the refactorer's evaluation. Each phase drags along baggage from the others.

This isn't just messy—it fundamentally breaks TDD. The whole point of writing the test first is that **you don't know the implementation yet**. But if the same context sees both phases, the LLM subconsciously designs tests around the implementation it's already planning. It "cheats" without meaning to.
</Alert>

**Subagents solve this architectural limitation.** Each phase runs in complete isolation:

- The **test writer** focuses purely on test design—it has no idea how the feature will be implemented
- The **implementer** sees only the failing test—it can't be influenced by test-writing decisions
- The **refactorer** evaluates clean implementation code—it starts fresh without implementation baggage

Each agent starts with exactly the context it needs and nothing more. This isn't just organization—it's the only way to get genuine test-first development from an LLM.

Combining skills with subagents gave me exactly what I needed:

## The TDD Skill

The orchestrating skill lives at `.claude/skills/tdd-integration/skill.md`:

```markdown
---
name: tdd-integration
description: Enforce Test-Driven Development with strict Red-Green-Refactor cycle using integration tests. Auto-triggers when implementing new features or functionality. Trigger phrases include "implement", "add feature", "build", "create functionality", or any request to add new behavior. Does NOT trigger for bug fixes, documentation, or configuration changes.
---

# TDD Integration Testing

Enforce strict Test-Driven Development using the Red-Green-Refactor cycle with dedicated subagents.

## Mandatory Workflow

Every new feature MUST follow this strict 3-phase cycle. Do NOT skip phases.

### Phase 1: RED - Write Failing Test

🔴 RED PHASE: Delegating to tdd-test-writer...

Invoke the `tdd-test-writer` subagent with:
- Feature requirement from user request
- Expected behavior to test

The subagent returns:
- Test file path
- Failure output confirming test fails
- Summary of what the test verifies

**Do NOT proceed to Green phase until test failure is confirmed.**

### Phase 2: GREEN - Make It Pass

🟢 GREEN PHASE: Delegating to tdd-implementer...

Invoke the `tdd-implementer` subagent with:
- Test file path from RED phase
- Feature requirement context

The subagent returns:
- Files modified
- Success output confirming test passes
- Implementation summary

**Do NOT proceed to Refactor phase until test passes.**

### Phase 3: REFACTOR - Improve

🔵 REFACTOR PHASE: Delegating to tdd-refactorer...

Invoke the `tdd-refactorer` subagent with:
- Test file path
- Implementation files from GREEN phase

The subagent returns either:
- Changes made + test success output, OR
- "No refactoring needed" with reasoning

**Cycle complete when refactor phase returns.**

## Multiple Features

Complete the full cycle for EACH feature before starting the next:

Feature 1: 🔴 → 🟢 → 🔵 ✓
Feature 2: 🔴 → 🟢 → 🔵 ✓
Feature 3: 🔴 → 🟢 → 🔵 ✓

## Phase Violations

Never:
- Write implementation before the test
- Proceed to Green without seeing Red fail
- Skip Refactor evaluation
- Start a new feature before completing the current cycle
```

The `description` field contains trigger phrases so Claude activates this skill automatically when I ask to implement something. Each phase has explicit "Do NOT proceed until..." gates—Claude needs clear boundaries. The 🔴🟢🔵 emojis make tracking progress easy in the output.

## The Test Writer Agent (RED Phase)

At `.claude/agents/tdd-test-writer.md`:

```markdown
---
name: tdd-test-writer
description: Write failing integration tests for TDD RED phase. Use when implementing new features with TDD. Returns only after verifying test FAILS.
tools: Read, Glob, Grep, Write, Edit, Bash
skills: vue-integration-testing
---

# TDD Test Writer (RED Phase)

Write a failing integration test that verifies the requested feature behavior.

## Process

1. Understand the feature requirement from the prompt
2. Write an integration test in `src/__tests__/integration/`
3. Run `pnpm test:unit <test-file>` to verify it fails
4. Return the test file path and failure output

## Test Structure

typescript
describe('Feature Name', () => {
  afterEach(async () => {
    resetWorkout()
    await resetDatabase()
    document.body.innerHTML = ''
  })

  it('describes the user journey', async () => {
    const app = await createTestApp()

    // Act: User interactions
    await app.user.click(app.getByRole('button', { name: /action/i }))

    // Assert: Verify outcomes
    expect(app.router.currentRoute.value.path).toBe('/expected')

    app.cleanup()
  })
})

## Requirements

- Test must describe user behavior, not implementation details
- Use `createTestApp()` for full app integration
- Use Testing Library queries (`getByRole`, `getByText`)
- Test MUST fail when run - verify before returning

## Return Format

Return:
- Test file path
- Failure output showing the test fails
- Brief summary of what the test verifies
```

I limited the tools to only what's needed for writing and running tests. The `skills` field pulls in my `vue-integration-testing` skill for project-specific context. And the explicit return format ensures clean handoffs between phases.

<Alert type="info" title="About the vue-integration-testing skill">
  This skill defines how I want tests written: using jsdom with Vue Test Utils, writing BDD-style tests that describe user behavior, and avoiding mocks wherever possible. I don't see much value in unit tests that mock everything—they often just verify implementation details rather than actual functionality. Integration tests that exercise real code paths catch more bugs.
</Alert>

## The Implementer Agent (GREEN Phase)

At `.claude/agents/tdd-implementer.md`:

```markdown
---
name: tdd-implementer
description: Implement minimal code to pass failing tests for TDD GREEN phase. Write only what the test requires. Returns only after verifying test PASSES.
tools: Read, Glob, Grep, Write, Edit, Bash
---

# TDD Implementer (GREEN Phase)

Implement the minimal code needed to make the failing test pass.

## Process

1. Read the failing test to understand what behavior it expects
2. Identify the files that need changes
3. Write the minimal implementation to pass the test
4. Run `pnpm test:unit <test-file>` to verify it passes
5. Return implementation summary and success output

## Principles

- **Minimal**: Write only what the test requires
- **No extras**: No additional features, no "nice to haves"
- **Test-driven**: If the test passes, the implementation is complete
- **Fix implementation, not tests**: If the test fails, fix your code

## Return Format

Return:
- Files modified with brief description of changes
- Test success output
- Summary of the implementation
```

## The Refactorer Agent (REFACTOR Phase)

At `.claude/agents/tdd-refactorer.md`:

```markdown
---
name: tdd-refactorer
description: Evaluate and refactor code after TDD GREEN phase. Improve code quality while keeping tests passing. Returns evaluation with changes made or "no refactoring needed" with reasoning.
tools: Read, Glob, Grep, Write, Edit, Bash
skills: vue-composables
---

# TDD Refactorer (REFACTOR Phase)

Evaluate the implementation for refactoring opportunities and apply improvements while keeping tests green.

## Process

1. Read the implementation and test files
2. Evaluate against refactoring checklist
3. Apply improvements if beneficial
4. Run `pnpm test:unit <test-file>` to verify tests still pass
5. Return summary of changes or "no refactoring needed"

## Refactoring Checklist

Evaluate these opportunities:

- **Extract composable**: Reusable logic that could benefit other components
- **Simplify conditionals**: Complex if/else chains that could be clearer
- **Improve naming**: Variables or functions with unclear names
- **Remove duplication**: Repeated code patterns
- **Thin components**: Business logic that should move to composables

## Decision Criteria

Refactor when:
- Code has clear duplication
- Logic is reusable elsewhere
- Naming obscures intent
- Component contains business logic

Skip refactoring when:
- Code is already clean and simple
- Changes would be over-engineering
- Implementation is minimal and focused

## Return Format

If changes made:
- Files modified with brief description
- Test success output confirming tests pass
- Summary of improvements

If no changes:
- "No refactoring needed"
- Brief reasoning (e.g., "Implementation is minimal and focused")
```

This agent has a **decision framework** for whether to refactor. Sometimes "no refactoring needed" is the right answer. The `skills` field references my `vue-composables` skill so it knows my project's patterns for extracting reusable logic.

## Real Example: Adding Workout Detail View

Here's what this looks like in practice. My request:

> "When a user is on the Workouts page, they should be able to click on a past workout and see a detail view of what exercises and sets they completed."

The workflow executes like this:

```mermaid
sequenceDiagram
    participant U as User
    participant S as TDD Skill
    participant TW as Test Writer
    participant I as Implementer
    participant R as Refactorer

    U->>S: "Add workout detail view"
    S->>TW: Feature requirement
    TW->>TW: Write test
    TW->>TW: Run test
    TW-->>S: ❌ Test fails
    S->>I: Test file path
    I->>I: Write minimal code
    I->>I: Run test
    I-->>S: ✅ Test passes
    S->>R: Implementation files
    R->>R: Evaluate code
    R->>R: Extract composable
    R->>R: Run test
    R-->>S: ✅ Improvements applied
    S-->>U: 🔴→🟢→🔵 Complete
```

### 🔴 RED Phase

The `tdd-test-writer` produced:

```typescript
// src/__tests__/integration/workout-detail.spec.ts
describe('Workout History Detail View', () => {
  afterEach(async () => {
    // cleanup
  })

  it('navigates to detail view when clicking a completed workout', async () => {
    // Arrange: Create a completed workout
    const completedWorkout = {
      id: generateId(),
      name: 'Push Day',
      exercises: [{
        name: 'Bench Press',
        sets: [{ kg: '100', reps: '10' }]
      }],
      completedAt: Date.now(),
    }
    await db.workouts.add(completedWorkout)

    // Act: Navigate and click
    const app = await createTestApp()
    await app.user.click(app.getByRole('button', { name: /workouts/i }))
    await app.user.click(await app.findByText('Push Day'))

    // Assert
    expect(app.router.currentRoute.value.path)
      .toBe(`/workouts/${completedWorkout.id}`)
    expect(app.getByText('Bench Press')).toBeDefined()
    expect(app.getByText('100')).toBeDefined()

    app.cleanup()
  })
})
```

The test failed:
```
AssertionError: expected '/workouts' to be '/workouts/d747077d-...'
```

Exactly what I wanted—a clear failure pointing to missing functionality.

### 🟢 GREEN Phase

The `tdd-implementer` created:
* `WorkoutDetailView.vue` — New detail view component
* Modified `TheWorkoutsView.vue` — Added click handlers
* Modified `router/index.ts` — Added `/workouts/:id` route

Test passed. Minimal implementation, just enough to satisfy the assertions.

### 🔵 REFACTOR Phase

The `tdd-refactorer` evaluated the code and made improvements:
* **Extracted <InternalLink slug="how-to-test-vue-composables">`useWorkoutDetail` composable</InternalLink>** — Reusable data fetching with discriminated union states
* **Created shared formatters** — Pulled `formatDuration` and `formatDate` into `lib/formatters.ts`
* **Added accessibility** — Keyboard navigation for clickable cards

All tests still passed. The cycle completed.

## The Test Helper

A crucial piece making all this work is my `createTestApp()` helper:

```typescript
// src/__tests__/helpers/createTestApp.ts
export async function createTestApp(): Promise<TestApp> {
  const pinia = createPinia()
  const router = createRouter({
    history: createMemoryHistory(),
    routes,
  })

  render(App, {
    global: { plugins: [router, pinia] },
  })

  await router.isReady()

  return {
    router,
    user: userEvent.setup(),
    getByRole: screen.getByRole,
    getByText: screen.getByText,
    findByText: screen.findByText,
    waitForRoute: (pattern) => waitFor(() => {
      if (!pattern.test(router.currentRoute.value.path)) {
        throw new Error('Route mismatch')
      }
    }),
    cleanup: () => { document.body.innerHTML = '' },
  }
}
```

This gives agents a consistent API for rendering the full app and simulating user interactions. They don't need to figure out how to set up Vue, Pinia, and Vue Router each time—they just call `createTestApp()` and start writing assertions.

## Hooks for Consistent Skill Activation

Even with well-written skills, Claude sometimes skipped evaluation and jumped straight to implementation. I tracked this informally—skill activation happened maybe 20% of the time.

I found a great solution in [Scott Spence's post on making skills activate reliably](https://scottspence.com/posts/how-to-make-claude-code-skills-activate-reliably). He tested 200+ prompts across different hook configurations and found that a "forced eval" approach—making Claude explicitly evaluate each skill before proceeding—jumped activation from ~20% to ~84%.

The fix: **<InternalLink slug="claude-code-notification-hooks">hooks</InternalLink>**. Claude Code runs hooks at specific lifecycle points, and I used `UserPromptSubmit` to inject a reminder before every response.

In `.claude/settings.json`:

```json
{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "npx tsx \"$CLAUDE_PROJECT_DIR/.claude/hooks/user-prompt-skill-eval.ts\"",
            "timeout": 5
          }
        ]
      }
    ]
  }
}
```

The hook script at `.claude/hooks/user-prompt-skill-eval.ts`:

```typescript
#!/usr/bin/env npx tsx
function main(): void {
  readFileSync(0, 'utf-8') // consume stdin

  const instruction = `
INSTRUCTION: MANDATORY SKILL ACTIVATION SEQUENCE

Step 1 - EVALUATE:
For each skill in <available_skills>, state: [skill-name] - YES/NO - [reason]

Step 2 - ACTIVATE:
IF any skills are YES → Use Skill(skill-name) tool for EACH relevant skill NOW
IF no skills are YES → State "No skills needed" and proceed

Step 3 - IMPLEMENT:
Only after Step 2 is complete, proceed with implementation.

CRITICAL: You MUST call Skill() tool in Step 2. Do NOT skip to implementation.
`

  stdout.write(instruction.trim())
}

main()
```

<Alert type="important" title="Results">
  With this hook, skill activation jumped from ~20% to ~84%. Now when I say "implement the workout detail view," the TDD skill triggers automatically.
</Alert>

## Conclusion

Claude Code's default behavior produces implementation-first code with minimal test coverage. Without constraints, it optimizes for "working code" rather than "tested code."

The system described here addresses this through architectural separation:

* **Hooks** inject evaluation logic before every prompt, increasing skill activation from ~20% to ~84%
* **Skills** define explicit phase gates that block progression until each TDD step completes
* **Subagents** enforce context isolation—the test writer cannot see implementation plans, so tests reflect actual requirements rather than anticipated code structure

The setup cost is ~2 hours of configuration. After that, each feature request automatically follows the Red-Green-Refactor cycle without manual enforcement.

---

--- title: Claude Code Notifications: Get Alerts When Tasks Finish (Hooks Setup) description: How to set up Claude Code notifications using hooks. Get desktop alerts when Claude finishes a task, needs your input, or requests permission, instead of watching the terminal. tags: ['claude-code', 'notifications', 'hooks', 'automation'] url: https://alexop.dev/posts/claude-code-notification-hooks ---

# Claude Code Notifications: Get Alerts When Tasks Finish (Hooks Setup)



You're deep in your work. Claude Code is running, doing its thing. You check back five minutes later. Still waiting. Ten minutes later? Still waiting.

Wouldn't it be nice to know *when* Claude actually needs you?

This is where hooks come in. <InternalLink slug="understanding-claude-code-full-stack">Claude Code runs hooks</InternalLink> at specific points in its workflow. You can tap into those hooks to send yourself desktop notifications—so you never miss an important moment.

But here's the thing—if you've never used hooks before, they might sound abstract. Let me break it down.

## What Are Hooks?

Hooks are commands that run at specific points in Claude Code's lifecycle. They let you respond to events without constantly watching the CLI. Instead of polling, you get notified.

Claude Code provides two notification hooks:
- **`permission_prompt`** - Claude needs your permission to do something
- **`idle_prompt`** - Claude is waiting for your input

Think of them like webhooks, but for your local machine. Claude Code fires an event, you can respond.

## Setting Up Desktop Notifications

Now let's get this working. It's straightforward—just two pieces: a configuration file and a notification script.

Start by creating a `.claude/hooks` directory in your project. Then add the hook configuration to `.claude/settings.json`:

```json
{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt|idle_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "npx tsx \"$CLAUDE_PROJECT_DIR/.claude/hooks/notification-desktop.ts\"",
            "timeout": 5
          }
        ]
      }
    ]
  }
}
```

This tells Claude Code: "When you hit a `permission_prompt` or `idle_prompt`, run this command." The `timeout: 5` means the hook has 5 seconds to complete before Claude moves on.

You can place this in two locations:
- `.claude/settings.json` - Project-specific (checked into git, shared with team)
- `~/.claude/settings.json` - Global user settings (personal machine only)

Use project-specific settings for team hooks, global settings for personal notifications. The `$CLAUDE_PROJECT_DIR` is an environment variable Claude Code provides—it expands to your project root automatically.

Here's what your project structure should look like:

<FileTree tree={[
  { name: 'your-project', children: [
    { name: '.claude', children: [
      { name: 'settings.json', comment: 'Hook configuration' },
      { name: 'hooks', children: [
        { name: 'notification-desktop.ts', comment: 'Notification script' }
      ], open: true }
    ], open: true },
    { name: 'src', comment: '...' },
    { name: 'package.json', comment: '...' }
  ], open: true }
]} />

## The Notification Script

Create `.claude/hooks/notification-desktop.ts`. This script handles sending the actual notifications:

```typescript
#!/usr/bin/env npx tsx
/* eslint-disable node/prefer-global/process */
/**
 * Claude Code Notification Hook - Desktop Alerts
 *
 * Sends system notifications when Claude needs attention:
 * - Permission prompts
 * - Idle prompts (waiting for input)
 */

function readStdin(): string {
  return readFileSync(0, 'utf-8')
}

function sendMacNotification(title: string, message: string): void {
  // Escape special characters for AppleScript
  const escapedTitle = title.replace(/"/g, '\\"')
  const escapedMessage = message.replace(/"/g, '\\"')

  const script = `display notification "${escapedMessage}" with title "${escapedTitle}" sound name "Ping"`

  try {
    execSync(`osascript -e '${script}'`, { stdio: 'ignore' })
  }
  catch {
    // Notification failed, ignore silently
  }
}

function main(): void {
  const rawInput = readStdin()

  let parsedInput: unknown
  try {
    parsedInput = JSON.parse(rawInput)
  }
  catch {
    process.exit(0)
  }

  const input = parsedInput as NotificationHookInput

  const notificationType = (input as { notification_type?: string }).notification_type
  const message = input.message

  switch (notificationType) {
    case 'permission_prompt':
      sendMacNotification('Claude Code - Permission Required', message || 'Claude needs your permission to continue')
      break
    case 'idle_prompt':
      sendMacNotification('Claude Code - Waiting', message || 'Claude is waiting for your input')
      break
    default:
      // Don't notify for other types
      break
  }

  process.exit(0)
}

main()

```

## When This Really Shines

You've set up the basics. Now here's where it becomes powerful.

This notification system is especially useful when you're doing deep focus work and Claude Code runs a long operation. You don't have to check your terminal every few seconds. Permission prompts that need immediate action? They hit you with a different sound. Idle waits while you've stepped away? A gentle reminder pulls you back.

The key is this: the notification comes exactly when you need to be engaged. No sooner, no later.

Want to go deeper? You can even <InternalLink slug="building-my-first-claude-code-plugin">build custom plugins that use hooks</InternalLink> across different projects for more powerful automation.

## Conclusion

Hooks transform Claude Code from a tool you watch into a tool that watches for you.
The setup takes maybe five minutes. Copy the configuration, create the script, adjust the sounds to your preference. After that, you're done. No more context switching. No more glancing at the terminal every few seconds wondering if Claude needs you. The notification arrives exactly when it matters.
That's the real power here. It's not about automating notifications. It's about reclaiming your focus—letting Claude Code work while you work, and pulling your attention back only when it's needed. Set it up once, and you've unlocked a better way to collaborate with AI.

---

--- title: Claude Code Slash Commands: A Complete Guide (2026) description: Learn how to transform Claude Code from a chatbot into a deterministic engine using Slash Commands. This guide covers the technical setup and a complete 'Full Circle' workflow that automates your entire feature lifecycle. tags: ['ai', 'claude-code'] url: https://alexop.dev/posts/claude-code-slash-commands-guide ---

# Claude Code Slash Commands: A Complete Guide (2026)



I was wasting time. Every commit message, every branch name, every PR description. I typed the same things over and over.
Then I discovered Slash Commands in Claude Code. Now I type `/commit` and it writes the message for me. `/branch "add dark mode"` and it creates `feat/add-dark-mode`. `/pr` and it generates a full PR description from my commits.
This post shows you how to build the same workflow. I'll cover how Slash Commands work, then we'll build a complete system that automates your entire git lifecycle.

<Aside type="tip" title="Related Reading">
Slash Commands are just one piece of the Claude Code puzzle. For the full picture—including MCP, hooks, subagents, and skills—see my <InternalLink slug="understanding-claude-code-full-stack">comprehensive guide to Claude Code's feature stack</InternalLink>.
</Aside>

<Alert type="important" title="Prerequisites">
You need Git and the GitHub CLI (`gh`). Install `gh` with `brew install gh` on macOS or check [cli.github.com](https://cli.github.com). Run `gh auth login` to authenticate.

Without `gh`, commands like `/pr` and `/fix-pipeline` will not work.
</Alert>

## Two things you need to know

Before we build the workflow, you need to understand two features.

### Bash command execution

Write `!git status` inside a command file. Claude runs the command first, captures the output, and injects it into the prompt. The AI sees the result before it starts thinking.

This is how `/commit` knows what you changed. It runs `!git diff` automatically. See the [official documentation](https://docs.anthropic.com/en/docs/claude-code/slash-commands#bash-command-execution) for more details.

### Model selection

You don't need a powerful model to fix a missing semicolon.
Claude Code lets you pick the model in the frontmatter:

- `sonnet` — for complex reasoning (default)
- `haiku` — fast and cheap

Add `model: haiku` and commands run almost instantly.

## Command structure

Slash commands are Markdown files stored in `.claude/commands/` (project-level) or `~/.claude/commands/` (personal). The filename becomes the command name: `commit.md` becomes `/commit`.

<FileTree
  tree={[
    {
      name: "my-project",
      open: true,
      children: [
        {
          name: ".claude",
          open: true,
          children: [
            { name: "settings.json", comment: "project settings" },
            {
              name: "commands",
              open: true,
              children: [
                { name: "branch.md", comment: "/branch" },
                { name: "commit.md", comment: "/commit" },
                { name: "pr.md", comment: "/pr" },
                { name: "lint.md", comment: "/lint" },
              ],
            },
          ],
        },
        { name: "src" },
        { name: "package.json" },
      ],
    },
  ]}
/>

Here is a complete example:

```markdown
---
description: Create a git commit with a conventional message
allowed-tools: Bash(git add:*), Bash(git commit:*)
argument-hint: [message]
model: haiku
---

# Commit Changes

<git_diff>
!`git diff --cached`
</git_diff>

Create a commit message following Conventional Commits.
If $ARGUMENTS is provided, use it as the commit message.
```

### Frontmatter options

| Option | Purpose | Default |
|--------|---------|---------|
| `description` | Brief description shown in `/help` | First line of prompt |
| `allowed-tools` | Tools the command can use | Inherits from conversation |
| `model` | Model to use (`sonnet`, `haiku`, or full model ID) | Inherits from conversation |
| `argument-hint` | Shows expected arguments in autocomplete | None |

### Arguments

Use `$ARGUMENTS` to capture everything passed to the command:

```markdown
Create a branch named: $ARGUMENTS
```

For multiple arguments, use positional parameters `$1`, `$2`, etc:

```markdown
---
argument-hint: [pr-number] [priority]
---

Review PR #$1 with priority $2.
```

### File references

Include file contents with the `@` prefix:

```markdown
Review the implementation in @src/utils/helpers.js
```

## The workflow

I replaced my manual git rituals with custom commands. They live in `.claude/commands/`. Here is how I drive a feature from start to merge.

```mermaid
---
title: Development Workflow
---
flowchart LR
    %% Initial Setup
    Start((Start)) --> Branch["/branch"]
    Branch --> Code[Write Code]

    %% Local Iteration Loop
    Code --> Lint["/lint<br/>(Haiku)"]
    Lint -- "Auto-fix" --> Lint
    Lint --> Test["/vitest<br/>(Haiku)"]
    Test -- "Fix Failure" --> Test
    
    %% Deployment Flow
    Test --> Push["/push"]
    Push --> PR["/pr"]
    PR --> CI{CI Pass?}

    %% CI Debugging Loop
    CI -- "No" --> Fix["/fix-pipeline<br/>(Sonnet)"]
    Fix -- "Fix & Push" --> CI

    %% Final Review & Merge
    CI -- "Yes" --> Review["/review-coderabbit"]
    Review --> Merge["/merge-to-main"]
    Merge --> Done((Done))
```

### /branch — start a task

<PromptLink href="/prompts/claude/claude-branch-command">
I type `/branch "implement dark mode toggle"` and Claude checks out main, pulls latest, and creates `feat/dark-mode-toggle`. No more thinking about naming conventions.
</PromptLink>

### /lint — fix before commit

<PromptLink href="/prompts/claude/claude-lint-command">
I type `/lint`. It runs the linter with auto-fix, and if errors remain, Claude fixes them. Uses Haiku for speed—runs in about 20 seconds.
</PromptLink>

### /vitest — run unit tests

<PromptLink href="/prompts/claude/claude-vitest-command">
I type `/vitest`. It runs the test suite and fixes any failures. The prompt tells Claude to fix the code, not the test—implementation should match expected behavior.
</PromptLink>

### /commit — save your work

<PromptLink href="/prompts/claude/claude-commit-command">
I type `/commit`. Claude analyzes the diff, generates a Conventional Commit message, and commits. It looks at recent commits to match your project's style.
</PromptLink>

### /push — commit and push in one step

<PromptLink href="/prompts/claude/claude-push-command">
I type `/push`. It stages everything, generates a commit message, commits, and pushes. My most-used command—one word and the code is on GitHub.
</PromptLink>

### /fix-pipeline — fix failing CI tests

<PromptLink href="/prompts/claude/claude-fix-pipeline-command">
I type `/fix-pipeline`. It fetches the failed logs via `gh`, analyzes the error, and fixes it. Uses Sonnet because debugging requires reasoning. The prompt includes guardrails—Claude must read the actual error before proposing fixes.
</PromptLink>

### /pr — create a pull request

<PromptLink href="/prompts/claude/claude-pr-command">
I type `/pr`. It analyzes all commits on the branch, generates a PR title and description, and opens it via `gh pr create`. Checks if a PR already exists first.
</PromptLink>

### /review-coderabbit — address review comments

<PromptLink href="/prompts/claude/claude-review-coderabbit-command">
I type `/review-coderabbit`. It fetches CodeRabbit's comments via GraphQL, verifies each suggestion against the codebase, implements valid fixes or pushes back with reasoning, and resolves every thread. AI reviewers aren't always right—the prompt ensures Claude verifies before acting.
</PromptLink>

### /merge-to-main — finish the task

<PromptLink href="/prompts/claude/claude-merge-to-main-command">
I type `/merge-to-main`. It squash merges the PR, deletes the branch, and pulls main. Done.
</PromptLink>

## Summary

By moving your process into `.claude/commands/`, you are building a system.

- Bash command execution injects real-time context
- Model selection balances speed vs reasoning
- The workflow automates branching, linting, committing, CI debugging, PRs, and merging

Define the process once. Claude executes it every time.

Want to extend Claude Code even further? Connect external tools via <InternalLink slug="what-is-model-context-protocol-mcp">MCP (Model Context Protocol)</InternalLink> or package your commands into a <InternalLink slug="building-my-first-claude-code-plugin">shareable plugin</InternalLink>.

I don't think about naming conventions, commit messages, or PR descriptions anymore. The commands handle it.

<Alert type="tip" title="Bonus: Shell aliases for even faster execution">
You can skip the interactive prompt entirely with `claude -p`. Add aliases to your `.zshrc` or `.bashrc`:

```bash
alias clint="claude -p '/lint'"
alias cpush="claude -p '/push'"
alias ccommit="claude -p '/commit'"
alias cbranch="claude -p '/branch'"
```

Now `clint` runs the lint command without opening the interactive session. The `-p` flag passes the prompt directly—Claude executes and exits. Two steps become one keystroke.
</Alert>

---

--- title: Claude Code Explained (2026): MCP, Skills, Subagents, Hooks & Plugins description: A practical guide to Claude Code's features: MCP, CLAUDE.md, slash commands, subagents, hooks, plugins, skills, and scheduled tasks. Updated April 2026 with deferred tool loading, worktree isolation, agent teams, and more. tags: ['claude-code', 'ai', 'mcp', 'productivity', 'tooling'] url: https://alexop.dev/posts/understanding-claude-code-full-stack ---

# Claude Code Explained (2026): MCP, Skills, Subagents, Hooks & Plugins



I used Claude Code for months as a glorified autocomplete. Quick edits. Boilerplate. The vibe coding tool.

Then I dug into MCP servers, slash commands, plugins, skills, hooks, subagents, and CLAUDE.md files. Claude Code is a framework for orchestrating AI agents, and most people use one or two features without seeing how they stack together. (It also runs in more places now: CLI, VS Code, JetBrains, a standalone desktop app, a web app at claude.ai/code, and iOS.)

This guide explains each concept **in the order they build on each other**, from external connections to automatic behaviors. (New to using LLMs for development? Start with my <InternalLink slug="how-i-use-llms">overview of how I use LLMs</InternalLink> for context.)

> Claude Code is, with hindsight, poorly named. It's not purely a coding tool: it's a tool for general computer automation. Anything you can achieve by typing commands into a computer is something that can now be automated by Claude Code. It's best described as a general agent. Skills make this a whole lot more obvious and explicit.
>
> — Simon Willison, [Claude Skills are awesome, maybe a bigger deal than MCP](https://simonwillison.net/2025/Oct/16/claude-skills/)

<TLDR
  items={[
    "CLAUDE.md files give Claude project memory and context",
    "Skills are the unified extensibility model — commands and skills are now one thing",
    "Subagents handle parallel work in isolated contexts",
    "Hooks react to lifecycle events without manual triggering",
    "Plugins bundle commands, hooks, and skills for sharing",
    "MCP connects external tools through a universal protocol",
    "Skills activate based on task context",
    "Scheduled tasks run Claude on a cron schedule without you present",
  ]}
/>

## The feature stack

1. **Model Context Protocol (MCP)** — the foundation for connecting external tools and data sources
2. **Claude Code core features** — project memory, skills, subagents, and hooks
3. **Plugins** — shareable packages that bundle skills, hooks, and metadata
4. **Skills** — the unified extensibility model (replaces the old command/skill split)
5. **Scheduled Tasks** — cloud-based triggers that run Claude on a cron schedule

<Figure
  src={claudeSenpai}
  caption="Claude Senpai knows all the features!"
  alt="Robot Claude Senpai with a knowing expression"
  size="medium"
/>

---

## 1) Model Context Protocol (MCP) — connecting external systems

```mermaid
sequenceDiagram
    actor User
    participant Claude
    participant MCPServer

    User->>Claude: /mcp connect github
    Claude->>MCPServer: Authenticate + request capabilities
    MCPServer-->>Claude: Return tools/resources/prompts
    Claude-->>User: Display /mcp__github__* commands
```

**What it is.** The <InternalLink slug="what-is-model-context-protocol-mcp">Model Context Protocol</InternalLink> connects Claude Code to external tools and data sources. Think universal adapter for GitHub, databases, APIs, and other systems.

**How it works.** Connect an MCP server, get access to its tools, resources, and prompts as slash commands:

```bash
# Install a server
claude mcp add playwright npx @playwright/mcp@latest

# Use it
/mcp__playwright__create-test [args]
```

<Alert type="info" title="Deferred Tool Loading (2026)">
  Claude Code no longer loads full MCP tool schemas at startup. It loads tool names only, then fetches the full schema on demand via `ToolSearch`. If you run 50+ MCP tools, this cuts context overhead by an order of magnitude. Monitor remaining usage with `/context`.
</Alert>

**Remote servers.** The MCP spec added streamable HTTP transport (replacing SSE) and OAuth 2.1 with PKCE for authentication. You can now connect to remote MCP servers without running a local stdio process.

**The gotcha.** MCP servers expose their own tools. They don't inherit Claude's Read, Write, or Bash unless you provide them.

**Real-world example.** Want to see MCP in action? Check out how to <InternalLink slug="building_ai_qa_engineer_claude_code_playwright">build an AI QA engineer with Playwright MCP</InternalLink> that tests your app like a real user.

---

## 2) Claude Code core features

### 2.1) Project memory with `CLAUDE.md`

**What it is.** Markdown files Claude loads at startup. They give Claude memory about your project's conventions, architecture, and patterns.

**How it works.** Files merge hierarchically from enterprise → user (`~/.claude/CLAUDE.md`) → project (`./CLAUDE.md`). When you reference `@components/Button.vue`, Claude also reads CLAUDE.md from that directory and its parents.

Two additions since launch: `CLAUDE.local.md` files sit alongside `CLAUDE.md` but are gitignored, so you can add personal preferences without affecting the team. And `~/.claude/rules/` lets you split global instructions into separate files instead of one large `~/.claude/CLAUDE.md`.

**Example structure for a Vue app:**

<FileTree
  tree={[
    {
      name: "my-vue-app",
      open: true,
      children: [
        {
          name: "CLAUDE.md",
          comment: "Project-wide conventions, tech stack, build commands",
        },
        {
          name: "src",
          open: true,
          children: [
            {
              name: "components",
              open: true,
              children: [
                {
                  name: "CLAUDE.md",
                  comment: "Component patterns, naming conventions, prop types",
                },
                { name: "Button.vue" },
                { name: "Card.vue" },
              ],
            },
            {
              name: "pages",
              open: true,
              children: [
                {
                  name: "CLAUDE.md",
                  comment: "Routing patterns, page structure, data fetching",
                },
                { name: "Home.vue" },
                { name: "About.vue" },
              ],
            },
          ],
        },
      ],
    },
  ]}
/>

When you work on `src/components/Button.vue`, Claude loads context from:

1. Enterprise CLAUDE.md (if configured)
2. User `~/.claude/CLAUDE.md` (personal preferences)
3. Project root `CLAUDE.md` (project-wide info)
4. `src/components/CLAUDE.md` (component-specific patterns)

**What goes in.** Common commands, coding standards, architectural patterns. Keep it concise — reference guide, not documentation. Need help creating your own? Check out this [CLAUDE.md creation guide](/prompts/claude/claude-create-md).

Here's my blog's CLAUDE.md:

````markdown
# CLAUDE.md

## Project Overview

Alexander Opalic's personal blog built on AstroPaper - Astro-based blog theme with TypeScript, React, TailwindCSS.

**Tech Stack**: Astro 5, TypeScript, React, TailwindCSS, Shiki, FuseJS, Playwright

## Development Commands

```bash
npm run dev              # Build + Pagefind + dev server (localhost:4321)
npm run build            # Production build
npm run lint             # ESLint for .astro, .ts, .tsx
---
```
````

### 2.2) Skills — the unified extensibility model

```mermaid
graph LR
    Skill["SKILL.md"]
    Auto["Claude auto-invokes<br/>(description matches task)"]
    Manual["User invokes<br/>(/skill-name args)"]
    Fork{"context: fork?"}
    Main["Run in main context"]
    Sub["Run in subagent"]

    Skill --> Auto
    Skill --> Manual
    Auto --> Fork
    Manual --> Fork
    Fork -->|no| Main
    Fork -->|yes| Sub
```

<Alert type="info" title="Commands and Skills Are Now One Thing">
  As of 2026, slash commands and skills are unified. Files in `.claude/commands/` still work, but the recommended approach is `.claude/skills/`. Every skill gets a `/slash-command` interface. Frontmatter controls whether Claude can auto-invoke it, whether users see it in the `/` menu, and whether it runs in a subagent.
</Alert>

**What they are.** Folders with a `SKILL.md` file (plus optional helper scripts) that define reusable behaviors. Frontmatter controls invocation: Claude can auto-invoke based on task context, you can trigger manually with `/skill-name`, or both.

**Key frontmatter fields:**

| Field | Purpose |
|-------|---------|
| `name` | Display name, becomes `/slash-command`. Lowercase, hyphens, max 64 chars. Defaults to directory name. |
| `description` | What the skill does. Claude uses this to decide auto-invocation. |
| `disable-model-invocation` | Set `true` to prevent Claude from auto-invoking (deploy, commit). |
| `user-invocable` | Set `false` to hide from `/` menu (background knowledge only). |
| `allowed-tools` | Tools Claude can use without asking. |
| `context` | Set to `fork` to run in an isolated subagent context. |
| `agent` | Subagent type when `context: fork` is set (`Explore`, `Plan`, `general-purpose`). |
| `model` | Model override (`haiku`, `sonnet`, `opus`). |
| `argument-hint` | Hint for expected arguments, shown in autocomplete. |
| `paths` | Glob patterns limiting when skill auto-loads (e.g., `src/**/*.ts`). |

**Argument substitution:** `$ARGUMENTS` for all args, `$0`, `$1`, `$2` for positional, `${CLAUDE_SKILL_DIR}` for the skill's directory.

**Key features:**

- `@file` syntax to inline code
- `allowed-tools: Bash(...)` for pre-execution scripts
- <InternalLink slug="xml-tagged-prompts-framework-reliable-ai-responses">
    XML-tagged prompts
  </InternalLink>
  for reliable outputs

**When to use.** Repeatable workflows, domain expertise, automated enforcement. For a complete example of a git workflow built with skills, see my <InternalLink slug="claude-code-slash-commands-guide">Slash Commands Guide</InternalLink>. Want to create your own? Use this [skill creation guide](/prompts/claude/claude-create-skill).

**Example: a deploy skill that only you can trigger:**

```markdown
---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
allowed-tools: Bash(npm:*), Bash(git:*)
---

Deploy to production:
1. Run tests
2. Build
3. Push to deployment target
```

This creates `/deploy` that **only you can invoke** — Claude cannot auto-trigger it.

**Example: a skill that runs in a subagent:**

```markdown
---
name: deep-research
description: Research a topic thoroughly
context: fork
agent: Explore
allowed-tools: Read, Grep, Glob
---

Research $ARGUMENTS thoroughly. Find relevant files, read and analyze them, summarize findings.
```

When invoked, this spawns a separate context window. Your main conversation stays clean.

---

### 2.3) Subagents — specialized AI personalities for delegation

```mermaid
sequenceDiagram
    participant Main
    participant SubA
    participant SubB

    Main->>SubA: task: security analysis
    Main->>SubB: task: test generation
    par Parallel execution
        SubA-->>Main: results
        SubB-->>Main: results
    end
```

**What they are.** Pre-configured AI personalities with specific expertise areas. Each subagent has its own system prompt, allowed tools, and separate context window. Claude delegates to them when a task matches their expertise.

**Why use them.** Keep your main conversation clean while offloading specialized work. Each subagent works in its own context window, preventing token bloat. Run multiple subagents in parallel for concurrent analysis.

<Alert type="tip" title="Avoiding Context Poisoning">
  Subagents prevent "context poisoning" — when detailed implementation work
  clutters your main conversation. Use subagents for deep dives (security
  audits, test generation, refactoring) that would otherwise fill your primary
  context with noise.
</Alert>

**Example structure:**

```markdown
---
name: security-auditor
description: Analyzes code for security vulnerabilities
tools: Read, Grep, Bash # Controls what this personality can access
model: sonnet # Optional: sonnet, opus, haiku, inherit
---

You are a security-focused code auditor.

Identify vulnerabilities (XSS, SQL injection, CSRF, etc.)
Check dependencies and packages
Verify auth/authorization
Review data validation

Provide severity levels: Critical, High, Medium, Low.
Focus on OWASP Top 10.
```

The system prompt shapes the subagent's behavior. The `description` tells Claude when to delegate. The `tools` field restricts access.

**Best practices:** One expertise area per subagent. Minimal tool access. Use `haiku` for simple tasks, `sonnet` for complex analysis. Run independent work in parallel. Need a template? Check out this [subagent creation guide](/prompts/claude/claude-create-agent).

<Alert type="info" title="Worktree Isolation (2026)">
  Set `isolation: worktree` to give a subagent its own git worktree. Each subagent works on an isolated copy of the repo, so multiple subagents can edit files in parallel without conflicts. The worktree is cleaned up if no changes are made; if the subagent produces changes, you get the worktree path and branch back.
</Alert>

Claude also ships three built-in subagent types you can use without writing a config file: **Explore** (fast, read-only, uses Haiku), **Plan** (research and architecture, read-only), and **General-purpose** (full tool access).

<Alert type="tip" title="Agent Teams vs Subagents">
  Subagents report to a parent. Agent teams are different: multiple Claude sessions that coordinate as peers, messaging each other and sharing tasks. Think of subagents as delegation and agent teams as collaboration.
</Alert>

---

### 2.4) Hooks — automatic event-driven actions

```mermaid
graph TD
    Event[Lifecycle Event]
    HookA[Hook 1]
    HookB[Hook 2]
    HookC[Hook 3]

    Event --> HookA
    Event --> HookB
    Event --> HookC
```

**What they are.** JSON-configured handlers in `.claude/settings.json` that trigger on lifecycle events. No manual invocation.

**Available events** (expanded from the original 7):

- **Tool lifecycle:** `PreToolUse`, `PostToolUse`
- **Session lifecycle:** `SessionStart`, `Stop`, `SubagentStart`, `SubagentStop`
- **Task lifecycle:** `TaskCreated`, `TaskCompleted`
- **Environment:** `CwdChanged`, `FileChanged`
- **Permissions:** `PermissionDenied`
- **Context:** `PreCompact`, `PostCompact`
- **User input:** `UserPromptSubmit`, `Notification`

**Handler types:**

- **Command:** Run shell commands (fast, predictable)
- **Prompt:** Let Claude decide with the LLM (flexible, context-aware)
- **HTTP:** POST JSON to an external service with auth headers
- **Async:** Add `"async": true` to run a hook in the background without blocking

PreToolUse hooks can also return `updatedInput` to modify tool arguments before execution.

**Example:** Auto-lint after file edits.

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/run-oxlint.sh"
          }
        ]
      }
    ]
  }
}
```

```bash
#!/usr/bin/env bash
file_path="$(jq -r '.tool_input.file_path // ""')"

if [[ "$file_path" =~ \.(js|jsx|ts|tsx|vue)$ ]]; then
  pnpm lint:fast
fi
```

**Common uses:** Auto-format after edits, require approval for bash commands, validate writes, initialize sessions. For a practical example, see how to <InternalLink slug="claude-code-notification-hooks">set up desktop notifications</InternalLink> when Claude needs your attention. Want to build your own? Use this [hook creation guide](/prompts/claude/claude-create-hook).

---

## 3) Plugins — shareable, packaged configurations

```mermaid
classDiagram
    class Plugin {
      name
      version
      author
    }
    Plugin --> Skills
    Plugin --> Hooks
```

**What they are.** Distributable bundles of skills, hooks, and metadata. Share your setup with teammates or install pre-built configurations.

**Basic structure:**

<FileTree
  tree={[
    {
      name: "my-plugin",
      open: true,
      children: [
        {
          name: ".claude-plugin",
          open: true,
          children: [
            { name: "plugin.json", comment: "Manifest: name, version, author" },
          ],
        },
        {
          name: "skills",
          children: [
            { name: "greet", children: [{ name: "SKILL.md" }] },
            { name: "my-skill", children: [{ name: "SKILL.md" }] },
          ],
        },
        { name: "hooks", children: [{ name: "hooks.json" }] },
      ],
    },
  ]}
/>

**When to use.** Share team configurations, <InternalLink slug="building-my-first-claude-code-plugin">package domain workflows</InternalLink>, distribute opinionated patterns, install community tooling.

**How it works.** Install a plugin, get instant access. Hooks combine, skills appear in autocomplete and activate on context match. Ready to build your own? Check out this [plugin creation guide](/prompts/claude/claude-create-plugin).

---

## 4) Skills deep dive — where to put them and how they compose

Skills were covered in section 2.2. This section focuses on discovery, placement, and composition patterns.

**How Claude discovers skills.** When you give Claude a task, it reviews available skill descriptions to find relevant ones. If a skill's `description` field matches the task context, Claude loads the full instructions. You don't need to invoke auto-invoked skills by name — Claude finds them.

<Alert type="info" title="Official Example Skills">
  Check out the [official Anthropic skills
  repository](https://github.com/anthropics/skills) for ready-to-use examples.
</Alert>

> Claude Skills are awesome, maybe a bigger deal than MCP
>
> — Simon Willison, [Claude Skills are awesome, maybe a bigger deal than MCP](https://simonwillison.net/2025/Oct/16/claude-skills/)

<Alert type="tip" title="Advanced Skills: Superpowers Library">
Want rigorous, spec-driven development? Check out [obra's superpowers](https://github.com/obra/superpowers) — a comprehensive skills library that enforces systematic workflows.

**What it provides:** TDD workflows (RED-GREEN-REFACTOR), systematic debugging, code review processes, git worktree management, and brainstorming frameworks. Each skill pushes you toward verification-based development instead of "trust me, it works."

**The philosophy:** Test before implementation. Verify with evidence. Debug systematically through four phases. Plan before coding. No shortcuts.

**Use when:** You want Claude to be more disciplined about development practices, especially for production code.

</Alert>

**Where to put them:**

- `~/.claude/skills/` — personal, all projects
- `.claude/skills/` — project-specific
- Inside plugins — distributable

**Skills vs CLAUDE.md.** Skills are modular chunks of a CLAUDE.md file. Instead of reviewing a massive document on every task, Claude loads specific skill instructions only when the task matches. Better context efficiency, same automatic behavior.

**Controlling invocation with frontmatter.** The old command/skill split is gone. A single SKILL.md file with different frontmatter covers every use case:

| Pattern | Frontmatter | Result |
|---------|-------------|--------|
| Auto-invoke only (old "skill") | `description:` set, defaults | Claude invokes when relevant |
| Manual only (old "command") | `disable-model-invocation: true` | Only runs when you type `/name` |
| Background knowledge | `user-invocable: false` | Claude reads it, users don't see it in `/` menu |
| Both auto and manual | `description:` set, `user-invocable: true` | Claude can invoke it, you can too |
| Isolated execution | `context: fork`, `agent: Explore` | Runs in a subagent with its own context |

<Alert type="caution" title="Migrating Old Commands">
Files in `.claude/commands/` still work and appear as `/slash-commands`. But new work should go in `.claude/skills/`. The skill format supports everything commands did, plus auto-invocation, `context: fork`, `paths` filtering, and model overrides.
</Alert>

---

## 5) Scheduled Tasks and Triggers — running Claude without you

**What they are.** Cloud-based cron jobs that run Claude Code on Anthropic's infrastructure. You define a schedule and a prompt; Claude executes it on the cron interval, with full access to your project.

**How to set one up.** Use the `/schedule` command or `claude trigger create` from the CLI. Define the cron expression and the task prompt:

```bash
claude trigger create --schedule "0 9 * * 1" --prompt "Review open PRs and summarize status"
```

**In-session polling.** For shorter-lived recurring work, `/loop 5m /your-command` runs a slash command on an interval inside your current session.

<Alert type="info" title="Channels (Research Preview)">
  Channels let MCP servers push messages into a Claude session. You can connect Telegram, Discord, webhooks, or other services so external events trigger Claude's attention. Still a research preview as of April 2026.
</Alert>

---

## Putting it all together

How these features work together in practice:

1. **Memory (`CLAUDE.md`)** — Establish project context and conventions that Claude always knows
2. **Skills** — Define reusable behaviors, from manual workflows to auto-invoked expertise
3. **Subagents** — Offload parallel or isolated work to specialized agents
4. **Hooks** — Enforce rules and automate repetitive actions at key lifecycle events
5. **Plugins** — Package and distribute your entire setup to others
6. **MCP** — Connect external systems and make their capabilities available as commands
7. **Scheduled Tasks** — Run Claude on a cron schedule for recurring work

### Example: A Task-Based Development Workflow

A real-world workflow that combines multiple features:

**Setup phase:**

- `CLAUDE.md` contains implementation standards ("don't commit until I approve", "write tests first")
- `/load-context` skill (`disable-model-invocation: true`) initializes new chats with project state
- `update-documentation` skill (auto-invoked) activates after implementations
- Hook triggers linting after file edits

**Planning phase (Chat 1):**

- Main agent plans bug fix or new feature
- Outputs detailed task file with approach

**Implementation phase (Chat 2):**

- Start fresh context with `/load-context`
- Feed in the plan from Chat 1
- Implementation subagent executes the plan
- `update-documentation` skill updates docs on its own
- `/resolve-task` skill marks task complete

**Why this works:** Main context stays focused on planning. Heavy implementation work happens in isolated context. Skills handle documentation. Hooks enforce quality standards.

## Decision guide: choosing the right tool

<Alert type="info" title="Community Resource: Claude Code Driver Repository">
  🎉 **Huge thanks to [@thewiredbear](https://github.com/thewiredbear)** for creating the [Claude Code Driver](https://github.com/thewiredbear/Claude_Code_Driver/) repository! This community-driven collection includes examples, templates, and resources based on this guide. Perfect for getting started quickly or finding inspiration for your own Claude Code setup. Check it out and contribute your own patterns!
</Alert>

<Alert type="info" title="Quick Reference Cheat Sheet">
  For a comprehensive visual guide to all Claude Code features, check out the
  [Awesome Claude Code Cheat Sheet](https://awesomeclaude.ai/code-cheatsheet).
</Alert>

<Alert type="tip" title="Customize Your Terminal">
  Want model name, context usage, and cost displayed in your terminal? See how to <InternalLink slug="customize_claude_code_status_line">customize your Claude Code status line</InternalLink>.
</Alert>

<Aside type="tip" title="Quick Reference">

- **Use `CLAUDE.md`** to define lasting project context — architecture, conventions, and patterns Claude should always remember. Best for: static knowledge that rarely changes.
- **Use <InternalLink slug="claude-code-slash-commands-guide">Skills</InternalLink>** for reusable workflows and expertise. Set `disable-model-invocation: true` for manual-only triggers, leave it off for auto-invocation, or use `context: fork` to run in a subagent. Best for: everything from deploy scripts to style enforcement.
- **Use Subagents** when you need parallel execution or want to isolate heavy computational work. Best for: preventing context pollution, specialized deep dives.
- **Use Hooks** to enforce standards or react to specific events. Best for: quality gates, actions tied to tool usage.
- **Use Plugins** to package and share complete configurations across teams or projects. Best for: team standardization, distributing opinionated setups.
- **Use MCP** to integrate external systems and expose their capabilities as native commands. Best for: connecting databases, APIs, third-party tools.
- **Use Scheduled Tasks** for recurring work that should run without you present. Best for: nightly audits, weekly reports, periodic maintenance.

</Aside>

### Feature comparison

<Alert type="info" title="Source">
  This comparison table is adapted from [IndyDevDan's video "I finally CRACKED
  Claude Agent Skills"](https://www.youtube.com/watch?v=kFpLzCVLA20&t=1027s).
</Alert>

| Category            | Skill              | MCP     | Subagent | Trigger  |
| ------------------- | ------------------ | ------- | -------- | -------- |
| Triggered By        | Agent, Engineer, or Both | Both | Both | Schedule |
| Context Efficiency  | High               | Low     | High     | High     |
| Context Persistence | ✅                 | ✅      | ✅       | ❌       |
| Parallelizable      | ✅ (context: fork) | ❌      | ✅       | ✅       |
| Specializable       | ✅                 | ✅      | ✅       | ✅       |
| Sharable            | ✅                 | ✅      | ✅       | ❌       |
| Modularity          | High               | High    | Mid      | Low      |
| Tool Permissions    | ✅                 | ❌      | ✅       | ✅       |
| Can Use Prompts     | ✅                 | ✅      | ✅       | ✅       |
| Can Use Skills      | ✅                 | Kind of | ✅       | ✅       |
| Can Use MCP Servers | ✅                 | ✅      | ✅       | ✅       |
| Can Use Subagents   | ✅                 | ✅      | ✅       | ✅       |

### Real-world examples

| Use Case                                               | Best Tool     | Why                                                  |
| ------------------------------------------------------ | ------------- | ---------------------------------------------------- |
| "Always use Pinia for state management in Vue apps"    | `CLAUDE.md`   | Persistent context that applies to all conversations |
| Generate standardized commit messages                  | Skill (`disable-model-invocation: true`) | Explicit action you trigger when ready to commit |
| Check Jira tickets and analyze security simultaneously | Subagents     | Parallel execution with isolated contexts            |
| Run linter after every file edit                       | Hook          | Automatic reaction to lifecycle event                |
| Share your team's Vue testing patterns                 | Plugin        | Distributable package with commands + skills         |
| Query PostgreSQL database for reports                  | MCP           | External system integration                          |
| <InternalLink slug="how-i-use-claude-code-for-doing-seo-audits">Run automated SEO audits with browser testing</InternalLink> | MCP | External system integration |
| Detect style guide violations during any edit          | Skill         | Automatic behavior based on task context             |
| Create React components from templates                 | Skill (`disable-model-invocation: true`) | Manual workflow with repeatable structure |
| "Never use `any` type in TypeScript"                   | Hook          | Automatic enforcement after code changes             |
| Auto-format code on save                               | Hook          | Event-driven automation                              |
| Connect to GitHub for issue management                 | MCP           | External API integration                             |
| Run comprehensive test suite in parallel               | Subagent      | Isolated, resource-intensive work                    |
| Deploy to staging environment                          | Skill (`disable-model-invocation: true`) | Manual trigger with safeguards |
| <InternalLink slug="custom-tdd-workflow-claude-code-vue">Enforce TDD workflow automatically</InternalLink> | Skill | Context-aware automatic behavior |
| Initialize new projects with team standards            | Plugin        | Shareable, complete configuration                    |
| Run nightly dependency audit                           | Trigger       | Recurring task on a cron schedule                    |
| Summarize open PRs every Monday morning                | Trigger       | Scheduled report without manual invocation           |

---

--- title: How to Build a Claude Code Plugin: Skills, Agents & Commands description: How I built a Claude Code plugin to generate skills, agents, commands, and more—and stopped copy-pasting boilerplate. tags: ['claude-code', 'ai', 'tooling', 'productivity'] url: https://alexop.dev/posts/building-my-first-claude-code-plugin ---

# How to Build a Claude Code Plugin: Skills, Agents & Commands



<Alert type="info" title="New to Claude Code?">
  If you're unfamiliar with Claude Code or want to understand the full ecosystem (MCP, Skills, Subagents, Hooks, and Plugins), check out my{" "}
  <InternalLink slug="understanding-claude-code-full-stack">
    comprehensive guide to Claude Code's full stack
  </InternalLink>
  {" "}first. This post assumes you know the basics.
</Alert>

## The Problem

I've been using Claude Code for a while now. It's been my daily driver for development work, alongside <InternalLink slug="how-i-use-llms">other AI tools in my workflow</InternalLink>.

But here's the thing—over the last few months, I stopped paying attention to what Anthropic was shipping. Skills? Didn't look into them. Plugins? No idea they existed.

Today I caught up. And I discovered something I'd been missing: plugins.

The idea clicked immediately. Everything I'd been building locally—custom commands, agents, configurations—was stuck in `.claude/` folders per project. Plugins change that. You can package it up and share it across projects. Give Claude Code new abilities anywhere.

That's when I decided to build one. A plugin that generates slash commands, skills, agents, and everything else I kept creating manually.

<Aside type="tip" title="Want to Skip to the Code?">
The plugin is open source and ready to use. Check out the repository on GitHub to see the implementation or install it right away.

[View on GitHub](https://github.com/alexanderop/claude-code-builder)

</Aside>

<Aside type="info" title="What Are Plugins?">
Plugins extend Claude Code with custom commands, agents, hooks, Skills, and MCP servers through the plugin system. They let you package up functionality and share it across projects and teams.

Plugins can contain:

- **Slash commands** – Custom workflows you trigger explicitly (like `/analyze-deps`)
- **Skills** – Abilities Claude automatically uses when relevant
- **Agents** – Specialized sub-agents for focused tasks
- **Hooks** – Event handlers that run on tool use, prompt submit, etc.

For complete technical specifications and the official guide, see the [Claude Code Plugins documentation](https://code.claude.com/docs/en/plugins).

</Aside>

## The Manual Workflow Was Painful

Before the plugin, creating a new command looked like this:

1. Search the docs for the right frontmatter format
2. Create `.claude/commands/my-command.md`
3. Copy-paste a template
4. Fill in the blanks
5. Hope you got the structure right

Repeat for agents. Repeat for skills. Repeat for hooks.

10 minutes on boilerplate. 5 minutes on actual logic.

Same problem every time: too much manual work for something that should be instant.

## The Solution: Claude Code Builder

I fixed this by building a plugin that generates everything for me.

Here's what it includes:

| Command                | Description                                  |
| ---------------------- | -------------------------------------------- |
| `/create-skill`        | Generate model-invoked skills                |
| `/create-agent`        | Create specialized sub-agents                |
| `/create-command`      | Add custom slash commands                    |
| `/create-hook`         | Configure event-driven hooks                 |
| `/create-md`           | Generate CLAUDE.md files for project context |
| `/create-output-style` | Create custom output styles                  |
| `/create-plugin`       | Package your setup as a plugin               |

Each command handles the structure, frontmatter, and best practices. I just provide the name and description.

## The Plugin Structure

Here's the structure:

<FileTree
  tree={[
    {
      name: ".claude-plugin",
      open: true,
      children: [
        { name: "marketplace.json", comment: "Marketplace manifest" },
        { name: "plugin.json", comment: "Plugin metadata" },
      ],
    },
    { name: ".gitignore" },
    { name: "LICENSE" },
    { name: "README.md" },
    {
      name: "commands",
      open: true,
      children: [
        { name: "create-agent.md" },
        { name: "create-command.md" },
        { name: "create-hook.md" },
        { name: "create-md.md" },
        { name: "create-output-style.md" },
        { name: "create-plugin.md" },
        { name: "create-skill.md" },
      ],
    },
  ]}
/>

## Command Files: Where the Magic Happens

Each command is a markdown file with frontmatter. Here's the `/create-skill` command as an example:

```markdown
---
description: Generate a new Claude Skill with proper structure and YAML frontmatter
argument-hint: [skill-name] [description]
---

# /create-skill

## Purpose

Generate a new Claude Skill with proper structure and YAML frontmatter using official documentation as reference

## Contract

**Inputs:**

- `$1` — SKILL_NAME (lowercase, kebab-case, max 64 characters)
- `$2` — DESCRIPTION (what the skill does and when to use it, max 1024 characters)
- `--personal` — create in ~/.claude/skills/ (default)
- `--project` — create in .claude/skills/

**Outputs:** `STATUS=<CREATED|EXISTS|FAIL> PATH=<path>`

## Instructions

1. **Validate inputs:**
   - Skill name: lowercase letters, numbers, hyphens only
   - Description: non-empty, max 1024 characters

2. **Determine target directory:**
   - Personal (default): `~/.claude/skills/{{SKILL_NAME}}/`
   - Project: `.claude/skills/{{SKILL_NAME}}/`

3. **Generate SKILL.md using this template:**
   [template content here...]
```

<Alert type="tip" title="Key Insight">
  Commands are just instructions for Claude. Write them like you're teaching a
  junior developer the exact steps to follow. Good{" "}
  <InternalLink slug="xml-tagged-prompts-framework-reliable-ai-responses">
    prompt engineering principles
  </InternalLink>{" "}
  apply here too.
</Alert>

Here's what the plugin generates when you run a command:

<Figure
  src={outputExample}
  alt="Example output showing a generated skill file with proper structure and frontmatter"
  caption="The plugin creates properly structured files with all the boilerplate handled"
  width={800}
/>

## Publishing to GitHub

Once I had it working locally, publishing was straightforward:

1. Push to GitHub
2. Users add the marketplace: `/plugin marketplace add alexanderop/claude-code-builder`
3. Users install: `/plugin install claude-code-builder@claude-code-builder`

No npm, no build step. Just GitHub.

## Try It Yourself

Ready to stop copy-pasting Claude Code boilerplate?

**Step 1: Install the plugin**

```bash
/plugin install claude-code-builder@claude-code-builder
```

**Step 2: Verify installation**

Check that the plugin is loaded:

```bash
/plugins
```

You should see `claude-code-builder` in the list.

<Figure
  src={plugins}
  alt="Claude Code plugins list showing claude-code-builder installed"
  caption="The plugin appears in your installed plugins list"
  width={600}
/>

**Step 3: Use the new commands**

You now have access to seven new commands. Try creating your first skill:

```bash
/create-skill commit-helper "Generate clear commit messages; use when committing"
```

<Figure
  src={commands}
  alt="All seven commands available in Claude Code after installing the plugin"
  caption="Seven new commands at your fingertips"
  width={600}
/>

That's it. You're now equipped to generate skills, agents, commands, and more—without touching the docs.

## What's Next?

I'm using this daily. Every time I think "I wish Claude could...", I run `/create-skill` instead of Googling docs.

Right now, I'm focused on workflow optimization: building Vue applications faster with Claude Code.

The question I'm exploring: How do I teach Claude Code to write good Vue applications?

I'm working on:

- Skills that encode Vue best practices
- Commands for common Vue patterns (composables, stores, components)
- Custom agents that understand Vue architecture decisions
- <InternalLink slug="what-is-model-context-protocol-mcp">
    MCP server integrations
  </InternalLink>
  for external tools

It's not just about speed. It's about teaching Claude Code the way I think about development.

Building tools that build tools. That's where it gets fun.

---

--- title: Building a Modular Monolith with Nuxt Layers: A Practical Guide description: Learn how to build scalable applications using Nuxt Layers to enforce clean architecture boundaries without the complexity of microservices. tags: ['nuxt', 'vue', 'architecture', 'typescript'] url: https://alexop.dev/posts/nuxt-layers-modular-monolith ---

# Building a Modular Monolith with Nuxt Layers: A Practical Guide



I once worked on a project that wanted to build an e-commerce website with Nuxt that could be used by multiple countries. The architecture was a nightmare: they had a base repository, and then they would merge the base repo into country-specific code. This was before Nuxt Layers existed, back in the Nuxt 2 days, and managing this was incredibly painful. Every merge brought conflicts, and maintaining consistency across countries was a constant struggle.

Now with Nuxt Layers, we finally have a much better solution for this exact use case. But in this blog post, we're going to explore something even more powerful: using Nuxt Layers to build a **modular monolith architecture**.

I recently built a simple example e-commerce application to explore this pattern in depth, and I want to share what I learned. By the end of this post, you'll understand how to structure your Nuxt applications with clean boundaries and enforced separation of concerns, without the complexity of microservices or the pain of repository merging strategies.

**Full project repository**: https://github.com/alexanderop/nuxt-layer-example

This is Part 4 of my [How to Structure Vue Projects](/posts/how-to-structure-vue-projects/). If you're choosing between architecture patterns, start there first.

## The Problem: When Flat Architecture Stops Scaling

Most projects start the same way. You create a new Nuxt project, organize files into `components/`, `composables/`, and `stores/` folders, and everything feels clean and organized. This works beautifully at first.

Then your application grows. You add a product catalog, then a shopping cart, then user profiles, then an admin panel. Suddenly your `components/` folder has 50+ files. Your stores reference each other in complex ways you didn't plan for. A seemingly innocent change to the cart accidentally breaks the product listing page.

I've been there, and I'm sure you have too.

The core problem is simple: **flat architectures have no boundaries**. Nothing prevents your cart component from directly importing from your products store. Nothing stops circular dependencies. You can import anything from anywhere, and this freedom becomes a liability as your codebase grows.

<FileTree
  tree={[
    {
      name: "app",
      open: true,
      children: [
        {
          name: "components",
          open: true,
          children: [
            { name: "ProductCard.vue" },
            { name: "CartButton.vue" },
            { name: "CartItem.vue" },
            { name: "FilterBar.vue" },
            { name: "...", comment: "50+ more files" },
          ],
        },
        {
          name: "composables",
          open: true,
          children: [{ name: "...", comment: "everything mixed together" }],
        },
        {
          name: "stores",
          open: true,
          children: [
            { name: "products.ts" },
            { name: "cart.ts" },
            { name: "...", comment: "tightly coupled" },
          ],
        },
      ],
    },
  ]}
/>

When I first encountered this problem, I considered micro frontends. While [How to build Microfrontends with Module Federation and Vue](/posts/how-to-build-microfrontends-with-module-federation-and-vue/) solve similar problems, Nuxt Layers offers better developer experience for monorepos. I wanted clean boundaries without the operational complexity of deploying and maintaining separate services.

That's when I discovered Nuxt Layers.

## What Are Nuxt Layers?

Before diving into the implementation, let me explain what Nuxt Layers actually are and why they solve our problem.

Nuxt Layers let you split your application into independent, reusable modules. Think of each layer as a mini Nuxt application with its own components, composables, pages, and stores. Each layer lives in its own folder with its own `nuxt.config.ts` file.

<Aside type="info" title="Official Documentation">
  For comprehensive documentation on Nuxt Layers, visit the [official Nuxt
  Layers guide](https://nuxt.com/docs/4.x/guide/going-further/layers).
</Aside>

You compose these layers together using the `extends` keyword in your main configuration:

```typescript
// nuxt.config.ts
export default defineNuxtConfig({
  extends: [
    "./layers/shared", // Local folder
    "./layers/products",
    "./layers/cart",
  ],
});
```

<Aside type="tip" title="Layers Can Be Anywhere">
  Layers aren't limited to local folders. You can also extend from npm packages
  (`@your-org/ui-layer`) or git repositories (`github:your-org/shared-layer`).
  For remote sources to work as valid layers, they must contain a
  `nuxt.config.ts` file in their repository. This makes layers incredibly
  powerful for code reuse across projects.
</Aside>

When you extend layers, Nuxt merges their configurations and makes their code available to your application. All extended layers become accessible through auto-generated TypeScript paths (like `#layers/products/...`), and their components, composables, and utilities are automatically imported.

Here's the important part: **by default, there's no compile-time enforcement preventing cross-layer imports**. If your app extends both the products and cart layers, the cart layer can technically import from products at runtime—even if cart doesn't extend products directly. This is where ESLint enforcement becomes crucial, which I'll cover later.

```mermaid
graph TD
    A[App Root<br/>extends all layers] --> B[Products Layer<br/>extends shared]
    A --> C[Cart Layer<br/>extends shared]
    B --> D[Shared Layer<br/>extends nothing]
    C --> D
```

## Building an E-commerce Application with Layers

Let me show you how I structured a real e-commerce application using this pattern. I created three layers, each with a specific purpose:

**Shared Layer**: The foundation. This layer provides UI components (like badges and buttons), utility functions (currency formatting, storage helpers), and nothing else. No business logic lives here.

**Products Layer**: Everything related to browsing and viewing products. Product schemas, the product store, catalog pages, and filter components all live here. Crucially, this layer knows nothing about shopping carts.

**Cart Layer**: Everything related to managing a shopping cart. The cart store, localStorage persistence, and cart UI components. This layer knows nothing about product catalogs.

**Your Project Root**: The orchestrator. This is not a separate layer—it's your main application that extends all the layers. This is where you create pages that combine features from multiple layers (like a product listing page with "add to cart" functionality).

Here's the folder structure:

<FileTree
  tree={[
    {
      name: "layers",
      open: true,
      children: [
        {
          name: "shared",
          comment: "Foundation (no dependencies)",
          open: true,
          children: [
            {
              name: "components",
              open: true,
              children: [
                {
                  name: "base",
                  children: [{ name: "BaseBadge.vue" }],
                },
              ],
            },
            {
              name: "utils",
              children: [{ name: "currency.ts" }, { name: "storage.ts" }],
            },
          ],
        },
        {
          name: "products",
          comment: "Product feature (depends on shared only)",
          open: false,
          children: [
            {
              name: "components",
              children: [
                { name: "ProductCard.vue" },
                { name: "ProductFilters.vue" },
              ],
            },
            {
              name: "stores",
              children: [
                {
                  name: "products",
                  children: [{ name: "useProductsStore.ts" }],
                },
              ],
            },
            {
              name: "schemas",
              children: [{ name: "product.schema.ts" }],
            },
          ],
        },
        {
          name: "cart",
          comment: "Cart feature (depends on shared only)",
          open: false,
          children: [
            {
              name: "components",
              children: [
                { name: "CartSummary.vue" },
                { name: "CartItemCard.vue" },
              ],
            },
            {
              name: "stores",
              children: [
                {
                  name: "cart",
                  children: [{ name: "useCartStore.ts" }],
                },
              ],
            },
          ],
        },
      ],
    },
  ]}
/>

Notice how the products and cart layers never import from each other. They are completely independent features. This is the core principle that makes this pattern work.

## The Difference: Before and After

Let me show you the contrast between a traditional approach and the layered approach.

### Without Layers: Tight Coupling

In a traditional flat structure, your product component might directly import the cart store:

```vue
<script setup lang="ts">
// ❌ Tight coupling in flat architecture
const cart = useCartStore();
const products = useProductsStore();

function addToCart(productId: string) {
  const product = products.getById(productId);
  cart.addItem(product);
}
</script>
```

This creates hidden dependencies. The products feature now depends on the cart feature. You cannot use products without including cart. You cannot understand one without reading the other. Testing becomes harder because everything is coupled.

### With Layers: Clear Boundaries

With layers, the product component has no idea that carts exist:

```vue
<!-- layers/products/components/ProductCard.vue -->
<script setup lang="ts">
const props = defineProps<{
  product: Product;
}>();

const emit = defineEmits<{
  select: [productId: string];
}>();
</script>

<template>
  <UCard>
    <h3>{{ product.name }}</h3>
    <p>{{ product.price }}</p>
    <UButton @click="emit('select', product.id)"> View Details </UButton>
  </UCard>
</template>
```

The product component simply emits an event. The parent page (living in your project root) connects products to cart:

```vue
<!-- pages/index.vue (in your project root) -->
<script setup lang="ts">
const products = useProductsStore();
const cart = useCartStore();

function handleProductSelect(productId: string) {
  const product = products.getById(productId);
  if (product) {
    cart.addItem(product);
  }
}
</script>

<template>
  <div>
    <ProductCard
      v-for="product in products.items"
      :key="product.id"
      :product="product"
      @select="handleProductSelect"
    />
  </div>
</template>
```

Your project root acts as the orchestrator. It knows about both products and cart, but the features themselves stay completely independent.

<Aside type="info" title="Why This Approach Works">
  This pattern follows the dependency inversion principle. High-level modules
  (the app) depend on low-level modules (features), but features don't depend on
  each other. Changes to one feature won't cascade to others.
</Aside>

## How Features Communicate

When a page needs functionality from multiple layers, your project root orchestrates the interaction. I like to think of this pattern as similar to micro frontends with an app shell.

**Feature layers** are independent workers. Each does one job well. They expose simple interfaces (stores, components, composables) but have no knowledge of each other.

**Your project root** is the manager. It knows all the workers. When a task needs multiple workers, your project root coordinates them.

Here's a sequence diagram showing how this works:

```mermaid
sequenceDiagram
    participant User
    participant Page (Project Root)
    participant Products Layer
    participant Cart Layer

    User->>Page (Project Root): Click product
    Page (Project Root)->>Products Layer: Get product data
    Products Layer-->>Page (Project Root): Return product
    Page (Project Root)->>Cart Layer: Add to cart
    Cart Layer-->>Page (Project Root): Cart updated
    Page (Project Root)->>User: Show confirmation
```

Let me show you a real example from the cart page. It needs to display cart items (from the cart layer) with product details (from the products layer):

```vue
<!-- pages/cart.vue -->
<script setup lang="ts">
const cart = useCartStore();
const products = useProductsStore();

// App layer combines data from both features
const enrichedItems = computed(() => {
  return cart.items.map(cartItem => {
    const product = products.getById(cartItem.productId);
    return {
      ...cartItem,
      productDetails: product,
    };
  });
});
</script>

<template>
  <div>
    <h1>Your Cart</h1>
    <CartItemCard
      v-for="item in enrichedItems"
      :key="item.id"
      :item="item"
      @remove="cart.removeItem"
      @update-quantity="cart.updateQuantity"
    />
  </div>
</template>
```

Your project root queries both stores and combines the data. Neither feature layer knows about the other. This keeps your features loosely coupled and incredibly easy to test in isolation.

```mermaid
graph TB
    subgraph "Project Root (Orchestrator)"
        Page[Cart Page]
    end

    subgraph "Independent Features"
        Cart[Cart Layer<br/>Cart items & logic]
        Products[Products Layer<br/>Product data]
    end

    Page -->|reads| Cart
    Page -->|reads| Products
    Page -->|combines| Combined[Combined View]

    Cart -.->|never imports| Products
    Products -.->|never imports| Cart
```

## Enforcing Boundaries with ESLint

Now here's something important I discovered while working with this pattern. Nuxt provides basic boundary enforcement through TypeScript: if you try to import from a layer not in your `extends` array, your build fails. This is good, but it's not enough.

The problem is this: if your main config extends both products and cart, nothing prevents the cart layer from importing from products. Technically both layers are available at runtime. This creates the exact coupling we're trying to avoid.

I needed stricter enforcement. So I built a custom ESLint plugin called `eslint-plugin-nuxt-layers`.

This plugin enforces two critical rules:

1. **No cross-feature imports**: Cart cannot import from products (or vice versa)
2. **No upward imports**: Feature layers cannot import from the app layer

The plugin detects which layer a file belongs to based on its path, then validates all imports against the allowed dependencies.

```javascript
// ❌ This fails linting
// In layers/cart/stores/cart/useCartStore.ts
// Error: cart layer cannot import from products layer

// ✅ This passes linting (in layers/cart/)
// OK: cart layer can import from shared layer

// ✅ This also passes linting (in your project root)
// OK: project root can import from any layer
```

<Aside type="tip" title="Published Package">
I've published this ESLint plugin on npm so you can use it in your own projects. Install it with `pnpm add -D eslint-plugin-nuxt-layers` and get immediate feedback in your editor.

**Package link**: [eslint-plugin-nuxt-layers on npm](https://www.npmjs.com/package/eslint-plugin-nuxt-layers?activeTab=readme)

</Aside>

Here's how the validation logic works:

```mermaid
graph LR
    A[File being linted] --> B{Which layer?}
    B -->|shared| C[Can import: nothing]
    B -->|products| D[Can import: shared only]
    B -->|cart| E[Can import: shared only]
    B -->|project root| F[Can import: all layers]

    D -.->|❌| G[products → cart]
    E -.->|❌| H[cart → products]
```

The ESLint plugin gives you enforcement of your architecture. Your IDE will warn you immediately if you violate boundaries, and your CI/CD pipeline will fail if violations slip through.

## Important Gotchas to Avoid

Working with Nuxt Layers comes with some quirks you should know about. I learned these the hard way, so let me save you the trouble:

<Aside type="caution" title="Layer Priority Order">
Layer order determines override priority: **earlier layers have higher priority and override later ones**. This matters when multiple layers define the same component, page, or config value.

```typescript
// shared overrides products, products overrides cart
extends: ['./layers/shared', './layers/products', './layers/cart']

// cart overrides products, products overrides shared
extends: ['./layers/cart', './layers/products', './layers/shared']
```

For dependency purposes, all extended layers are available to each other at runtime. However, for clean architecture, you should still organize by semantic importance—typically putting shared/base layers first, then feature layers. Use ESLint rules to prevent unwanted cross-layer imports regardless of order.

</Aside>

<Aside type="caution" title="Same-Named Files Overwrite">
If multiple layers have a file at the same path (like `pages/index.vue`), only the first one wins. The later ones are silently ignored. This can cause confusing bugs where pages or components mysteriously disappear.

I recommend using unique names or paths for pages in different layers to avoid this issue entirely.

</Aside>

<Aside type="info" title="Config Changes Need Restart">
  Changes to `nuxt.config.ts` files in layers don't always hot reload properly.
  When you modify layer configuration, restart your dev server. I learned this
  after spending 30 minutes debugging why my changes weren't applying!
</Aside>

**Route paths need full names**: Layer names don't auto-prefix routes. If you have `layers/blog/pages/index.vue`, it creates the `/` route, not `/blog`. You need `layers/blog/pages/blog/index.vue` to get `/blog`.

**Component auto-import prefixing**: By default, nested components get prefixed. A component at `components/form/Input.vue` becomes `<FormInput>`. You can disable this with `pathPrefix: false` in the components config if you prefer explicit names.

## When Should You Use This Pattern?

I want to be honest with you: Nuxt Layers add complexity. They're powerful, but they're not always the right choice. Here's when I recommend using them:

**Your app has distinct features**: If you're building an application with clear feature boundaries (products, cart, blog, admin panel), layers shine. Each feature gets its own layer with its own components, pages, and logic.

**You have multiple developers**: Layers prevent teams from stepping on each other's toes. The cart team works in their layer, the products team works in theirs. No more merge conflicts in a giant shared components folder.

**You want to reuse code**: Building multiple apps that share functionality? Extract common features into layers and publish them as npm packages. Your marketing site and main app can share the same blog layer without code duplication.

**You're thinking long-term**: A small project with 5 components doesn't need layers. But a project that will grow to 50+ features over two years? Layers will save your sanity.

<Aside type="tip" title="Start Simple, Refactor When Needed">
  I don't recommend starting with layers on day one for small projects. Begin
  with a flat structure. When you notice features bleeding into each other and
  boundaries becoming unclear, that's the perfect time to refactor into layers.
  The patterns in this article will guide you through that migration.
</Aside>

## The Benefits You'll Get

After working with this pattern for several months, here are the concrete benefits I've experienced:

| Benefit                                | Description                                                                                                                                                                                                                                                                                                            |
| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Clear boundaries enforced by tools** | Import rules aren't just documentation that developers ignore. Your build fails if someone violates the architecture. This is incredibly powerful for maintaining standards as your team grows.                                                                                                                        |
| **Independent development**            | Team members can work on different features without conflicts. The cart team never touches product code. Changes are isolated and safe.                                                                                                                                                                                |
| **Easy testing**                       | Each layer has minimal dependencies. You can test features in complete isolation without complex mocking setups.                                                                                                                                                                                                       |
| **Gradual extraction**                 | If you need to extract a feature later (maybe to share across projects or even split into a micro frontend), you already have clean boundaries. You could publish a layer as its own npm package with minimal refactoring.                                                                                             |
| **Better code review**                 | When someone adds an import in a pull request, you immediately see if it crosses layer boundaries. Architecture violations become obvious during review.                                                                                                                                                               |
| **Scales with complexity**             | As your app grows, you simply add new layers. Existing layers stay independent and unaffected.                                                                                                                                                                                                                         |
| **Better AI assistant context**        | You can add layer-specific documentation files (like `claude.md`) to each layer with context tailored to that feature. When working with AI coding assistants like Claude or GitHub Copilot, changes to the cart layer will only pull in cart-specific context, making the AI's suggestions more accurate and focused. |
| **Targeted testing**                   | Running tests becomes more efficient. Instead of running your entire test suite, you can run only the tests related to the feature you're working on.                                                                                                                                                                  |

## Getting Started with Your Own Project

If you want to try this pattern, here's how to get started:

### 1. Clone and Explore the Example

Start by exploring the complete example project:

```bash
# 📥 Clone the repository
git clone https://github.com/alexanderop/nuxt-layer-example
cd nuxt-layer-example

# 📦 Install dependencies
pnpm install

# 🚀 Start development server
pnpm dev
```

Browse through the layers to see how everything connects. Try making changes to understand how the boundaries work.

### 2. Create Your Own Layered Project

To start your own project from scratch:

```bash
# 📁 Create layer folders
mkdir -p layers/shared layers/products layers/cart

# 🔧 Add a nuxt.config.ts to each layer
echo "export default defineNuxtConfig({
  \$meta: {
    name: 'shared',
    description: 'Shared UI and utilities'
  }
})" > layers/shared/nuxt.config.ts
```

<Aside type="info" title="Automatic Layer Discovery">
  Nuxt automatically discovers and extends layers in the `layers/` directory.
  You only need to explicitly configure `extends` in your `nuxt.config.ts` if
  you're using external layers (npm packages, git repositories) or if your
  layers are in a different location.
</Aside>

### 3. Add ESLint Enforcement

Install the ESLint plugin:

```bash
# 📦 Install ESLint plugin
pnpm add -D eslint-plugin-nuxt-layers
```

<Aside type="caution" title="Auto-Import Limitation">
  This ESLint plugin only works when auto-imports are disabled. You need to
  explicitly import from layers using `#layers/` aliases for the plugin to
  detect and validate cross-layer imports. If you rely on Nuxt's auto-import
  feature, the plugin won't be able to enforce boundaries.
</Aside>

Configure it in your `eslint.config.mjs` with the `layer-boundaries` rule:

```javascript
export default [
  {
    plugins: {
      "nuxt-layers": nuxtLayers,
    },
    rules: {
      "nuxt-layers/layer-boundaries": [
        "error",
        {
          root: "layers", // 📁 Your layers directory name
          aliases: ["#layers", "@layers"], // 🔗 Path aliases that point to layers
          layers: {
            shared: [], // 🏗️ Cannot import from any layer
            products: ["shared"], // 🛍️ Can only import from shared
            cart: ["shared"], // 🛒 Can only import from shared
            // 🏠 Your project root files can import from all layers (use '*')
          },
        },
      ],
    },
  },
];
```

The plugin will now enforce your architecture boundaries automatically. It detects violations in ES6 imports, dynamic imports, CommonJS requires, and export statements—giving you immediate feedback in your IDE and failing your CI/CD pipeline if boundaries are violated.

## Conclusion

I've been working with modular monoliths for a while now, and I believe this pattern gives you the best of both worlds. You get the clear boundaries and independent development of micro frontends without the operational complexity of deployment, networking, and data consistency.

Nuxt Layers makes this pattern accessible and practical. You get compile-time enforcement of boundaries through TypeScript. You get clear dependency graphs that are easy to visualize and understand. You get a structure that scales from small teams to large organizations without a rewrite.

You can start with layers from day one, or you can refactor gradually as your application grows. Either way, your future self will thank you when your codebase is still maintainable after two years and 50+ features.

I hope this blog post has been insightful and useful. The complete code is available for you to explore, learn from, and build upon. Clone it, break it, experiment with it.

**Full project repository**: https://github.com/alexanderop/nuxt-layer-example

If you have questions or want to share your own experiences with Nuxt Layers, I'd love to hear from you. This pattern has fundamentally changed how I approach application architecture, and I'm excited to see how you use it in your own projects.

---

--- title: How to Handle API Calls in Pinia with The Elm Pattern description: Learn how to handle API calls in Pinia using the Elm pattern for predictable, testable side effects. Includes complete examples with the Pokemon API. tags: ['vue'] url: https://alexop.dev/posts/handling-api-calls-pinia-elm-pattern ---

# How to Handle API Calls in Pinia with The Elm Pattern



<Aside type="info" title="When to Use This Pattern">
If your goal is to cache backend results or manage server state, Pinia is not the right tool.
Libraries such as [pinia-colada](https://pinia-colada.esm.dev/), [TanStack Vue Query](https://tanstack.com/query/vue), or [RStore](https://rstore.dev/) are designed for this purpose.
They provide built-in caching, background refetching, and synchronization features that make them a better fit for working with APIs.

The approach described in this post is useful when you want to stay within Pinia but still keep your logic functional, predictable, and easy to test.
It is best for local logic, explicit message-driven updates, or cases where you need fine control over how side effects are triggered and handled.

</Aside>

<Aside type="tip" title="Related Reading">
  This post builds on the concepts introduced in{" "}
  <InternalLink slug="tea-architecture-pinia-private-store-pattern">
    How to Write Better Pinia Stores with the Elm Pattern
  </InternalLink>
  . If you're new to The Elm Architecture or want to understand the full pattern
  for structuring Pinia stores, start there first. This post focuses
  specifically on handling side effects like API calls.
</Aside>

## Understanding Pure Functions and Side Effects

Before diving into the pattern, it's important to understand the foundational concepts of functional programming that make this approach powerful.

### What Is a Pure Function?

A pure function is a function that satisfies two key properties:

1. **Deterministic**: Given the same inputs, it always returns the same output.
2. **No side effects**: It does not interact with anything outside its scope.

Here's a simple example:

```ts
// Pure function - always predictable
function add(a: number, b: number): number {
  return a + b;
}

add(2, 3); // Always returns 5
add(2, 3); // Always returns 5
```

This function is pure because:

- It only depends on its inputs (`a` and `b`)
- It always produces the same result for the same inputs
- It doesn't modify any external state
- It doesn't perform any I/O operations

### What Is a Side Effect?

A side effect is any operation that interacts with the outside world or modifies state beyond the function's return value.

Common side effects include:

```ts
// Side effect: Network request
function fetchUser(id: number) {
  return fetch(`/api/users/${id}`); // Network I/O
}

// Side effect: Modifying external state
let count = 0;
function increment() {
  count++; // Mutates external variable
}

// Side effect: Writing to storage
function saveUser(user: User) {
  localStorage.setItem("user", JSON.stringify(user)); // I/O operation
}

// Side effect: Logging
function calculate(x: number) {
  console.log("Calculating..."); // I/O operation
  return x * 2;
}
```

None of these are pure functions because they interact with something beyond their inputs and outputs.

### Why Does This Matter?

Pure functions are easier to:

- **Test**: No need to mock APIs, databases, or global state
- **Reason about**: The function's behavior is completely determined by its inputs
- **Debug**: No hidden dependencies or unexpected state changes
- **Reuse**: Work anywhere without environmental setup

However, real applications need side effects. You can't build useful software without API calls, database writes, or user interactions.

The key insight from functional programming is not to eliminate side effects, but to **separate** them from your business logic.

## Why Side Effects Are a Problem

A pure function only depends on its inputs and always returns the same output.
If you include an API call or any asynchronous operation inside it, the function becomes unpredictable and hard to test.

Example:

```ts
export function update(model, msg) {
  if (msg.type === "FETCH_POKEMON") {
    fetch("https://pokeapi.co/api/v2/pokemon/pikachu");
    return { ...model, isLoading: true };
  }
}
```

This mixes logic with side effects.
The function now depends on the network and the API structure, making it complex to test and reason about.

## The Solution: Separate Logic and Effects

The Elm Architecture provides a simple way to handle side effects correctly.

1. Keep the update function pure.
2. Move side effects into separate functions that receive a dispatch function.
3. Use the store as the bridge between both layers.

This separation keeps your business logic independent of the framework and easier to verify.

### File Organization

Before diving into the code, here's how we organize the files for a Pinia store using the Elm pattern:

```
src/
└── stores/
    └── pokemon/
        ├── pokemonModel.ts    # Types and initial state
        ├── pokemonUpdate.ts   # Pure update function
        ├── pokemonEffects.ts  # Side effects (API calls)
        └── pokemon.ts         # Pinia store (connects everything)
```

Each file has a clear, single responsibility:

- **`pokemonModel.ts`**: Defines the state shape and message types
- **`pokemonUpdate.ts`**: Contains pure logic for state transitions
- **`pokemonEffects.ts`**: Handles side effects like API calls
- **`pokemon.ts`**: The Pinia store that wires everything together

This structure makes it easy to:

- Find and modify specific logic
- Test each piece independently
- Reuse the update logic in different contexts
- Add new effects without touching business logic

## Example: Fetching Data from the Pokémon API

This example demonstrates how to handle an API call using this pattern.

### `pokemonModel.ts`

The model defines the structure of the state and the possible messages that can change it.

```ts
export type PokemonModel = {
  isLoading: boolean;
  pokemon: string | null;
  error: string | null;
};

export const initialModel: PokemonModel = {
  isLoading: false,
  pokemon: null,
  error: null,
};

export type PokemonMsg =
  | { type: "FETCH_REQUEST"; name: string }
  | { type: "FETCH_SUCCESS"; pokemon: string }
  | { type: "FETCH_FAILURE"; error: string };
```

### `pokemonUpdate.ts`

The update function handles all state transitions in a pure way.

```ts
export function update(model: PokemonModel, msg: PokemonMsg): PokemonModel {
  switch (msg.type) {
    case "FETCH_REQUEST":
      return { ...model, isLoading: true, error: null };

    case "FETCH_SUCCESS":
      return { ...model, isLoading: false, pokemon: msg.pokemon };

    case "FETCH_FAILURE":
      return { ...model, isLoading: false, error: msg.error };

    default:
      return model;
  }
}
```

This function has no side effects.
It only describes how the state changes in response to a message.

### `pokemonEffects.ts`

This file performs the network request and communicates back through the dispatch function.

```ts
export async function fetchPokemon(
  name: string,
  dispatch: (m: PokemonMsg) => void
) {
  dispatch({ type: "FETCH_REQUEST", name });

  try {
    const res = await fetch(`https://pokeapi.co/api/v2/pokemon/${name}`);
    if (!res.ok) throw new Error("Not found");
    const data = await res.json();

    dispatch({ type: "FETCH_SUCCESS", pokemon: data.name });
  } catch (e: any) {
    dispatch({ type: "FETCH_FAILURE", error: e.message });
  }
}
```

This function does not depend on Pinia or Vue.
It simply performs the side effect and dispatches messages based on the result.

### `pokemon.ts`

The Pinia store connects the pure logic and the side effect layer.

```ts
import {
  initialModel,
  type PokemonModel,
  type PokemonMsg,
} from "./pokemonModel";
export const usePokemonStore = defineStore("pokemon", () => {
  const model = ref<PokemonModel>(initialModel);

  function dispatch(msg: PokemonMsg) {
    model.value = update(model.value, msg);
  }

  async function load(name: string) {
    await fetchPokemon(name, dispatch);
  }

  return {
    state: readonly(model),
    load,
  };
});
```

The store contains no direct logic for handling API responses.
It only coordinates updates and side effects.

### Usage in a Component

```vue
<script setup lang="ts">
const store = usePokemonStore();
const name = ref("pikachu");

function fetchIt() {
  store.load(name.value);
}
</script>

<template>
  <div>
    
    <button @click="fetchIt">Search</button>

    <p v-if="store.state.isLoading">Loading...</p>
    <p v-else-if="store.state.error">Error: {{ store.state.error }}</p>
    <p v-else-if="store.state.pokemon">Found: {{ store.state.pokemon }}</p>
  </div>
</template>
```

The component only interacts with the public API of the store.
It does not mutate the state directly.

## Why This Approach Works

Separating logic and effects provides several benefits.

- The update function is pure and easy to test.
- The side effect functions are independent and reusable.
- The store focuses only on coordination.
- The overall data flow remains predictable and maintainable.

This method is especially effective in projects where you want full control over how and when side effects are executed.

<Aside type="tip" title="Testing Made Simple">
Because the `update` function is pure and framework-agnostic, you can test it with simple assertions without any mocking:

```ts
describe("pokemon update", () => {
  it("sets loading state on fetch request", () => {
    const state = { isLoading: false, pokemon: null, error: null };
    const result = update(state, { type: "FETCH_REQUEST", name: "pikachu" });

    expect(result.isLoading).toBe(true);
    expect(result.error).toBeNull();
  });
});
```

No Pinia setup, no component mounting, just pure function testing.

</Aside>

<Aside type="caution" title="When This Pattern May Be Overkill">
The Elm pattern adds structure and discipline, but it comes with trade-offs:

**Not ideal for simple stores:**
If your store just fetches data and displays it with minimal logic, the traditional Pinia approach is perfectly fine. Creating four separate files for a simple CRUD operation adds unnecessary complexity.

**Requires team buy-in:**
This pattern works best when your entire team embraces functional programming concepts. If your team isn't comfortable with ideas like pure functions, immutability, and message-driven updates, this pattern will feel foreign and may be resisted.

**Where it shines:**

- Complex business logic with multiple state transitions
- Stores that need rock-solid testing
- Applications with sophisticated side effect orchestration (retries, cancellation, queuing)
- Projects where state predictability is critical

**Bottom line:** Start simple. Adopt this pattern when complexity demands it and your team is ready for functional programming principles. Don't use it just because it's clever—use it when it solves real problems.

</Aside>

## Other Side Effects You Can Handle with This Pattern

This pattern is not limited to API requests.
You can manage any kind of asynchronous or external operation the same way.

Examples include:

- Writing to or reading from `localStorage` or `IndexedDB`
- Sending analytics or telemetry events
- Performing authentication or token refresh logic
- Communicating with WebSockets or event streams
- Scheduling background tasks with `setTimeout` or `requestAnimationFrame`
- Reading files or using browser APIs such as the Clipboard or File System

By using the same structure, you can keep these effects organized and testable.
Each effect becomes an independent unit that transforms external data into messages for your update function.

## Summary

If you only need caching or background synchronization, use a specialized library such as [pinia-colada](https://pinia-colada.esm.dev/), [TanStack Vue Query](https://tanstack.com/query/vue), or [RStore](https://rstore.dev/).
If you need to stay within Pinia and still maintain a functional structure, this approach is effective.

1. Define your model and messages.
2. Keep the update function pure.
3. Implement effects as separate functions that take a dispatch function.
4. Connect them inside the store.

This structure keeps your Pinia stores predictable, testable, and easy to extend to any type of side effect.

---

--- title: How to Write Better Pinia Stores with the Elm Pattern description: Learn how to combine The Elm Architecture (TEA) principles with Pinia's private store pattern for testable, framework-agnostic state management in Vue applications. tags: ['vue'] url: https://alexop.dev/posts/tea-architecture-pinia-private-store-pattern ---

# How to Write Better Pinia Stores with the Elm Pattern



## The Problem: Pinia Gives You Freedom, Not Rules

Pinia is a fantastic state management library for Vue, but it doesn't enforce any architectural patterns. It gives you complete freedom to structure your stores however you want. This flexibility is powerful, but it comes with a hidden cost: without discipline, your stores can become unpredictable and hard to test.

The core issue? Pinia stores are inherently mutable and framework-coupled. While this makes them convenient for rapid development, it creates three problems:

```ts
// Traditional Pinia approach - tightly coupled to Vue
export const useTodosStore = defineStore("todos", () => {
  const todos = ref<Todo[]>([]);

  function addTodo(text: string) {
    todos.value.push({ id: Date.now(), text, done: false });
  }

  return { todos, addTodo };
});
```

The problem? Components can bypass your API and directly manipulate state:

```vue
<script setup lang="ts">
const store = useTodosStore();

// Intended way
store.addTodo("Learn Pinia");

// But this also works! Direct state manipulation
store.todos.push({ id: 999, text: "Hack the state", done: false });
</script>
```

This leads to unpredictable state changes, makes testing difficult (requires mocking Pinia's entire runtime), and couples your business logic tightly to Vue's reactivity system.

```mermaid
graph TB
    C1[Component A] -->|"store.addTodo() ✓"| API[Intended API]
    C2[Component B] -->|"store.todos.push() ✗"| State[Direct State Access]
    C3[Component C] -->|"store.todos[0].done = true ✗"| State
    API --> Store[Store State]
    State --> Store
    Store -->|unpredictable changes| Debug[Difficult to Debug]
```

## The Solution: TEA + Private Store Pattern

What if we could keep Pinia's excellent developer experience while adding the predictability and testability of functional patterns? Enter The Elm Architecture (TEA) combined with the "private store" technique from [Mastering Pinia](https://masteringpinia.com/blog/how-to-create-private-state-in-stores) by Eduardo San Martin Morote (creator of Pinia).

This hybrid approach gives you:

- **Pure, testable business logic** that's framework-agnostic
- **Controlled state mutations** through a single dispatch function
- **Seamless Vue integration** with Pinia's reactivity
- **Full devtools support** for debugging

You'll use a private internal store for mutable state, expose only selectors and a dispatch function publicly, and keep your update logic pure and framework-agnostic.

<Aside type="tip" title="When Should You Use This Pattern?">
  This pattern shines when you have complex business logic, need framework
  portability, or want rock-solid testing. For simple CRUD operations with
  minimal logic, traditional Pinia stores are perfectly fine. Ask yourself:
  "Would I benefit from testing this logic in complete isolation?" If yes, this
  pattern is worth it.
</Aside>

<Aside type="info" title="Historical Context">
  The Elm Architecture emerged from the [Elm programming
  language](https://guide.elm-lang.org/architecture/), which pioneered a purely
  functional approach to building web applications. This pattern later inspired
  Redux's architecture in the JavaScript ecosystem, demonstrating the value of
  unidirectional data flow and immutable updates. While Elm enforces these
  patterns through its type system, we can achieve similar benefits in Vue with
  disciplined patterns.
</Aside>

## Understanding The Elm Architecture

Before we dive into the implementation, let's understand the core concepts of TEA:

1. **Model**: The state of your application
2. **Update**: Pure functions that transform state based on messages/actions
3. **View**: Rendering UI based on the current model

```mermaid
graph LR
    M[Model<br/>Current State] -->|renders| V[View<br/>UI Display]
    V -->|user interaction<br/>produces| Msg[Message/Action]
    Msg -->|dispatched to| U[Update Function<br/>Pure Logic]
    U -->|returns new| M

```

The key insight is that update functions are pure—given the same state and action, they always return the same new state. This makes them trivial to test without any framework dependencies.

## How It Works: Combining TEA with Private State

The pattern uses three key pieces: a private internal store for mutable state, pure update functions for business logic, and a public store that exposes only selectors and dispatch.

### The Private Internal Store

First, create a private store that holds the mutable model. This stays in the same file as your public store but is not exported:

```ts
// Inside stores/todos.ts - NOT exported!
const useTodosPrivate = defineStore("todos-private", () => {
  const model = ref<TodosModel>({
    todos: [],
  });

  return { model };
});
```

The key here: no `export` keyword means components can't access this directly.

### Pure Update Function

Next, define your business logic as pure functions:

<Aside type="info" title="What Are Pure Functions?">
  A pure function always returns the same output for the same inputs and has no
  side effects. No API calls, no mutations of external state, no `console.log`.
  Just input → transformation → output. This makes them trivially easy to test
  and reason about: `update(state, action)` always produces the same new state.
</Aside>

```ts
// stores/todos-update.ts
export function update(model: TodosModel, message: TodosMessage): TodosModel {
  switch (message.type) {
    case "ADD_TODO":
      return {
        ...model,
        todos: [
          ...model.todos,
          { id: Date.now(), text: message.text, done: false },
        ],
      };

    case "TOGGLE_TODO":
      return {
        ...model,
        todos: model.todos.map(todo =>
          todo.id === message.id ? { ...todo, done: !todo.done } : todo
        ),
      };

    default:
      return model;
  }
}
```

This update function is completely framework-agnostic. You can test it with simple assertions:

```ts
describe("update", () => {
  it("adds a todo", () => {
    const initial = { todos: [] };
    const result = update(initial, { type: "ADD_TODO", text: "Test" });

    expect(result.todos).toHaveLength(1);
    expect(result.todos[0].text).toBe("Test");
  });
});
```

<Aside type="info" title="Familiar with Redux?">
  If you've used Redux, this pattern will feel familiar—the `update` function is
  like a reducer, and `TodosMessage` is like an action. The key difference?
  We're using Pinia's reactivity instead of Redux's subscription model, and
  we're keeping the private store pattern to prevent direct state access. This
  gives you Redux's testability with Pinia's developer experience.
</Aside>

### Public Store with Selectors + Dispatch

Finally, combine everything in a single file. The private store is defined but not exported:

```ts
// stores/todos.ts (this is what components import)
// Private store - not exported!
const useTodosPrivate = defineStore("todos-private", () => {
  const model = ref<TodosModel>({
    todos: [],
  });

  return { model };
});

// Public store - this is what gets exported
export const useTodosStore = defineStore("todos", () => {
  const privateStore = useTodosPrivate();

  // Selectors
  const todos = computed(() => privateStore.model.todos);

  // Dispatch
  function dispatch(message: TodosMessage) {
    privateStore.model = update(privateStore.model, message);
  }

  return { todos, dispatch };
});
```

```mermaid
graph LR
    Component[Component]
    Component -->|dispatch message| Public[Public Store]
    Public -->|call| Update[Update Function<br/>Pure Logic]
    Update -->|new state| Private[Private Store]
    Private -->|selectors| Public
    Public -->|reactive data| Component
```

<Aside type="caution" title="️Private Store Limitation">
Reddit user [maertensen](https://www.reddit.com/user/maertensen/) helpfully pointed out that the private store pattern only prevents direct mutation of primitives, **not arrays and objects**. Components can still mutate through selectors:

```vue
<script setup lang="ts">
const publicTodosStore = useTodosStore();

function mutateTodosSelector() {
  // This still works and bypasses dispatch! ✗
  publicTodosStore.todos.push({
    id: Date.now(),
    text: "Mutated by selector",
    done: false,
  });
}
</script>
```

This is why I recommend using **`readonly` only** (shown below) instead of the private store pattern.

</Aside>

### Usage in Components

Components interact with the public store:

```vue
<script setup lang="ts">
const store = useTodosStore();
</script>

<template>
  <div>
    <input
      @keyup.enter="
        store.dispatch({ type: 'ADD_TODO', text: $event.target.value })
      "
    />

    <div v-for="todo in store.todos" :key="todo.id">
      <input
        type="checkbox"
        :checked="todo.done"
        @change="store.dispatch({ type: 'TOGGLE_TODO', id: todo.id })"
      />
      {{ todo.text }}
    </div>
  </div>
</template>
```

## Simpler Alternative: Using Vue's readonly

If you want to prevent direct state mutations without creating a private store, Vue's `readonly` utility provides a simpler approach:

```ts
// stores/todos.ts
export const useTodosStore = defineStore("todos", () => {
  const model = ref<TodosModel>({
    todos: [],
  });

  // Dispatch
  function dispatch(message: TodosMessage) {
    model.value = update(model.value, message);
  }

  // Only expose readonly state
  return {
    todos: readonly(model),
    dispatch,
  };
});
```

With `readonly`, any attempt to mutate the state from a component will fail:

```vue
<script setup lang="ts">
const store = useTodosStore();

// ✓ Works - using dispatch
store.dispatch({ type: "ADD_TODO", text: "Learn Vue" });

// ✓ Works - accessing readonly state
const todos = store.model.todos;

// ✗ TypeScript error - readonly prevents mutation
store.model.todos.push({ id: 1, text: "Hack", done: false });
</script>
```

<Aside type="tip" title="Use readonly, Not Private Store">
  **Prefer `readonly` over the private store pattern.** The private store
  pattern has a critical flaw: it doesn't prevent mutation of arrays and objects
  (see warning above). Using `readonly` is simpler, more effective, and truly
  prevents all direct state mutations.
</Aside>

## Benefits of This Approach

1. **Pure business logic**: The `update` function has zero dependencies on Vue or Pinia
2. **Easy testing**: Test your update function with simple unit tests
3. **Framework flexibility**: Could swap Vue for React without changing update logic
4. **Type safety**: TypeScript ensures message types are correct
5. **Devtools support**: Still works with Pinia devtools since we're using real stores
6. **Encapsulation**: Private store is an implementation detail

```mermaid
graph TB
    subgraph T["Traditional Pinia"]
        TC[Component]
        TC -->|direct| TS[State]
        TC -->|actions| TA[Actions]
        TA --> TS
    end

    subgraph P["TEA + Private Store"]
        PC[Component] -->|dispatch| PD[Dispatch]
        PD --> PU[Update]
        PU --> PM[Model]
        PM -->|selectors| PC
    end
```

## Conclusion

By combining The Elm Architecture with Pinia's private store pattern, we achieve:

- Pure, testable business logic
- Clear separation of concerns
- Framework-agnostic state management
- Full Pinia devtools integration
- Type-safe message dispatching

This pattern scales from simple forms to complex domain logic while keeping your code maintainable and your tests simple.

---

_Credit: This post synthesizes ideas from [The Elm Architecture](https://guide.elm-lang.org/architecture/) and Eduardo San Martin Morote's ["private store" pattern](https://masteringpinia.com/blog/how-to-create-private-state-in-stores) from Mastering Pinia._

---

--- title: How to build Microfrontends with Module Federation and Vue description: Build a Vue 3 microfrontend app with Module Federation. Clear decisions, working code, and a small reference project. tags: ['vue', 'microfrontends', 'module-federation', 'architecture'] url: https://alexop.dev/posts/how-to-build-microfrontends-with-module-federation-and-vue ---

# How to build Microfrontends with Module Federation and Vue



<Alert type="tip" title="TL;DR">
  Monorepo with `pnpm`. Vue 3 SPA. Client side composition with Module
  Federation. Host owns routing. Events for navigation. Cart sync through
  localStorage plus events. Shared UI library for consistency. Fallbacks for
  remote failures. Code:
  https://github.com/alexanderop/tractorStoreVueModuleFederation
</Alert>

<Alert type="warning" title="Who should read this">
  You know Vue and basic bundling. You want to split a SPA into independent
  parts without tight coupling. If you do not have multiple teams or deployment
  bottlenecks, you likely do not need microfrontends.
</Alert>

I wanted to write about microfrontends three years ago. My first touchpoint was the book _Micro Frontends in Action_ by Michael Geers. It taught me a lot, and I was still confused. This post shows a practical setup that works today with Vue 3 and Module Federation.

## Scope

We build microfrontends for a Vue 3 SPA with client side composition. Server and universal rendering exist, but they are out of scope here.

> Microfrontends are the technical representation of a business subdomain. They allow independent implementations with minimal shared code and single team ownership.
> (Luca Mezzalira)

## The Tractor Store in one minute

The Tractor Store is a reference shop that lets us compare microfrontend approaches on the same feature set (explore, decide, checkout). It is clear enough to show boundaries and realistic enough to surface routing, shared state, and styling issues.

<YouTube
  id="12TN7Zq7VxM"
  title="The Tractor Store idea"
  caption="If you want to understand the background and the full setup behind the Tractor Store exercise, watch the video of the creator: https://micro-frontends.org/tractor-store/"
/>

<Figure
  src={tractorStoreImage}
  alt="Tractor Store application overview showing the microfrontend architecture with product listings, recommendations, and shopping cart functionality"
  width={800}
  caption="The Tractor Store built with Vue 3 microfrontends and Module Federation"
/>

## Architecture decisions

| Question         | Decision                                                        | Notes                                              |
| ---------------- | --------------------------------------------------------------- | -------------------------------------------------- |
| Repo layout      | Monorepo with `pnpm` workspaces                                 | Shared configs, atomic refactors, simple local dev |
| Composition      | Client side with Module Federation                              | Fast iteration, simple hosting                     |
| Routing          | Host owns routing                                               | One place for guards, links, and errors            |
| Team boundaries  | Explore, Decide, Checkout, plus Host                            | Map to clear user flows                            |
| Communication    | Custom events for navigation. Cart via localStorage plus events | Low coupling and no shared global store            |
| UI consistency   | Shared UI library in `packages/shared`                          | Buttons, inputs, tokens                            |
| Failure handling | Loading and error fallbacks in host. Retry once                 | Keep the shell usable                              |
| Styles           | Team prefixes or Vue scoped styles. Tokens in shared            | Prevent leakage and keep a common look             |

Repository layout:

```
├── apps/
│   ├── host/          (Shell application)
│   ├── explore/       (Product discovery)
│   ├── decide/        (Product detail)
│   └── checkout/      (Cart and checkout)
├── packages/
│   └── shared/        (UI, tokens, utils)
└── pnpm-workspace.yaml
```

Workspace definition:

```yaml
packages:
  - "apps/*"
  - "packages/*"
```

High level view:

```mermaid
graph TD
    subgraph "Monorepo (@tractor)"
        subgraph "apps/"
            Host("host")
            Explore("explore")
            Decide("decide")
            Checkout("checkout")
        end
        subgraph "packages/"
            Shared("shared")
        end
    end

    Host -- Consumes --> Explore
    Host -- Consumes --> Decide
    Host -- Consumes --> Checkout

    Explore -- Uses --> Shared
    Decide -- Uses --> Shared
    Checkout -- Uses --> Shared
    Host -- Uses --> Shared
```

## Implementation

We compose at the client in the host. The host loads remote components at runtime and routes between them.

### Host router

```ts
// apps/host/src/router.ts
export const router = createRouter({
  history: createWebHistory(),
  routes: [
    { path: "/", component: remote("explore/HomePage") },
    {
      path: "/products/:category?",
      component: remote("explore/CategoryPage"),
      props: true,
    },
    {
      path: "/product/:id",
      component: remote("decide/ProductPage"),
      props: true,
    },
    { path: "/checkout/cart", component: remote("checkout/CartPage") },
  ],
});
```

### `remote()` utility

<Alert type="tip" title="Vue async components">
Vue `defineAsyncComponent` wraps any loader in a friendly component. It gives lazy loading, built in states, and retries. This is why it fits microfrontends.

```js
const AsyncComp = defineAsyncComponent({
  loader: () => Promise.resolve(/* component */),
  delay: 200,
  timeout: 3000,
  onError(error, retry, fail, attempts) {
    if (attempts <= 1) retry();
    else fail();
  },
});
```

</Alert>

```ts
// apps/host/src/utils/remote.ts
export function remote(id: string, delay = 150) {
  return defineAsyncComponent({
    loader: async () => {
      const loader = (window as any).getComponent?.(id);
      if (!loader) throw new Error(`Missing loader for ${id}`);
      return await loader();
    },
    delay,
    loadingComponent: {
      render: () => h("div", { class: "mf-loading" }, "Loading..."),
    },
    errorComponent: {
      render: () => h("div", { class: "mf-error" }, "Failed to load."),
    },
    onError(error, retry, fail, attempts) {
      if (attempts <= 1) setTimeout(retry, 200);
      else fail();
    },
  });
}
```

<Alert type="note" title="💡 What is Module Federation?">
  Module Federation enables dynamic loading of JavaScript modules from different
  applications at runtime. Think of it as splitting your app into independently
  deployable pieces that can share code and communicate. You can use **Webpack
  5**, **Rspack**, or **Vite** as bundlers. **Rspack offers the most
  comprehensive Module Federation support** with excellent performance, but for
  this solution I used **Rspack** (for the host) and **Vite** (for one remote)
  to showcase interoperability between different bundlers.
</Alert>

### Module Federation runtime

The host bootstraps Module Federation and exposes a single loader.

```ts
// apps/host/src/mf.ts
import {
  createInstance,
  loadRemote,
} from "@module-federation/enhanced/runtime";

declare global {
  interface Window {
    getComponent: (id: string) => () => Promise<any>;
  }
}

createInstance({
  name: "host",
  remotes: [
    {
      name: "decide",
      entry: "http://localhost:5175/mf-manifest.json",
      alias: "decide",
    },
    {
      name: "explore",
      entry: "http://localhost:3004/mf-manifest.json",
      alias: "explore",
    },
    {
      name: "checkout",
      entry: "http://localhost:3003/mf-manifest.json",
      alias: "checkout",
    },
  ],
  plugins: [
    {
      name: "fallback-plugin",
      errorLoadRemote(args: any) {
        console.warn(`Failed to load remote: ${args.id}`, args.error);
        return {
          default: {
            template: `<div style="padding: 2rem; text-align: center; border: 1px solid #ddd; border-radius: 8px; background: #f9f9f9; margin: 1rem 0;">
              <h3 style="color: #c00; margin-bottom: 1rem;">Remote unavailable</h3>
              <p><strong>Remote:</strong> ${args.id}</p>
              <p>Try again or check the service.</p>
            </div>`,
          },
        };
      },
    },
  ],
});

window.getComponent = (id: string) => {
  return async () => {
    const mod = (await loadRemote(id)) as any;
    return mod.default || mod;
  };
};
```

**Why this setup**

- The host is the single source of truth for remote URLs and versions.
- URLs can change without rebuilding remotes.
- The fallback plugin gives a consistent error experience.

## Communication

We avoid a shared global store. We use two small patterns that keep coupling low.

<Alert type="important" title="Why we do not need Pinia">
A global store looks handy. In microfrontends it creates tight runtime coupling. That kills independent deploys.

What goes wrong:

- Lockstep releases (one store change breaks other teams)
- Hidden contracts (store shape is an API that drifts)
- Boot order traps (who creates the store and plugins)
- Bigger blast radius (a store error can break the whole app)
- Harder tests (cross team mocks and brittle fixtures)

Do this instead:

- Each microfrontend owns its state
- Communicate with explicit custom events
- Use URL and localStorage for simple shared reads
- Share code not state (tokens, UI, pure utils)
- If shared state grows, revisit boundaries rather than centralize it
</Alert>

<Alert type="info" title="💡 Alternative: VueUse EventBus">
  You could use VueUse's `useEventBus` for more Vue-like event communication
  instead of vanilla JavaScript events. It provides a cleaner API with
  TypeScript support and automatic cleanup in component lifecycle. However,
  adding VueUse means another dependency in your microfrontends. The tradeoff is
  developer experience vs. bundle size and dependency management: vanilla
  JavaScript events keep things lightweight and framework-agnostic.
</Alert>

### Navigation through custom events

Remotes dispatch `mf:navigate` with `{ to }`. The host listens and calls `router.push`.

```ts
// apps/host/src/main.ts
window.addEventListener("mf:navigate", (e: Event) => {
  const to = (e as CustomEvent).detail?.to;
  if (to) router.push(to);
});
```

### Cart sync through localStorage plus events

The checkout microfrontend owns cart logic. It listens for `add-to-cart` and `remove-from-cart`. After each change, it writes to localStorage and dispatches `updated-cart`. Any component can listen and re read.

```ts
// apps/checkout/src/stores/cartStore.ts
window.addEventListener("add-to-cart", (ev: Event) => {
  const { sku } = (ev as CustomEvent).detail;
  // update cart array here
  localStorage.setItem("cart", JSON.stringify(cart));
  window.dispatchEvent(new CustomEvent("updated-cart"));
});
```

## Styling

- Design tokens in `packages/shared` (CSS variables).
- Shared UI in `packages/shared/ui` (Button, Input, Card).
- Local isolation with Vue scoped styles or BEM with team prefixes (`e_`, `d_`, `c_`, `h_`).
- Host provides `.mf-loading` and `.mf-error` classes for fallback UI.

Example with BEM plus team prefix:

```css
/* decide */
.d_ProductPage__title {
  font-size: 2rem;
  color: var(--color-primary);
}
.d_ProductPage__title--featured {
  color: var(--color-accent);
}
```

Or Vue scoped styles:

```vue
<template>
  <div class="product-information">
    <h1 class="title">{{ product.name }}</h1>
  </div>
</template>

<style scoped>
.product-information {
  padding: 1rem;
}
.title {
  font-size: 2rem;
}
</style>
```

## Operations

Plan for failure and keep the shell alive.

- Each remote shows a clear loading state and a clear error state.
- Navigation works even if a remote fails.
- Logs are visible in the host during development.

Global styles in the host help here:

```css
/* apps/host/src/styles.css */
.mf-loading {
  display: flex;
  align-items: center;
  justify-content: center;
  padding: 2rem;
  color: var(--color-text-muted);
}

.mf-error {
  padding: 1rem;
  background: var(--color-error-background);
  border: 1px solid var(--color-error-border);
  color: var(--color-error-text);
  border-radius: 4px;
}
```

## More Module Federation features (short hints)

Our solution is simple on purpose. Module Federation can do more. Use these when your app needs them.

**Prefetch** (requires registering lazyLoadComponentPlugin)  
Pre load JS, CSS, and data for a remote before the user clicks (for example on hover). This cuts wait time.

```js
// after registering lazyLoadComponentPlugin on the runtime instance
const mf = getInstance();
function onHover() {
  mf.prefetch({
    id: "shop/Button",
    dataFetchParams: { productId: "12345" },
    preloadComponentResource: true, // also fetch JS and CSS
  });
}
```

**Component level data fetching**  
Expose a `.data` loader next to a component. The consumer can ask the runtime to fetch data before render (works in CSR and SSR). Use a `.data.client.ts` file for client loaders when SSR falls back.

**Caching for loaders**  
Wrap expensive loaders in a cache helper (with maxAge, revalidate, tag, and custom keys). You get stale while revalidate behavior and tag based invalidation.

```js
// inside your DataLoader file
const fetchDashboard = cache(async () => getStats(), {
  maxAge: 120000,
  revalidate: 60000,
});
```

**Type hinting for remotes**  
`@module-federation/enhanced` can generate types for exposes. Add this to tsconfig.json so editors resolve remote types and hot reload them.

```json
{
  "compilerOptions": { "paths": { "*": ["./@mf-types/*"] } },
  "include": ["./@mf-types/*"]
}
```

**Vue bridge for app level modules**  
Mount a whole remote Vue app into a route when you need an application level integration (not just a component).

```js
const RemoteApp = createRemoteAppComponent({
  loader: () => loadRemote("remote1/export-app"),
});
// router: { path: '/remote1/:pathMatch(.*)*', component: RemoteApp }
```

You can read more about these interesting techniques at [module-federation.io](https://module-federation.io/).

### Summary

This was my first attempt to understand **microfrontends** better while solving the _Tractor Store_ exercise.

In the future, I may also try it with **SSR** and **universal rendering**, which I find interesting.

Another option could be to use **Nuxt Layers** and take a _“microfrontend-ish”_ approach at build time.

---

--- title: Why You Need Something Hard in Your Life description: The biggest paradox in life: the hardest things are usually the ones that help you grow. Exploring why challenge and difficulty are essential for meaning and personal development. tags: ['personal-development', 'productivity', 'motivation'] url: https://alexop.dev/posts/why-you-need-something-hard-in-your-life ---

# Why You Need Something Hard in Your Life



The biggest paradox in life is simple: the hardest things are usually the ones that help you grow. They force you out of your comfort zone. They make you stronger.

One reason so many people in my generation are depressed is that they do not have a hard thing that is worth aiming for. They live on autopilot. Work 9 to 5. Watch Netflix. Go to a party on the weekend. And then repeat.

Sometimes life gives you that hard thing automatically. Having a kid, for example, is brutally hard but also meaningful. But what if you do not have that? What do you do now?

That is why so many millennials run marathons. A marathon is something hard. It gives you structure, meaning, and a clear goal. It demands you change your habits. It tells you who you are when things get tough.

For me, I am happiest when I have a goal in front of me. Something hard. Not impossible, but not easy either. If it is too easy, I get bored. If it is too hard, I give up. But the sweet spot, where I have to fight for it, that is where life feels good. I am reading Flow right now by the Hungarian psychologist Mihály Csíkszentmihályi, and he explains exactly this. Real happiness does not come from comfort. It comes from challenge. From stretching yourself just enough that you lose track of time and become fully absorbed in the thing you are doing. That is where meaning lives.

One of my favorite sports anime, Blue Lock, explains the concept of flow perfectly in [this video](https://www.youtube.com/watch?v=KTHqbv2M0aA). It shows how athletes enter a state where everything else disappears and they become completely absorbed in the challenge at hand. This is flow in action.

The times when I was unhappy were always the times when I had no goal. I was just living. Eating badly. Drinking too much. Slowly sinking into a life I did not want.

So here is my takeaway:

Find something hard.

Stick with it.

Let it shape you.

Because without it, life gets empty fast.

---

--- title: What Is the Model Context Protocol (MCP)? How It Works description: Learn how MCP (Model Context Protocol) standardizes AI tool integration, enabling LLMs to interact with external services, databases, and APIs through a universal protocol similar to USB-C for AI applications. tags: ['mcp', 'typescript', 'ai'] url: https://alexop.dev/posts/what-is-model-context-protocol-mcp ---

# What Is the Model Context Protocol (MCP)? How It Works



I did not see how powerful MCP was until I used Claude Code with the Playwright MCP.
**Playwright MCP lets an AI use a real browser.** It can open a page, click buttons, fill forms, and take screenshots.
I asked Claude to audit my site for SEO. It ran checks in a real browser, gave me the results, and sent screenshots. You can read more about <InternalLink slug="how-i-use-claude-code-for-doing-seo-audits">how I use Claude Code for doing SEO audits</InternalLink>.
**That was when I saw it.** This was not just text prediction. This was an AI that can see and work with the web like a human tester.

## What is MCP

MCP means Model Context Protocol.
Before we define it, let us see how we got here.

## How it started

```mermaid
flowchart TD
    U[User] --> A[LLM]
    A --> U
```

In 2022 ChatGPT made AI open to everyone.
You typed a question. It predicted the next tokens and sent back text.
You could ask for your favorite author or create code.

## The problem with plain LLMs

A plain LLM is a text generator.

- It has no live data
- It cannot read your files
- It struggles with math
- It cannot tell you who won yesterday in football

You can read more in my post about <InternalLink slug="how-chatgpt-works-for-dummies">LLM limits</InternalLink>.

## The first fix: tools

```mermaid {scale: '0.5'}
flowchart TD
    U[User] --> A[LLM]
    A --> D{Needs Python?}
    D -->|Yes| P[Run code in Python sandbox]
    P --> O[Execution result]
    O --> A
    D -->|No| A
    A --> U
```

When OpenAI added a Python sandbox, LLMs could run code and give exact results.

## More tools mean more power

```mermaid {scale: '0.5'}
flowchart TD
    U[User] --> A[LLM]
    A --> D{Needs external tool?}

    D -->|Python| P[Run code in Python sandbox]
    P --> O[Execution result]
    O --> A

    D -->|Web search| W[Search the web for information]
    W --> R[Search result]
    R --> A

    D -->|No| A
    A --> U
```

Web search gave live knowledge. Now the model could answer fresh questions.

## Even more tools

```mermaid {scale: '0.5'}
flowchart TD
    U[User] --> A[LLM]
    A --> D{Needs external tool?}

    D -->|Python| P[Run code in Python sandbox]
    P --> O[Execution result]
    O --> A

    D -->|Web search| W[Search the web for information]
    W --> R[Search result]
    R --> A

    D -->|Google Calendar| G[Check / update calendar events]
    G --> E[Calendar data]
    E --> A

    D -->|No| A
    A --> U
```

Anthropic added more tools to Claude like Google Calendar and email.
You can ask it what meetings you have next week and it tells you.

<CaptionedImage
  src={scalingProblemComic}
  alt="Comic showing multiple teams reinventing the wheel by building the same API connectors"
  caption="If every team builds their own tool for connecting to email, calendar, and other APIs, everyone reinvents the wheel"
/>

## The solution: a protocol

We need a standard.
One tool for Google Calendar that any agent can use.
In November the Model Context Protocol was released.

## Definition

**MCP** is an open protocol that lets apps give context to LLMs in a standard way.

Think of **USB-C**. You plug in power, a display, or storage and it just works.

MCP does the same for AI with data sources and tools.

With MCP you can build agents and workflows without custom glue code.

<CaptionedImage
  src={robotMcpComic}
  alt="Robot MCP Comic showing how MCP connects different tools and services"
  caption="MCP acts as the universal connector for AI tools and services"
/>

---

## How MCP Works (mental model)

At its core, MCP has **three roles**:

- **Host** → LLM applications that initiate connections
- **Client** → Connectors within the host application
- **Server** → Services that provide context and capabilities

<Alert type="note">
  MCP takes some inspiration from the Language Server Protocol, which
  standardizes how to add support for programming languages across a whole
  ecosystem of development tools. In a similar way, MCP standardizes how to
  integrate additional context and tools into the ecosystem of AI applications.
</Alert>

The host embeds clients, and those clients connect to one or more servers.
Your VS Code could have a Playwright MCP server for browser automation and another MCP server for your docs — all running at the same time.

```mermaid
flowchart LR
  U((User))
  U --> H[Host UI<br>Claude Desktop, VS Code/Claude Code]
  H --> C1[MCP Client 1]
  H --> C2[MCP Client 2]
  H --> C3[MCP Client 3]
  C1 --> S1[MCP Server A]
  C2 --> S2[MCP Server B]
  C3 --> S3[MCP Server C]
```

---

## How MCP Connects: Transports

MCP uses **JSON-RPC 2.0** for all messages and supports two main transport mechanisms:

<GridCards
  cards={[
    {
      title: "stdio (local)",
      icon: "📍",
      items: [
        "Server runs as subprocess of the client",
        "Messages flow through stdin/stdout pipes",
        "No network latency - instant communication",
        "Perfect for local tools and dev environments",
      ],
    },
    {
      title: "Streamable HTTP (remote)",
      icon: "🌐",
      items: [
        "Single HTTP endpoint for all operations",
        "POST for sending messages, GET for listening",
        "Server-Sent Events (SSE) for streaming",
        "Ideal for cloud-hosted MCP servers",
      ],
    },
  ]}
/>

**Key points:**

- Messages are UTF-8 encoded JSON-RPC
- stdio uses newline-delimited JSON (one message per line)
- HTTP supports session management via `Mcp-Session-Id` headers
- Both transports handle requests, responses, and notifications equally well

The transport choice depends on your use case: stdio for local tools with minimal latency, HTTP for remote services that multiple clients can connect to.

## What servers can expose

An MCP server can offer any combination of three capabilities:

### Tools: Functions the AI can call

- Give AI ability to execute actions (check weather, query databases, solve math)
- Each tool describes what it does and what info it needs
- AI sends parameters → server runs function → returns results

```typescript
// Simple calculator tool example
server.registerTool(
  "calculate",
  {
    title: "Calculator",
    description: "Perform mathematical calculations",
    inputSchema: {
      operation: z.enum(["add", "subtract", "multiply", "divide"]),
      a: z.number(),
      b: z.number(),
    },
  },
  async ({ operation, a, b }) => {
    let result;
    switch (operation) {
      case "add":
        result = a + b;
        break;
      case "subtract":
        result = a - b;
        break;
      case "multiply":
        result = a * b;
        break;
      case "divide":
        result = b !== 0 ? a / b : "Error: Division by zero";
        break;
    }

    return {
      content: [
        {
          type: "text",
          text: `${a} ${operation} ${b} = ${result}`,
        },
      ],
    };
  }
);
```

### Resources: Context and data

- AI can read files, docs, database schemas
- Provides context before answering questions or using tools
- Supports change notifications when files update

```typescript
server.registerResource(
  "app-config",
  "config://application",
  {
    title: "Application Configuration",
    description: "Current app settings and environment",
    mimeType: "application/json",
  },
  async uri => ({
    contents: [
      {
        uri: uri.href,
        text: JSON.stringify(
          {
            environment: process.env.NODE_ENV,
            version: "1.0.0",
            features: {
              darkMode: true,
              analytics: false,
              beta: process.env.BETA === "true",
            },
          },
          null,
          2
        ),
      },
    ],
  })
);
```

### Prompts: Templates for interaction

- Pre-made templates for common tasks (code review, data analysis)
- Exposed as slash commands or UI elements
- Makes repetitive workflows quick and consistent

````typescript
server.registerPrompt(
  "code-review",
  {
    title: "Code Review",
    description: "Review code for quality and best practices",
    argsSchema: {
      language: z.enum(["javascript", "typescript", "python", "go"]),
      code: z.string(),
      focus: z
        .enum(["security", "performance", "readability", "all"])
        .default("all"),
    },
  },
  ({ language, code, focus }) => ({
    messages: [
      {
        role: "user",
        content: {
          type: "text",
          text: [
            `Please review this ${language} code focusing on ${focus}:`,
            "",
            "```" + language,
            code,
            "```",
            "",
            "Provide feedback on:",
            focus === "all"
              ? "- Security issues\n- Performance optimizations\n- Code readability\n- Best practices"
              : focus === "security"
                ? "- Potential security vulnerabilities\n- Input validation\n- Authentication/authorization issues"
                : focus === "performance"
                  ? "- Time complexity\n- Memory usage\n- Potential optimizations"
                  : "- Variable naming\n- Code structure\n- Comments and documentation",
          ].join("\n"),
        },
      },
    ],
  })
);
````

## What a Client can expose

An MCP client can provide capabilities that let servers interact with the world beyond their sandbox:

### Roots: Filesystem boundaries

- Client tells server which directories it can access
- Creates secure sandbox (e.g., only your project folder)
- Prevents access to system files or other projects

### Sampling: Nested LLM calls

- Servers can request AI completions through the client
- No API keys needed on server side
- Enables autonomous, agentic behaviors

### Elicitation: Asking users for input

- Servers request missing info from users via client UI
- Client handles forms and validation
- Users can accept, decline, or cancel requests

## Example: How we can use MCPS in Vscode

Your `mcp.json` could look like this:

```json
{
  "servers": {
    "playwright": {
      "gallery": true,
      "command": "npx",
      "args": ["@playwright/mcp@latest"],
      "type": "stdio"
    },
    "deepwiki": {
      "type": "http",
      "url": "https://mcp.deepwiki.com/sse",
      "gallery": true
    }
  }
}
```

- **playwright** → Runs `npx @playwright/mcp@latest` locally over stdio for low-latency browser automation
- **deepwiki** → Connects over HTTP/SSE to `https://mcp.deepwiki.com/sse` for live docs and codebase search
- **gallery: true** → Makes them visible in tool pickers

## What MCP is not

- **Not a hosted service** — It is a protocol
- **Not a replacement** for your app logic
- **Not a magic fix** for every hallucination — It gives access to real tools and data
- You still need good prompts and good UX

---

## Simple example of your first MCP Server

```ts
#!/usr/bin/env node
const server = new McpServer({
  name: "echo-onefile",
  version: "1.0.0",
});

server.tool(
  "echo",
  "Echo back the provided text",
  {
    text: z
      .string()
      .min(1, "Text cannot be empty")
      .describe("Text to echo back"),
  },
  async ({ text }) => ({
    content: [{ type: "text", text }],
  })
);

const transport = new StdioServerTransport();

server
  .connect(transport)
  .then(() => console.error("Echo MCP server listening on stdio"))
  .catch(err => {
    console.error(err);
    process.exit(1);
  });
```

This example uses the official [MCP SDK for TypeScript](https://modelcontextprotocol.io/docs/sdk), which provides type-safe abstractions for building MCP servers.

The server exposes a single tool called "echo" that takes text input and returns it back. We're using [Zod](https://zod.dev/) for runtime schema validation, ensuring the input matches our expected structure with proper type safety and clear error messages.

## Simple MCP Client Example

Here's how to connect to an MCP server and use its capabilities:

```typescript
// Create a client that connects to your MCP server
async function connectToServer() {
  // Create transport - this runs your server as a subprocess
  const transport = new StdioClientTransport({
    command: "node",
    args: ["./echo-server.js"],
  });

  // Create and connect the client
  const client = new Client({
    name: "my-mcp-client",
    version: "1.0.0",
  });

  await client.connect(transport);

  return client;
}

// Use the server's capabilities
async function useServer() {
  const client = await connectToServer();

  // List available tools
  const tools = await client.listTools();
  console.log("Available tools:", tools);

  // Call a tool
  const result = await client.callTool({
    name: "echo",
    arguments: {
      text: "Hello from MCP client!",
    },
  });

  console.log("Tool result:", result.content);

  // List and read resources
  const resources = await client.listResources();
  for (const resource of resources) {
    const content = await client.readResource({
      uri: resource.uri,
    });
    console.log(`Resource ${resource.name}:`, content);
  }

  // Get and execute a prompt
  const prompts = await client.listPrompts();
  if (prompts.length > 0) {
    const prompt = await client.getPrompt({
      name: prompts[0].name,
      arguments: {
        code: "console.log('test')",
        language: "javascript",
      },
    });
    console.log("Prompt messages:", prompt.messages);
  }

  // Clean up
  await client.close();
}

// Run the client
useServer().catch(console.error);
```

This client example shows how to:

- Connect to an MCP server using stdio transport
- List and call tools with arguments
- Read resources from the server
- Get and use prompt templates
- Properly close the connection when done

## Use it with Vscode

```json
{
  "servers": {
    "echo": {
      "gallery": true,
      "type": "stdio",
      "command": "node",
      "args": ["--import", "tsx", "/absolute/path/echo-server.ts"]
    }
  }
}
```

## Summary

This was just my starter post for MCP to give an overview. I will write more blog posts that will go in depth about the different topics.

<Alert type="note">
  If you need a TypeScript starter template for your next MCP server, you can
  use my
  [mcp-server-starter-ts](https://github.com/alexanderop/mcp-server-starter-ts)
  repository to get up and running quickly.
</Alert>

---

--- title: How VueUse Solves SSR Window Errors in Vue Applications description: Discover how VueUse solves SSR issues with browser APIs and keeps your Vue composables safe from 'window is not defined' errors. tags: ['vue'] url: https://alexop.dev/posts/how-vueuse-solves-ssr-window-errors-vue-applications ---

# How VueUse Solves SSR Window Errors in Vue Applications



I am a big fan of [VueUse](https://vueuse.org). Every time I browse the docs I discover a new utility that saves me hours of work. Yet VueUse does more than offer nice functions. It also keeps your code safe when you mix client-side JavaScript with server-side rendering (SSR). In this post I show the typical **"`window` is not defined"** problem, explain why it happens, and walk through the simple tricks VueUse uses to avoid it.

## The Usual Pain: `window` Fails on the Server

When you run a Vue app with SSR, Vue executes in **two** places:

1. **Server (Node.js)** – It renders HTML so the user sees a fast first screen.
2. **Browser (JavaScript runtime in the user's tab)** – It takes over and adds interactivity.

The server uses **Node.js**, which has **no browser objects** like `window`, `document`, or `navigator`. The browser has them. If code that needs `window` runs on the server, Node.js throws an error and the page render breaks.

### Diagram: How SSR Works

```mermaid
sequenceDiagram
    participant B as Browser
    participant S as Server (Node.js)
    B->>S: Request page
    S-->>S: Run Vue code<br/>(no window)
    S-->>B: Send HTML
    B-->>B: Hydrate app<br/>(has window)
    Note over S,B: If Vue code touches <br/>"window" on the server, SSR crashes
```

## Node.js vs Browser: Two Different Worlds

| Feature     | Node.js on the server | Browser in the tab |
| ----------- | --------------------- | ------------------ |
| `window`    | ❌ not defined        | ✅ defined         |
| `document`  | ❌                    | ✅                 |
| `navigator` | ❌                    | ✅                 |
| DOM access  | ❌                    | ✅                 |
| Goal        | Render HTML fast      | Add interactivity  |

A Vue _composable_ that reads the mouse position or listens to scroll events needs those browser objects. It must **not** run while the server renders.

## How VueUse Solves the Problem

VueUse uses three small patterns: a **client check**, **safe defaults**, and an **SSR guard** inside each composable.

### 1. One-Line Client Check

VueUse first asks, "Are we in the browser?" It does that in [`is.ts`](https://github.com/vueuse/vueuse/blob/main/packages/shared/utils/is.ts):

```ts
export const isClient =
  typeof window !== "undefined" && typeof document !== "undefined";
```

#### Diagram

```mermaid
flowchart TD
  Start --> Test{window exists?}
  Test -- yes --> Client[isClient = true]
  Test -- no --> Server[isClient = false]
```

### 2. Safe Defaults for Browser Objects

Instead of making _you_ write `if (isClient)` checks, VueUse exports harmless fallbacks from [`_configurable.ts`](https://github.com/vueuse/vueuse/blob/main/packages/core/_configurable.ts):

```ts
export const defaultWindow = isClient ? window : undefined;
export const defaultDocument = isClient ? window.document : undefined;
export const defaultNavigator = isClient ? window.navigator : undefined;
```

On the server these constants are `undefined`. That value is safe to read, so nothing crashes.

#### Diagram

```mermaid
flowchart TD
  Check[isClient?] -->|true| Real[Return real window]
  Check -->|false| Undef[Return undefined]
  Real --> Compose[Composable receives safe value]
  Undef --> Compose
```

### 3. The SSR Guard Inside Every Composable

Each composable that might touch the DOM adds a simple guard. Example: [`onElementRemoval`](https://github.com/vueuse/vueuse/blob/main/packages/core/onElementRemoval/index.ts):

```ts
export function onElementRemoval(options: any = {}) {
  const { window = defaultWindow } = options;

  if (!window)
    // server path
    return () => {}; // no-op

  // browser logic goes here
}
```

If `window` is `undefined`, the function returns a no-op and exits. The server render keeps going without errors.

#### Diagram

```mermaid
flowchart TD
  Run[Composable starts] --> IsWin{defaultWindow ?}
  IsWin -- no --> Noop[Return empty function]
  IsWin -- yes --> Logic[Run browser code]
```

### 4. Extra Safety with `useSupported`

Sometimes you **are** in the browser, but the user's browser lacks a feature. VueUse offers [`useSupported`](https://github.com/vueuse/vueuse/blob/main/packages/core/useSupported/index.ts) to check that:

```ts
export function useSupported(test: () => unknown) {
  const isMounted = useMounted();
  return computed(() => {
    isMounted.value; // make it reactive
    return Boolean(test());
  });
}
```

#### Example: `useEyeDropper`

`useEyeDropper` checks both SSR and feature support (see the full file [here](https://github.com/vueuse/vueuse/blob/main/packages/core/useEyeDropper/index.ts)):

```ts
export function useEyeDropper() {
  const isSupported = useSupported(
    () => typeof window !== "undefined" && "EyeDropper" in window
  );

  async function open() {
    if (!isSupported.value) return; // safe exit
    const eyeDropper = new (window as any).EyeDropper();
    await eyeDropper.open();
  }

  return { isSupported, open };
}
```

## Wrap-Up

- **Node.js** renders HTML but lacks browser globals.
- **VueUse** avoids crashes with three steps:
  1. A single **`isClient`** flag tells where the code runs.
  2. **Safe defaults** turn `window`, `document`, and `navigator` into `undefined` on the server.
  3. Every composable adds a quick **SSR guard** that eliminates environment concerns.

Because of this design you can import any VueUse composable, even ones that touch the DOM, and trust it to work in SSR without extra code.

### Learn More

- VueUse guidelines that inspired these patterns: [https://vueuse.org/guidelines](https://vueuse.org/guidelines)
- Full VueUse repository: [https://github.com/vueuse/vueuse](https://github.com/vueuse/vueuse)

---

--- title: Mastering GraphQL Fragments in Vue 3: Component-Driven Data Fetching description: Part 3 of the Vue 3 + GraphQL series: Learn how to use GraphQL fragments with fragment masking to create truly component-driven data fetching in Vue 3. tags: ['graphql', 'vue', 'typescript'] url: https://alexop.dev/posts/mastering-graphql-fragments-vue3-component-driven-data-fetching ---

# Mastering GraphQL Fragments in Vue 3: Component-Driven Data Fetching



```mermaid
graph TD
    A["❌ Traditional Approach"] --> A1["Monolithic Queries"]
    A1 --> A2["Over-fetching"]
    A1 --> A3["Tight Coupling"]
    A1 --> A4["Implicit Dependencies"]

    B["✅ Fragment Masking"] --> B1["Component-Owned Data"]
    B1 --> B2["Type Safety"]
    B1 --> B3["Data Encapsulation"]
    B1 --> B4["Safe Refactoring"]
```

## Why Fragments Are a Game-Changer

In Part 2, we achieved type safety with GraphQL Code Generator. But our queries are still monolithic—each component doesn't declare its own data needs. This creates several problems:

- **Over-fetching**: Parent components request data their children might not need
- **Under-fetching**: Adding a field means hunting down every query using that type
- **Tight coupling**: Components depend on their parents to provide the right data
- **Implicit dependencies**: Parent components can accidentally rely on data from child fragments
- **Brittle refactoring**: Changing a component's data needs can break unrelated components

Enter GraphQL fragments with **fragment masking**—the pattern that Relay popularized and that Apollo Client 3.12 has made even more powerful. This transforms how we think about data fetching by providing **true data encapsulation** at the component level.

## What Are GraphQL Fragments?

GraphQL fragments are **reusable units of fields** that components can declare for themselves. But they're more than just field groupings—when combined with fragment masking, they provide **data access control**.

```graphql
fragment CountryBasicInfo on Country {
  code
  name
  emoji
  capital
}
```

**Fragment masking** is the key innovation that makes fragments truly powerful. It ensures that:

1. **Data is encapsulated**: Only the component that defines a fragment can access its fields
2. **Dependencies are explicit**: Components can't accidentally rely on data from other fragments
3. **Refactoring is safe**: Changing a fragment won't break unrelated components
4. **Type safety is enforced**: TypeScript prevents accessing fields you didn't request

## Understanding Fragments Through the Spread Operator

If you're familiar with JavaScript's spread operator, fragments work exactly the same way:

```javascript
// JavaScript objects
const basicInfo = { code: "US", name: "United States" };
const fullCountry = { ...basicInfo, capital: "Washington D.C." };
```

```graphql
# GraphQL fragments
fragment CountryBasicInfo on Country {
  code
  name
}

query GetCountryDetails {
  country(code: "US") {
    ...CountryBasicInfo # Spread fragment fields
    capital # Add extra fields
  }
}
```

**Fragment masking** takes this further by ensuring components can only access the data they explicitly request—pioneered by **Relay** and now enhanced in **Apollo Client 3.12**.

## Step 1: Enable Fragment Masking

Ensure your `codegen.ts` uses the client preset (from Part 2):

```typescript
const config: CodegenConfig = {
  overwrite: true,
  schema: "https://countries.trevorblades.com/graphql",
  documents: ["src/**/*.vue", "src/**/*.graphql"],
  generates: {
    "src/gql/": {
      preset: "client",
      plugins: [],
      config: { useTypeImports: true },
    },
  },
};
```

This generates:

- `FragmentType<T>`: Masked fragment types for props
- `useFragment()`: Function to unmask fragment data
- Type safety to prevent accessing non-fragment fields

## Step 2: Your First Fragment with Masking

Let's create a `CountryCard` component that declares its own data requirements:

```vue
<script setup lang="ts">
// Define what data this component needs
const CountryCard_CountryFragment = graphql(`
  fragment CountryCard_CountryFragment on Country {
    code
    name
    emoji
    capital
    phone
    currency
  }
`);

// Props accept a masked fragment type
interface Props {
  country: FragmentType<typeof CountryCard_CountryFragment>;
}

const props = defineProps<Props>();

// Unmask to access the actual data (reactive for Vue)
const country = computed(() =>
  useFragment(CountryCard_CountryFragment, props.country)
);
</script>

<template>
  <div class="country-card">
    <h3>{{ country.emoji }} {{ country.name }}</h3>
    <p>Capital: {{ country.capital }}</p>
    <p>Phone: +{{ country.phone }}</p>
    <p>Currency: {{ country.currency }}</p>
  </div>
</template>
```

## Understanding Fragment Masking: The Key to Data Isolation

**Fragment masking** is the core concept that makes this pattern so powerful. It's not just about code organization—it's about **data access control and encapsulation**.

### What Fragment Masking Actually Does

Think of fragment masking like **access control in programming languages**. Just as a module can have private and public methods, fragment masking controls which components can access which pieces of data.

```typescript
// Without fragment masking (traditional approach)
const result = useQuery(GET_COUNTRIES);
const countries = result.value?.countries || [];

// ❌ Parent can access ANY field from the query
console.log(countries[0].name); // Works
console.log(countries[0].capital); // Works
console.log(countries[0].currency); // Works
```

With fragment masking enabled:

```typescript
// ✅ Parent component CANNOT access fragment fields
const name = result.value?.countries[0].name; // TypeScript error!

// ✅ Only CountryCard can access its fragment data
const country = useFragment(CountryCard_CountryFragment, props.country);
console.log(country.name); // Works!
```

### The Power of Data Encapsulation

Fragment masking provides **true data encapsulation**:

1. **Prevents Implicit Dependencies**: Parent components can't accidentally rely on data their children need
2. **Catches Breaking Changes Early**: If a child component removes a field, the parent can't access it anymore
3. **Enforces Component Boundaries**: Each component owns its data requirements
4. **Enables Safe Refactoring**: Change a fragment without breaking unrelated components

### Why This Matters

Without fragment masking, parent components can accidentally depend on child fragment data. When the child removes a field, the parent breaks at runtime. With fragment masking, TypeScript catches this at compile time.

```typescript
// Parent can only access explicitly requested fields
countries[0].id; // ✅ Works (parent requested this)
countries[0].name; // ❌ TypeScript error (only in fragment)

// Child components unmask their fragment data
const country = useFragment(CountryCard_CountryFragment, props.country);
country.name; // ✅ Works (component owns this fragment)
```

> **📝 Vue Reactivity Note**: Always wrap `useFragment` in a `computed()` for Vue reactivity. This ensures the component updates when fragment data changes.

## Step 3: Parent Component Uses the Fragment

Now the parent component includes the child's fragment in its query:

```vue
<script setup lang="ts">
const COUNTRIES_WITH_DETAILS_QUERY = graphql(`
  query CountriesWithDetails {
    countries {
      code
      # Parent can add its own fields
      region
      # Child component's fragment
      ...CountryCard_CountryFragment
    }
  }
`);

const { result, loading, error } = useQuery(COUNTRIES_WITH_DETAILS_QUERY);

// Parent can access its own fields
const countriesByRegion = computed(() => {
  if (!result.value?.countries) return {};

  return result.value.countries.reduce(
    (acc, country) => {
      const region = country.region;
      if (!acc[region]) acc[region] = [];
      acc[region].push(country);
      return acc;
    },
    {} as Record<string, typeof result.value.countries>
  );
});

// But parent CANNOT access fragment fields:
// const name = result.value?.countries[0].name ❌ TypeScript error!
</script>

<template>
  <div class="countries-container">
    <div v-if="loading">Loading countries...</div>
    <div v-else-if="error">Error: {{ error.message }}</div>
    <div v-else class="countries-by-region">
      <div
        v-for="(countries, region) in countriesByRegion"
        :key="region"
        class="region-section"
      >
        <h2>{{ region }}</h2>
        <div class="country-grid">
          <CountryCard
            v-for="country in countries"
            :key="country.code"
            :country="country"
          />
        </div>
      </div>
    </div>
  </div>
</template>
```

## The Magic of Fragment Masking

Here's what just happened:

```mermaid
graph TB
    subgraph "GraphQL Query Result"
        QR["countries: Country[]"]
    end

    subgraph "Parent Component"
        PC["Parent can access:<br/>• countries[].code<br/>• countries[].region<br/>❌ countries[].name"]
    end

    subgraph "Child Component"
        CC["CountryCard receives:<br/>Masked Fragment Data"]
        UF["useFragment() unmasks:<br/>• code<br/>• name<br/>• emoji<br/>• capital"]
    end

    QR --> PC
    QR --> CC
    CC --> UF
```

The parent component **cannot access** fields from `CountryCard_Fragment`—they're masked! Only `CountryCard` can unmask and use that data.

## Step 4: Nested Fragments

Fragments can include other fragments, creating a hierarchy:

```graphql
# Basic fragment
fragment LanguageItem_LanguageFragment on Language {
  code
  name
  native
}

# Fragment that uses other fragments
fragment CountryWithLanguages_CountryFragment on Country {
  code
  name
  emoji
  languages {
    ...LanguageItem_LanguageFragment
  }
}
```

Child components use their own fragments:

```vue
<!-- LanguageItem.vue -->
<script setup lang="ts">
const LanguageItem_LanguageFragment = graphql(`
  fragment LanguageItem_LanguageFragment on Language {
    code
    name
    native
  }
`);

interface Props {
  language: FragmentType<typeof LanguageItem_LanguageFragment>;
}

const props = defineProps<Props>();
const language = computed(() =>
  useFragment(LanguageItem_LanguageFragment, props.language)
);
</script>

<template>
  <div class="language-item">
    <span>{{ language.name }} ({{ language.code }})</span>
  </div>
</template>
```

## Fragment Dependency Management

Notice how the query automatically includes all nested fragments:

```mermaid
graph LR
    subgraph "Components"
        A[CountryDetailPage]
        B[CountryWithLanguages.vue]
        C[LanguageItem.vue]
    end

    subgraph "Their Fragments"
        A1[Page Fields:<br/>code]
        B1[Country Fragment:<br/>code, name, emoji<br/>languages]
        C1[Language Fragment:<br/>code, name, native]
    end

    A -.-> A1
    B -.-> B1
    C -.-> C1
```

## Step 5: Conditional Fragments

Use GraphQL directives to conditionally include fragments:

```graphql
query CountriesConditional($includeLanguages: Boolean!) {
  countries {
    code
    name
    ...CountryDetails_CountryFragment @include(if: $includeLanguages)
  }
}
```

This enables dynamic data loading based on user interactions or application state.

## Best Practices

### Key Guidelines

1. **Naming**: Use `ComponentName_TypeNameFragment` convention
2. **Vue Reactivity**: Always wrap `useFragment` in `computed()`
3. **TypeScript**: Use `FragmentType<typeof MyFragment>` for props
4. **Organization**: Colocate fragments with components

```typescript
// ✅ Good naming and Vue reactivity
const CountryCard_CountryFragment = graphql(`...`);

interface Props {
  country: FragmentType<typeof CountryCard_CountryFragment>;
}

const country = computed(() =>
  useFragment(CountryCard_CountryFragment, props.country)
);
```

## Performance Benefits

Fragments aren't just about developer experience - they provide concrete performance and maintainability benefits:

```mermaid
graph TD
    A["❌ Multiple Queries"] --> A1["3 Network Requests"]
    A1 --> A2["Duplicate Data Fetching"]
    A2 --> A3["Larger Bundle Size"]

    B["✅ Fragment Composition"] --> B1["Single Network Request"]
    B1 --> B2["Optimized Payload"]
    B2 --> B3["Better Performance"]
```

## Summary

GraphQL fragments with fragment masking enable **component-driven data fetching** in Vue 3:

✅ **Type Safety**: Components can only access their declared fields
✅ **True Modularity**: Each component declares its exact data needs  
✅ **Better Performance**: Load only the data you need
✅ **Maintainable Code**: Changes to fragments don't break unrelated components

## Migration Checklist

1. Start with leaf components (no children)
2. Always use `computed()` with `useFragment` for Vue reactivity
3. Update TypeScript interfaces to use `FragmentType`
4. Run `npm run codegen` after fragment changes

## What's Next?

This is Part 3 of our Vue 3 + GraphQL series:

1. **Part 1**: Setting up Apollo Client with Vue 3
2. **Part 2**: Type-safe queries with GraphQL Code Generator
3. **Part 3**: Advanced fragments and component-driven data fetching (current)
4. **Part 4**: GraphQL Caching Strategies in Vue 3 (coming next!)

## Other Fragment Use Cases

Beyond component-driven data fetching, fragments offer additional powerful patterns:

- **Fragments on Unions and Interfaces**: Handle polymorphic types with inline fragments (`... on Type`)
- **Batch Operations**: Share field selections between queries, mutations, and subscriptions
- **Schema Documentation**: Use fragments as living documentation of data shapes
- **Testing**: Create fragment mocks for isolated component testing
- **Fragment Composition**: Build complex queries from simple, reusable pieces

For more advanced fragment patterns, see the [Vue Apollo Fragments documentation](https://apollo.vuejs.org/guide-composable/fragments).

## Source Code

Find the full demo for this series here: [example](https://github.com/alexanderop/vue-graphql-simple-example)

**Note:** The code for this tutorial is on the `part3` branch.

```bash
git clone https://github.com/alexanderop/vue-graphql-simple-example.git
cd vue-graphql-simple-example
git checkout part3
```

---

--- title: How I Use Claude Code for Doing SEO Audits description: Learn how to leverage Claude Code with Puppeteer MCP to perform comprehensive SEO audits in minutes, complete with automated analysis and actionable reports. tags: ['claude-code', 'ai', 'seo'] url: https://alexop.dev/posts/how-i-use-claude-code-for-doing-seo-audits ---

# How I Use Claude Code for Doing SEO Audits



I'm building a Nuxt blog starter called [NuxtPapier](https://github.com/alexanderop/NuxtPapier). Like any developer who wants their project to show up in search results, I needed to make sure it works well with search engines. Manual SEO audits take too much time and I often miss things, so I used Claude Code with Puppeteer MCP to do this automatically.

## What is Claude Code?

Claude Code is Anthropic's official command-line tool that brings AI help right into your coding workflow. Think of it like having a skilled developer sitting next to you, ready to help with any coding task. What makes it really powerful for SEO audits is that it can use MCP (Model Context Protocol) tools. For a deeper look at what Claude Code can do, see my [[understanding-claude-code-full-stack|overview of the full Claude Code feature stack]].

## Enter Puppeteer MCP

> **What is MCP?**  
> According to [Anthropic's official documentation](https://www.anthropic.com/news/model-context-protocol), the Model Context Protocol (MCP) is "an open standard that enables developers to build secure, two-way connections between their data sources and AI-powered tools." It provides a universal interface for connecting AI systems with external tools, systems, and data sources, replacing fragmented integrations with a single protocol.

MCP lets Claude Code connect with outside tools and services. I was using the [Puppeteer MCP server](https://github.com/merajmehrabi/puppeteer-mcp-server) which gives Claude Code the power to:

- Control a real web browser with code
- Go to any website
- Take screenshots
- Pull data from web pages
- Check page structure and speed

This means Claude Code can visit your website, look at it the same way search engines do, and give you detailed insights.

```mermaid
---
title: Claude Code SEO Audit Workflow
---
graph LR
    A[Claude Code CLI] --> B[Puppeteer MCP]
    B --> C[Real Browser Instance]
    C --> D[Your Website]
    D --> E[Extract Data]
    E --> F[SEO Analysis]
    F --> G[Comprehensive Report]
```

## My SEO Audit Prompt

Here's the exact prompt I used:

```
You are a SEO expert your name is John Wick. I gave you so much money now you have to do a SEO audit for this blog. When you are done write down everything into a own markdown file so I can solve the problems later. Use Puppeteer MCP, the server is already running.
```

Simple and direct. It uses Claude Code's ability to act like an expert while using the Puppeteer tools.

Claude Code quickly responded with:

> "I'll do a complete SEO audit for your blog, Senpai Alex. Let me start by making a plan and then checking your site using Puppeteer."

## The Automated Process

One of the coolest things is how Claude Code organizes itself by making todos. It quickly made its own plan:

**Claude Code's Self-Generated Todo List:**

- [ ] Navigate to the homepage and take screenshots
- [ ] Analyze meta tags and SEO elements
- [ ] Check blog post pages for optimization
- [ ] Evaluate page structure and heading hierarchy
- [ ] Analyze site performance and loading times
- [ ] Check mobile responsiveness
- [ ] Review robots.txt and sitemap availability
- [ ] Document all findings in a markdown report

What amazed me was how Claude Code worked through each todo step by step, using Puppeteer to get real data from my site - checking meta tags, measuring how fast pages load, checking structured data, and even taking mobile screenshots. It checked off each item as it finished them.

While working, Claude Code told me what it found:

> "I found a big SEO problem - the robots meta tag says 'noindex, nofollow' which stops search engines from finding your site. This is a major issue."

```mermaid
---
title: Automated SEO Analysis Process
---
sequenceDiagram
    participant CC as Claude Code
    participant P as Puppeteer
    participant B as Browser
    participant W as Website

    CC->>CC: Generate Todo List
    CC->>P: Initialize browser session
    P->>B: Launch browser

    loop For each SEO check
        CC->>P: Navigate to page
        P->>B: Go to URL
        B->>W: Load page
        W->>B: Return content
        B->>P: Extract data
        P->>CC: Return analysis data
        CC->>CC: ✓ Mark todo complete
    end

    CC->>CC: Generate final report
```

## The Report

Claude Code created a detailed SEO audit report that I could actually use. It included:

**Critical Issues:**

- My site had `noindex, nofollow` meta tags (development setting blocking all search engines!)
- robots.txt was blocking all crawlers
- Duplicate H1 tags on blog posts

**Positive Findings:**

- Proper structured data implementation
- Good mobile responsiveness
- Fast page load times (200ms)
- Clean URL structure

**What to Fix:**

- Quick fixes with code examples
- Short-term improvements ranked by importance
- Long-term improvement plans

The report even told me exactly which files to change and what code to fix.

Claude Code wrapped up with:

> "The audit found big blocking problems - search engines can't see your site because of noindex, nofollow meta tags and development robots.txt settings. But the good news is your blog has great technical basics with proper structured data, mobile-friendly design, and fast loading."

```mermaid
---
title: SEO Audit Report Structure
---
mindmap
  root((SEO Audit Report))
    Critical Issues
      noindex/nofollow tags
      Blocked robots.txt
      Duplicate H1 tags
    Positive Findings
      Structured data ✓
      Mobile responsive ✓
      Fast load times ✓
      Clean URLs ✓
    Recommendations
      Immediate fixes
        Code examples
        File locations
      Short-term improvements
        Priority ranking
      Long-term strategies
        Enhancement roadmap
```

## Why This Workflow Works So Well

1. **Speed**: Claude Code finished in minutes what would take me hours to do by hand
2. **Complete**: Claude Code checked things I might have missed
3. **Useful Results**: Not just problems, but solutions with code examples
4. **Documentation**: Everything saved in a markdown file I can use later

## Getting Started

To copy this workflow:

1. Install Claude Code: `npm install -g @anthropic/claude-code`
2. Set up the [Puppeteer MCP server](https://github.com/merajmehrabi/puppeteer-mcp-server)
3. Start your development server
4. Give Claude Code a clear prompt about what you want checked

Claude Code's smarts plus Puppeteer's browser control makes a powerful SEO audit tool that any developer can use. No more guessing about SEO problems - just run the audit and get a professional report in minutes. You can further automate workflows like this using [[claude-code-customization-guide-claudemd-skills-subagents|CLAUDE.md, skills, and subagents]].

Try it on your own projects and see what SEO problems you might be missing!

---

--- title: The Age of the Generalist description: How AI is transforming software development and why high-agency generalists will thrive in this new era of technology. tags: ['ai'] url: https://alexop.dev/posts/the-age-of-the-generalist ---

# The Age of the Generalist



AI this, AI that. Like many of you, I'm constantly switching between _"Wow, you can do that with AI?"_ and _"Ugh, not AI again."_

But here we are. AI is changing how we work and how we live.
I’m a millennial. The last major disruption technology brought to my life was social media (and then the iPhone).

Now there is a new wave coming. It will slowly change everything.

And yes, it is AI.

How does AI change the work of software developers?

Short answer: we will all become more like generalists.

This shift is already happening. Most teams no longer separate frontend and backend. They hire full-stack developers. This helps teams move faster. Traditional separation creates communication overhead and slows execution.

So we are already becoming generalists.

If you join a startup as a dev, you will not find neat job titles. There is no budget for that. You wear whatever hat the day requires.

Now add AI to the mix.

Tasks that took hours , writing code, setting up tooling , can now be done in minutes. You can delegate to AI, generate boilerplate, spin up components, scaffold tests. You can work in parallel. You will probably spend more time reading code than writing it.

But AI has no understanding of architecture. It does not know what good design looks like. It cannot distinguish between cohesion and coupling. It does not know when to break something into modules or when to leave it flat. It has no initiative. It only works when a human prompts it.

That is why **high agency** is more important than ever.

AI does not replace builders. It replaces waiters.
If you wait to be told what to do, you will fall behind.
If you take action, ask questions, and push things forward, you will stay ahead.

High agency means seeing a mess and deciding what to clean up. It means figuring out what matters without someone else making the roadmap.
AI can give you answers, but it will never tell you what is worth building.

So what should developers focus on?

Become a generalist with high agency.

Think of Leonardo da Vinci. He painted _The Last Supper_ and _Mona Lisa_. He dissected human bodies and sketched the nervous system. He designed flying machines. He wrote about optics, engineering, and warfare.
He did not pick a lane. He learned widely and built from what he learned.

That mindset , curious, self-directed, and hands-on , is what will matter most in the age of AI.

---

--- title: How I Use LLMs description: Learn how I use LLMs to improve my productivity and efficiency. tags: ['ai', 'productivity'] url: https://alexop.dev/posts/how-i-use-llms ---

# How I Use LLMs



Motivated by the awesome YouTube video from Andrew Karpathy [How I use LLMs](https://www.youtube.com/watch?v=EWvNQjAaOHw), I decided to give two talks on how I use LLMs, both at my company and at the TypeScript meetup in Munich.

This blog post is the written version of those talks.

Keep in mind that while some things might change, especially regarding the models I currently use, I hope these tips will remain helpful for a long time.

<Figure
  src={cover}
  alt="Cover"
  width={600}
  class="mx-auto"
  caption="Dev doing many things"
/>

As a junior developer, you might think your job is all about coding. However, as you gain experience, you realize that's not entirely true. We developers spend a significant amount of time learning new things or explaining concepts to others. That's why, when it comes to using LLMs, we shouldn't focus solely on code generation.

We should also consider how to:

- **Research faster**
- **Document better**
- **Learn more effectively**

Most of my tips won't be about how to use Cursor AI or Copilot better. I think that would be worth its own blog post or a short video.

## Which model should I choose

<Figure
  src={which}
  alt="Which model should I choose"
  width={800}
  class="mx-auto"
  caption="Which model should I choose"
/>

It's annoying that we even have to think about which model to use for which task. I would guess that in the future (Cursor AI is already doing this), there will be a model as a kind of router in the middle that understands which prompt relates to which model.

But for now, this isn't the case, so here's my guideline. In the picture, you see that I came up with four categories:

1. **Everyday tasks** (like fixing spelling, writing something better)
2. **Quick Refactoring** (like adding console logs to debug something, small refactorings)
3. **Technical Tasks** (like doing research)
4. **Complex Tasks** (tasks that definitely need long reasoning and thinking)

It's important for me, since I don't have an unlimited amount of o3, for example, to try to use o4-mini-high if I think I don't need long reasoning for something.

As I said, these models will change daily, but I think the categories will remain.

So most of the time, I ask myself if I need a model that requires reasoning or not.

## o3 is a mini agent

What's also clear is that new models like o3 are mini agents. This means they're not only predicting the next token but also have tools. With these tools, they can gain better context or perform operations with Python.

This is why Simon Willison's blog post explains how he used o3 to guess his location. As his title says: Watching o3 guess a photo's location is surreal, dystopian, and wildly entertaining, but it also shows how powerful this can be. Read his blog post [here](https://simonwillison.net/2025/Apr/26/o3-photo-locations/).

I also wrote a blog post once where I gave o3 a hard chess puzzle to solve. Feel free to read it [here](../how-03-model-tries-chess-puzzle).

## Some tips on how to get more out of Copilot and co

My first tip is to index your codebase, either with a local index or remote. With this, Cursor or Copilot can perform better searches.

It all falls back to automatic retrieval. Keep in mind that an LLM doesn't know where your files are located. So it always has to search against your codebase.

One technique besides keyword search that can help is dense vector or embedding search. You can read the docs on how to implement that.

Another tip: when you have a project that's indexed, you can use Copilot's ask mode and use @workspace. Now you can ask business questions or even solve simple tickets in one shot (if there are well-written tickets). For more information on how to index your repositories for Copilot Chat, refer to the [GitHub Copilot documentation](https://docs.github.com/en/copilot/using-github-copilot/copilot-chat/indexing-repositories-for-copilot-chat).

My last tip, where I use Gemini 2.0 Flash or GPT-4.1, is to do little refactorings or code changes quickly. I quickly mark the related lines and then use a prompt to make the changes.

## How can we improve the output of an LLM

<Figure
  src={improveLlm}
  alt="How can we improve the output of an LLM"
  width={800}
  class="mx-auto"
  caption="How can we improve the output of an LLM"
/>

In the book ["AI Engineering"](https://www.oreilly.com/library/view/ai-engineering/9781098166298/) by Chip Huyen, she explains that there are three main ways to improve the output of an LLM:

1. **With Prompts**
2. **Per RAG**
3. **With fine-tuning**

Of course, all three ways will increase in effort and maybe ROI, but it's clear that better prompts are always the first step to improving the output of an LLM.

## The almighty System Prompt

The idea of a System Prompt is simple but genius. We change the default behavior of an LLM and customize it to our needs.

<Figure
  src={systemPrompt}
  alt="The almighty System Prompt"
  width={800}
  class="mx-auto"
  caption="The almighty System Prompt"
/>

In the picture, you see an example of a system prompt that I use to write blog posts.

In the picture, you see an example of a system prompt that can be used to write Jira tickets. At work, I have something like that and use it together with Copilot. My goal is to quickly write what needs to be done, and the LLM handles the rest. It also asks questions when something is not clear.

You can use that for many problems, and also keep in mind that every LLM provider, like OpenAI or Claude, has their own system prompt. One use case, for example, is to explain which tools an LLM has available, etc. At [GitHub](https://github.com/jujumilk3/leaked-system-prompts), you can read some of the leaked system prompts.

This is why this is a good structure to think about when you write system prompts:

1. **Role Definition**
2. **Step-by-Step Instructions**
3. **Output Format**
4. **Edge Cases**
5. **Style Guidelines**

When you tell the LLM which role it has, it will already use words and tokens that are useful for this role in its next prediction.

Clear steps can help for a more complex workflow so the LLM knows when it's done, etc.

For something like a Jira ticket, we should also add a concrete output format with an example.

In my experience, edge cases are something that you will add over time. We need to play with the LLM and see what vibe we get from it.

Style guidelines are useful. For example, I love easy words and active voice.

You can also ask the LLM how a system prompt should look for the problem you want to solve and use that as your version 1. This approach can provide a solid starting point for further refinement.

## Googling is dead

Don't get me wrong, I think Google is winning the AI arms race. As noted in [The Algorithmic Bridge](https://www.thealgorithmicbridge.com/p/google-is-winning-on-every-ai-front), Google is excelling on every AI front. But the classical googling, where we typed a query and the first five results had an ad and it was hard to find an organic result, is over.

<Figure
  src={goggelingISDead}
  alt="Googling is dead"
  width={500}
  class="mx-auto"
  caption="Googling is dead"
/>

Most of the time, I use a reasoning model with a web search tool. This helps me as a starter to find related blog posts, etc., for my problem. I only use Google when I know the site I want to reach or I know which blog post I want to read.

## Get all tokens out of a repo

If you change GitHub to Uithub for any repo, you will get all text in a way that you can just copy-paste it into a model with a high context, like Google Gemini.

This can be useful to either ask questions against the codebase or to learn how it works or to rebuild something similar without needing to increase the depth of your node modules.

<Figure
  src={bruceExtractCodebase}
  alt="Get all tokens out of a repo"
  width={800}
  class="mx-auto"
  caption="Get all tokens out of a repo"
/>

## Generate a Wiki out of any repo

When you go to https://deepwiki.org/, you can generate a wiki out of any repo. Useful for understanding other repos or even for your own little side projects. What I like is that the LLMs generate mermaid diagrams, and sometimes they are really useful.

## Generate diagrams

I think there are now three ways to generate good diagrams with an LLM:

1. **As SVG**
2. **As Mermaid**
3. **Or as a picture with the new model**

I already wrote about how to use ChatGPT to generate mermaid diagrams. Read it [here](../how-to-use-ai-for-effective-diagram-creation-a-guide-to-chatgpt-and-mermaid).

## Rules Rules Rules

We human developers need rules, and the same is true for LLMs to write better code. This is why both Copilot and Cursor have their own rule system. For detailed information on how to set up and use rules in Cursor, check out the [official Cursor documentation on rules](https://docs.cursor.com/context/rules).

One idea when you have a monorepo could be something like this:

```plaintext
my-app/
├── .cursor/
│   └── rules/
│       └── project-guidelines.mdc       # General code style, naming, formatting
├── frontend/
│   ├── .cursor/
│   │   └── rules/
│   │       ├── vue-components.mdc       # Naming + structure for components
│   │       └── tailwind-usage.mdc       # Utility-first CSS rules
│   └── src/
│       └── ...
├── backend/
│   ├── .cursor/
│   │   └── rules/
│   │       ├── api-structure.mdc        # REST/GraphQL structure conventions
│   │       └── service-patterns.mdc     # How to organize business logic
│   └── src/
│       └── ...
├── shared/
│   ├── .cursor/
│   │   └── rules/
│   │       └── shared-types.mdc         # How to define + use shared TypeScript types
│   └── src/
│       └── ...
├── README.md
└── package.json
```

One rule could then look like this:

```mdc
---
description: Base project guidelines and conventions
globs:
  - "**/*.ts"
  - "**/*.vue"
alwaysApply: false
---

- **Use `PascalCase` for component names.**
- **Use `camelCase` for variables, functions, and file names (except components).**
- **Prefer composition API (`setup()`) over options API.**
- **Type everything. Avoid `any` unless absolutely necessary.**
- **Keep files under 150 LOC. Split logic into composables or utilities.**
- **Use absolute imports from `@/` instead of relative paths.**
- **Every module must have tests that reflect the feature's acceptance criteria.**
- **Commit messages must follow Conventional Commits format.**
- **Use TODO: and FIXME: comments with your initials (e.g., `// TODO: refactor`).**
- **Format code with Prettier. Lint with ESLint before committing.**

Referenced files:
@.eslintrc.js
@.prettierrc
@tsconfig.json
```

This is an example for Cursor. The idea is to give a more fine-grained context. In our example, maybe it would even be better to only have a .vue and separate .ts rule.

In Agent mode, Cursor will then automatically apply this rule as context.

## Write better image prompts

One technique that I think can be useful is to describe which image you want and then say, "give me that back as a Midjourney prompt." This has the advantage that the description of the image is nicely formatted.

## When should you use an LLM directly

An interesting question that I got from the TypeScript meetup was when I would directly vibe code and just tell Cursor to implement feature X and when not.

In my experience, it all depends on the topic and how much training data is available for that.

For example, last week I was using Nuxt together with NuxtUI, a good UI library for Nuxt, but the problem was that the LLM doesn't understand how the components are structured, etc. So in that case, it would be better if I were the main driver and not the LLM.

So always ask yourself if there is enough training data out there for your problem. Was it already solved in the past?

Sometimes you will waste time by just blindly doing vibe coding.

## Summary

There are many ways we developers can use LLMs to be more productive and also have more fun. I believe most of us don't want to spend too much time writing tickets. This is where LLMs can help us. I believe it's important to be open and try out these tools.

If you want to get better with these tools, also try to understand the fundamentals. I wrote a blog post explaining [how ChatGPT works](../how-chatgpt-works-for-dummies) that might help you understand what's happening under the hood.

---

--- title: No Server, No Database: Smarter Related Posts in Astro with `transformers.js` description: How I used Hugging Face embeddings to create smart “Related Posts” for my Astro blog—no backend, no database, just TypeScript. tags: ['ai', 'astro', 'typescript'] url: https://alexop.dev/posts/semantic-related-posts-astro-transformersjs ---

# No Server, No Database: Smarter Related Posts in Astro with `transformers.js`



I recently read a interesting blog post about Embeddings at [Embeddings in Technical Writing](https://technicalwriting.dev/ml/embeddings/overview.html):

> “I could tell you exactly how to advance technical writing with embeddings, but where’s the fun in that?”

Challenge accepted!
In this post, I show how I used **Hugging Face’s `transformers.js`** to create smarter related-post suggestions for my Astro blog, without servers or databases.

## Why Embeddings Are Better Than Tags

Tags group posts by labels, but not by meaning. Posts about Vue 3 and deep reactivity concepts get mixed up together.
Embeddings capture the meaning of text using numeric vectors. Two posts become related when their content is similar, not just when tags match.

### Vectors and Cosine Similarity

Words like “cat” and “kitty” are close in meaning, while “dog” is slightly different:

| word  | vector     |
| ----- | ---------- |
| cat   | `[0, 1]`   |
| kitty | `[0, 0.9]` |
| dog   | `[1, -1]`  |

Cosine similarity measures how similar these vectors are.
For a deeper dive into TypeScript and vectors, check out my post on [How to Implement a Cosine Similarity Function in TypeScript for Vector Comparison](../how-to-implement-a-cosine-similarity-function-in-typescript-for-vector-comparison/).

## Transformers.js in Action

`transformers.js` lets you run Hugging Face models directly in JavaScript:

```ts
const model = "sentence-transformers/all-MiniLM-L6-v2";
const extractor = await pipeline("feature-extraction", model);

const embedding = await extractor("Hello, world!", {
  pooling: "mean",
  normalize: true,
});

console.log(embedding); // Float32Array with 384 dimensions
```

You don't need Python or a server. Everything runs in your browser or Node.js.

## My Simple Workflow

Here's how my workflow works:

1. Load markdown files (`.md` or `.mdx`) from my blog.
2. Remove markdown formatting to get plain text.
3. Use `transformers.js` to create embeddings.
4. Calculate cosine similarity between all posts.
5. Find the top 5 most related posts for each post.
6. Save the results in a JSON file (`similarities.json`).
7. Display these related posts with Astro.

### Main Script (TypeScript)

```ts
// --------- Configurations ---------
const GLOB = "src/content/**/*.{md,mdx}"; // Where to find Markdown content
const OUT = "src/assets/similarities.json"; // Output file for results
const TOP_N = 5; // Number of similar docs to keep
const MODEL = "Snowflake/snowflake-arctic-embed-m-v2.0"; // Embedding model

// --------- Type Definitions ---------
interface Frontmatter {
  slug: string;
  [k: string]: unknown;
}
interface Document {
  path: string;
  content: string;
  frontmatter: Frontmatter;
}
interface SimilarityResult extends Frontmatter {
  path: string;
  similarity: number;
}

// --------- Utils ---------

/**
 * Normalizes a vector to unit length (L2 norm == 1)
 * This makes cosine similarity a simple dot product!
 */
function normalize(vec: Float32Array): Float32Array {
  let len = Math.hypot(...vec); // L2 norm
  if (!len) return vec;
  return new Float32Array(vec.map(x => x / len));
}

/**
 * Computes dot product of two same-length vectors.
 * Vectors MUST be normalized before using this for cosine similarity!
 */
const dot = (a: Float32Array, b: Float32Array) =>
  a.reduce((sum, ai, i) => sum + ai * b[i], 0);

/**
 * Strips markdown formatting, import/export lines, headings, tables, etc.
 * Returns plain text for semantic analysis.
 */
const getPlainText = async (md: string) => {
  let txt = String(await remark().use(strip).process(md))
    .replace(/^import .*?$/gm, "")
    .replace(/^export .*?$/gm, "")
    .replace(
      /^\s*(TLDR|Introduction|Conclusion|Summary|Quick Setup Guide|Rules?)\s*$/gim,
      ""
    )
    .replace(/^[A-Z\s]{4,}$/gm, "")
    .replace(/^\|.*\|$/gm, "")
    .replace(/(Rule\s\d+:.*)(?=\s*Rule\s\d+:)/g, "$1\n")
    .replace(/\n{3,}/g, "\n\n")
    .replace(/\n{2}/g, "\n\n")
    .replace(/\n/g, " ")
    .replace(/\s{2,}/g, " ")
    .trim();
  return txt;
};

/**
 * Parses and validates a single Markdown file.
 * - Extracts frontmatter (slug, etc.)
 * - Converts content to plain text
 * - Skips drafts or files with no slug
 */
async function processFile(path: string): Promise<Document | null> {
  try {
    const { content, data } = matter(fs.readFileSync(path, "utf-8"));
    if (!data.slug || data.draft) return null;
    const plain = await getPlainText(content);
    return { path, content: plain, frontmatter: data as Frontmatter };
  } catch {
    return null;
  }
}

/**
 * Processes an array of Markdown file paths into Documents
 */
async function loadDocs(paths: string[]) {
  const docs: Document[] = [];
  for (const p of paths) {
    const d = await processFile(p);
    if (d) docs.push(d);
  }
  return docs;
}

/**
 * Generates vector embeddings for each document's plain text.
 * - Uses HuggingFace model
 * - Normalizes each vector for fast cosine similarity search
 */
async function embedDocs(
  docs: Document[],
  extractor: FeatureExtractionPipeline
) {
  if (!docs.length) return [];
  // Don't let the model normalize, we do it manually for safety
  const res = (await extractor(
    docs.map(d => d.content),
    { pooling: "mean", normalize: false }
  )) as any;
  const [n, dim] = res.dims;
  // Each embedding vector is normalized for performance
  return Array.from({ length: n }, (_, i) =>
    normalize(res.data.slice(i * dim, (i + 1) * dim))
  );
}

/**
 * Computes the top-N most similar documents for the given document index.
 * - Uses dot product of normalized vectors for cosine similarity
 * - Returns only the top-N
 */
function topSimilar(
  idx: number,
  docs: Document[],
  embs: Float32Array[],
  n: number
): SimilarityResult[] {
  return docs
    .map((d, j) =>
      j === idx
        ? null
        : {
            ...d.frontmatter,
            path: d.path,
            similarity: +dot(embs[idx], embs[j]).toFixed(2), // higher = more similar
          }
    )
    .filter(Boolean)
    .sort((a, b) => (b as any).similarity - (a as any).similarity)
    .slice(0, n) as SimilarityResult[];
}

/**
 * Computes all similarities for every document, returns as {slug: SimilarityResult[]} map.
 */
function allSimilarities(docs: Document[], embs: Float32Array[], n: number) {
  return Object.fromEntries(
    docs.map((d, i) => [d.frontmatter.slug, topSimilar(i, docs, embs, n)])
  );
}

/**
 * Saves result object as JSON file.
 * - Ensures output directory exists.
 */
async function saveJson(obj: any, out: string) {
  fs.mkdirSync(path.dirname(out), { recursive: true });
  fs.writeFileSync(out, JSON.stringify(obj, null, 2));
}

// --------- Main Execution Flow ---------
async function main() {
  try {
    // 1. Load transformer model for embeddings
    const extractor = await pipeline("feature-extraction", MODEL);

    // 2. Find all Markdown files
    const files = await glob(GLOB);
    if (!files.length)
      return console.log(chalk.yellow("No content files found."));

    // 3. Parse and process all files
    const docs = await loadDocs(files);
    if (!docs.length) return console.log(chalk.red("No documents loaded."));

    // 4. Generate & normalize embeddings
    const embs = await embedDocs(docs, extractor);
    if (!embs.length) return console.log(chalk.red("No embeddings."));

    // 5. Calculate similarities for each doc
    const results = allSimilarities(docs, embs, TOP_N);

    // 6. Save results to disk
    await saveJson(results, OUT);
    console.log(chalk.green(`Similarity results saved to ${OUT}`));
  } catch (e) {
    console.error(chalk.red("Error:"), e);
    process.exitCode = 1;
  }
}

main();
```

## This Will Produce a JSON file with the following structure:

```json
{
  "vue-introduction": [
    {
      "slug": "typescript-advanced-types",
      "title": "Advanced Types in TypeScript",
      "date": "2024-06-03T00:00:00.000Z",
      "path": "src/content/typescript-advanced-types.md",
      "similarity": 0.35
    }
    // Additional similar documents...
  ]
  // Additional document entries...
}
```

### Astro Component

```astro
---
if (similarities[post.slug]) {
  mostRelatedPosts = similarities[post.slug]
    .filter((p: RelatedPost) => !p.draft)
    .sort(
      (a: RelatedPost, b: RelatedPost) =>
        (b.similarity ?? 0) - (a.similarity ?? 0)
    )
    .slice(0, 3);
}
---

{
  mostRelatedPosts.length > 0 && (
    <div data-pagefind-ignore class="mb-8 mt-16">
      <h2 class="mb-6 text-3xl font-bold text-skin-accent">
        Most Related Posts
      </h2>
      <div class="md:grid-cols-3 grid grid-cols-1 gap-6">
        {mostRelatedPosts.map((relatedPost: RelatedPost) => (
          <a
            href={`/posts/${relatedPost.slug}/`}
            class="related-post-card group"
          >
            <div class="p-5">
              <h3 class="related-post-title">{relatedPost.title}</h3>
              <p class="related-post-description">{relatedPost.description}</p>
              <div class="flex items-center justify-between text-xs text-skin-base text-opacity-60">
                <Datetime
                  pubDatetime={relatedPost.pubDatetime}
                  modDatetime={relatedPost.modDatetime}
                  size="sm"
                />
                <span class="related-post-tag">{relatedPost.tags?.[0]}</span>
              </div>
            </div>
          </a>
        ))}
      </div>
    </div>
  )
}
```

## Does It Work?

Yes! Now, my blog suggests truly related content, not random posts.

---

## What I Learned

- **No extra servers or databases**: Everything runs during build time.
- **Easy to use**: Works in both browsers and Node.js.
- **Flexible**: Quickly change the model or method.

If you have a static blog and want better recommendations, give embeddings and Astro a try. Let me know how it goes!

Of course, this is far from perfect. I also don't know which model would be ideal, but at the moment I'm getting much better related posts than before, so I'm happy with the results.
If you want to play with the script yourself check out [post-matcher-ai](https://github.com/alexanderop/post-matcher-ai)

---

--- title: Type-Safe GraphQL Queries in Vue 3 with GraphQL Code Generator description: Part 2 of the Vue 3 + GraphQL series: generate fully-typed `useQuery` composables in Vue 3 with GraphQL Code Generator tags: ['graphql', 'vue'] url: https://alexop.dev/posts/type-safe-graphql-queries-vue3-codegen ---

# Type-Safe GraphQL Queries in Vue 3 with GraphQL Code Generator



<Figure
  src={Workflow}
  alt="GraphQL Codegen Workflow"
  width={800}
  class="mx-auto"
  caption="GraphQL Codegen Workflow"
/>

## Why plain TypeScript isn't enough

If you hover over the `result` from `useQuery` in last week's code, you'll still see `Ref<any>`. That means:

```vue
<li v-for="c in result?.countries2" :key="c.code"></li>
```

…slips right past TypeScript.

<Figure
  src={anyIsBad}
  alt="Any is bad"
  width={400}
  class="mx-auto"
  caption="`any` sneaking past TypeScript"
/>

It's time to bring in **GraphQL Code Generator** which gives us:

- 100% typed operations, variables, and results
- Build-time schema validation (_fail fast, ship safe_)

## Step 1: Install the right packages

Let's start by installing the necessary dependencies:

```bash
npm i graphql
npm i -D typescript @graphql-codegen/cli
npm i -D @parcel/watcher
```

> 🚨 `@parcel/watcher` is a dev dependency.

## Step 2: Create a clean `codegen.ts`

Next, use the CLI to generate your config file:

```bash
npx graphql-code-generator init
```

When prompted, answer as follows:

```bash
? What type of application are you building? Application built with Vue
? Where is your schema?: (path or url) https://countries.trevorblades.com/graphql
? Where are your operations and fragments?: src/**/*.vue
? Where to write the output: src/gql/
? Do you want to generate an introspection file? No
? How to name the config file? codegen.ts
? What script in package.json should run the codegen? codegen
Fetching latest versions of selected plugins...
```

Your generated `codegen.ts` should look like this:

```ts
const config: CodegenConfig = {
  overwrite: true,
  schema: "https://countries.trevorblades.com/graphql",
  documents: "src/**/*.vue",
  generates: {
    "src/gql/": {
      preset: "client",
      plugins: [],
    },
  },
};

export default config;
```

## Step 3: Add dev scripts and watch mode

Update your `package.json` scripts to streamline development:

```json
{
  "scripts": {
    "codegen": "graphql-codegen --config codegen.ts",
    "codegen:watch": "graphql-codegen --watch --config codegen.ts"
  }
}
```

## Step 4: Write your first typed query

Create a new file at `src/queries/countries.graphql`:

```graphql
query AllCountries {
  countries {
    code
    name
    emoji
  }
}
```

Then, generate your types:

```bash
npm run codegen
```

The command writes all generated types to `src/gql/`.

### Update your `CountryList.vue` component to use the generated types

```vue
<script setup lang="ts">
const { result, loading, error } = useQuery(AllCountriesDocument);
const countries = computed(() => result.value?.countries);
</script>
```

<Figure
  src={typedQuery}
  alt="Typed query"
  width={400}
  class="mx-auto"
  caption="Goodbye `any`, hello types"
/>

### Inline queries with the generated `graphql` tag

Alternatively, define the query directly in your component using the generated `graphql` tag:

```vue
<script setup lang="ts">
const COUNTRIES_QUERY = graphql(`
  query AllCountries {
    countries {
      code
      name
      emoji
    }
  }
`);

const { result, loading, error } = useQuery(COUNTRIES_QUERY);
const countries = computed(() => result.value?.countries);
</script>
```

## Watch mode

With `@parcel/watcher` installed, you can enable watch mode for a smoother development experience. If you frequently change your GraphQL schema while developing, simply run:

```bash
npm run codegen:watch
```

GraphQL Code Generator immediately throws an error when your local operations drift from the live schema.
Remember, your GraphQL server needs to be running for this to work.

## Bonus: Proper validation out of the box

A powerful benefit of this setup is **automatic validation**. If the Countries GraphQL API ever changes—say, it renames `code` to `code2`—you'll get an error when generating types.

For example, if you query for `code2`, you'll see:

```bash
⚠ Generate outputs
  ❯ Generate to src/gql/
    ✔ Load GraphQL schemas
    ✔ Load GraphQL documents
    ✖ GraphQL Document Validation failed with 1 errors;
      Error 0: Cannot query field "code2" on type "Country". Did you mean "code"?
```

## Should you commit generated files?

A common question: should you commit the generated types to your repository?

| Strategy        | Pros                              | Cons                                 |
| --------------- | --------------------------------- | ------------------------------------ |
| **Commit them** | Fast onboarding · Diff visibility | Noisy PRs · Merge conflicts          |
| **Ignore them** | Clean history · Zero conflicts    | Extra `npm run generate` in CI/local |

Many teams choose to commit generated files, **but** enforce `npm run generate -- --check` in CI to guard against stale artifacts.

## Up next (Part 3)

- **Fragments without repetition**

## Summary & Key Takeaways

In this part of the Vue 3 + GraphQL series, we:

- Set up GraphQL Code Generator v5 to create fully-typed queries and composables for Vue 3
- Learned how to configure `codegen.ts` for a remote schema and local `.vue` operations
- Automated type generation with dev scripts and watch mode for a smooth DX
- Used generated types and the `graphql` tag to eliminate `any` and catch schema errors at build time
- Discussed whether to commit generated files and best practices for CI

### What you learned

- How to make your GraphQL queries type-safe and schema-validated in Vue 3
- How to avoid runtime errors and catch breaking API changes early
- How to streamline your workflow with codegen scripts and watch mode
- The tradeoffs of committing vs. ignoring generated files in your repo

### Actionable reminders

- Always run `npm run generate` after changing queries or schema
- Use the generated types in your components for full type safety
- Consider enforcing type checks in CI to prevent stale artifacts

Stay tuned for Part 3, where we'll cover fragments and avoid repetition in your queries!

## Source Code

Find the full demo for this series here: [example](https://github.com/alexanderop/vue-graphql-simple-example)

> **Note:**  
> The code for this tutorial is on the `part-two` branch.  
> After cloning the repository, make sure to check out the correct branch:
>
> ```bash
> git clone https://github.com/alexanderop/vue-graphql-simple-example.git
> cd vue-graphql-simple-example
> git checkout part-two
> ```
>
> [View the branch directly on GitHub](https://github.com/alexanderop/vue-graphql-simple-example/tree/part-two)

---

--- title: LLM-Powered Search: o4-mini-high vs o3 vs Deep Research description: A practical benchmark of three OpenAI models—o4-mini-high, o3, and Deep Research—for LLM-powered search. Compare their speed, depth, accuracy, citations, and cost when tackling real research questions like 'How does Vercel use Speakeasy for API testing?Ideal for developers exploring AI-assisted technical research tags: ['ai'] url: https://alexop.dev/posts/llm-powered-search-comparison-o4-mini-high-o3-deep-research ---

# LLM-Powered Search: o4-mini-high vs o3 vs Deep Research



## tldr:

> **Prompt:** "How does Vercel use Speakeasy for API testing?"

| Feature / Model       | o-4-mini-high                     | o3                                      | Deep Research                              |
| --------------------- | --------------------------------- | --------------------------------------- | ------------------------------------------ |
| **Speed**             | ⚡ Instant                        | 🕒 Conversational                       | 🐢 Slower                                  |
| **Depth of Response** | 🟢 Basic facts                    | 🟡 Balanced depth                       | 🔵 Comprehensive analysis                  |
| **Citation Quality**  | Inline links only                 | Inline links                            | 30+ footnotes                              |
| **Latency Friction**  | None                              | Low                                     | High (3-min delay)                         |
| **Cost**              | 💸 Lowest                         | 💸 Moderate                             | 💸💸 Highest                               |
| **Best Use Case**     | Sanity-checks, quick verification | Background research, architectural docs | Formal research, literature-style analysis |
| **Output Length**     | Medium (~4.8k characters)         | Longer (~7.5k characters)               | Very Long (~13.9k characters)              |
| **Sources Used**      | 10                                | 15                                      | 31                                         |
| **Ideal Context**     | Slack pings, fact-checks          | Blog prep, decision-making              | Deep dive reports, whitepapers             |

## Introduction

While reading about the "Docs as Tests" approach to API documentation, I found something interesting about Vercel using Speakeasy for their API testing. This caught my attention because I wanted to learn more about how they put this into practice.

Last week, Simon Willison had published a compelling argument that modern LLMs have essentially "solved" web search for everyday research tasks (with the caveat that you should still verify any potential inaccuracies). ([AI assisted search-based research actually works now](https://simonwillison.net/2025/Apr/21/ai-assisted-search/))

This gave me an idea: instead of using Google like most people would, I could test different LLM models against each other. I decided to ask three different OpenAI models the same research question:

## Why is this now working?

The key difference with models like o3 is that they're no longer just language models that predict the next token—they're becoming mini agents. This means they can also predict when to call a function or use a tool, like running a Python script or performing a web search.

For example, o3 is often powered by tools like Bing for real-time web access or a Python interpreter for calculations. That’s why it can generate tables, analyze data, and reason with up-to-date information.

Traditional "vanilla" models (that only predict the next token without tools) are limited—they rely solely on their internal knowledge, which can be outdated and prone to hallucinations. But once you give a model access to tools, it can fetch accurate, real-world context on demand, making its next-token prediction much smarter.

## Model Response Analysis

> **Prompt:** "How does Vercel use Speakeasy for API testing?"

### Raw Response Samples

_(First words of each, to give you a feel for the tone)_

### 🟢 o-4-mini-high

Vercel leverages Speakeasy's OpenAPI-driven toolchain to generate both their official TypeScript SDK and a comprehensive suite of contract tests based on their public spec at `https://openapi.vercel.sh` ([sdk/tests-overlay.yaml at main · vercel/sdk · GitHub](https://github.com/vercel/sdk/blob/main/tests-overlay.yaml), [Testing | Speakeasy](https://www.speakeasy.com/product/api-testing)). Using the Speakeasy CLI's `speakeasy test` command, they spin up a mock server and validate every endpoint against its schema automatically ([GitHub - speakeasy-api/speakeasy](https://github.com/speakeasy-api/speakeasy)). To handle endpoints that are still evolving, Vercel maintains a `tests-overlay.yaml` overlay file in their SDK repository, which disables specific tests by annotating operations with `x-speakeasy-test: false` ([sdk/tests-overlay.yaml at main · vercel/sdk · GitHub](https://github.com/vercel/sdk/blob/main/tests-overlay.yaml)). This entire process is woven into their CI/CD via GitHub Actions: running `speakeasy configure tests` scaffolds a "Test SDKs" workflow that executes these tests on every pull request ([Testing in GitHub Actions](https://www.speakeasy.com/docs/customize-testing/github-actions)). As a showcase customer, Vercel is explicitly listed on Speakeasy's product page among world-class API teams using automated API testing in their pipelines ([Testing | Speakeasy](https://www.speakeasy.com/product/api-testing)).

_Thought for 41 seconds · 10 sources_  
_Characters: 4,811_

[Full conversation →](https://chatgpt.com/share/6813248e-cd28-8004-8cb4-ab662014271b)

### 🟡 o3 Result

Speakeasy sits in Vercel's CI/CD pipeline as an **OpenAPI-driven "safety-net"**: every time the Vercel REST-API spec changes, Speakeasy (1) regenerates an SDK, (2) boots a ready-made Bun test-suite that hits live endpoints, and (3) compares the new spec against the last published contract in its registry. The workflow automatically runs in GitHub Actions; if an endpoint breaks schema, status-codes, or core behaviour, the job fails and engineers are alerted before the change ships. Below is a deep-dive into each moving part and how they fit together.

#### Why Vercel Automates API Tests

- Vercel's public API is used by thousands of deploy hooks, CLIs, and partners; even a minor breaking change can halt customer CI pipelines. Speakeasy markets its testing product to "world-class API companies" and lists Vercel as a reference logo, highlighting reliability as a selling point. ([Testing | Speakeasy](https://www.speakeasy.com/product/api-testing?utm_source=chatgpt.com))
- In Speakeasy's Series A announcement the company calls out Vercel as one of the "fast-growing innovators" that relies on automated contract testing to "make sure no unintentional breaking changes get shipped." ([Speakeasy's $15M Series A](https://www.speakeasy.com/post/fundraising-series-a?utm_source=chatgpt.com))

_Thought for 1m 25s · 15 Sources_  
_Characters: 7,483_

[Full conversation →](https://chatgpt.com/share/68132509-ea28-8004-8cf0-beeb88c77577)

### 🔵 Deep Research

#### Vercel's Speakeasy-Powered API Toolchain

Vercel uses Speakeasy to automate its REST API tooling – generating SDKs, docs, mocks and tests from an OpenAPI spec. In late 2024 Vercel announced a new **TypeScript SDK** (`@vercel/sdk`) built with Speakeasy ([Introducing the Vercel TypeScript SDK - Vercel](https://vercel.com/changelog/introducing-the-vercel-typescript-sdk#:~:text=This%20SDK%20includes%3A)). The SDK is **fully type-safe** (using Zod schemas) and provides complete coverage of the Vercel REST API ([Introducing the Vercel TypeScript SDK - Vercel](https://vercel.com/changelog/introducing-the-vercel-typescript-sdk#:~:text=This%20SDK%20includes%3A)) ([Using the Vercel SDK - Vercel API Docs](https://vercel.com/docs/rest-api/sdk#:~:text=The%20%60%40vercel%2Fsdk%60%20is%20a%20type,of%20the%20Vercel%20REST%20API)). In fact, Vercel's SDK repo explicitly notes "SDK Created by Speakeasy" ([GitHub - vercel/sdk](https://github.com/vercel/sdk?trk=public_post_comment-text#:~:text=SDK%20Created%20by%20Speakeasy)). Under the hood, Vercel maintains an OpenAPI spec (`vercel-spec.json`) and a Speakeasy config (`.speakeasy/gen.yaml`) that drives code generation. A GitHub Actions workflow invokes the Speakeasy CLI on each update, regenerating the SDK (and publishing to npm) whenever the API spec changes. This ensures the SDK and docs stay in sync with the API. As a result, every Vercel endpoint is exposed via the SDK with up-to-date **documentation and code examples**, and the generated code is optimized (e.g. "standalone functions" for tree-shaking) ([Introducing the Vercel TypeScript SDK - Vercel](https://vercel.com/changelog/introducing-the-vercel-typescript-sdk#:~:text=,REST%20API%20with%20Zod%20schemas)) ([Using the Vercel SDK - Vercel API Docs](https://vercel.com/docs/rest-api/sdk#:~:text=The%20%60%40vercel%2Fsdk%60%20is%20a%20type,of%20the%20Vercel%20REST%20API)).

_Research completed in 3m · 31 sources_  
_Characters: 13,942_

[Full conversation →](https://chatgpt.com/share/6813258e-4a70-8004-a4ec-a229ac12ac6c)

### Key Finding

For _search-focused_ tasks, **o3 beat Deep Research**. I got almost the same depth but twice as fast and for a fraction of the cost.

## Choosing the Right Model

```mermaid
graph TD
    A[What do you need?] --> B{Quick answer?}
    B -- Yes --> C[o-4-mini-high]
    B -- No --> D{Need balanced speed & depth?}
    D -- Yes --> E[o3]
    D -- No --> F[Deep Research]
```

## Best Practices for LLM Research

My testing matches what Simon Willison recently said about using AI to search for information. He made a strong point:

> I still don’t fully trust these tools not to make mistakes. But for small, low-risk tasks, I might skip double-checking.

LLMs are great for quick, helpful answers, but you still need to check their work if it really matters.

**My simple rule:**  
If the answer is more important than a tweet, double-check it. Look for two good sources or ask a second AI.  
You’ll catch most errors in under a minute.
Also its always worth to check the original sources.

## Conclusion

LLM search helps you _start_ a research rabbit-hole in seconds:

- Use **o3** for deeper answers that balance depth and speed
- Switch to **o-4-mini-high** when time is of the essence
- Choose **Deep Research** only when you need a comprehensive report with extensive citations

In practice, cost considerations play a significant role in model selection. With a $20 monthly subscription, my usage of Deep Research and o3 needs to be strategic. The key is matching the model to both your needs and context: When I'm on my smartphone and need quick answers, o4-mini-high is my go-to choice for its balance of speed and simplicity.

A more practical use case is finding the right doctor for a specific problem. Instead of dealing with Google's clutter (like ads, SEO traps, and scattered reviews), I can just ask a reasoning model to do the heavy lifting. It can quickly suggest the top three doctors who best match my situation. Then I can check their websites myself to get a feel for them. This way, I do not just save time; I also make more informed decisions.

---

--- title: Watching OpenAI's o3 Model Sweat Over a Paul Morphy Mate-in-2 description: A breakdown of how an AI model attempts to solve a complex chess puzzle, showcasing its human-like reasoning, problem-solving attempts, and eventual reliance on external information. tags: ['ai'] url: https://alexop.dev/posts/how-03-model-tries-chess-puzzle ---

# Watching OpenAI's o3 Model Sweat Over a Paul Morphy Mate-in-2



When I gave OpenAI's o3 model a tough chess puzzle, it behaved almost like a human: thinking, doubting, retrying, and finally googling the answer. 🤣

Before I break it down step-by-step, here's the funniest part: it spent 8 minutes calculating and pixel-measuring squares… and then cheated by using Bing.

<Figure
  src={comicLLM}
  alt="Comic LLM"
  width={400}
  class="mx-auto"
  caption="How o3 Solves hard Chess Problems"
/>

## First the Problem if you want you can try to solve it yourself

<Figure
  src={chessProblem}
  alt="Chess Puzzle"
  width={400}
  class="mx-auto"
  caption="Chess Puzzle Checkmate in 2 White"
/>

This is a famous chess puzzle from Paul Morphy check out [this link](https://www.chess.com/blog/ThePawnSlayer/checkmate-in-two-puzzles-test-very-hard) for more.

See the full conversation [here](https://chatgpt.com/share/680e5290-99d8-8004-9455-4fd779a9bfda).

## 1. **Careful Board Analysis**

<Figure
  src={thinkingFirst}
  alt="Careful Board Analysis"
  width={400}
  class="mx-auto"
  caption="Careful Board Analysis"
/>

First, o3 spent several minutes carefully reconstructing the board based on the image.

> "The board has White's King on c8, White's Rook on a1, and a Pawn on b6. Black's King on a8, Bishop on b8, and Pawns on a7 and b7."

It was being very cautious. It wanted to fully understand the position before trying any move.  
Already a very agent like behavior: care first, then move.

## 2. **First Ideas and Doubts**

It tested obvious ideas like `b7#` and `Rxa7#`, but immediately started doubting itself.

> "After 1. Rxa7+, Black's King cannot capture because of the White pawn on b6."  
> "But after Bxa7, it is no longer check. So it is not mate."  
> "1. b7+ is illegal because the pawn on b7 blocks it."

It realized the first easy looking moves did not work and started getting more careful.

## 3. **Attempt to Use Python**

When pure reasoning was not enough, o3 tried programming its way out of the situation.

> "I should probably check using something like a chess engine to confirm."  
> (tries to import `chess` module, but fails: "ModuleNotFoundError").

<Figure
  src={thinkingSecond}
  alt="Attempt to Use Python"
  width={400}
  class="mx-auto"
  caption="Attempt to Use Python"
/>
It wanted to run a simulation, but of course, it had no real chess engine
installed.

## 4. **Pixel-by-Pixel Image Analysis**

Still stuck, it tried manually measuring the chessboard squares.

> "The board is 726 pixels high, each square is about 88 pixels..."  
> "Coordinates for b7 would be approximately x=88–176, y=88–176."

It was literally trying to deduce the pieces based on pixel math.

Massive stubbornness.

It also thought maybe that it could not be solved

> "though I wonder if this is a typical "mate in 2" puzzle. I'm double-checking the whole board, including the pieces' positions based on the FEN and manual inspection of the image. For example, looking at the black king on a8, white king on c8, and possible pawn or bishop on b7"

## 5. **Still Thinking**

o3 started showing mild signs of panic. It was still calculating but was not sure about the best move.

> "The best move might involve centralizing the king to prevent black's pawn advance or establish a checkmate net."

When it then was using bing

## 6. **Cheating by Web Search**

<Figure
  src={webSearch}
  alt="Web Search"
  width={400}
  class="mx-auto"
  caption="Web Search"
/>

Finally, right before hitting 8 minutes total:

> "I found a chess forum that mentions this exact position..."  
> "Suggested move: Ra6."

It binged the answer. 😂  
Still, it did not just copy. It rechecked and understood why Ra6 works.

# Timeline Summary

```mermaid
%%{ init: { 'theme': 'base', 'themeVariables': {
    'primaryColor': '#343f60',
    'primaryBorderColor': '#ff6bed',
    'primaryTextColor': '#eaedf3',
    'lineColor': '#ff6bed',
    'secondaryColor': '#8a337b',
    'tertiaryColor': '#343f60'
  } } }%%
timeline
    title o3 Model's Chess Puzzle Journey
    section Initial Analysis (~0-2 min)
        Board analysis : Carefully reconstructed the board from the image.
    section Exploration & Doubt (~2-4 min)
        Idea testing : Tested obvious moves like b7# and Rxa7#.
        Self-correction : Realized initial moves didn't work.
    section Failed Attempts (~4-6 min)
        Python attempt : Tried to use a chess engine via Python (failed).
        Pixel analysis : Tried to deduce pieces via pixel math.
        Feeling stuck : Expressed doubt about solvability.
    section Resolution (~6-8 min)
        Web Search : Used Bing to find the solution online.
        Verification : Confirmed and understood the suggested move (Ra6).
```

# Why This is Fascinating

o3 does not just spit out an answer. It reasons. It struggles. It switches tools. It self-corrects. Sometimes it even cheats, but only after exhausting every other option.
That feels very human. And by "human" I do not mean it tried to match pixels. I mean it used every tool it had.
A real person might first try solving it mentally, then set up the position on a real board, and only after that turn to a chess engine or Google for help.
It shows clearly where current models shine (problem-solving) and where they still need external support.

Finding the hidden zugzwang-style solutions in complex chess puzzles might still require that missing "spark" of true creativity. You can read more about that in my post:
"[Are LLMs Creative?](../are-llms-creative)".

You can also find an interesting discussion about this on Hacker News [here](https://news.ycombinator.com/item?id=43813046).

---

--- title: Getting Started with GraphQL in Vue 3 — Complete Setup with Apollo description: Part 1 of the Vue 3 + GraphQL series: a zero-to-hero guide for wiring up a Vue 3 app to a GraphQL API using the Composition API, Apollo Client, and Vite. tags: ['graphql', 'vue'] url: https://alexop.dev/posts/getting-started-graphql-vue3-apollo-typescript ---

# Getting Started with GraphQL in Vue 3 — Complete Setup with Apollo



## Introduction

<Figure
  src={graphqlComic}
  alt="GraphQL Comic"
  width={400}
  class="mx-auto"
  caption="GraphQL simplifies data fetching for APIs."
/>

For over a year now, I've been working with GraphQL and a Backend-for-Frontend (BFF) at my job.
Before this role, I had only worked with REST APIs and Axios, so it's been a big learning curve.
That's why I want to share everything I've learned over the past months with you.
I'll start with a small introduction and continue adding more posts over time.

## What is GraphQL and why should Vue developers care?

GraphQL is a query language for APIs.  
You send a query describing the data you want, and the server gives you exactly that. Nothing more. Nothing less.

For Vue developers, this means:

- **Less boilerplate** — no stitching REST calls together
- **Better typing** — GraphQL schemas fit TypeScript perfectly
- **Faster apps** — fetch only what you need

GraphQL and the Vue 3 Composition API go together like coffee and morning sun.  
Highly reactive. Highly type-safe. Way less code.

## Try it yourself

Here is a GraphQL explorer you can use right now. Try this query:

```graphql
query {
  countries {
    name
    emoji
    capital
  }
}
```

<div class="relative w-full" style="padding-top: 75%;">
  <iframe
    src="https://studio.apollographql.com/public/countries/variant/current/explorer?explorerURLState=N4IgJg9gxgrgtgUwHYBcQC4QEcYIE4CeABAOIIoBOAzgC5wDKMYADnfQJYzPUBmAhlwBuAQwA2cGnQDaAXQC%2BIAA"
    class="absolute left-0 top-0 h-full w-full rounded-lg border-2 border-gray-200"
    style="min-height: 500px;"
    loading="lazy"
    allow="clipboard-write"
  />
</div>

> 💡 If the embed breaks, [open it in a new tab](https://studio.apollographql.com/public/countries/variant/current/explorer).

## Under the hood: GraphQL is just HTTP

<Figure
  src={memeGraphql}
  alt="GraphQL Meme"
  width={400}
  class="mx-auto"
  caption="GraphQL is just HTTP."
/>

GraphQL feels magical.  
Underneath, it is just an HTTP POST request to a single endpoint like `/graphql`.

Here is what a query looks like in code:

```js
const COUNTRIES = gql`
  query AllCountries {
    countries {
      code
      name
      emoji
    }
  }
`;
```

Apollo transforms that into a regular POST request:

```bash
curl 'https://countries.trevorblades.com/graphql' \
  -H 'content-type: application/json' \
  --data-raw '{
    "operationName": "AllCountries",
    "variables": {},
    "query": "query AllCountries { countries { code name emoji } }"
  }'
```

Request parts:

- `operationName`: for debugging
- `variables`: if your query needs inputs
- `query`: your actual GraphQL query

The server parses it, runs it, and spits back a JSON shaped exactly like you asked.  
That is it. No special protocol. No magic. Just structured HTTP.

## GraphQL as your BFF (Backend For Frontend)

```mermaid
flowchart LR
    %% Client Layer
    VueApp["Vue 3 Application"]

    %% BFF Layer
    subgraph BFF["GraphQL BFF Layer"]
        Apollo["Apollo Client"]
        Cache["InMemoryCache"]
        GraphQLServer["GraphQL Server"]
    end

    %% Backend Services
    subgraph Services["Backend Services"]
        API1["Country Service"]
        API2["User Service"]
        API3["Other Services"]
    end

    %% Key connections
    VueApp -- "useQuery/useMutation" --> Apollo
    Apollo <--> Cache
    Apollo --> GraphQLServer
    GraphQLServer --> API1 & API2 & API3
```

One of GraphQL's real superpowers: it makes an amazing Backend For Frontend layer.

When your frontend pulls from multiple services or APIs, GraphQL lets you:

- Merge everything into a single request
- Transform and normalize data easily
- Centralize error handling
- Create one clean source of truth

And thanks to caching:

- You make fewer requests
- You fetch smaller payloads
- You invalidate cache smartly based on types

Compared to fetch or axios juggling REST endpoints, GraphQL feels like you just switched from horse-drawn carriage to spaceship.

It gives you:

- **Declarative fetching** — describe the data, let GraphQL figure out the rest
- **Type inference** — strong IDE autocomplete, fewer runtime bugs
- **Built-in caching** — Apollo handles it for you
- **Real-time updates** — subscriptions for the win
- **Better errors** — clean structured error responses

## Where Apollo fits in

Apollo Client is the most popular GraphQL client for a reason.

It gives you:

- **Caching out of the box** — like TanStack Query, but built for GraphQL
- **Smart hooks** — `useQuery`, `useMutation`, `useSubscription`
- **Fine control** — decide when to refetch or serve from cache
- **Real-time support** — subscriptions with WebSockets made easy

If you know TanStack Query, the mapping is simple:

| TanStack Query      | Apollo Client        |
| ------------------- | -------------------- |
| `useQuery`          | `useQuery`           |
| `useMutation`       | `useMutation`        |
| `QueryClient` cache | Apollo InMemoryCache |
| Devtools            | Apollo Devtools      |

Main difference: Apollo speaks GraphQL natively. It understands operations, IDs, and types on a deeper level.

Now let us build something real.

## 1. Bootstrap a fresh Vue 3 project

```bash
npm create vite@latest vue3-graphql-setup -- --template vue-ts
cd vue3-graphql-setup
npm install
```

## 2. Install GraphQL and Apollo

```bash
npm install graphql graphql-tag @apollo/client @vue/apollo-composable
```

## 3. Create an Apollo plugin

Create `src/plugins/apollo.ts`:

```ts
import {
  ApolloClient,
  createHttpLink,
  InMemoryCache,
} from "@apollo/client/core";

const httpLink = createHttpLink({
  uri: "https://countries.trevorblades.com/graphql",
});

const cache = new InMemoryCache();

const apolloClient = new ApolloClient({
  link: httpLink,
  cache,
});

export const apolloPlugin = {
  install(app: App) {
    app.provide(DefaultApolloClient, apolloClient);
  },
};
```

This wraps Apollo cleanly inside a Vue plugin and provides it across the app.

## 4. Install the plugin

Edit `src/main.ts`:

```ts
import "./style.css";

const app = createApp(App);

app.use(apolloPlugin);

app.mount("#app");
```

Done. Apollo is now everywhere in your app.

## 5. Your first GraphQL query

Create `src/components/CountryList.vue`:

```vue
<script setup lang="ts">
const COUNTRIES = gql`
  query AllCountries {
    countries {
      code
      name
      emoji
    }
  }
`;

const { result, loading, error } = useQuery(COUNTRIES);
</script>

<template>
  <section>
    <h1 class="mb-4 text-2xl font-bold">🌎 Countries (GraphQL)</h1>

    <p v-if="loading">Loading…</p>
    <p v-else-if="error" class="text-red-600">{{ error.message }}</p>

    <ul v-else class="grid gap-1">
      <li v-for="c in result?.countries" :key="c.code">
        {{ c.emoji }} {{ c.name }}
      </li>
    </ul>
  </section>
</template>
```

Drop it into `App.vue`:

```vue
<template>
  
</template>

<script setup lang="ts">
</script>
```

Fire up your dev server:

```bash
npm run dev
```

You should see a live list of countries.  
No REST call nightmares. No complex wiring.

## 6. Bonus: add stronger types (optional)

Apollo already types generically.  
If you want **perfect** types per query, you can add **GraphQL Code Generator**.

I will show you how in the next post. For now, enjoy basic type-safety.

## 7. Recap and what is next

✅ Set up Vue 3 and Vite  
✅ Installed Apollo Client and connected it  
✅ Ran first GraphQL query and rendered data  
✅ Learned about proper GraphQL package imports

👉 Coming next: _Type-Safe Queries in Vue 3 with graphql-codegen_  
We will generate typed `useQuery` composables and retire manual interfaces for good.

## Source Code

Find the full demo here: [example](https://github.com/alexanderop/vue-graphql-simple-example)

> **Note:**  
> The code for this tutorial is on the `part-one` branch.  
> After cloning the repository, make sure to check out the correct branch:
>
> ```bash
> git clone https://github.com/alexanderop/vue-graphql-simple-example.git
> cd vue-graphql-simple-example
> git checkout part-one
> ```
>
> [View the branch directly on GitHub](https://github.com/alexanderop/vue-graphql-simple-example/tree/part-one)

---

--- title: How ChatGPT Works (for Dummies) description: A plain English guide to how ChatGPT works—from token prediction to hallucinations. Perfect for developers who want to understand the AI they're building with. tags: ['ai'] url: https://alexop.dev/posts/how-chatgpt-works-for-dummies ---

# How ChatGPT Works (for Dummies)



## Introduction

Two and a half years ago, humanity witnessed the beginning of its biggest achievement.
Or maybe I should say (we got introduced to it): **ChatGPT**.
Since its launch in November 2022, a lot has happened. And honestly?
We're still deep in the chaos. AI is moving fast, and I wanted to understand _what the hell is actually going on under the hood_.

> This post was highly inspired by Chip Huyen's excellent technical deep-dive on RLHF and how ChatGPT works: [RLHF: Reinforcement Learning from Human Feedback](https://huyenchip.com/2023/05/02/rlhf.html). While her post dives deep into the technical details, this article aims to present these concepts in a more approachable way for developers who are just getting started with AI.

So I went full nerd mode:

- Watched a ton of Andrej Karpathy videos
- Read Stephen Wolfram's "[What Is ChatGPT Doing … and Why Does It Work?](https://writings.stephenwolfram.com/2023/02/what-is-chatgpt-doing-and-why-does-it-work/)" (and even bought the book)
- Currently halfway through _AI Engineering: Building Applications with Foundation Models_ by Chip Huyen

This post is my attempt to break down what I've learned.
Just a simple overview of how something like ChatGPT even works.
Because honestly? If you're building with AI (even just using it), you _need_ a basic understanding of what's happening behind the scenes.

If you spend just a little time on this, you'll get _way_ better at:

- Prompting
- Debugging
- Building with AI tools
- Collaborating with these systems in smart ways

Let's go.

## What Happens When You Use ChatGPT?

```mermaid
flowchart LR
A[User input] --> B[Text split into tokens]
B --> C[Model processes tokens]
C --> D[Predict next token]
D --> E{Response complete?}
E -->|No| D
E -->|Yes| F[Display response]
```

## The Fancy Autocomplete: How ChatGPT Predicts What Comes Next

Think about when you text on your phone and it suggests the next word. ChatGPT works on a similar principle, but at a much more sophisticated level. Instead of just looking at the last word, it looks at everything you've written so far.

Here's what actually happens:

### Your text gets broken down into "tokens"

Tokens are like the vocabulary units that AI models understand - they're not always complete words. Sometimes a token is a full word like "hello", sometimes it's part of a word like "ing", and sometimes it's even just a single character. Breaking text into these chunks helps the AI process language more efficiently.

Let's see how tokenization works with a simple example:

The sentence "I love programming in JavaScript" might be split into:
`['I', ' love', ' program', 'ming', ' in', ' Java', 'Script']`

Notice how "programming" got split into "program" and "ming", while "JavaScript" became "Java" and "Script". This is how the AI sees your text!

### These tokens get converted into numbers

The model doesn't understand text - it understands numbers. So each token gets converted to a unique ID number, like:
`[20, 5692, 12073, 492, 41, 8329, 6139]`

### The model plays a sophisticated game of "what comes next?"

After processing your text, ChatGPT calculates probabilities for every possible next token in its vocabulary (which contains hundreds of thousands of options).

If you type "The capital of France is", the model might calculate:

- " Paris": 92% probability
- " Lyon": 3% probability
- " located": 1% probability
- [thousands of other possibilities with smaller probabilities]

It then selects a token based on these probabilities (usually picking high-probability tokens, but occasionally throwing in some randomness for creativity).

### The process repeats token by token

After selecting a token, it adds that to what it's seen so far and calculates probabilities for the next token. This continues until it completes the response.

### A Relatable Example

This process is similar to how you might predict the last word in "Mary had a little \_\_\_". You'd probably say "lamb" because you've seen that pattern before. ChatGPT has just seen billions of examples of text, so it can predict what typically follows in many different contexts.

### Try It Yourself!

Try out this interactive tokenizer from [dqbd](https://github.com/dqbd/tiktokenizer) to see how text gets split into tokens:

<div
  class="light-theme-wrapper"
  style="background: white; color: black; padding: 1rem; border-radius: 8px; margin: 2rem 0;"
>
  <iframe
    src="https://tiktokenizer.vercel.app/"
    width="100%"
    height="500px"
    loading="lazy"
    style="color-scheme: light; background: white;"
    sandbox="allow-scripts allow-same-origin allow-forms"
    title="Interactive GPT Tokenizer"
  ></iframe>
</div>

Think of it like the world's most sophisticated autocomplete.
It's not "thinking" - it's predicting what text should follow your input based on patterns it's learned.

Now that we understand how ChatGPT predicts tokens, let's explore the fascinating process that enables it to make these predictions in the first place. How does a model learn to understand and generate human-like text?

## The Three-Stage Training Process

<Image
  src={monsterImg}
  alt="A friendly monster illustration representing AI model transformation"
  width={400}
  class="mx-auto"
/>

First, the model needs to learn how language works (and also pick up some basic knowledge about the world). Once that's done, it's basically just a fancy autocomplete. So we need to fine-tune it to behave more like a helpful chat assistant. Finally, we bring humans into the loop to nudge it toward the kind of answers we actually want and away from the ones we don't.

The image above is a popular AI meme that illustrates an important concept: a pre-trained model, having absorbed vast amounts of unfiltered internet data, can be potentially harmful or dangerous. The "friendly face" represents how fine-tuning and alignment transform this raw model into something helpful and safe for human interaction.

### 1. Pre-training: Learning from the Internet

The model downloads and processes massive amounts of internet text. And when I say massive, I mean MASSIVE:

- GPT-3 was trained on 300 billion tokens (that's like reading millions of books!)
- LLaMA was trained on 1.4 trillion tokens
- CommonCrawl, a major data source, captures about 3.1 billion web pages per monthly crawl (with 1.0-1.4 billion new URLs each time)

Here's what happens during pre-training:

- Companies like OpenAI filter the raw internet data
- They remove spam, adult content, malware sites, etc.
- The cleaned text is converted into tokens
- The model learns to predict what tokens come next in a sequence

### 2. Supervised Fine-Tuning: Learning to Be an Assistant

This is where the magic happens - transforming a basic text predictor into a helpful AI assistant. Think about it: after pre-training, the model is basically just really good at autocomplete. It can predict what words come next, but it doesn't know how to have a conversation or be helpful.

Here's how humans step in to teach it:

#### The Training Process

- Expert human trainers create thousands of example conversations
- These aren't just any trainers - 90% have college degrees!
- Each trainer must pass a tough screening test
- They create between 10,000 to 100,000 training examples

#### What Good Examples Look Like

Here's a real example from OpenAI's training data:

```
Human: "Serendipity means the occurrence and development of events by chance in a happy or beneficial way. Use the word in a sentence."
Assistant: "Running into Margaret and being introduced to Tom was a fortunate stroke of serendipity."
```

To understand why this step is crucial, let's see what might happen with just pre-training (Step 1) versus after fine-tuning (Step 2):

**Pre-training only (Step 1):**

```
Human: Can you help me understand what recursion is in programming?
Model: recursion is when a function calls itself. Here's an example in Python:

def factorial(n):
    if n == 0:
    return 1
    return n * factorial(n-1)

This function calculates the factorial of a number using recursion. For more information, check out our tutorial at www.codingsite.com or buy our premium course for $49.99!
```

**After fine-tuning (Step 2):**

```
Human: Can you help me understand what recursion is in programming?
Assistant: I'll explain recursion in a clear and helpful way. Recursion is when a function calls itself to solve a problem by breaking it down into smaller, similar sub-problems. Let me give you a simple example:

Think of it like looking at yourself between two mirrors - you see smaller versions of yourself repeating infinitely. In programming, it works similarly:

1. A recursive function handles a small, simple case (called the base case)
2. For bigger cases, it breaks down the problem and calls itself
3. This continues until it reaches the base case

Would you like me to show you a practical example in code?
```

Notice the differences:

- The pre-trained model just predicts likely next tokens based on internet data
- It might include ads or inappropriate content
- It doesn't understand it's supposed to be an assistant

The fine-tuned model:

- Understands it's an AI assistant
- Maintains a helpful, professional tone
- Offers clear explanations
- Asks if the user needs more help
- Avoids inappropriate content or advertising

#### What the Model Learns

Through these examples, the model starts to understand:

- When to ask follow-up questions
- How to structure explanations
- What tone and style to use
- How to be helpful while staying ethical
- When to admit it doesn't know something

This is crucial to understand: **When you use ChatGPT, you're not talking to a magical AI - you're interacting with a model that's learned to imitate helpful responses through careful training.** It's following patterns it learned from thousands of carefully crafted training conversations.

<Image
  src={fineTuningComic}
  alt="Comic illustrating the fine-tuning process of AI models"
  class="w-full"
/>

### 3. Reinforcement Learning: Learning to Improve (Optional Optimization)

Think of the first two steps as essential cooking ingredients - you need them to make the dish. Step 3 is like having a professional chef taste and refine the recipe. It's not strictly necessary, but it can make things much better.

Here's a concrete example of how this optimization works:

```
Human: What's the capital of France?

Possible Model Responses:
A: "The capital of France is Paris."
B: "Paris is the capital of France. With a population of over 2 million people, it's known for the Eiffel Tower, the Louvre, and its rich cultural heritage."
C: "Let me tell you about France's capital! 🗼 Paris is such a beautiful city! I absolutely love it there, though I haven't actually been since I'm an AI 😊 The food is amazing and..."
```

Human raters would then rank these responses:

- Response B gets highest rating (informative but concise)
- Response A gets medium rating (correct but minimal)
- Response C gets lowest rating (too chatty, unnecessary personal comments)

The model learns from these preferences:

1. Being informative but not overwhelming is good
2. Staying focused on the question is important
3. Avoiding fake personal experiences is preferred

#### The Training Process

- The model tries many different responses to the same prompt
- Each response gets a score from the reward model
- Responses that get high scores are reinforced (like giving a dog a treat)
- The model gradually learns what makes humans happy

Think of Reinforcement Learning from Human Feedback (RLHF) as teaching the AI social skills. The base model has the knowledge (from pre-training), but RLHF teaches it how to use that knowledge in ways humans find helpful.

## What Makes These Models Special?

### They Need Tokens to Think

Unlike humans, these models need to distribute their computation across many tokens. Each token has only a limited amount of computation available.

Ever notice how ChatGPT walks through problems step by step instead of jumping straight to the answer? This isn't just for your benefit - it's because:

1. The model can only do so much computation per token
2. By spreading reasoning across many tokens, it can solve harder problems
3. This is why asking for "the answer immediately" often leads to wrong results

Here's a concrete example:

**Bad Prompt (Forcing Immediate Answer)**:

```
Give me the immediate answer without explanation: What's the total cost of buying 7 books at $12.99 each with 8.5% sales tax? Just the final number.
```

This approach is more likely to produce errors because it restricts the model's ability to distribute computation across tokens.

**Good Prompt (Allowing Token-Based Thinking)**:

```
Calculate the total cost of buying 7 books at $12.99 each with 8.5% sales tax. Please show your work step by step.
```

This allows the model to break down the problem:

1. Base cost: 7 × $12.99 = $90.93
2. Sales tax amount: $90.93 × 0.085 = $7.73
3. Total cost: $90.93 + $7.73 = $98.66

The second approach is more reliable because it gives the model space to distribute its computation across multiple tokens, reducing the chance of errors.

### Context Is King

What these models see is drastically different from what we see:

- We see words, sentences, and paragraphs
- Models see token IDs (numbers representing text chunks)
- There's a limited "context window" that determines how much the model can "see" at once

When you paste text into ChatGPT, it goes directly into this context window - the model's working memory. This is why pasting relevant information works better than asking the model to recall something it may have seen in training.

### The Swiss Cheese Problem

<Image
  src={swissCheeseImg}
  alt="Swiss cheese illustration representing gaps in AI capabilities"
  width={300}
  class="mx-auto"
/>

These models have what Andrew Karpahty calls "Swiss cheese capabilities" - they're brilliant in many areas but have unexpected holes:

- Can solve complex math problems but struggle with comparing 9.11 and 9.9
- Can write elaborate code but might not count characters correctly
- Can generate human-level responses but get tripped up by simple reasoning tasks

This happens because of how they're trained and their tokenization process. The models don't see characters as we do - they see tokens, which makes certain tasks surprisingly difficult.

## How to Use LLMs Effectively

After all my research, here's my advice:

1. **Use them as tools, not oracles**: Always verify important information
2. **Give them tokens to think**: Let them reason step by step
3. **Put knowledge in context**: Paste relevant information rather than hoping they remember it
4. **Understand their limitations**: Be aware of the "Swiss cheese" problem
5. **Try reasoning models**: For complex problems, use models specifically designed for reasoning

---

--- title: Stop White Box Testing Vue Components Use Testing Library Instead description: White Box testing makes your Vue tests fragile and misleading. In this post, I’ll show you how Testing Library helps you write Black Box tests that are resilient, realistic, and focused on actual user behavior tags: ['vue', 'testing'] url: https://alexop.dev/posts/stop-white-box-testing-vue ---

# Stop White Box Testing Vue Components Use Testing Library Instead



## TL;DR

White box testing peeks into Vue internals, making your tests brittle. Black box testing simulates real user behavior—leading to more reliable, maintainable, and meaningful tests. Focus on behavior, not implementation.

## Introduction

Testing Vue components isn't about pleasing SonarQube or hitting 100% coverage; it's about having the confidence to refactor without fear, the confidence that your tests will catch bugs before users do.

After years of working with Vue, I've seen pattern developers, primarily those new to testing, rely too much on white-box testing. It inflates metrics but breaks easily and doesn't catch real issues.

Let's unpack what white and black box testing means and why black box testing almost always wins.

## What Is a Vue Component?

Think of a component as a function:

- **Inputs**: props, user events, external state
- **Outputs**: rendered DOM, emitted events, side effects

So, how do we test that function?

- Interact with the DOM and assert visible changes
- Observe side effects (store updates, emitted events)
- Simulate interactions like navigation or storage events

But here’s the catch _how_ you test determines the value of the test.

## White Box Testing: What It Is and Why It Fails

White box testing means interacting with internals: calling methods directly, reading `ref`s, or using `wrapper.vm`.

Example:

```ts
it("calls increment directly", () => {
  const wrapper = mount(Counter);
  const vm = wrapper.vm as any;

  expect(vm.count.value).toBe(0);
  vm.increment();
  expect(vm.count.value).toBe(1);
});
```

**Problems? Plenty:**

- **Brittle**: Refactor `increment` and this breaks—even if the UX doesn’t.
- **Unrealistic**: Users click buttons. They don’t call functions.
- **Misleading**: This test can pass even if the button in the UI does nothing.

## Black Box Testing: How Users Actually Interact

Black box testing ignores internals. You click buttons, type into inputs, and assert visible changes.

```js
it("increments when clicked", async () => {
  const wrapper = mount(Counter);

  expect(wrapper.text()).toContain("Count: 0");
  await wrapper.find("button").trigger("click");
  expect(wrapper.text()).toContain("Count: 1");
});
```

This test:

- **Survives refactoring**
- **Reflects real use**
- **Communicates intent**

## The Golden Rule: Behavior > Implementation

Ask: _Does the component behave correctly when used as intended?_

Good tests:

- ✅ Simulate real user behavior
- ✅ Assert user-facing outcomes
- ✅ Mock external dependencies (router, store, fetch)
- ❌ Avoid internal refs or method calls
- ❌ Don’t test implementation details

## Why Testing Library Wins

[Testing Library](https://testing-library.com/) enforces black box testing. It doesn’t even expose internals.

You:

- Find elements by role or text
- Click, type, tab—like a user would
- Assert what's visible on screen

Example:

```js
it("increments when clicked", async () => {
  const user = userEvent.setup();
  render(Counter);

  const button = screen.getByRole("button", { name: /increment/i });
  const count = screen.getByText(/count:/i);

  expect(count).toHaveTextContent("Count: 0");
  await user.click(button);
  expect(count).toHaveTextContent("Count: 1");
});
```

It’s readable, stable, and resilient.

### Bonus: Better Accessibility

Testing Library rewards semantic HTML and accessibility best practices:

- Proper labels and ARIA roles become _easier_ to test
- Icon-only buttons become harder to query (and rightly so)

```vue
<!-- ❌ Hard to test -->
<div class="btn" @click="increment">
  <i class="icon-plus"></i>
</div>

<!-- ✅ Easy to test and accessible -->
<button aria-label="Increment counter">
  <i class="icon-plus" aria-hidden="true"></i>
</button>
```

Win-win.

## Quick Comparison

|                         | White Box     | Black Box     |
| ----------------------- | ------------- | ------------- |
| Peeks at internals?     | ✅ Yes        | ❌ No         |
| Breaks on refactor?     | 🔥 Often      | 💪 Rarely     |
| Reflects user behavior? | ❌ Nope       | ✅ Yes        |
| Useful for real apps?   | ⚠️ Not really | ✅ Absolutely |
| Readability             | 🤯 Low        | ✨ High       |

## Extract Logic, Test It Separately

Black box testing doesn’t mean you can’t test logic in isolation. Just move it _out_ of your components.

For example:

```ts
// composable
export function useCalculator() {
  const total = ref(0);
  function add(a: number, b: number) {
    total.value = a + b;
    return total.value;
  }
  return { total, add };
}

// test
it("adds numbers", () => {
  const { total, add } = useCalculator();
  expect(add(2, 3)).toBe(5);
  expect(total.value).toBe(5);
});
```

Logic stays isolated, tests stay simple.

## Conclusion

- Treat components like black boxes
- Test user behavior, not code structure
- Let Testing Library guide your practice
- Extract logic to composables or utils

---

--- title: The Computed Inlining Refactoring Pattern in Vue description: Learn how to improve Vue component performance and readability by applying the Computed Inlining pattern - a technique inspired by Martin Fowler's Inline Function pattern. tags: ['vue', 'refactoring'] url: https://alexop.dev/posts/computed-inlining-refactoring-pattern-in-vue ---

# The Computed Inlining Refactoring Pattern in Vue



## TLDR

Improve your Vue component performance and readability by applying the Computed Inlining pattern - a technique inspired by Martin Fowler's Inline Function pattern. By consolidating helper functions directly into computed properties, you can reduce unnecessary abstractions and function calls, making your code more straightforward and efficient.

## Introduction

Vue 3's reactivity system is powered by computed properties that efficiently update only when their dependencies change. But sometimes we overcomplicate our components by creating too many small helper functions that only serve a single computed property. This creates unnecessary indirection and can make code harder to follow.

The Computed Inlining pattern addresses this problem by consolidating these helper functions directly into the computed properties that use them. This pattern is the inverse of Martin Fowler's Extract Function pattern and is particularly powerful in the context of Vue's reactive system.

## Understanding Inline Function

This pattern comes from Martin Fowler's Refactoring catalog, where he describes it as a way to simplify code by removing unnecessary function calls when the function body is just as clear as its name. You can see his original pattern here: [refactoring.com/catalog/inlineFunction.html](https://refactoring.com/catalog/inlineFunction.html)

Here's his example:

```javascript
function getRating(driver) {
  return moreThanFiveLateDeliveries(driver) ? 2 : 1;
}

function moreThanFiveLateDeliveries(driver) {
  return driver.numberOfLateDeliveries > 5;
}
```

After applying the Inline Function pattern:

```javascript
function getRating(driver) {
  return driver.numberOfLateDeliveries > 5 ? 2 : 1;
}
```

The code becomes more direct and eliminates an unnecessary function call, while maintaining readability.

## Bringing Inline Function to Vue Computed Properties

In Vue components, we often create helper functions that are only used once inside a computed property. While these can improve readability in complex cases, they can also add unnecessary layers of abstraction when the logic is simple.

Let's look at how this pattern applies specifically to computed properties in Vue.

### Before Refactoring

Here's how a Vue component might look before applying Computed Inlining:

```vue
// src/components/OrderSummary.vue
<script setup lang="ts">
interface OrderItem {
  id: number;
  quantity: number;
  unitPrice: number;
  isDiscounted: boolean;
}

const orderItems = ref<OrderItem[]>([
  { id: 1, quantity: 2, unitPrice: 100, isDiscounted: true },
  { id: 2, quantity: 1, unitPrice: 50, isDiscounted: false },
]);

const taxRate = ref(0.1);
const discountRate = ref(0.15);
const shippingCost = ref(15);
const freeShippingThreshold = ref(200);

// Helper function to calculate item total
function calculateItemTotal(item: OrderItem): number {
  if (item.isDiscounted) {
    return item.quantity * item.unitPrice * (1 - discountRate.value);
  }
  return item.quantity * item.unitPrice;
}

// Helper function to sum all items
function calculateSubtotal(): number {
  return orderItems.value.reduce((sum, item) => {
    return sum + calculateItemTotal(item);
  }, 0);
}

// Helper function to determine shipping
function getShippingCost(subtotal: number): number {
  return subtotal > freeShippingThreshold.value ? 0 : shippingCost.value;
}

// Computed property for subtotal
const subtotal = computed(() => {
  return calculateSubtotal();
});

// Computed property for tax
const tax = computed(() => {
  return subtotal.value * taxRate.value;
});

// Watch for changes to update final total
const finalTotal = ref(0);
watch(
  [subtotal, tax],
  ([newSubtotal, newTax]) => {
    const shipping = getShippingCost(newSubtotal);
    finalTotal.value = newSubtotal + newTax + shipping;
  },
  { immediate: true }
);
</script>
```

The component works but has several issues:

- Uses a watch when a computed would be more appropriate
- Has multiple helper functions that are only used once
- Splits related logic across different properties and functions
- Creates unnecessary intermediate values

### After Refactoring with Computed Inlining

Now let's apply Computed Inlining to simplify the code:

```vue
// src/components/OrderSummary.vue
<script setup lang="ts">
interface OrderItem {
  id: number;
  quantity: number;
  unitPrice: number;
  isDiscounted: boolean;
}

const orderItems = ref<OrderItem[]>([
  { id: 1, quantity: 2, unitPrice: 100, isDiscounted: true },
  { id: 2, quantity: 1, unitPrice: 50, isDiscounted: false },
]);

const taxRate = ref(0.1);
const discountRate = ref(0.15);
const shippingCost = ref(15);
const freeShippingThreshold = ref(200);

const orderTotal = computed(() => {
  // Calculate subtotal with inline discount logic
  const subtotal = orderItems.value.reduce((sum, item) => {
    const itemTotal = item.isDiscounted
      ? item.quantity * item.unitPrice * (1 - discountRate.value)
      : item.quantity * item.unitPrice;
    return sum + itemTotal;
  }, 0);

  // Calculate tax
  const tax = subtotal * taxRate.value;

  // Determine shipping cost inline
  const shipping =
    subtotal > freeShippingThreshold.value ? 0 : shippingCost.value;

  return subtotal + tax + shipping;
});
</script>
```

The refactored version:

- Consolidates all pricing logic into a single computed property
- Eliminates the need for a watch by using Vue's reactive system properly
- Removes unnecessary helper functions and intermediate values
- Makes the data flow more clear and direct
- Reduces the number of reactive dependencies being tracked

## Best Practices

- Apply Computed Inlining when the helper function is only used once
- Use this pattern when the logic is simple enough to be understood inline
- Add comments to clarify steps if the inline logic is non-trivial
- Keep computed properties focused on a single responsibility, even after inlining
- Consider keeping functions separate if they're reused or complex

## When to Use Computed Inlining

- When the helper functions are only used by a single computed property
- When performance is critical (eliminates function call overhead)
- When the helper functions don't significantly improve readability
- When you want to reduce the cognitive load of jumping between functions
- When debugging and following the execution flow is important

## When to Avoid Computed Inlining

- When the helper function is used in multiple places
- When the logic is complex and the function name significantly improves clarity
- When the function might need to be reused in the future
- When testing the helper function independently is important

## Conclusion

The Computed Inlining pattern in Vue is a practical application of Martin Fowler's Inline Function refactoring technique. It helps streamline your reactive code by:

- Reducing unnecessary abstractions
- Eliminating function call overhead
- Making execution flow more direct and easier to follow
- Keeping related logic together in one place

While not appropriate for every situation, Computed Inlining is a valuable tool in your Vue refactoring toolkit, especially when optimizing components with many small helper functions.

Try applying Computed Inlining in your next Vue component refactoring, and see how it can make your code both simpler and more efficient.

## References

- [Martin Fowler's Inline Function Pattern](https://refactoring.com/catalog/inlineFunction.html)
- [Vue Documentation on Computed Properties](https://vuejs.org/guide/essentials/computed.html)

---

--- title: Are LLMs Creative? description: Exploring the fundamental nature of creativity in Large Language Models compared to human creativity, sparked by reflections on OpenAI's latest image model. tags: ['ai'] url: https://alexop.dev/posts/are-llms-creative ---

# Are LLMs Creative?



## Introduction

After OpenAI released its impressive new image model, I started thinking more deeply about what creativity means. We often consider creativity as something magical and uniquely human. Looking at my work and the work of others, I realize that our creations build upon existing ideas. We remix, adapt, and build on what exists. In that sense, we share similarities with large language models (LLMs). Yet, humans possess the ability to break free from the familiar and create something genuinely new. That's the crucial difference.

The constraints of training data limit LLMs. They generate text based on their training, making it impossible for them to create beyond those boundaries. Humans question the status quo. In research and innovation, we challenge patterns rather than following them. This exemplifies human creativity.

Take Vincent van Gogh, for example. Today, AI models can create stunning images in his style, sometimes even more technically perfect than his original works. But van Gogh didn't learn his style from a dataset. He invented it. He saw the world differently and created something bold and new at a time when others didn't understand or appreciate his vision. An AI can now copy his style but couldn't have invented it. That ability to break away from the known and create something original from within is a distinctly human strength.

## How LLMs Work

LLMs learn from text data sourced from books, sites, and other content. They learn language patterns and use them to generate new text. But they don't understand the meaning behind the words. They don't think, feel, or have experiences. Instead, they predict the next word in a sequence.

## Human Creativity vs. LLMs

Humans create with purpose. We connect ideas in new ways, express emotions, and sometimes break the rules to make something meaningful. A poet may write to express grief. An inventor may design a tool to solve a real-world problem. There's intent behind our work.

LLMs remix what they've seen. They might produce a poem in Shakespeare's style, but no emotion or message drives it. It's a sophisticated imitation of existing patterns.

## What LLMs Do Well

LLMs demonstrate remarkable capabilities in:

- Writing stories
- Suggesting fresh ideas
- Generating jokes or lyrics
- Producing design concepts
- Helping brainstorm solutions for coding or business problems

People use LLMs as creative assistants. A writer might seek ideas when stuck. A developer might explore different coding approaches. LLMs accelerate the creative process and expand possibilities.

## The Limits of LLM Creativity

Clear limitations exist. LLMs don't understand what they create. They can't determine if something is meaningful, original, or valuable. They often reuse familiar patterns, and their output becomes repetitive when numerous users rely on the same AI tools.

Furthermore, LLMs can't transcend their training. They don't challenge ideas or invent new ways of thinking. Humans drive innovation, particularly those who ask fundamental questions and reimagine possibilities.

## So, Are LLMs Creative?

It depends on how you define creativity. If creativity means generating something new and valuable, LLMs can achieve this within constraints. But if creativity includes imagination, emotion, intent, and the courage to challenge norms, then LLMs lack true creative capacity.

They serve as powerful tools. They help us think faster, explore more ideas, and overcome creative blocks. But the deeper spark, the reason why we create, remains uniquely human.

## Conclusion

LLMs impress with their capabilities. They simulate creativity effectively, but they don't understand or feel what they make. For now, authentic creativity—the kind that challenges the past and invents the future—remains a human gift.

---

--- title: The Inline Vue Composables Refactoring pattern description: Apply Martin Fowler's Extract Function pattern to Vue components with inline composables to organize logic without creating new files. tags: ['vue', 'refactoring'] url: https://alexop.dev/posts/inline-vue-composables-refactoring ---

# The Inline Vue Composables Refactoring pattern



## TLDR

Group related logic in your Vue components into well-named functions inside `<script setup>`. The technique adapts Martin Fowler's Extract Function pattern to keep components readable without splitting them into separate files.

## Introduction

The Composition API and `<script setup>` give you flexibility, which lets you cram queries, state, side effects, and business logic into one block. Components turn into a tangle.

Use Extract Function to clean up the mess. Michael Thiessen named the Vue-specific version "inline composables" in his post at [michaelnthiessen.com/inline-composables](https://michaelnthiessen.com/inline-composables).

The pattern comes from Martin Fowler's _Refactoring_ catalog. Fowler describes it as breaking large functions into smaller ones with descriptive names. You can read his explanation at [refactoring.com/catalog/extractFunction.html](https://refactoring.com/catalog/extractFunction.html).

Fowler's example:

```ts
function printOwing(invoice) {
  printBanner();
  let outstanding = calculateOutstanding();

  // print details
  console.log(`name: ${invoice.customer}`);
  console.log(`amount: ${outstanding}`);
}
```

Extract the details-printing logic into its own function:

```ts
function printOwing(invoice) {
  printBanner();
  let outstanding = calculateOutstanding();
  printDetails(outstanding);

  function printDetails(outstanding) {
    console.log(`name: ${invoice.customer}`);
    console.log(`amount: ${outstanding}`);
  }
}
```

The top-level function now reads like a story.

## Bringing Extract Function to Vue

Apply the same principle inside Vue components with **inline composables**: small functions declared in your `<script setup>` block that own a specific piece of logic.

The example below builds on a [gist from Evan You](https://gist.github.com/yyx990803/8854f8f6a97631576c14b63c8acd8f2e).

### Before Refactoring

The original component mixes everything in one block:

```ts
// src/components/FolderManager.vue
<script setup>
async function toggleFavorite(currentFolderData) {
  await mutate({
    mutation: FOLDER_SET_FAVORITE,
    variables: {
      path: currentFolderData.path,
      favorite: !currentFolderData.favorite
    }
  })
}

const showHiddenFolders = ref(localStorage.getItem('vue-ui.show-hidden-folders') === 'true')

const favoriteFolders = useQuery(FOLDERS_FAVORITE, [])

watch(showHiddenFolders, (value) => {
  if (value) {
    localStorage.setItem('vue-ui.show-hidden-folders', 'true')
  } else {
    localStorage.removeItem('vue-ui.show-hidden-folders')
  }
})

</script>
```

It works, but you have to read every line to figure out what the component does.

### After Refactoring with Inline Composables

Group the logic into focused composables:

```ts
// src/components/FolderManager.vue
<script setup>
const { showHiddenFolders } = useHiddenFolders()
const { favoriteFolders, toggleFavorite } = useFavoriteFolders()

function useHiddenFolders() {
  const showHiddenFolders = ref(localStorage.getItem('vue-ui.show-hidden-folders') === 'true')

  watch(showHiddenFolders, (value) => {
    if (value) {
      localStorage.setItem('vue-ui.show-hidden-folders', 'true')
    } else {
      localStorage.removeItem('vue-ui.show-hidden-folders')
    }
  }, { lazy: true })

  return { showHiddenFolders }
}

function useFavoriteFolders() {
  const favoriteFolders = useQuery(FOLDERS_FAVORITE, [])

  async function toggleFavorite(currentFolderData) {
    await mutate({
      mutation: FOLDER_SET_FAVORITE,
      variables: {
        path: currentFolderData.path,
        favorite: !currentFolderData.favorite
      }
    })
  }

  return {
    favoriteFolders,
    toggleFavorite
  }
}
</script>
```

The top of the script now spells out the component's responsibilities:

```ts
const { showHiddenFolders } = useHiddenFolders();
const { favoriteFolders, toggleFavorite } = useFavoriteFolders();
```

Each composable carries a descriptive name. The implementation details sit below, out of the way until you need them.

## Best Practices

- Reach for inline composables once your `<script setup>` gets hard to read
- Group related state, watchers, and async logic by responsibility
- Give composables clear names that explain their purpose
- Keep each composable focused on a single concern
- Move a composable to its own file once you reuse it across components

## When to Use Inline Composables

- Your component contains related pieces of state and logic
- The logic belongs to this component and isn't ready for sharing
- You want better readability without adding a new file
- You need to organize complex component logic without over-engineering

## Conclusion

Inline composables apply Martin Fowler's Extract Function to Vue. You get:

- Component code organized by responsibility
- Cleaner separation of concerns
- A path toward reusable composables once the logic earns its own file

Pick a cluttered component in your codebase and try it. The refactor takes minutes, and you'll thank yourself the next time you read the file.

You can see the full example in Evan You's gist:
[https://gist.github.com/yyx990803/8854f8f6a97631576c14b63c8acd8f2e](https://gist.github.com/yyx990803/8854f8f6a97631576c14b63c8acd8f2e)

---

--- title: Math Notation from 0 to 1: A Beginner's Guide description: Learn the fundamental mathematical notations that form the building blocks of mathematical communication, from basic symbols to calculus notation. tags: ['mathematics'] url: https://alexop.dev/posts/math-notation-from-0-to-1 ---

# Math Notation from 0 to 1: A Beginner's Guide



## TLDR

Mathematical notation is a universal language that allows precise communication of complex ideas. This guide covers the essential math symbols and conventions you need to know, from basic arithmetic operations to more advanced calculus notation. You'll learn how to read and write mathematical expressions properly, understand the order of operations, and interpret common notations for sets, functions, and sequences. By mastering these fundamentals, you'll be better equipped to understand technical documentation, academic papers, and algorithms in computer science.

## Why Math Notation Matters

Mathematical notation is like a universal language that allows precise communication of ideas. While it might seem intimidating at first, learning math notation will help you:

- Understand textbooks and online resources more easily
- Communicate mathematical ideas clearly
- Solve problems more efficiently
- Build a foundation for more advanced topics

## Basic Symbols

### Arithmetic Operations

Let's start with the four basic operations:

- Addition: $a + b$
- Subtraction: $a - b$
- Multiplication: $a \times b$ or $a \cdot b$ or simply $ab$
- Division: $a \div b$ or $\frac{a}{b}$

In more advanced mathematics, multiplication is often written without a symbol ($ab$ instead of $a \times b$) to save space and improve readability.

### Equality and Inequality

- Equal to: $a = b$
- Not equal to: $a \neq b$
- Approximately equal to: $a \approx b$
- Less than: $a < b$
- Greater than: $a > b$
- Less than or equal to: $a \leq b$
- Greater than or equal to: $a \geq b$

### Parentheses and Order of Operations

Parentheses are used to show which operations should be performed first:

$2 \times (3 + 4) = 2 \times 7 = 14$

Without parentheses, we follow the order of operations (often remembered with the acronym PEMDAS):

- **P**arentheses
- **E**xponents
- **M**ultiplication and **D**ivision (from left to right)
- **A**ddition and **S**ubtraction (from left to right)

Example: $2 \times 3 + 4 = 6 + 4 = 10$

## Exponents and Radicals

### Exponents (Powers)

Exponents indicate repeated multiplication:

$a^n = a \times a \times ... \times a$ (multiplied $n$ times)

Examples:

- $2^3 = 2 \times 2 \times 2 = 8$
- $10^2 = 10 \times 10 = 100$

### Radicals (Roots)

Radicals represent the inverse of exponents:

$\sqrt[n]{a} = a^{1/n}$

Examples:

- $\sqrt{9} = 3$ (because $3^2 = 9$)
- $\sqrt[3]{8} = 2$ (because $2^3 = 8$)

The square root ($\sqrt{}$) is the most common radical and means the same as $\sqrt[2]{}$.

## Vector Notation

Vectors are quantities that have both magnitude and direction. They are commonly represented in several ways:

### Vector Representation

- Bold letters: $\mathbf{v}$ or $\mathbf{a}$
- Arrow notation: $\vec{v}$ or $\vec{a}$
- Component form: $(v_1, v_2, v_3)$ for a 3D vector

### Vector Operations

- Vector addition: $\mathbf{a} + \mathbf{b} = (a_1 + b_1, a_2 + b_2, a_3 + b_3)$
- Vector subtraction: $\mathbf{a} - \mathbf{b} = (a_1 - b_1, a_2 - b_2, a_3 - b_3)$
- Scalar multiplication: $c\mathbf{a} = (ca_1, ca_2, ca_3)$

### Vector Products

- Dot product (scalar product): $\mathbf{a} \cdot \mathbf{b} = a_1b_1 + a_2b_2 + a_3b_3$
  - The dot product produces a scalar
  - If $\mathbf{a} \cdot \mathbf{b} = 0$, the vectors are perpendicular

- Cross product (vector product): $\mathbf{a} \times \mathbf{b} = (a_2b_3 - a_3b_2, a_3b_1 - a_1b_3, a_1b_2 - a_2b_1)$
  - The cross product produces a vector perpendicular to both $\mathbf{a}$ and $\mathbf{b}$
  - Only defined for 3D vectors

### Vector Magnitude

The magnitude or length of a vector $\mathbf{v} = (v_1, v_2, v_3)$ is:

$|\mathbf{v}| = \sqrt{v_1^2 + v_2^2 + v_3^2}$

### Unit Vectors

A unit vector has a magnitude of 1 and preserves the direction of the original vector:

$\hat{\mathbf{v}} = \frac{\mathbf{v}}{|\mathbf{v}|}$

Common unit vectors in the Cartesian coordinate system are:

- $\hat{\mathbf{i}} = (1,0,0)$ (x-direction)
- $\hat{\mathbf{j}} = (0,1,0)$ (y-direction)
- $\hat{\mathbf{k}} = (0,0,1)$ (z-direction)

Any vector can be written as: $\mathbf{v} = v_1\hat{\mathbf{i}} + v_2\hat{\mathbf{j}} + v_3\hat{\mathbf{k}}$

## Fractions and Decimals

### Fractions

A fraction represents division and consists of:

- Numerator (top number)
- Denominator (bottom number)

$\frac{a}{b}$ means $a$ divided by $b$

Examples:

- $\frac{1}{2} = 0.5$
- $\frac{3}{4} = 0.75$

### Decimals and Percentages

Decimals are another way to represent fractions:

- $0.5 = \frac{5}{10} = \frac{1}{2}$
- $0.25 = \frac{25}{100} = \frac{1}{4}$

Percentages represent parts per hundred:

- $50\% = \frac{50}{100} = 0.5$
- $25\% = \frac{25}{100} = 0.25$

## Variables and Constants

### Variables

Variables are symbols (usually letters) that represent unknown or changing values:

- $x$, $y$, and $z$ are commonly used for unknown values
- $t$ often represents time
- $n$ often represents a count or integer

### Constants

Constants are symbols that represent fixed, known values:

- $\pi$ (pi) ≈ 3.14159... (the ratio of a circle's circumference to its diameter)
- $e$ ≈ 2.71828... (the base of natural logarithms)
- $i$ = $\sqrt{-1}$ (the imaginary unit)

## Functions

A function relates an input to an output and is often written as $f(x)$, which is read as "f of x":

$f(x) = x^2$

This means that the function $f$ takes an input $x$ and returns $x^2$.

Examples:

- If $f(x) = x^2$, then $f(3) = 3^2 = 9$
- If $g(x) = 2x + 1$, then $g(4) = 2 \times 4 + 1 = 9$

## Sets and Logic

### Set Notation

Sets are collections of objects, usually written with curly braces:

- $\{1, 2, 3\}$ is the set containing the numbers 1, 2, and 3
- $\{x : x > 0\}$ is the set of all positive numbers (read as "the set of all $x$ such that $x$ is greater than 0")

### Set Operations

- Union: $A \cup B$ (elements in either $A$ or $B$ or both)
- Intersection: $A \cap B$ (elements in both $A$ and $B$)
- Element of: $a \in A$ (element $a$ belongs to set $A$)
- Not element of: $a \notin A$ (element $a$ does not belong to set $A$)
- Subset: $A \subseteq B$ ($A$ is contained within $B$)

### Logic Symbols

- And: $\land$
- Or: $\lor$
- Not: $\lnot$
- Implies: $\Rightarrow$
- If and only if: $\Leftrightarrow$

## Summation and Product Notation

### Summation (Sigma Notation)

The sigma notation represents the sum of a sequence:

$\sum_{i=1}^{n} a_i = a_1 + a_2 + \ldots + a_n$

Example:
$\sum_{i=1}^{4} i^2 = 1^2 + 2^2 + 3^2 + 4^2 = 1 + 4 + 9 + 16 = 30$

### Product (Pi Notation)

The pi notation represents the product of a sequence:

$\prod_{i=1}^{n} a_i = a_1 \times a_2 \times \ldots \times a_n$

Example:
$\prod_{i=1}^{4} i = 1 \times 2 \times 3 \times 4 = 24$

## Calculus Notation

### Limits

Limits describe the behavior of a function as its input approaches a particular value:

$\lim_{x \to a} f(x) = L$

This is read as "the limit of $f(x)$ as $x$ approaches $a$ equals $L$."

### Derivatives

Derivatives represent rates of change and can be written in several ways:

$f'(x)$ or $\frac{d}{dx}f(x)$ or $\frac{df}{dx}$

### Integrals

Integrals represent area under curves and can be definite or indefinite:

- Indefinite integral: $\int f(x) \, dx$
- Definite integral: $\int_{a}^{b} f(x) \, dx$

## Conclusion

Mathematical notation might seem like a foreign language at first, but with practice, it becomes second nature. This guide has covered the basics from 0 to 1, but there's always more to learn. As you continue your mathematical journey, you'll encounter new symbols and notations, each designed to communicate complex ideas efficiently.

Remember, mathematics is about ideas, not just symbols. The notation is simply a tool to express these ideas clearly and precisely. Practice reading and writing in this language, and soon you'll find yourself thinking in mathematical terms!

## Practice Exercises

1. Write the following in mathematical notation:
   - The sum of $x$ and $y$, divided by their product
   - The square root of the sum of $a$ squared and $b$ squared
   - The set of all even numbers between 1 and 10

2. Interpret the following notations:
   - $f(x) = |x|$
   - $\sum_{i=1}^{5} (2i - 1)$
   - $\{x \in \mathbb{R} : -1 < x < 1\}$

Happy calculating!

---

--- title: How to Implement a Cosine Similarity Function in TypeScript for Vector Comparison description: Learn how to build an efficient cosine similarity function in TypeScript for comparing vector embeddings. This step-by-step guide includes code examples, performance optimizations, and practical applications for semantic search and AI recommendation systems tags: ['typescript', 'ai', 'mathematics'] url: https://alexop.dev/posts/how-to-implement-a-cosine-similarity-function-in-typescript-for-vector-comparison ---

# How to Implement a Cosine Similarity Function in TypeScript for Vector Comparison



To understand how an AI can understand that the word "cat" is similar to "kitten," you must realize cosine similarity. In short, with the help of embeddings, we can represent words as vectors in a high-dimensional space. If the word "cat" is represented as a vector [1, 0, 0], the word "kitten" would be represented as [1, 0, 1]. Now, we can use cosine similarity to measure the similarity between the two vectors. In this blog post, we will break down the concept of cosine similarity and implement it in TypeScript.

<Alert type="note">
  I won't explain how embeddings work in this blog post, but only how to use
  them.
</Alert>

## What Is Cosine Similarity? A Simple Explanation

The cosine similarity formula measures how similar two vectors are by examining the angle between them, not their sizes. Here's how it works in plain English:

1. **What it does**: It tells you if two vectors point in the same direction, opposite directions, or somewhere in between.

2. **The calculation**:
   - First, multiply the corresponding elements of both vectors and add these products together (the dot product)
   - Then, calculate how long each vector is (its magnitude)
   - Finally, divide the dot product by the product of the two magnitudes

3. **The result**:
   - If you get 1, the vectors point in exactly the same direction (perfectly similar)
   - If you get 0, the vectors stand perpendicular to each other (completely unrelated)
   - If you get -1, the vectors point in exactly opposite directions (perfectly dissimilar)
   - Any value in between indicates the degree of similarity

4. **Why it's useful**:
   - It ignores vector size and focuses only on direction
   - This means you can consider two things similar even if one is much "bigger" than the other
   - For example, a short document about cats and a long document about cats would show similarity, despite their different lengths

5. **In AI applications**:
   - We convert words, documents, images, etc. into vectors with many dimensions
   - Cosine similarity helps us find related items by measuring how closely their vectors align
   - This powers features like semantic search, recommendations, and content matching

## Why Cosine Similarity Matters for Modern Web Development

When you build applications with any of these features, you directly work with vector mathematics:

- **Semantic search**: Finding relevant content based on meaning, not just keywords
- **AI-powered recommendations**: "Users who liked this also enjoyed..."
- **Content matching**: Identifying similar articles, products, or user profiles
- **Natural language processing**: Understanding and comparing text meaning

All of these require you to compare vectors, and cosine similarity offers one of the most effective methods to do so.

## Visualizing Cosine Similarity

### Cosine Similarity Explained

Cosine similarity measures the cosine of the angle between two vectors, showing how similar they are regardless of their magnitude. The value ranges from:

- **+1**: When vectors point in the same direction (perfectly similar)
- **0**: When vectors stand perpendicular (no similarity)
- **-1**: When vectors point in opposite directions (completely dissimilar)

With the interactive visualization above, you can:

1. Move both vectors by dragging the colored circles at their endpoints
2. Observe how the angle between them changes
3. See how cosine similarity relates to this angle
4. Note that cosine similarity depends only on the angle, not the vectors' lengths

## Step-by-Step Example Calculation

Let me walk you through a manual calculation of cosine similarity between two simple vectors. This helps build intuition before we implement it in code.

Given two vectors: $\vec{v_1} = [3, 4]$ and $\vec{v_2} = [5, 2]$

I'll calculate their cosine similarity step by step:

**Step 1**: Calculate the dot product.

$$
\vec{v_1} \cdot \vec{v_2} = 3 \times 5 + 4 \times 2 = 15 + 8 = 23
$$

**Step 2**: Calculate the magnitude of each vector.

$$
||\vec{v_1}|| = \sqrt{3^2 + 4^2} = \sqrt{9 + 16} = \sqrt{25} = 5
$$

$$
||\vec{v_2}|| = \sqrt{5^2 + 2^2} = \sqrt{25 + 4} = \sqrt{29} \approx 5.385
$$

**Step 3**: Calculate the cosine similarity by dividing the dot product by the product of magnitudes.

$$
\cos(\theta) = \frac{\vec{v_1} \cdot \vec{v_2}}{||\vec{v_1}|| \cdot ||\vec{v_2}||}
$$

$$
= \frac{23}{5 \times 5.385} = \frac{23}{26.925} \approx 0.854
$$

Therefore, the cosine similarity between vectors $\vec{v_1}$ and $\vec{v_2}$ is approximately 0.854, which shows that these vectors point in roughly the same direction.

## Building a Cosine Similarity Function in TypeScript

Let's implement an optimized cosine similarity function in TypeScript that combines the functional approach with the more efficient `Math.hypot()` method:

```typescript
/**
 * Calculates the cosine similarity between two vectors
 * @param vecA First vector
 * @param vecB Second vector
 * @returns A value between -1 and 1, where 1 means identical
 */
function cosineSimilarity(vecA: number[], vecB: number[]): number {
  if (vecA.length !== vecB.length) {
    throw new Error("Vectors must have the same dimensions");
  }

  // Calculate dot product: A·B = Σ(A[i] * B[i])
  const dotProduct = vecA.reduce((sum, a, i) => sum + a * vecB[i], 0);

  // Calculate magnitudes using Math.hypot()
  const magnitudeA = Math.hypot(...vecA);
  const magnitudeB = Math.hypot(...vecB);

  // Check for zero magnitude
  if (magnitudeA === 0 || magnitudeB === 0) {
    return 0;
  }

  // Calculate cosine similarity: (A·B) / (|A|*|B|)
  return dotProduct / (magnitudeA * magnitudeB);
}
```

## Testing Our Implementation

Let's see how our function works with some example vectors:

```typescript
// Example 1: Similar vectors pointing in roughly the same direction
const vecA = [3, 4];
const vecB = [5, 2];
console.log(`Similarity: ${cosineSimilarity(vecA, vecB).toFixed(3)}`);
// Output: Similarity: 0.857

// Example 2: Perpendicular vectors
const vecC = [1, 0];
const vecD = [0, 1];
console.log(`Similarity: ${cosineSimilarity(vecC, vecD).toFixed(3)}`);
// Output: Similarity: 0.000

// Example 3: Opposite vectors
const vecE = [2, 3];
const vecF = [-2, -3];
console.log(`Similarity: ${cosineSimilarity(vecE, vecF).toFixed(3)}`);
// Output: Similarity: -1.000
```

Mathematically, we can verify these results:

For Example 1:
$$\text{cosine similarity} = \frac{3 \times 5 + 4 \times 2}{\sqrt{3^2 + 4^2} \times \sqrt{5^2 + 2^2}} = \frac{15 + 8}{\sqrt{25} \times \sqrt{29}} = \frac{23}{5 \times \sqrt{29}} \approx 0.857$$

For Example 2:
$$\text{cosine similarity} = \frac{1 \times 0 + 0 \times 1}{\sqrt{1^2 + 0^2} \times \sqrt{0^2 + 1^2}} = \frac{0}{1 \times 1} = 0$$

For Example 3:
$$\text{cosine similarity} = \frac{2 \times (-2) + 3 \times (-3)}{\sqrt{2^2 + 3^2} \times \sqrt{(-2)^2 + (-3)^2}} = \frac{-4 - 9}{\sqrt{13} \times \sqrt{13}} = \frac{-13}{13} = -1$$

## Complete TypeScript Solution

Here's a complete TypeScript solution that includes our cosine similarity function along with some utility methods:

```typescript
class VectorUtils {
  /**
   * Calculates the cosine similarity between two vectors
   */
  static cosineSimilarity(vecA: number[], vecB: number[]): number {
    if (vecA.length !== vecB.length) {
      throw new Error(
        `Vector dimensions don't match: ${vecA.length} vs ${vecB.length}`
      );
    }

    const dotProduct = vecA.reduce((sum, a, i) => sum + a * vecB[i], 0);
    const magnitudeA = Math.hypot(...vecA);
    const magnitudeB = Math.hypot(...vecB);

    if (magnitudeA === 0 || magnitudeB === 0) {
      return 0;
    }

    return dotProduct / (magnitudeA * magnitudeB);
  }

  /**
   * Calculates the dot product of two vectors
   */
  static dotProduct(vecA: number[], vecB: number[]): number {
    if (vecA.length !== vecB.length) {
      throw new Error(
        `Vector dimensions don't match: ${vecA.length} vs ${vecB.length}`
      );
    }

    return vecA.reduce((sum, a, i) => sum + a * vecB[i], 0);
  }

  /**
   * Calculates the magnitude (length) of a vector
   */
  static magnitude(vec: number[]): number {
    return Math.hypot(...vec);
  }

  /**
   * Normalizes a vector (converts to unit vector)
   */
  static normalize(vec: number[]): number[] {
    const mag = this.magnitude(vec);

    if (mag === 0) {
      return Array(vec.length).fill(0);
    }

    return vec.map(v => v / mag);
  }

  /**
   * Converts cosine similarity to angular distance in degrees
   */
  static similarityToDegrees(similarity: number): number {
    // Clamp similarity to [-1, 1] to handle floating point errors
    const clampedSimilarity = Math.max(-1, Math.min(1, similarity));
    return Math.acos(clampedSimilarity) * (180 / Math.PI);
  }
}
```

## Using Cosine Similarity in Real Web Applications

When you work with AI in web applications, you'll often need to calculate similarity between vectors. Here's a practical example:

```typescript
// Example: Semantic search implementation
function semanticSearch(
  queryEmbedding: number[],
  documentEmbeddings: DocumentWithEmbedding[]
): SearchResult[] {
  return documentEmbeddings
    .map(doc => ({
      document: doc,
      relevance: VectorUtils.cosineSimilarity(queryEmbedding, doc.embedding),
    }))
    .filter(result => result.relevance > 0.7) // Only consider relevant results
    .sort((a, b) => b.relevance - a.relevance);
}
```

## Using OpenAI Embedding Models with Cosine Similarity

While the examples above used simple vectors for clarity, real-world AI applications typically use embedding models that transform text and other data into high-dimensional vector spaces.

OpenAI provides powerful embedding models that you can easily incorporate into your applications. These models transform text into vectors with hundreds or thousands of dimensions that capture semantic meaning:

```typescript
// Example of using OpenAI embeddings with our cosine similarity function
async function compareTextSimilarity(
  textA: string,
  textB: string
): Promise<number> {
  // Get embeddings from OpenAI API
  const responseA = await fetch("https://api.openai.com/v1/embeddings", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "text-embedding-3-large",
      input: textA,
    }),
  });

  const responseB = await fetch("https://api.openai.com/v1/embeddings", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "text-embedding-3-large",
      input: textB,
    }),
  });

  const embeddingA = (await responseA.json()).data[0].embedding;
  const embeddingB = (await responseB.json()).data[0].embedding;

  // Calculate similarity using our function
  return VectorUtils.cosineSimilarity(embeddingA, embeddingB);
}
```

<Alert type="warning">
  In a production environment, you should pre-compute embeddings for your
  content (like blog posts, products, or documents) and store them in a vector
  database (like Pinecone, Qdrant, or Milvus). Re-computing embeddings for every
  user request as shown in this example wastes resources and slows performance.
  A better approach: embed your content once during indexing, store the vectors,
  and only embed the user's query when performing a search.
</Alert>

OpenAI's latest embedding models like `text-embedding-3-large` have up to 3,072 dimensions, capturing extremely nuanced semantic relationships between words and concepts. These high-dimensional embeddings enable much more accurate similarity measurements than simpler vector representations.

For more information on OpenAI's embedding models, including best practices and implementation details, check out their documentation at [https://platform.openai.com/docs/guides/embeddings](https://platform.openai.com/docs/guides/embeddings).

## Conclusion

Understanding vectors and cosine similarity provides practical tools that empower you to work effectively with modern AI features. By implementing these concepts in TypeScript, you gain a deeper understanding and precise control over calculating similarity in your applications.
The interactive visualizations we've explored help you build intuition about these mathematical concepts, while the TypeScript implementation gives you the tools to apply them in real-world scenarios.
Whether you build recommendation systems, semantic search, or content-matching features, the foundation you've gained here will help you implement more intelligent, accurate, and effective AI-powered features in your web applications.

## Join the Discussion

This article has sparked interesting discussions across different platforms. Join the conversation to share your thoughts, ask questions, or learn from others' perspectives about implementing cosine similarity in AI applications.

- [Join the discussion on Hacker News →](https://news.ycombinator.com/item?id=43307541)
- [Discuss on Reddit r/typescript →](https://www.reddit.com/r/typescript/comments/1j73whg/how_to_implement_a_cosine_similarity_function_in/)

---

---

--- title: How I Added llms.txt to My Astro Blog description: I built a simple way to load my blog content into any LLM with one click. This post shows how you can do it too. tags: ['astro', 'ai'] url: https://alexop.dev/posts/how-i-added-llms-txt-to-my-astro-blog ---

# How I Added llms.txt to My Astro Blog



## TLDR

I created an endpoint in my Astro blog that outputs all posts in plain text format. This lets me copy my entire blog with one click and paste it into any LLM with adequate context window. The setup uses TypeScript and Astro's API routes, making it work with any Astro content collection.

## Why I Built This

I wanted a quick way to ask AI models questions about my own blog content. Copying posts one by one is slow. With this solution, I can give any LLM all my blog posts at once.

## How It Works

The solution creates a special endpoint that:

1. Gets all blog posts
2. Converts them to plain text
3. Formats them with basic metadata
4. Outputs everything as one big text file

## Setting Up the File

First, I created a new TypeScript file in my Astro pages directory:

```ts
// src/pages/llms.txt.ts
// Function to extract the frontmatter as text
const extractFrontmatter = (content: string): string => {
  const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
  return frontmatterMatch ? frontmatterMatch[1] : "";
};

// Function to clean content while keeping frontmatter
const cleanContent = (content: string): string => {
  // Extract the frontmatter as text
  const frontmatterText = extractFrontmatter(content);

  // Remove the frontmatter delimiters
  let cleanedContent = content.replace(/^---\n[\s\S]*?\n---/, "");

  // Clean up MDX-specific imports
  cleanedContent = cleanedContent.replace(
    /import\s+.*\s+from\s+['"].*['"];?\s*/g,
    ""
  );

  // Remove MDX component declarations
  cleanedContent = cleanedContent.replace(/<\w+\s+.*?\/>/g, "");

  // Remove Shiki Twoslash syntax like
  cleanedContent = cleanedContent.replace(/\/\/\s*@noErrors/g, "");
  cleanedContent = cleanedContent.replace(/\/\/\s*@(.*?)$/gm, ""); // Remove other Shiki Twoslash directives

  // Clean up multiple newlines
  cleanedContent = cleanedContent.replace(/\n\s*\n\s*\n/g, "\n\n");

  // Return the frontmatter as text, followed by the cleaned content
  return frontmatterText + "\n\n" + cleanedContent.trim();
};

export const GET: APIRoute = async () => {
  try {
    // Get all blog posts sorted by date (newest first)
    const posts = await getCollection("blog", ({ data }) => !data.draft);
    const sortedPosts = posts.sort(
      (a, b) =>
        new Date(b.data.pubDatetime).valueOf() -
        new Date(a.data.pubDatetime).valueOf()
    );

    // Generate the content
    let llmsContent = "";

    for (const post of sortedPosts) {
      // Add post metadata in the format similar to the example
      llmsContent += `--- title: ${post.data.title} description: ${post.data.description} tags: [${post.data.tags.map(tag => `'${tag}'`).join(", ")}] ---\n\n`;

      // Add the post title as a heading
      llmsContent += `# ${post.data.title}\n\n`;

      // Process the content, keeping frontmatter as text
      const processedContent = cleanContent(post.body);
      llmsContent += processedContent + "\n\n";

      // Add separator between posts
      llmsContent += "---\n\n";
    }

    // Return the response as plain text
    return new Response(llmsContent, {
      headers: { "Content-Type": "text/plain; charset=utf-8" },
    });
  } catch (error) {
    console.error("Failed to generate llms.txt:", error);
    return new Response("Error generating llms.txt", { status: 500 });
  }
};
```

This code accomplishes four key functions:

1. It uses Astro's `getCollection` function to grab all published blog posts
2. It sorts them by date with newest first
3. It cleans up each post's content with helper functions
4. It formats each post with its metadata and content
5. It returns everything as plain text

## How to Use It

Using this is simple:

1. Visit `alexop.dev/llms.txt` in your browser
2. Press Ctrl+A (or Cmd+A on Mac) to select all the text
3. Copy it (Ctrl+C or Cmd+C)
4. Paste it into any LLM with adequate context window (like ChatGPT, Claude, Llama, etc.)
5. Ask questions about your blog content

The LLM now has all your blog posts in its context window. You can ask questions such as:

- "What topics have I written about?"
- "Summarize my post about [topic]"
- "Find code examples in my posts that use [technology]"
- "What have I written about [specific topic]?"

## Benefits of This Approach

This approach offers distinct advantages:

- Works with any Astro blog
- Requires a single file to set up
- Makes your content easy to query with any LLM
- Keeps useful metadata with each post
- Formats content in a way LLMs understand well

## Conclusion

By adding one straightforward TypeScript file to your Astro blog, you can create a fast way to chat with your own content using any LLM with adequate context window. This makes it easy to:

- Find information in your old posts
- Get summaries of your content
- Find patterns across your writing
- Generate new ideas based on your past content

Give it a try! The setup takes minutes, and it makes interacting with your blog content much faster.

---

--- title: How to Do Visual Regression Testing in Vue with Vitest? description: Learn how to implement visual regression testing in Vue.js using Vitest's browser mode. This comprehensive guide covers setting up screenshot-based testing, creating component stories, and integrating with CI/CD pipelines for automated visual testing. tags: ['vue', 'testing', 'vitest'] url: https://alexop.dev/posts/visual-regression-testing-with-vue-and-vitest-browser ---

# How to Do Visual Regression Testing in Vue with Vitest?



TL;DR:
Visual regression testing detects unintended UI changes by comparing screenshots. With Vitest's experimental browser mode and Playwright, you can:

- **Run tests in a real browser environment**
- **Define component stories for different states**
- **Capture screenshots and compare them with baseline images using snapshot testing**

In this guide, you'll learn how to set up visual regression testing for Vue components using Vitest.

Our test will generate this screenshot:

<CaptionedImage
  src={import("../../assets/images/all-button-variants.png")}
  alt="Screenshot showing all button variants rendered side by side"
  caption="Generated screenshot of all button variants in different states and styles"
/>

<Alert type="definition">
  Visual regression testing captures screenshots of UI components and compares
  them against baseline images to flag visual discrepancies. This ensures
  consistent styling and layout across your design system.
</Alert>

## Vitest Configuration

Start by configuring Vitest with the Vue plugin:

```typescript
export default defineConfig({
  plugins: [vue()],
});
```

## Setting Up Browser Testing

Visual regression tests need a real browser environment. Install these dependencies:

```bash
npm install -D vitest @vitest/browser playwright
```

You can also use the following command to initialize the browser mode:

```bash
npx vitest init browser
```

First, configure Vitest to support both unit and browser tests using a workspace file, `vitest.workspace.ts`. For more details on workspace configuration, see the [Vitest Workspace Documentation](https://vitest.dev/guide/workspace.html).

<Alert type="tip" title="Pro Tip">
  Using a workspace configuration allows you to maintain separate settings for
  unit and browser tests while sharing common configuration. This makes it
  easier to manage different testing environments in your project.
</Alert>

```typescript
export default defineWorkspace([
  {
    extends: "./vitest.config.ts",
    test: {
      name: "unit",
      include: ["**/*.spec.ts", "**/*.spec.tsx"],
      exclude: ["**/*.browser.spec.ts", "**/*.browser.spec.tsx"],
      environment: "jsdom",
    },
  },
  {
    extends: "./vitest.config.ts",
    test: {
      name: "browser",
      include: ["**/*.browser.spec.ts", "**/*.browser.spec.tsx"],
      browser: {
        enabled: true,
        provider: "playwright",
        headless: true,
        instances: [{ browser: "chromium" }],
      },
    },
  },
]);
```

Add scripts in your `package.json`

```json
{
  "scripts": {
    "test": "vitest",
    "test:unit": "vitest --project unit",
    "test:browser": "vitest --project browser"
  }
}
```

Now we can run tests in separate environments like this:

```bash
npm run test:unit
npm run test:browser
```

## The BaseButton Component

Consider the `BaseButton.vue` component a reusable button with customizable size, variant, and disabled state:

```vue
<template>
  <button
    :class="[
      'button',
      `button--${size}`,
      `button--${variant}`,
      { 'button--disabled': disabled },
    ]"
    :disabled="disabled"
    @click="$emit('click', $event)"
  >
    <slot></slot>
  </button>
</template>

<script setup lang="ts">
interface Props {
  size?: "small" | "medium" | "large";
  variant?: "primary" | "secondary" | "outline";
  disabled?: boolean;
}

defineProps<Props>();
defineEmits<{
  (e: "click", event: MouseEvent): void;
}>();
</script>

<style scoped>
.button {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  /* Additional styling available in the GitHub repository */
}

/* Size, variant, and state modifiers available in the GitHub repository */
</style>
```

## Defining Stories for Testing

Create "stories" to showcase different button configurations:

```typescript
const buttonStories = [
  {
    name: "Primary Medium",
    props: { variant: "primary", size: "medium" },
    slots: { default: "Primary Button" },
  },
  {
    name: "Secondary Medium",
    props: { variant: "secondary", size: "medium" },
    slots: { default: "Secondary Button" },
  },
  // and much more ...
];
```

Each story defines a name, props, and slot content.

## Rendering Stories for Screenshots

Render all stories in one container to capture a comprehensive screenshot:

```typescript
interface Story<T> {
  name: string;
  props: Record<string, any>;
  slots: Record<string, string>;
}

function renderStories<T>(
  component: Component,
  stories: Story<T>[]
): HTMLElement {
  const container = document.createElement("div");
  container.style.display = "flex";
  container.style.flexDirection = "column";
  container.style.gap = "16px";
  container.style.padding = "20px";
  container.style.backgroundColor = "#ffffff";

  stories.forEach(story => {
    const storyWrapper = document.createElement("div");
    const label = document.createElement("h3");
    label.textContent = story.name;
    storyWrapper.appendChild(label);

    const { container: storyContainer } = render(component, {
      props: story.props,
      slots: story.slots,
    });
    storyWrapper.appendChild(storyContainer);
    container.appendChild(storyWrapper);
  });

  return container;
}
```

## Writing the Visual Regression Test

Write a test that renders the stories and captures a screenshot:

```typescript
// [buttonStories and renderStories defined above]

describe("BaseButton", () => {
  describe("visual regression", () => {
    it("should match all button variants snapshot", async () => {
      const container = renderStories(BaseButton, buttonStories);
      document.body.appendChild(container);

      const screenshot = await page.screenshot({
        path: "all-button-variants.png",
      });

      // this assertion is acutaly not doing anything
      // but otherwise you would get a warning about the screenshot not being taken
      expect(screenshot).toBeTruthy();

      document.body.removeChild(container);
    });
  });
});
```

Use `render` from `vitest-browser-vue` to capture components as they appear in a real browser.

<Alert type="note">
  Save this file with a `.browser.spec.ts` extension (e.g.,
  `BaseButton.browser.spec.ts`) to match your browser test configuration.
</Alert>

## Beyond Screenshots: Automated Comparison

Automate image comparison by encoding screenshots in base64 and comparing them against baseline snapshots:

```typescript
// Helper function to take and compare screenshots
async function takeAndCompareScreenshot(name: string, element: HTMLElement) {
  const screenshotDir = "./__screenshots__";
  const snapshotDir = "./__snapshots__";
  const screenshotPath = `${screenshotDir}/${name}.png`;

  // Append element to body
  document.body.appendChild(element);

  // Take screenshot
  const screenshot = await page.screenshot({
    path: screenshotPath,
    base64: true,
  });

  // Compare base64 snapshot
  await expect(screenshot.base64).toMatchFileSnapshot(
    `${snapshotDir}/${name}.snap`
  );

  // Save PNG for reference
  await expect(screenshot.path).toBeTruthy();

  // Cleanup
  document.body.removeChild(element);
}
```

Then update the test:

```typescript
describe("BaseButton", () => {
  describe("visual regression", () => {
    it("should match all button variants snapshot", async () => {
      const container = renderStories(BaseButton, buttonStories);
      await expect(
        takeAndCompareScreenshot("all-button-variants", container)
      ).resolves.not.toThrow();
    });
  });
});
```

<Alert type="note" title="Future improvements">
  Vitest is discussing native screenshot comparisons in browser mode. Follow and
  contribute at
  [github.com/vitest-dev/vitest/discussions/690](https://github.com/vitest-dev/vitest/discussions/690).
</Alert>

```mermaid
flowchart LR
    A[Render Component] --> B[Capture Screenshot]
    B --> C{Compare with Baseline}
    C -->|Match| D[Test Passes]
    C -->|Difference| E[Review Changes]
    E -->|Accept| F[Update Baseline]
    E -->|Reject| G[Fix Component]
    G --> A
```

## Conclusion

Vitest's experimental browser mode empowers developers to perform accurate visual regression testing of Vue components in real browser environments.
While the current workflow requires manual review of screenshot comparisons, it establishes a foundation for more automated visual testing in the future.
This approach also strengthens collaboration between developers and UI designers.
Designers can review visual changes to components before production deployment by accessing the generated screenshots in the component library.
For advanced visual testing capabilities, teams should explore dedicated tools like Playwright or Cypress that offer more features and maturity.
Keep in mind to perform visual regression tests against your Base components.

---

--- title: How to Test Vue Router Components with Testing Library and Vitest description: Learn how to test Vue Router components using Testing Library and Vitest. This guide covers real router integration, mocked router setups, and best practices for testing navigation, route guards, and dynamic components in Vue applications. tags: ['vue', 'testing', 'vue-router', 'vitest', 'testing-library'] url: https://alexop.dev/posts/how-to-test-vue-router-components-with-testing-library-and-vitest ---

# How to Test Vue Router Components with Testing Library and Vitest



## TLDR

This guide shows you how to test Vue Router components using real router integration and isolated component testing with mocks. You'll learn to verify router-link interactions, programmatic navigation, and navigation guard handling.

## Introduction

Modern Vue applications need thorough testing to ensure reliable navigation and component performance. We'll cover testing strategies using Testing Library and Vitest to simulate real-world scenarios through router integration and component isolation.

## Vue Router Testing Techniques with Testing Library and Vitest

Let's explore how to write effective tests for Vue Router components using both real router instances and mocks.

## Testing Vue Router Navigation Components

### Navigation Component Example

```vue
<!-- NavigationMenu.vue -->
<script setup lang="ts">
const router = useRouter();
const goToProfile = () => {
  router.push("/profile");
};
</script>

<template>
  <nav>
    <router-link to="/dashboard" class="nav-link">Dashboard</router-link>
    <router-link to="/settings" class="nav-link">Settings</router-link>
    <button @click="goToProfile">Profile</button>
  </nav>
</template>
```

### Real Router Integration Testing

Test complete routing behavior with a real router instance:

```typescript
describe("NavigationMenu", () => {
  it("should navigate using router links", async () => {
    const router = createRouter({
      history: createWebHistory(),
      routes: [
        { path: "/dashboard", component: { template: "Dashboard" } },
        { path: "/settings", component: { template: "Settings" } },
        { path: "/profile", component: { template: "Profile" } },
        { path: "/", component: { template: "Home" } },
      ],
    });

    render(NavigationMenu, {
      global: {
        plugins: [router],
      },
    });

    const user = userEvent.setup();
    expect(router.currentRoute.value.path).toBe("/");

    await router.isReady();
    await user.click(screen.getByText("Dashboard"));
    expect(router.currentRoute.value.path).toBe("/dashboard");

    await user.click(screen.getByText("Profile"));
    expect(router.currentRoute.value.path).toBe("/profile");
  });
});
```

### Mocked Router Testing

Test components in isolation with router mocks:

```typescript
const mockPush = vi.fn();
vi.mock("vue-router", () => ({
  useRouter: vi.fn(),
}));

describe("NavigationMenu with mocked router", () => {
  it("should handle navigation with mocked router", async () => {
    const mockRouter = {
      push: mockPush,
      currentRoute: { value: { path: "/" } },
    } as unknown as Router;

    vi.mocked(useRouter).mockImplementation(() => mockRouter);

    const user = userEvent.setup();
    render(NavigationMenu);

    await user.click(screen.getByText("Profile"));
    expect(mockPush).toHaveBeenCalledWith("/profile");
  });
});
```

### RouterLink Stub for Isolated Testing

Create a RouterLink stub to test navigation without router-link behavior:

```ts
// test-utils.ts
export const RouterLinkStub: Component = {
  name: "RouterLinkStub",
  props: {
    to: {
      type: [String, Object],
      required: true,
    },
    tag: {
      type: String,
      default: "a",
    },
    exact: Boolean,
    exactPath: Boolean,
    append: Boolean,
    replace: Boolean,
    activeClass: String,
    exactActiveClass: String,
    exactPathActiveClass: String,
    event: {
      type: [String, Array],
      default: "click",
    },
  },
  setup(props) {
    const router = useRouter();
    const navigate = () => {
      router.push(props.to);
    };
    return { navigate };
  },
  render() {
    return h(
      this.tag,
      {
        onClick: () => this.navigate(),
      },
      this.$slots.default?.()
    );
  },
};
```

Use the RouterLinkStub in tests:

```ts
const mockPush = vi.fn();
vi.mock("vue-router", () => ({
  useRouter: vi.fn(),
}));

describe("NavigationMenu with mocked router", () => {
  it("should handle navigation with mocked router", async () => {
    const mockRouter = {
      push: mockPush,
      currentRoute: { value: { path: "/" } },
    } as unknown as Router;

    vi.mocked(useRouter).mockImplementation(() => mockRouter);

    const user = userEvent.setup();
    render(NavigationMenu, {
      global: {
        stubs: {
          RouterLink: RouterLinkStub,
        },
      },
    });

    await user.click(screen.getByText("Dashboard"));
    expect(mockPush).toHaveBeenCalledWith("/dashboard");
  });
});
```

### Testing Navigation Guards

Test navigation guards by rendering the component within a route context:

```vue
<script setup lang="ts">
onBeforeRouteLeave(() => {
  return window.confirm("Do you really want to leave this page?");
});
</script>

<template>
  <div>
    <h1>Route Leave Guard Demo</h1>
    <div>
      <nav>
        <router-link to="/">Home</router-link> |
        <router-link to="/about">About</router-link> |
        <router-link to="/guard-demo">Guard Demo</router-link>
      </nav>
    </div>
  </div>
</template>
```

Test the navigation guard:

```ts
const routes = [
  { path: "/", component: RouteLeaveGuardDemo },
  { path: "/about", component: { template: "<div>About</div>" } },
];

const router = createRouter({
  history: createWebHistory(),
  routes,
});

const App = { template: "<router-view />" };

describe("RouteLeaveGuardDemo", () => {
  beforeEach(async () => {
    vi.clearAllMocks();
    window.confirm = vi.fn();
    await router.push("/");
    await router.isReady();
  });

  it("should prompt when guard is triggered and user confirms", async () => {
    // Set window.confirm to simulate a user confirming the prompt
    window.confirm = vi.fn(() => true);

    // Render the component within a router context
    render(App, {
      global: {
        plugins: [router],
      },
    });

    const user = userEvent.setup();

    // Find the 'About' link and simulate a user click
    const aboutLink = screen.getByRole("link", { name: /About/i });
    await user.click(aboutLink);

    // Assert that the confirm dialog was shown with the correct message
    expect(window.confirm).toHaveBeenCalledWith(
      "Do you really want to leave this page?"
    );

    // Verify that the navigation was allowed and the route changed to '/about'
    expect(router.currentRoute.value.path).toBe("/about");
  });
});
```

### Reusable Router Test Helper

Create a helper function to simplify router setup:

```typescript
// test-utils.ts
// path of the definition of your routes
interface RenderWithRouterOptions extends Omit<RenderOptions<any>, "global"> {
  initialRoute?: string;
  routerOptions?: {
    routes?: typeof routes;
    history?: ReturnType<typeof createWebHistory>;
  };
}

export function renderWithRouter(
  Component: any,
  options: RenderWithRouterOptions = {}
) {
  const { initialRoute = "/", routerOptions = {}, ...renderOptions } = options;

  const router = createRouter({
    history: createWebHistory(),
    // Use provided routes or import from your router file
    routes: routerOptions.routes || routes,
  });

  router.push(initialRoute);

  return {
    // Return everything from regular render, plus the router instance
    ...render(Component, {
      global: {
        plugins: [router],
      },
      ...renderOptions,
    }),
    router,
  };
}
```

Use the helper in tests:

```typescript
describe("NavigationMenu", () => {
  it("should navigate using router links", async () => {
    const { router } = renderWithRouter(NavigationMenu, {
      initialRoute: "/",
    });

    await router.isReady();
    const user = userEvent.setup();

    await user.click(screen.getByText("Dashboard"));
    expect(router.currentRoute.value.path).toBe("/dashboard");
  });
});
```

### Conclusion: Best Practices for Vue Router Component Testing

When we test components that rely on the router, we need to consider whether we want to test the functionality in the most realistic use case or in isolation. In my humble opinion, the more you mock a test, the worse it will get. My personal advice would be to aim to use the real router instead of mocking it. Sometimes, there are exceptions, so keep that in mind.

Also, you can help yourself by focusing on components that don't rely on router functionality. Reserve router logic for view/page components. While keeping our components simple, we will never have the problem of mocking the router in the first place.

---

--- title: Building a Pinia Plugin for Cross-Tab State Syncing description: Learn how to create a Pinia plugin that synchronizes state across browser tabs using the BroadcastChannel API and Vue 3's Script Setup syntax. tags: ['vue', 'pinia'] url: https://alexop.dev/posts/building-pinia-plugin-cross-tab-sync ---

# Building a Pinia Plugin for Cross-Tab State Syncing



## TLDR

Create a Pinia plugin that enables state synchronization across browser tabs using the BroadcastChannel API. The plugin allows you to mark specific stores for cross-tab syncing and handles state updates automatically with timestamp-based conflict resolution.

## Introduction

In modern web applications, users often work with multiple browser tabs open. When using Pinia for state management, we sometimes need to ensure that state changes in one tab are reflected across all open instances of our application. This post will guide you through creating a plugin that adds cross-tab state synchronization to your Pinia stores.

## Understanding Pinia Plugins

A Pinia plugin is a function that extends the functionality of Pinia stores. Plugins are powerful tools that help:

- Reduce code duplication
- Add reusable functionality across stores
- Keep store definitions clean and focused
- Implement cross-cutting concerns

## Cross-Tab Communication with BroadcastChannel

The BroadcastChannel API provides a simple way to send messages between different browser contexts (tabs, windows, or iframes) of the same origin. It's perfect for our use case of synchronizing state across tabs.

Key features of BroadcastChannel:

- Built-in browser API
- Same-origin security model
- Simple pub/sub messaging pattern
- No need for external dependencies

### How BroadcastChannel Works

The BroadcastChannel API operates on a simple principle: any browsing context (window, tab, iframe, or worker) can join a channel by creating a `BroadcastChannel` object with the same channel name. Once joined:

1. Messages are sent using the `postMessage()` method
2. Messages are received through the `onmessage` event handler
3. Contexts can leave the channel using the `close()` method

## Implementing the Plugin

### Store Configuration

To use our plugin, stores need to opt-in to state sharing through configuration:

```ts
export const useCounterStore = defineStore(
  "counter",
  () => {
    const count = ref(0);
    const doubleCount = computed(() => count.value * 2);

    function increment() {
      count.value++;
    }

    return { count, doubleCount, increment };
  },
  {
    share: {
      enable: true,
      initialize: true,
    },
  }
);
```

The `share` option enables cross-tab synchronization and controls whether the store should initialize its state from other tabs.

### Plugin Registration `main.ts`

Register the plugin when creating your Pinia instance:

```ts
const pinia = createPinia();
pinia.use(PiniaSharedState);
```

### Plugin Implementation `plugin/plugin.ts`

Here's our complete plugin implementation with TypeScript support:

```ts
type Serializer<T extends StateTree> = {
  serialize: (value: T) => string;
  deserialize: (value: string) => T;
};

interface BroadcastMessage {
  type: "STATE_UPDATE" | "SYNC_REQUEST";
  timestamp?: number;
  state?: string;
}

type PluginOptions<T extends StateTree> = {
  enable?: boolean;
  initialize?: boolean;
  serializer?: Serializer<T>;
};

export interface StoreOptions<
  S extends StateTree = StateTree,
  G = object,
  A = object,
> extends DefineStoreOptions<string, S, G, A> {
  share?: PluginOptions<S>;
}

// Add type extension for Pinia
declare module "pinia" {
  // eslint-disable-next-line @typescript-eslint/no-unused-vars
  export interface DefineStoreOptionsBase<S, Store> {
    share?: PluginOptions<S>;
  }
}

export function PiniaSharedState<T extends StateTree>({
  enable = false,
  initialize = false,
  serializer = {
    serialize: JSON.stringify,
    deserialize: JSON.parse,
  },
}: PluginOptions<T> = {}) {
  return ({ store, options }: PiniaPluginContext) => {
    if (!(options.share?.enable ?? enable)) return;

    const channel = new BroadcastChannel(store.$id);
    let timestamp = 0;
    let externalUpdate = false;

    // Initial state sync
    if (options.share?.initialize ?? initialize) {
      channel.postMessage({ type: "SYNC_REQUEST" });
    }

    // State change listener
    store.$subscribe((_mutation, state) => {
      if (externalUpdate) return;

      timestamp = Date.now();
      channel.postMessage({
        type: "STATE_UPDATE",
        timestamp,
        state: serializer.serialize(state as T),
      });
    });

    // Message handler
    channel.onmessage = (event: MessageEvent<BroadcastMessage>) => {
      const data = event.data;
      if (
        data.type === "STATE_UPDATE" &&
        data.timestamp &&
        data.timestamp > timestamp &&
        data.state
      ) {
        externalUpdate = true;
        timestamp = data.timestamp;
        store.$patch(serializer.deserialize(data.state));
        externalUpdate = false;
      }

      if (data.type === "SYNC_REQUEST") {
        channel.postMessage({
          type: "STATE_UPDATE",
          timestamp,
          state: serializer.serialize(store.$state as T),
        });
      }
    };
  };
}
```

The plugin works by:

1. Creating a BroadcastChannel for each store
2. Subscribing to store changes and broadcasting updates
3. Handling incoming messages from other tabs
4. Using timestamps to prevent update cycles
5. Supporting custom serialization for complex state

### Communication Flow Diagram

```mermaid
flowchart LR
    A[User interacts with store in Tab 1] --> B[Store state changes]
    B --> C[Plugin detects change]
    C --> D[BroadcastChannel posts STATE_UPDATE]
    D --> E[Other tabs receive STATE_UPDATE]
    E --> F[Plugin patches store state in Tab 2]
```

## Using the Synchronized Store

Components can use the synchronized store just like any other Pinia store:

```ts
const counterStore = useCounterStore();
// State changes will automatically sync across tabs
counterStore.increment();
```

## Conclusion

With this Pinia plugin, we've added cross-tab state synchronization with minimal configuration. The solution is lightweight, type-safe, and leverages the built-in BroadcastChannel API. This pattern is particularly useful for applications where users frequently work across multiple tabs and need a consistent state experience.

Remember to consider the following when using this plugin:

- Only enable sharing for stores that truly need it
- Be mindful of performance with large state objects
- Consider custom serialization for complex data structures
- Test thoroughly across different browser scenarios

## Future Optimization: Web Workers

For applications with heavy cross-tab communication or complex state transformations, consider offloading the BroadcastChannel handling to a Web Worker. This approach can improve performance by:

- Moving message processing off the main thread
- Handling complex state transformations without blocking UI
- Reducing main thread load when syncing large state objects
- Buffering and batching state updates for better performance

This is particularly beneficial when:

- Your application has many tabs open simultaneously
- State updates are frequent or computationally intensive
- You need to perform validation or transformation on synced data
- The application handles large datasets that need to be synced

You can find the complete code for this plugin in the [GitHub repository](https://github.com/alexanderop/pluginPiniaTabs).
It also has examples of how to use it with Web Workers.

---

--- title: How to Use AI for Effective Diagram Creation: A Guide to ChatGPT and Mermaid description: Learn how to leverage ChatGPT and Mermaid to create effective diagrams for technical documentation and communication. tags: ['ai', 'productivity'] url: https://alexop.dev/posts/how-to-use-ai-for-effective-diagram-creation-a-guide-to-chatgpt-and-mermaid ---

# How to Use AI for Effective Diagram Creation: A Guide to ChatGPT and Mermaid



## TLDR

Learn how to combine ChatGPT and Mermaid to quickly create professional diagrams for technical documentation. This approach eliminates the complexity of traditional diagramming tools while maintaining high-quality output.

## Introduction

Mermaid is a markdown-like script language that generates diagrams from text descriptions. When combined with ChatGPT, it becomes a powerful tool for creating technical diagrams quickly and efficiently.

## Key Diagram Types

### Flowcharts

Perfect for visualizing processes:

```plaintext
flowchart LR
  A[Customer selects products] --> B[Customer reviews order]
  B --> C{Payment Successful?}
  C -->|Yes| D[Generate Invoice]
  D --> E[Dispatch goods]
  C -->|No| F[Redirect to Payment]
```

```mermaid
flowchart LR
  A[Customer selects products] --> B[Customer reviews order]
  B --> C{Payment Successful?}
  C -->|Yes| D[Generate Invoice]
  D --> E[Dispatch goods]
  C -->|No| F[Redirect to Payment]
```

### Sequence Diagrams

Ideal for system interactions:

```plaintext
sequenceDiagram
    participant Client
    participant Server
    Client->>Server: Request (GET /resource)
    Server-->>Client: Response (200 OK)
```

```mermaid
sequenceDiagram
    participant Client
    participant Server
    Client->>Server: Request (GET /resource)
    Server-->>Client: Response (200 OK)
```

## Using ChatGPT with Mermaid

1. Ask ChatGPT to explain your concept
2. Request a Mermaid diagram representation
3. Iterate on the diagram with follow-up questions

Example prompt: "Create a Mermaid sequence diagram showing how Nuxt.js performs server-side rendering"

```plaintext
sequenceDiagram
  participant Client as Client Browser
  participant Nuxt as Nuxt.js Server
  participant Vue as Vue.js Application
  participant API as Backend API

  Client->>Nuxt: Initial Request
  Nuxt->>Vue: SSR Starts
  Vue->>API: API Calls (if any)
  API-->>Vue: API Responses
  Vue->>Nuxt: Rendered HTML
  Nuxt-->>Client: HTML Content
```

```mermaid
sequenceDiagram
  participant Client as Client Browser
  participant Nuxt as Nuxt.js Server
  participant Vue as Vue.js Application
  participant API as Backend API

  Client->>Nuxt: Initial Request
  Nuxt->>Vue: SSR Starts
  Vue->>API: API Calls (if any)
  API-->>Vue: API Responses
  Vue->>Nuxt: Rendered HTML
  Nuxt-->>Client: HTML Content
```

## Quick Setup Guide

### Online Editor

Use [Mermaid Live Editor](https://mermaid.live/) for quick prototyping.

### VS Code Integration

1. Install "Markdown Preview Mermaid Support" extension
2. Create `.md` file with Mermaid code blocks
3. Preview with built-in markdown viewer

### Web Integration

```html
<script src="https://unpkg.com/mermaid/dist/mermaid.min.js"></script>
<script>
  mermaid.initialize({ startOnLoad: true });
</script>
<div class="mermaid">graph TD A-->B</div>
```

## Conclusion

The combination of ChatGPT and Mermaid streamlines technical diagramming, making it accessible and efficient. Try it in your next documentation project to save time while creating professional diagrams.

---

--- title: The Browser That Speaks 200 Languages: Building an AI Translator Without APIs description: Learn how to build a browser-based translator that works offline and handles 200 languages using Vue and Transformers.js tags: ['vue', 'ai'] url: https://alexop.dev/posts/building-client-side-ai-translator-vue ---

# The Browser That Speaks 200 Languages: Building an AI Translator Without APIs



## Introduction

Most AI translation tools rely on external APIs.
This means sending data to servers and paying for each request. But what if you could run translations directly in your browser? This guide shows you how to build a free, offline translator that handles 200 languages using Vue and Transformers.js.

## The Tools

- Vue 3 for the interface
- Transformers.js to run AI models locally
- Web Workers to handle heavy processing
- NLLB-200, Meta's translation model

```mermaid
---
title: Architecture Overview
---

graph LR
    Frontend[Vue Frontend]
    Worker[Web Worker]
    TJS[Transformers.js]
    Model[NLLB-200 Model]

    Frontend -->|"Text"| Worker
    Worker -->|"Initialize"| TJS
    TJS -->|"Load"| Model
    Model -->|"Results"| TJS
    TJS -->|"Stream"| Worker
    Worker -->|"Translation"| Frontend

    classDef default fill:#344060,stroke:#AB4B99,color:#EAEDF3
    classDef accent fill:#8A337B,stroke:#AB4B99,color:#EAEDF3

    class TJS,Model accent
```

## Building the Translator

![AI Translator](../../assets/images/vue-ai-translate.png)

### 1. Set Up Your Project

Create a new Vue project with TypeScript:

```bash
npm create vite@latest vue-translator -- --template vue-ts
cd vue-translator
npm install
npm install @huggingface/transformers
```

### 2. Create the Translation Worker

The translation happens in a background process. Create `src/worker/translation.worker.ts`:

```typescript
import {
  pipeline,
  TextStreamer,
  TranslationPipeline,
} from "@huggingface/transformers";
// Singleton pattern for the translation pipeline
class MyTranslationPipeline {
  static task: PipelineType = "translation";
  // We use the distilled model for faster loading and inference
  static model = "Xenova/nllb-200-distilled-600M";
  static instance: TranslationPipeline | null = null;

  static async getInstance(progress_callback?: ProgressCallback) {
    if (!this.instance) {
      this.instance = (await pipeline(this.task, this.model, {
        progress_callback,
      })) as TranslationPipeline;
    }
    return this.instance;
  }
}

// Type definitions for worker messages
interface TranslationRequest {
  text: string;
  src_lang: string;
  tgt_lang: string;
}

// Worker message handler
self.addEventListener(
  "message",
  async (event: MessageEvent<TranslationRequest>) => {
    try {
      // Initialize the translation pipeline with progress tracking
      const translator = await MyTranslationPipeline.getInstance(x => {
        self.postMessage(x);
      });

      // Configure streaming for real-time translation updates
      const streamer = new TextStreamer(translator.tokenizer, {
        skip_prompt: true,
        skip_special_tokens: true,
        callback_function: (text: string) => {
          self.postMessage({
            status: "update",
            output: text,
          });
        },
      });

      // Perform the translation
      const output = await translator(event.data.text, {
        
        tgt_lang: event.data.tgt_lang,
        src_lang: event.data.src_lang,
        streamer,
      });

      // Send the final result
      self.postMessage({
        status: "complete",
        output,
      });
    } catch (error) {
      self.postMessage({
        status: "error",
        error:
          error instanceof Error ? error.message : "An unknown error occurred",
      });
    }
  }
);
```

### 3. Build the Interface

Create a clean interface with two main components:

#### Language Selector (`src/components/LanguageSelector.vue`)

```vue
<script setup lang="ts">
// Language codes follow the ISO 639-3 standard with script codes
const LANGUAGES: Record<string, string> = {
  English: "eng_Latn",
  French: "fra_Latn",
  Spanish: "spa_Latn",
  German: "deu_Latn",
  Chinese: "zho_Hans",
  Japanese: "jpn_Jpan",
  // Add more languages as needed
};
// Strong typing for component props
interface Props {
  type: string;
  modelValue: string;
}

defineProps<Props>();
const emit = defineEmits<{
  (e: "update:modelValue", value: string): void;
}>();

const onChange = (event: Event) => {
  const target = event.target as HTMLSelectElement;
  emit("update:modelValue", target.value);
};
</script>

<template>
  <div class="language-selector">
    <label>{{ type }}: </label>
    <select :value="modelValue" @change="onChange">
      <option
        v-for="[key, value] in Object.entries(LANGUAGES)"
        :key="key"
        :value="value"
      >
        {{ key }}
      </option>
    </select>
  </div>
</template>

<style scoped>
.language-selector {
  display: flex;
  align-items: center;
  gap: 0.5rem;
}

select {
  padding: 0.5rem;
  border-radius: 4px;
  border: 1px solid rgb(var(--color-border));
  background-color: rgb(var(--color-card));
  color: rgb(var(--color-text-base));
  min-width: 200px;
}
</style>
```

#### Progress Bar (`src/components/ProgressBar.vue`)

```vue
<script setup lang="ts">
defineProps<{
  text: string;
  percentage: number;
}>();
</script>

<template>
  <div class="progress-container">
    <div class="progress-bar" :style="{ width: `${percentage}%` }">
      {{ text }} ({{ percentage.toFixed(2) }}%)
    </div>
  </div>
</template>

<style scoped>
.progress-container {
  width: 100%;
  height: 20px;
  background-color: rgb(var(--color-card));
  border-radius: 10px;
  margin: 10px 0;
  overflow: hidden;
  border: 1px solid rgb(var(--color-border));
}

.progress-bar {
  height: 100%;
  background-color: rgb(var(--color-accent));
  transition: width 0.3s ease;
  display: flex;
  align-items: center;
  padding: 0 10px;
  color: rgb(var(--color-text-base));
  font-size: 0.9rem;
  white-space: nowrap;
}

.progress-bar:hover {
  background-color: rgb(var(--color-card-muted));
}
</style>
```

### 4. Put It All Together

In your main app file:

```vue
<script setup lang="ts">
interface ProgressItem {
  file: string;
  progress: number;
}

// State
const worker = ref<Worker | null>(null);
const ready = ref<boolean | null>(null);
const disabled = ref(false);
const progressItems = ref<Map<string, ProgressItem>>(new Map());

const input = ref("I love walking my dog.");
const sourceLanguage = ref("eng_Latn");
const targetLanguage = ref("fra_Latn");
const output = ref("");

// Computed property for progress items array
const progressItemsArray = computed(() => {
  return Array.from(progressItems.value.values());
});

// Watch progress items
watch(
  progressItemsArray,
  newItems => {
    console.log("Progress items updated:", newItems);
  },
  { deep: true }
);

// Translation handler
const translate = () => {
  if (!worker.value) return;

  disabled.value = true;
  output.value = "";

  worker.value.postMessage({
    text: input.value,
    src_lang: sourceLanguage.value,
    tgt_lang: targetLanguage.value,
  });
};

// Worker message handler
const onMessageReceived = (e: MessageEvent) => {
  switch (e.data.status) {
    case "initiate":
      ready.value = false;
      progressItems.value.set(e.data.file, {
        file: e.data.file,
        progress: 0,
      });
      progressItems.value = new Map(progressItems.value);
      break;

    case "progress":
      if (progressItems.value.has(e.data.file)) {
        progressItems.value.set(e.data.file, {
          file: e.data.file,
          progress: e.data.progress,
        });
        progressItems.value = new Map(progressItems.value);
      }
      break;

    case "done":
      progressItems.value.delete(e.data.file);
      progressItems.value = new Map(progressItems.value);
      break;

    case "ready":
      ready.value = true;
      break;

    case "update":
      output.value += e.data.output;
      break;

    case "complete":
      disabled.value = false;
      break;

    case "error":
      console.error("Translation error:", e.data.error);
      disabled.value = false;
      break;
  }
};

// Lifecycle hooks
onMounted(() => {
  worker.value = new Worker(
    new URL("./workers/translation.worker.ts", import.meta.url),
    { type: "module" }
  );
  worker.value.addEventListener("message", onMessageReceived);
});

onUnmounted(() => {
  worker.value?.removeEventListener("message", onMessageReceived);
  worker.value?.terminate();
});
</script>

<template>
  <div class="app">
    <h1>Transformers.js</h1>
    <h2>ML-powered multilingual translation in Vue!</h2>

    <div class="container">
      <div class="language-container">

      </div>

      <div class="textbox-container">
        <textarea
          v-model="input"
          rows="3"
          placeholder="Enter text to translate..."
        />
        <textarea
          v-model="output"
          rows="3"
          readonly
          placeholder="Translation will appear here..."
        />
      </div>
    </div>

    <button :disabled="disabled || ready === false" @click="translate">
      {{ ready === false ? "Loading..." : "Translate" }}
    </button>

    <div class="progress-bars-container">
      <label v-if="ready === false"> Loading models... (only run once) </label>
      <div v-for="item in progressItemsArray" :key="item.file">
        
      </div>
    </div>
  </div>
</template>

<style scoped>
.app {
  max-width: 800px;
  margin: 0 auto;
  padding: 2rem;
  text-align: center;
}

.container {
  margin: 2rem 0;
}

.language-container {
  display: flex;
  justify-content: center;
  gap: 2rem;
  margin-bottom: 1rem;
}

.textbox-container {
  display: flex;
  gap: 1rem;
}

textarea {
  flex: 1;
  padding: 0.5rem;
  border-radius: 4px;
  border: 1px solid rgb(var(--color-border));
  background-color: rgb(var(--color-card));
  color: rgb(var(--color-text-base));
  font-size: 1rem;
  min-height: 100px;
  resize: vertical;
}

button {
  padding: 0.5rem 2rem;
  font-size: 1.1rem;
  cursor: pointer;
  background-color: rgb(var(--color-accent));
  color: rgb(var(--color-text-base));
  border: none;
  border-radius: 4px;
  transition: background-color 0.3s;
}

button:hover:not(:disabled) {
  background-color: rgb(var(--color-card-muted));
}

button:disabled {
  opacity: 0.6;
  cursor: not-allowed;
}

.progress-bars-container {
  margin-top: 2rem;
}

h1 {
  color: rgb(var(--color-text-base));
  margin-bottom: 0.5rem;
}

h2 {
  color: rgb(var(--color-card-muted));
  font-size: 1.2rem;
  font-weight: normal;
  margin-top: 0;
}
</style>
```

## Step 5: Optimizing the Build

Configure Vite to handle our Web Workers and TypeScript efficiently:

```typescript
export default defineConfig({
  plugins: [vue()],
  worker: {
    format: "es", // Use ES modules format for workers
    plugins: [], // No additional plugins needed for workers
  },
  optimizeDeps: {
    exclude: ["@huggingface/transformers"], // Prevent Vite from trying to bundle Transformers.js
  },
});
```

## How It Works

1. You type text and select languages
2. The text goes to a Web Worker
3. Transformers.js loads the AI model (once)
4. The model translates your text
5. You see the translation appear in real time

The translator works offline after the first run. No data leaves your browser. No API keys needed.

## Try It Yourself

Want to explore the code further? Check out the complete source code on [GitHub](https://github.com/alexanderop/vue-ai-translate-poc).

Want to learn more? Explore these resources:

- [Transformers.js docs](https://huggingface.co/docs/transformers.js)
- [NLLB-200 model details](https://huggingface.co/facebook/nllb-200-distilled-600M)
- [Web Workers guide](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API)

---

--- title: Solving Prop Drilling in Vue: Modern State Management Strategies description: Eliminate prop drilling in Vue apps using Composition API, Provide/Inject, and Pinia. Learn when to use each approach with practical examples. tags: ['vue'] url: https://alexop.dev/posts/solving-prop-drilling-in-vue ---

# Solving Prop Drilling in Vue: Modern State Management Strategies



## TL;DR: Prop Drilling Solutions at a Glance

- **Global state**: Pinia (Vue's official state management)
- **Reusable logic**: Composables
- **Component subtree sharing**: Provide/Inject
- **Avoid**: Event buses for state management

> Click the toggle button to see interactive diagram animations that demonstrate each concept.

---

## The Hidden Cost of Prop Drilling: A Real-World Scenario

Imagine building a Vue dashboard where the user's name needs to be displayed in seven nested components. Every intermediate component becomes a middleman for data it doesn't need. Imagine changing the prop name from `userName` to `displayName`. You'd have to update six components to pass along something they don't use!

**This is prop drilling** – and it creates:

- 🚨 **Brittle code** that breaks during refactors
- 🕵️ **Debugging nightmares** from unclear data flow
- 🐌 **Performance issues** from unnecessary re-renders

---

## Solution 1: Pinia for Global State Management

### When to Use: App-wide state (user data, auth state, cart items)

**Implementation**:

```javascript
// stores/user.js
export const useUserStore = defineStore('user', {
const username = ref(localStorage.getItem('username') || 'Guest');
const isLoggedIn = computed(() => username.value !== 'Guest');

function setUsername(newUsername) {
    username.value = newUsername;
    localStorage.setItem('username', newUsername);
}

return {
    username,
    isLoggedIn,
    setUsername
};
});
```

**Component Usage**:

```vue
<!-- DeeplyNestedComponent.vue -->
<script setup>
const user = useUserStore();
</script>

<template>
  <div class="user-info">
    Welcome, {{ user.username }}!
    <button v-if="!user.isLoggedIn" @click="user.setUsername('John')">
      Log In
    </button>
  </div>
</template>
```

✅ **Pros**

- Centralized state with DevTools support
- TypeScript-friendly
- Built-in SSR support

⚠️ **Cons**

- Overkill for small component trees
- Requires understanding of Flux architecture

---

## Solution 2: Composables for Reusable Logic

### When to Use: Shared component logic (user preferences, form state)

**Implementation with TypeScript**:

```typescript
// composables/useUser.ts
const username = ref(localStorage.getItem("username") || "Guest");

export function useUser() {
  const setUsername = (newUsername: string) => {
    username.value = newUsername;
    localStorage.setItem("username", newUsername);
  };

  return {
    username,
    setUsername,
  };
}
```

**Component Usage**:

```vue
<!-- UserProfile.vue -->
<script setup lang="ts">
const { username, setUsername } = useUser();
</script>

<template>
  <div class="user-profile">
    <h2>Welcome, {{ username }}!</h2>
    <button @click="setUsername('John')">Update Username</button>
  </div>
</template>
```

✅ **Pros**

- Zero-dependency solution
- Perfect for logic reuse across components
- Full TypeScript support

⚠️ **Cons**

- Shared state requires singleton pattern
- No built-in DevTools integration
- **SSR Memory Leaks**: State declared outside component scope persists between requests
- **Not SSR-Safe**: Using this pattern in SSR can lead to state pollution across requests

## Solution 3: Provide/Inject for Component Tree Scoping

### When to Use: Library components or feature-specific user data

**Type-Safe Implementation**:

```typescript

// utilities/user.ts
interface UserContext {
  username: Ref<string>;
  updateUsername: (name: string) => void;
}

export const UserKey = Symbol('user') as InjectionKey<UserContext>;

// ParentComponent.vue
<script setup lang="ts">
const username = ref<string>('Guest');
const updateUsername = (name: string) => {
  username.value = name;
};

provide(UserKey, { username, updateUsername });
</script>

// DeepChildComponent.vue
<script setup lang="ts">
const { username, updateUsername } = inject(UserKey, {
  username: ref('Guest'),
  updateUsername: () => console.warn('No user provider!'),
});
</script>
```

✅ **Pros**

- Explicit component relationships
- Perfect for component libraries
- Type-safe with TypeScript

⚠️ **Cons**

- Can create implicit dependencies
- Debugging requires tracing providers

---

## Why Event Buses Fail for State Management

Event buses create more problems than they solve for state management:

1. **Spaghetti Data Flow**  
   Components become invisibly coupled through arbitrary events. When `ComponentA` emits `update-theme`, who's listening? Why? DevTools can't help you track the chaos.

2. **State Inconsistencies**  
   Multiple components listening to the same event often maintain duplicate state:

   ```javascript
   // Two components, two sources of truth
   eventBus.on("login", () => (this.isLoggedIn = true));
   eventBus.on("login", () => (this.userStatus = "active"));
   ```

3. **Memory Leaks**  
   Forgotten event listeners in unmounted components keep reacting to events, causing bugs and performance issues.

**Where Event Buses Actually Work**

- ✅ Global notifications (toasts, alerts)
- ✅ Analytics tracking
- ✅ Decoupled plugin events

**Instead of Event Buses**: Use Pinia for state, composables for logic, and provide/inject for component trees.

```mermaid
---
title: "Decision Guide: Choosing Your Weapon"
---
graph TD
    A[Need Shared State?] -->|No| B[Props/Events]
    A -->|Yes| C{Scope?}
    C -->|App-wide| D[Pinia]
    C -->|Component Tree| E[Provide/Inject]
    C -->|Reusable Logic| F[Composables]
```

## Pro Tips for State Management Success

1. **Start Simple**: Begin with props, graduate to composables
2. **Type Everything**: Use TypeScript for stores/injections
3. **Name Wisely**: Prefix stores (`useUserStore`) and injection keys (`UserKey`)
4. **Monitor Performance**: Use Vue DevTools to track reactivity
5. **Test State**: Write unit tests for Pinia stores/composables

By mastering these patterns, you'll write Vue apps that scale gracefully while keeping component relationships clear and maintainable.

---

--- title: Building Local-First Apps with Vue and Dexie.js description: Learn how to create offline-capable, local-first applications using Vue 3 and Dexie.js. Discover patterns for data persistence, synchronization, and optimal user experience. tags: ['vue', 'dexie', 'indexeddb', 'local-first'] url: https://alexop.dev/posts/building-local-first-apps-vue-dexie ---

# Building Local-First Apps with Vue and Dexie.js



Ever been frustrated when your web app stops working because the internet connection dropped? That's where local-first applications come in! In this guide, we'll explore how to build robust, offline-capable apps using Vue 3 and Dexie.js. If you're new to local-first development, check out my [comprehensive introduction to local-first web development](https://alexop.dev/posts/what-is-local-first-web-development/) first.

## What Makes an App "Local-First"?

Martin Kleppmann defines local-first software as systems where "the availability of another computer should never prevent you from working." Think Notion's desktop app or Figma's offline mode - they store data locally first and seamlessly sync when online.

Three key principles:

1. Works without internet connection
2. Users stay productive when servers are down
3. Data syncs smoothly when connectivity returns

## The Architecture Behind Local-First Apps

```mermaid
---
title: Local-First Architecture with Central Server
---
flowchart LR
    subgraph Client1["Client Device"]
        UI1["UI"] --> DB1["Local Data"]
    end

    subgraph Client2["Client Device"]
        UI2["UI"] --> DB2["Local Data"]
    end

    subgraph Server["Central Server"]
        SDB["Server Data"]
        Sync["Sync Service"]
    end

    DB1 <--> Sync
    DB2 <--> Sync
    Sync <--> SDB
```

Key decisions:

- How much data to store locally (full vs. partial dataset)
- How to handle multi-user conflict resolution

## Enter Dexie.js: Your Local-First Swiss Army Knife

Dexie.js provides a robust offline-first architecture where database operations run against local IndexedDB first, ensuring responsiveness without internet connection.

```mermaid
---
title: Dexie.js Local-First Implementation
---
flowchart LR
    subgraph Client["Client"]
        App["Application"]
        Dexie["Dexie.js"]
        IDB["IndexedDB"]

        App --> Dexie
        Dexie --> IDB

        subgraph DexieSync["Dexie Sync"]
            Rev["Revision Tracking"]
            Queue["Sync Queue"]
            Rev --> Queue
        end
    end

    subgraph Cloud["Dexie Cloud"]
        Auth["Auth Service"]
        Store["Data Store"]
        Repl["Replication Log"]

        Auth --> Store
        Store --> Repl
    end

    Dexie <--> Rev
    Queue <--> Auth
    IDB -.-> Queue
    Queue -.-> Store
```

### Sync Strategies

1. **WebSocket Sync**: Real-time updates for collaborative apps
2. **HTTP Long-Polling**: Default sync mechanism, firewall-friendly
3. **Service Worker Sync**: Optional background syncing when configured

## Setting Up Dexie Cloud

To enable multi-device synchronization and real-time collaboration, we'll use Dexie Cloud. Here's how to set it up:

1. **Create a Dexie Cloud Account**:
   - Visit [https://dexie.org/cloud/](https://dexie.org/cloud/)
   - Sign up for a free developer account
   - Create a new database from the dashboard

2. **Install Required Packages**:

   ```bash
   npm install dexie-cloud-addon
   ```

3. **Configure Environment Variables**:
   Create a `.env` file in your project root:

   ```bash
   VITE_DEXIE_CLOUD_URL=https://db.dexie.cloud/db/<your-db-id>
   ```

   Replace `<your-db-id>` with the database ID from your Dexie Cloud dashboard.

4. **Enable Authentication**:
   Dexie Cloud provides built-in authentication. You can:
   - Use email/password authentication
   - Integrate with OAuth providers
   - Create custom authentication flows

The free tier includes:

- Up to 50MB of data per database
- Up to 1,000 sync operations per day
- Basic authentication and access control
- Real-time sync between devices

## Building a Todo App

Let's implement a practical example with a todo app:

```mermaid
flowchart TD
    subgraph VueApp["Vue Application"]
        App["App.vue"]
        TodoList["TodoList.vue<br>Component"]
        UseTodo["useTodo.ts<br>Composable"]
        Database["database.ts<br>Dexie Configuration"]

        App --> TodoList
        TodoList --> UseTodo
        UseTodo --> Database
    end

    subgraph DexieLayer["Dexie.js Layer"]
        IndexedDB["IndexedDB"]
        SyncEngine["Dexie Sync Engine"]

        Database --> IndexedDB
        Database --> SyncEngine
    end

    subgraph Backend["Backend Services"]
        Server["Server"]
        ServerDB["Server Database"]

        SyncEngine <-.-> Server
        Server <-.-> ServerDB
    end
```

## Setting Up the Database

```typescript
export interface Todo {
  id?: string;
  title: string;
  completed: boolean;
  createdAt: Date;
}

export class TodoDB extends Dexie {
  todos!: Table<Todo>;

  constructor() {
    super("TodoDB", { addons: [dexieCloud] });

    this.version(1).stores({
      todos: "@id, title, completed, createdAt",
    });
  }

  async configureSync(databaseUrl: string) {
    await this.cloud.configure({
      databaseUrl,
      requireAuth: true,
      tryUseServiceWorker: true,
    });
  }
}

export const db = new TodoDB();

if (!import.meta.env.VITE_DEXIE_CLOUD_URL) {
  throw new Error("VITE_DEXIE_CLOUD_URL environment variable is not defined");
}

db.configureSync(import.meta.env.VITE_DEXIE_CLOUD_URL).catch(console.error);

export const currentUser = db.cloud.currentUser;
export const login = () => db.cloud.login();
export const logout = () => db.cloud.logout();
```

## Creating the Todo Composable

```typescript
export function useTodos() {
  const newTodoTitle = ref("");
  const error = ref<string | null>(null);

  const todos = useObservable<Todo[]>(
    from(liveQuery(() => db.todos.orderBy("createdAt").toArray()))
  );

  const completedTodos = computed(
    () => todos.value?.filter(todo => todo.completed) ?? []
  );

  const pendingTodos = computed(
    () => todos.value?.filter(todo => !todo.completed) ?? []
  );

  const addTodo = async () => {
    try {
      if (!newTodoTitle.value.trim()) return;

      await db.todos.add({
        title: newTodoTitle.value,
        completed: false,
        createdAt: new Date(),
      });

      newTodoTitle.value = "";
      error.value = null;
    } catch (err) {
      error.value = "Failed to add todo";
      console.error(err);
    }
  };

  const toggleTodo = async (todo: Todo) => {
    try {
      await db.todos.update(todo.id!, {
        completed: !todo.completed,
      });
      error.value = null;
    } catch (err) {
      error.value = "Failed to toggle todo";
      console.error(err);
    }
  };

  const deleteTodo = async (id: string) => {
    try {
      await db.todos.delete(id);
      error.value = null;
    } catch (err) {
      error.value = "Failed to delete todo";
      console.error(err);
    }
  };

  return {
    todos,
    newTodoTitle,
    error,
    completedTodos,
    pendingTodos,
    addTodo,
    toggleTodo,
    deleteTodo,
  };
}
```

## Authentication Guard Component

```vue
<script setup lang="ts">
import {
  Card,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
} from "@/components/ui/card";
const user = useObservable(currentUser);
const isAuthenticated = computed(() => !!user.value);
const isLoading = ref(false);

async function handleLogin() {
  isLoading.value = true;
  try {
    await login();
  } finally {
    isLoading.value = false;
  }
}
</script>

<template>
  <div
    v-if="!isAuthenticated"
    class="bg-background flex min-h-screen flex-col items-center justify-center p-4"
  >
    <Card class="w-full max-w-md">
      <!-- Login form content -->
    </Card>
  </div>
  <template v-else>
    <div class="bg-card sticky top-0 z-20 border-b">
      <!-- User info and logout button -->
    </div>
    
  </template>
</template>
```

## Better Architecture: Repository Pattern

```typescript
export interface TodoRepository {
  getAll(): Promise<Todo[]>;
  add(todo: Omit<Todo, "id">): Promise<string>;
  update(id: string, todo: Partial<Todo>): Promise<void>;
  delete(id: string): Promise<void>;
  observe(): Observable<Todo[]>;
}

export class DexieTodoRepository implements TodoRepository {
  constructor(private db: TodoDB) {}

  async getAll() {
    return this.db.todos.toArray();
  }

  observe() {
    return from(liveQuery(() => this.db.todos.orderBy("createdAt").toArray()));
  }

  async add(todo: Omit<Todo, "id">) {
    return this.db.todos.add(todo);
  }

  async update(id: string, todo: Partial<Todo>) {
    await this.db.todos.update(id, todo);
  }

  async delete(id: string) {
    await this.db.todos.delete(id);
  }
}

export function useTodos(repository: TodoRepository) {
  const newTodoTitle = ref("");
  const error = ref<string | null>(null);
  const todos = useObservable<Todo[]>(repository.observe());

  const addTodo = async () => {
    try {
      if (!newTodoTitle.value.trim()) return;
      await repository.add({
        title: newTodoTitle.value,
        completed: false,
        createdAt: new Date(),
      });
      newTodoTitle.value = "";
      error.value = null;
    } catch (err) {
      error.value = "Failed to add todo";
      console.error(err);
    }
  };

  return {
    todos,
    newTodoTitle,
    error,
    addTodo,
    // ... other methods
  };
}
```

## Understanding the IndexedDB Structure

When you inspect your application in the browser's DevTools under the "Application" tab > "IndexedDB", you'll see a database named "TodoDB-zy02f1..." with several object stores:

### Internal Dexie Stores (Prefixed with $)

> Note: These stores are only created when using Dexie Cloud for sync functionality.

- **$baseRevs**: Keeps track of base revisions for synchronization
- **$jobs**: Manages background synchronization tasks
- **$logins**: Stores authentication data including your last login timestamp
- **$members_mutations**: Tracks changes to member data for sync
- **$realms_mutations**: Tracks changes to realm/workspace data
- **$roles_mutations**: Tracks changes to role assignments
- **$syncState**: Maintains the current synchronization state
- **$todos_mutations**: Records all changes made to todos for sync and conflict resolution

### Application Data Stores

- **members**: Contains user membership data with compound indexes:
  - `[userId+realmId]`: For quick user-realm lookups
  - `[email+realmId]`: For email-based queries
  - `realmId`: For realm-specific queries
- **realms**: Stores available workspaces
- **roles**: Manages user role assignments
- **todos**: Your actual todo items containing:
  - Title
  - Completed status
  - Creation timestamp

Here's how a todo item actually looks in IndexedDB:

```json
{
  "id": "tds0PI7ogcJqpZ1JCly0qyAheHmcom",
  "title": "test",
  "completed": false,
  "createdAt": "Tue Jan 21 2025 08:40:59 GMT+0100 (Central Europe)",
  "owner": "opalic.alexander@gmail.com",
  "realmId": "opalic.alexander@gmail.com"
}
```

Each todo gets a unique `id` generated by Dexie, and when using Dexie Cloud, additional fields like `owner` and `realmId` are automatically added for multi-user support.

Each store in IndexedDB acts like a table in a traditional database, but is optimized for client-side storage and offline operations. The `$`-prefixed stores are managed automatically by Dexie.js to handle:

1. **Offline Persistence**: Your todos are stored locally
2. **Multi-User Support**: User data in `members` and `roles`
3. **Sync Management**: All `*_mutations` stores track changes
4. **Authentication**: Login state in `$logins`

## Understanding Dexie's Merge Conflict Resolution

```mermaid
%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#344360', 'primaryBorderColor': '#ab4b99', 'primaryTextColor': '#eaedf3', 'lineColor': '#ab4b99', 'textColor': '#eaedf3' }}}%%
flowchart LR
    A[Detect Change Conflict] --> B{Different Fields?}
    B -->|Yes| C[Auto-Merge Changes]
    B -->|No| D{Same Field Conflict}
    D --> E[Apply Server Version<br>Last-Write-Wins]
    F[Delete Operation] --> G[Always Takes Priority<br>Over Updates]
```

Dexie's conflict resolution system is sophisticated and field-aware, meaning:

- Changes to different fields of the same record can be merged automatically
- Conflicts in the same field use last-write-wins with server priority
- Deletions always take precedence over updates to prevent "zombie" records

This approach ensures smooth collaboration while maintaining data consistency across devices and users.

## Conclusion

This guide demonstrated building local-first applications with Dexie.js and Vue. For simpler applications like todo lists or note-taking apps, Dexie.js provides an excellent balance of features and simplicity. For more complex needs similar to Linear, consider building a custom sync engine.

Find the complete example code on [GitHub](https://github.com/alexanderop/vue-dexie).

---

--- title: Adding Obsidian-Style Wiki Links to My Astro Blog description: I added [[wiki link]] syntax to my Astro blog with hover preview cards. Here's how it works and how you can build it too. tags: ['astro', 'markdown', 'obsidian'] url: https://alexop.dev/posts/adding-obsidian-wiki-links-to-astro-blog ---

# Adding Obsidian-Style Wiki Links to My Astro Blog



## TLDR

I built a remark plugin that transforms `[[slug]]` syntax into internal links with hover preview cards. It supports multiple content collections, custom display text, and shows broken link warnings at build time.

## Live Examples

Hover over these links to see the preview cards in action:

**Blog post:** [[are-llms-creative]]

**Blog post with alias:** [[are-llms-creative|my thoughts on LLM creativity]]

**TIL:** [[til:dynamic-pinia-stores]]

**Notes:** [[notes:software-testing-with-generative-ai|Testing with AI]]

**Broken link:** [[this-post-does-not-exist]]

All of these are written as simple `[[slug]]` syntax in the markdown source.

## Why I Built This

I use Obsidian for note-taking and love the `[[wiki link]]` syntax. It's fast to type and creates connections between notes naturally. I wanted the same experience when writing blog posts.

Before this, I had an `InternalLink` component that required MDX imports:

```mdx
Check out <InternalLink slug="some-post">this post</InternalLink>.
```

Too verbose. I wanted to just type `[[some-post]]` and have it work.

## How It Works

The solution uses a custom remark plugin that:

1. Finds `[[...]]` patterns in markdown text
2. Looks up the post metadata from the file system
3. Generates the full preview card HTML at build time

### Supported Syntax

```markdown
[[slug]]                           # Links to blog post
[[slug|custom text]]               # With display text
[[til:slug]]                       # Links to TIL collection
[[notes:slug|my notes]]            # Other collections with alias
```

### The Preview Card

Hover over any wiki link to see a preview card with:

- Post title
- Description (3 lines max)
- Tags (first 3)
- Publication date

The card uses fixed positioning to escape overflow containers and flips below the link when too close to the viewport top.

## Building the Remark Plugin

The plugin runs during markdown processing. It reads all content collection files at initialization and caches the metadata for fast lookups.

```ts
// src/lib/remarkWikiLinks.ts
const WIKI_LINK_REGEX = /\[\[([^\]|]+?)(?:\|([^\]]+))?\]\]/g;

export function remarkWikiLinks() {
  // Load all posts at plugin init
  const cache = loadAllPosts();

  return (tree) => {
    visit(tree, "text", (node, index, parent) => {
      const matches = [...node.value.matchAll(WIKI_LINK_REGEX)];
      if (matches.length === 0) return;

      // Replace matches with HTML nodes containing preview cards
      // ...
    });
  };
}
```

The key insight: remark plugins can output raw HTML nodes. The plugin generates the complete preview card markup, so no separate rehype processing is needed.

### Parsing the Syntax

The regex captures two groups:

1. The target (either `slug` or `collection:slug`)
2. The optional alias after the pipe

```ts
function parseWikiLink(target: string, alias?: string) {
  let collection = "blog";
  let slug = target;

  if (target.includes(":")) {
    const [col, sl] = target.split(":", 2);
    if (["blog", "til", "notes", "prompts"].includes(col)) {
      collection = col;
      slug = sl;
    }
  }

  return { collection, slug, alias };
}
```

### Loading Post Metadata

The plugin reads frontmatter directly from content files using `gray-matter`:

```ts
function loadCollectionPosts(collection: string) {
  const posts = new Map();
  const dir = `src/content/${collection}`;

  for (const file of fs.readdirSync(dir, { recursive: true })) {
    if (!file.endsWith(".md") && !file.endsWith(".mdx")) continue;

    const content = fs.readFileSync(`${dir}/${file}`, "utf-8");
    const { data } = matter(content);

    if (data.draft) continue;

    const slug = file.replace(/\.(md|mdx)$/, "");
    posts.set(slug, {
      title: data.title,
      description: data.description,
      tags: data.tags,
      pubDatetime: data.pubDatetime,
    });
  }

  return posts;
}
```

### Generating Preview Card HTML

The plugin outputs the same HTML structure as my existing `InternalLink` component:

```ts
function createPreviewCardHtml(post, href, displayText) {
  return `
    <span class="internal-link-wrapper">
      <a href="${href}" class="internal-link">${displayText}</a>
      <span class="preview-card" role="tooltip">
        <span class="preview-content">
          <span class="preview-title">${post.title}</span>
          <span class="preview-description">${post.description}</span>
          <!-- tags and date -->
        </span>
      </span>
    </span>
  `;
}
```

## Broken Link Detection

When a wiki link references a non-existent post, the plugin:

1. Logs a warning during build: `[wiki-links] Post not found: blog:missing-slug`
2. Renders the link with error styling (red wavy underline)

```ts
if (!postData) {
  console.warn(`[wiki-links] Post not found: ${collection}:${slug}`);
  return `<span class="wiki-link-broken" title="Post not found: ${slug}">${displayText}</span>`;
}
```

This catches typos and stale references before they hit production.

## Adding the Plugin to Astro

Register the plugin in `astro.config.ts`:

```ts
export default defineConfig({
  markdown: {
    remarkPlugins: [
      remarkWikiLinks,
      // other plugins...
    ],
  },
});
```

The plugin runs first so wiki links are processed before other transformations.

## The CSS

The styles match my existing `InternalLink` component:

```css
.internal-link-wrapper {
  position: relative;
  display: inline-block;
}

.internal-link {
  @apply text-skin-accent underline decoration-dashed;
}

.preview-card {
  position: absolute;
  bottom: calc(100% + 8px);
  opacity: 0;
  visibility: hidden;
  transition: opacity 0.2s;
}

.wiki-link-broken {
  @apply text-red-400 underline decoration-wavy;
}
```

## The Hover Script

A small inline script handles the preview card positioning:

```js
document.addEventListener("astro:page-load", () => {
  document.querySelectorAll(".internal-link-wrapper").forEach((wrapper) => {
    wrapper.addEventListener("mouseenter", () => {
      const card = wrapper.querySelector(".preview-card");
      // Calculate position, flip if needed, show card
    });
  });
});
```

The script runs on `astro:page-load` to work with Astro's view transitions.

## Result

Now I can write posts with natural wiki link syntax:

```markdown
I wrote about [[are-llms-creative|LLM creativity]] last month.
See also my [[til:dynamic-pinia-stores|TIL on Pinia stores]].
```

The links render with hover previews, and broken references get caught at build time. Much better than importing components everywhere.

## What's Next

A few improvements I'm considering:

- Fuzzy matching for slug typos
- Backlinks section showing which posts link to the current one
- Support for heading anchors: `[[post#section]]`

---

--- title: Unlocking Reading Insights: A Guide to Data Analysis with Claude and Readwise description: Discover how to transform your reading data into actionable insights by combining Readwise exports with Claude AI's powerful analysis capabilities tags: ['ai', 'productivity', 'reading'] url: https://alexop.dev/posts/supercharging-reading-comprehension-claude-readwise ---

# Unlocking Reading Insights: A Guide to Data Analysis with Claude and Readwise



Recently, I've been exploring Claude.ai's new CSV analysis feature, which allows you to upload spreadsheet data for automated analysis and visualization. In this blog post, I'll demonstrate how to leverage Claude.ai's capabilities using Readwise data as an example. We'll explore how crafting better prompts can help you extract more meaningful insights from your data. Additionally, we'll peek under the hood to understand the technical aspects of how Claude processes and analyzes this information.

Readwise is a powerful application that syncs and organizes highlights from your Kindle and other reading platforms. While this tutorial uses Readwise data as an example, the techniques demonstrated here can be applied to analyze any CSV dataset with Claude.

## The Process: From Highlights to Insights

### 1. Export and Initial Setup

First things first: export your Readwise highlights as CSV.
Just login into your Readwise account and go to -> https://readwise.io/export
Scroll down to the bottom and click on "Export to CSV"
![Readwise Export CSV](../../assets/images/readwise_claude_csv/readwise_export_csv.png)

### 2. Upload the CSV into Claude

Drop that CSV into Claude's interface. Yes, it's that simple. No need for complex APIs or coding knowledge.

> Note: The CSV file must fit within Claude's conversation context window. For very large export files, you may need to split them into smaller chunks.

### 3. Use Prompts to analyze the data

#### a) First Approach

First we will use a generic Prompt to see what would happen if we don't even know what to analyze for:

```plaintext
Please Claude, analyze this data for me.
```

<AstroGif
  src="/images/readwise_claude_csv/claude_first_prompt.gif"
  alt="Claude first prompt response"
  caption="Claude analyzing the initial prompt and providing a structured response"
/>

Claude analyzed my Readwise data and provided a high-level overview:

- Collection stats: 1,322 highlights across 131 books by 126 authors from 2018-2024
- Most highlighted books focused on writing and note-taking, with "How to Take Smart Notes" leading at 102 highlights
- Tag analysis showed "discard" as most common (177), followed by color tags and topical tags like "mental" and "tech"

Claude also offered to dive deeper into highlight lengths, reading patterns over time, tag relationships, and data visualization.
Even with this basic prompt, Claude provides valuable insights and analysis. The initial overview can spark ideas for deeper investigation and more targeted analysis. However, we can craft more specific prompts to extract even more meaningful insights from our data.

### 4. Visualization and Analysis

While our last Prompt did give use some insights, it was not very useful for me.
Also I am a visual person, so I want to see some visualizations.

This is why I created this Prompt to get better Visualization I also added the Colors
from this blog since I love them.

```plaintext
Create a responsive data visualization dashboard for my Readwise highlights using React and Recharts.

Theme Colors (Dark Mode):
- Background: rgb(33, 39, 55)
- Text: rgb(234, 237, 243)
- Accent: rgb(255, 107, 237)
- Card Background: rgb(52, 63, 96)
- Muted Elements: rgb(138, 51, 123)
- Borders: rgb(171, 75, 153)

Color Application:
- Use background color for main dashboard
- Apply text color for all typography
- Use accent color for interactive elements and highlights
- Apply card background for visualization containers
- Use muted colors for secondary information
- Implement borders for section separation

Input Data Structure:
- CSV format with columns:
  - Highlight text
  - Book Title
  - Book Author
  - Color
  - Tags
  - Location
  - Highlighted Date

Required Visualizations:
1. Reading Analytics:
   - Average reading time per book (calculated from highlight timestamps)
   - Reading patterns by time of day (heatmap using card background and accent colors)
   - Heat map showing active reading days
     - Base: rgb(52, 63, 96)
     - Intensity levels: rgb(138, 51, 123) → rgb(255, 107, 237)

2. Content Analysis:
   - Vertical bar chart: Top 10 most highlighted books
   - Bars: gradient from rgb(138, 51, 123) to rgb(255, 107, 237)
   - Labels: rgb(234, 237, 243)
   - Grid lines: rgba(171, 75, 153, 0.2)

3. Timeline View:
   - Monthly highlighting activity
   - Line color: rgb(255, 107, 237)
   - Area fill: rgba(255, 107, 237, 0.1)
   - Grid: rgba(171, 75, 153, 0.15)

4. Knowledge Map:
   - Interactive mind map using force-directed graph
   - Node colors: rgb(52, 63, 96)
   - Node borders: rgb(171, 75, 153)
   - Connections: rgba(255, 107, 237, 0.6)
   - Hover state: rgb(255, 107, 237)

5. Summary Statistics Card:
   - Background: rgb(52, 63, 96)
   - Border: rgb(171, 75, 153)
   - Headings: rgb(234, 237, 243)
   - Values: rgb(255, 107, 237)

Design Requirements:
- Typography:
  - Primary font: Light text on dark background
  - Base text: rgb(234, 237, 243)
  - Minimum 16px for body text
  - Headings: rgb(255, 107, 237)

- Card Design:
  - Background: rgb(52, 63, 96)
  - Border: 1px solid rgb(171, 75, 153)
  - Border radius: 8px
  - Box shadow: 0 4px 6px rgba(0, 0, 0, 0.1)

- Interaction States:
  - Hover: Accent color rgb(255, 107, 237)
  - Active: rgb(138, 51, 123)
  - Focus: 2px solid rgb(255, 107, 237)

- Responsive Design:
  - Desktop: Grid layout with 2-3 columns
  - Tablet: 2 columns
  - Mobile: Single column, stacked
  - Gap: 1.5rem
  - Padding: 2rem

Accessibility:
- Ensure contrast ratio ≥ 4.5:1 with text color
- Use rgba(234, 237, 243, 0.7) for secondary text
- Provide focus indicators using accent color
- Include aria-labels for interactive elements
- Support keyboard navigation

Performance:
- Implement CSS variables for theme colors
- Use CSS transitions for hover states
- Optimize SVG rendering for mind map
- Implement virtualization for large datasets
```

<AstroGif
  src="/images/readwise_claude_csv/readwise_analytics.gif"
  alt="Claude second prompt response"
  caption="Interactive dashboard visualization of Readwise highlights analysis"
/>

The interactive dashboard generated by Claude demonstrates the powerful synergy between generative AI and data analysis.
By combining Claude's natural language processing capabilities with programmatic visualization, we can transform raw reading data into actionable insights. This approach allows us to extract meaningful patterns and trends that would be difficult to identify through manual analysis alone.

Now I want to give you some tips on how to get the best out of claude.

## Writing Effective Analysis Prompts

Here are key principles for crafting prompts that generate meaningful insights:

### 1. Start with Clear Objectives

Instead of vague requests, specify what you want to learn:

```plaintext
Analyze my reading data to identify:
1. Time-of-day reading patterns
2. Most engaged topics
3. Knowledge connection opportunities
4. Potential learning gaps
```

### 2. Use Role-Based Prompting

Give Claude a specific expert perspective:

```plaintext
Act as a learning science researcher analyzing my reading patterns.
Focus on:
- Comprehension patterns
- Knowledge retention indicators
- Learning efficiency metrics
```

### 3. Request Specific Visualizations

Be explicit about the visual insights you need:

```plaintext
Create visualizations showing:
1. Daily reading heatmap
2. Topic relationship network
3. Highlight frequency trends
Use theme-consistent colors for clarity
```

## Bonus: Behind the Scenes - How the Analysis Tool Works

For those curious about the technical implementation, let's peek under the hood at how Claude uses the analysis tool to process your Readwise data:

### The JavaScript Runtime Environment

When you upload your Readwise CSV, Claude has access to a JavaScript runtime environment similar to a browser's console. This environment comes pre-loaded with several powerful libraries:

```javascript
// Available libraries
// For CSV processing
// For data manipulation
// For UI components
// For visualizations
```

### Data Processing Pipeline

The analysis happens in two main stages:

1. **Initial Data Processing:**

```javascript
async function analyzeReadingData() {
  // Read the CSV file
  const fileContent = await window.fs.readFile("readwisedata.csv", {
    encoding: "utf8",
  });

  // Parse CSV using Papaparse
  const parsedData = Papa.parse(fileContent, {
    header: true,
    skipEmptyLines: true,
    dynamicTyping: true,
  });

  // Analyze time patterns
  const timeAnalysis = parsedData.data.map(row => {
    const date = new Date(row["Highlighted at"]);
    return {
      hour: date.getHours(),
      title: row["Book Title"],
      tags: row["Tags"],
    };
  });

  // Group and count data using lodash
  const hourlyDistribution = _.countBy(timeAnalysis, "hour");
  console.log("Reading time distribution:", hourlyDistribution);
}
```

2. **Visualization Component:**

```javascript
const ReadingPatterns = () => {
  const [timeData, setTimeData] = useState([]);
  const [topBooks, setTopBooks] = useState([]);

  useEffect(() => {
    const analyzeData = async () => {
      const response = await window.fs.readFile("readwisedata.csv", {
        encoding: "utf8",
      });

      // Process time data for visualization
      const timeAnalysis = parsedData.data.reduce((acc, row) => {
        const hour = new Date(row["Highlighted at"]).getHours();
        acc[hour] = (acc[hour] || 0) + 1;
        return acc;
      }, {});

      // Format data for charts
      const timeDataForChart = Object.entries(timeAnalysis).map(
        ([hour, count]) => ({
          hour: `${hour}:00`,
          count,
        })
      );

      setTimeData(timeDataForChart);
    };
    analyzeData();
  }, []);

  return (
    <div className="w-full space-y-8 p-4">
      <ResponsiveContainer width="100%" height="100%">
        <BarChart data={timeData}>

        </BarChart>
      </ResponsiveContainer>
    </div>
  );
};
```

### Key Technical Features

1. **Asynchronous File Handling**: The `window.fs.readFile` API provides async file access, similar to Node.js's fs/promises.

2. **Data Processing Libraries**:
   - Papaparse handles CSV parsing with options for headers and type conversion
   - Lodash provides efficient data manipulation functions
   - React and Recharts enable interactive visualizations

3. **React Integration**:
   - Components use hooks for state management
   - Tailwind classes for styling
   - Responsive container adapts to screen size

4. **Error Handling**: The code includes proper error boundaries and async/await patterns to handle potential issues gracefully.

This technical implementation allows Claude to process your reading data efficiently while providing interactive visualizations that help you understand your reading patterns better.

## Conclusion

I hope this blog post demonstrates how AI can accelerate data analysis workflows. What previously required significant time and technical expertise can now be accomplished in minutes. This democratization of data analysis empowers people without coding backgrounds to gain valuable insights from their own data.

---

--- title: The What Why and How of Goal Settings description: A deep dive into the philosophy of goal-setting and personal development, exploring the balance between happiness and meaning while providing practical steps for achieving your goals in 2025. tags: ['personal-development', 'productivity'] url: https://alexop.dev/posts/the-what-why-and-how-of-goal-settings ---

# The What Why and How of Goal Settings



There is beauty in having goals and in aiming to achieve them. This idea is perfectly captured by Jim Rohn's quote:

> "Become a millionaire not for the million dollars, but for what it will make of you to achieve it."

This wisdom suggests that humans need goals to reach them and grow and improve through the journey. Yet, this perspective isn't without its critics. Take, for instance, this provocative quote from Fight Club:

> "SELF-IMPROVEMENT IS MASTURBATION, NOW SELF-DESTRUCTION..." - TYLER DURDEN

This counter-view raises an interesting point: focusing too much on self-improvement can become narcissistic and isolating. Rather than connecting with others or making real change, someone might become trapped in an endless cycle of self-focus, similar to the character's own psychological struggles.

Despite these conflicting viewpoints, I find the pursuit of self-improvement invigorating, probably because I grew up watching anime. I have always loved the classic story arc, in which the hero faces a devastating loss, then trains and comes back stronger than before. This narrative speaks to something fundamental about human potential and resilience.

But let's dig deeper into the practical side of goal-setting. If you align more with Jim Rohn's philosophy of continuous improvement, you might wonder how to reach your goals. However, I've found that what's harder than the "how" is actually the "what" and "why." Why do you even want to reach goals? This question becomes especially relevant in our modern Western society, where many people seem settled for working their 9-5, doing the bare minimum, then watching Netflix. Maybe they have a girlfriend or boyfriend, and their only adventure is visiting other countries. Or they just enjoy living in the moment. Or they have a kid, and that child becomes the whole meaning of life.

These are all valid ways to live, but they raise an interesting question about happiness versus meaning. This reminds me of a profound conversation from the series "Heroes":

Mr. Linderman: "You see, I think there comes a time when a man has to ask himself whether he wants a life of happiness or a life of meaning."

Nathan Petrelli: "I'd like to think I have both."

Mr. Linderman: "Can't be done. Two very different paths. I mean, to be truly happy, a man must live absolutely in the present. And with no thought of what's gone before, and no thought of what lies ahead. But, a life of meaning... A man is condemned to wallow in the past and obsess about the future. And my guess is that you've done quite a bit of obsessing about yours these last few days."

This dialogue highlights a fundamental dilemma in goal-setting. If your sole aim is happiness, perhaps the wisest path would be to retreat to Tibet and meditate all day, truly living in the now. But for many of us, pursuing meaning through goals provides its own form of fulfillment.

Before setting any goals, you need to honestly assess what you want. Sometimes, your goal is maintaining what you already have - a good job, house, spouse, and kids. However, this brings up another trap I've encountered personally. I used to think that once I had everything I wanted, I could stop trying, assuming things would stay the same. This is often a fundamental mistake. Even maintaining the status quo requires continuous work and attention.

Once you understand your "why," you can formulate specific goals. You need to develop a clear vision of how you want your life to look in the coming years. Let's use weight loss as an example since it's familiar and easily quantifiable.

Consider this vision: "I want to be healthy and look good by the end of the year. I want to be more self-confident."

Now, let's examine how not to structure your goal. Many people simply say, "My goal is to lose weight." With such a vague objective, you might join the gym in January and countless others. Still, when life throws curveballs your way - illness, work stress, or missed training sessions - your commitment quickly fades because there's no clear target to maintain your focus.

A better approach would be setting a specific goal like "I want to weigh x KG by y date." This brings clarity and measurability to your objective. However, even this improved goal isn't enough on its own. You must build a system - an environment that naturally nudges you toward your goals. As James Clear, author of Atomic Habits, brilliantly puts it:

> "You do not rise to the level of your goals. You fall to the level of your systems."

This insight from one of the most influential books on habit formation reminds us that motivation alone is unreliable. Instead, you need to create sustainable habits that align with your goals. For a weight loss goal of 10kg by May, these habits might include:

- weighing yourself daily
- tracking calories
- walking 10k steps
- going to the gym 3 times per week

Another powerful insight from James Clear concerns the language we use with ourselves. For instance, if you're trying to quit smoking and someone offers you a cigarette, don't say you're trying to stop or that you're an ex-smoker. Instead, firmly state, "I don't smoke," from day one. This simple shift in language helps reprogram your identity - you're not just trying to become a non-smoker, you already are one. Fake it till you make it.

While habit-tracking apps can be helpful tools when starting out, remember to be gentle with yourself. If you miss a day, don't let it unravel your entire journey. This leads to the most important advice: don't do it alone. Despite what some YouTube gurus might suggest about "monk mode" and isolation, finding a community of like-minded individuals can be crucial for success. Share your journey, find accountability partners, and don't hesitate to work out with others.

To summarize the path to reaching your goals:

## Why

Be honest with yourself. Think about your life. Are you happy with it? What kind of meaning do you want to create?

## What

If you're content with your life, what aspects need maintenance? If not, what specific changes would create the life you envision? Think carefully about which goals would elevate your life's quality and meaning.

## How

Once you've identified a meaningful goal that resonates deeply with your values, the implementation becomes clearer:

1. Write down the goal in specific, measurable terms
2. Set a realistic timeline for accomplishment
3. Study and adopt the habits of those who've already achieved similar goals
4. Track your progress consistently
5. Build a supportive community of like-minded people
6. Distance yourself from influences that don't align with your new direction (you know who they are)

Remember, the journey toward your goals is as important as reaching them. Through this process, you'll discover not just what you can achieve but who you can become.

---

--- title: XML-Style Tagged Prompts: A Framework for Reliable AI Responses description: Learn how top AI engineers use XML-style prompts to consistently get structured, accurate responses from ChatGPT, Claude, and other LLMs. Step-by-step guide with real examples tags: ['ai', 'llm', 'prompt-engineering'] url: https://alexop.dev/posts/xml-tagged-prompts-framework-reliable-ai-responses ---

# XML-Style Tagged Prompts: A Framework for Reliable AI Responses



## Why Traditional AI Communication Falls Short

Getting consistent, well-structured responses can be challenging when working with LLMs. Traditional prompting often leads to unpredictable results, making relying on AI assistance for complex tasks difficult.
While exploring prompt engineering techniques this year, I discovered an interesting approach: Tagged Prompts. This method has improved my interactions with AI, delivering more thoughtful responses.

## What Are Tagged Prompts? A Simple Guide

Tagged prompts borrow from XML's structured approach to data organization. By wrapping different parts of our prompts in descriptive tags, we create a clear framework for AI responses. Think of it as creating a mental model that guides the AI's thinking process.

### The XML Connection

To understand tagged prompts, let's first look at XML's simple yet powerful structure:

```xml
<book>
  <title>The Great Gatsby</title>
  <author>F. Scott Fitzgerald</author>
</book>
```

This familiar structure provides the foundation for our prompt engineering approach.

## How Tagged Prompts Work: XML-Style Structure

Let's compare how an AI responds to the same question with and without tagged prompts:

### Standard Response

<ChatUI
  question="I want to learn software engineering. What should I do?"
  answer={`I'll help you create a structured path to learn software engineering. Here's a comprehensive approach:

First, start with programming fundamentals:

1. Learn a beginner-friendly programming language like Python or JavaScript
2. Master basic concepts like variables, data types, control flow, functions, and object-oriented programming
3. Practice with small projects to reinforce your learning

Once you have the basics, focus on:

- **Version Control**: Learn Git and GitHub to manage code and collaborate with others
- **Data Structures & Algorithms**: Understanding these is crucial for writing efficient code and passing technical interviews
- **Development Tools**: Get comfortable with an IDE (like VS Code), command line, and debugging tools
- **Web Development Fundamentals**: HTML, CSS, and JavaScript if you're interested in web development
- **Testing**: Learn about unit tests, integration tests, and test-driven development
- **Databases**: Start with SQL basics, then learn about database design

Practical steps you can take:

1. Choose learning resources:
   - Free platforms like freeCodeCamp, The Odin Project, or CS50x
   - Paid platforms like Udemy, Coursera, or boot camps
   - Technical books and documentation

2. Build projects:
   - Start with small, achievable projects
   - Gradually increase complexity
   - Create a portfolio to showcase your work

3. Join the community:
   - Participate in coding forums like Stack Overflow
   - Join local coding meetups
   - Contribute to open source projects

Would you like me to suggest some specific resources for any of these areas? Or would you prefer to focus on a particular aspect of software engineering?`}
/>

## Before vs After: Impact of Tagged Prompts on AI Responses

## Step-by-Step Guide to Implementing Tagged Prompts

Tagged prompts can be implemented in two ways:

1. As a system prompt for ongoing AI interactions
2. As part of individual conversation messages

<CaptionedImage
  src={systemPromptClaude}
  alt="Claude System Prompt"
  caption="Example of how a system prompt with instructions on Claude's project looks like."
/>

### Basic Implementation

Here's a simple but effective system prompt structure:

<SystemPromptUI
  prompt={`When answering queries:
1. Think through your reasoning in <thinking> tags
2. Provide your answer in <output> tags 
3. If you spot an error, explain and correct it in <reflection> tags`}
/>

### Tagged Response Example

<ChatUI
  question="I want to learn software engineering. What should I do?"
  answer={`<thinking>
Let me break this down systematically:
1. Software engineering is a broad field - need to cover both fundamentals and practical skills
2. Should suggest a structured learning path that's manageable
3. Important to emphasize both theoretical knowledge and hands-on practice
4. Need to include guidance on building a portfolio and joining the community
5. Should consider both formal and self-learning options
</thinking>
<output>
Here's a comprehensive path to get started with software engineering:
Start with Programming Fundamentals:
Begin with Python or JavaScript - they're beginner-friendly and widely used. Focus on basics like variables, control flow, functions, and data structures. Platforms like freeCodeCamp or The Odin Project offer free structured courses.
Build Computer Science Foundation:
Learn core concepts like:

Data structures (arrays, linked lists, trees)
Basic algorithms and their complexity
How computers work at a basic level
Version control with Git

Practice Project-Based Learning:

Start with small projects that teach fundamentals
Gradually increase complexity as you learn
Build projects that solve real problems you encounter
Document your code and maintain a GitHub portfolio

Join the Community:

Participate in coding communities on Discord or Reddit
Contribute to open source projects
Attend local tech meetups or virtual events
Find a mentor or study group

Recommended Learning Path:

Month 1-2: Programming basics and Git
Month 3-4: Web development fundamentals (HTML, CSS, JavaScript)
Month 5-6: Choose a specialization (backend, frontend, mobile, etc.)
Month 7-8: Build portfolio projects
Month 9+: Advanced topics and job preparation

Resources to Consider:

CS50 from Harvard (free on edX) for computer science basics
freeCodeCamp for web development
"Clean Code" by Robert Martin for best practices
LeetCode for coding practice

Would you like me to elaborate on any of these areas or suggest resources for a specific aspect you're most interested in?

</output>
<reflection>
After reviewing my response, I note that while comprehensive, I could have:
1. Emphasized the importance of learning testing early in the process
2. Mentioned the value of understanding databases
3. Included information about different learning styles and approaches
However, these can be addressed in follow-up discussion based on the human's interests and needs.
</reflection>`}
/>

## Advanced Techniques: Taking Tagged Prompts Further

For more sophisticated applications, we can add quality metrics and step tracking:

<SystemPromptUI 
  prompt={`Use <thinking> tags to explore different approaches and viewpoints  
Use <step> tags to break down the solution (20 step budget, request more if needed)  
Add <count> tags after each step to track remaining budget  
Use <reflection> tags to evaluate progress and be self-critical  
Rate quality with <reward> tags (0.0-1.0):

- Greater than or equal to 0.8: Continue approach
- Between 0.5 and 0.7: Minor adjustments
- Less than 0.5: Try new approach

Show all work and calculations explicitly  
Explore multiple solutions when possible  
Summarize final answer in <answer> tags  
End with final reflection and reward score  
Adjust strategy based on reward scores and intermediate results`}
/>

## Tagged Prompts in Production: v0 by Vercel Case Study

Vercel's AI assistant v0 demonstrates how tagged prompts work in production. Their implementation, revealed through a [leaked prompt on Reddit](https://www.reddit.com/r/LocalLLaMA/comments/1gwwyia/leaked_system_prompts_from_v0_vercels_ai/), shows the power of structured prompts in professional tools.

## Essential Resources for Mastering Tagged Prompts

For deeper exploration of tagged prompts and related concepts:

- [Claude Documentation on Structured Outputs](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/use-xml-tags)
- [Prompt Engineering Guide](https://www.promptingguide.ai/)

## Key Takeaways: Getting Started with Tagged Prompts

This was just a quick overview to explain the basic idea of tagged prompts.
I would suggest trying out this technique for your specific use case.
Compare responses with tags and without tags to see the difference.

---

--- title: How to Use the Variant Props Pattern in Vue description: Learn how to create type-safe Vue components where prop types depend on other props using TypeScript discriminated unions. A practical guide with real-world examples. tags: ['vue', 'typescript'] url: https://alexop.dev/posts/vue-typescript-variant-props-type-safe-props ---

# How to Use the Variant Props Pattern in Vue



Building Vue components that handle multiple variations while maintaining type safety can be tricky. Let's dive into the Variant Props Pattern (VPP) - a powerful approach that uses TypeScript's discriminated unions with Vue's composition API to create truly type-safe component variants.

## TL;DR

The Variant Props Pattern in Vue combines TypeScript's discriminated unions with Vue's prop system to create type-safe component variants. Instead of using complex type utilities, we explicitly mark incompatible props as never to prevent prop mixing at compile time:

```typescript
// Define base props
type BaseProps = {
  title: string;
};

// Success variant prevents error props
type SuccessProps = BaseProps & {
  variant: "success";
  message: string;
  errorCode?: never; // Prevents mixing
};

// Error variant prevents success props
type ErrorProps = BaseProps & {
  variant: "error";
  errorCode: string;
  message?: never; // Prevents mixing
};

type Props = SuccessProps | ErrorProps;
```

This pattern provides compile-time safety, excellent IDE support, and reliable vue-tsc compatibility. Perfect for components that need multiple, mutually exclusive prop combinations.

## The Problem: Mixed Props Nightmare

Picture this: You're building a notification component that needs to handle both success and error states. Each state has its own specific properties:

- Success notifications need a `message` and `duration`
- Error notifications need an `errorCode` and a `retryable` flag

Without proper type safety, developers might accidentally mix these props:

```html
<!-- This should fail! -->
<NotificationAlert
  variant="primary"
  title="Data Saved"
  message="Success!"
  errorCode="UPLOAD_001"  <!-- 🚨 Mixing success and error props -->
  :duration="5000"
  @close="handleClose"
/>
```

## The Simple Solution That Doesn't Work

Your first instinct might be to define separate interfaces:

```typescript
interface SuccessProps {
  title: string;
  variant: "primary" | "secondary";
  message: string;
  duration: number;
}

interface ErrorProps {
  title: string;
  variant: "danger" | "warning";
  errorCode: string;
  retryable: boolean;
}

// 🚨 This allows mixing both types!
type Props = SuccessProps & ErrorProps;
```

The problem? This approach allows developers to use both success and error props simultaneously - definitely not what we want!

## Using Discriminated Unions with `never`

> **TypeScript Tip**: The `never` type is a special type in TypeScript that represents values that never occur. When a property is marked as `never`, TypeScript ensures that value can never be assigned to that property. This makes it perfect for creating mutually exclusive props, as it prevents developers from accidentally using props that shouldn't exist together.
>
> The `never` type commonly appears in TypeScript in several scenarios:
>
> - Functions that never return (throw errors or have infinite loops)
> - Exhaustive type checking in switch statements
> - Impossible type intersections (e.g., `string & number`)
> - Making properties mutually exclusive, as we do in this pattern

The main trick to make it work with the current implmenation of defineProps is to use `never` to explicitly mark unused variant props.

```typescript
// Base props shared between variants
type BaseProps = {
  title: string;
};

// Success variant
type SuccessProps = BaseProps & {
  variant: "primary" | "secondary";
  message: string;
  duration: number;
  // Explicitly mark error props as never
  errorCode?: never;
  retryable?: never;
};

// Error variant
type ErrorProps = BaseProps & {
  variant: "danger" | "warning";
  errorCode: string;
  retryable: boolean;
  // Explicitly mark success props as never
  message?: never;
  duration?: never;
};

// Final props type - only one variant allowed!
type Props = SuccessProps | ErrorProps;
```

## Important Note About Vue Components

When implementing this pattern, you'll need to make your component generic due to a current type restriction in `defineComponent`.
By making the component generic, we can bypass `defineComponent` and define the component as a functional component:

```vue
<script setup lang="ts" generic="T">
// Now our discriminated union props will work correctly
type BaseProps = {
  title: string;
};

type SuccessProps = BaseProps & {
  variant: "primary" | "secondary";
  message: string;
  duration: number;
  errorCode?: never;
  retryable?: never;
};

// ... rest of the types
</script>
```

This approach allows TypeScript to properly enforce our prop variants at compile time.

## Putting It All Together

Here's our complete notification component using the Variant Props Pattern:

## Conclusion

The Variant Props Pattern (VPP) provides a robust approach for building type-safe Vue components. While the Vue team is working on improving native support for discriminated unions [in vuejs/core#8952](https://github.com/vuejs/core/issues/8952), this pattern offers a practical solution today:

Unfortunately, what currently is not working is using helper utility types like Xor so that we don't have to
manually mark unused variant props as never. When you do that, you will get an error from vue-tsc.

Example of a helper type like Xor:

```typescript
type Without<T, U> = { [P in Exclude<keyof T, keyof U>]?: never };
type XOR<T, U> = T | U extends object
  ? (Without<T, U> & U) | (Without<U, T> & T)
  : T | U;

// Success notification properties
type SuccessProps = {
  title: string;
  variant: "primary" | "secondary";
  message: string;
  duration: number;
};

// Error notification properties
type ErrorProps = {
  title: string;
  variant: "danger" | "warning";
  errorCode: string;
  retryable: boolean;
};

// Final props type - only one variant allowed! ✨
type Props = XOR<SuccessProps, ErrorProps>;
```

## Video Reference

If you also prefer to learn this in video format, check out this tutorial:

<YouTube
  id="vyD5pYOa5mY"
  title="Understanding TypeScript Discriminated Unions in Vue"
/>

---

--- title: SQLite in Vue: Complete Guide to Building Offline-First Web Apps description: Learn how to build offline-capable Vue 3 apps using SQLite and WebAssembly in 2024. Step-by-step tutorial includes code examples for database operations, query playground implementation, and best practices for offline-first applications. tags: ['vue', 'local-first'] url: https://alexop.dev/posts/sqlite-vue3-offline-first-web-apps-guide ---

# SQLite in Vue: Complete Guide to Building Offline-First Web Apps



## TLDR

- Set up SQLite WASM in a Vue 3 application for offline data storage
- Learn how to use Origin Private File System (OPFS) for persistent storage
- Build a SQLite query playground with Vue composables
- Implement production-ready offline-first architecture
- Compare SQLite vs IndexedDB for web applications

Looking to add offline capabilities to your Vue application? While browsers offer IndexedDB, SQLite provides a more powerful solution for complex data operations. This comprehensive guide shows you how to integrate SQLite with Vue using WebAssembly for robust offline-first applications.

## 📚 What We'll Build

- A Vue 3 app with SQLite that works offline
- A simple query playground to test SQLite
- Everything runs in the browser - no server needed!

![Screenshot Sqlite Playground](../../assets/images/sqlite-vue/sqlite-playground.png)
_Try it out: Write and run SQL queries right in your browser_

> 🚀 **Want the code?** Get the complete example at [github.com/alexanderop/sqlite-vue-example](https://github.com/alexanderop/sqlite-vue-example)

## 🗃️ Why SQLite?

Browser storage like IndexedDB is okay, but SQLite is better because:

- It's a real SQL database in your browser
- Your data stays safe even when offline
- You can use normal SQL queries
- It handles complex data relationships well

## 🛠️ How It Works

We'll use three main technologies:

1. **SQLite Wasm**: SQLite converted to run in browsers
2. **Web Workers**: Runs database code without freezing your app
3. **Origin Private File System**: A secure place to store your database

Here's how they work together:

<ExcalidrawSVG
  src={myDiagram}
  alt="How SQLite works in the browser"
  caption="How SQLite runs in your browser"
/>

## 📝 Implementation Guide

Let's build this step by step, starting with the core SQLite functionality and then creating a playground to test it.

### Step 1: Install Dependencies

First, install the required SQLite WASM package:

```bash
npm install @sqlite.org/sqlite-wasm
```

### Step 2: Configure Vite

Create or update your `vite.config.ts` file to support WebAssembly and cross-origin isolation:

```ts
export default defineConfig(() => ({
  server: {
    headers: {
      "Cross-Origin-Opener-Policy": "same-origin",
      "Cross-Origin-Embedder-Policy": "require-corp",
    },
  },
  optimizeDeps: {
    exclude: ["@sqlite.org/sqlite-wasm"],
  },
}));
```

This configuration is crucial for SQLite WASM to work properly:

- **Cross-Origin Headers**:
  - `Cross-Origin-Opener-Policy` and `Cross-Origin-Embedder-Policy` headers enable "cross-origin isolation"
  - This is required for using SharedArrayBuffer, which SQLite WASM needs for optimal performance
  - Without these headers, the WebAssembly implementation might fail or perform poorly

- **Dependency Optimization**:
  - `optimizeDeps.exclude` tells Vite not to pre-bundle the SQLite WASM package
  - This is necessary because the WASM files need to be loaded dynamically at runtime
  - Pre-bundling would break the WASM initialization process

### Step 3: Add TypeScript Types

Since `@sqlite.org/sqlite-wasm` doesn't include TypeScript types for Sqlite3Worker1PromiserConfig, we need to create our own. Create a new file `types/sqlite-wasm.d.ts`:

Define this as a d.ts file so that TypeScript knows about it.

```ts
declare module "@sqlite.org/sqlite-wasm" {
  type OnreadyFunction = () => void;

  type Sqlite3Worker1PromiserConfig = {
    onready?: OnreadyFunction;
    worker?: Worker | (() => Worker);
    generateMessageId?: (messageObject: unknown) => string;
    debug?: (...args: any[]) => void;
    onunhandled?: (event: MessageEvent) => void;
  };

  type DbId = string | undefined;

  type PromiserMethods = {
    "config-get": {
      args: Record<string, never>;
      result: {
        dbID: DbId;
        version: {
          libVersion: string;
          sourceId: string;
          libVersionNumber: number;
          downloadVersion: number;
        };
        bigIntEnabled: boolean;
        opfsEnabled: boolean;
        vfsList: string[];
      };
    };
    open: {
      args: Partial<{
        filename?: string;
        vfs?: string;
      }>;
      result: {
        dbId: DbId;
        filename: string;
        persistent: boolean;
        vfs: string;
      };
    };
    exec: {
      args: {
        sql: string;
        dbId?: DbId;
        bind?: unknown[];
        returnValue?: string;
      };
      result: {
        dbId: DbId;
        sql: string;
        bind: unknown[];
        returnValue: string;
        resultRows?: unknown[][];
      };
    };
  };

  type PromiserResponseSuccess<T extends keyof PromiserMethods> = {
    type: T;
    result: PromiserMethods[T]["result"];
    messageId: string;
    dbId: DbId;
    workerReceivedTime: number;
    workerRespondTime: number;
    departureTime: number;
  };

  type PromiserResponseError = {
    type: "error";
    result: {
      operation: string;
      message: string;
      errorClass: string;
      input: object;
      stack: unknown[];
    };
    messageId: string;
    dbId: DbId;
  };

  type PromiserResponse<T extends keyof PromiserMethods> =
    | PromiserResponseSuccess<T>
    | PromiserResponseError;

  type Promiser = <T extends keyof PromiserMethods>(
    messageType: T,
    messageArguments: PromiserMethods[T]["args"]
  ) => Promise<PromiserResponse<T>>;

  export function sqlite3Worker1Promiser(
    config?: Sqlite3Worker1PromiserConfig | OnreadyFunction
  ): Promiser;
}
```

### Step 4: Create the SQLite Composable

The core of our implementation is the `useSQLite` composable. This will handle all database operations:

```ts
const databaseConfig = {
  filename: "file:mydb.sqlite3?vfs=opfs",
  tables: {
    test: {
      name: "test_table",
      schema: `
        CREATE TABLE IF NOT EXISTS test_table (
          id INTEGER PRIMARY KEY AUTOINCREMENT,
          name TEXT NOT NULL,
          created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
        );
      `,
    },
  },
} as const;

export function useSQLite() {
  const isLoading = ref(false);
  const error = ref<Error | null>(null);
  const isInitialized = ref(false);

  let promiser: ReturnType<typeof sqlite3Worker1Promiser> | null = null;
  let dbId: string | null = null;

  async function initialize() {
    if (isInitialized.value) return true;

    isLoading.value = true;
    error.value = null;

    try {
      // Initialize the SQLite worker
      promiser = await new Promise(resolve => {
        const _promiser = sqlite3Worker1Promiser({
          onready: () => resolve(_promiser),
        });
      });

      if (!promiser) throw new Error("Failed to initialize promiser");

      // Get configuration and open database
      await promiser("config-get", {});
      const openResponse = await promiser("open", {
        filename: databaseConfig.filename,
      });

      if (openResponse.type === "error") {
        throw new Error(openResponse.result.message);
      }

      dbId = openResponse.result.dbId as string;

      // Create initial tables
      await promiser("exec", {
        dbId,
        sql: databaseConfig.tables.test.schema,
      });

      isInitialized.value = true;
      return true;
    } catch (err) {
      error.value = err instanceof Error ? err : new Error("Unknown error");
      throw error.value;
    } finally {
      isLoading.value = false;
    }
  }

  async function executeQuery(sql: string, params: unknown[] = []) {
    if (!dbId || !promiser) {
      await initialize();
    }

    isLoading.value = true;
    error.value = null;

    try {
      const result = await promiser!("exec", {
        dbId: dbId as DbId,
        sql,
        bind: params,
        returnValue: "resultRows",
      });

      if (result.type === "error") {
        throw new Error(result.result.message);
      }

      return result;
    } catch (err) {
      error.value =
        err instanceof Error ? err : new Error("Query execution failed");
      throw error.value;
    } finally {
      isLoading.value = false;
    }
  }

  return {
    isLoading,
    error,
    isInitialized,
    executeQuery,
  };
}
```

### Step 5: Create a SQLite Playground Component

Now let's create a component to test our SQLite implementation:

```vue
<script setup lang="ts">
const { isLoading, error, executeQuery } = useSQLite();
const sqlQuery = ref("SELECT * FROM test_table");
const queryResult = ref<any[]>([]);
const queryError = ref<string | null>(null);

// Predefined example queries for testing
const exampleQueries = [
  { title: "Select all", query: "SELECT * FROM test_table" },
  {
    title: "Insert",
    query: "INSERT INTO test_table (name) VALUES ('New Test Item')",
  },
  {
    title: "Update",
    query: "UPDATE test_table SET name = 'Updated Item' WHERE name LIKE 'New%'",
  },
  {
    title: "Delete",
    query: "DELETE FROM test_table WHERE name = 'Updated Item'",
  },
];

async function runQuery() {
  queryError.value = null;
  queryResult.value = [];

  try {
    const result = await executeQuery(sqlQuery.value);
    const isSelect = sqlQuery.value.trim().toLowerCase().startsWith("select");

    if (isSelect) {
      queryResult.value = result?.result.resultRows || [];
    } else {
      // After mutation, fetch updated data
      queryResult.value =
        (await executeQuery("SELECT * FROM test_table"))?.result.resultRows ||
        [];
    }
  } catch (err) {
    queryError.value = err instanceof Error ? err.message : "An error occurred";
  }
}
</script>

<template>
  <div class="mx-auto max-w-7xl px-4 py-6">
    <h2 class="text-2xl font-bold">SQLite Playground</h2>

    <!-- Example queries -->
    <div class="mt-4">
      <h3 class="text-sm font-medium">Example Queries:</h3>
      <div class="mt-2 flex gap-2">
        <button
          v-for="example in exampleQueries"
          :key="example.title"
          class="rounded-full bg-gray-100 px-3 py-1 text-sm hover:bg-gray-200"
          @click="sqlQuery = example.query"
        >
          {{ example.title }}
        </button>
      </div>
    </div>

    <!-- Query input -->
    <div class="mt-6">
      <textarea
        v-model="sqlQuery"
        rows="4"
        class="w-full rounded-lg px-4 py-3 font-mono text-sm"
        :disabled="isLoading"
      />
      <button
        :disabled="isLoading"
        class="mt-2 rounded-lg bg-blue-600 px-4 py-2 text-white"
        @click="runQuery"
      >
        {{ isLoading ? "Running..." : "Run Query" }}
      </button>
    </div>

    <!-- Error display -->
    <div
      v-if="error || queryError"
      class="mt-4 rounded-lg bg-red-50 p-4 text-red-600"
    >
      {{ error?.message || queryError }}
    </div>

    <!-- Results table -->
    <div v-if="queryResult.length" class="mt-4">
      <h3 class="text-lg font-semibold">Results:</h3>
      <div class="mt-2 overflow-x-auto">
        <table class="w-full">
          <thead>
            <tr>
              <th
                v-for="column in Object.keys(queryResult[0])"
                :key="column"
                class="px-4 py-2 text-left"
              >
                {{ column }}
              </th>
            </tr>
          </thead>
          <tbody>
            <tr v-for="(row, index) in queryResult" :key="index">
              <td
                v-for="column in Object.keys(row)"
                :key="column"
                class="px-4 py-2"
              >
                {{ row[column] }}
              </td>
            </tr>
          </tbody>
        </table>
      </div>
    </div>
  </div>
</template>
```

## 🎯 Real-World Example: Notion's SQLite Implementation

[Notion recently shared](https://www.notion.com/blog/how-we-sped-up-notion-in-the-browser-with-wasm-sqlite) how they implemented SQLite in their web application, providing some valuable insights:

### Performance Improvements

- 20% faster page navigation across all modern browsers
- Even greater improvements for users with slower connections:

### Multi-Tab Architecture

Notion solved the challenge of handling multiple browser tabs with an innovative approach:

1. Each tab has its own Web Worker for SQLite operations
2. A SharedWorker manages which tab is "active"
3. Only one tab can write to SQLite at a time
4. Queries from all tabs are routed through the active tab's Worker

### Key Learnings from Notion

1. **Async Loading**: They load the WASM SQLite library asynchronously to avoid blocking initial page load
2. **Race Conditions**: They implemented a "racing" system between SQLite and API requests to handle slower devices
3. **OPFS Handling**: They discovered that Origin Private File System (OPFS) doesn't handle concurrency well out of the box
4. **Cross-Origin Isolation**: They opted for OPFS SyncAccessHandle Pool VFS to avoid cross-origin isolation requirements

This real-world implementation demonstrates both the potential and challenges of using SQLite in production web applications. Notion's success shows that with careful architecture choices, SQLite can significantly improve web application performance.

## 🎯 Conclusion

You now have a solid foundation for building offline-capable Vue applications using SQLite. This approach offers significant advantages over traditional browser storage solutions, especially for complex data requirements.

---

--- title: Create Dark Mode-Compatible Technical Diagrams in Astro with Excalidraw: A Complete Guide description: Learn how to create and integrate theme-aware Excalidraw diagrams into your Astro blog. This step-by-step guide shows you how to build custom components that automatically adapt to light and dark modes, perfect for technical documentation and blogs tags: ['astro', 'excalidraw'] url: https://alexop.dev/posts/excalidraw-dark-mode-astro-diagrams ---

# Create Dark Mode-Compatible Technical Diagrams in Astro with Excalidraw: A Complete Guide



## Why You Need Theme-Aware Technical Diagrams in Your Astro Blog

Technical bloggers often face a common challenge: creating diagrams seamlessly integrating with their site’s design system. While tools like Excalidraw make it easy to create beautiful diagrams, maintaining their visual consistency across different theme modes can be frustrating. This is especially true when your Astro blog supports light and dark modes.
This tutorial will solve this problem by building a custom solution that automatically adapts your Excalidraw diagrams to match your site’s theme.

## Common Challenges with Technical Diagrams in Web Development

When working with Excalidraw, we face several issues:

- Exported SVGs come with fixed colors
- Diagrams don't automatically adapt to dark mode
- Maintaining separate versions for different themes is time-consuming
- Lack of interactive elements and smooth transitions

## Before vs After: The Impact of Theme-Aware Diagrams

<div class="grid grid-cols-2 gap-8 w-full">
  <div class="w-full">
    <h4 class="text-xl font-bold">Standard Export</h4>
    <p>Here's how a typical Excalidraw diagram looks without any customization:</p>
    <Image
      src={exampleImage}
      alt="How a excalidraw diagrams looks without our custom component"
      width={400}
      height={300}
      class="w-full h-auto object-cover"
    />
  </div>

  <div class="w-full">
    <h4 class="text-xl font-bold">With Our Solution</h4>
    <p>And here's the same diagram using our custom component:</p>
    
  </div>
</div>

## Building a Theme-Aware Excalidraw Component for Astro

We'll create an Astro component that transforms static Excalidraw exports into dynamic, theme-aware diagrams. Our solution will:

1. Automatically adapt to light and dark modes
2. Support your custom design system colors
3. Add interactive elements and smooth transitions
4. Maintain accessibility standards

💡 Quick Start: Need an Astro blog first? Use [AstroPaper](https://github.com/satnaing/astro-paper) as your starter or build from scratch. This tutorial focuses on the diagram component itself.

## Step-by-Step Implementation Guide

### 1. Implementing the Theme System

First, let's define the color variables that will power our theme-aware diagrams:

```css
html[data-theme="light"] {
  --color-fill: 250, 252, 252;
  --color-text-base: 34, 46, 54;
  --color-accent: 211, 0, 106;
  --color-card: 234, 206, 219;
  --color-card-muted: 241, 186, 212;
  --color-border: 227, 169, 198;
}

html[data-theme="dark"] {
  --color-fill: 33, 39, 55;
  --color-text-base: 234, 237, 243;
  --color-accent: 255, 107, 237;
  --color-card: 52, 63, 96;
  --color-card-muted: 138, 51, 123;
  --color-border: 171, 75, 153;
}
```

### 2. Creating Optimized Excalidraw Diagrams

Follow these steps to prepare your diagrams:

1. Create your diagram at [Excalidraw](https://excalidraw.com/)
2. Export the diagram:
   - Select your diagram
   - Click the export button
     ![How to export Excalidraw diagram as SVG](../../assets/images/excalidraw-astro/how-to-click-export-excalidraw.png)
3. Configure export settings:
   - Uncheck "Background"
   - Choose SVG format
   - Click "Save"
     ![How to hide background and save as SVG](../../assets/images/excalidraw-astro/save-as-svg.png)

### 3. Building the ExcalidrawSVG Component

Here's our custom Astro component that handles the theme-aware transformation:

```astro
---
interface Props {
  src: ImageMetadata | string;
  alt: string;
  caption?: string;
}

const { src, alt, caption } = Astro.props;

const svgUrl = typeof src === "string" ? src : src.src;
---

<figure class="excalidraw-figure">
  <div class="excalidraw-svg" data-svg-url={svgUrl} aria-label={alt}>
    
  </div>
  {caption && <figcaption>{caption}</figcaption>}
</figure>

<script>
  function modifySvg(svgString: string): string {
    const parser = new DOMParser();
    const doc = parser.parseFromString(svgString, "image/svg+xml");
    const svg = doc.documentElement;

    svg.setAttribute("width", "100%");
    svg.setAttribute("height", "100%");
    svg.classList.add("w-full", "h-auto");

    doc.querySelectorAll("text").forEach(text => {
      text.removeAttribute("fill");
      text.classList.add("fill-skin-base");
    });

    doc.querySelectorAll("rect").forEach(rect => {
      rect.removeAttribute("fill");
      rect.classList.add("fill-skin-soft");
    });

    doc.querySelectorAll("path").forEach(path => {
      path.removeAttribute("stroke");
      path.classList.add("stroke-skin-accent");
    });

    doc.querySelectorAll("g").forEach(g => {
      g.classList.add("excalidraw-element");
    });

    return new XMLSerializer().serializeToString(doc);
  }

  function initExcalidrawSVG() {
    const svgContainers =
      document.querySelectorAll<HTMLElement>(".excalidraw-svg");
    svgContainers.forEach(async container => {
      const svgUrl = container.dataset.svgUrl;
      if (svgUrl) {
        try {
          const response = await fetch(svgUrl);
          if (!response.ok) {
            throw new Error(`Failed to fetch SVG: ${response.statusText}`);
          }
          const svgData = await response.text();
          const modifiedSvg = modifySvg(svgData);
          container.innerHTML = modifiedSvg;
        } catch (error) {
          console.error("Error in ExcalidrawSVG component:", error);
          container.innerHTML = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
            <text x="10" y="50" fill="red">Error loading SVG</text>
          </svg>`;
        }
      }
    });
  }

  // Run on initial page load
  document.addEventListener("DOMContentLoaded", initExcalidrawSVG);

  // Run on subsequent navigation
  document.addEventListener("astro:page-load", initExcalidrawSVG);
</script>

<style>
  .excalidraw-figure {
    @apply my-8 w-full max-w-full overflow-hidden;
  }
  .excalidraw-svg {
    @apply w-full max-w-full overflow-hidden;
  }
  :global(.excalidraw-svg svg) {
    @apply h-auto w-full;
  }
  :global(.excalidraw-svg .fill-skin-base) {
    @apply fill-[rgb(34,46,54)] dark:fill-[rgb(234,237,243)];
  }
  :global(.excalidraw-svg .fill-skin-soft) {
    @apply fill-[rgb(234,206,219)] dark:fill-[rgb(52,63,96)];
  }
  :global(.excalidraw-svg .stroke-skin-accent) {
    @apply stroke-[rgb(211,0,106)] dark:stroke-[rgb(255,107,237)];
  }
  :global(.excalidraw-svg .excalidraw-element) {
    @apply transition-all duration-300;
  }
  :global(.excalidraw-svg .excalidraw-element:hover) {
    @apply opacity-80;
  }
  figcaption {
    @apply mt-4 text-center text-sm italic text-skin-base;
  }
</style>
```

### 4. Using the Component

Integrate the component into your MDX blog posts:

💡 **Note:** We need to use MDX so that we can use the `ExcalidrawSVG` component in our blog posts. You can read more about MDX [here](https://mdxjs.com/).

```mdx
---
---

# My Technical Blog Post

<ExcalidrawSVG
  src={myDiagram}
  alt="Architecture diagram"
  caption="System architecture overview"
/>
```

### Best Practices and Tips for Theme-Aware Technical Diagrams

1. **Simplicity and Focus**
   - Keep diagrams simple and focused for better readability
   - Avoid cluttering with unnecessary details

2. **Consistent Styling**
   - Use consistent styling across all diagrams
   - Maintain a uniform look and feel throughout your documentation

3. **Thorough Testing**
   - Test thoroughly in both light and dark modes
   - Ensure diagrams are clear and legible in all color schemes

4. **Accessibility Considerations**
   - Consider accessibility when choosing colors and contrast
   - Ensure diagrams are understandable for users with color vision deficiencies

5. **Smooth Transitions**
   - Implement smooth transitions for theme changes
   - Provide a seamless experience when switching between light and dark modes

## Conclusion

With this custom component, you can now create technical diagrams that seamlessly integrate with your Astro blog's design system.
This solution eliminates the need for maintaining multiple versions of diagrams while providing a superior user experience through smooth transitions and interactive elements.

---

--- title: Frontend Testing Guide: 10 Essential Rules for Naming Tests description: Learn how to write clear and maintainable frontend tests with 10 practical naming rules. Includes real-world examples showing good and bad practices for component testing across any framework. tags: ['testing', 'vitest'] url: https://alexop.dev/posts/frontend-testing-guide-10-essential-rules ---

# Frontend Testing Guide: 10 Essential Rules for Naming Tests



## Introduction

The path to better testing starts with something surprisingly simple: how you name your tests. Good test names:

- Make your test suite more maintainable
- Guide you toward writing tests that focus on user behavior
- Improve clarity and readability for your team

In this blog post, we'll explore 10 essential rules for writing better tests that will transform your approach to testing. These principles are:

1. Framework-agnostic
2. Applicable across the entire testing pyramid
3. Useful for various testing tools:
   - Unit tests (Jest, Vitest)
   - Integration tests
   - End-to-end tests (Cypress, Playwright)

By following these rules, you'll create a more robust and understandable test suite, regardless of your chosen testing framework or methodology.

## Rule 1: Always Use "should" + Verb

Every test name should start with "should" followed by an action verb.

```js
// ❌ Bad
it("displays the error message", () => {});
it("modal visibility", () => {});
it("form validation working", () => {});

// ✅ Good
it("should display error message when validation fails", () => {});
it("should show modal when trigger button is clicked", () => {});
it("should validate form when user submits", () => {});
```

**Generic Pattern:** `should [verb] [expected outcome]`

## Rule 2: Include the Trigger Event

Specify what causes the behavior you're testing.

```js
// ❌ Bad
it("should update counter", () => {});
it("should validate email", () => {});
it("should show dropdown", () => {});

// ✅ Good
it("should increment counter when plus button is clicked", () => {});
it("should show error when email format is invalid", () => {});
it("should open dropdown when toggle is clicked", () => {});
```

**Generic Pattern:** `should [verb] [expected outcome] when [trigger event]`

## Rule 3: Group Related Tests with Descriptive Contexts

Use describe blocks to create clear test hierarchies.

```js
// ❌ Bad
describe("AuthForm", () => {
  it("should test empty state", () => {});
  it("should test invalid state", () => {});
  it("should test success state", () => {});
});

// ✅ Good
describe("AuthForm", () => {
  describe("when form is empty", () => {
    it("should disable submit button", () => {});
    it("should not show any validation errors", () => {});
  });

  describe("when submitting invalid data", () => {
    it("should show validation errors", () => {});
    it("should keep submit button disabled", () => {});
  });
});
```

**Generic Pattern:**

```js
describe("[Component/Feature]", () => {
  describe("when [specific condition]", () => {
    it("should [expected behavior]", () => {});
  });
});
```

## Rule 4: Name State Changes Explicitly

Clearly describe the before and after states in your test names.

```js
// ❌ Bad
it("should change status", () => {});
it("should update todo", () => {});
it("should modify permissions", () => {});

// ✅ Good
it("should change status from pending to approved", () => {});
it("should mark todo as completed when checkbox clicked", () => {});
it("should upgrade user from basic to premium", () => {});
```

**Generic Pattern:** `should change [attribute] from [initial state] to [final state]`

## Rule 5: Describe Async Behavior Clearly

Include loading and result states for asynchronous operations.

```js
// ❌ Bad
it("should load data", () => {});
it("should handle API call", () => {});
it("should fetch user", () => {});

// ✅ Good
it("should show skeleton while loading data", () => {});
it("should display error message when API call fails", () => {});
it("should render profile after user data loads", () => {});
```

**Generic Pattern:** `should [verb] [expected outcome] [during/after] [async operation]`

## Rule 6: Name Error Cases Specifically

Be explicit about the type of error and what causes it.

```js
// ❌ Bad
it("should show error", () => {});
it("should handle invalid input", () => {});
it("should validate form", () => {});

// ✅ Good
it('should show "Invalid Card" when card number is wrong', () => {});
it('should display "Required" when password is empty', () => {});
it("should show network error when API is unreachable", () => {});
```

**Generic Pattern:** `should show [specific error message] when [error condition]`

## Rule 7: Use Business Language, Not Technical Terms

Write tests using domain language rather than implementation details.

```js
// ❌ Bad
it("should update state", () => {});
it("should dispatch action", () => {});
it("should modify DOM", () => {});

// ✅ Good
it("should save customer order", () => {});
it("should update cart total", () => {});
it("should mark order as delivered", () => {});
```

**Generic Pattern:** `should [business action] [business entity]`

## Rule 8: Include Important Preconditions

Specify conditions that affect the behavior being tested.

```js
// ❌ Bad
it("should enable button", () => {});
it("should show message", () => {});
it("should apply discount", () => {});

// ✅ Good
it("should enable checkout when cart has items", () => {});
it("should show free shipping when total exceeds $100", () => {});
it("should apply discount when user is premium member", () => {});
```

**Generic Pattern:** `should [expected behavior] when [precondition]`

## Rule 9: Name UI Feedback Tests from User Perspective

Describe visual changes as users would perceive them.

```js
// ❌ Bad
it("should set error class", () => {});
it("should toggle visibility", () => {});
it("should update styles", () => {});

// ✅ Good
it("should highlight search box in red when empty", () => {});
it("should show green checkmark when password is strong", () => {});
it("should disable submit button while processing", () => {});
```

**Generic Pattern:** `should [visual change] when [user action/condition]`

## Rule 10: Structure Complex Workflows Step by Step

Break down complex processes into clear steps.

```js
// ❌ Bad
describe("Checkout", () => {
  it("should process checkout", () => {});
  it("should handle shipping", () => {});
  it("should complete order", () => {});
});

// ✅ Good
describe("Checkout Process", () => {
  it("should first validate items are in stock", () => {});
  it("should then collect shipping address", () => {});
  it("should finally process payment", () => {});

  describe("after successful payment", () => {
    it("should display order confirmation", () => {});
    it("should send confirmation email", () => {});
  });
});
```

**Generic Pattern:**

```js
describe("[Complex Process]", () => {
  it("should first [initial step]", () => {});
  it("should then [next step]", () => {});
  it("should finally [final step]", () => {});

  describe("after [key milestone]", () => {
    it("should [follow-up action]", () => {});
  });
});
```

## Complete Example

Here's a comprehensive example showing how to combine all these rules:

```js
// ❌ Bad
describe("ShoppingCart", () => {
  it("test adding item", () => {});
  it("check total", () => {});
  it("handle checkout", () => {});
});

// ✅ Good
describe("ShoppingCart", () => {
  describe("when adding items", () => {
    it("should add item to cart when add button is clicked", () => {});
    it("should update total price immediately", () => {});
    it("should show item count badge", () => {});
  });

  describe("when cart is empty", () => {
    it("should display empty cart message", () => {});
    it("should disable checkout button", () => {});
  });

  describe("during checkout process", () => {
    it("should validate stock before proceeding", () => {});
    it("should show loading indicator while processing payment", () => {});
    it("should display success message after completion", () => {});
  });
});
```

## Test Name Checklist

Before committing your test, verify that its name:

- [ ] Starts with "should"
- [ ] Uses a clear action verb
- [ ] Specifies the trigger condition
- [ ] Uses business language
- [ ] Describes visible behavior
- [ ] Is specific enough for debugging
- [ ] Groups logically with related tests

## Conclusion

Thoughtful test naming is a fundamental building block in the broader landscape of writing better tests. To maintain consistency across your team:

1. Document your naming conventions in detail
2. Share these guidelines with all team members
3. Integrate the guidelines into your development workflow

For teams using AI tools like GitHub Copilot:

- Incorporate these guidelines into your project documentation
- Link the markdown file containing these rules to Copilot
- This integration allows Copilot to suggest test names aligned with your conventions

For more information on linking documentation to Copilot, see:
[VS Code Experiments Boost AI Copilot Functionality](https://visualstudiomagazine.com/Articles/2024/09/09/VS-Code-Experiments-Boost-AI-Copilot-Functionality.aspx)

By following these steps, you can ensure consistent, high-quality test naming across your entire project.

---

--- title: Create a Native-Like App in 4 Steps: PWA Magic with Vue 3 and Vite description: Transform your Vue 3 project into a powerful Progressive Web App in just 4 steps. Learn how to create offline-capable, installable web apps using Vite and modern PWA techniques. tags: ['vue', 'pwa', 'vite'] url: https://alexop.dev/posts/create-pwa-vue3-vite-4-steps ---

# Create a Native-Like App in 4 Steps: PWA Magic with Vue 3 and Vite



## Table of Contents

## Introduction

Progressive Web Apps (PWAs) have revolutionized our thoughts on web applications. PWAs offer a fast, reliable, and engaging user experience by combining the best web and mobile apps. They work offline, can be installed on devices, and provide a native app-like experience without app store distribution.

This guide will walk you through creating a Progressive Web App using Vue 3 and Vite. By the end of this tutorial, you’ll have a fully functional PWA that can work offline, be installed on users’ devices, and leverage modern web capabilities.

## Understanding the Basics of Progressive Web Apps (PWAs)

Before diving into the development process, it's crucial to grasp the fundamental concepts of PWAs:

- **Multi-platform Compatibility**: PWAs are designed for applications that can function across multiple platforms, not just the web.
- **Build Once, Deploy Everywhere**: With PWAs, you can develop an application once and deploy it on Android, iOS, Desktop, and Web platforms.
- **Enhanced User Experience**: PWAs offer features like offline functionality, push notifications, and home screen installation.

For a more in-depth understanding of PWAs, refer to the [MDN Web Docs on Progressive Web Apps](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps).

## Prerequisites for Building a PWA with Vue 3 and Vite

Before you start, make sure you have the following tools installed:

1. Node.js installed on your system
2. Package manager: pnpm, npm, or yarn
3. Basic familiarity with Vue 3

<ExcalidrawSVG
  src={fourSteps}
  alt="Four steps to create a PWA"
  caption="Four steps to create a PWA"
/>

## Step 1: Setting Up the Vue Project

First, we'll set up a new Vue project using the latest Vue CLI. This will give us a solid foundation to build our PWA upon.

1. Create a new Vue project by running the following command in your terminal:

   ```bash
   pnpm create vue@latest
   ```

2. Follow the prompts to configure your project. Here's an example configuration:

   ```shell
   ✔ Project name: … local-first-example
   ✔ Add TypeScript? … Yes
   ✔ Add JSX Support? … Yes
   ✔ Add Vue Router for Single Page Application development? … Yes
   ✔ Add Pinia for state management? … Yes
   ✔ Add Vitest for Unit Testing? … Yes
   ✔ Add an End-to-End Testing Solution? › No
   ✔ Add ESLint for code quality? … Yes
   ✔ Add Prettier for code formatting? … Yes
   ✔ Add Vue DevTools 7 extension for debugging? (experimental) … Yes
   ```

3. Once the project is created, navigate to your project directory and install dependencies:
   ```bash
   cd local-first-example
   pnpm install
   pnpm run dev
   ```

Great! You now have a basic Vue 3 project up and running. Let's move on to adding PWA functionality.

## Step 2: Create the needed assets for the PWA

We need to add specific assets and configurations to transform our Vue app into a PWA.
PWAs can be installed on various devices, so we must prepare icons and other assets for different platforms.

1. First, let's install the necessary packages:

   ```bash
   pnpm add -D vite-plugin-pwa @vite-pwa/assets-generator
   ```

2. Create a high-resolution icon (preferably an SVG or a PNG with at least 512x512 pixels) for your PWA and place it in your `public` directory. Name it something like `pwa-icon.svg` or `pwa-icon.png`.

3. Generate the PWA assets by running:
   ```bash
   npx pwa-asset-generator --preset minimal public/pwa-icon.svg
   ```

This command will automatically generate a set of icons and a web manifest file in your `public` directory. The `minimal` preset will create:

- favicon.ico (48x48 transparent icon for browser tabs)
- favicon.svg (SVG icon for modern browsers)
- apple-touch-icon-180x180.png (Icon for iOS devices when adding to home screen)
- maskable-icon-512x512.png (Adaptive icon that fills the entire shape on Android devices)
- pwa-64x64.png (Small icon for various UI elements)
- pwa-192x192.png (Medium-sized icon for app shortcuts and tiles)
- pwa-512x512.png (Large icon for high-resolution displays and splash screens)

Output will look like this:

```shell
> vue3-pwa-timer@0.0.0 generate-pwa-assets /Users/your user/git2/vue3-pwa-example
> pwa-assets-generator "--preset" "minimal-2023" "public/pwa-icon.svg"

Zero Config PWA Assets Generator v0.2.6
◐ Preparing to generate PWA assets...
◐ Resolving instructions...
✔ PWA assets ready to be generated, instructions resolved
◐ Generating PWA assets from public/pwa-icon.svg image
◐ Generating assets for public/pwa-icon.svg...
✔ Generated PNG file: /Users/your user/git2/vue3-pwa-example/public/pwa-64x64.png
✔ Generated PNG file: /Users/your user/git2/vue3-pwa-example/public/pwa-192x192.png
✔ Generated PNG file: /Users/your user/git2/vue3-pwa-example/public/pwa-512x512.png
✔ Generated PNG file: /Users/your user/git2/vue3-pwa-example/public/maskable-icon-512x512.png
✔ Generated PNG file: /Users/your user/git2/vue3-pwa-example/public/apple-touch-icon-180x180.png
✔ Generated ICO file: /Users/your user/git2/vue3-pwa-example/public/favicon.ico
✔ Assets generated for public/pwa-icon.svg
◐ Generating Html Head Links...
<link rel="icon" href="/favicon.ico" sizes="48x48">
<link rel="icon" href="/pwa-icon.svg" sizes="any" type="image/svg+xml">
<link rel="apple-touch-icon" href="/apple-touch-icon-180x180.png">
✔ Html Head Links generated
◐ Generating PWA web manifest icons entry...
{
  "icons": [
    {
      "src": "pwa-64x64.png",
      "sizes": "64x64",
      "type": "image/png"
    },
    {
      "src": "pwa-192x192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "pwa-512x512.png",
      "sizes": "512x512",
      "type": "image/png"
    },
    {
      "src": "maskable-icon-512x512.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "maskable"
    }
  ]
}
✔ PWA web manifest icons entry generated
✔ PWA assets generated
```

These steps will ensure your PWA has all the necessary icons and assets to function correctly across different devices and platforms.
The minimal-2023 preset provides a modern, optimized set of icons that meet the latest PWA requirements.

## Step 3: Configuring Vite for PWA Support

With our assets ready, we must configure Vite to enable PWA functionality. This involves setting up the manifest and other PWA-specific options.

First, update your main HTML file (usually `index.html`) to include important meta tags in the `<head>` section:

```html
<head>

</head>
```

Now, update your `vite.config.ts` file with the following configuration:

```typescript
export default defineConfig({
  plugins: [
    vue(),
    VitePWA({
      registerType: "autoUpdate",
      includeAssets: [
        "favicon.ico",
        "apple-touch-icon-180x180.png",
        "maskable-icon-512x512.png",
      ],
      manifest: {
        name: "My Awesome PWA",
        short_name: "MyPWA",
        description: "A PWA built with Vue 3",
        theme_color: "#ffffff",
        icons: [
          {
            src: "pwa-64x64.png",
            sizes: "64x64",
            type: "image/png",
          },
          {
            src: "pwa-192x192.png",
            sizes: "192x192",
            type: "image/png",
          },
          {
            src: "pwa-512x512.png",
            sizes: "512x512",
            type: "image/png",
            purpose: "any",
          },
          {
            src: "maskable-icon-512x512.png",
            sizes: "512x512",
            type: "image/png",
            purpose: "maskable",
          },
        ],
      },
      devOptions: {
        enabled: true,
      },
    }),
  ],
});
```

<Aside type="note">
  The `devOptions: { enabled: true }` setting is crucial for testing your PWA on localhost. Normally, PWAs require HTTPS, but this setting allows the PWA features to work on `http://localhost` during development. Remember to remove or set this to `false` for production builds.
</Aside>

This configuration generates a Web App Manifest, a JSON file that tells the browser about your Progressive Web App and how it should behave when installed on the user’s desktop or mobile device. The manifest includes the app’s name, icons, and theme colors.

## PWA Lifecycle and Updates

The `registerType: 'autoUpdate'` option in our configuration sets up automatic updates for our PWA. Here's how it works:

1. When a user visits your PWA, the browser downloads and caches the latest version of your app.
2. On subsequent visits, the service worker checks for updates in the background.
3. If an update is available, it's downloaded and prepared for the next launch.
4. The next time the user opens or refreshes the app, they'll get the latest version.

This ensures that users always have the most up-to-date version of your app without manual intervention.

## Step 4: Implementing Offline Functionality with Service Workers

The real power of PWAs comes from their ability to work offline. We'll use the `vite-plugin-pwa` to integrate Workbox, which will handle our service worker and caching strategies.

Before we dive into the configuration, let's understand the runtime caching strategies we'll be using:

1. **StaleWhileRevalidate** for static resources (styles, scripts, and workers):
   - This strategy serves cached content immediately while fetching an update in the background.
   - It's ideal for frequently updated resources that aren't 100% up-to-date.
   - We'll limit the cache to 50 entries and set an expiration of 30 days.

2. **CacheFirst** for images:
   - This strategy serves cached images immediately without network requests if they're available.
   - It's perfect for static assets that don't change often.
   - We'll limit the image cache to 100 entries and set an expiration of 60 days.

These strategies ensure that your PWA remains functional offline while efficiently managing cache storage.

Now, let's update your `vite.config.ts` file to include service worker configuration with these advanced caching strategies:

```typescript
export default defineConfig({
  plugins: [
    vue(),
    VitePWA({
      devOptions: {
        enabled: true,
      },
      registerType: "autoUpdate",
      includeAssets: ["favicon.ico", "apple-touch-icon.png", "masked-icon.svg"],
      manifest: {
        name: "Vue 3 PWA Timer",
        short_name: "PWA Timer",
        description: "A customizable timer for Tabata and EMOM workouts",
        theme_color: "#ffffff",
        icons: [
          {
            src: "pwa-192x192.png",
            sizes: "192x192",
            type: "image/png",
          },
          {
            src: "pwa-512x512.png",
            sizes: "512x512",
            type: "image/png",
          },
        ],
      },
      workbox: {
        runtimeCaching: [
          {
            urlPattern: ({ request }) =>
              request.destination === "style" ||
              request.destination === "script" ||
              request.destination === "worker",
            handler: "StaleWhileRevalidate",
            options: {
              cacheName: "static-resources",
              expiration: {
                maxEntries: 50,
                maxAgeSeconds: 30 * 24 * 60 * 60, // 30 days
              },
            },
          },
          {
            urlPattern: ({ request }) => request.destination === "image",
            handler: "CacheFirst",
            options: {
              cacheName: "images",
              expiration: {
                maxEntries: 100,
                maxAgeSeconds: 60 * 24 * 60 * 60, // 60 days
              },
            },
          },
        ],
      },
    }),
  ],
});
```

<ExcalidrawSVG
  src={myDiagram}
  alt="Diagram explaining how PWAs use service workers to enable offline functionality"
  caption="How PWAs leverage service workers for offline functionality"
/>

## Testing Your PWA

Now that we've set up our PWA, it's time to test its capabilities:

1. Test your PWA locally:

   ```bash
   pnpm run dev
   ```

2. Open Chrome DevTools and navigate to the Application tab.
   - Check the "Manifest" section to ensure your Web App Manifest is loaded correctly.
   - In the "Service Workers" section, verify that your service worker is registered and active.
     [![PWA Service Worker](../../assets/images/pwa/serviceWorker.png)

3. Test offline functionality:
   - Go to the Network tab in DevTools and check the "Offline" box to simulate offline conditions.
   - Refresh the page and verify that your app still works without an internet connection.
   - Uncheck the “Offline” box and refresh to ensure the app works online.

4. Test caching:
   - In the Application tab, go to "Cache Storage" to see the caches created by your service worker.
   - Verify that assets are being cached according to your caching strategies.

5. Test installation:
   - On desktop: Look for the install icon in the address bar or the three-dot menu.
     [![PWA Install Icon](../../assets/images/pwa/desktopInstall.png)](../../assets/images/pwa/desktopInstall.png)
     [![PWA Install Icon](../../assets/images/pwa/installApp.png)](../../assets/images/pwa/installApp.png)

   - On mobile: You should see a prompt to "Add to Home Screen".

6. Test updates:
   - Make a small change to your app and redeploy.
   - Revisit the app and check if the service worker updates (you can monitor this in the Application tab).

By thoroughly testing these aspects, you can ensure that your PWA functions correctly across various scenarios and platforms.

<Aside type="info">
  If you want to see a full-fledged PWA in action, check out
  [Elk](https://elk.zone/), a nimble Mastodon web client. It's built with Nuxt
  and is anexcellent example of a production-ready PWA. You can also explore its
  open-source code on [GitHub](https://github.com/elk-zone/elk) to see how
  they've implemented various PWA features.
</Aside>

## Conclusion

Congratulations! You've successfully created a Progressive Web App using Vue 3 and Vite.
Your app can now work offline, be installed on users' devices, and provide a native-like experience.

Refer to the [Vite PWA Workbox documentation](https://vite-pwa-org.netlify.app/workbox/) for more advanced Workbox configurations and features.

The more challenging part is building suitable components with a native-like feel on all the devices you want to support.
PWAs are also a main ingredient in building local-first applications.
If you are curious about what I mean by that, check out the following: [What is Local First Web Development](../what-is-local-first-web-development).

For a complete working example of this Vue 3 PWA, you can check out the complete source code at [full example](https://github.com/alexanderop/vue3-pwa-example).
This repository contains the finished project, allowing you to see how all the pieces come together in a real-world application.

---

--- title: Atomic Architecture: Structuring Vue and Nuxt Projects description: Learn how to implement Atomic Design principles in Vue or Nuxt projects. Improve your code structure and maintainability with this guide tags: ['vue', 'architecture'] url: https://alexop.dev/posts/atomic-design-vue-or-nuxt ---

# Atomic Architecture: Structuring Vue and Nuxt Projects



## Introduction

Clear writing requires clear thinking. The same is valid for coding.
Throwing all components into one folder may work when starting a personal project.
But as projects grow, especially with larger teams, this approach leads to problems:

- Duplicated code
- Oversized, multipurpose components
- Difficult-to-test code

Atomic Design offers a solution. Let's examine how to apply it to a Nuxt project.

## What is Atomic Design

![atomic design diagram brad Frost](../../assets/images/atomic/diagram.svg)

Brad Frost developed Atomic Design as a methodology for creating design systems. He structured it into five levels inspired by chemistry:

1. Atoms: Basic building blocks (e.g. form labels, inputs, buttons)
2. Molecules: Simple groups of UI elements (e.g. search forms)
3. Organisms: Complex components made of molecules/atoms (e.g. headers)
4. Templates: Page-level layouts
5. Pages: Specific instances of templates with content

<Aside type="tip" title="Tip">
  Read Brad Frost's original post for the full picture: [Atomic Web
  Design](https://bradfrost.com/blog/post/atomic-web-design/)
</Aside>

For Nuxt, we can adapt these definitions:

- Atoms: Pure, single-purpose components
- Molecules: Combinations of atoms with minimal logic
- Organisms: Larger, self-contained, reusable components
- Templates: Nuxt layouts defining page structure
- Pages: Components handling data and API calls

<Aside type="info" title="Organisms vs Molecules: What's the Difference?">

Molecules and organisms can be confusing. Think of it like LEGO:

- Molecules are small and simple. Individual bricks that snap together.
  Examples:
  - A search bar (input + button)
  - A login form (username input + password input + submit button)
  - A star rating (5 star icons + rating number)

- Organisms are bigger and more complex. Pre-built sets.
  Examples:
  - A full website header (logo + navigation menu + search bar)
  - A product card (image + title + price + add to cart button)
  - A comment section (comment form + list of comments)

Remember: Molecules are parts of organisms, but organisms can work independently.

</Aside>

### Code Example: Before and After

#### Consider this non-Atomic Design todo app component:

![Screenshot of ToDo App](../../assets/images/atomic/screenshot-example-app.png)

```vue
<template>
  <div class="container mx-auto p-4">
    <h1 class="mb-4 text-2xl font-bold text-gray-800 dark:text-gray-200">
      Todo App
    </h1>

    <!-- Add Todo Form -->
    <form @submit.prevent="addTodo" class="mb-4">
      <input
        v-model="newTodo"
        type="text"
        placeholder="Enter a new todo"
        class="mr-2 rounded border bg-white p-2 text-gray-800 dark:bg-gray-700 dark:text-gray-200"
      />
      <button
        type="submit"
        class="rounded bg-blue-500 p-2 text-white transition duration-300 hover:bg-blue-600"
      >
        Add Todo
      </button>
    </form>

    <!-- Todo List -->
    <ul class="space-y-2">
      <li
        v-for="todo in todos"
        :key="todo.id"
        class="flex items-center justify-between rounded bg-gray-100 p-3 shadow-sm dark:bg-gray-700"
      >
        <span class="text-gray-800 dark:text-gray-200">{{ todo.text }}</span>
        <button
          @click="deleteTodo(todo.id)"
          class="rounded bg-red-500 p-1 text-white transition duration-300 hover:bg-red-600"
        >
          Delete
        </button>
      </li>
    </ul>
  </div>
</template>

<script setup lang="ts">
interface Todo {
  id: number;
  text: string;
}

const newTodo = ref("");
const todos = ref<Todo[]>([]);

const fetchTodos = async () => {
  // Simulating API call
  todos.value = [
    { id: 1, text: "Learn Vue.js" },
    { id: 2, text: "Build a Todo App" },
    { id: 3, text: "Study Atomic Design" },
  ];
};

const addTodo = async () => {
  if (newTodo.value.trim()) {
    // Simulating API call
    const newTodoItem: Todo = {
      id: Date.now(),
      text: newTodo.value,
    };
    todos.value.push(newTodoItem);
    newTodo.value = "";
  }
};

const deleteTodo = async (id: number) => {
  // Simulating API call
  todos.value = todos.value.filter(todo => todo.id !== id);
};

onMounted(fetchTodos);
</script>
```

This approach leads to large, difficult-to-maintain components. Let's refactor using Atomic Design:

### This will be the refactored structure

```shell
📐 Template (Layout)
   │
   └─── 📄 Page (TodoApp)
        │
        └─── 📦 Organism (TodoList)
             │
             ├─── 🧪 Molecule (TodoForm)
             │    │
             │    ├─── ⚛️ Atom (BaseInput)
             │    └─── ⚛️ Atom (BaseButton)
             │
             └─── 🧪 Molecule (TodoItems)
                  │
                  └─── 🧪 Molecule (TodoItem) [multiple instances]
                       │
                       ├─── ⚛️ Atom (BaseText)
                       └─── ⚛️ Atom (BaseButton)
```

### Refactored Components

#### Template Default

```vue
<template>
  <div
    class="min-h-screen bg-gray-100 text-gray-900 transition-colors duration-300 dark:bg-gray-900 dark:text-gray-100"
  >
    <header class="bg-white shadow dark:bg-gray-800">
      <nav
        class="container mx-auto flex items-center justify-between px-4 py-4"
      >
        <NuxtLink to="/" class="text-xl font-bold">Todo App</NuxtLink>
        
      </nav>
    </header>
    <main class="container mx-auto px-4 py-8">
      
    </main>
  </div>
</template>

<script setup lang="ts">
</script>
```

#### Pages

```vue
<script setup lang="ts">
interface Todo {
  id: number;
  text: string;
}

const todos = ref<Todo[]>([]);

const fetchTodos = async () => {
  // Simulating API call
  todos.value = [
    { id: 1, text: "Learn Vue.js" },
    { id: 2, text: "Build a Todo App" },
    { id: 3, text: "Study Atomic Design" },
  ];
};

const addTodo = async (text: string) => {
  // Simulating API call
  const newTodoItem: Todo = {
    id: Date.now(),
    text,
  };
  todos.value.push(newTodoItem);
};

const deleteTodo = async (id: number) => {
  // Simulating API call
  todos.value = todos.value.filter(todo => todo.id !== id);
};

onMounted(fetchTodos);
</script>

<template>
  <div class="container mx-auto p-4">
    <h1 class="mb-4 text-2xl font-bold text-gray-800 dark:text-gray-200">
      Todo App
    </h1>
    
  </div>
</template>
```

#### Organism (TodoList)

```vue
<script setup lang="ts">
interface Todo {
  id: number;
  text: string;
}

defineProps<{
  todos: Todo[];
}>();

defineEmits<{
  (e: "add-todo", value: string): void;
  (e: "delete-todo", id: number): void;
}>();
</script>

<template>
  <div>
    
    <ul class="space-y-2">
      <TodoItem
        v-for="todo in todos"
        :key="todo.id"
        :todo="todo"
        @delete-todo="$emit('delete-todo', $event)"
      />
    </ul>
  </div>
</template>
```

#### Molecules (TodoForm and TodoItem)

##### TodoForm.vue:

```vue
<script setup lang="ts">
const newTodo = ref("");
const emit = defineEmits<{
  (e: "add-todo", value: string): void;
}>();

const addTodo = () => {
  if (newTodo.value.trim()) {
    emit("add-todo", newTodo.value);
    newTodo.value = "";
  }
};
</script>

<template>
  <form @submit.prevent="addTodo" class="mb-4">
    
    <BaseButton type="submit">Add Todo</BaseButton>
  </form>
</template>
```

##### TodoItem.vue:

```vue
<script setup lang="ts">
interface Todo {
  id: number;
  text: string;
}

const props = defineProps<{
  todo: Todo;
}>();

defineEmits<{
  (e: "delete-todo", id: number): void;
}>();
</script>

<template>
  <li class="flex items-center justify-between">
    <BaseText>{{ todo.text }}</BaseText>
    <BaseButton variant="danger" @click="$emit('delete-todo', todo.id)">
      Delete
    </BaseButton>
  </li>
</template>
```

#### Atoms (BaseButton, BaseInput, BaseText)

##### BaseButton.vue:

```vue
<script setup lang="ts">
defineProps<{
  variant?: "primary" | "danger";
}>();
</script>

<template>
  <button
    :class="[
      'rounded p-2 transition duration-300',
      variant === 'danger'
        ? 'bg-red-500 text-white hover:bg-red-600'
        : 'bg-blue-500 text-white hover:bg-blue-600',
    ]"
  >
    <slot></slot>
  </button>
</template>
```

#### BaseInput.vue:

```vue
<script setup lang="ts">
defineProps<{
  modelValue: string;
  placeholder?: string;
}>();
defineEmits<{
  (e: "update:modelValue", value: string): void;
}>();
</script>

<template>
  <input
    :value="modelValue"
    @input="
      $emit('update:modelValue', ($event.target as HTMLInputElement).value)
    "
    type="text"
    :placeholder="placeholder"
    class="mr-2 rounded border bg-white p-2 text-gray-800 dark:bg-gray-700 dark:text-gray-200"
  />
</template>
```

<Aside type="info" title="Info">
  Want to check out the full example yourself? [click
  me](https://github.com/alexanderop/todo-app-example)
</Aside>

| Component Level | Job                                                                                           | Examples                                            |
| --------------- | --------------------------------------------------------------------------------------------- | --------------------------------------------------- |
| Atoms           | Pure, single-purpose components                                                               | BaseButton BaseInput BaseIcon BaseText              |
| Molecules       | Combinations of atoms with minimal logic                                                      | SearchBar LoginForm StarRating Tooltip              |
| Organisms       | Larger, self-contained, reusable components. Can perform side effects and complex operations. | TheHeader ProductCard CommentSection NavigationMenu |
| Templates       | Nuxt layouts defining page structure                                                          | DefaultLayout BlogLayout DashboardLayout AuthLayout |
| Pages           | Components handling data and API calls                                                        | HomePage UserProfile ProductList CheckoutPage       |

## Summary

Atomic Design gives you a clear code structure and works well as a starting point.
As complexity grows, other architectures may fit better.
My post on [How to structure vue Projects](../how-to-structure-vue-projects) covers approaches beyond Atomic Design for larger projects.

---

--- title: Bolt Your Presentations: AI-Powered Slides description: Elevate your dev presentations with AI-powered tools. Learn to leverage Bolt, Slidev, and WebContainers for rapid, code-friendly slide creation. This guide walks developers through 7 steps to build impressive tech presentations using Markdown and browser-based Node.js. Master efficient presentation development with instant prototyping and one-click deployment to Netlify tags: ['productivity', 'ai'] url: https://alexop.dev/posts/create-ai-presentations-fast ---

# Bolt Your Presentations: AI-Powered Slides



## Introduction

Presentations plague the middle-class professional. Most bore audiences with wordy slides. But AI tools promise sharper results, faster. Let's explore how.

![Bolt landingpage](../../assets/images/create-ai-presentations-fast/venn.svg)

## The Birth of Bolt

StackBlitz unveiled Bolt at ViteConf 2024. This browser-based coding tool lets developers build web apps without local setup. Pair it with Slidev, a Markdown slide creator, for rapid presentation development.

[![Image Presentation WebContainers & AI: Introducing bolt.new](http://img.youtube.com/vi/knLe8zzwNRA/0.jpg)](https://www.youtube.com/watch?v=knLe8zzwNRA "WebContainers & AI: Introducing bolt.new")

## Tools Breakdown

Three key tools enable this approach:

1. Bolt: AI-powered web app creation in the browser
   ![Bolt landingpage](../../assets/images/create-ai-presentations-fast/bolt-desc.png)

2. Slidev: Markdown-based slides with code support
   ![Slidev Landing page](../../assets/images/create-ai-presentations-fast/slidev-desc.png)

3. Webcontainers: Browser-based Node.js for instant prototyping
   ![WebContainers landing page](../../assets/images/create-ai-presentations-fast/webcontainers-interface.png)

## Seven Steps to AI Presentation Mastery

Follow these steps to craft AI-powered presentations:

1. Open bolt.new in your browser.

2. Tell Bolt to make a presentation on your topic. Be specific. (add use Slidedev for it)
   ![Screenshot for chat Bolt](../../assets/images/create-ai-presentations-fast/initial-interface.png)

3. Review the Bolt-generated slides. Check content and flow.
   ![Screenshot presentation result of bolt](../../assets/images/create-ai-presentations-fast/presentation.png)

4. Edit and refine.
   ![Screenshot for code from Bolt](../../assets/images/create-ai-presentations-fast/code-overview.png)

5. Ask AI for help with new slides, examples, or transitions.

6. Add code snippets and diagrams.

7. Deploy to Netlify with one click.
   ![Screenshot deploy bolt](../../assets/images/create-ai-presentations-fast/deploy-netlify.png)

## Why This Method Works

This approach delivers key advantages:

- Speed: Bolt jumpstarts content creation.
- Ease: No software to install.
- Flexibility: Make real-time adjustments.
- Collaboration: Share works-in-progress.
- Quality: Built-in themes ensure polish.
- Version control: Combine it with GitHub.

## Conclusion

Try this approach for your next talk. You'll create polished slides that engage your audience.

---

--- title: 10 Rules for Better Writing from the Book Economical Writing description: Master 10 key writing techniques from Deirdre McCloskey's 'Economical Writing.' Learn to use active verbs, write clearly, and avoid common mistakes. Ideal for students, researchers, and writers aiming to communicate more effectively. tags: ['book-summary', 'productivity'] url: https://alexop.dev/posts/10-rules-better-writing-economical-writing-book ---

# 10 Rules for Better Writing from the Book Economical Writing



<BookCover
  src={bookCoverImage}
  alt="Book cover of Economical Writing"
  title="Economical Writing"
  author="Deirdre N. McCloskey"
  publicationYear={2019}
  genre="Academic Writing"
  rating={5}
  link="https://www.amazon.com/dp/022644807X"
/>

## Introduction

I always look for ways to `improve my writing`. Recently, I found Deirdre McCloskey’s book `Economical Writing` through an Instagram reel. In this post, I share `10 useful rules` from the book, with examples and quotes from McCloskey.

## Rules

### Rule 1: Be Thou Clear; but Seek Joy, Too

> Clarity is a matter of speed directed at The Point.
> Bad writing makes slow reading.

McCloskey emphasizes that `clarity is crucial above all`. When writing about complex topics, give your reader every help possible. I've noticed that even if a text has good content, bad writing makes it hard to understand.

<ExampleComparison
  bad="The aforementioned methodology was implemented to facilitate the optimization of resource allocation."
  good="We used this method to make the best use of our resources. It was exciting to see how much we could improve!"
/>

### Rule 2: You Will Need Tools

> The next most important tool is a dictionary, or nowadays a site on the internet that is itself a good dictionary. Googling a word is a bad substitute for a good dictionary site. You have to choose the intelligent site over the dreck such as Wiktionary, Google, and Dictionary.com, all useless.

The Writer highlights the significance of `tools` that everyone who is serious about writing should use. The tools could be:

- <a href="https://www.grammarly.com" target="_blank" rel="noopener noreferrer">
    Spell Checker
  </a>
  (Grammarly for example)
- <a href="https://www.oed.com" target="_blank" rel="noopener noreferrer">
    OED
  </a>
  (a real dictionary to look up the origin of words)
- <a href="https://www.thesaurus.com" target="_blank" rel="noopener noreferrer">
    Thesaurus
  </a>
  (shows you similar words)
- <a
    href="https://www.hemingwayapp.com"
    target="_blank"
    rel="noopener noreferrer"
  >
    Hemingway Editor
  </a>
  (improves readability and highlights complex sentences)

### Rule 3: Avoid Boilerplate

McCloskey warns against using `filler language`:

> Never start a paper with that all-purpose filler for the bankrupt imagination, 'This paper . . .'

<ExampleComparison
  bad="In this paper, we will explore, examine, and analyze the various factors that contribute to climate change."
  good="Climate change stems from several key factors, including rising greenhouse gas emissions and deforestation."
/>

### Rule 4: A Paragraph Should Have a Point

Each paragraph should `focus` on a single topic:

> The paragraph should be a more or less complete discussion of one topic.

<ExampleComparison
  bad="The economy is complex. There are many factors involved. Some people think it's improving while others disagree. It's hard to predict what will happen next."
  good="The economy's complexity makes accurate predictions challenging, as multiple factors influence its performance in often unpredictable ways."
/>

### Rule 5: Make Your Writing Cohere

Coherence is crucial for readability:

> Make writing hang together. The reader can understand writing that hangs together,
> from the level of phrases up to entire books.

<ExampleComparison
  bad="The experiment failed. We used new equipment. The results were unexpected."
  good="We used new equipment for the experiment. However, it failed, producing unexpected results."
/>

### Rule 6: Avoid Elegant Variation

McCloskey emphasizes that `clarity trumps elegance`:

> People who write so seem to mistake the purpose of writing, believing it to be an opportunity for empty display. The seventh grade, they should realize, is over.

{" "}

<ExampleComparison
  bad="The cat sat on the windowsill. The feline then jumped to the floor. The domestic pet finally curled up in its bed."
  good="The cat sat on the windowsill. It then jumped to the floor and finally curled up in its bed."
/>

### Rule 7: Watch Punctuation

Proper punctuation is more complex than it seems:

> Another detail is punctuation. You might think punctuation would be easy, since English has only seven marks."
> After a comma (,), semicolon (;), or colon (:), put one space before you start something new. After a period (.), question mark (?), or exclamation point (!), put two spaces.
> The colon (:) means roughly “to be specific.” The semicolon (;) means roughly “likewise” or “also.”

{" "}

<ExampleComparison
  bad="However we decided to proceed with the project despite the risks."
  good="However, we decided to proceed with the project despite the risks."
/>

### Rule 8: Watch The Order Around Switch Until It Good Sounds

McCloskey advises ending sentences with the main point:

> You should cultivate the habit of mentally rearranging the order of words and phrases of every sentence you write. Rules, as usual, govern the rewriting. One rule or trick is to use so-called auxiliary verbs (should, can, might, had, is, etc.) to lessen clotting in the sentence. “Looking through a lens-shape magnified what you saw.” Tough to read. “Looking through a lens-shape would magnify what you saw” is easier.
> The most important rule of rearrangement of sentences is that the end is the place of emphasis. I wrote the sentence first as “The end of the sentence is the emphatic location,” which put the emphasis on the word location. The reader leaves the sentence with the last word ringing in her mental ears.

<ExampleComparison
  bad="Looking through a lens-shape magnified what you saw."
  good="Looking through a lens-shape would magnify what you saw."
/>

### Rule 9: Use Verbs, Active Ones

Active verbs make writing more engaging:

> Use active verbs: not “Active verbs should be used,” which is cowardice, hiding the user in the passive voice. Rather: “You should use active verbs.”
> Verbs make English. If you pick out active, accurate, and lively verbs, you will write in an active, accurate, and lively style.

{" "}

<ExampleComparison
  bad="The decision was made by the committee to approve the proposal."
  good="The committee decided to approve the proposal."
/>

### Rule 10: Avoid This, That, These, Those

Vague demonstrative pronouns can obscure meaning:

> Often the plain the will do fine and keep the reader reading. The formula in revision is to ask of every this, these, those whether it might better be replaced by ether plain old the (the most common option) or it, or such (a).

<ExampleComparison
  bad="This led to that, which caused these problems."
  good="The budget cuts led to staff shortages, which caused delays in project completion."
/>

## Summary

I quickly finished the book, thanks to its excellent writing style. Its most important lesson was that much of what I learned about `good writing` in school is incorrect. Good writing means expressing your thoughts `clearly`. Avoid using complicated words. `Write the way you speak`. The book demonstrates that using everyday words is a strength, not a weakness. I suggest everyone read this book. Think about how you can improve your writing by using its ideas.

---

--- title: TypeScript Tutorial: Extracting All Keys from Nested Object description: Learn how to extract all keys, including nested ones, from TypeScript objects using advanced type manipulation techniques. Improve your TypeScript skills and write safer code. tags: ['typescript'] url: https://alexop.dev/posts/typescript-extract-all-keys-nested-objects ---

# TypeScript Tutorial: Extracting All Keys from Nested Object



## What's the Problem?

Let's say you have a big TypeScript object. It has objects inside objects. You want to get all the keys, even the nested ones. But TypeScript doesn't provide this functionality out of the box.

Look at this User object:

```typescript twoslash
type User = {
  id: string;
  name: string;
  address: {
    street: string;
    city: string;
  };
};
```

You want "id", "name", and "address.street". The standard approach is insufficient:

```typescript
// little helper to prettify the type on hover
type Pretty<T> = {
  [K in keyof T]: T[K];
} & {};

type UserKeys = keyof User;
type PrettyUserKeys = Pretty<UserKeys>;
```

This approach returns the top-level keys, missing nested properties like "address.street".

We need a more sophisticated solution using TypeScript's advanced features:

1. Conditional Types (if-then for types)
2. Mapped Types (change each part of a type)
3. Template Literal Types (make new string types)
4. Recursive Types (types that refer to themselves)

Here's our solution:

```typescript
type ExtractKeys<T> = T extends object
  ? {
      [K in keyof T & string]:
        | K
        | (T[K] extends object ? `${K}.${ExtractKeys<T[K]>}` : K);
    }[keyof T & string]
  : never;
```

Let's break down this type definition:

1. We check if T is an object.
2. For each key in the object:
3. We either preserve the key as-is, or
4. If the key's value is another object, we combine the key with its nested keys
5. We apply this to the entire type structure

Now let's use it:

```typescript
type UserKeys = ExtractKeys<User>;
```

This gives us all keys, including nested ones.

The practical benefits become clear in this example:

```typescript
const user: User = {
  id: "123",
  name: "John Doe",
  address: {
    street: "Main St",
    city: "Berlin",
  },
};

function getProperty(obj: User, key: UserKeys) {
  const keys = key.split(".");
  let result: any = obj;

  for (const k of keys) {
    result = result[k];
  }

  return result;
}

// This works
getProperty(user, "address.street");

// This gives an error
getProperty(user, "address.country");
```

TypeScript detects potential errors during development.

Important Considerations:

1. This type implementation may impact performance with complex nested objects.
2. The type system enhances development-time safety without runtime overhead.
3. Consider the trade-off between type safety and code readability.

## Wrap-Up

We've explored how to extract all keys from nested TypeScript objects. This technique provides enhanced type safety for your data structures. Consider the performance implications when implementing this in your projects.

---

--- title: TypeScript Snippets in Astro: Show, Don't Tell description: Learn how to add interactive type information and syntax highlighting to TypeScript snippets in your Astro site, enhancing code readability and user experience. tags: ['astro', 'typescript'] url: https://alexop.dev/posts/typescript-snippets-astro-show-dont-tell ---

# TypeScript Snippets in Astro: Show, Don't Tell



## Elevate Your Astro Code Highlights with TypeScript Snippets

Want to take your Astro code highlights to the next level? This guide will show you how to add TypeScript snippets with hover-over type information, making your code examples more interactive and informative.

## Prerequisites for Astro Code Highlights

Start with an Astro project. Follow the [official Astro quickstart guide](https://docs.astro.build/en/getting-started/) to set up your project.

## Configuring Shiki for Enhanced Astro Code Highlights

Astro includes Shiki for syntax highlighting. Here's how to optimize it for TypeScript snippets:

1. Update your `astro.config.mjs`:

```typescript
export default defineConfig({
  markdown: {
    shikiConfig: {
      themes: { light: "min-light", dark: "tokyo-night" },
      wrap: true,
    },
  },
});
```

2. Add a stylish border to your code blocks:

```css
pre:has(code) {
  @apply border border-skin-line;
}
```

## Adding Type Information to Code Blocks

To add type information to your code blocks, you can use TypeScript's built-in type annotations:

```typescript

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

const user: User = {
  name: "John Doe",
  age: "30", // Type error: Type 'string' is not assignable to type 'number'
};

console.log(user.name);
```

You can also show type information inline:

```typescript
interface User {
  name: string;
  age: number;
}

const user: User = {
  name: "John Doe",
  age: 30,
};

// The type of user.name is 'string'
const name = user.name;
```

## Benefits of Enhanced Astro Code Highlights

Your Astro site now includes:

- Advanced syntax highlighting
- Type information in code blocks
- Adaptive light and dark mode code blocks

These features enhance code readability and user experience, making your code examples more valuable to readers.

---

--- title: Vue 3.5's onWatcherCleanup: Mastering Side Effect Management in Vue Applications description: Discover how Vue 3.5's new onWatcherCleanup function revolutionizes side effect management in Vue applications tags: ['vue'] url: https://alexop.dev/posts/vue-35s-onwatchercleanup-mastering-side-effect-management-in-vue-applications ---

# Vue 3.5's onWatcherCleanup: Mastering Side Effect Management in Vue Applications



## Introduction

My team and I discussed Vue 3.5's new features, focusing on the `onWatcherCleanup` function. The insights proved valuable enough to share in this blog post.

## The Side Effect Challenge in Vue

Managing side effects in Vue presents challenges when dealing with:

- API calls
- Timer operations
- Event listener management

These side effects become complex during frequent value changes.

## A Common Use Case: Fetching User Data

To illustrate the power of `onWatcherCleanup`, let's compare the old and new ways of fetching user data.

### The Old Way

```vue
<script setup lang="ts">
const userId = ref<string>("");
const userData = ref<any | null>(null);
let controller: AbortController | null = null;

watch(userId, async (newId: string) => {
  if (controller) {
    controller.abort();
  }
  controller = new AbortController();

  try {
    const response = await fetch(`https://api.example.com/users/${newId}`, {
      signal: controller.signal,
    });
    if (!response.ok) {
      throw new Error("User not found");
    }
    userData.value = await response.json();
  } catch (error) {
    if (error instanceof Error && error.name !== "AbortError") {
      console.error("Fetch error:", error);
      userData.value = null;
    }
  }
});
</script>

<template>
  <div>
    
    <div v-if="userData">
      <h2>User Data</h2>
      <pre>{{ JSON.stringify(userData, null, 2) }}</pre>
    </div>
    <div v-else-if="userId && !userData">User not found</div>
  </div>
</template>
```

Problems with this method:

1. External controller management
2. Manual request abortion
3. Cleanup logic separate from effect
4. Easy to forget proper cleanup

## The New Way: onWatcherCleanup

Here's how `onWatcherCleanup` improves the process:

```vue
<script setup lang="ts">
const userId = ref<string>("");
const userData = ref<any | null>(null);

watch(userId, async (newId: string) => {
  const controller = new AbortController();

  onWatcherCleanup(() => {
    controller.abort();
  });

  try {
    const response = await fetch(`https://api.example.com/users/${newId}`, {
      signal: controller.signal,
    });
    if (!response.ok) {
      throw new Error("User not found");
    }
    userData.value = await response.json();
  } catch (error) {
    if (error instanceof Error && error.name !== "AbortError") {
      console.error("Fetch error:", error);
      userData.value = null;
    }
  }
});
</script>

<template>
  <div>
    
    <div v-if="userData">
      <h2>User Data</h2>
      <pre>{{ JSON.stringify(userData, null, 2) }}</pre>
    </div>
    <div v-else-if="userId && !userData">User not found</div>
  </div>
</template>
```

### Benefits of onWatcherCleanup

1. Clearer code: Cleanup logic is right next to the effect
2. Automatic execution
3. Fewer memory leaks
4. Simpler logic
5. Consistent with Vue API
6. Fits seamlessly into Vue's reactivity system

## When to Use onWatcherCleanup

Use it to:

- Cancel API requests
- Clear timers
- Remove event listeners
- Free resources

## Advanced Techniques

### Multiple Cleanups

```ts twoslash
watch(dependency, () => {
  const timer1 = setInterval(() => {
    /* ... */
  }, 1000);
  const timer2 = setInterval(() => {
    /* ... */
  }, 5000);

  onWatcherCleanup(() => clearInterval(timer1));
  onWatcherCleanup(() => clearInterval(timer2));

  // More logic...
});
```

### Conditional Cleanup

```ts twoslash
watch(dependency, () => {
  if (condition) {
    const resource = acquireResource();
    onWatcherCleanup(() => releaseResource(resource));
  }

  // More code...
});
```

### With watchEffect

```ts twoslash
watchEffect(onCleanup => {
  const data = fetchSomeData();

  onCleanup(() => {
    cleanupData(data);
  });
});
```

## How onWatcherCleanup Works

![Image description](../../assets/images/onWatcherCleanup.png)

Vue uses a WeakMap to manage cleanup functions efficiently. This approach connects cleanup functions with their effects and triggers them at the right time.

### Executing Cleanup Functions

The system triggers cleanup functions in two scenarios:

1. Before the effect re-runs
2. When the watcher stops

This ensures proper resource management and side effect cleanup.

### Under the Hood

The `onWatcherCleanup` function integrates with Vue's reactivity system. It uses the current active watcher to associate cleanup functions with the correct effect, triggering cleanups in the right context.

## Performance

The `onWatcherCleanup` implementation prioritizes efficiency:

- The system creates cleanup arrays on demand
- WeakMap usage optimizes memory management
- Adding cleanup functions happens instantly

These design choices enhance your Vue applications' performance when handling watchers and side effects.

## Best Practices

1. Register cleanups at the start of your effect function
2. Keep cleanup functions simple and focused
3. Avoid creating new side effects within cleanup functions
4. Handle potential errors in your cleanup logic
5. Thoroughly test your effects and their associated cleanups

## Conclusion

Vue 3.5's `onWatcherCleanup` strengthens the framework's toolset for managing side effects. It enables cleaner, more maintainable code by unifying setup and teardown logic. This feature helps create robust applications that handle resource management effectively and prevent side effect-related bugs.

As you incorporate `onWatcherCleanup` into your projects, you'll discover how it simplifies common patterns and prevents bugs related to unmanaged side effects.

---

--- title: How to Build Your Own Vue-like Reactivity System from Scratch description: Learn to build a Vue-like reactivity system from scratch, implementing your own ref() and watchEffect().  tags: ['vue'] url: https://alexop.dev/posts/how-to-build-your-own-vue-like-reactivity-system-from-scratch ---

# How to Build Your Own Vue-like Reactivity System from Scratch



## Introduction

Understanding the core of modern Frontend frameworks is crucial for every web developer. Vue, known for its reactivity system, offers a seamless way to update the DOM based on state changes. But have you ever wondered how it works under the hood?

In this tutorial, we'll demystify Vue's reactivity by building our own versions of `ref()` and `watchEffect()`. By the end, you'll have a deeper understanding of reactive programming in frontend development.

## What is Reactivity in Frontend Development?

Before we dive in, let's define reactivity:

> **Reactivity: A declarative programming model for updating based on state changes.**[^1]

[^1]: [What is Reactivity](https://www.pzuraq.com/blog/what-is-reactivity) by Pzuraq

This concept is at the heart of modern frameworks like Vue, React, and Angular. Let's see how it works in a simple Vue component:

```vue
<script setup>
const counter = ref(0);

const incrementCounter = () => {
  counter.value++;
};
</script>

<template>
  <div>
    <h1>Counter: {{ counter }}</h1>
    <button @click="incrementCounter">Increment</button>
  </div>
</template>
```

In this example:

1. **State Management:** `ref` creates a reactive reference for the counter.
2. **Declarative Programming:** The template uses `{{ counter }}` to display the counter value. The DOM updates automatically when the state changes.

## Building Our Own Vue-like Reactivity System

To create a basic reactivity system, we need three key components:

1. A method to store data
2. A way to track changes
3. A mechanism to update dependencies when data changes

### Key Components of Our Reactivity System

1. A store for our data and effects
2. A dependency tracking system
3. An effect runner that activates when data changes

### Understanding Effects in Reactive Programming

An `effect` is a function that executes when a reactive state changes. Effects can update the DOM, make API calls, or perform calculations.

```ts
type Effect = () => void;
```

This `Effect` type represents a function that runs when a reactive state changes.

### The Store

We'll use a Map to store our reactive dependencies:

```ts
const depMap: Map<object, Map<string | symbol, Set<Effect>>> = new Map();
```

## Implementing Key Reactivity Functions

### The Track Function: Capturing Dependencies

This function records which effects depend on specific properties of reactive objects. It builds a dependency map to keep track of these relationships.

```ts
type Effect = () => void;

let activeEffect: Effect | null = null;

const depMap: Map<object, Map<string | symbol, Set<Effect>>> = new Map();

function track(target: object, key: string | symbol): void {
  if (!activeEffect) return;

  let dependenciesForTarget = depMap.get(target);
  if (!dependenciesForTarget) {
    dependenciesForTarget = new Map<string | symbol, Set<Effect>>();
    depMap.set(target, dependenciesForTarget);
  }

  let dependenciesForKey = dependenciesForTarget.get(key);
  if (!dependenciesForKey) {
    dependenciesForKey = new Set<Effect>();
    dependenciesForTarget.set(key, dependenciesForKey);
  }

  dependenciesForKey.add(activeEffect);
}
```

### The Trigger Function: Activating Effects

When a reactive property changes, this function activates all the effects that depend on that property. It uses the dependency map created by the track function.

```ts
function trigger(target: object, key: string | symbol): void {
  const depsForTarget = depMap.get(target);
  if (depsForTarget) {
    const depsForKey = depsForTarget.get(key);
    if (depsForKey) {
      depsForKey.forEach(effect => effect());
    }
  }
}
```

### Implementing ref: Creating Reactive References

This creates a reactive reference to a value. It wraps the value in an object with getter and setter methods that track access and trigger updates when the value changes.

```ts
class RefImpl<T> {
  private _value: T;

  constructor(value: T) {
    this._value = value;
  }

  get value(): T {
    track(this, "value");
    return this._value;
  }

  set value(newValue: T) {
    if (newValue !== this._value) {
      this._value = newValue;
      trigger(this, "value");
    }
  }
}

function ref<T>(initialValue: T): RefImpl<T> {
  return new RefImpl(initialValue);
}
```

### Creating watchEffect: Reactive Computations

This function creates a reactive computation. It executes the provided effect function and re-runs it whenever any reactive values used within the effect change.

```ts
function watchEffect(effect: Effect): void {
  function wrappedEffect() {
    activeEffect = wrappedEffect;
    effect();
    activeEffect = null;
  }

  wrappedEffect();
}
```

## Putting It All Together: A Complete Example

Let's see our reactivity system in action:

```ts
const countRef = ref(0);
const doubleCountRef = ref(0);

watchEffect(() => {
  console.log(`Ref count is: ${countRef.value}`);
});

watchEffect(() => {
  doubleCountRef.value = countRef.value * 2;
  console.log(`Double count is: ${doubleCountRef.value}`);
});

countRef.value = 1;
countRef.value = 2;
countRef.value = 3;

console.log("Final depMap:", depMap);
```

## Diagram for the complete workflow

![diagram for reactive workflow](../../assets/images/refFromScratch.png)

check out the full example -> [click](https://www.typescriptlang.org/play/?#code/C4TwDgpgBAogZnCBjYUC8UAUBKdA+KANwHsBLAEwG4BYAKDoBsJUBDFUwieRFALlgTJUAHygA7AK4MG6cVIY16tAPTKoAYQBOEFsGgsoAWRZgowYlADO57VHIRIY+2KSkIlqHGKaoOpAAsoYgAjACshADo6VSgAFX9oY1MAd1JpKH9iBnIgsKEPYH9dKABbEygAawgQAotLZg9iOF9BFEso2iRiMWs7ByT+JIAeEPCUABojEyHrTVIxAHMoUUsQEuCsyYBlZiHuITxD2TEIZKmwHEU6OAkXYFJus002CsxgFk0F5n5RoUmqkD8WbzJYrNYbBjYfgkChQADedCgUFIzUwbHunH2KFwCNoSKRXR6WQgEQYxAWmAA5LFnkgKiCWjxgLxKZN0RwuK1gNgrnj8UxUPYwJYAGLeWIfL6oDBCpIRKVvSXMHmI-EorAAQiFovFSu58NV+L6wrFmgln2Yx1O5xmwDmi2WVnBmygO2Aey5h0uhvxspMEXqwEVFuAk21pvNUpVfKRAF86D6BcadZoANLVWTh3Uh+XMTAA6NG9WYLUOFPpkA4n1IrNpjMYE5nN0epl4b0x31liN6gN5gFhrveCuF-HxpRG2sViIscjkNHsTFc6OqsdjhO0G53B5iJ6kBZfTTBqU-PITSrVIF2hlg9ZZKFEMg5XEE7qWYmk8lUml7g8MiBcjwvB8d4QxZSYQKlSZKQBMDz0rXkXx6QVBzNPVM36f0FQg5VFCRYta0jZUDQ7Qleknetk27HMFQLXC1VRcjK2Io0axQqcgJgNh-Ewf8mXwZiWMQt8mA-ClKRgAAPZAJHuB1eKEWD5OxOjBKUoMRyNWMNKgMc4zoNdOgYFhLA8AAlf8AEkSjABghliAhnygMA5kIXRoAAfVchgJAgfhYgQqBSLtCQUG8TAvJ8vyqw7QpSHaTyWG86AMAiiA6IMpEpSIRKfJwPyBKRO0Xjefw4qg1LKW00j3zJMSAHFmFkpZUtg2L4tS7TtGACRNB3NqIgSpL0vXJFA2ypLMEbAA1HLfLiaKi1RabZqgDU0AwfrBp8haWM21KrWSGahurQLXxqz9KTdJrxsi1lxFOI7tpU-Er33CBDza8rZsq57dJ0-T103dhHm0OA7LbeZSHuRLHrm2J73MuArJs8GBK6nqd0bKBEeRhhMEh6GGFh6MDKB+5HmSXQAixIM1P4Gn7xhJ9VTJ7coGSZ4wEgcgaZwAqoHZRc+IwDmTG5mnnrU9sjUFzlhbkaRhvHdnOfFrl2wMmJJJYaymCgCRLBYL5eHXILTtuYBEdkUHMAABmXTpX0FYgJGCJh1BdsRLf-a3-zth2ta5KAAEZ+AAGXJAoEhu6AmnNr3EboSngGp9W+bQBzVWqkTaswAADK2ugt5FLH4AASOEi4T-8IlS2M85Jh310DviACZ+DdDxyBdt2IA9i2rfMKBgmgbvXb1wpoH2uOq+9uAk6p-xefTzO+TH3v++ruBa5WjBZ8RnekqgAAqKBW7o7OSVzvOABEe712eS-LuF1-dz258Pnz68b3kYm-N77RLEnoyfIdB94132hgYOihwHb0gWfGB78D7wIAMy8nXKbM6OcLoinmIlY0Aw7p+jANGIAA)

## Beyond the Basics: What's Missing?

While our implementation covers the core concepts, production-ready frameworks like Vue offer more advanced features:

1. Handling of nested objects and arrays
2. Efficient cleanup of outdated effects
3. Performance optimizations for large-scale applications
4. Computed properties and watchers
5. Much more...

## Conclusion: Mastering Frontend Reactivity

By building our own `ref` and `watchEffect` functions, we've gained valuable insights into the reactivity systems powering modern frontend frameworks. We've covered:

- Creating reactive data stores with `ref`
- Tracking changes using the `track` function
- Updating dependencies with the `trigger` function
- Implementing reactive computations via `watchEffect`

This knowledge empowers you to better understand, debug, and optimize reactive systems in your frontend projects.

---

--- title: What is Local-first Web Development? description: What is local-first software and why does it matter? This guide covers local-first architecture, offline-capable apps with automatic sync, data ownership, and how to build a local-first web app with Vue step by step. tags: ['local-first', 'architecture', 'vue', 'offline'] url: https://alexop.dev/posts/what-is-local-first-web-development ---

# What is Local-first Web Development?



Imagine having complete control over your data in every web app, from social media platforms to productivity tools. Picture using these apps offline with automatic synchronization when you're back online. This is the essence of local-first web development – a revolutionary approach that puts users in control of their digital experience.

As browsers and devices become more powerful, we can now create web applications that minimize backend dependencies, eliminate loading delays, and overcome network errors. In this comprehensive guide, we'll dive into the fundamentals of local-first web development and explore its numerous benefits for users and developers alike.

## The Limitations of Traditional Web Applications

![Traditional Web Application](../../assets/images/what-is-local-first/tradidonal-web-app.png)

Traditional web applications rely heavily on backend servers for most operations. This dependency often results in:

- Frequent loading spinners during data saves
- Potential errors when the backend is unavailable
- Limited or no functionality when offline
- Data storage primarily in the cloud, reducing user ownership

While modern frameworks like Nuxt have improved initial load times through server-side rendering, many apps still suffer from performance issues post-load. Moreover, users often face challenges in accessing or exporting their data if an app shuts down.

## Core Principles of Local-First Development

Local-first development shares similarities with offline-first approaches but goes further in prioritizing user control and data ownership. Here are the key principles that define a true local-first web application:

1. **Instant Access:** Users can immediately access their work without waiting for data to load or sync.
2. **Device Independence:** Data is accessible across multiple devices seamlessly.
3. **Network Independence:** Basic tasks function without an internet connection.
4. **Effortless Collaboration:** The app supports easy collaboration, even in offline scenarios.
5. **Future-Proof Data:** User data remains accessible and usable over time, regardless of software changes.
6. **Built-In Security:** Security and privacy are fundamental design considerations.
7. **User Control:** Users have full ownership and control over their data.

It's important to note that some features, such as account deletion, may still require real-time backend communication to maintain data integrity.

For a deeper dive into local-first software principles, check out [Ink & Switch: Seven Ideals for Local-First Software](https://www.inkandswitch.com/local-first/#seven-ideals-for-local-first-software).

## Cloud vs Local-First Software Comparison

| Feature                 | Cloud Software 🌥️                                                  | Local-First Software 💻                                   |
| ----------------------- | ------------------------------------------------------------------ | --------------------------------------------------------- |
| Real-time Collaboration | 😟 Hard to implement                                               | 😊 Built for real-time sync                               |
| Offline Support         | 😟 Does not work offline                                           | 😊 Works offline                                          |
| Service Reliability     | 😟 Service shuts down? Lose everything!                            | 😊 Users can continue using local copy of software + data |
| Service Implementation  | 😟 Custom service for each app (infra, ops, on-call rotation, ...) | 😊 Sync service is generic → outsource to cloud vendor    |

## Local-First Software Fit Guide

### ✅ Good Fit

- **File Editing** 📝 - text editors, word processors, spreadsheets, slides, graphics, video, music, CAD, Jupyter notebooks
- **Productivity** 📋 - notes, tasks, issues, calendar, time tracking, messaging, bookkeeping
- **Summary**: Ideal for apps where users freely manipulate their data

### ❌ Bad Fit

- **Money** 💰 - banking, payments, ad tracking
- **Physical Resources** 📦 - e-commerce, inventory
- **Vehicles** 🚗 - car sharing, freight, logistics
- **Summary**: Better with centralized cloud/server model for real-world resource management

## Types of Local-First Applications

Local-first applications can be categorized into two main types:

### 1. Local-Only Applications

![Local-Only Applications](../../assets/images/what-is-local-first/local-only.png)

While often mistakenly categorized as local-first, these are actually offline-first applications. They store data exclusively on the user's device without cloud synchronization, and data transfer between devices requires manual export and import processes. This approach, while simpler to implement, doesn't fulfill the core local-first principles of device independence and effortless collaboration. It's more accurately described as an offline-first architecture.

### 2. Sync-Enabled Applications

![Sync-Enabled Applications](../../assets/images/what-is-local-first/sync-enabled-applications.png)

These applications automatically synchronize user data with a cloud database, enhancing the user experience but introducing additional complexity for developers.

## Challenges in Implementing Sync-Enabled Local-First Apps

Developing sync-enabled local-first applications presents unique challenges, particularly in managing data conflicts. For example, in a collaborative note-taking app, offline edits by multiple users can lead to merge conflicts upon synchronization. Resolving these conflicts requires specialized algorithms and data structures, which we'll explore in future posts in this series.

Even for single-user applications, synchronizing local data with cloud storage demands careful consideration and additional logic.

## Building Local-First Web Apps: A Step-by-Step Approach

To create powerful local-first web applications, consider the following key steps, with a focus on Vue.js:

1. **Transform Your Vue SPA into a PWA**
   Convert your Vue Single Page Application (SPA) into a Progressive Web App (PWA) to enable native app-like interactions. For a detailed guide, see [Create a Native-Like App in 4 Steps: PWA Magic with Vue 3 and Vite](../create-pwa-vue3-vite-4-steps).

2. **Implement Robust Storage Solutions**
   Move beyond simple localStorage to more sophisticated storage mechanisms that support offline functionality and data persistence. Learn more in [How to Use SQLite in Vue 3: Complete Guide to Offline-First Web Apps](../sqlite-vue3-offline-first-web-apps-guide).

3. **Develop Syncing and Authentication Systems**
   For sync-enabled apps, implement user authentication and secure data synchronization across devices. Learn how to implement syncing and conflict resolution in <InternalLink slug="building-local-first-apps-vue-dexie">Building Local-First Apps with Vue and Dexie</InternalLink>.

4. **Prioritize Security Measures**
   Employ encryption techniques to protect sensitive user data stored in the browser.

We'll delve deeper into each of these topics throughout this series on local-first web development.

## Additional Resources for Local-First Development

To further your understanding of local-first applications, explore these valuable resources:

1. **Website:** [Local First Web](https://localfirstweb.dev/) - An excellent starting point with comprehensive follow-up topics.
2. **Podcast:** [Local First FM](https://www.localfirst.fm/) - An insightful podcast dedicated to local-first development.
3. **Community:** Join the [Local First Discord](https://discord.com/invite/ZRrwZxn4rW) to connect with fellow developers and enthusiasts.
4. **Resource:** [Local-First Landscape](https://www.localfirst.fm/landscape) - A comprehensive overview of local-first technologies, frameworks, and tools to help developers navigate the ecosystem.

## Community Discussion

This article sparked an interesting discussion on Hacker News, where developers shared their experiences and insights about local-first development. You can join the conversation and read different perspectives on the topic in the [Hacker News discussion thread](https://news.ycombinator.com/item?id=43577285).

## Conclusion: Embracing the Local-First Revolution

Local-first web development represents a paradigm shift in how we create and interact with web applications. By prioritizing user control, data ownership, and offline capabilities, we can build more resilient, user-centric apps that adapt to the evolving needs of modern users.

This introductory post marks the beginning of an exciting journey into the world of local-first development. Stay tuned for more in-depth articles exploring various aspects of building powerful, local-first web applications with Vue and other modern web technologies.

---

--- title: Vue Accessibility Blueprint: 8 Steps description: Master Vue accessibility with our comprehensive guide. Learn 8 crucial steps to create inclusive, WCAG-compliant web applications that work for all users. tags: ['vue', 'accessibility'] url: https://alexop.dev/posts/vue-accessibility-blueprint-8-steps ---

# Vue Accessibility Blueprint: 8 Steps



Creating accessible Vue components is crucial for building inclusive web applications that work for everyone, including people with disabilities. This guide outlines 8 essential steps to improve the accessibility of your Vue projects and align them with Web Content Accessibility Guidelines (WCAG) standards.

## Why Accessibility Matters

Implementing accessible design in Vue apps:

- Expands your potential user base
- Enhances user experience
- Boosts SEO performance
- Reduces legal risks
- Demonstrates social responsibility

Now let's explore the 8 key steps for building accessible Vue components:

## 1. Master Semantic HTML

Using proper HTML structure and semantics provides a solid foundation for assistive technologies. Key actions:

- Use appropriate heading levels (h1-h6)
- Add ARIA attributes
- Ensure form inputs have associated labels

```html
<header>
  <h1>Accessible Blog</h1>
  <nav aria-label="Main">
    <a href="#home">Home</a>
    <a href="#about">About</a>
  </nav>
</header>

<main>
  <article>
    <h2>Latest Post</h2>
    <p>Content goes here...</p>
  </article>

  <form>
    <label for="comment">Comment:</label>
    <textarea id="comment" name="comment"></textarea>
    <button type="submit">Post</button>
  </form>
</main>
```

Resource: [Vue Accessibility Guide](https://vuejs.org/guide/best-practices/accessibility.html)

## 2. Use eslint-plugin-vue-a11y

Add this ESLint plugin to detect accessibility issues during development:

```shell
npm install eslint-plugin-vuejs-accessibility --save-dev
```

Benefits:

- Automated a11y checks
- Consistent code quality
- Less manual testing needed

Resource: [eslint-plugin-vue-a11y GitHub](https://github.com/vue-a11y/eslint-plugin-vuejs-accessibility)

## 3. Test with Vue Testing Library

Adopt Vue Testing Library to write accessibility-focused tests:

```js
test("renders accessible button", () => {
  render(MyComponent);
  const button = screen.getByRole("button", { name: /submit/i });
  expect(button).toBeInTheDocument();
});
```

Resource: [Vue Testing Library Documentation](https://testing-library.com/docs/vue-testing-library/intro/)

## 4. Use Screen Readers

Test your app with screen readers like NVDA, VoiceOver or JAWS to experience it as visually impaired users do.

## 5. Run Lighthouse Audits

Use Lighthouse in Chrome DevTools or CLI to get comprehensive accessibility assessments.

Resource: [Google Lighthouse Documentation](https://developer.chrome.com/docs/lighthouse/overview/)

## 6. Consult A11y Experts

Partner with accessibility specialists to gain deeper insights and recommendations.

## 7. Integrate A11y in Workflows

Make accessibility a core part of planning and development:

- Include a11y requirements in user stories
- Set a11y acceptance criteria
- Conduct team WCAG training

## 8. Automate Testing with Cypress

Use Cypress with axe-core for automated a11y testing:

```js
describe("Home Page Accessibility", () => {
  beforeEach(() => {
    cy.visit("/");
    cy.injectAxe();
  });

  it("Has no detectable a11y violations", () => {
    cy.checkA11y();
  });
});
```

Resource: [Cypress Accessibility Testing Guide](https://docs.cypress.io/app/guides/accessibility-testing)

By following these 8 steps, you will enhance the accessibility of your Vue applications and create more inclusive web experiences. Remember that accessibility is an ongoing process - continually learn, test, and strive to make your apps usable by everyone.

---

--- title: How to Structure Vue Projects description: Discover best practices for structuring Vue projects of any size, from simple apps to complex enterprise solutions. tags: ['vue', 'architecture'] url: https://alexop.dev/posts/how-to-structure-vue-projects ---

# How to Structure Vue Projects



## Quick Summary

This post covers specific Vue project structures suited for different project sizes:

- Flat structure for small projects
- Atomic Design for scalable applications
- Modular approach for larger projects
- Feature Sliced Design for complex applications
- Micro frontends for enterprise-level solutions

## Table of Contents

## Introduction

When starting a Vue project, one of the most critical decisions you'll make is how to structure it. The right structure enhances scalability, maintainability, and collaboration within your team. This consideration aligns with **Conway's Law**:

> "Organizations which design systems are constrained to produce designs which are copies of the communication structures of these organizations."  
> — Mel Conway

In essence, your Vue application's architecture will reflect your organization's structure, influencing how you should plan your project's layout.

![Diagram of Conway's Law](../../assets/images/how-to-structure-vue/conway.png)

Whether you're building a small app or an enterprise-level solution, this guide covers specific project structures suited to different scales and complexities.

---

## 1. Flat Structure: Perfect for Small Projects

Are you working on a small-scale Vue project or a proof of concept? A simple, flat folder structure might be the best choice to keep things straightforward and avoid unnecessary complexity.

<FileTree
  tree={[
    {
      name: "src",
      open: true,
      children: [
        {
          name: "components",
          children: [
            { name: "BaseButton.vue" },
            { name: "BaseCard.vue" },
            { name: "PokemonList.vue" },
            { name: "PokemonCard.vue" },
          ],
        },
        {
          name: "composables",
          children: [{ name: "usePokemon.js" }],
        },
        {
          name: "utils",
          children: [{ name: "validators.js" }],
        },
        {
          name: "layout",
          children: [
            { name: "DefaultLayout.vue" },
            { name: "AdminLayout.vue" },
          ],
        },
        {
          name: "plugins",
          children: [{ name: "translate.js" }],
        },
        {
          name: "views",
          children: [{ name: "Home.vue" }, { name: "PokemonDetail.vue" }],
        },
        {
          name: "router",
          children: [{ name: "index.js" }],
        },
        {
          name: "store",
          children: [{ name: "index.js" }],
        },
        {
          name: "assets",
          children: [
            { name: "images", children: [] },
            { name: "styles", children: [] },
          ],
        },
        {
          name: "tests",
          children: [{ name: "...", comment: "test files" }],
        },
        { name: "App.vue" },
        { name: "main.js" },
      ],
    },
  ]}
/>

### Pros and Cons

<div class="overflow-x-auto">
  <table class="custom-table">
    <thead>
      <tr>
        <th>✅ Pros</th>
        <th>❌ Cons</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>Easy to implement</td>
        <td>Not scalable</td>
      </tr>
      <tr>
        <td>Minimal setup</td>
        <td>Becomes cluttered as the project grows</td>
      </tr>
      <tr>
        <td>Ideal for small teams or solo developers</td>
        <td>Lack of clear separation of concerns</td>
      </tr>
    </tbody>
  </table>
</div>

---

## 2. Atomic Design: Scalable Component Organization

![Atomic Design Diagram](../../assets/images/atomic/diagram.svg)

For larger Vue applications, Atomic Design provides a clear structure. This approach organizes components into a hierarchy from simplest to most complex.

### The Atomic Hierarchy

- **Atoms:** Basic elements like buttons and icons.
- **Molecules:** Groups of atoms forming simple components (e.g., search bars).
- **Organisms:** Complex components made up of molecules and atoms (e.g., navigation bars).
- **Templates:** Page layouts that structure organisms without real content.
- **Pages:** Templates filled with real content to form actual pages.

This method ensures scalability and maintainability, facilitating a smooth transition between simple and complex components.

<FileTree
  tree={[
    {
      name: "src",
      open: true,
      children: [
        {
          name: "components",
          open: true,
          children: [
            {
              name: "atoms",
              children: [{ name: "AtomButton.vue" }, { name: "AtomIcon.vue" }],
            },
            {
              name: "molecules",
              children: [
                { name: "MoleculeSearchInput.vue" },
                { name: "MoleculePokemonThumbnail.vue" },
              ],
            },
            {
              name: "organisms",
              children: [
                { name: "OrganismPokemonCard.vue" },
                { name: "OrganismHeader.vue" },
              ],
            },
            {
              name: "templates",
              children: [
                { name: "TemplatePokemonList.vue" },
                { name: "TemplatePokemonDetail.vue" },
              ],
            },
          ],
        },
        {
          name: "pages",
          children: [
            { name: "PageHome.vue" },
            { name: "PagePokemonDetail.vue" },
          ],
        },
        {
          name: "composables",
          children: [{ name: "usePokemon.js" }],
        },
        {
          name: "utils",
          children: [{ name: "validators.js" }],
        },
        {
          name: "layout",
          children: [
            { name: "LayoutDefault.vue" },
            { name: "LayoutAdmin.vue" },
          ],
        },
        {
          name: "plugins",
          children: [{ name: "translate.js" }],
        },
        {
          name: "router",
          children: [{ name: "index.js" }],
        },
        {
          name: "store",
          children: [{ name: "index.js" }],
        },
        {
          name: "assets",
          children: [
            { name: "images", children: [] },
            { name: "styles", children: [] },
          ],
        },
        {
          name: "tests",
          children: [{ name: "...", comment: "test files" }],
        },
        { name: "App.vue" },
        { name: "main.js" },
      ],
    },
  ]}
/>

### Pros and Cons

<div class="overflow-x-auto">
  <table class="custom-table">
    <thead>
      <tr>
        <th>✅ Pros</th>
        <th>❌ Cons</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>Highly scalable</td>
        <td>Can introduce overhead in managing layers</td>
      </tr>
      <tr>
        <td>Organized component hierarchy</td>
        <td>Initial complexity in setting up</td>
      </tr>
      <tr>
        <td>Reusable components</td>
        <td>Might be overkill for smaller projects</td>
      </tr>
      <tr>
        <td>Improves collaboration among teams</td>
        <td></td>
      </tr>
    </tbody>
  </table>
</div>

<Aside type="info" title="Want to Learn More About Atomic Design?">
  Check out my detailed blog post on [Atomic Design in Vue and
  Nuxt](../atomic-design-vue-or-nuxt).
</Aside>

---

## 3. Modular Approach: Feature-Based Organization

As your project scales, consider a **Modular Monolithic Architecture**. This structure encapsulates each feature or domain, enhancing maintainability and preparing for potential evolution towards microservices.

<FileTree
  tree={[
    {
      name: "src",
      open: true,
      children: [
        {
          name: "core",
          open: true,
          children: [
            {
              name: "components",
              children: [{ name: "BaseButton.vue" }, { name: "BaseIcon.vue" }],
            },
            { name: "models", children: [] },
            { name: "store", children: [] },
            { name: "services", children: [] },
            {
              name: "views",
              children: [
                { name: "DefaultLayout.vue" },
                { name: "AdminLayout.vue" },
              ],
            },
            {
              name: "utils",
              children: [{ name: "validators.js" }],
            },
          ],
        },
        {
          name: "modules",
          open: true,
          children: [
            {
              name: "pokemon",
              open: true,
              children: [
                {
                  name: "components",
                  children: [
                    { name: "PokemonThumbnail.vue" },
                    { name: "PokemonCard.vue" },
                    { name: "PokemonListTemplate.vue" },
                    { name: "PokemonDetailTemplate.vue" },
                  ],
                },
                { name: "models", children: [] },
                {
                  name: "store",
                  children: [{ name: "pokemonStore.js" }],
                },
                { name: "services", children: [] },
                {
                  name: "views",
                  children: [{ name: "PokemonDetailPage.vue" }],
                },
                {
                  name: "tests",
                  children: [{ name: "pokemonTests.spec.js" }],
                },
              ],
            },
            {
              name: "search",
              open: false,
              children: [
                {
                  name: "components",
                  children: [{ name: "SearchInput.vue" }],
                },
                { name: "models", children: [] },
                {
                  name: "store",
                  children: [{ name: "searchStore.js" }],
                },
                { name: "services", children: [] },
                { name: "views", children: [] },
                {
                  name: "tests",
                  children: [{ name: "searchTests.spec.js" }],
                },
              ],
            },
          ],
        },
        {
          name: "assets",
          children: [
            { name: "images", children: [] },
            { name: "styles", children: [] },
          ],
        },
        { name: "scss", children: [] },
        { name: "App.vue" },
        { name: "main.ts" },
        { name: "router.ts" },
        { name: "store.ts" },
        {
          name: "tests",
          children: [{ name: "...", comment: "test files" }],
        },
        {
          name: "plugins",
          children: [{ name: "translate.js" }],
        },
      ],
    },
  ]}
/>

### Alternative: Simplified Flat Feature Structure

A common pain point in larger projects is excessive folder nesting, which can make navigation and file discovery more difficult. Here's a simplified, flat feature structure that prioritizes IDE-friendly navigation and reduces cognitive load:

<FileTree
  tree={[
    {
      name: "features",
      open: true,
      children: [
        {
          name: "project",
          open: true,
          children: [
            { name: "project.composable.ts" },
            { name: "project.data.ts" },
            { name: "project.store.ts" },
            { name: "project.types.ts" },
            { name: "project.utils.ts" },
            { name: "project.utils.test.ts" },
            { name: "ProjectList.vue" },
            { name: "ProjectItem.vue" },
          ],
        },
      ],
    },
  ]}
/>

This structure offers key advantages:

- **Quick Navigation**: Using IDE features like "Quick Open" (Ctrl/Cmd + P), you can find any project-related file by typing "project..."
- **Reduced Nesting**: All feature-related files are at the same level, eliminating deep folder hierarchies
- **Clear Ownership**: Each file's name indicates its purpose
- **Pattern Recognition**: Consistent naming makes it simple to understand each file's role
- **Test Colocation**: Tests live right next to the code they're testing

---

## 4. Feature-Sliced Design: For Complex Applications

**Feature-Sliced Design** is ideal for big, long-term projects. This approach breaks the application into different layers, each with a specific role.

![Feature-Sliced Design Diagram](../../assets/images/how-to-structure-vue/feature-sliced.png)

### Layers of Feature-Sliced Design

- **App:** Global settings, styles, and providers.
- **Processes:** Global business processes, like user authentication flows.
- **Pages:** Full pages built using entities, features, and widgets.
- **Widgets:** Combines entities and features into cohesive UI blocks.
- **Features:** Handles user interactions that add value.
- **Entities:** Represents core business models.
- **Shared:** Reusable utilities and components unrelated to specific business logic.

<FileTree
  tree={[
    {
      name: "src",
      open: true,
      children: [
        {
          name: "app",
          open: true,
          children: [
            { name: "App.vue" },
            { name: "main.js" },
            { name: "app.scss" },
          ],
        },
        { name: "processes", children: [] },
        {
          name: "pages",
          children: [{ name: "Home.vue" }, { name: "PokemonDetailPage.vue" }],
        },
        {
          name: "widgets",
          children: [
            { name: "UserProfile.vue" },
            { name: "PokemonStatsWidget.vue" },
          ],
        },
        {
          name: "features",
          open: true,
          children: [
            {
              name: "pokemon",
              children: [
                { name: "CatchPokemon.vue" },
                { name: "PokemonList.vue" },
              ],
            },
            {
              name: "user",
              children: [{ name: "Login.vue" }, { name: "Register.vue" }],
            },
          ],
        },
        {
          name: "entities",
          open: true,
          children: [
            {
              name: "user",
              children: [{ name: "userService.js" }, { name: "userModel.js" }],
            },
            {
              name: "pokemon",
              children: [
                { name: "pokemonService.js" },
                { name: "pokemonModel.js" },
              ],
            },
          ],
        },
        {
          name: "shared",
          open: true,
          children: [
            {
              name: "ui",
              children: [
                { name: "BaseButton.vue" },
                { name: "BaseInput.vue" },
                { name: "Loader.vue" },
              ],
            },
            {
              name: "lib",
              children: [{ name: "api.js" }, { name: "helpers.js" }],
            },
          ],
        },
        {
          name: "assets",
          children: [
            { name: "images", children: [] },
            { name: "styles", children: [] },
          ],
        },
        {
          name: "router",
          children: [{ name: "index.js" }],
        },
        {
          name: "store",
          children: [{ name: "index.js" }],
        },
        {
          name: "tests",
          children: [{ name: "featureTests.spec.js" }],
        },
      ],
    },
  ]}
/>

### Pros and Cons

<div class="overflow-x-auto">
  <table class="custom-table">
    <thead>
      <tr>
        <th>✅ Pros</th>
        <th>❌ Cons</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>High cohesion and clear separation</td>
        <td>Initial complexity in understanding the layers</td>
      </tr>
      <tr>
        <td>Scalable and maintainable</td>
        <td>Requires thorough planning</td>
      </tr>
      <tr>
        <td>Facilitates team collaboration</td>
        <td>Needs consistent enforcement of conventions</td>
      </tr>
    </tbody>
  </table>
</div>

<Aside type="tip" title="Learn More About Feature-Sliced Design">
  Visit the [official Feature-Sliced Design
  documentation](https://feature-sliced.design/) for an in-depth understanding.
</Aside>

---

## 5. Micro Frontends: Enterprise-Level Solution

**Micro frontends** apply the microservices concept to frontend development. Teams can work on distinct sections of a web app independently, enabling flexible development and deployment.

![Micro Frontend Diagram](../../assets/images/how-to-structure-vue/microfrontend.png)

### Key Components

- **Application Shell:** The main controller handling basic layout and routing, connecting all micro frontends.
- **Decomposed UIs:** Each micro frontend focuses on a specific part of the application using its own technology stack.

### Pros and Cons

<div class="overflow-x-auto">
  <table class="custom-table">
    <thead>
      <tr>
        <th>✅ Pros</th>
        <th>❌ Cons</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>Independent deployments</td>
        <td>High complexity in orchestration</td>
      </tr>
      <tr>
        <td>Scalability across large teams</td>
        <td>Requires robust infrastructure</td>
      </tr>
      <tr>
        <td>Technology-agnostic approach</td>
        <td>Potential inconsistencies in user experience</td>
      </tr>
    </tbody>
  </table>
</div>

<Aside type="caution" title="Note">
  Micro frontends are best suited for large, complex projects with multiple
  development teams. This approach can introduce significant complexity and is
  usually not necessary for small to medium-sized applications.
</Aside>

<Aside type="tip" title="Deep Dive into Microfrontends">
  Want to learn how to actually implement microfrontends with Vue? Check out my
  comprehensive guide: [How to build Microfrontends with Module Federation and
  Vue](../how-to-build-microfrontends-with-module-federation-and-vue) - includes
  working code, architectural decisions, and a complete reference project.
</Aside>

---

## Conclusion

![Conclusion](../../assets/images/how-to-structure-vue/conclusion.png)

Selecting the right project structure depends on your project's size, complexity, and team organization. The more complex your team or project is, the more you should aim for a structure that facilitates scalability and maintainability.

Your project's architecture should grow with your organization, providing a solid foundation for future development.

### Comparison Chart

<div class="overflow-x-auto">
  <table class="custom-table">
    <thead>
      <tr>
        <th>Approach</th>
        <th>Description</th>
        <th>✅ Pros</th>
        <th>❌ Cons</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>
          <strong>Flat Structure</strong>
        </td>
        <td>Simple structure for small projects</td>
        <td>Easy to implement</td>
        <td>Not scalable, can become cluttered</td>
      </tr>
      <tr>
        <td>
          <strong>Atomic Design</strong>
        </td>
        <td>Hierarchical component-based structure</td>
        <td>Scalable, organized, reusable components</td>
        <td>Overhead in managing layers, initial complexity</td>
      </tr>
      <tr>
        <td>
          <strong>Modular Approach</strong>
        </td>
        <td>Feature-based modular structure</td>
        <td>Scalable, encapsulated features</td>
        <td>Potential duplication, requires discipline</td>
      </tr>
      <tr>
        <td>
          <strong>Feature-Sliced Design</strong>
        </td>
        <td>Functional layers and slices for large projects</td>
        <td>High cohesion, clear separation</td>
        <td>Initial complexity, requires thorough planning</td>
      </tr>
      <tr>
        <td>
          <strong>Micro Frontends</strong>
        </td>
        <td>Independent deployments of frontend components</td>
        <td>Independent deployments, scalable</td>
        <td>High complexity, requires coordination between teams</td>
      </tr>
    </tbody>
  </table>
</div>

---

## General Rules and Best Practices

Before concluding, let's highlight some general rules you can apply to every structure. These guidelines are important for maintaining consistency and readability in your codebase.

### Base Component Names

Use a prefix for your UI components to distinguish them from other components.

**Bad:**

<FileTree
  tree={[
    {
      name: "components",
      open: true,
      children: [
        { name: "MyButton.vue" },
        { name: "VueTable.vue" },
        { name: "Icon.vue" },
      ],
    },
  ]}
/>

**Good:**

<FileTree
  tree={[
    {
      name: "components",
      open: true,
      children: [
        { name: "BaseButton.vue" },
        { name: "BaseTable.vue" },
        { name: "BaseIcon.vue" },
      ],
    },
  ]}
/>

### Related Component Names

Group related components together by naming them accordingly.

**Bad:**

<FileTree
  tree={[
    {
      name: "components",
      open: true,
      children: [
        { name: "TodoList.vue" },
        { name: "TodoItem.vue" },
        { name: "TodoButton.vue" },
      ],
    },
  ]}
/>

**Good:**

<FileTree
  tree={[
    {
      name: "components",
      open: true,
      children: [
        { name: "TodoList.vue" },
        { name: "TodoListItem.vue" },
        { name: "TodoListItemButton.vue" },
      ],
    },
  ]}
/>

### Order of Words in Component Names

Component names should start with the highest-level words and end with descriptive modifiers.

**Bad:**

<FileTree
  tree={[
    {
      name: "components",
      open: true,
      children: [
        { name: "ClearSearchButton.vue" },
        { name: "ExcludeFromSearchInput.vue" },
        { name: "LaunchOnStartupCheckbox.vue" },
      ],
    },
  ]}
/>

**Good:**

<FileTree
  tree={[
    {
      name: "components",
      open: true,
      children: [
        { name: "SearchButtonClear.vue" },
        { name: "SearchInputExclude.vue" },
        { name: "SettingsCheckboxLaunchOnStartup.vue" },
      ],
    },
  ]}
/>

### Organizing Tests

Decide whether to keep your tests in a separate folder or alongside your components. Both approaches are valid, but consistency is key.

#### Approach 1: Separate Test Folder

<FileTree
  tree={[
    {
      name: "vue-project",
      open: true,
      children: [
        {
          name: "src",
          open: true,
          children: [
            {
              name: "components",
              children: [{ name: "MyComponent.vue" }],
            },
            {
              name: "views",
              children: [{ name: "HomeView.vue" }],
            },
          ],
        },
        {
          name: "tests",
          open: true,
          children: [
            {
              name: "components",
              children: [{ name: "MyComponent.spec.js" }],
            },
            {
              name: "views",
              children: [{ name: "HomeView.spec.js" }],
            },
          ],
        },
      ],
    },
  ]}
/>

#### Approach 2: Inline Test Files

<FileTree
  tree={[
    {
      name: "vue-project",
      open: true,
      children: [
        {
          name: "src",
          open: true,
          children: [
            {
              name: "components",
              open: true,
              children: [
                { name: "MyComponent.vue" },
                { name: "MyComponent.spec.js" },
              ],
            },
            {
              name: "views",
              open: true,
              children: [
                { name: "HomeView.vue" },
                { name: "HomeView.spec.js" },
              ],
            },
          ],
        },
      ],
    },
  ]}
/>

---

## Additional Resources

- [Official Vue.js Style Guide](https://vuejs.org/style-guide/)
- [Micro Frontends - Extending Microservice Ideas to Frontend Development](https://micro-frontends.org/)
- [Martin Fowler on Micro Frontends](https://martinfowler.com/articles/micro-frontends.html)
- [Official Feature-Sliced Design Documentation](https://feature-sliced.design/)

---

---

--- title: How to Persist User Data with LocalStorage in Vue description: Learn how to efficiently store and manage user preferences like dark mode in Vue applications using LocalStorage. This guide covers basic operations, addresses common challenges, and provides type-safe solutions for robust development. tags: ['vue'] url: https://alexop.dev/posts/how-to-persist-user-data-with-localstorage-in-vue ---

# How to Persist User Data with LocalStorage in Vue



## Introduction

When developing apps, there's often a need to store data. Consider a simple scenario where your application features a dark mode, and users want to save their preferred setting. Most users might prefer dark mode, but some will want light mode. This raises the question: where should we store this preference? We could use an API with a backend to store the setting. For configurations that affect the client's experience, persisting this data locally makes more sense. LocalStorage offers a straightforward solution. In this blog post, I'll guide you through using LocalStorage in Vue and show you how to handle this data in an elegant and type-safe manner.

## Understanding LocalStorage

LocalStorage is a web storage API that lets JavaScript sites store and access data directly in the browser indefinitely. This data remains saved across browser sessions. LocalStorage is straightforward, using a key-value store model where both the key and the value are strings.

Here's how you can use LocalStorage:

- To **store** data: `localStorage.setItem('myKey', 'myValue')`
- To **retrieve** data: `localStorage.getItem('myKey')`
- To **remove** an item: `localStorage.removeItem('myKey')`
- To **clear** all storage: `localStorage.clear()`

![Diagram that explains LocalStorage](../../assets/images/localstorage-vue/diagram.png)

## Using LocalStorage for Dark Mode Settings

In Vue, you can use LocalStorage to save a user's preference for dark mode in a component.

![Picture that shows a button where user can toggle dark mode](../../assets/images/localstorage-vue/picture-dark-mode.png)

```vue
<template>
  <button class="dark-mode-toggle" @click="toggleDarkMode">
    {{ isDarkMode ? "Switch to Light Mode" : "Switch to Dark Mode" }}
    
  </button>
</template>

<script setup lang="ts">
const isDarkMode = ref(JSON.parse(localStorage.getItem("darkMode") ?? "false"));

const styleProperties = computed(() => ({
  "--background-color": isDarkMode.value ? "#333" : "#FFF",
  "--text-color": isDarkMode.value ? "#FFF" : "#333",
}));

const sunIcon = `<svg some svg </svg>`;

const moonIcon = `<svg some svg </svg>`;

function applyStyles() {
  for (const [key, value] of Object.entries(styleProperties.value)) {
    document.documentElement.style.setProperty(key, value);
  }
}

function toggleDarkMode() {
  isDarkMode.value = !isDarkMode.value;
  localStorage.setItem("darkMode", JSON.stringify(isDarkMode.value));
  applyStyles();
}

// On component mount, apply the stored or default styles
onMounted(applyStyles);
</script>

<style scoped>
.dark-mode-toggle {
  display: flex;
  align-items: center;
  justify-content: space-between;
  padding: 10px 20px;
  font-size: 16px;
  color: var(--text-color);
  background-color: var(--background-color);
  border: 1px solid var(--text-color);
  border-radius: 5px;
  cursor: pointer;
}

.icon {
  display: inline-block;
  margin-left: 10px;
}

:root {
  --background-color: #fff;
  --text-color: #333;
}

body {
  background-color: var(--background-color);
  color: var(--text-color);
  transition:
    background-color 0.3s,
    color 0.3s;
}
</style>
```

## Addressing Issues with Initial Implementation

The basic approach works well for simple cases, but larger applications face these key challenges:

1. **Type Safety and Key Validation**: Always check and handle data from LocalStorage to prevent errors.
2. **Decoupling from LocalStorage**: Avoid direct LocalStorage interactions in your components. Instead, use a utility service or state management for better code maintenance and testing.
3. **Error Handling**: Manage exceptions like browser restrictions or storage limits properly as LocalStorage operations can fail.
4. **Synchronization Across Components**: Use event-driven communication or shared state to keep all components updated with changes.
5. **Serialization Constraints**: LocalStorage stores data as strings, making serialization and deserialization challenging with complex data types.

## Solutions and Best Practices for LocalStorage

To overcome these challenges, consider these solutions:

- **Type Definitions**: Use TypeScript to enforce type safety and help with autocompletion.

```ts
// types/localStorageTypes.ts
export type UserSettings = { name: string };

export type LocalStorageValues = {
  darkMode: boolean;
  userSettings: UserSettings;
  lastLogin: Date;
};

export type LocalStorageKeys = keyof LocalStorageValues;
```

- **Utility Classes**: Create a utility class to manage all LocalStorage operations.

```ts
// utils/LocalStorageHandler.ts
// export class LocalStorageHandler {
  static getItem<K extends LocalStorageKeys>(
    key: K
  ): LocalStorageValues[K] | null {
    try {
      const item = localStorage.getItem(key);
      return item ? (JSON.parse(item) as LocalStorageValues[K]) : null;
    } catch (error) {
      console.error(`Error retrieving item from localStorage: ${error}`);
      return null;
    }
  }

  static setItem<K extends LocalStorageKeys>(
    key: K,
    value: LocalStorageValues[K]
  ): void {
    try {
      const item = JSON.stringify(value);
      localStorage.setItem(key, item);
    } catch (error) {
      console.error(`Error setting item in localStorage: ${error}`);
    }
  }

  static removeItem(key: LocalStorageKeys): void {
    localStorage.removeItem(key);
  }

  static clear(): void {
    localStorage.clear();
  }
}
```

- **Composables**: Extract logic into Vue composables for better reusability and maintainability

```ts
// composables/useDarkMode.ts
export function useDarkMode() {
  const isDarkMode = ref(LocalStorageHandler.getItem("darkMode") ?? false);

  watch(isDarkMode, newValue => {
    LocalStorageHandler.setItem("darkMode", newValue);
  });

  return { isDarkMode };
}
```

![Diagram that shows how component and localStorage work together](../../assets/images/localstorage-vue/diagram-local-storage-and-component.png)

You can check the full refactored example out here

[Play with Vue on Vue Playground](https://play.vuejs.org/#eNq9WG1v20YS/itz6gGSAXFFUu88O7m0lyBpnKY49/qlKhCaXEmMKS6xXEqWff7vfXZJSiSluAkKVLEYcnZenpmdnRnqsfMqTdk25x2vc6n4Jo19xV8sEqLL21wpkVAQ+1l2teiEvryzNiLklhKrVcwXHfp3EEfBHdYKyn/A8QEMi45RQPT4SFFWUekldW92kQrWpARdR6u1Ik3vkldf0Owl/empUHOZpf4RRxSIBLa31lptYv1ct7ARInkHBujMcnMH1kHhz6BwCA+Xg5qneMwCGaWKMq7ylGI/WWmXMuNGtEmFVPRIgdikueJhn0TyQeQJbumJllJsqIvwdWuseXYIxYGFDWrU7r+0WYDLNHvNgSe6qkv3Lo58mdrH/GcpUi5VxDMwVoh6vQu6ekG9R+1l17Ju/eBuJQExtAIRC9n1aibY1o9zsxffDYdDE/vv3rx50+2Xworfq+fFNLcR0/KL5OmiDrKIOcB9usy2K7rfxInes7VSqTcY7HY7thsyIVcD17btAViwPbsoVGswuSM8rLlOjOppGcV6i4NcSp6oHzQsUKtMuI3oNrJgU6dDxHffi3tQbbLJmeCvTMPL1FdrCrHyYUYjNnL8IRvPyVzAiX82TZkzKyglWS/YliY/QMrx2ZiNS7K+3TpsXKNZYP4VpFc1Nkg9bHDjfoXs1mrSwGex8cNmYk3a0usWJ75vnVFTYyltOS7ZdUguzd62pC3n7QnAh82cDecTGjPHbtqf2jOyY4fZCC8u1RpiaOk1/Y3hij0xl6YhvfjwYcic0QRBno1Hp5qvR2zujGB3fFb1dSEMZycNzKVuoNZa5sydN10qdCNIGjYSoG7523C3pfE9yp4NibmYiJ2oLnA9LDq6PF3qs/Di0/EkHQrZ33mUtNGvPUs66YbkOAh3wGY28piNXBcb61oIFoLqTF1rxCbOyGKT6VxnuAnCfDSxXDaezsA2moxxPx/W9gsBH09mzJ06r8bMdofIBn01SzTH7k7HATAx22HD6Qg38yGbT4fksok7q6lBJk+mUGPSaTgrr8XSiLnjKQzbE/hwtOtOptiu+emOLPMkUBH2wk/TeH+jC3FGKLqm4C6FpF6xZ7/d8X2fTKX8ncSSPt5+5oFiCLdExe61KnhRUi9KNUShCPINeFl18zrm5tnIMTSnUnbfO9pB7SVCm8RfDWezHR+gnpTzK/pHm6b5YhH48Y0S0l8Zu+/QLXtd3f9N8+rTjzcffwIsGSWraLnvtXXojkD1YOk+ZhAOBvQRnRyNSyRwDVmORtovWEmtObqckGisiGnIl34el30vWySHrturKYZe7JPp3mUn12TKAgQqBIW1h5YiEGGUofvvPVrG/B69GGDjaJVYERzNPAoAjUtD/5xnCi6iI4KUKEwVqR9w65arHeeJYUn9MEQgPHLs9J5cXAx5CQkrix44FiYlzfRVDzsne/VOe2EW22274mvTS24hQw4eBzYzEUfhl7QaPkv6YZTDtXGFJJeZNpGKqPTV7A/Tw1UrRlESRwlcRlbcGdmNL1dRYsV8iXhopytpTwqBgUbznML2SE8ORkEdJciYIyoNtyLcFwq+LRrPBlZJP8kifTC8E7Vks2HWL+TNfYEESaUTCRnU6WMSRFCW0Yp9zkSCMdngQyVFFkcxlx9TrRrToled5EXHj2Ox+9HQlMy5Ga6MzJoHd2fon7N7TVt0fpY843KLEfqwphBurorl1zc/wbnaIlI716P4M4v/5ciPXGMs2L6H84Bd4zNo35npFYn8S/b6HrmeVU5poKbKGP5FB8PuD8+4foSL+l5VJ0TxulZUftmnqH8qQzD5vRmaFSj0P7h+w5UGoefbx8Tf4PQUdcakR525ru9XXXWMSFlKy3KE/RYi5n5SuorR+mDAa5grGdAN1bVAdnt4D1F6f561+57vtVWUY1T7U0Atr9/6JvCF34eXhba+/jnPjm8RJ2Es3iVKhKadNxSURqvIZMpXUUDYIV3UL98TMoYnYVNGw3ihm4xH7y+8M3h+e/87/Z+SPI4rvfqjZHl2j5+iL+qyijA12kqJQFspTunxI/EaJpNC6mXRa1JfZrynKRfkN8EeEXkGUU3ZEwW+fqvscSlRDM6BQ3Yws9r79Fr/p42jWW+REwUAE/c6co/++Wgknj59AXgbRXFrEqm2BWVf/YotKFv9FzYCG7QVKP/fsBGt9l307JYvZ2cAM3eYXfiLUYZCfewKQFHyNQH+Qhgl34gtr9A1Y6SDeCY8Ddea8pXBtpUARUT2/kxXyXXUoete7XW+dfIlX/ZpZ2JX/yEB4meLQ3WSz9eCcrVRDQ7zYOMnhQp+mRLHHx+uNKLeuYpVHdbjDHhBL1/S0o8zkziFQuNKbRjsUy/hO5Oo5geKWtjOGTk3aB7kq5gerZWHrfnzie7enac/AMi2358=)

## Conclusion

This post explained the effective use of LocalStorage in Vue to manage user settings such as dark mode. We covered its basic operations, addressed common issues, and provided solutions to ensure robust and efficient application development. With these strategies, developers can create more responsive applications that effectively meet user needs.

---

--- title: How to Write Clean Vue Components description: There are many ways to write better Vue components. One of my favorite ways is to separate business logic into pure functions. tags: ['vue', 'architecture'] url: https://alexop.dev/posts/how-to-write-clean-vue-components ---

# How to Write Clean Vue Components



## Table of Contents

## Introduction

Writing code that's both easy to test and easy to read can be a challenge, with Vue components. In this blog post, I'm going to share a design idea that will make your Vue components better. This method won't speed up your code, but it will make it simpler to test and understand. Think of it as a big-picture way to improve your Vue coding style. It's going to make your life easier when you need to fix or update your components.

Whether you're new to Vue or have been using it for some time, this tip will help you make your Vue components cleaner and more straightforward.

---

## Understanding Vue Components

A Vue component is like a reusable puzzle piece in your app. It has three main parts:

1. **View**: This is the template section where you design the user interface.
2. **Reactivity**: Here, Vue's features like `ref` make the interface interactive.
3. **Business Logic**: This is where you process data or manage user actions.

![Architecture](../../assets/images/how-to-write-clean-vue-components/architecture.png)

---

## Case Study: `snakeGame.vue`

Let's look at a common Vue component, `snakeGame.vue`. It mixes the view, reactivity, and business logic, which can make it complex and hard to work with.

### Code Sample: Traditional Approach

```vue
<template>
  <div class="game-container">
    <canvas ref="canvas" width="400" height="400"></canvas>
  </div>
</template>

<script setup lang="ts">
const canvas = ref<HTMLCanvasElement | null>(null);
const ctx = ref<CanvasRenderingContext2D | null>(null);
let snake = [{ x: 200, y: 200 }];
let direction = { x: 0, y: 0 };
let lastDirection = { x: 0, y: 0 };
let food = { x: 0, y: 0 };
const gridSize = 20;
let gameInterval: number | null = null;

onMounted(() => {
  if (canvas.value) {
    ctx.value = canvas.value.getContext("2d");
    resetFoodPosition();
    gameInterval = window.setInterval(gameLoop, 100);
  }
  window.addEventListener("keydown", handleKeydown);
});

onUnmounted(() => {
  if (gameInterval !== null) {
    window.clearInterval(gameInterval);
  }
  window.removeEventListener("keydown", handleKeydown);
});

function handleKeydown(e: KeyboardEvent) {
  e.preventDefault();
  switch (e.key) {
    case "ArrowUp":
      if (lastDirection.y !== 0) break;
      direction = { x: 0, y: -gridSize };
      break;
    case "ArrowDown":
      if (lastDirection.y !== 0) break;
      direction = { x: 0, y: gridSize };
      break;
    case "ArrowLeft":
      if (lastDirection.x !== 0) break;
      direction = { x: -gridSize, y: 0 };
      break;
    case "ArrowRight":
      if (lastDirection.x !== 0) break;
      direction = { x: gridSize, y: 0 };
      break;
  }
}

function gameLoop() {
  updateSnakePosition();
  if (checkCollision()) {
    endGame();
    return;
  }
  checkFoodCollision();
  draw();
  lastDirection = { ...direction };
}

function updateSnakePosition() {
  for (let i = snake.length - 2; i >= 0; i--) {
    snake[i + 1] = { ...snake[i] };
  }
  snake[0].x += direction.x;
  snake[0].y += direction.y;
}

function checkCollision() {
  return (
    snake[0].x < 0 ||
    snake[0].x >= 400 ||
    snake[0].y < 0 ||
    snake[0].y >= 400 ||
    snake
      .slice(1)
      .some(segment => segment.x === snake[0].x && segment.y === snake[0].y)
  );
}

function checkFoodCollision() {
  if (snake[0].x === food.x && snake[0].y === food.y) {
    snake.push({ ...snake[snake.length - 1] });
    resetFoodPosition();
  }
}

function resetFoodPosition() {
  food = {
    x: Math.floor(Math.random() * 20) * gridSize,
    y: Math.floor(Math.random() * 20) * gridSize,
  };
}

function draw() {
  if (!ctx.value) return;
  ctx.value.clearRect(0, 0, 400, 400);
  drawGrid();
  drawSnake();
  drawFood();
}

function drawGrid() {
  if (!ctx.value) return;
  ctx.value.strokeStyle = "#ddd";
  for (let i = 0; i <= 400; i += gridSize) {
    ctx.value.beginPath();
    ctx.value.moveTo(i, 0);
    ctx.value.lineTo(i, 400);
    ctx.value.stroke();
    ctx.value.moveTo(0, i);
    ctx.value.lineTo(400, i);
    ctx.value.stroke();
  }
}

function drawSnake() {
  if (!ctx.value) return;
  ctx.value.fillStyle = "green";
  snake.forEach(segment => {
    ctx.value?.fillRect(segment.x, segment.y, gridSize, gridSize);
  });
}

function drawFood() {
  if (!ctx.value) return;
  ctx.value.fillStyle = "red";
  ctx.value.fillRect(food.x, food.y, gridSize, gridSize);
}

function endGame() {
  if (gameInterval !== null) {
    window.clearInterval(gameInterval);
  }
  alert("Game Over");
}
</script>

<style>
.game-container {
  display: flex;
  justify-content: center;
  align-items: center;
  height: 100vh;
}
</style>
```

### Screenshot from the game

![Snake Game Screenshot](./../../assets/images/how-to-write-clean-vue-components/snakeGameImage.png)

### Challenges with the Traditional Approach

When you mix the view, reactivity, and business logic all in one file, the component becomes bulky and hard to maintain. Unit tests become more complex, requiring integration tests for comprehensive coverage.

---

## Introducing the Functional Core, Imperative Shell Pattern

To solve these problems in Vue, we use the "Functional Core, Imperative Shell" pattern. This pattern is key in software architecture and helps you structure your code better:

> **Functional Core, Imperative Shell Pattern**: In this design, the main logic of your app (the 'Functional Core') stays pure and without side effects, making it testable. The 'Imperative Shell' handles the outside world, like the UI or databases, and talks to the pure core.

![Functional core Diagram](./../../assets/images/how-to-write-clean-vue-components/functional-core-diagram.png)

### What Are Pure Functions?

In this pattern, **pure functions** are at the heart of the 'Functional Core'. A pure function is a concept from functional programming, and it has two key characteristics:

1. **Predictability**: If you give a pure function the same inputs, it always gives back the same output.
2. **No Side Effects**: Pure functions don't change anything outside them. They don't alter external variables, call APIs, or do any input/output.

Pure functions simplify testing, debugging, and code comprehension. They form the foundation of the Functional Core, keeping your app's business logic clean and manageable.

---

### Applying the Pattern in Vue

In Vue, this pattern has two parts:

- **Imperative Shell** (`useGameSnake.ts`): This part handles the Vue-specific reactive bits. It's where your components interact with Vue, managing operations like state changes and events.
- **Functional Core** (`pureGameSnake.ts`): This is where your pure business logic lives. It's separate from Vue, which makes it easier to test and think about your app's main functions, independent of the UI.

---

### Implementing `pureGameSnake.ts`

The `pureGameSnake.ts` file encapsulates the game's business logic without any Vue-specific reactivity. This separation means easier testing and clearer logic.

```typescript
export const gridSize = 20;

interface Position {
  x: number;
  y: number;
}

type Snake = Position[];

export function initializeSnake(): Snake {
  return [{ x: 200, y: 200 }];
}

export function moveSnake(snake: Snake, direction: Position): Snake {
  return snake.map((segment, index) => {
    if (index === 0) {
      return { x: segment.x + direction.x, y: segment.y + direction.y };
    }
    return { ...snake[index - 1] };
  });
}

export function isCollision(snake: Snake): boolean {
  const head = snake[0];
  return (
    head.x < 0 ||
    head.x >= 400 ||
    head.y < 0 ||
    head.y >= 400 ||
    snake.slice(1).some(segment => segment.x === head.x && segment.y === head.y)
  );
}

export function randomFoodPosition(): Position {
  return {
    x: Math.floor(Math.random() * 20) * gridSize,
    y: Math.floor(Math.random() * 20) * gridSize,
  };
}

export function isFoodEaten(snake: Snake, food: Position): boolean {
  const head = snake[0];
  return head.x === food.x && head.y === food.y;
}
```

### Implementing `useGameSnake.ts`

In `useGameSnake.ts`, we manage the Vue-specific state and reactivity, leveraging the pure functions from `pureGameSnake.ts`.

```typescript
interface Position {
  x: number;
  y: number;
}

type Snake = Position[];

interface GameState {
  snake: Ref<Snake>;
  direction: Ref<Position>;
  food: Ref<Position>;
  gameState: Ref<"over" | "playing">;
}

export function useGameSnake(): GameState {
  const snake: Ref<Snake> = ref(GameLogic.initializeSnake());
  const direction: Ref<Position> = ref({ x: 0, y: 0 });
  const food: Ref<Position> = ref(GameLogic.randomFoodPosition());
  const gameState: Ref<"over" | "playing"> = ref("playing");
  let gameInterval: number | null = null;

  const startGame = (): void => {
    gameInterval = window.setInterval(() => {
      snake.value = GameLogic.moveSnake(snake.value, direction.value);

      if (GameLogic.isCollision(snake.value)) {
        gameState.value = "over";
        if (gameInterval !== null) {
          clearInterval(gameInterval);
        }
      } else if (GameLogic.isFoodEaten(snake.value, food.value)) {
        snake.value.push({ ...snake.value[snake.value.length - 1] });
        food.value = GameLogic.randomFoodPosition();
      }
    }, 100);
  };

  onMounted(startGame);

  onUnmounted(() => {
    if (gameInterval !== null) {
      clearInterval(gameInterval);
    }
  });

  return { snake, direction, food, gameState };
}
```

### Refactoring `gameSnake.vue`

Now, our `gameSnake.vue` is more focused, using `useGameSnake.ts` for managing state and reactivity, while the view remains within the template.

```vue
<template>
  <div class="game-container">
    <canvas ref="canvas" width="400" height="400"></canvas>
  </div>
</template>

<script setup lang="ts">
const { snake, direction, food, gameState } = useGameSnake();
const canvas = ref<HTMLCanvasElement | null>(null);
const ctx = ref<CanvasRenderingContext2D | null>(null);
let lastDirection = { x: 0, y: 0 };

onMounted(() => {
  if (canvas.value) {
    ctx.value = canvas.value.getContext("2d");
    draw();
  }
  window.addEventListener("keydown", handleKeydown);
});

onUnmounted(() => {
  window.removeEventListener("keydown", handleKeydown);
});

watch(gameState, state => {
  if (state === "over") {
    alert("Game Over");
  }
});

function handleKeydown(e: KeyboardEvent) {
  e.preventDefault();
  switch (e.key) {
    case "ArrowUp":
      if (lastDirection.y !== 0) break;
      direction.value = { x: 0, y: -gridSize };
      break;
    case "ArrowDown":
      if (lastDirection.y !== 0) break;
      direction.value = { x: 0, y: gridSize };
      break;
    case "ArrowLeft":
      if (lastDirection.x !== 0) break;
      direction.value = { x: -gridSize, y: 0 };
      break;
    case "ArrowRight":
      if (lastDirection.x !== 0) break;
      direction.value = { x: gridSize, y: 0 };
      break;
  }
  lastDirection = { ...direction.value };
}

watch(
  [snake, food],
  () => {
    draw();
  },
  { deep: true }
);

function draw() {
  if (!ctx.value) return;
  ctx.value.clearRect(0, 0, 400, 400);
  drawGrid();
  drawSnake();
  drawFood();
}

function drawGrid() {
  if (!ctx.value) return;
  ctx.value.strokeStyle = "#ddd";
  for (let i = 0; i <= 400; i += gridSize) {
    ctx.value.beginPath();
    ctx.value.moveTo(i, 0);
    ctx.value.lineTo(i, 400);
    ctx.value.stroke();
    ctx.value.moveTo(0, i);
    ctx.value.lineTo(400, i);
    ctx.value.stroke();
  }
}

function drawSnake() {
  ctx.value.fillStyle = "green";
  snake.value.forEach(segment => {
    ctx.value.fillRect(segment.x, segment.y, gridSize, gridSize);
  });
}

function drawFood() {
  ctx.value.fillStyle = "red";
  ctx.value.fillRect(food.value.x, food.value.y, gridSize, gridSize);
}
</script>

<style>
.game-container {
  display: flex;
  justify-content: center;
  align-items: center;
  height: 100vh;
}
</style>
```

---

## Advantages of the Functional Core, Imperative Shell Pattern

The Functional Core, Imperative Shell pattern enhances the **testability** and **maintainability** of Vue components. By separating the business logic from the framework-specific code, this pattern offers key advantages:

### Simplified Testing

Business logic combined with Vue's reactivity and component structure makes testing complex. Traditional unit testing becomes challenging, leading to integration tests that lack precision. By extracting the core logic into pure functions (as in `pureGameSnake.ts`), we write focused unit tests for each function. This isolation streamlines testing, as each piece of logic operates independently of Vue's reactivity system.

### Enhanced Maintainability

The Functional Core, Imperative Shell pattern creates a clear **separation of concerns**. Vue components focus on the user interface and reactivity, while the pure business logic lives in separate, framework-agnostic files. This separation improves code readability and understanding. Maintenance becomes straightforward as the application grows.

### Framework Agnosticism

A key advantage of this pattern is the **portability** of your business logic. The pure functions in the Functional Core remain independent of any UI framework. If you need to switch from Vue to another framework, or if Vue changes, your core logic remains intact. This flexibility protects your code against changes and shifts in technology.

## Testing Complexities in Traditional Vue Components vs. Functional Core, Imperative Shell Pattern

### Challenges in Testing Traditional Components

Testing traditional Vue components, where view, reactivity, and business logic combine, presents specific challenges. In such components, unit tests face these obstacles:

- Tests function more like integration tests, reducing precision
- Vue's reactivity system creates complex mocking requirements
- Test coverage must span reactive behavior and side effects

These challenges reduce confidence in tests and component stability.

### Simplified Testing with Functional Core, Imperative Shell Pattern

The Functional Core, Imperative Shell pattern transforms testing:

- **Isolated Business Logic**: Pure functions in the Functional Core enable direct unit tests without Vue's reactivity or component states.
- **Predictable Outcomes**: Pure functions deliver consistent outputs for given inputs.
- **Clear Separation**: The reactive and side-effect code stays in the Imperative Shell, enabling focused testing of Vue interactions.

This approach creates a modular, testable codebase where each component undergoes thorough testing, improving reliability.

---

### Conclusion

The Functional Core, Imperative Shell pattern strengthens Vue applications through improved testing and maintenance. It prepares your code for future changes and growth. While restructuring requires initial effort, the pattern delivers long-term benefits, making it valuable for Vue developers aiming to enhance their application's architecture and quality.

![Blog Conclusion Diagram](./../../assets/images/how-to-write-clean-vue-components/conclusionDiagram.png)

---

--- title: The Problem with as in TypeScript: Why It's a Shortcut We Should Avoid description: Learn why as can be a Problem in Typescript tags: ['typescript'] url: https://alexop.dev/posts/the-problem-with-as-in-typescript-why-its-a-shortcut-we-should-avoid ---

# The Problem with as in TypeScript: Why It's a Shortcut We Should Avoid



### Introduction: Understanding TypeScript and Its Challenges

TypeScript enhances JavaScript by adding stricter typing rules. While JavaScript's flexibility enables rapid development, it can also lead to runtime errors such as "undefined is not a function" or type mismatches. TypeScript aims to catch these errors during development.

The as keyword in TypeScript creates specific challenges with type assertions. It allows developers to override TypeScript's type checking, reintroducing the errors TypeScript aims to prevent. When developers assert an any type with a specific interface, runtime errors occur if the object doesn't match the interface. In codebases, frequent use of as indicates underlying design issues or incomplete type definitions.

The article will examine the pitfalls of overusing as and provide guidelines for more effective TypeScript development, helping developers leverage TypeScript's strengths while avoiding its potential drawbacks. Readers will explore alternatives to as, such as type guards and generics, and learn when type assertions make sense.

### Easy Introduction to TypeScript's `as` Keyword

TypeScript is a special version of JavaScript. It adds rules to make coding less error-prone and clearer. But there's a part of TypeScript, called the `as` keyword, that's tricky. In this article, I'll talk about why `as` can be a problem.

#### What is `as` in TypeScript?

`as` in TypeScript changes data types. For example:

```typescript twoslash
let unknownInput: unknown = "Hello, TypeScript!";
let asString = unknownInput as string;
//  ^?
```

#### The Problem with `as`

The best thing about TypeScript is that it finds mistakes in your code before you even run it. But when you use `as`, you can skip these checks. It's like telling the computer, "I'm sure this is right," even if we might be wrong.

Using `as` too much is risky. It can cause errors in parts of your code where TypeScript could have helped. Imagine driving with a blindfold; that's what it's like.

#### Why Using `as` Can Be Bad

- **Skipping Checks**: TypeScript is great because it checks your code. Using `as` means you skip these helpful checks.
- **Making Code Unclear**: When you use `as`, it can make your code hard to understand. Others (or even you later) might not know why you used `as`.
- **Errors Happen**: If you use `as` wrong, your program will crash.

#### Better Ways Than `as`

- **Type Guards**: TypeScript has type guards. They help you check types.

```typescript twoslash
// Let's declare a variable of unknown type
let unknownInput: unknown;

// Now we'll use a type guard with typeof
if (typeof unknownInput === "string") {
  // TypeScript now knows unknownInput is a string
  console.log(unknownInput.toUpperCase());
} else {
  // Here, TypeScript still considers it unknown
  console.log(unknownInput);
}
```

- **Better Type Definitions**: Developers reach for `as` because of incomplete type definitions. Improving type definitions eliminates this need.
- **Your Own Type Guards**: For complicated types, you can make your own checks.

```typescript

// Define our type guard function
function isValidString(unknownInput: unknown): unknownInput is string {
  return typeof unknownInput === "string" && unknownInput.trim().length > 0;
}

// Example usage
const someInput: unknown = "Hello, World!";
const emptyInput: unknown = "";
const numberInput: unknown = 42;

if (isValidString(someInput)) {
  console.log(someInput.toUpperCase());
} else {
  console.log("Input is not a valid string");
}

if (isValidString(emptyInput)) {
  console.log("This won't be reached");
} else {
  console.log("Empty input is not a valid string");
}

if (isValidString(numberInput)) {
  console.log("This won't be reached");
} else {
  console.log("Number input is not a valid string");
}

// Hover over `result` to see the inferred type
const result = [someInput, emptyInput, numberInput].filter(isValidString);
//    ^?
```

### Cases Where Using `as` is Okay

The `as` keyword fits specific situations:

1. **Integrating with Non-Typed Code**: When working with JavaScript libraries or external APIs without types, `as` helps assign types to external data. Type guards remain the better choice, offering more robust type checking that aligns with TypeScript's goals.

2. **Casting in Tests**: In unit tests, when mocking or setting up test data, `as` helps shape data into the required form.

In these situations, verify that `as` solves a genuine need rather than masking improper type handling.

![Diagram as typescript inference](../../assets/images/asTypescript.png)

#### Conclusion

`as` serves a purpose in TypeScript, but better alternatives exist. By choosing proper type handling over shortcuts, we create clearer, more reliable code. Let's embrace TypeScript's strengths and write better code.

---

--- title: Exploring the Power of Square Brackets in TypeScript description: TypeScript, a statically-typed superset of JavaScript, implements square brackets [] for specific purposes. This post details the essential applications of square brackets in TypeScript, from array types to complex type manipulations, to help you write type-safe code. tags: ['typescript'] url: https://alexop.dev/posts/exploring-the-power-of-square-brackets-in-typescript ---

# Exploring the Power of Square Brackets in TypeScript



## Introduction

TypeScript, the popular statically-typed superset of JavaScript, offers advanced type manipulation features that enhance development with strong typing. Square brackets `[]` serve distinct purposes in TypeScript. This post details how square brackets work in TypeScript, from array types to indexed access types and beyond.

## 1. Defining Array Types

Square brackets in TypeScript define array types with precision.

```typescript
let numbers: number[] = [1, 2, 3];
let strings: Array<string> = ["hello", "world"];
```

This syntax specifies that `numbers` contains numbers, and `strings` contains strings.

## 2. Tuple Types

Square brackets define tuples - arrays with fixed lengths and specific types at each index.

```typescript
type Point = [number, number];
let coordinates: Point = [12.34, 56.78];
```

In this example, `Point` represents a 2D coordinate as a tuple.

## 3. The `length` Property

Every array in TypeScript includes a `length` property that the type system recognizes.

```typescript
type LengthArr<T extends Array<any>> = T["length"];

type foo = LengthArr<["1", "2"]>;
```

TypeScript recognizes `length` as the numeric size of the array.

## 4. Indexed Access Types

Square brackets access specific index or property types.

```typescript
type Point = [number, number];
type FirstElement = Point[0];
```

Here, `FirstElement` represents the first element in the `Point` tuple: `number`.

## 5. Creating Union Types from Tuples

Square brackets help create union types from tuples efficiently.

```typescript
type Statuses = ["active", "inactive", "pending"];
type CurrentStatus = Statuses[number];
```

`Statuses[number]` creates a union from all tuple elements.

## 6. Generic Array Types and Constraints

Square brackets define generic constraints and types.

```typescript
function logArrayElements<T extends any[]>(elements: T) {
  elements.forEach(element => console.log(element));
}
```

This function accepts any array type through the generic constraint `T`.

## 7. Mapped Types with Index Signatures

Square brackets in mapped types define index signatures to create dynamic property types.

```typescript
type StringMap<T> = { [key: string]: T };
let map: StringMap<number> = { a: 1, b: 2 };
```

`StringMap` creates a type with string keys and values of type `T`.

## 8. Advanced Tuple Manipulation

Square brackets enable precise tuple manipulation for extracting or omitting elements.

```typescript
type WithoutFirst<T extends any[]> = T extends [any, ...infer Rest] ? Rest : [];
type Tail = WithoutFirst<[1, 2, 3]>;
```

`WithoutFirst` removes the first element from a tuple.

### Conclusion

Square brackets in TypeScript provide essential functionality, from basic array definitions to complex type manipulations. These features make TypeScript code reliable and maintainable. The growing adoption of TypeScript demonstrates the practical benefits of its robust type system.

The [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/intro.html) provides comprehensive documentation of these features. [TypeHero](https://typehero.dev/) offers hands-on practice through interactive challenges to master TypeScript concepts, including square bracket techniques for type manipulation. These resources will strengthen your command of TypeScript and expand your programming capabilities.

---

--- title: How to Test Vue Composables: A Comprehensive Guide with Vitest description: Learn how to effectively test Vue composables using Vitest. Covers independent and dependent composables, with practical examples and best practices. tags: ['vue', 'testing'] url: https://alexop.dev/posts/how-to-test-vue-composables ---

# How to Test Vue Composables: A Comprehensive Guide with Vitest



## Introduction

Hello, everyone; in this blog post, I want to help you better understand how to test a composable in Vue. Nowadays, much of our business logic or UI logic is often encapsulated in composables, so I think it’s important to understand how to test them.

## Definitions

Before discussing the main topic, it’s important to understand some basic concepts regarding testing. This foundational knowledge will help clarify where testing Vue compostables fits into the broader landscape of software testing.

### Composables

**Composables** in Vue are reusable composition functions that encapsulate and manage reactive states and logic. They allow a flexible way to organize and reuse code across components, enhancing modularity and maintainability.

### Testing Pyramid

The **Testing Pyramid** is a conceptual metaphor that illustrates the ideal
balance of different types of testing. It recommends a large base of unit tests,
supplemented by a smaller set of integration tests and capped with an even
smaller set of end-to-end tests. This structure ensures efficient and effective
test coverage.

### Unit Testing and How Testing a Composable Would Be a Unit Test

**Unit testing** refers to the practice of testing individual units of code in isolation. In the context of Vue, testing a composable is a form of unit testing. It involves rigorously verifying the functionality of these isolated, reusable code blocks, ensuring they function correctly without external dependencies.

---

## Testing Composables

Composables in Vue are essentially functions, leveraging Vue's reactivity system. Given this unique nature, we can categorize composables into different types. On one hand, there are `Independent Composables`, which can be tested directly due to their standalone nature. On the other hand, we have `Dependent Composables`, which only function correctly when integrated within a component.In the sections that follow, I'll delve into these distinct types, provide examples for each, and guide you through effective testing strategies for both.

---

### Independent Composables

<ExcalidrawSVG
  src={independentComposable}
  alt="Independent Composables Diagram"
/>

An Independent Composable exclusively uses Vue's Reactivity APIs. These composables operate independently of Vue component instances, making them straightforward to test.

#### Example & Testing Strategy

Here is an example of an independent composable that calculates the sum of two reactive values:

```ts
function useSum(a: Ref<number>, b: Ref<number>): ComputedRef<number> {
  return computed(() => a.value + b.value);
}
```

To test this composable, you would directly invoke it and assert its returned state:

Test with Vitest:

```ts
describe("useSum", () => {
  it("correctly computes the sum of two numbers", () => {
    const num1 = ref(2);
    const num2 = ref(3);
    const sum = useSum(num1, num2);

    expect(sum.value).toBe(5);
  });
});
```

This test directly checks the functionality of useSum by passing reactive references and asserting the computed result.

---

### Dependent Composables

`Dependent Composables` are distinguished by their reliance on Vue's component instance. They often leverage features like lifecycle hooks or context for their operation. These composables are an integral part of a component and necessitate a distinct approach for testing, as opposed to Independent Composables.

#### Example & Usage

An exemplary Dependent Composable is `useLocalStorage`. This composable facilitates interaction with the browser's localStorage and harnesses the `onMounted` lifecycle hook for initialization:

```ts
function useLocalStorage<T>(key: string, initialValue: T) {
  const value = ref<T>(initialValue);

  function loadFromLocalStorage() {
    const storedValue = localStorage.getItem(key);
    if (storedValue !== null) {
      value.value = JSON.parse(storedValue);
    }
  }

  onMounted(loadFromLocalStorage);

  watch(value, newValue => {
    localStorage.setItem(key, JSON.stringify(newValue));
  });

  return { value };
}

export default useLocalStorage;
```

This composable can be utilised within a component, for instance, to create a persistent counter:

![Counter Ui](../../assets/images/how-to-test-vue-composables/counter-ui.png)

```vue
<script setup lang="ts">
// ... script content ...
</script>

<template>
  <div>
    <h1>Counter: {{ count }}</h1>
    <button @click="increment">Increment</button>
  </div>
</template>
```

The primary benefit here is the seamless synchronization of the reactive `count` property with localStorage, ensuring persistence across sessions.

### Testing Strategy

To effectively test `useLocalStorage`, especially considering the `onMounted` lifecycle, we initially face a challenge. Let's start with a basic test setup:

```ts
describe("useLocalStorage", () => {
  it("should load the initialValue", () => {
    const { value } = useLocalStorage("testKey", "initValue");
    expect(value.value).toBe("initValue");
  });

  it("should load from localStorage", async () => {
    localStorage.setItem("testKey", JSON.stringify("fromStorage"));
    const { value } = useLocalStorage("testKey", "initialValue");
    expect(value.value).toBe("fromStorage");
  });
});
```

Here, the first test will pass, asserting that the composable initialises with the given `initialValue`. However, the second test, which expects the composable to load a pre-existing value from localStorage, fails. The challenge arises because the `onMounted` lifecycle hook is not triggered during testing. To address this, we need to refactor our composable or our test setup to simulate the component mounting process.

---

### Enhancing Testing with the `withSetup` Helper Function

To facilitate easier testing of composables that rely on Vue's lifecycle hooks, we've developed a higher-order function named `withSetup`. This utility allows us to create a Vue component context programmatically, focusing primarily on the setup lifecycle function where composables are typically used.

#### Introduction to `withSetup`

`withSetup` is designed to simulate a Vue component's setup function, enabling us to test composables in an environment that closely mimics their real-world use. The function accepts a composable and returns both the composable's result and a Vue app instance. This setup allows for comprehensive testing, including lifecycle and reactivity features.

```ts
export function withSetup<T>(composable: () => T): [T, App] {
  let result: T;
  const app = createApp({
    setup() {
      result = composable();
      return () => {};
    },
  });
  app.mount(document.createElement("div"));
  return [result, app];
}
```

In this implementation, `withSetup` mounts a minimal Vue app and executes the provided composable function during the setup phase. This approach allows us to capture and return the composable's output alongside the app instance for further testing.

#### Utilizing `withSetup` in Tests

With `withSetup`, we can enhance our testing strategy for composables like `useLocalStorage`, ensuring they behave as expected even when they depend on lifecycle hooks:

```ts
it("should load the value from localStorage if it was set before", async () => {
  localStorage.setItem("testKey", JSON.stringify("valueFromLocalStorage"));
  const [result] = withSetup(() => useLocalStorage("testKey", "testValue"));
  expect(result.value.value).toBe("valueFromLocalStorage");
});
```

This test demonstrates how `withSetup` enables the composable to execute as if it were part of a regular Vue component, ensuring the `onMounted` lifecycle hook is triggered as expected. Additionally, the robust TypeScript support enhances the development experience by providing clear type inference and error checking.

---

### Testing Composables with Inject

Another common scenario is testing composables that rely on Vue's dependency injection system using `inject`. These composables present unique challenges as they expect certain values to be provided by ancestor components. Let's explore how to effectively test such composables.

#### Example Composable with Inject

Here's an example of a composable that uses inject:

```ts
export const MessageKey: InjectionKey<string> = Symbol("message");

export function useMessage() {
  const message = inject(MessageKey);

  if (!message) {
    throw new Error("Message must be provided");
  }

  const getUpperCase = () => message.toUpperCase();
  const getReversed = () => message.split("").reverse().join("");

  return {
    message,
    getUpperCase,
    getReversed,
  };
}
```

#### Creating a Test Helper

To test composables that use inject, we need a helper function that creates a testing environment with the necessary providers. Here's a utility function that makes this possible:

```ts
type InstanceType<V> = V extends { new (...arg: any[]): infer X } ? X : never;
type VM<V> = InstanceType<V> & { unmount: () => void };

interface InjectionConfig {
  key: InjectionKey<any> | string;
  value: any;
}

export function useInjectedSetup<TResult>(
  setup: () => TResult,
  injections: InjectionConfig[] = []
): TResult & { unmount: () => void } {
  let result!: TResult;

  const Comp = defineComponent({
    setup() {
      result = setup();
      return () => h("div");
    },
  });

  const Provider = defineComponent({
    setup() {
      injections.forEach(({ key, value }) => {
        provide(key, value);
      });
      return () => h(Comp);
    },
  });

  const mounted = mount(Provider);

  return {
    ...result,
    unmount: mounted.unmount,
  } as TResult & { unmount: () => void };
}

function mount<V>(Comp: V) {
  const el = document.createElement("div");
  const app = createApp(Comp as any);
  const unmount = () => app.unmount();
  const comp = app.mount(el) as any as VM<V>;
  comp.unmount = unmount;
  return comp;
}
```

#### Writing Tests

With our helper function in place, we can now write comprehensive tests for our inject-dependent composable:

```ts
describe("useMessage", () => {
  it("should handle injected message", () => {
    const wrapper = useInjectedSetup(
      () => useMessage(),
      [{ key: MessageKey, value: "hello world" }]
    );

    expect(wrapper.message).toBe("hello world");
    expect(wrapper.getUpperCase()).toBe("HELLO WORLD");
    expect(wrapper.getReversed()).toBe("dlrow olleh");

    wrapper.unmount();
  });

  it("should throw error when message is not provided", () => {
    expect(() => {
      useInjectedSetup(() => useMessage(), []);
    }).toThrow("Message must be provided");
  });
});
```

The `useInjectedSetup` helper creates a testing environment that:

1. Simulates a component hierarchy
2. Provides the necessary injection values
3. Executes the composable in a proper Vue context
4. Returns the composable's result along with an unmount function

This approach allows us to:

- Test composables that depend on inject
- Verify error handling when required injections are missing
- Test the full functionality of methods that use injected values
- Properly clean up after tests by unmounting the test component

Remember to always unmount the test component after each test to prevent memory leaks and ensure test isolation.

---

## Summary

| Independent Composables 🔓                                     | Dependent Composables 🔗                 |
| -------------------------------------------------------------- | ---------------------------------------- |
| - ✅ can be tested directly                                    | - 🧪 need a component to test            |
| - 🛠️ uses everything beside of lifecycles and provide / inject | - 🔄 uses Lifecycles or Provide / Inject |

In our exploration of testing Vue composables, we uncovered two distinct categories: **Independent Composables** and **Dependent Composables**. Independent Composables stand alone and can be tested akin to regular functions, showcasing straightforward testing procedures. Meanwhile, Dependent Composables, intricately tied to Vue's component system and lifecycle hooks, require a more nuanced approach. For these, we learned the effectiveness of utilizing a helper function, such as `withSetup`, to simulate a component context, enabling comprehensive testing.

I hope this blog post has been insightful and useful in enhancing your understanding of testing Vue composables. I'm also keen to learn about your experiences and methods in testing composables within your projects. Your insights and approaches could provide valuable perspectives and contribute to the broader Vue community's knowledge.

---

--- title: Robust Error Handling in TypeScript: A Journey from Naive to Rust-Inspired Solutions description: Learn to write robust, predictable TypeScript code using Rust's Result pattern. This post demonstrates practical examples and introduces the ts-results library, implementing Rust's powerful error management approach in TypeScript. tags: ['typescript'] url: https://alexop.dev/posts/robust-error-handling-in-typescript-a-journey-from-naive-to-rust-inspired-solutions ---

# Robust Error Handling in TypeScript: A Journey from Naive to Rust-Inspired Solutions



## Introduction

In software development, robust error handling forms the foundation of reliable software. Even the best-written code encounters unexpected challenges in production. This post explores how to enhance TypeScript error handling with Rust's Result pattern—creating more resilient and explicit error management.

## The Pitfalls of Overlooking Error Handling

Consider this TypeScript division function:

```typescript
const divide = (a: number, b: number) => a / b;
```

This function appears straightforward but fails when `b` is zero, returning `Infinity`. Such overlooked cases can lead to illogical outcomes:

```typescript
const divide = (a: number, b: number) => a / b;
// ---cut---
const calculateAverageSpeed = (distance: number, time: number) => {
  const averageSpeed = divide(distance, time);
  return `${averageSpeed} km/h`;
};

// will be "Infinity km/h"
console.log("Average Speed: ", calculateAverageSpeed(50, 0));
```

## Embracing Explicit Error Handling

TypeScript provides powerful error management techniques. The Rust-inspired approach enhances code safety and predictability.

### Result Type Pattern: A Rust-Inspired Approach in TypeScript

Rust excels at explicit error handling through the `Result` type. Here's the pattern in TypeScript:

```typescript
type Success<T> = { kind: "success"; value: T };
type Failure<E> = { kind: "failure"; error: E };
type Result<T, E> = Success<T> | Failure<E>;

function divide(a: number, b: number): Result<number, string> {
  if (b === 0) {
    return { kind: "failure", error: "Cannot divide by zero" };
  }
  return { kind: "success", value: a / b };
}
```

### Handling the Result in TypeScript

```typescript
const handleDivision = (result: Result<number, string>) => {
  if (result.kind === "success") {
    console.log("Division result:", result.value);
  } else {
    console.error("Division error:", result.error);
  }
};

const result = divide(10, 0);
handleDivision(result);
```

### Native Rust Implementation for Comparison

In Rust, the `Result` type is an enum with variants for success and error:

```rust

fn divide(a: i32, b: i32) -> std::result::Result<i32, String> {
    if b == 0 {
        std::result::Result::Err("Cannot divide by zero".to_string())
    } else {
        std::result::Result::Ok(a / b)
    }
}

fn main() {
    match divide(10, 2) {
        std::result::Result::Ok(result) => println!("Division result: {}", result),
        std::result::Result::Err(error) => println!("Error: {}", error),
    }
}

```

### Why the Rust Way?

1. **Explicit Handling**: Forces handling of both outcomes, enhancing code robustness.
2. **Clarity**: Makes code intentions clear.
3. **Safety**: Reduces uncaught exceptions.
4. **Functional Approach**: Aligns with TypeScript's functional programming style.

## Leveraging ts-results for Rust-Like Error Handling

For TypeScript developers, the [ts-results](https://github.com/vultix/ts-results) library is a great tool to apply Rust's error handling pattern, simplifying the implementation of Rust's `Result` type in TypeScript.

## Conclusion

Implementing Rust's `Result` pattern in TypeScript, with tools like ts-results, enhances error handling strategies. This approach creates robust applications that handle errors while maintaining code integrity and usability.

Let's embrace these practices to craft software that withstands the tests of time and uncertainty.

---

--- title: Mastering Vue 3 Composables: A Comprehensive Style Guide description: Did you ever struggle how to write better composables in Vue? In this Blog post I try to give some tips how to do that tags: ['vue'] url: https://alexop.dev/posts/mastering-vue-3-composables-a-comprehensive-style-guide ---

# Mastering Vue 3 Composables: A Comprehensive Style Guide



## Introduction

The release of Vue 3 brought a transformational change, moving from the Options API to the Composition API. At the heart of this transition lies the concept of "composables" — modular functions that leverage Vue's reactive features. This change enhanced the framework's flexibility and code reusability. The inconsistent implementation of composables across projects often leads to convoluted and hard-to-maintain codebases.

This style guide harmonizes coding practices around composables, focusing on producing clean, maintainable, and testable code. While composables represent a new pattern, they remain functions at their core. The guide bases its recommendations on time-tested principles of good software design.

This guide serves as a comprehensive resource for both newcomers to Vue 3 and experienced developers aiming to standardize their team's coding style.

## Table of Contents

## File Naming

### Rule 1.1: Prefix with `use` and Follow PascalCase

```ts
// Good
useCounter.ts;
useApiRequest.ts;

// Bad
counter.ts;
APIrequest.ts;
```

---

## Composable Naming

### Rule 2.1: Use Descriptive Names

```ts
// Good
export function useUserData() {}

// Bad
export function useData() {}
```

---

## Folder Structure

### Rule 3.1: Place in composables Directory

```plaintext
src/
└── composables/
    ├── useCounter.ts
    └── useUserData.ts
```

---

## Argument Passing

### Rule 4.1: Use Object Arguments for Four or More Parameters

```ts
// Good: For Multiple Parameters
useUserData({ id: 1, fetchOnMount: true, token: "abc", locale: "en" });

// Also Good: For Fewer Parameters
useCounter(1, true, "session");

// Bad
useUserData(1, true, "abc", "en");
```

---

## Error Handling

### Rule 5.1: Expose Error State

```ts
// Good
const error = ref(null);
try {
  // Do something
} catch (err) {
  error.value = err;
}
return { error };

// Bad
try {
  // Do something
} catch (err) {
  console.error("An error occurred:", err);
}
return {};
```

---

## Avoid Mixing UI and Business Logic

### Rule 6.2: Decouple UI from Business Logic in Composables

Composables should focus on managing state and business logic, avoiding UI-specific behavior like toasts or alerts. Keeping UI logic separate from business logic will ensure that your composable is reusable and testable.

```ts
// Good
export function useUserData(userId) {
  const user = ref(null);
  const error = ref(null);

  const fetchUser = async () => {
    try {
      const response = await axios.get(`/api/users/${userId}`);
      user.value = response.data;
    } catch (e) {
      error.value = e;
    }
  };

  return { user, error, fetchUser };
}

// In component
setup() {
  const { user, error, fetchUser } = useUserData(userId);

  watch(error, (newValue) => {
    if (newValue) {
      showToast("An error occurred.");  // UI logic in component
    }
  });

  return { user, fetchUser };
}

// Bad
export function useUserData(userId) {
  const user = ref(null);

  const fetchUser = async () => {
    try {
      const response = await axios.get(`/api/users/${userId}`);
      user.value = response.data;
    } catch (e) {
      showToast("An error occurred."); // UI logic inside composable
    }
  };

  return { user, fetchUser };
}
```

---

## Anatomy of a Composable

### Rule 7.2: Structure Your Composables Well

A well-structured composable improves understanding, usage, and maintenance. It consists of these components:

- **Primary State**: The main reactive state that the composable manages.
- **State Metadata**: States that hold values like API request status or errors.
- **Methods**: Functions that update the Primary State and State Metadata. These functions can call APIs, manage cookies, or integrate with other composables.

Following this structure makes your composables more intuitive and improves code quality across your project.

```ts
// Good Example: Anatomy of a Composable
// Well-structured according to Anatomy of a Composable
export function useUserData(userId) {
  // Primary State
  const user = ref(null);

  // Supportive State
  const status = ref("idle");
  const error = ref(null);

  // Methods
  const fetchUser = async () => {
    status.value = "loading";
    try {
      const response = await axios.get(`/api/users/${userId}`);
      user.value = response.data;
      status.value = "success";
    } catch (e) {
      status.value = "error";
      error.value = e;
    }
  };

  return { user, status, error, fetchUser };
}

// Bad Example: Anatomy of a Composable
// Lacks well-defined structure and mixes concerns
export function useUserDataAndMore(userId) {
  // Muddled State: Not clear what's Primary or Supportive
  const user = ref(null);
  const count = ref(0);
  const message = ref("Initializing...");

  // Methods: Multiple responsibilities and side-effects
  const fetchUserAndIncrement = async () => {
    message.value = "Fetching user and incrementing count...";
    try {
      const response = await axios.get(`/api/users/${userId}`);
      user.value = response.data;
    } catch (e) {
      message.value = "Failed to fetch user.";
    }
    count.value++; // Incrementing count, unrelated to user fetching
  };

  // More Methods: Different kind of task entirely
  const setMessage = newMessage => {
    message.value = newMessage;
  };

  return { user, count, message, fetchUserAndIncrement, setMessage };
}
```

---

## Functional Core, Imperative Shell

### Rule 8.2: (optional) use functional core imperative shell pattern

Structure your composable such that the core logic is functional and devoid of side effects, while the imperative shell handles the Vue-specific or side-effecting operations. Following this principle makes your composable easier to test, debug, and maintain.

#### Example: Functional Core, Imperative Shell

```ts
// good
// Functional Core
const calculate = (a, b) => a + b;

// Imperative Shell
export function useCalculatorGood() {
  const result = ref(0);

  const add = (a, b) => {
    result.value = calculate(a, b); // Using the functional core
  };

  // Other side-effecting code can go here, e.g., logging, API calls

  return { result, add };
}

// wrong
// Mixing core logic and side effects
export function useCalculatorBad() {
  const result = ref(0);

  const add = (a, b) => {
    // Side-effect within core logic
    console.log("Adding:", a, b);
    result.value = a + b;
  };

  return { result, add };
}
```

---

## Single Responsibility Principle

### Rule 9.1: Use SRP for composables

A composable should follow the Single Responsibility Principle: one reason to change. This means each composable handles one specific task. Following this principle creates composables that are clear, maintainable, and testable.

```ts
// Good
export function useCounter() {
  const count = ref(0);

  const increment = () => {
    count.value++;
  };

  const decrement = () => {
    count.value--;
  };

  return { count, increment, decrement };
}

// Bad

export function useUserAndCounter(userId) {
  const user = ref(null);
  const count = ref(0);

  const fetchUser = async () => {
    try {
      const response = await axios.get(`/api/users/${userId}`);
      user.value = response.data;
    } catch (error) {
      console.error("An error occurred while fetching user data:", error);
    }
  };

  const increment = () => {
    count.value++;
  };

  const decrement = () => {
    count.value--;
  };

  return { user, fetchUser, count, increment, decrement };
}
```

---

## File Structure of a Composable

### Rule 10.1: Rule: Consistent Ordering of Composition API Features

Your team should establish and follow a consistent order for Composition API features throughout the codebase.

Here's a recommended order:

1. Initializing: Setup logic
2. Refs: Reactive references
3. Computed: Computed properties
4. Methods: Functions for state manipulation
5. Lifecycle Hooks: onMounted, onUnmounted, etc.
6. Watch

Pick an order that works for your team and apply it consistently across all composables.

```ts
// Example in useCounter.ts
export default function useCounter() {
  // Initializing
  // Initialize variables, make API calls, or any setup logic
  // For example, using a router
  // ...

  // Refs
  const count = ref(0);

  // Computed
  const isEven = computed(() => count.value % 2 === 0);

  // Methods
  const increment = () => {
    count.value++;
  };

  const decrement = () => {
    count.value--;
  };

  // Lifecycle
  onMounted(() => {
    console.log("Counter is mounted");
  });

  return {
    count,
    isEven,
    increment,
    decrement,
  };
}
```

## Conclusion

These guidelines provide best practices for writing clean, testable, and efficient Vue 3 composables. They combine established software design principles with practical experience, though they aren't exhaustive.

Programming blends art and science. As you develop with Vue, you'll discover patterns that match your needs. Focus on maintaining a consistent, scalable, and maintainable codebase. Adapt these guidelines to fit your project's requirements.

Share your ideas, improvements, and real-world examples in the comments. Your input helps evolve these guidelines into a better resource for the Vue community.

---

--- title: Best Practices for Error Handling in Vue Composables description: Error handling can be complex, but it's crucial for composables to manage errors consistently. This post explores an effective method for implementing error handling in composables. tags: ['vue'] url: https://alexop.dev/posts/best-practices-for-error-handling-in-vue-composables ---

# Best Practices for Error Handling in Vue Composables



## Introduction

Navigating the complex world of composables presented a significant challenge. Understanding this powerful paradigm required effort when determining the division of responsibilities between a composable and its consuming component. The strategy for error handling emerged as a critical aspect that demanded careful consideration.

In this blog post, we aim to clear the fog surrounding this intricate topic. We'll delve into the concept of **Separation of Concerns**, a fundamental principle in software engineering, and how it provides guidance for proficient error handling within the scope of composables. Let's delve into this critical aspect of Vue composables and demystify it together.

> "Separation of Concerns, even if not perfectly possible, is yet the only available technique for effective ordering of one's thoughts, that I know of." -- Edsger W. Dijkstra

## The `usePokemon` Composable

Our journey begins with the creation of a custom composable, aptly named `usePokemon`. This particular composable acts as a liaison between our application and the Pokémon API. It boasts three core methods — `load`, `loadSpecies`, and `loadEvolution` — each dedicated to retrieving distinct types of data.

A straightforward approach would allow these methods to propagate errors directly. Instead, we take a more robust approach. Each method catches potential exceptions internally and exposes them via a dedicated error object. This strategy enables more sophisticated and context-sensitive error handling within the components that consume this composable.

Without further ado, let's delve into the TypeScript code for our `usePokemon` composable:

## Dissecting the `usePokemon` Composable

Let's break down our `usePokemon` composable step by step, to fully grasp its structure and functionality.

### The `ErrorRecord` Interface and `errorsFactory` Function

```ts
interface ErrorRecord {
  load: Error | null;
  loadSpecies: Error | null;
  loadEvolution: Error | null;
}

const errorsFactory = (): ErrorRecord => ({
  load: null,
  loadSpecies: null,
  loadEvolution: null,
});
```

First, we define a `ErrorRecord` interface that encapsulates potential errors from our three core methods. This interface ensures that each method can store a `Error` object or `null` if no error has occurred.

The `errorsFactory` function creates these ErrorRecord objects. It returns an ErrorRecord with all values set to null, indicating no errors have occurred yet.

### Initialising Refs

```ts
const pokemon: Ref<any | null> = ref(null);
const species: Ref<any | null> = ref(null);
const evolution: Ref<any | null> = ref(null);
const error: Ref<ErrorRecord> = ref(errorsFactory());
```

Next, we create the `Ref` objects that store our data (`pokemon`, `species`, and `evolution`) and our error information (error). We use the errorsFactory function to set up the initial error-free state.

### The `load`, `loadSpecies`, and `loadEvolution` Methods

Each of these methods performs a similar set of operations: it fetches data from a specific endpoint of the Pokémon API, assigns the returned data to the appropriate `Ref` object, and handles any potential errors.

```ts
const load = async (id: number) => {
  try {
    const response = await fetch(`https://pokeapi.co/api/v2/pokemon/${id}`);
    pokemon.value = await response.json();
    error.value.load = null;
  } catch (err) {
    error.value.load = err as Error;
  }
};
```

For example, in the `load` method, we fetch data from the `pokemon` endpoint using the provided ID. A successful fetch updates `pokemon.value` with the returned data and clears any previous error by setting `error.value.load` to null. When an error occurs during the fetch, we catch it and store it in error.value.load.

The `loadSpecies` and `loadEvolution` methods operate similarly, but they fetch from different endpoints and store their data and errors in different Ref objects.

### The Return Object

The composable returns an object providing access to the Pokémon, species, and evolution data, as well as the three load methods. It exposes the error object as a computed property. This computed property updates whenever any of the methods sets an error, allowing consumers of the composable to react to errors.

```ts
return {
  pokemon,
  species,
  evolution,
  load,
  loadSpecies,
  loadEvolution,
  error: computed(() => error.value),
};
```

### Full Code

```ts
interface ErrorRecord {
  load: Error | null;
  loadSpecies: Error | null;
  loadEvolution: Error | null;
}

const errorsFactory = (): ErrorRecord => ({
  load: null,
  loadSpecies: null,
  loadEvolution: null,
});

export default function usePokemon() {
  const pokemon: Ref<any | null> = ref(null);
  const species: Ref<any | null> = ref(null);
  const evolution: Ref<any | null> = ref(null);
  const error: Ref<ErrorRecord> = ref(errorsFactory());

  const load = async (id: number) => {
    try {
      const response = await fetch(`https://pokeapi.co/api/v2/pokemon/${id}`);
      pokemon.value = await response.json();
      error.value.load = null;
    } catch (err) {
      error.value.load = err as Error;
    }
  };

  const loadSpecies = async (id: number) => {
    try {
      const response = await fetch(
        `https://pokeapi.co/api/v2/pokemon-species/${id}`
      );
      species.value = await response.json();
      error.value.loadSpecies = null;
    } catch (err) {
      error.value.loadSpecies = err as Error;
    }
  };

  const loadEvolution = async (id: number) => {
    try {
      const response = await fetch(
        `https://pokeapi.co/api/v2/evolution-chain/${id}`
      );
      evolution.value = await response.json();
      error.value.loadEvolution = null;
    } catch (err) {
      error.value.loadEvolution = err as Error;
    }
  };

  return {
    pokemon,
    species,
    evolution,
    load,
    loadSpecies,
    loadEvolution,
    error: computed(() => error.value),
  };
}
```

## The Pokémon Component

Next, let's look at a Pokémon component that uses our `usePokemon` composable:

```vue
<template>
  <div>
    <div v-if="pokemon">
      <h2>Pokemon Data:</h2>
      <p>Name: {{ pokemon.name }}</p>
    </div>

    <div v-if="species">
      <h2>Species Data:</h2>
      <p>Name: {{ species.base_happiness }}</p>
    </div>

    <div v-if="evolution">
      <h2>Evolution Data:</h2>
      <p>Name: {{ evolution.evolutionName }}</p>
    </div>

    <div v-if="loadError">
      An error occurred while loading the pokemon: {{ loadError.message }}
    </div>

    <div v-if="loadSpeciesError">
      An error occurred while loading the species:
      {{ loadSpeciesError.message }}
    </div>

    <div v-if="loadEvolutionError">
      An error occurred while loading the evolution:
      {{ loadEvolutionError.message }}
    </div>
  </div>
</template>

<script lang="ts" setup>
const { load, loadSpecies, loadEvolution, pokemon, species, evolution, error } =
  usePokemon();

const loadError = computed(() => error.value.load);
const loadSpeciesError = computed(() => error.value.loadSpecies);
const loadEvolutionError = computed(() => error.value.loadEvolution);

const pokemonId = ref(1);
const speciesId = ref(1);
const evolutionId = ref(1);

load(pokemonId.value);
loadSpecies(speciesId.value);
loadEvolution(evolutionId.value);
</script>
```

The above code uses the usePokemon composable to fetch and display Pokémon, species, and evolution data. The component shows errors to users when fetch operations fail.

## Conclusion

Wrapping the `fetch` operations in a try-catch block in the `composable` and surfacing errors through a reactive error object keeps the component clean and focused on its core responsibilities - presenting data and handling user interaction.

This approach promotes `separation of concerns` - the composable manages error handling logic independently, while the component responds to the provided state. The component remains focused on presenting the data effectively.

The error object's reactivity integrates seamlessly with Vue's template system. The system tracks changes automatically, updating relevant template sections when the error state changes.

This pattern offers a robust approach to error handling in composables. By centralizing error-handling logic in the composable, you create components that maintain clarity, readability, and maintainability.

---

--- title: How to Improve Accessibility with Testing Library and jest-axe for Your Vue Application description: Use Jest axe to have automatic tests for your vue application tags: ['vue', 'accessibility'] url: https://alexop.dev/posts/how-to-improve-accessibility-with-testing-library-and-jest-axe-for-your-vue-application ---

# How to Improve Accessibility with Testing Library and jest-axe for Your Vue Application



Accessibility is a critical aspect of web development that ensures your application serves everyone, including people with disabilities. Making your Vue apps accessible fulfills legal requirements and enhances the experience for all users. In this post, we'll explore how to improve accessibility in Vue applications using Testing Library and jest-axe.

## Prerequisites

Before we dive in, make sure you have the following installed in your Vue project:

- @testing-library/vue
- jest-axe

You can add them with:

```bash
npm install --save-dev @testing-library/vue jest-axe
```

## Example Component

Let's look at a simple Vue component that displays an image and some text:

```vue
<template>
  <div>
    <h2>{{ title }}</h2>
    <p>{{ description }}</p>
    
  </div>
</template>

<script setup lang="ts">
defineProps({
  title: String,
  description: String,
});
</script>
```

Developers should include alt text for images to ensure accessibility, but how can we verify this in production?

## Testing with jest-axe

This is where jest-axe comes in. Axe is a leading accessibility testing toolkit used by major tech companies.

To test our component, we can create a test file like this:

```js
expect.extend(toHaveNoViolations);

describe("MyComponent", () => {
  it("has no accessibility violations", async () => {
    const { container } = render(MyComponent, {
      props: {
        title: "Sample Title",
        description: "Sample Description",
      },
    });

    const results = await axe(container);
    expect(results).toHaveNoViolations();
  });
});
```

When we run this test, we'll get an error like:

```shell
FAIL  src/components/MyComponent.spec.ts > MyComponent > has no accessibility violations

Error: expect(received).toHaveNoViolations(expected)

Expected the HTML found at $('img') to have no violations:

<img src="sample_image.jpg">

Received:

"Images must have alternate text (image-alt)"

Fix any of the following:
  Element does not have an alt attribute
  aria-label attribute does not exist or is empty
  aria-labelledby attribute does not exist, references elements that do not exist or references elements that are empty
  Element has no title attribute
  Element's default semantics were not overridden with role="none" or role="presentation"
```

This tells us we need to add an alt attribute to our image. We can fix the component and re-run the test until it passes.

## Conclusion

By integrating accessibility testing with tools like Testing Library and jest-axe, we catch accessibility issues during development. This ensures our Vue applications remain usable for everyone. Making accessibility testing part of our CI pipeline maintains high standards and delivers a better experience for all users.

---

--- title: Mastering TypeScript: Looping with Types description: Did you know that TypeScript is Turing complete? In this post, I will show you how you can loop with TypeScript. tags: ['typescript'] url: https://alexop.dev/posts/mastering-typescript-looping-with-types ---

# Mastering TypeScript: Looping with Types



## Introduction

Loops play a pivotal role in programming, enabling code execution without redundancy. JavaScript developers might be familiar with `foreach` or `do...while` loops, but TypeScript offers unique looping capabilities at the type level. This blog post delves into three advanced TypeScript looping techniques, demonstrating their importance and utility.

## Mapped Types

Mapped Types in TypeScript allow the transformation of object properties. Consider an object requiring immutable properties:

```typescript
type User = {
  id: string;
  email: string;
  age: number;
};
```

We traditionally hardcode it to create an immutable version of this type. To maintain adaptability with the original type, Mapped Types come into play. They use generics to map each property, offering flexibility to transform property characteristics. For instance:

```typescript
type ReadonlyUser<T> = {
  readonly [P in keyof T]: T[P];
};
```

This technique is extensible. For example, adding nullability:

```typescript
type Nullable<T> = {
  [P in keyof T]: T[P] | null;
};
```

Or filtering out certain types:

```typescript
type ExcludeStrings<T> = {
  [P in keyof T as T[P] extends string ? never : P]: T[P];
};
```

Understanding the core concept of Mapped Types opens doors to creating diverse, reusable types.

## Recursion

Recursion is fundamental in TypeScript's type-level programming since state mutation is not an option. Consider applying immutability to all nested properties:

```typescript
type DeepReadonly<T> = {
  readonly [P in keyof T]: T[P] extends object ? DeepReadonly<T[P]> : T[P];
};
```

Here, TypeScript's compiler recursively ensures every property is immutable, demonstrating the language's depth in handling complex types.

## Union Types

Union Types represent a set of distinct types, such as:

```typescript
const hi = "Hello";
const msg = `${hi}, world`;
```

Creating structured types from unions involves looping over each union member. For instance, constructing a type where each status is an object:

```typescript
type Status = "Failure" | "Success";
type StatusObject = Status extends infer S ? { status: S } : never;
```

## Conclusion

TypeScript's advanced type system transcends static type checking, providing sophisticated tools for type transformation and manipulation. Mapped Types, Recursion, and Union Types are not mere features but powerful instruments that enhance code maintainability, type safety, and expressiveness. These techniques underscore TypeScript's capability to handle complex programming scenarios, affirming its status as more than a JavaScript superset but a language that enriches our development experience.

---

================================================================================
# TODAY I LEARNED (TIL)
================================================================================

--- title: Claude Code's /goal Keeps the Agent Working Until It's Actually Done description: Using Claude Code's /goal command to set a measurable target the agent can't stop short of — and how I used it to cut my Astro build time in half. tags: ['claude-code', 'ai', 'build-performance', 'astro'] url: https://alexop.dev/tils/claude-code-goal-command ---

# Claude Code's /goal Keeps the Agent Working Until It's Actually Done



Today I learned about Claude Code's `/goal` command. Instead of giving the agent a task and hoping it finishes, you give it a _condition_ — and it can't stop until that condition holds.

## How it works

`/goal <condition>` installs a session-scoped Stop hook. The condition itself becomes the directive, so the agent starts working immediately without asking what to do. Every time it tries to end the turn, the hook checks the condition: if it isn't met, stopping is blocked and the agent keeps going. Once the condition holds, the hook auto-clears.

The key part is making the condition _measurable_. "Make the build faster" is vague. "Improve the build time by 50%" forces the agent to take a baseline, do the work, and prove the number — it can't declare victory on vibes.

```
/goal improve the time it takes to build this project by 50 percent
```

## Where I used it

I pointed it at the build time of this very blog. The agent profiled `astro build`, found that OG image generation was the bottleneck (~122 satori + resvg PNG routes), and made two changes:

- **Memoized the font fetch.** The fonts were being re-fetched from Google subset to _each image's text_, so nothing was cacheable — hundreds of network round-trips per build. Fetching the full font once and caching it killed all of them.
- **Cached the rasterized PNGs.** `resvg` rasterization costs ~140ms per image; the satori layout step is ~4ms. So it now caches each PNG on disk keyed by a hash of the SVG. Unchanged images skip `resvg` entirely.

Baseline was **104s**. Warm builds now run in **44s** — a 58% cut. The Stop hook didn't let it settle for the easy 15% win from the font fix alone; it kept digging until it cleared the 50% bar.

Two takeaways:

- `/goal` turns a fuzzy ask into a contract the agent has to satisfy.
- A measurable target (a number, a passing test) is what makes that contract enforceable.

---

--- title: TIL - Blending Fuzzy and Semantic Search with Reciprocal Rank Fusion description: Learn how to merge fuzzy and semantic search results using Reciprocal Rank Fusion (RRF) with TypeScript implementation and interactive Vue demo tags: ['typescript', 'vue', 'search'] url: https://alexop.dev/tils/reciprocal-rank-fusion-typescript-vue ---

# TIL - Blending Fuzzy and Semantic Search with Reciprocal Rank Fusion



I learned today how to blend fuzzy search and semantic search results using a method called Reciprocal Rank Fusion (RRF). If you ever build a search feature, you might run two separate searches (one that matches text closely and one that matches meaning). RRF helps you merge those two ranked lists into one final list. In this post I explain it in easy words and show how you can do it in TypeScript. At the end I include an interactive Vue component you can paste into your playground.

## Why combine fuzzy and semantic results?

Imagine a user types this query into your search box:

> “vue hooks guide”

A fuzzy search tries to match text exactly (it looks for “vue”, “hooks” and “guide” in titles or content). A semantic search tries to match meaning (it knows that Composition API is similar to hooks in Vue). Let’s say you have these indexed pages:

- **Vue.js Composition API Guide**
- **React Hooks Overview**
- **TypeScript Generics Guide**
- **Vue Router Basics**
- **CSS Flexbox Tutorial**

**Fuzzy hits** might rank (in order):

1. Vue.js Composition API Guide
2. React Hooks Overview
3. Vue Router Basics
4. CSS Flexbox Tutorial

(It matched “vue”, “hooks” or “guide” exactly in those titles. It placed “Vue.js Composition API Guide” first because it contains both “vue” and “guide.”)

**Semantic hits** might rank (in order):

1. Vue.js Composition API Guide
2. Vue Router Basics
3. React Hooks Overview
4. TypeScript Generics Guide

(It matched meaning—Composition API is like hooks—so it ranked that first. It also knows that “Vue Router Basics” belongs to the Vue ecosystem and is related enough.)

If you showed only one list, you would miss out on valuable matches. RRF gives each result a small score based on its position (rank) in each list. Then it adds those scores to get a final ranking.

## How RRF score works

Let’s say you have a ranked list from fuzzy search. The top item is rank 1, next is rank 2, and so on. You also have a ranked list from semantic search with its own ranks. RRF assigns each item a score using this formula:

```
score = weight × (1 / (rank + k))
```

- **rank** is the position in that list (1 means first, 2 means second, and so on)
- **weight** is how much you trust that list (for example 0.5 if you trust fuzzy and 0.5 if you trust semantic)
- **k** (often a number like 60) keeps the scores small so that lower ranked items do not jump too high

Compute that score for every item in each list. If an item appears in both lists (same unique id or slug), add its two scores together. That final sum decides its place in the merged list.

Continuing our example, let’s pick k = 60, fuzzyWeight = 0.5, semanticWeight = 0.5.

> From fuzzy hits:
>
> 1. “Vue.js Composition API Guide” → rank 1 → score = 0.5 × (1 / (1 + 60)) = 0.5 × (1/61) ≈ 0.00820
> 2. “React Hooks Overview” → rank 2 → score = 0.5 × (1 / (2 + 60)) = 0.5 × (1/62) ≈ 0.00806
> 3. “Vue Router Basics” → rank 3 → score = 0.5 × (1 / (3 + 60)) = 0.5 × (1/63) ≈ 0.00794
> 4. “CSS Flexbox Tutorial” → rank 4 → score = 0.5 × (1 / (4 + 60)) = 0.5 × (1/64) ≈ 0.00781

> From semantic hits:
>
> 1. “Vue.js Composition API Guide” → rank 1 → score = 0.5 × (1 / (1 + 60)) ≈ 0.00820
> 2. “Vue Router Basics” → rank 2 → score = 0.5 × (1 / (2 + 60)) ≈ 0.00806
> 3. “React Hooks Overview” → rank 3 → score = 0.5 × (1 / (3 + 60)) ≈ 0.00794
> 4. “TypeScript Generics Guide” → rank 4 → score = 0.5 × (1 / (4 + 60)) ≈ 0.00781

Now add scores for duplicates:

- **Vue.js Composition API Guide**: 0.00820 + 0.00820 = 0.01640
- **React Hooks Overview**: 0.00806 + 0.00794 = 0.01600
- **Vue Router Basics**: 0.00794 + 0.00806 = 0.01600
- **CSS Flexbox Tutorial**: 0.00781 (from fuzzy only)
- **TypeScript Generics Guide**: 0.00781 (from semantic only)

Sorted by total score:

1. Vue.js Composition API Guide (0.01640)
2. React Hooks Overview (0.01600)
3. Vue Router Basics (0.01600)
4. CSS Flexbox Tutorial (0.00781)
5. TypeScript Generics Guide (0.00781)

If two items tie (like “React Hooks Overview” and “Vue Router Basics”), you can break ties by alphabetical order or by whichever list you trust more first.

## Choosing weights by document type

Depending on the kind of content you index, you might want to favor fuzzy or semantic search more. Here are simple guidelines:

(1) API reference or code snippets (high precision needed)

- Use `fuzzyWeight = 0.7` and `semanticWeight = 0.3`
- You want exact matches on function names, class names, or code examples

(2) Tutorials or how to guides (balanced match)

- Use `fuzzyWeight = 0.5` and `semanticWeight = 0.5`
- You want both exact terms and conceptual matches

(3) Blog posts or conceptual articles (meaning matters more)

- Use `fuzzyWeight = 0.3` and `semanticWeight = 0.7`
- You want to catch related ideas even if they do not use exact keywords

Feel free to adjust these values based on your own data. If your content often uses synonyms or varied phrasing you might lean heavier toward semantic weight. If your content is very technical with precise terms you might lean heavier toward fuzzy weight.

## A simple TypeScript example

Below is a snippet that shows how to compute RRF scores and merge two lists. Assume each result has a unique `id` and a `name` (the title or description).

```ts
type SearchResult = { id: string; name: string };

function computeRrfScore(rank: number, weight: number, k: number): number {
  // rank is 1 for first item, 2 for second, and so on
  return weight * (1 / (rank + k));
}

function mergeResults(
  fuzzy: SearchResult[],
  semantic: SearchResult[],
  fuzzyWeight: number,
  semanticWeight: number,
  k: number,
  limit: number
): SearchResult[] {
  // Map from id to { item, score }
  const bucket = new Map<string, { item: SearchResult; score: number }>();

  // Add fuzzy scores
  fuzzy.forEach((item, idx) => {
    const rank = idx + 1;
    const score = computeRrfScore(rank, fuzzyWeight, k);
    const prev = bucket.get(item.id);
    if (prev) {
      prev.score += score;
    } else {
      bucket.set(item.id, { item, score });
    }
  });

  // Add semantic scores
  semantic.forEach((item, idx) => {
    const rank = idx + 1;
    const score = computeRrfScore(rank, semanticWeight, k);
    const prev = bucket.get(item.id);
    if (prev) {
      prev.score += score;
    } else {
      bucket.set(item.id, { item, score });
    }
  });

  // Convert to array and sort by score descending
  const mergedArray = Array.from(bucket.values())
    .sort((a, b) => b.score - a.score)
    .slice(0, limit)
    .map(entry => entry.item);

  return mergedArray;
}

// Example usage
const fuzzyHits: SearchResult[] = [
  { id: "vue-composition", name: "Vue.js Composition API Guide" },
  { id: "react-hooks", name: "React Hooks Overview" },
  { id: "vue-router", name: "Vue Router Basics" },
  { id: "css-flexbox", name: "CSS Flexbox Tutorial" },
];

const semanticHits: SearchResult[] = [
  { id: "vue-composition", name: "Vue.js Composition API Guide" },
  { id: "vue-router", name: "Vue Router Basics" },
  { id: "react-hooks", name: "React Hooks Overview" },
  { id: "typescript-generics", name: "TypeScript Generics Guide" },
];

const finalResults = mergeResults(
  fuzzyHits,
  semanticHits,
  0.5, // fuzzy weight (adjust by document type)
  0.5, // semantic weight
  60, // k value
  10 // limit top 10 results
);

console.log(finalResults);
```

In this code:

1. We define `computeRrfScore` to get small scores for each rank.
2. We loop through the fuzzy list and add each item’s score to `bucket`.
3. We loop through the semantic list and add each item’s score (or increase it if it is already in the bucket).
4. We sort all items by the combined score, then take the top `limit`.

You can adjust `fuzzyWeight` or `semanticWeight` to favor one search type. If you want fuzzy to matter more for API reference, set `fuzzyWeight = 0.7` and `semanticWeight = 0.3`.

## Interactive Vue component

Below is an interactive Vue component that shows step by step how RRF adds scores and sorts items. You can copy and paste it into your Vue playground to see how changing weights affects the final order.

**What is the perfect ratio between fuzzy and semantic?**

There is no single “perfect” ratio. It depends on your content and your users. Use these simple steps to find what works best:

1. **Start at 0.5/0.5**
   Give fuzzy and semantic equal weight (0.5 each). This balanced split works well for most mixed-content sites (API docs, tutorials, blog posts).

2. **Adjust by document type**
   - **Technical reference (exact names matter)**
     Try `fuzzyWeight = 0.7` and `semanticWeight = 0.3`. Exact matches (function names, code snippets) should score higher.
   - **How-to guides or tutorials (both term and meaning matter)**
     Keep `fuzzyWeight = 0.5` and `semanticWeight = 0.5`. You want both precise keywords and conceptual matches.
   - **Blog posts or conceptual articles (meaning matters more)**
     Try `fuzzyWeight = 0.3` and `semanticWeight = 0.7`. You want to surface related ideas even if the keywords don’t match exactly.

3. **Measure and tune with real queries**
   - Run a small set of typical searches against your index.
   - Compare top results for fuzzy-heavy (0.7/0.3), balanced (0.5/0.5), and semantic-heavy (0.3/0.7).
   - Ask teammates or a few users which results feel most relevant.
   - Adjust weights until the top results feel right for your audience.

4. **Consider domain and data size**
   - If your site has thousands of very similar pages (e.g., product SKUs), a higher fuzzy weight (0.8/0.2) helps pick exact matches.
   - If your content is short snippets or conversational text, lean semantic (0.4/0.6) so you capture intent even when wording varies.

5. **Use a validation set**
   - Pick 20–50 real example queries and hand-label the ideal result order.
   - Compute RRF scores for several weight pairs and see which pair minimizes ranking errors against your labels.
   - This gives a data-driven “best ratio” for your specific use case.

In short:

- Start at 0.5/0.5.
- Move toward fuzzy (e.g., 0.7/0.3) when exact terms matter.
- Move toward semantic (e.g., 0.3/0.7) when meaning matters most.
- Test with real queries and adjust until the top-ranked items feel right.

---

--- title: Indexed v-model in Vue 3 description: TIL about handling any number of inputs with one reactive array by binding each field to array[index] in Vue 3. tags: ['vue'] url: https://alexop.dev/tils/indexed-v-model-in-vue-3 ---

# Indexed v-model in Vue 3



## 📝 TIL — _Indexed `v-model`_ in Vue 3

> **Today I learned** that you can handle **any number of inputs** with **one reactive array** by binding each field to `array[index]`.
> It's the simplest way to keep dynamic rows in sync—no prop-drilling, no form library, no extra components.

---

### The 4-step recipe

1.  **Define your dynamic list:**

    ```js
    const rows = reactive([{ id: 1 } /* ... */]);
    ```

    - This is your dynamic list, which could come from props or an API call.

2.  **Create a ref for input values:**

    ```ts
    const values = ref<string[]>([]);
    ```

    - This will be the single source of truth for all corresponding inputs.

3.  **Keep `values` in sync with `rows`:**

    ```js
    watchEffect(() => {
      values.value = rows.map((_, i) => values.value[i] ?? "");
    });
    ```

    - This `watchEffect` ensures that the `values` array has the same length as the `rows` array, preserving any existing user input when rows are added or removed.

4.  **Bind inputs in your template:**

    ```html
    
    ```

    - Inside your `v-for` loop, bind each input to its corresponding element in the `values` array using `values[i]`.

That's it—**four key pieces of logic**.

---

### 🧪 30-second Proof-of-Concept

**Play with it**

- Add rows → the `values` array grows automatically.
- Type in any input → its value appears at the matching index.
- Remove rows → the input and its value disappear together.

---

### Why this pattern rocks

1. **Zero boilerplate** – one array, one watch, done.
2. **Reorder-safe** – as long as you keep stable keys (`:key="row.id"`), Vue keeps DOM ↔︎ array indices aligned.
3. **Easy aggregates** – totals, validation, API payloads are all `values.value` away:

   ```js
   const total = computed(() => values.value.reduce((s, n) => s + +n, 0));
   ```

Use it whenever your UI says "N inputs where N can change." This is particularly useful when you have a dynamic table with input fields and you need to have validation.

---

--- title: TIL - Detecting fresh deployments in a Vue 3 SPA with vite + version.json description: Learn how to detect fresh deployments in a Vue 3 SPA with vite + version.json tags: ['vue', 'vite'] url: https://alexop.dev/tils/detecting-fresh-deployments-vue3-spa-vite-version-json ---

# TIL - Detecting fresh deployments in a Vue 3 SPA with vite + version.json



Today I discovered a very simple way for my Vue 3 single-page app to tell users when I've released a new update.

## The idea

1.  **Build-time**: Each time I run `vite build`, a small Vite plugin creates a `version.json` file. It also sets up some information that's available when the app is built.
2.  **Run-time**: The app regularly checks the `/version.json` file.
3.  If the **`version`** or **`tag`** in that file doesn't match the information the app was built with, we show a message like "New version available – refresh!"

```mermaid
---
title: "Compile-Time Access"
---
flowchart TB
    A[Vite Build Process]
    A --> B[version-json Plugin]
    B -->|Injects constants| C[Environment Variables:<br/>• import.meta.env.APP_VERSION<br/>• import.meta.env.APP_TAG]
    D[Application Code]
    D -->|Accesses| C
```

## The Vite plugin ( `plugins/version-json.ts` )

```ts
export default function versionJson(): Plugin {
  // …snip…
  const versionDetails = {
    name: pkg.name,
    version: pkg.version, // 2.0.0
    tag: gitTag(), // v2.0.0-2-gabcdef
    commit: gitCommitHash(), // abcdef…
    commitTime: gitCommitTimestamp(),
    created: new Date().toISOString(),
  };

  return {
    name: "version-json",
    // 👉 1. Serve /version.json in dev
    configureServer(server) {
      server.middlewares.use((req, res, next) => {
        if (req.url === "/version.json") {
          res.setHeader("Content-Type", "application/json");
          res.end(JSON.stringify(versionDetails, null, 2));
          return;
        }
        next();
      });
    },

    // 👉 2. Emit dist/version.json in production
    closeBundle() {
      writeFileSync(
        resolve(outDir, "version.json"),
        JSON.stringify(
          { ...versionDetails, created: new Date().toISOString() },
          null,
          2
        )
      );
    },
  };
}
```

<Aside type="info">
  <h3>Version Information Format</h3>
  <p>The version information includes:</p>
  <ul>
    <li>Application name - From package.json (e.g., "vue-package-json")</li>
    <li>Version number - From package.json (e.g., "2.0.0")</li>
    <li>Git tag - Latest repository tag</li>
    <li>Git commit hash - Current commit identifier</li>
    <li>Git commit timestamp - When the code was committed</li>
    <li>Creation timestamp - When the version.json was generated</li>
  </ul>
</Aside>

The plugin also makes `import.meta.env.APP_VERSION` and `APP_TAG` available, so the app always knows which version it's running.

---

## The watcher component ( `ShowNewVersion.vue` )

```vue
<script setup lang="ts">
const props = defineProps<{
  initialVersion: string | null;
  initialTag: string | null;
}>();
const { isNewVersion, details } = useCheck();

function useCheck() {
  const isNewVersion = ref(false);
  const details = ref<string | null>(null);

  async function poll() {
    if (!props.initialVersion) return;
    const res = await fetch("/version.json");
    const v = await res.json();
    if (v.version !== props.initialVersion || v.tag !== props.initialTag) {
      isNewVersion.value = true;
      details.value = `${v.version} (${v.tag})`;
    }
  }
  onMounted(() => poll(), setInterval(poll, 30_000));
  return { isNewVersion, details };
}
</script>

<template>
  <div v-if="isNewVersion" class="alert">
    A new version is available → refresh! {{ details }}
  </div>
</template>
```

---

## How I use it

I run this command:

```bash
npm run build        # emits dist/version.json
```

When people use the app, their browser checks the `/version.json` file every 30 seconds. As soon as the file's content changes, the yellow banner appears. They can then do a manual refresh (`⌘R`) to load the new version.

## Takeaways

- **No server changes needed** – it's just one static file.
- It works the same way when I'm developing locally (the file is served on the fly) and in the live app (the file is created once during the build).
- You get information at build-time **and** a check at run-time, all in one.
- You can find the full code I showed above in this repository → [vueNewVersion](https://github.com/alexanderop/vueNewVersion).

For more details, you can look at the [Deep Wiki documentation](https://deepwiki.com/alexanderop/vueNewVersion/1-overview).

That's it – one plugin, one tiny component, and an easy way to manage cache-busting!

---

--- title: TIL: TypeScript Function Overloads description: Today I learned about function overloads in TypeScript. They solve a common problem - making your code understand exactly what type comes out based on what type goes in. tags: ['typescript'] url: https://alexop.dev/tils/typescript-function-overloads ---

# TIL: TypeScript Function Overloads



## What Function Overloads Do

Function overloads let me define multiple ways to call the same function:

```typescript
// These tell TypeScript about different ways to call my function
function convert(value: string): number;
function convert(value: number): string;

// This is the actual function that runs
function convert(value: string | number): string | number {
  if (typeof value === "string") {
    return parseInt(value);
  } else {
    return value.toString();
  }
}

const a = convert("42"); // TypeScript knows this is a number
const b = convert(42); // TypeScript knows this is a string
```

## How This Improves My Code

Without overloads, I'd have to use a union type, which loses information:

```typescript
function convert(value: string | number): string | number {
  if (typeof value === "string") {
    return parseInt(value);
  } else {
    return value.toString();
  }
}

const a = convert("42"); // TypeScript only knows this is string | number
const b = convert(42); // TypeScript only knows this is string | number
```

With overloads, TypeScript remembers which type I get back based on what I put in!

## Overloads vs. Union Types

- **Overloads**: More precise typing, TypeScript knows exactly which output type matches which input type
- **Union types**: Simpler code, but TypeScript only knows all possible output types, not which specific one

## Limitations in TypeScript

The big drawback? In TypeScript, I can't write separate code for each overload. I write one function that handles all cases. This gets messy with complex functions.

C++ does this better. In C++, each overload is a completely separate function:

```cpp
// Two totally separate functions
void convert(int value) {
    // Code for integers only
    cout << to_string(value) << endl;
}

void convert(string value) {
    // Different code for strings only
    cout << stoi(value) << endl;
}
```

In TypeScript, I have to write my own type-checking logic to figure out which version was called. This makes overloads in TypeScript harder to use for complex cases.

---

--- title: TIL: Powerful Vue.js Patterns for Complex JSON Rendering description: Key insights on using provide/inject and recursive components to build a JSON viewer in Vue.js tags: ['vue', 'typescript', 'components', 'recursion'] url: https://alexop.dev/tils/using-provide-inject-and-recursive-components-in-vuejs ---

# TIL: Powerful Vue.js Patterns for Complex JSON Rendering



Today I discovered how powerful the combination of Vue's provide/inject pattern and recursive components can be when dealing with nested data structures like JSON. Here are the key insights:

```mermaid
graph TD
    A[JSON Data] --> B[VJsonViewer]
    B -->|provides state| C[VJsonNode]
    C -->|recursive| C
    C -->|injects state| D[expandedNodes]
```

1. **Provide/Inject eliminates prop drilling** - Instead of passing state through multiple component levels, the parent component provides it directly to any descendant that needs it.

2. **Symbols prevent naming conflicts** - Using a Symbol as the injection key ensures uniqueness throughout the application:

   ```js
   export const jsonViewerKey = Symbol("jsonViewer");
   ```

3. **Centralized state management is cleaner** - The parent component manages all state changes:

   ```js
   provide(jsonViewerKey, {
     toggleNode: path => {
       expandedNodes.value.has(path)
         ? expandedNodes.value.delete(path)
         : expandedNodes.value.add(path);
     },
     isExpanded: path => expandedNodes.value.has(path),
   });
   ```

4. **Recursive components handle infinite nesting elegantly** - A component that renders itself can handle any level of nesting in your data structure:

   ```vue
   // src/components/VJsonNode.vue
   <VJsonNode
     v-for="entry in entries"
     :key="entry.path"
     :value="entry.value"
     :path="entry.path"
   />
   ```

5. **Computed properties make type handling clean** - Vue's reactivity system helps manage complex logic:

   ```js
   const valueType = computed(() => {
     if (Array.isArray(props.value)) return "array";
     if (props.value === null) return "null";
     return typeof props.value;
   });
   ```

6. **Path-based identifiers track state** - Using paths like `root.users[0].name` makes tracking expansion state straightforward across the entire structure.

7. **Validation improves component reliability** - Checking for proper context prevents misuse:
   ```js
   if (!jsonViewerProvider.withinJsonViewer) {
     throw new Error("VJsonNode must be used within a VJsonViewer component");
   }
   ```

This pattern has dramatically simplified how I handle complex nested data in Vue applications. What seemed like a daunting task became elegant and maintainable.

---

--- title: TypeScript Type Extraction Patterns description: Learn powerful TypeScript patterns for extracting and transforming nested types from complex interfaces. tags: ['typescript', 'types', 'patterns'] url: https://alexop.dev/tils/typescript-type-extraction-patterns ---

# TypeScript Type Extraction Patterns



## Extract Nested Types from Complex Interfaces

```ts
interface GetTodoQuery {
  todo?: {
    id: number;
    title: string;
    completed: boolean;
    tags?: Array<{
      id: number;
      name: string;
      color: string;
    }> | null;
    collaborators?: Array<{
      userId: number;
      role: "VIEWER" | "EDITOR";
      joinedAt: string;
    }> | null;
  };
}

// Extract nested types with proper type narrowing
type TodoTags = NonNullable<NonNullable<GetTodoQuery["todo"]>["tags"]>;
type TodoTag = TodoTags[number];
```

## Key Patterns

1. Handle optional properties: `NonNullable<T>` removes `undefined` and `null`
2. Access nested types: Chain properties using `['prop']`
3. Extract array item type: Use `[number]` index

Perfect for working with GraphQL queries and complex API responses where you need to extract specific nested types with proper type narrowing.

---

--- title: Better Type Inference with TypeScript Array Filters description: How to improve TypeScript type inference when filtering arrays using type guards tags: ['typescript', 'arrays', 'type-inference'] url: https://alexop.dev/tils/typescript-array-filter-type-inference ---

# Better Type Inference with TypeScript Array Filters



Today I learned about the difference between using Boolean as a filter function versus using a proper type guard for array filtering in TypeScript.

While `Boolean` can remove falsy values, it doesn't improve TypeScript's type inference:

```ts twoslash
const numbers = [1, null, 2, undefined, 3].filter(Boolean);
const type = numbers;
//    ^?
```

The type remains `(number | null | undefined)[]` because TypeScript doesn't understand that we're removing null and undefined values.

Using a type guard provides proper type inference:

```ts twoslash
const numbersTyped = [1, null, 2, undefined, 3].filter(
  (num): num is NonNullable<typeof num> => num !== null && num !== undefined
);
const type = numbersTyped;
//    ^?
```

TypeScript infers the type as `number[]`!

Key takeaways:

- Use type guards instead of `Boolean` for better type inference
- `NonNullable<T>` is a useful utility type for removing null and undefined
- Type predicates (`is` keyword) help TypeScript understand our filtering logic

---

--- title: Deploy your Vue App to GitHub Pages with Caching description: Learn how to speed up your GitHub Actions workflows by caching node_modules and properly deploy Vue apps to GitHub Pages tags: ['github-actions', 'vue', 'deployment', 'performance'] url: https://alexop.dev/tils/github-actions-vue-deployment-caching ---

# Deploy your Vue App to GitHub Pages with Caching



## Problem

Need a free and efficient way to deploy a Vue app? GitHub Pages is an excellent solution. Here's how to set it up with proper caching.

## Solution

### 1. Enable GitHub Pages

Go to repository Settings > Pages and enable GitHub Pages.

### 2. Create GitHub Action

Create `.github/workflows/deploy.yml`:

```yaml
name: Deploy to GitHub Pages

on:
  push:
    branches:
      - main

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: true

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: "20"
          cache: npm

      - name: Cache node modules
        uses: actions/cache@v4
        with:
          path: node_modules
          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-node-

      - name: Install dependencies
        run: npm ci

      - name: Build
        run: npm run build

      - name: Setup Pages
        uses: actions/configure-pages@v4

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./dist

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4
```

### 3. Configure Vite

Update `vite.config.ts`:

```typescript
export default defineConfig(({ command }) => ({
  plugins: [vue()],
  base: command === "build" ? "/your-repo-name/" : "/",
}));
```

## Key Features

- Implements dependency caching to speed up builds
- Uses proper concurrency control to prevent conflicting deployments
- Automatically configures correct base URL for GitHub Pages
- Utilizes latest GitHub Actions versions

#github-actions #vue #deployment #performance

---

--- title: Dynamic Pinia Stores in Vue 3 description: Create dynamic Pinia stores with unique IDs for separate component instances tags: ['vue', 'pinia', 'typescript'] url: https://alexop.dev/tils/dynamic-pinia-stores ---

# Dynamic Pinia Stores in Vue 3



Today I learned how to create dynamic Pinia stores in Vue 3 by generating unique store IDs. This is super useful when you need separate state management for different instances of the same component, like data tables or forms.

Here's how to do it:

```typescript
const useStore = (id: string) =>
  defineStore(`store-${id}`, () => {
    const data = ref({});

    return { data };
  })();

// Usage example:
const tableOneStore = useStore("table1");
const tableTwoStore = useStore("table2");
```

Each store instance gets its own isolated state, making it perfect for managing independent components. This approach prevents state conflicts and keeps your data properly organized.

Key benefits:

- Isolated state per component instance
- Clean and maintainable code
- Type-safe with TypeScript
- Perfect for dynamic components

#VueJS

---

================================================================================
# NOTES
================================================================================

--- title: Vibe Engineering Effect Apps: Just Clone the Repo description: Michael Arnaldi's workshop on building Effect apps with coding agents. The single trick: clone the library repo as a git subtree so the agent reads source code instead of fighting stale docs. sourceType: video sourceAuthor: Michael Arnaldi tags: ['ai-agents', 'effect', 'typescript', 'coding-agents', 'vibe-coding'] url: https://alexop.dev/notes/vibe-engineering-effect-apps ---

# Vibe Engineering Effect Apps: Just Clone the Repo



## Why I watched this

I'd been hitting a wall with coding agents on library-heavy Effect work. The model has stale knowledge, MCP doc servers underperform, and most "agents.md best practices" posts stay on the surface. Michael Arnaldi's workshop promised the unvarnished version, built live from an empty directory by someone who hasn't written code by hand in eight months. That's the post-mortem I wanted.

## What I learned

### Design for what LLMs are, not what they look like

People keep treating models like little humans. They are not. The differences shape everything downstream:

- **No continuous learning.** Pre-training cutoff, post-training phase, then frozen. Tell the model something today and tomorrow it has forgotten.
- **Context is a fixed-size array of messages**, not memory. Bigger windows confuse the model. A 1M-token context often hurts more than it helps.
- **Coding agents are post-trained on reading and producing code in a project.** They are less trained on reading prose docs and on calling MCP tools they've never seen. Most agents deprioritise `node_modules`; Cursor by default doesn't even index `.gitignore`d files.

The design constraint: the agent is dumb, has six-month-old knowledge at best, can't remember between sessions, and gets worse the more junk you stuff into its context. Build for that.

### Just clone the damn repo

If the model has stale knowledge, you need a way to deliver new knowledge. People reach for clever options: MCP doc servers, README scraping, doc-CLIs. All of these underperform a dumber move: **clone the library's source into your own working tree** as a git subtree under `repos/<library>`, and tell the agent it's reference material.

Now the model treats it as "more of my codebase," explores it with the same tools it uses for your own files, and copies the patterns it finds. You're not fighting its training; you're feeding it the thing it's best at consuming.

```
repos/
  effect/         # cloned as a git subtree, no history
src/
  ...your code...
agents.md         # tells the agent: "patterns live in repos/effect"
```

This is also what [`effect.solutions`](https://effect.solutions) is solving, but that approach chases its tail: it gives the model a CLI to read docs, and then the model has to know how to use *that* CLI. Read the project's own README and you find the line *"you should actually just clone the repository."* So we did.

### Patterns folders, not raw library access

Don't point the agent at the raw cloned repo every turn. Have it distil into project-local `patterns/*.md`:

> "Explore the Effect repo for patterns on how to build an HTTP API with OpenAPI docs and a generated type-safe client. Save your research into `patterns/http-api.md`."

Two reasons this beats re-reading the library each turn:

1. **Self-selection.** Effect is huge. If you let the model wander, you'll end up using *every* feature. Project-local patterns are the Effect-subset *you* chose. Matters even more in brownfield codebases where you don't want a refactor of the world.
2. **Context discipline.** A 200-line `patterns/sql.md` is cheap; re-reading half the Effect monorepo every turn is not.

### Crank every diagnostic to error

For an AI-driven project: zero soft warnings. Every TypeScript suggestion, every unused-symbol notice, all errors. The model won't commit code with errors. It ignores warnings. Combined with `format on save: true`, this gives a tight feedback loop without babysitting style.

### ESLint as back-pressure: a moat against shortcuts

The other half of the loop. Every shortcut Michael caught the model taking, he banned with a custom rule:

- **No `as` casts.** Use `Schema` to validate. (When he banned `as unknown as X`, the model learned that `never` is a bottom type and started writing `as never as X`. So he banned `as` outright.)
- **No `any`. No `unknown`** at API boundaries.
- **No `sql<MyType>` typed query placeholders.** Zero runtime safety. Use `SqlSchema` instead.
- **No constructors inside HTTP handlers** to massage strings into branded types. Sign your *schema at the edge* is too loose.
- **Branded types for every identifier.** `UserId`, `TodoId`, etc. Otherwise the agent will pass a `userId: string` where a `todoId: string` is wanted.

### Spec-first, then implement, in dumb loops

Plan mode cripples tool access. Use spec-driven development instead. The first task: "discuss with me how to build X and write the plan to `plans/x.md`." That spec becomes the durable artefact. A *second* task implements against the spec, inside a Ralph-style loop:

```sh
while true; do
  agent "$(cat NEXT_TASK.md)" || break
done
```

Why restart the agent so often? A long session accretes irrelevant context: failed attempts, abandoned ideas, dead branches. The earliest messages then bias the model on later, unrelated tasks. With AI, *less is more*. Complex context-management architectures lose to dumb loops.

### Match prompts to the model

The "agents.md standard" pretends models are interchangeable. They aren't.

- **GPT** gets scared by ALL CAPS and de-optimises into sycophancy. Keep prompts calm. More concise output. Asks permission more often.
- **Opus** does the opposite. Shouted instructions get extra attention. Eager: it does the thing where GPT keeps asking. Sometimes a feature, sometimes a bug (takes shortcuts, sleeps, removes failing tests rather than fixing them).
- Leave a single `any` in a codebase and Opus will copy it everywhere.
- For UI work, reach for Opus over codex. For most other things they're interchangeable.
- **Open-weights models lag frontier models by 3–6 months** but already past where Sonnet 4 was when Michael started.

### Skills vs slash commands

Slash commands work when one person controls the agent (`/new-pattern`, `/update-agents`). Skills generalise across teammates with different agents. Skills are *not* a magic wand. Install many "Next.js skills" and you pollute the context, ending up worse. Use skills for *specific, narrow* tasks. They're CLI tools, not knowledge dumps.

### The workflow gap nobody fills

The part most people get wrong: long-running, multi-step business processes. Take registration:

1. Insert user row.
2. Send confirmation email.

There's no transaction across (1) and (2). The server crashes between them. Hence every signup flow has *"if the email doesn't arrive in 30 minutes, please retry."* That copy hides a broken system behind a UX wrapper.

The fix: a workflow engine. Temporal, Inngest, or `@effect/cluster` + `@effect/workflow`. This used to be a "large company" problem because edge cases happened twice a day at scale. AI made it everyone's problem. With LLMs in the request path, response times went from 10ms to a minute. In that minute, the server will fail. Even a 10-user app now needs durable workflows. Hence Temporal's moment.

### Evals, and why "is this code good?" is hard

Everything above is opinion-driven. *Michael* thinks branded IDs are better. *He* prefers classes. How does he know his patterns improve agent output? Honest answer: by running evals, badly. The hard part: "is this code good?" *depends*. Terse vs verbose, this structure vs that, both convey meaning, both type-check. 100 humans give you an 80/20 split.

Current approach: keep human-written reference solutions, generate model output, use an LLM judge to score similarity. Not pretty. Necessary if you want to fine-tune a model on Effect itself, because you can't reinforcement-learn without an eval signal.

## The takeaway

If I remember nothing else from this:

1. **Clone the library repo as a git subtree.** Stop fighting the agent's training.
2. **Distil into `patterns/*.md`** instead of pointing at the raw repo every turn. You get to choose your subset.
3. **Crank every diagnostic to error**, and let a custom-rule linter ban the shortcuts you keep catching.
4. **Spec first, implement second**, and run implementation in dumb loops with fresh contexts.
5. **Match prompts to the model.** GPT calm, Opus loud. Don't pretend they're the same.
6. **Stop trying to write code.** Start setting up the repository so the agent can.

## My Rating

The most useful coding-agent talk I've watched this year, because Michael prepared nothing and showed the live mistakes (placeholder npm package, models inventing `as never as X` to dodge a lint rule). The "just clone the repo" insight reframes a dozen other techniques as cope. The Ralph-loop-and-fresh-context dogma matches what I arrived at on smaller projects. The workflows section is the one I keep coming back to: durable orchestration is now a 10-user-app problem, the moment you put LLMs in the request path.

- ⭐⭐⭐⭐⭐ (5/5).

---

--- title: Writing Good Tests for Vue Applications description: A principle-driven guide to testing Vue apps. Argues for an Application-Test-heavy strategy with Vitest, Playwright, Testing Library and MSW, glued together by a driver pattern that decouples tests from any specific framework. sourceType: book sourceAuthor: Markus Oberlehner tags: ['testing', 'vue', 'tdd', 'playwright', 'vitest', 'book-summary'] url: https://alexop.dev/notes/writing-good-tests-for-vue-applications ---

# Writing Good Tests for Vue Applications



## Overview

The book lays out an opinionated approach to testing Vue applications, organised around two big ideas: **what kinds of tests to write and in what proportion**, and **how to structure tests so refactors don't break them**. The recommended stack is **Vitest + Playwright + Testing Library + Mock Service Worker (MSW)**.

## The four types of automated tests

The book defines four distinct categories, each with its own purpose:

1. **E2E System Tests**: exercise the full system, including real backend services and databases. Highest confidence at the highest cost.
2. **Application Tests**: exercise the entire Vue SPA from the user's perspective, with every external HTTP call mocked.
3. **Component Tests**: exercise a single Vue component in isolation. Fast and narrow.
4. **Unit Tests**: exercise extracted utility functions, classes, or modules. Not composables.

The book's headline rule: *every test that can be automated should be automated.* Manual testing covers exploratory work and usability checks. It shouldn't block deployments.

## How the book frames the testing pyramid

The classical pyramid for a Vue project looks like this:

```
       ▲  E2E (Cypress / Playwright)        few, slow, full system
      ▲▲  Integration                       some
    ▲▲▲▲  Unit (Jest, vue-test-utils)       lots, fast, narrow
```

The book rejects this shape. It treats both Pyramid and Trophy as starting points rather than prescriptions, and argues that feedback speed is what matters. The recommended distribution sits closer to Kent C. Dodds' Testing Trophy, but skewed further toward the user-perspective middle:

```
        ▲  manual exploratory   (continuous, non-blocking)
       ▲▲  E2E smoke tests      (1–5 critical paths)
     ▲▲▲▲  Application Tests    ← the bulk lives here
    ▲▲▲▲▲  Component + Unit     (only when they earn their place)
```

Three decisions follow from this:

- Reserve E2E System Tests for critical-integration smoke tests.
- Build the suite around **Application Tests**.
- Write Component and Unit Tests **only when the Application Test layer cannot give precise enough feedback**: a component with many edge cases of its own, or a pure function that deserves documentation through tests.

The book is explicit: don't test composables, stores, or plugins in isolation. The components or applications that use them cover them.

## What the book means by "Application Test"

*Application Test* is the book's most distinctive vocabulary, because the wider community overloads *Integration Test* and *E2E Test* with too many meanings. The book's definition is precise:

> An **Application Test** exercises the **entire Vue SPA inside a single repository**, from the user's point of view, while **mocking every HTTP call** to services outside the SPA.

Two properties separate this from a typical "integration test" or a Cypress E2E:

- **Boundary = the Git repo, not the system.** The router, Pinia stores, layouts, page components, composables, and fetching code: all real. The backend, database, Stripe, and the auth provider: all mocked at the network layer.
- **Tool-agnostic.** The same test should run in both jsdom and Playwright. The choice of runner is a feedback-speed lever.

Visually, the scope looks like this:

A concrete Application Test using Playwright reads like a user story, with `page.route()` standing in for the backend:

```ts
it('should be possible to buy a bike', async ({ page }) => {
  await page.route('/api/product/list', route =>
    route.fulfill({ json: [bestBikeEver, notSoGoodBike] }),
  );
  await page.route('/api/checkout', route =>
    route.fulfill({ json: { success: true } }),
  );

  await page.goto('https://my.bikestore');
  await page.findByText('Best Bike Ever').click();
  await page.findByRole('button', { name: 'Add to cart' }).click();
  await page.findByRole('button', { name: 'Checkout' }).click();

  expect(await page.findByText('Thank you for your order!').isVisible())
    .toBe(true);
});
```

What's missing here: no `mount(SomeComponent)`, no stubbing of child components, no assertions on Pinia actions. The test boots the real app, drives it through the UI, and asserts on visible outcomes. Compare that to a Component Test, which has a much narrower brief:

```ts
// Component Test — only PostForm, in isolation
it('should warn the user when they enter invalid data', async () => {
  render(PostForm);
  await userEvent.type(await screen.findByLabel('Title'), '');
  await userEvent.click(screen.getByRole('button', { name: 'Save' }));
  expect(await screen.findByText('Please enter a valid title')).toBeInTheDocument();
});
```

The Application Test can fail because of routing, store wiring, a missing prop on a child component, a broken interceptor, or a real bug in the checkout flow. The Component Test can only fail because `PostForm` itself is broken. That breadth is why the book puts the bulk of testing effort at the Application layer. One test there replaces a small pile of Component Tests plus their mocking ceremony.

Practical implications for a Vue project:

- **The whole app boots.** Application Tests navigate to a route instead of importing single components. The router and the store run as part of that route.
- **Mock at the network boundary.** Playwright uses `page.route()`, Vitest uses MSW. Don't reach into Pinia or `vi.mock` internal modules.
- **Tests live in `test/specs/`, not next to a component.** Component Tests sit next to source files; Application Tests describe whole user journeys and live separately.
- **Don't test composables, stores, or plugins in isolation.** The Application Test that uses them covers them.

The book's rule of thumb for placement: if you can phrase a test as a user goal ("should be possible to buy a bike"), it is an Application Test. If it reads only as a component contract ("should emit `submit` when the button is clicked"), it is a Component Test. Otherwise it is a Unit Test on an extracted utility.

## How the book structures a test setup

The recommended file layout:

```
project/
├─ src/
│  └─ components/
│     └─ HelloWorld.spec.ts   ← Component Tests live next to source
├─ test/
│  ├─ utils.ts                ← re-exports + custom setup() helper
│  ├─ driver.ts               ← framework-agnostic Driver interface
│  ├─ drivers/
│  │  ├─ vitest/setup.ts      ← Vitest implementation of the Driver
│  │  └─ playwright/          ← Playwright implementation
│  ├─ dsl/                    ← domain helpers (shop, products, …)
│  └─ specs/                  ← Playwright application tests
├─ vitest.config.ts
└─ playwright.config.ts
```

The Vitest config merges the existing Vite config (so build and test stay in sync) and points at a setup file:

```ts
// vitest.config.ts
export default mergeConfig(
  viteConfig,
  defineConfig({
    test: {
      clearMocks: true,
      environment: 'jsdom',
      setupFiles: ['./test/drivers/vitest/setup.ts'],
      coverage: { provider: 'v8', all: true, reporter: ['html', 'text'] },
    },
  }),
);
```

The custom `test/utils.ts` re-exports everything tests need from a single module. That's the first step toward decoupling from the framework:

```ts
// test/utils.ts
export { screen } from '@testing-library/vue';
export { expect, it } from 'vitest';

export const setup = (component, { renderOptions } = {}) => ({
  user: userEvent.setup(),
  ...render(component, renderOptions),
});
```

A Component Test then looks like this. Nothing imports from `vitest` or `@testing-library`:

```ts
// src/components/HelloWorld.spec.ts
it('should render the greeting', async () => {
  setup(HelloWorld, { renderOptions: { props: { msg: 'Hello!' } } });
  expect(await screen.findByText('Hello!')).toBeVisible();
});
```

## The three decoupling principles

The book illustrates each principle with a "before" that resembles a typical Vue test, and an "after" that pushes the coupling into one central file.

**1. Decouple from the test framework** via a **driver interface**. The interface defines what tests can do (`click`, `type`, `findByRole`, `goTo`, …) without committing to Playwright or Vitest:

```ts
// test/driver.ts
export type Interactions = {
  click: () => Promise<void>;
  type: (text: string) => Promise<void>;
};

export type Assertions = {
  shouldBeVisible: () => Promise<void>;
};

export type Driver = {
  findByRole: (role: 'button' | 'link', opts: { name: string })
    => Interactions & Assertions;
  findByText: (text: string) => Assertions;
  goTo: (path: string) => Promise<void>;
};
```

Write one driver implementation per framework. The same Application Test then runs under Playwright when you need real-browser confidence, and under Vitest+jsdom when you need sub-second feedback during a refactor.

**2. Decouple from implementation details.** A Component Test that leaks three different couplings in five lines:

```ts
// ❌ couples to Vue Test Utils, axios, AND HTTP
vi.mock('axios');
const wrapper = mount(ProductList);
axios.get.mockResolvedValue({ data: fakeProducts });
expect(axios.get).toHaveBeenCalledWith('/api/products');
expect(wrapper.text()).toContain('Bread');
```

The same test, decoupled, hides the framework behind `test/utils` and the data layer behind a `hasProducts()` helper that owns the mocking strategy:

```ts
// ✅ no direct mention of axios, HTTP, or vue-test-utils
it('should render a list of products', async () => {
  await hasProducts(['Bread', 'Butter']);
  await render(ProductList);
  expect(await screen.findByText('Bread')).toBeInDocument();
});
```

Swap REST for GraphQL and only `hasProducts` changes. Swap Vitest for Jest and only `test/utils.ts` changes. The book is firm that CSS selectors and `wrapper.vm` access both count as coupling to internals. Replace them with role-based queries and user-style interactions.

**3. Decouple from the UI** with a small **DSL** that mirrors how a domain expert would describe the feature. A checkout test reads like the original user story:

```ts
it('should show the correct total after adding items', async ({ driver }) => {
  const shop = makeShop({ driver });
  await shop.visit();
  await shop.addItemsToCart();
  await shop.goToCheckout();
  await shop.expectTotalSum(199.99);
});
```

Behind the DSL, `shop.addItemsToCart()` calls the driver's `findByRole('button', { name: 'Add to cart' }).click()`. If the UI later changes from a button to a swipe gesture or a voice command, only the DSL implementation changes. The test itself stays identical. The book notes this is overkill for Component Tests, where simplicity beats abstraction.

## On code coverage

The book reads coverage as a diagnostic. Threshold-driven test writing produces high coverage but ties tests to implementation details, which makes refactoring harder. Low coverage signals untested critical paths. Monitor the trend, investigate uncovered lines case-by-case, and don't gate merges on a percentage. Consistent TDD makes high coverage a by-product.

## Further reading from Markus

The book consolidates ideas Markus Oberlehner has been sharpening on his blog for years. These posts map onto the book's themes:

- [Decoupling Component Tests From Implementation Details with Preconditions](https://markus.oberlehner.net/blog/decoupling-component-tests-from-implementation-details-with-preconditions): the direct precursor to the book's DSL layer. Introduces the `hasProducts()`-style "precondition" helpers that hide MSW setup behind reusable, domain-named functions.
- [Telling a Story with Test Code](https://markus.oberlehner.net/blog/telling-a-story-with-test-code): the mindset behind the DSL chapter. Argues that a test should read as a Given/When/Then user story so non-developers can audit it.
- [Using Mock Service Worker with Vitest and fetch](https://markus.oberlehner.net/blog/using-mock-service-worker-with-vitest-and-fetch): a practical companion to the book's mocking chapter. Walks through the MSW + Vitest setup that makes Application Tests runnable in jsdom.
- [Using Testing Library jest-dom with Vitest](https://markus.oberlehner.net/blog/using-testing-library-jest-dom-with-vitest): the matcher setup the book assumes is already working (`toBeInTheDocument`, `toBeVisible`, etc.).
- [Visual Regression Testing With Vitest](https://markus.oberlehner.net/blog/visual-regression-testing-with-vitest): the current illustration of the Vitest + Playwright pairing, using Vitest's browser mode with the Playwright provider for stable snapshots.
- [Using the Wrapper Factory Pattern for Vue.js Unit Testing](https://markus.oberlehner.net/blog/using-the-wrapper-factory-pattern-for-vue-unit-testing): a 2018 piece that, in hindsight, is the seed of the Driver pattern. Useful for seeing the lineage of "always abstract over the test framework".

Markus also publishes free chapter excerpts and follow-up essays on the [Good Vue Tests Substack](https://goodvuetests.substack.com/).

## Talks and videos

Most of Markus Oberlehner's testing talks live on conference channels rather than a personal channel. The recordings below cover the same arguments as the book. Most include live-coded walkthroughs:

- [Writing Good Tests for Vue Applications (Vue.js Live 2023)](https://www.youtube.com/watch?v=lwDueLed9fE): the conference version of the book itself. A live-coded TDD walkthrough that mixes E2E with component tests and frames good tests as the precondition for confident refactoring and Friday deploys.
- [Perfect Vue Test Environment with Playwright and Vitest](https://www.youtube.com/watch?v=MxH3ApkuNMA): the practical setup that backs the book's driver and DSL chapters. Demonstrates running the same tests under Playwright and Vitest by hiding both behind a domain-specific language.
- [Vitest or Cypress? Why not both?! (vuejs.de Conf 2022)](https://www.youtube.com/watch?v=vY9t6hNFhFc): challenges the "Cypress for E2E, Vitest for units" split and argues for combining the two, the foundation of the book's Application-Tests-in-both-runners stance.
- [Writing (Really) Good Tests (Vuejs Amsterdam 2023)](https://www.youtube.com/watch?v=zPGJ4DL4d6A): walks through E2E, integration, unit, and component tests and which to focus on. Mirrors the book's testing-strategy chapters, with decoupling tests from implementation as the central theme.
- [No More Mocking! Write Better Tests For Your Nuxt Application With Contract Tests (Vue.js Live 2024)](https://www.youtube.com/watch?v=2NZmEhuielg): extends the book's mocking chapter into contract testing for Nuxt apps, using Specmatic and OpenAPI stub servers as an alternative to MSW-style mocking for SSR/BFF setups.

---

--- title: Software Testing with Generative AI description: A beginner friendly guide for leveraging AI in software testing practices sourceType: book sourceAuthor: Mark Winteringham tags: ['testing', 'ai', 'book-summary'] url: https://alexop.dev/notes/software-testing-with-generative-ai ---

# Software Testing with Generative AI



## Why I read this book

I read this book to enhance my use of AI in my development workflow. Testing is a crucial part of being a developer. Having worked with an excellent QA Engineer previously, I understand the importance of writing good automated tests while also considering manual testing strategies and exploratory testing. As AI accelerates code production, we need more sophisticated testing techniques.

## What I learned

### AI-Assisted Test Development

GenAi like ChatGPT excels at:

Creating page objects from HTML (a design pattern that creates an abstraction layer for UI testing)[^3]. Example: In Chapter 7, the author demonstrates creating a ContactFormPage class by providing HTML to ChatGPT, which generates a complete Java class with Selenium annotations and interaction methods.

Also ofc to write tests faster or boilerplate code.

### Test Data Generation

LLMs have demonstrated particular strength in:

- Generating and transforming test data effectively
- Integration with OpenAI API for automated data creation
- Creating realistic, diverse test datasets
- Supporting both unit tests and integration testing
- Automatically seeding test data via SQL statements

The book suggests integrating OpenAI's API directly into the testing pipeline to generate synthetic test data dynamically. While innovative, I'm somewhat skeptical about the practicality - introducing API calls to an LLM during test execution could introduce unnecessary complexity and potential failure points.

A more pragmatic approach might be using AI tools during development to generate a comprehensive test dataset that can be committed to the codebase.
I would not recommend this approach, as there are enough tools available that generate good test data without the complications of LLMs.
The most elegant solution would probably be to use property-based testing.[^1]

### Test Planning & Analysis

With well-crafted prompts[^4], AI can effectively identify risks and generate viable test plans. You can directly convert tickets into comprehensive test plans. Using advanced techniques like RAG and fine-tuning, you can further automate this process. The basic approach involves:

1. Setting up a chat interface
2. Using RAG to provide the AI with necessary knowledge
3. Implementing fine-tuning to enhance accuracy
4. Querying with questions like "What are the risks of Ticket-12345?"

### Best Prompt from the Book

The book's standout prompt focuses on test data generation, applicable for various data generation needs including SQL statements. Here's the prompt:

```
You are a JSON data generator. Generate 5 JSON objects in an array and check that 5
JSON objects have been created before outputting the results.

We use different delimiters to set out the rules for our data requirements:

* Each parameter is identified with a % sign.
* Each column is described in order of key, value data type and options using the |
sign.
* If a column data option says random, randomize data based on the suggested format
and column name.

Here are the instructions:

% room_name | string | random
% type | string | 'single' or 'double'
% beds | integer | 1 to 6
% accessible | boolean | true or false
% image | string | random url
% description | string | random max 20 characters
% features | array[string] | 'Wifi', 'TV' or 'Safe'
% roomPrice | integer | 100 to 200
```

## My Rating

The book provides excellent introductory content on AI-assisted testing, making it valuable for both developers and engineers. The advanced topics covering AI Agents, RAG, and fine-tuning felt somewhat disconnected and could warrant a separate book. Including a concrete example of how traditional Scrum workflows might evolve with prompt engineering[^4] would have enhanced the content.

Despite these minor critiques, it's highly recommended for beginners.

- ⭐⭐⭐⭐ (4/5).

---

## Footnotes

[^3]:
    **Page Object Pattern Resources**  
    Martin Fowler's [definitive article on Page Objects](https://martinfowler.com/bliki/PageObject.html) explains the pattern's core principles and best practices. For practical implementations, the [Playwright Page Object Model](https://playwright.dev/docs/pom) provides official guidance with TypeScript examples and reusable components. Additionally, [WebdriverIO Page Objects](https://webdriver.io/docs/pageobjects/) offers comprehensive implementation guides with modern JavaScript patterns.

[^1]:
    **Property-Based Testing**  
    [fast-check](https://github.com/dubzzz/fast-check) is a property-based testing framework for JavaScript/TypeScript that provides excellent TypeScript support, integrated shrinking capabilities, and built-in async/await support.

[^4]:
    **Prompt Engineering Resources**  
    The [Prompt Engineering Guide](https://www.promptingguide.ai/) offers comprehensive guidance for prompt engineering, including best practices, practical examples, and multi-language support.

---

================================================================================
# PROMPTS
================================================================================

--- title: Add Prompt: Quick Prompt Collection Entry description: Quickly add new prompts to the blog's prompts collection with auto-generated frontmatter tool: claude category: instruction tags: ['prompts', 'workflow', 'automation', 'claude-code'] url: https://alexop.dev/prompts/claude/claude-add-prompt-command ---

# Add Prompt: Quick Prompt Collection Entry

description: Add a new prompt to the blog's prompts collection with auto-generated frontmatter
argument-hint: [paste raw prompt content]
model: sonnet
allowed-tools: Read, Write, Glob, AskUserQuestion

# Add Prompt to Collection

Add a new prompt to `src/content/prompts/` with properly generated frontmatter.

## Phase 1: Parse Input

The user will provide raw prompt content. This typically includes:
- A YAML config block with: description, allowed-tools, model, argument-hint
- Markdown instructions/body

Extract:
1. **name**: From the heading or first line (e.g., "# Learn from Conversation" → "learn")
2. **description**: From the YAML `description` field
3. **model**: From the YAML `model` field
4. **allowed-tools**: From the YAML `allowed-tools` field

## Phase 2: Generate Frontmatter

Create the primary frontmatter block for the prompts collection:

```yaml
---
title: "{Title Case Name}: {Brief Purpose}"
pubDatetime: {today's date}T00:00:00Z
tool: "claude"
category: "{skill|instruction|prompt|agent}"  # Infer from content
tags: [{extract relevant keywords}]
description: "{from input description}"
useCase: "{derive from when/how to use}"
modelVersion: "{from model field, formatted nicely}"
expectedOutput: "{infer from the prompt's goal}"
draft: false
---
```

**Category inference:**
- Has `allowed-tools` + specific workflow → "instruction"
- Has `name:` field in YAML → "skill"
- Simple prompt without execution config → "prompt"
- Describes an autonomous agent → "agent"

## Phase 3: Generate Filename

Format: `claude-{kebab-case-name}-command.md`

Examples:
- "Learn" → `claude-learn-command.md`
- "Fix Pipeline" → `claude-fix-pipeline-command.md`
- "Create Skill" → `claude-create-skill.md`

## Phase 4: Present Draft

Show the complete file content:
1. The generated primary frontmatter
2. The original skill config YAML block (preserved as-is)
3. The original prompt body (preserved as-is)

Ask: "Ready to create `{filename}`?"

## Phase 5: Create File

After user approval:
1. Write to `src/content/prompts/{filename}`
2. Confirm creation with path

---

--- title: Conventional Commit description: Slash command to create conventional commit messages and commit staged changes following the conventional commits specification tool: claude category: instruction tags: ['git', 'commit', 'conventional-commits', 'automation', 'workflow'] url: https://alexop.dev/prompts/claude/claude-conventional-commit ---

# Conventional Commit


description: Create a conventional commit message and commit staged changes
allowed-tools: Bash(git status), Bash(git diff), Bash(git log), Bash(git add), Bash(git commit)
model: haiku


# Conventional Commit

I have gathered information about your changes. Here are the results:

<git_status>
!`git status`
</git_status>

<staged_diff>
!`git diff --cached`
</staged_diff>

<unstaged_diff>
!`git diff`
</unstaged_diff>

<recent_commits>
!`git log --oneline -10`
</recent_commits>

## Instructions

1. **Analyze the diffs** above to understand what changed.
2. **Stage files** if needed (skip already staged files, skip files that shouldn't be committed like `.env`).
3. **Generate a conventional commit message** following this format:
   ```
   <type>(<scope>): <description>

   [optional body]
   ```

   Types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`

4. **Create the commit** using a HEREDOC for proper formatting:
   ```bash
   git commit -m "$(cat <<'EOF'
   type(scope): description
   EOF
   )"
   ```

5. **Show the result** with `git log -1` to confirm.

---

--- title: Create Agent Command description: Slash command to create custom subagents for specialized tasks with proper configuration and system prompts tool: claude category: instruction tags: ['agent', 'automation', 'claude-code', 'subagent'] url: https://alexop.dev/prompts/claude/claude-create-agent ---

# Create Agent Command


description: Create a new custom subagent for specialized tasks
argument-hint: [name] [description]


## /create-agent

## Purpose

Create a new custom subagent (skill) for specialized tasks with proper configuration and system prompts.

## Contract

**Inputs:**

- `$1` — AGENT_NAME (lowercase, kebab-case, e.g., "code-reviewer")
- `$2` — DESCRIPTION (when this agent should be invoked, e.g., "Expert code reviewer. Use proactively after code changes.")
- `--user` — Create user-level agent in `~/.claude/agents/` (default: project-level in `.claude/agents/`)
- `--tools` — Comma-separated list of tools (e.g., "Read,Grep,Glob,Bash")
- `--model` — Model to use: "sonnet", "opus", "haiku", or "inherit" (default: sonnet)

**Outputs:**

- `STATUS=<CREATED|EXISTS|FAIL> PATH=<path> AGENT=<name>`

## Instructions

1. **Validate inputs:**
   - Agent name must be lowercase, kebab-case only
   - Description must be non-empty and descriptive
   - If `--tools` specified, validate tool names against available tools
   - If `--model` specified, validate it's one of: sonnet, opus, haiku, inherit

2. **Determine file location:**
   - Default: `.claude/agents/{AGENT_NAME}.md` (project-level)
   - With `--user`: `~/.claude/agents/{AGENT_NAME}.md` (user-level)
   - Create directory if it doesn't exist

3. **Check for existing agent:**
   - If file exists, output `STATUS=EXISTS` and exit
   - Recommend using `/agents` command to edit existing agents

4. **Generate agent file content:**

   ```markdown
   ---
   name: { AGENT_NAME }
   description: { DESCRIPTION }
   tools: { TOOLS } # Optional - only include if specified
   model: { MODEL } # Optional - only include if specified
   ---

   You are a specialized agent for {purpose based on description}.

   When invoked:

   1. Understand the specific task or problem
   2. Analyze the relevant context
   3. Execute your specialized function
   4. Provide clear, actionable results

   Key responsibilities:

   - {Responsibility 1 based on description}
   - {Responsibility 2 based on description}
   - {Responsibility 3 based on description}

   Best practices:

   - Be focused and efficient
   - Provide specific, actionable feedback
   - Document your reasoning
   - Follow established patterns and conventions

   For each task:

   - Explain your approach
   - Show your work
   - Highlight key findings or changes
   - Suggest next steps if applicable
   ```

5. **Write the file:**
   - Create the agent file with proper frontmatter
   - Ensure proper formatting and indentation
   - Set appropriate file permissions

6. **Output result:**
   - Print: `STATUS=CREATED PATH={path} AGENT={name}`
   - Provide usage example: `Use the {name} agent to...`

## Examples

### Basic project-level agent

```bash
/create-skill code-reviewer "Expert code review specialist. Use proactively after code changes."
# Output: STATUS=CREATED PATH=.claude/agents/code-reviewer.md AGENT=code-reviewer
```

### User-level agent with specific tools

```bash
/create-skill debugger "Debugging specialist for errors and test failures" --user --tools "Read,Edit,Bash,Grep,Glob"
# Output: STATUS=CREATED PATH=~/.claude/agents/debugger.md AGENT=debugger
```

### Agent with specific model

```bash
/create-skill data-scientist "Data analysis expert for SQL queries and insights" --tools "Bash,Read,Write" --model "sonnet"
# Output: STATUS=CREATED PATH=.claude/agents/data-scientist.md AGENT=data-scientist
```

## Constraints

- Idempotent: Won't overwrite existing agents
- No network access required
- Agent names must follow naming conventions
- Tools list must match available Claude Code tools
- Model must be valid alias or 'inherit'

## Best Practices

- Use descriptive, action-oriented descriptions
- Include "use PROACTIVELY" in description for automatic invocation
- Start with Claude-generated agents via `/agents` for complex cases
- Limit tools to only what the agent needs
- Design focused agents with single, clear responsibilities
- Add to version control for team collaboration

## Related Commands

- `/agents` - Interactive interface for managing agents (recommended for editing)
- Use created agents: "Use the {name} agent to..."
- Invoke explicitly: "Ask the {name} agent to investigate..."

---

--- title: Create Command description: Slash command to generate properly structured slash command files for Claude Code with standardized structure tool: claude category: instruction tags: ['slash-command', 'automation', 'claude-code', 'workflow'] url: https://alexop.dev/prompts/claude/claude-create-command ---

# Create Command


description: Create new slash commands with standardized structure
argument-hint: [name] [purpose]
allowed-tools: Bash(mkdir:_), Bash(tee:_), Bash(test:\*)


## /create-command

## Purpose

Generate properly structured slash command files for Claude Code.

## Contract

**Inputs:**

- `$1` — COMMAND_NAME (lowercase, kebab-case, verb-first)
- `$2` — PURPOSE (command description)

**Outputs:**

- `STATUS=<WROTE> PATH=<path>`

## Instructions

1. **Validate inputs:**
   - Command name: lowercase, kebab-case only
   - Purpose: non-empty string

2. **Generate file content** using this template:

```markdown
---
description: { { PURPOSE } }
argument-hint: [args...]
---

# /{{COMMAND_NAME}}

## Purpose

{{PURPOSE}}

## Contract

**Inputs:** `$ARGUMENTS` — command arguments
**Outputs:** `STATUS=<OK|FAIL> [key=value ...]`

## Instructions

1. **Validate inputs:**
   - Check that required arguments are provided
   - Validate argument format/values

2. **Execute the command:**

\`\`\`bash

# Add specific bash commands here

# Example: git worktree add path/to/worktree branch-name

\`\`\`

3. **Output status:**
   - Print `STATUS=OK` on success
   - Print `STATUS=FAIL ERROR="message"` on failure

## Constraints

- Idempotent and deterministic
- No network tools by default
- Minimal console output (STATUS line only)
```

3. **Output:**
   - Show preview in fenced markdown block
   - Create `.claude/commands/` dir and write file atomically
   - Print: `STATUS=WROTE PATH=.claude/commands/{{COMMAND_NAME}}.md`

## Example

```bash
/create-command analyze-deps "Analyze dependencies for outdated packages"
# Output: STATUS=WROTE PATH=.claude/commands/analyze-deps.md
```

---

--- title: Create Hook description: Slash command to create and configure Claude Code hooks with reference documentation and interactive guidance tool: claude category: instruction tags: ['hooks', 'automation', 'claude-code', 'workflow', 'event-driven'] url: https://alexop.dev/prompts/claude/claude-create-hook ---

# Create Hook


description: Create a new custom subagent for specialized tasks
argument-hint: [name] [description]


## /create-agent

## Purpose

Create a new custom subagent (skill) for specialized tasks with proper configuration and system prompts.

## Contract

**Inputs:**

- `$1` — AGENT_NAME (lowercase, kebab-case, e.g., "code-reviewer")
- `$2` — DESCRIPTION (when this agent should be invoked, e.g., "Expert code reviewer. Use proactively after code changes.")
- `--user` — Create user-level agent in `~/.claude/agents/` (default: project-level in `.claude/agents/`)
- `--tools` — Comma-separated list of tools (e.g., "Read,Grep,Glob,Bash")
- `--model` — Model to use: "sonnet", "opus", "haiku", or "inherit" (default: sonnet)

**Outputs:**

- `STATUS=<CREATED|EXISTS|FAIL> PATH=<path> AGENT=<name>`

## Instructions

1. **Validate inputs:**
   - Agent name must be lowercase, kebab-case only
   - Description must be non-empty and descriptive
   - If `--tools` specified, validate tool names against available tools
   - If `--model` specified, validate it's one of: sonnet, opus, haiku, inherit

2. **Determine file location:**
   - Default: `.claude/agents/{AGENT_NAME}.md` (project-level)
   - With `--user`: `~/.claude/agents/{AGENT_NAME}.md` (user-level)
   - Create directory if it doesn't exist

3. **Check for existing agent:**
   - If file exists, output `STATUS=EXISTS` and exit
   - Recommend using `/agents` command to edit existing agents

4. **Generate agent file content:**

   ```markdown
   ---
   name: { AGENT_NAME }
   description: { DESCRIPTION }
   tools: { TOOLS } # Optional - only include if specified
   model: { MODEL } # Optional - only include if specified
   ---

   You are a specialized agent for {purpose based on description}.

   When invoked:

   1. Understand the specific task or problem
   2. Analyze the relevant context
   3. Execute your specialized function
   4. Provide clear, actionable results

   Key responsibilities:

   - {Responsibility 1 based on description}
   - {Responsibility 2 based on description}
   - {Responsibility 3 based on description}

   Best practices:

   - Be focused and efficient
   - Provide specific, actionable feedback
   - Document your reasoning
   - Follow established patterns and conventions

   For each task:

   - Explain your approach
   - Show your work
   - Highlight key findings or changes
   - Suggest next steps if applicable
   ```

5. **Write the file:**
   - Create the agent file with proper frontmatter
   - Ensure proper formatting and indentation
   - Set appropriate file permissions

6. **Output result:**
   - Print: `STATUS=CREATED PATH={path} AGENT={name}`
   - Provide usage example: `Use the {name} agent to...`

## Examples

### Basic project-level agent

```bash
/create-skill code-reviewer "Expert code review specialist. Use proactively after code changes."
# Output: STATUS=CREATED PATH=.claude/agents/code-reviewer.md AGENT=code-reviewer
```

### User-level agent with specific tools

```bash
/create-skill debugger "Debugging specialist for errors and test failures" --user --tools "Read,Edit,Bash,Grep,Glob"
# Output: STATUS=CREATED PATH=~/.claude/agents/debugger.md AGENT=debugger
```

### Agent with specific model

```bash
/create-skill data-scientist "Data analysis expert for SQL queries and insights" --tools "Bash,Read,Write" --model "sonnet"
# Output: STATUS=CREATED PATH=.claude/agents/data-scientist.md AGENT=data-scientist
```

## Constraints

- Idempotent: Won't overwrite existing agents
- No network access required
- Agent names must follow naming conventions
- Tools list must match available Claude Code tools
- Model must be valid alias or 'inherit'

## Best Practices

- Use descriptive, action-oriented descriptions
- Include "use PROACTIVELY" in description for automatic invocation
- Start with Claude-generated agents via `/agents` for complex cases
- Limit tools to only what the agent needs
- Design focused agents with single, clear responsibilities
- Add to version control for team collaboration

## Related Commands

- `/agents` - Interactive interface for managing agents (recommended for editing)
- Use created agents: "Use the {name} agent to..."
- Invoke explicitly: "Ask the {name} agent to investigate..."

---

--- title: Create CLAUDE.md Documentation description: Slash command to analyze project structure and generate CLAUDE.md files for project documentation and coding guidelines tool: claude category: instruction tags: ['documentation', 'claude-code', 'project-setup', 'automation'] url: https://alexop.dev/prompts/claude/claude-create-md ---

# Create CLAUDE.md Documentation


description: Generate CLAUDE.md files for project and key subdirectories
argument-hint: [thoroughness: quick|medium|very-thorough]


## /create-md

## Purpose

Analyze project structure using the Explore subagent and generate CLAUDE.md files—one global file describing the project in general, plus nested CLAUDE.md files in important subdirectories for localized context.

## Contract

**Inputs:**

- `$1` — THOROUGHNESS (optional: `quick`, `medium`, `very-thorough`; default: `medium`)

**Outputs:**

- `STATUS=<OK|FAIL>`
- `FILES=<list of created CLAUDE.md paths>`

## Instructions

1. **Explore the project structure** using the Task tool with `subagent_type=Explore`:
   - Understand the overall architecture and technology stack
   - Identify key directories (e.g., `/src`, `/frontend`, `/backend`, `/services`, `/packages`)
   - Find existing setup/build/test commands (package.json, Makefile, etc.)
   - Detect coding conventions (ESLint, Prettier, etc.)
   - Map out the project structure

2. **Create root CLAUDE.md** with:
   - Project overview and architecture map
   - Setup, run, and test commands
   - Code style and conventions
   - Workflow and review expectations
   - Safety guardrails (no secrets, env vars, etc.)
   - Examples of good changes

3. **Create nested CLAUDE.md files** in subdirectories where useful:
   - For monorepo packages/apps with different tech stacks
   - For frontend/backend splits
   - For specialized modules with unique conventions
   - Keep them focused and scoped to that directory's context

4. **Output results**:
   - Print created file paths
   - Print: `STATUS=OK FILES=<comma-separated paths>`

## What to include in CLAUDE.md files

### Root CLAUDE.md

```md
# CLAUDE.md — Project rules

## Overview

One-liner + architecture map.

## Setup & Run

- Install: [command]
- Start dev: [command]
- Tests: [command]

## Code Style

- Linting/formatting tools and configs
- Commit style (Conventional Commits, etc.)

## Safety rails

- Never commit secrets; use .env.example
- Don't modify generated files

## Workflow

- For bugfixes: write failing test → fix → link issue
- For features: create RFC before code

## Examples

- See /docs/examples for typical PRs
```

### Nested CLAUDE.md (e.g., `/frontend/CLAUDE.md`)

```md
# Frontend — Local rules

## Stack

Next.js 14, TypeScript, TailwindCSS

## Key directories

- `/app` — App router pages
- `/components` — Reusable UI components
- `/lib` — Utilities and helpers

## Conventions

- Components: PascalCase, one per file
- Hooks: camelCase, prefix with `use`
- Server components by default; add 'use client' when needed

## Testing

- Run: pnpm test:frontend
- Write tests alongside components (\*.test.tsx)
```

## Constraints

- Use the Explore subagent (Task tool) for analysis
- Keep CLAUDE.md files concise and actionable
- Only create nested files where they add value
- Link to existing docs rather than duplicating content

## Example usage

```bash
# Quick exploration and basic CLAUDE.md files
/create-md quick

# Medium depth (default)
/create-md

# Very thorough analysis with comprehensive CLAUDE.md files
/create-md very-thorough
```

---

--- title: Create Output Style description: Slash command to generate custom output styles that modify Claude Code's system prompt for different agent behaviors tool: claude category: instruction tags: ['output-style', 'customization', 'claude-code', 'behavior'] url: https://alexop.dev/prompts/claude/claude-create-output-style ---

# Create Output Style


description: Generate custom output styles that modify Claude Code's system prompt for different agent behaviors
argument-hint: [style-name] [--user|--project] [--description "..."]


## /create-output-style

## Purpose

Generate custom output style files for Claude Code with proper structure and YAML frontmatter.

## Contract

**Inputs:**

- `$1` — STYLE_NAME (optional: name for the output style)
- `--user` — Save to user-level directory (~/.claude/output-styles)
- `--project` — Save to project-level directory (.claude/output-styles)
- `--description "..."` — Brief description of the output style

**Outputs:** `STATUS=<OK|FAIL> PATH=<path> SCOPE=<user|project>`

## Instructions

1. **Determine scope:**
   - If `--user` is provided: save to `~/.claude/output-styles/`
   - If `--project` is provided: save to `.claude/output-styles/`
   - Default: `--user` (user-level)

2. **Gather information:**
   - If STYLE_NAME not provided, ask user for the style name
   - If description not provided via `--description`, ask user what behavior they want
   - Style name should be title-cased (e.g., "My Custom Style")

3. **Generate output style file** using this template:

```markdown
---
name: { { STYLE_NAME } }
description: { { DESCRIPTION } }
---

# {{STYLE_NAME}} Instructions

You are an interactive CLI tool that helps users with software engineering tasks.

{{CUSTOM_INSTRUCTIONS}}

## Specific Behaviors

{{SPECIFIC_BEHAVIORS}}

## Key Principles

- {{PRINCIPLE_1}}
- {{PRINCIPLE_2}}
- {{PRINCIPLE_3}}
```

4. **Create the file:**
   - Convert style name to kebab-case for filename (e.g., "My Custom Style" → "my-custom-style.md")
   - Create target directory if it doesn't exist
   - Write the file
   - Print: `STATUS=OK PATH=<full-path> SCOPE=<user|project>`

5. **Inform user:**
   - Let them know the file was created
   - Remind them they can activate it with `/output-style [style-name]`
   - Mention they can edit the file directly to refine the instructions

## Examples

**Example 1: Basic usage**

```bash
/create-output-style
# Claude will ask for style name and description interactively
```

**Example 2: Full specification**

```bash
/create-output-style "Teaching Assistant" --project --description "Explains concepts step by step with examples"
# STATUS=OK PATH=.claude/output-styles/teaching-assistant.md SCOPE=project
```

**Example 3: User-level style**

```bash
/create-output-style "Code Reviewer" --user --description "Focuses on thorough code review with best practices"
# STATUS=OK PATH=~/.claude/output-styles/code-reviewer.md SCOPE=user
```

## Notes

- Output styles modify Claude Code's system prompt completely
- Non-default styles exclude standard code generation instructions
- User-level styles are available across all projects
- Project-level styles are specific to the current project
- You can manually edit the generated files to refine instructions

---

--- title: Create Plugin description: Slash command to convert a project into a properly structured Claude Code plugin with marketplace configuration tool: claude category: instruction tags: ['plugin', 'claude-code', 'packaging', 'distribution'] url: https://alexop.dev/prompts/claude/claude-create-plugin ---

# Create Plugin


description: Convert a project into a Claude Code plugin
argument-hint: [project-path]


## /create-plugin

## Purpose

Guide users through converting an existing project into a properly structured Claude Code plugin, following official documentation standards.

## Contract

**Inputs:** `[project-path]` — Optional path to project directory (defaults to current directory)
**Outputs:** `STATUS=<OK|FAIL> PLUGIN_PATH=<path>`

## Instructions

1. **Analyze the project structure:**
   - Identify existing components that could become plugin features
   - Check for slash commands, agents, skills, hooks, or MCP integrations
   - Review documentation files

2. **Create plugin and marketplace structure:**
   - Create `.claude-plugin/` directory at project root
   - Generate `plugin.json` manifest with proper metadata:
     - name (lowercase, kebab-case)
     - description
     - version (semantic versioning)
     - author information (object with name and optional url)
     - repository (string URL, not object)
     - license (optional)
   - Generate `marketplace.json` in the same directory with:
     - marketplace name
     - owner information
     - plugins array with source reference `"./"` (self-reference)

3. **Organize plugin components:**
   - `commands/` - Slash command markdown files
   - `agents/` - Agent definition markdown files
   - `skills/` - Agent Skills with SKILL.md files
   - `hooks/` - hooks.json for event handlers
   - `.mcp.json` - MCP server configurations (if applicable)

4. **Generate documentation:**
   - Create/update README.md with:
     - Installation instructions
     - Usage examples
     - Component descriptions
     - Testing guidance

5. **Provide testing workflow:**
   - Local marketplace setup commands
   - Installation verification steps
   - Iteration and debugging guidance

## Reference Documentation

Follow the official Claude Code plugin and marketplace structure:

```
my-plugin/
├── .claude-plugin/
│   ├── marketplace.json      # Marketplace manifest
│   └── plugin.json          # Plugin metadata
├── commands/                 # Custom slash commands (optional)
│   └── command-name.md
├── agents/                   # Custom agents (optional)
│   └── agent-name.md
├── skills/                   # Agent Skills (optional)
│   └── skill-name/
│       └── SKILL.md
├── hooks/                    # Event handlers (optional)
│   └── hooks.json
├── .mcp.json                # MCP servers (optional)
└── README.md                # Documentation
```

## Plugin Manifest Template

The plugin.json file MUST be created at `<plugin-dir>/.claude-plugin/plugin.json`:

```json
{
  "name": "plugin-name",
  "version": "1.0.0",
  "description": "Plugin description",
  "author": {
    "name": "Author Name",
    "url": "https://github.com/username"
  },
  "repository": "https://github.com/username/plugin-name",
  "license": "MIT"
}
```

**Important:** The `repository` field must be a string URL, not an object. Using an object format like `{"type": "git", "url": "..."}` will cause validation errors.

## Marketplace Manifest Template

The marketplace.json file MUST be created at `<plugin-dir>/.claude-plugin/marketplace.json` alongside plugin.json:

```json
{
  "name": "marketplace-name",
  "owner": {
    "name": "Owner Name"
  },
  "plugins": [
    {
      "name": "plugin-name",
      "source": "./",
      "description": "Plugin description"
    }
  ]
}
```

## Key Guidelines

- **Plugin manifest**: Use semantic versioning, clear descriptions
- **Marketplace manifest**: MUST create marketplace.json in the same .claude-plugin/ directory alongside plugin.json
- **Commands**: Markdown files with frontmatter (description, argument-hint)
- **Skills**: Create subdirectories with SKILL.md files
- **Testing**: Use local marketplace for iterative development
- **Documentation**: Include installation, usage, and examples

## Constraints

- Must create valid plugin.json schema in .claude-plugin/ directory
- Must create valid marketplace.json schema in the same .claude-plugin/ directory
- The repository field in plugin.json MUST be a string URL, not an object
- Follow kebab-case naming conventions
- Include proper frontmatter in all markdown files
- Marketplace source must reference "./" to point to the plugin directory itself
- Output final STATUS line with plugin path

## Example Output

```
Created plugin structure at: ./my-plugin
Generated components:
  - .claude-plugin/plugin.json
  - .claude-plugin/marketplace.json
  - commands/helper.md
  - README.md

Next steps:
1. cd my-plugin && claude
2. /plugin marketplace add .
3. /plugin install my-plugin@my-plugin-dev

Or for GitHub-based installation:
1. Push to GitHub repository
2. /plugin marketplace add username/my-plugin
3. /plugin install my-plugin@my-plugin-dev

STATUS=OK PLUGIN_PATH=./my-plugin
```

---

--- title: Create Skill description: Slash command to generate new Claude Skills with proper structure, YAML frontmatter, and bundled resources tool: claude category: instruction tags: ['skill', 'claude-code', 'automation', 'agent'] url: https://alexop.dev/prompts/claude/claude-create-skill ---

# Create Skill


description: Generate a new Claude Skill with proper structure and YAML frontmatter using official documentation as reference
argument-hint: [skill-name] [description]


## /create-skill

## Purpose

Generate a new Claude Skill with proper structure and YAML frontmatter using official documentation as reference

## Contract

**Inputs:**

- `$1` — SKILL_NAME (lowercase, kebab-case, max 64 characters)
- `$2` — DESCRIPTION (what the skill does and when to use it, max 1024 characters)
- `--personal` — create in ~/.claude/skills/ (default)
- `--project` — create in .claude/skills/

**Outputs:** `STATUS=<CREATED|EXISTS|FAIL> PATH=<path>`

## Instructions

1. **Validate inputs:**
   - Skill name: lowercase letters, numbers, hyphens only (max 64 chars)
   - Description: non-empty, max 1024 characters, no angle brackets (< or >)
   - Description should include both WHAT the skill does and WHEN to use it
   - If user provides additional frontmatter properties, validate against allowed list:
     - **Allowed:** name, description, license, allowed-tools, metadata
     - **Warning** (not error) for unexpected properties like version, author, tags
     - Inform user that unexpected properties may cause issues during packaging

2. **Determine target directory:**
   - Personal (default): `~/.claude/skills/{{SKILL_NAME}}/`
   - Project: `.claude/skills/{{SKILL_NAME}}/`

3. **Check if skill already exists:**
   - If exists: output `STATUS=EXISTS PATH=<path>` and stop

4. **Analyze what bundled resources this skill needs:**

   Based on the skill name and description, intelligently determine which bundled resources would be valuable:

   **Create scripts/ directory when:**
   - Skill involves file manipulation (PDF, images, documents, etc.)
   - Skill requires deterministic operations (data processing, conversions)
   - Same code would be rewritten repeatedly
   - Examples: pdf-editor, image-processor, data-analyzer, file-converter

   **Create references/ directory when:**
   - Skill needs reference documentation (API docs, schemas, specifications)
   - Detailed information would make SKILL.md too long (>5k words)
   - Domain knowledge needs to be documented (company policies, standards)
   - Examples: api-client, database-query, brand-guidelines, coding-standards

   **Create assets/ directory when:**
   - Skill uses templates or boilerplate code
   - Skill needs brand assets (logos, fonts, images)
   - Skill creates documents from templates (presentations, reports)
   - Examples: frontend-builder, brand-guidelines, document-generator, presentation-maker

   **Questions to ask user for clarification (only if unclear):**
   - "Will this skill need to run any scripts repeatedly?" (→ scripts/)
   - "Does this skill need reference documentation like API docs or schemas?" (→ references/)
   - "Will this skill use templates or assets like logos/fonts/boilerplate?" (→ assets/)

   **Communicate the decision:**
   After analysis, inform the user which directories will be created and why:
   - Example: "Based on the description, I'll create scripts/ for PDF manipulation utilities and references/ for schema documentation."
   - Be transparent about the reasoning
   - It's better to include a directory with placeholders than to omit one that might be needed

5. **Create skill directory structure based on analysis:**

   Always create:

   ```
   {{SKILL_NAME}}/
   └── SKILL.md (required)
   ```

   Conditionally create based on Step 4 analysis:

   ```
   ├── scripts/ (if determined needed)
   │   └── example.py (executable placeholder with TODO)
   ├── references/ (if determined needed)
   │   └── README.md (documentation placeholder with guidance)
   └── assets/ (if determined needed)
       └── README.md (asset placeholder with examples)
   ```

6. **Generate SKILL.md using this template:**

   ```markdown
   ---
   name: { { SKILL_NAME } }
   description: { { DESCRIPTION } }
   # Optional fields (uncomment if needed):
   # allowed-tools: ["Read", "Write", "Bash"]  # Restrict to specific tools
   # metadata:
   #   category: "development"
   #   version: "1.0.0"  # For tracking in your project
   # license: "MIT"  # For shared skills
   ---

   # {{Title Case Skill Name}}

   ## Overview

   [TODO: 1-2 sentences explaining what this skill does and why it's valuable]

   ## When to Use

   [TODO: Specific triggers and scenarios where this skill should be invoked]

   ## Structuring This Skill

   Choose an organizational pattern:

   **Workflow-Based** (sequential) - TDD workflows, git commits, deployments

   - Structure: Overview → Step 1 → Step 2 → Step 3...

   **Task-Based** (operations) - File tools, API operations, data transforms

   - Structure: Overview → Quick Start → Operation A → Operation B...

   **Reference-Based** (guidelines) - Brand standards, coding rules, checklists

   - Structure: Overview → Guidelines → Specifications → Examples

   **Capabilities-Based** (integrated) - Product management, debugging, systems

   - Structure: Overview → Core Capabilities → Feature 1 → Feature 2...

   Patterns can be mixed. Delete this section after choosing.

   [TODO: Delete this "Structuring This Skill" section after choosing your approach]

   ## Instructions

   [TODO: Provide clear, step-by-step guidance using imperative/infinitive language]

   [TODO: Reference any bundled resources (scripts, references, assets) so Claude knows how to use them]

   Example structure:

   1. First major step
   2. Second major step
   3. Third major step

   ## Bundled Resources

   [TODO: Document bundled resources. Delete unused subsections.]

   **scripts/** - Executable code run directly (not loaded into context)

   - Example: `scripts/process_data.py` - Processes CSV and generates reports

   **references/** - Documentation loaded into context when needed

   - Example: `references/api_docs.md` - API endpoint documentation

   **assets/** - Files used in output (not loaded into context)

   - Example: `assets/template.pptx` - Presentation template

   ## Examples

   [TODO: Show concrete examples with realistic user requests]
   ```

   User: "Help me [specific task]"
   Claude: [How the skill responds]

   ```

   ## Progressive Disclosure

   Keep SKILL.md <5k words. Move detailed info to references/. Three-level loading:
   1. Metadata (~100 words) - Always in context
   2. SKILL.md - Loaded when triggered
   3. Bundled resources - Loaded as needed
   ```

7. **Create bundled resource placeholders (based on Step 4 analysis):**

   For each directory determined in Step 4, create appropriate placeholder files:

   **scripts/** → Create `scripts/example.py` (executable Python template with TODO comment)
   **references/** → Create `references/README.md` (documentation template explaining purpose)
   **assets/** → Create `assets/README.md` (asset placeholder explaining common types)

   Make scripts executable: `chmod +x scripts/*.py`

8. **Follow official guidelines:**
   - Name: lowercase, numbers, hyphens only (max 64 chars)
   - Description: Include triggers and use cases (max 1024 chars)
   - Instructions: Clear, step-by-step guidance
   - Keep skills focused on single capabilities
   - Make descriptions specific with trigger keywords

9. **Output:**
   - Print: `STATUS=CREATED PATH={{full_path}}`
   - Summarize what was created and why (list directories + reasoning)
   - Remind user to populate placeholders and complete [TODO] items

## Constraints

- Skills are model-invoked (Claude decides when to use them)
- Description must be specific enough for Claude to discover when to use it
- One skill = one capability (stay focused)
- Use forward slashes in all file paths
- Valid YAML syntax required in frontmatter

## Frontmatter Properties

**Required:**

- `name` - Lowercase hyphen-case identifier (max 64 chars, matches directory name)
- `description` - What it does + when to use it (max 1024 chars, no angle brackets)

**Optional:**

- `allowed-tools: ["Read", "Write", "Bash"]` - Restrict Claude to specific tools
- `metadata: {category: "dev", version: "1.0"}` - Custom tracking fields
- `license: "MIT"` - License for shared skills

**Prohibited** (causes warnings):

- `version`, `author`, `tags` - Use metadata or description instead

## Examples

**Simple workflow skill:**

```bash
/create-skill commit-helper "Generate clear git commit messages from diffs. Use when writing commits or reviewing staged changes."
```

_Claude will determine: No bundled resources needed - just workflow guidance_

**File manipulation skill:**

```bash
/create-skill pdf-processor "Extract text and tables from PDF files. Use when working with PDFs, forms, or document extraction."
```

_Claude will determine: Needs scripts/ directory for PDF manipulation utilities_

**API integration skill:**

```bash
/create-skill api-client "Make REST API calls and handle responses. Use for API testing and integration work with the company API."
```

_Claude will determine: Needs references/ directory for API documentation and schemas_

**Image processing skill:**

```bash
/create-skill image-processor "Resize, rotate, and convert images. Use when editing images or batch processing files."
```

_Claude will determine: Needs scripts/ directory for image manipulation operations_

**Brand guidelines skill:**

```bash
/create-skill brand-guidelines "Apply company brand guidelines to designs. Use when creating presentations, documents, or marketing materials."
```

_Claude will determine: Needs references/ for guidelines + assets/ for logos, fonts, templates_

**Frontend builder skill:**

```bash
/create-skill frontend-builder "Build responsive web applications with React. Use when creating new frontend projects or components." --project
```

_Claude will determine: Needs scripts/ for build tools + assets/ for boilerplate templates_

**Database query skill:**

```bash
/create-skill database-query "Query and analyze database tables. Use when working with SQL, BigQuery, or data analysis tasks." --project
```

_Claude will determine: Needs references/ for schema documentation_

**How Claude determines what's needed:**

- Mentions "PDF", "images", "documents", "convert" → scripts/
- Mentions "API", "database", "guidelines", "standards" → references/
- Mentions "templates", "boilerplate", "brand", "presentations" → assets/
- Simple workflow/process skills → SKILL.md only

**Adding optional frontmatter properties:**

After creating a skill, you can manually edit SKILL.md to add optional frontmatter properties:

```markdown
---
name: database-query
description: Query and analyze database tables. Use when working with SQL, BigQuery, or data analysis tasks.
allowed-tools: ["Bash", "Read", "Grep"]
metadata:
  category: "data"
  version: "1.0.0"
  team: "analytics"
license: "MIT"
---
```

## Post-Creation Workflow

**1. Edit** - Complete [TODO] placeholders, populate bundled resources, add concrete examples

**2. Test** - Restart Claude Code, test with trigger queries matching description

**3. Validate** - Check frontmatter properties, description clarity, no sensitive data

**4. Iterate** - Use on real tasks, update based on struggles/feedback

**Optional:**

- Package for distribution: Use packaging tools or `/create-plugin`
- Share with team: Distribute .zip or via plugin marketplace

## Example: Well-Structured Skill

Here's an example of a production-quality skill to demonstrate best practices:

**artifacts-builder** - A skill for creating complex React/TypeScript artifacts with shadcn/ui

```
artifacts-builder/
├── SKILL.md (focused, ~75 lines)
└── scripts/
    ├── init-artifact.sh (323 lines - initializes React+Vite+shadcn project)
    ├── bundle-artifact.sh (54 lines - bundles to single HTML)
    └── shadcn-components.tar.gz (pre-packaged shadcn/ui components)
```

**SKILL.md structure:**

````markdown
---
name: artifacts-builder
description: Suite of tools for creating elaborate, multi-component claude.ai HTML artifacts using modern frontend web technologies (React, Tailwind CSS, shadcn/ui). Use for complex artifacts requiring state management, routing, or shadcn/ui components - not for simple single-file HTML/JSX artifacts.
license: Complete terms in LICENSE.txt
---

# Artifacts Builder

To build powerful frontend claude.ai artifacts, follow these steps:

1. Initialize the frontend repo using `scripts/init-artifact.sh`
2. Develop your artifact by editing the generated code
3. Bundle all code into a single HTML file using `scripts/bundle-artifact.sh`
4. Display artifact to user
5. (Optional) Test the artifact

**Stack**: React 18 + TypeScript + Vite + Parcel (bundling) + Tailwind CSS + shadcn/ui

## Design & Style Guidelines

VERY IMPORTANT: To avoid what is often referred to as "AI slop", avoid using excessive centered layouts, purple gradients, uniform rounded corners, and Inter font.

## Quick Start

### Step 1: Initialize Project

Run the initialization script to create a new React project:

```bash
bash scripts/init-artifact.sh <project-name>
cd <project-name>
```
````

This creates a fully configured project with:

- ✅ React + TypeScript (via Vite)
- ✅ Tailwind CSS 3.4.1 with shadcn/ui theming system
- ✅ Path aliases (`@/`) configured
- ✅ 40+ shadcn/ui components pre-installed
- ✅ All Radix UI dependencies included
- ✅ Parcel configured for bundling
- ✅ Node 18+ compatibility

### Step 2: Develop Your Artifact

To build the artifact, edit the generated files. See **Common Development Tasks** below for guidance.

### Step 3: Bundle to Single HTML File

To bundle the React app into a single HTML artifact:

```bash
bash scripts/bundle-artifact.sh
```

This creates `bundle.html` - a self-contained artifact with all JavaScript, CSS, and dependencies inlined.

### Step 4: Share Artifact with User

Finally, share the bundled HTML file in conversation with the user so they can view it as an artifact.

### Step 5: Testing/Visualizing the Artifact (Optional)

Note: This is a completely optional step. Only perform if necessary or requested.

## Reference

- **shadcn/ui components**: https://ui.shadcn.com/docs/components

```

**What makes this skill excellent:**

1. **Clear, specific description** - States exactly what it does (React artifacts with shadcn/ui) and when NOT to use it (simple HTML)

2. **Task-Based organizational pattern** - Uses numbered steps (Quick Start → Step 1, 2, 3...) for clear workflow

3. **Practical scripts/** - Contains executable utilities that prevent rewriting the same setup code:
   - `init-artifact.sh` - Automates 20+ setup steps (Vite, Tailwind, shadcn/ui, dependencies)
   - `bundle-artifact.sh` - Bundles multi-file React app into single HTML
   - `shadcn-components.tar.gz` - Pre-packaged components (saves installation time)

4. **Focused SKILL.md** - Only ~75 lines, moves implementation details to scripts

5. **Domain-specific guidance** - Includes "Design & Style Guidelines" section with specific advice

6. **Optional license field** - Uses `license: Complete terms in LICENSE.txt` since Apache 2.0 is verbose

7. **Progressive disclosure** - Metadata (~50 words), SKILL.md core workflow (<2k words), scripts executed without loading

8. **Explicit references** - Points to external docs (shadcn/ui) rather than duplicating them

**Claude Code would create scripts/ automatically for this skill because:**
- Description mentions "tools", "React", "Tailwind CSS", "shadcn/ui" (technical setup)
- Name "builder" implies construction/automation
- Description emphasizes "elaborate, multi-component" (complexity requiring tooling)

## Reference
Based on official Claude Code Agent Skills documentation:
- Personal skills: `~/.claude/skills/`
- Project skills: `.claude/skills/`
- Changes take effect on next Claude Code restart
- Test by asking questions matching the description triggers
```

---

--- title: Nuxt Content Documentation Reference Skill description: Skill that ensures Claude fetches current Nuxt Content documentation before answering questions or implementing features tool: claude category: skill tags: ['nuxt', 'nuxt-content', 'documentation', 'mdc', 'webfetch'] url: https://alexop.dev/prompts/claude/claude-nuxt-content-skill ---

# Nuxt Content Documentation Reference Skill


name: nuxt-content
description: Use when answering questions about OR implementing features with Nuxt Content (queries, MDC components, document-driven mode), especially when uncertain about current API - Nuxt Content is frequently updated with breaking changes, so fetch current documentation from llms.txt before responding to ensure accuracy over training data


## Nuxt Content Documentation Reference

## Overview

**Nuxt Content evolves rapidly. Training data is stale. Fetch current docs FIRST, implement/answer SECOND.**

Core principle: https://content.nuxt.com/llms.txt is the source of truth for ALL Nuxt Content questions AND implementations, regardless of how simple the task seems or how confident you feel about the API.

## When to Use

Use this skill for ANY question OR implementation task about:

- Nuxt Content queries (`queryContent`, `where`, operators)
- MDC (Markdown Components) syntax
- Document-driven mode
- Content rendering components
- API references
- Version-specific features
- Troubleshooting Nuxt Content issues

**Especially use when:**

- Implementing a feature using Nuxt Content
- Not confident about current API syntax
- Aware training data might be stale
- About to write code involving Nuxt Content
- User mentions "Nuxt Content" and you need to take action

## Mandatory Workflow

**Step 1: Fetch Documentation with Targeted Extraction**

**CRITICAL:** Use targeted WebFetch prompts that extract ONLY the specific sections needed. Do NOT ask for full documentation dumps.

```
Use WebFetch on: https://content.nuxt.com/llms.txt

Prompt format:
"Extract ONLY the documentation for [specific API/feature/concept].

Include:
- API syntax with parameters
- Code examples
- Version-specific notes
- Common gotchas

Exclude everything else. Return a concise summary."
```

**Why targeted extraction matters:**

- Full docs are 50k+ tokens
- Targeted extraction returns 1-3k tokens
- 20-50x context savings vs full dump
- Faster responses, cleaner context

**Exception for reusing:** Reuse docs from same conversation ONLY if ALL conditions met:

- You already fetched docs for this topic in this conversation AND
- The previous fetch explicitly covered the SAME specific API/feature/concept AND
- You can answer the new question completely with the previous result AND
- Less than 10 minutes have passed

**When in doubt, fetch again with targeted prompt.** Be specific about what to extract.

**Step 2: Answer Using Extracted Documentation**

- Use extracted documentation as PRIMARY source
- Reference training data only to supplement or provide context
- Include links to relevant docs sections
- Cite what came from llms.txt vs. general knowledge

**NO EXCEPTIONS to targeted fetch:** Fetch docs even when:

- User says "quick question"
- Question seems simple
- You feel confident about the answer
- User mentions they already looked at docs
- It's a yes/no question
- It's a version confirmation
- You're late in the conversation

## Red Flags - STOP and Dispatch Subagent First

If you're thinking ANY of these thoughts, STOP. Dispatch subagent to fetch docs FIRST:

**Question-answering red flags:**

- "This is a straightforward question I know"
- "User needs this fast"
- "Fetching docs would take extra time"
- "Low risk if I'm wrong"
- "I can fetch later if needed"
- "They already looked at docs"
- "This feature is mature, my knowledge is current"
- "Just need to confirm what I know"

**Implementation red flags:**

- "I'll implement based on what I know"
- "This seems straightforward to implement"
- "Let me write the code quickly"
- "I know how queryContent works"
- "I remember the MDC syntax"
- "I've used Nuxt Content before" (in training data)
- "I can update if the code fails"
- "Just need to write simple query code"

**Context-bloat red flags (CRITICAL):**

- "I'll fetch the full documentation"
- "Let me get all the docs to be thorough"
- "I'll load llms.txt completely"
- "Better to have all the info"
- "Generic WebFetch prompt is fine"

**ABSOLUTELY FORBIDDEN:** Fetching full documentation dump. This bloats context with 50k+ tokens.

**REQUIRED:** Use targeted WebFetch prompts that extract ONLY the specific section needed (1-3k tokens).

**All of these mean: Use targeted extraction. Specify EXACTLY what to extract. No full dumps.**

## Why Training Data Fails

Nuxt Content v3 introduced breaking changes. API evolves. Features change. Your training data is from January 2025 - documentation is updated continuously.

**Real examples from testing:**

- Agent suggested `$contains` without checking current operator syntax
- Agent confirmed MDC without verifying v3-specific changes
- Agent provided query patterns without checking current API

Every case: Agent was confident. Every case: Should have fetched docs.

## Common Mistakes

| Mistake                          | Why It Happens               | Fix                                                          |
| -------------------------------- | ---------------------------- | ------------------------------------------------------------ |
| Answer from memory               | Confidence in training data  | Fetch llms.txt with targeted extraction first                |
| Skip docs for "simple" questions | Assume simplicity = accuracy | Simple questions need current docs too - fetch targeted      |
| Postpone fetching                | "Can fetch if wrong"         | Wrong answers waste user time - fetch first                  |
| Trust version knowledge          | "Feature is mature"          | Mature features still change - verify with docs              |
| Cite "official docs say"         | User mentioned docs          | Fetch to verify what docs actually say                       |
| Fetch full documentation         | "Better to be thorough"      | Targeted extraction (1-3k tokens) vs full dump (50k+ tokens) |
| Generic WebFetch prompt          | Laziness                     | Specify EXACTLY what section to extract                      |

## Quick Reference

**Every Nuxt Content interaction:**

1. Use WebFetch on https://content.nuxt.com/llms.txt with TARGETED prompt
2. Extract ONLY relevant sections (not full docs)
3. Use extracted info as primary source
4. Provide answer/implementation based on extracted docs
5. Supplement with training knowledge only if needed
6. Cite source (docs vs. general knowledge)

**Targeted WebFetch prompt template:**

```
"Extract ONLY the documentation for [specific API/feature/concept] from Nuxt Content.

Include:
- API syntax with parameters
- Code examples
- Version-specific notes
- Common gotchas

Exclude everything else. Return a concise summary (1-3k tokens max)."
```

**Context savings:** Targeted extraction (1-3k tokens) vs full dump (50k+ tokens) = 20-50x savings

## Rationalization Table

| Excuse                                    | Reality                                                           |
| ----------------------------------------- | ----------------------------------------------------------------- |
| "User needs fast answer/implementation"   | Fast wrong answer wastes more time than slow correct answer       |
| "I know this from training"               | Training data is stale; Nuxt Content v3 has breaking changes      |
| "Straightforward question/implementation" | Simple tasks still need current API syntax                        |
| "Low risk if wrong"                       | Wrong answer/code blocks user; high cost to be wrong              |
| "They already looked at docs"             | Verify what docs actually say - might have misread                |
| "Feature is mature"                       | Mature features get updates and deprecations                      |
| "Can fetch later if needed"               | Fetch now = right first time; fetch later = wasted round trip     |
| "Just confirming what I know"             | Confirmation requires checking source, not memory                 |
| "I'll implement then test"                | Implementing wrong API = debugging time for user                  |
| "I can update if it fails"                | Test-fix cycle wastes time; fetch docs first prevents failures    |
| "I'll fetch all the docs to be thorough"  | Full dump = 50k+ tokens; targeted extraction = 1-3k tokens        |
| "Generic WebFetch prompt is fine"         | Targeted prompt extracts only what's needed; saves 20-50x context |
| "The docs are small enough"               | llms.txt is 50k+ tokens; always use targeted extraction           |

## Real-World Impact

**Without this skill:** Agents provide outdated API syntax, wrong operator names, incorrect version information, implement features with stale APIs based on training data, blow up context with full documentation dumps.

**With this skill:** Agents fetch current documentation with targeted extraction before answering OR implementing, provide accurate syntax, cite correct version info, save user debugging time, keep conversation context efficient.

**Context savings:** Targeted extraction (1-3k tokens) vs full dump (50k+ tokens) = 20-50x savings per interaction

**Time cost:** Targeted fetch adds 5-10 seconds. User debugging incorrect information or broken implementations adds 5-30 minutes. Always fetch with targeted extraction first.

---

--- title: Branch: Create Feature Branch from Main description: Creates a new branch from main with conventional commit-style naming based on a task description tool: claude category: instruction tags: ['git', 'branching', 'workflow', 'conventional-commits'] url: https://alexop.dev/prompts/claude/claude-branch-command ---

# Branch: Create Feature Branch from Main

description: Create a new branch from main with conventional commit-style naming
argument-hint: <task-description>
allowed-tools: Bash(git status), Bash(git fetch), Bash(git checkout), Bash(git pull), Bash(git branch)
model: haiku

# Create Feature Branch

## Context

<git_status>
!`git status`
</git_status>

<current_branch>
!`git branch --show-current`
</current_branch>

<recent_branches>
!`git branch --sort=-committerdate | head -5`
</recent_branches>

## Task Description

$ARGUMENTS

## Instructions

1. **Parse the task description** above to understand what needs to be done.

2. **Generate a branch name** following conventional commit style:
   ```
   <type>/<short-description>
   ```

   Types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`

   Rules:
   - Lowercase only
   - Replace spaces with hyphens
   - Keep concise (3-5 words max)
   - Examples: `feat/add-dark-mode`, `fix/sidebar-scroll-issue`, `refactor/extract-utils`

3. **Switch to main and pull latest:**
   ```bash
   git checkout main && git pull origin main
   ```

4. **Create and switch to the new branch:**
   ```bash
   git checkout -b <branch-name>
   ```

5. **Confirm** with `git branch --show-current`.

6. **Summarize** the branch name and what task it's for.

---

--- title: Commit: Create Conventional Commit Message description: Analyzes staged and unstaged changes to create a well-formatted conventional commit message tool: claude category: instruction tags: ['git', 'commits', 'conventional-commits', 'workflow'] url: https://alexop.dev/prompts/claude/claude-commit-command ---

# Commit: Create Conventional Commit Message

description: Create a conventional commit message and commit staged changes
allowed-tools: Bash(git status), Bash(git diff), Bash(git log), Bash(git add), Bash(git commit)
model: haiku

# Conventional Commit

I have gathered information about your changes. Here are the results:

<git_status>
!`git status`
</git_status>

<staged_diff>
!`git diff --cached`
</staged_diff>

<unstaged_diff>
!`git diff`
</unstaged_diff>

<recent_commits>
!`git log --oneline -10`
</recent_commits>

## Instructions

1. **Analyze the diffs** above to understand what changed.
2. **Stage files** if needed (skip already staged files, skip files that shouldn't be committed like `.env`).
3. **Generate a conventional commit message** following this format:
   ```text
   <type>(<scope>): <description>

   [optional body]
   ```

   Types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`

4. **Create the commit** using a HEREDOC for proper formatting:
   ```bash
   git commit -m "$(cat <<'EOF'
   type(scope): description
   EOF
   )"
   ```

5. **Show the result** with `git log -1` to confirm.

---

--- title: Create Command: Scaffold New Slash Commands description: Interactive agent that scaffolds new slash commands with best practices, proper frontmatter, and structured templates tool: claude category: agent tags: ['claude-code', 'slash-commands', 'automation', 'scaffolding'] url: https://alexop.dev/prompts/claude/claude-create-slash-command ---

# Create Command: Scaffold New Slash Commands



## Create Command: Scaffold New Slash Commands

An interactive agent that guides you through creating well-structured slash commands for Claude Code. It asks the right questions and generates commands following proven patterns.

## Purpose

Creating effective slash commands requires understanding frontmatter options, context gathering patterns, and instruction structures. This agent encapsulates best practices so you can create powerful commands quickly without memorizing the format.

## Instructions

### Step 1: Gather Requirements

Ask the user these questions:

**Question 1: Command Category**
What category best describes this command?

| Category | Description | Defaults |
|----------|-------------|----------|
| `git-workflow` | Git operations (commit, branch, push, merge) | `model: haiku`, git tools |
| `github` | GitHub operations (PR, issues, CI) | `model: haiku`, gh + git tools |
| `quality` | Linting, testing, type checking | test/lint tools |
| `debugging` | Fix errors, investigate issues | full tools, decision trees |
| `code-transform` | Refactoring, code generation | full tools, file references |
| `utility` | General purpose automation | varies |

**Question 2: Arguments**
Does this command need arguments?

| Option | Syntax | Example |
|--------|--------|---------|
| None | (no arguments) | `/lint` |
| Single required | `$1` | `/review-pr 123` |
| Multiple positional | `$1`, `$2`, `$3` | `/deploy staging v1.2.3` |
| Free-form text | `$ARGUMENTS` | `/branch add dark mode toggle` |

**Question 3: File References**
Does the command operate on specific files?

- **Yes** - Use `@$1` syntax to reference file contents
- **No** - Command works on general context

**Question 4: Complexity**
How complex is the workflow?

| Level | Characteristics | Structure |
|-------|-----------------|-----------|
| `simple` | Run command, report result | Linear steps |
| `linear` | Sequential steps, no branching | Numbered instructions |
| `branching` | Pre-checks, multiple paths | Decision tree |
| `complex` | Multi-phase, verification, fallback | Full protocol with red flags |

### Step 2: Generate Command File

Based on the answers, generate the command file with:

**Frontmatter:**
```yaml
---
description: <imperative verb phrase>
argument-hint: <show expected args>
allowed-tools: <category defaults>
model: <haiku for routine, omit for complex>
---
```

**Context Blocks** using semantic XML tags:
```markdown
<current_branch>
!`git branch --show-current`
</current_branch>
```

**Structure Templates** based on complexity level.

### Step 3: Write the File

1. Write the file to `.claude/commands/<name>.md`
2. Show the user the generated command
3. Explain how to use it

## Expected Output

- **Format:** Complete markdown file with YAML frontmatter
- **Key sections:**
  - Frontmatter with description, tools, model
  - Context blocks with shell commands
  - Decision tree (if branching/complex)
  - Numbered instructions
  - Red flags section (if complex)

## Example

**Input:**
```
/create-command deploy "Deploy to staging or production environment"
```

**Output:**
A complete command file at `.claude/commands/deploy.md` with:
- Proper frontmatter for deployment category
- Context blocks for git status, current branch, latest tag
- Decision tree handling uncommitted changes
- Instructions for build and deploy steps

## Done When

- [ ] User requirements gathered via questions
- [ ] Command file generated with correct frontmatter
- [ ] Context blocks use appropriate shell commands
- [ ] Instructions match complexity level
- [ ] File written to `.claude/commands/`

---

--- title: Fix Pipeline: Systematic CI/CD Debugging description: Agent that systematically debugs CI pipeline failures using root cause analysis before implementing fixes tool: claude category: agent tags: ['ci-cd', 'debugging', 'github-actions', 'testing', 'workflow'] url: https://alexop.dev/prompts/claude/claude-fix-pipeline-command ---

# Fix Pipeline: Systematic CI/CD Debugging

description: Check CI pipeline status for current branch and fix failures using systematic debugging
allowed-tools: Bash(gh *), Bash(git *), Bash(pnpm typecheck*), Bash(pnpm lint*), Bash(pnpm test*), Bash(pnpm build*), Read, Glob, Grep, Edit, Write

# Fix Pipeline

## Pipeline Context

<current_branch>
!`git branch --show-current`
</current_branch>

<push_status>
!`git status -sb | head -1`
</push_status>

<pipeline_runs>
!`gh run list --branch "$(git branch --show-current)" --limit 3 2>&1`
</pipeline_runs>

<latest_run>
!`gh run list --branch "$(git branch --show-current)" --limit 1 --json databaseId,status,conclusion,workflowName,headSha 2>&1`
</latest_run>

<recent_commits>
!`git log --oneline -5`
</recent_commits>

<changes_vs_main>
!`git diff main...HEAD --stat 2>/dev/null || echo "Cannot diff against main"`
</changes_vs_main>

---

## Decision Tree

Evaluate `latest_run` above:

| Condition | Action |
|-----------|--------|
| No runs / "not found" | Branch not pushed? Offer to push with `git push -u origin HEAD` |
| `status: "in_progress"` | Pipeline running. Wait or re-check later. |
| `conclusion: "success"` | **Pipeline passed.** Report success and stop. |
| `conclusion: "failure"` | **Pipeline failed.** Continue to Debugging Protocol below. |

---

## Debugging Protocol

### THE IRON LAW: NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

Skipping phases guarantees wasted time and broken fixes.

### Phase 1: Gather Failure Evidence (REQUIRED)

**1.1 Get the failed logs:**
```bash
gh run view <RUN_ID> --log-failed
```

**1.2 Answer these questions BEFORE proceeding:**
- [ ] Which job failed? (typecheck / lint / test / build)
- [ ] What is the exact error message?
- [ ] Which file(s) and line(s) are referenced?
- [ ] Is this a new failure or pre-existing?

**1.3 Reproduce locally:**

| CI Job | Local Command |
|--------|---------------|
| typecheck | `pnpm typecheck` |
| lint | `pnpm lint` |
| test | `pnpm test:e2e:with-server` or specific feature |
| build | `pnpm build` |

If it passes locally but fails in CI, investigate environment differences (node version, dependencies, etc.)

### Phase 2: Root Cause Analysis (REQUIRED)

**DO NOT propose fixes yet.**

1. **Read the full error** - not just the first line
2. **Trace to source** - what code/change caused this?
3. **Understand WHY** - not just WHERE

Form a hypothesis: "The error occurs because [specific reason], caused by [specific change]."

### Phase 3: Minimal Fix

Only after completing Phase 2:

1. **Make ONE targeted change** addressing root cause
2. **Verify locally** using same command from Phase 1.3
3. **Confirm error is gone**

### Phase 4: Commit and Re-run

```bash
# Stage and commit the fix
git add -A
git commit -m "fix: [description of what was fixed]"

# Push to trigger new CI run
git push

# Watch the new run
gh run watch
```

---

## Red Flags — STOP and Return to Phase 1

If you catch yourself:
- Proposing fixes without reading full error logs
- Saying "let me try X" without explaining WHY
- Changing multiple unrelated things
- Skipping local reproduction
- Not understanding the error message

**STOP. You are guessing. Return to Phase 1.**

## Escape Hatch

If after 3 fix attempts the issue persists:
- This may be an architectural or environmental problem
- Stop fixing symptoms
- Report findings and ask user for guidance

---

--- title: Lint: Auto-fix and Resolve Linting Issues description: Runs linter with auto-fix enabled and resolves any remaining errors that require manual intervention tool: claude category: instruction tags: ['linting', 'code-quality', 'eslint', 'workflow'] url: https://alexop.dev/prompts/claude/claude-lint-command ---

# Lint: Auto-fix and Resolve Linting Issues

description: Auto-fix linting issues and resolve remaining errors
allowed-tools: Bash(pnpm run lint), Bash(pnpm run lint:fix), Bash(eslint)
model: haiku

# Lint and Fix

I have already run the linter with the fix flag. Here are the results:

<lint_results>
!`pnpm run lint:fix || true`
</lint_results>

## Instructions
1. **Analyze the `<lint_results>`** above.
   - If the output shows "No errors" or is empty, respond with "No lint errors found." and stop - no further action needed.
   - If errors remain, they require manual intervention.
2. **Fix remaining errors** by editing the referenced files.
3. **Verify** by running the lint command one last time.

---

--- title: Merge to Main: Complete PR Workflow description: Merges current branch to main via GitHub PR with squash merge and branch cleanup tool: claude category: instruction tags: ['git', 'github', 'pull-requests', 'workflow', 'merging'] url: https://alexop.dev/prompts/claude/claude-merge-to-main-command ---

# Merge to Main: Complete PR Workflow

description: Merge current branch to main via GitHub PR
allowed-tools: Bash(git status), Bash(git branch), Bash(git log), Bash(git push), Bash(gh pr create), Bash(gh pr merge), Bash(gh pr list), Bash(gh pr view), Bash(git checkout), Bash(git pull)
model: haiku

# Merge to Main

I have gathered information about your branch. Here are the results:

<current_branch>
!`git branch --show-current`
</current_branch>

<branch_status>
!`git status --short`
</branch_status>

<commits_ahead>
!`git log main..HEAD --oneline`
</commits_ahead>

<existing_pr>
!`gh pr view --json number,title,state,mergeable --jq '"PR #\(.number): \(.title) [\(.state)] mergeable: \(.mergeable)"' 2>/dev/null || echo "No PR exists for this branch"`
</existing_pr>

## Instructions

1. **Check for uncommitted changes** - if there are uncommitted changes, stop and ask the user to commit first.

2. **Verify not on main** - if on main branch, stop and inform the user.

3. **Push the branch** if needed:
   ```bash
   git push -u origin $(git branch --show-current)
   ```

4. **Create or find PR**:
   - If no PR exists, create one with `--fill-verbose` to include commit details:
     ```bash
     gh pr create --base main --fill-verbose
     ```
   - If PR exists, show its current status with `gh pr view`

5. **Merge the PR** (squash merge, delete branch):
   ```bash
   gh pr merge --squash --delete-branch
   ```

6. **Switch to main and pull**:
   ```bash
   git checkout main && git pull
   ```

7. **Show the result** with `git log -1` to confirm the merge completed.

---

--- title: PR: Create Well-Formatted Pull Request description: Creates a GitHub PR with conventional title and structured description including summary, changes, and test plan tool: claude category: instruction tags: ['git', 'github', 'pull-requests', 'workflow'] url: https://alexop.dev/prompts/claude/claude-pr-command ---

# PR: Create Well-Formatted Pull Request

description: Create a new GitHub PR with a well-formatted description
allowed-tools: Bash(git status), Bash(git branch), Bash(git log), Bash(git diff), Bash(git push), Bash(git rev-parse), Bash(gh pr create), Bash(gh pr view), Bash(gh pr edit)
model: haiku

# Create Pull Request

I have gathered information about your branch. Here are the results:

<current_branch>
!`git branch --show-current`
</current_branch>

<branch_status>
!`git status --short`
</branch_status>

<commits_on_branch>
!`git log main..HEAD --oneline`
</commits_on_branch>

<commit_details>
!`git log main..HEAD --pretty=format:"### %s%n%n%b%n---"`
</commit_details>

<full_diff_stat>
!`git diff main..HEAD --stat`
</full_diff_stat>

<files_changed>
!`git diff main..HEAD --name-only`
</files_changed>

<existing_pr>
!`gh pr view --json number,title,state,url --jq '"PR #\(.number): \(.title) [\(.state)]\nURL: \(.url)"' 2>/dev/null || echo "No PR exists for this branch"`
</existing_pr>

## Instructions

### Pre-checks

1. **Check for uncommitted changes** - if there are uncommitted changes, stop and ask the user to commit first.
2. **Verify not on main** - if on main branch, stop and inform the user.
3. **Check if PR already exists** - if a PR exists, show the URL and ask if user wants to update it with `gh pr edit`.

### Step 1: Push the Branch

Push the branch to remote if needed:
```bash
git push -u origin $(git branch --show-current)
```

### Step 2: Create the PR

**Option A: Single commit branch** - use `--fill-first` to auto-fill from commit:
```bash
gh pr create --base main --fill-first
```

**Option B: Multi-commit branch** - craft a custom description using the format below:
```bash
gh pr create --base main --title "<title>" --body "$(cat <<'EOF'
<body>
EOF
)"
```

**Option C: Draft PR** - add `--draft` flag to create as draft:
```bash
gh pr create --base main --draft --title "<title>" --body "..."
```

**Useful flags:**
- `--fill` - Auto-fill title and body from commit info
- `--fill-first` - Use only the first commit for title/body
- `--fill-verbose` - Include full commit messages in body
- `--draft` - Create as draft PR
- `--dry-run` - Preview without creating

## PR Format

### Title Format

Use conventional commit style:
```text
<type>(<scope>): <description>
```

**Types:** `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`

**Examples:**
- `feat(editor): add vim macro support`
- `fix(documents): resolve save race condition`
- `refactor(color-theme): simplify OKLCH conversion`

### Body Format

```markdown
## Summary

Brief 1-2 sentence description of what this PR does and why.

## Changes

- Bullet point list of specific changes
- Group related changes together
- Include file/module names when helpful

## Test Plan

- [ ] Manual testing steps or automated tests that verify the change
- [ ] Edge cases considered
```

### Step 3: Show Result

After creating the PR, display the URL with:
```bash
gh pr view --json url --jq '.url'
```

---

--- title: Push: Commit and Push to Remote description: Combines commit creation with conventional message and push to remote in one command tool: claude category: instruction tags: ['git', 'commits', 'workflow', 'conventional-commits'] url: https://alexop.dev/prompts/claude/claude-push-command ---

# Push: Commit and Push to Remote

description: Commit staged changes and push to remote
allowed-tools: Bash(git status), Bash(git diff:*), Bash(git log:*), Bash(git add:*), Bash(git commit:*), Bash(git push:*), Bash(git rev-parse:*), Bash(git remote:*)
model: haiku

# Commit and Push

I have gathered information about your changes. Here are the results:

<git_status>
!`git status`
</git_status>

<staged_diff>
!`git diff --cached`
</staged_diff>

<unstaged_diff>
!`git diff`
</unstaged_diff>

<recent_commits>
!`git log --oneline -10`
</recent_commits>

<current_branch>
!`git rev-parse --abbrev-ref HEAD`
</current_branch>

<remote_info>
!`git remote -v`
</remote_info>

## Instructions

### Step 1: Commit (if there are changes)

1. **Analyze the diffs** above to understand what changed.
2. **Stage files** if needed (skip already staged files, skip files that shouldn't be committed like `.env`).
3. **Generate a conventional commit message** following this format:
   ```text
   <type>(<scope>): <description>

   [optional body]
   ```

   Types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`

4. **Create the commit** using a HEREDOC for proper formatting:
   ```bash
   git commit -m "$(cat <<'EOF'
   type(scope): description
   EOF
   )"
   ```

### Step 2: Push

5. **Push to remote** using the current branch:
   ```bash
   git push origin <current-branch>
   ```

   If the branch doesn't have an upstream, use:
   ```bash
   git push -u origin <current-branch>
   ```

6. **Show the result** with `git log -1` to confirm the commit, and verify the push succeeded.

---

--- title: Refactor Page Object: Test Pattern Refactoring description: Refactors Vue component tests to use the Page Object Pattern for better maintainability and readability tool: claude category: instruction tags: ['testing', 'vue', 'refactoring', 'page-object-pattern', 'vitest'] url: https://alexop.dev/prompts/claude/claude-refactor-page-object-command ---

# Refactor Page Object: Test Pattern Refactoring

description: Refactor a Vue component test to use the Page Object Pattern
argument-hint: [test-file-path]

# Page Object Pattern Refactoring

Refactor the test file located at @$1 to use the **Page Object Pattern**.

## Context
Analyze the component import in @$1 to understand the component being tested. You need to abstract all UI interactions into a helper function.

## Refactoring Rules

1.  **Create the Page Object Factory**:
    * Define an async function `create<ComponentName>Page()` at the **bottom** of the test file.
    * Move the `renderApp` or component rendering logic inside this function.
    * Return an object containing getters and action methods.

2.  **Encapsulate Elements**:
    * Create getters (e.g., `getSubmitButton`, `getSearchInput`).
    * Use semantic queries: `getByRole`, `getByLabelText`, `getByPlaceholderText`.
    * **Strict rule**: Do not expose `screen` or `userEvent` directly in the test body; they must be accessed via the page object.

3.  **Define Actions**:
    * Create semantic action methods (e.g., `searchFor(term)`, `submitForm()`).
    * Return promises for all actions.

4.  **Test Body Cleanup**:
    * Instantiate the page object at the start of each test: `const page = await createXyzPage();`.
    * Replace all `await user.type(...)` and `screen.getBy...` calls with methods from `page`.

## Target Code Style

Use this example as the ground truth for the desired output structure:

```typescript
// BEFORE:
// const searchInput = screen.getByPlaceholderText('Search...');
// await user.type(searchInput, 'test');

// AFTER:
// const page = await createMyComponentPage();
// await page.searchFor('test');

// Page Object Structure (at bottom of file):
async function createMyComponentPage() {
  await renderApp(MyComponent, {}, '/my-route');
  
  return {
    // Getters
    getSearchInput: () => screen.getByPlaceholderText('Search...'),
    getSubmitButton: () => screen.getByRole('button', { name: 'Submit' }),
    
    // Actions
    searchFor: async (term: string) => {
      await user.type(screen.getByPlaceholderText('Search...'), term);
      await user.click(screen.getByRole('button', { name: 'Submit' }));
    }
  };
}

---

--- title: Review CodeRabbit: Process AI Code Reviews description: Agent that processes CodeRabbit review comments with technical rigor - verifies suggestions before implementing and pushes back when wrong tool: claude category: agent tags: ['code-review', 'coderabbit', 'github', 'pull-requests', 'workflow'] url: https://alexop.dev/prompts/claude/claude-review-coderabbit-command ---

# Review CodeRabbit: Process AI Code Reviews

description: Fetch CodeRabbit review comments and process them with technical rigor - verify before implementing, push back when wrong
allowed-tools: Bash(gh *), Bash(git *), Bash(pnpm typecheck*), Bash(pnpm lint*), Bash(pnpm test*), Bash(pnpm build*), Read, Glob, Grep, Edit, Write

# Review CodeRabbit Feedback

## PR Context

<current_branch>
!`git branch --show-current`
</current_branch>

<pr_info>
!`gh pr view --json number,title,state,url 2>&1`
</pr_info>

<coderabbit_reviews>
!`gh pr view --json reviews --jq '.reviews[] | select(.author.login == "coderabbitai") | {state: .state, body: .body}' 2>&1`
</coderabbit_reviews>

<coderabbit_comments>
!`gh pr view --json comments --jq '.comments[] | select(.author.login == "coderabbitai") | .body' 2>&1`
</coderabbit_comments>

<review_threads>
!`gh api graphql -f query='query($owner: String!, $repo: String!, $pr: Int!) { repository(owner: $owner, name: $repo) { pullRequest(number: $pr) { reviewThreads(first: 100) { nodes { id isResolved path line comments(first: 10) { nodes { body author { login } } } } } } } }' -F owner="$(gh repo view --json owner -q .owner.login)" -F repo="$(gh repo view --json name -q .name)" -F pr="$(gh pr view --json number -q .number)" 2>&1 || echo "Could not fetch review threads"`
</review_threads>

---

## Decision Tree

| Condition | Action |
|-----------|--------|
| No PR found | Branch has no PR. Create one first with `gh pr create` |
| No CodeRabbit comments | No feedback to process. Done. |
| Comments found | Continue to Review Reception Protocol below |

---

## Review Reception Protocol

**CORE PRINCIPLE:** Verify before implementing. Ask before assuming. Technical correctness over social comfort.

### The Response Pattern

```
FOR EACH CodeRabbit suggestion:

1. READ: Complete feedback without reacting
2. UNDERSTAND: Restate requirement in own words
3. VERIFY: Check against codebase reality
4. EVALUATE: Technically sound for THIS codebase?
5. RESPOND: Technical acknowledgment or reasoned pushback
6. IMPLEMENT: One item at a time, test each
```

### Forbidden Responses

**NEVER say:**
- "You're absolutely right!" (explicit CLAUDE.md violation)
- "Great point!" / "Excellent feedback!" (performative)
- "Let me implement that now" (before verification)
- "Thanks for catching that!" (performative gratitude)

**INSTEAD:**
- Restate the technical requirement
- Ask clarifying questions if needed
- Push back with technical reasoning if wrong
- Just fix it (actions > words)

---

## Verification Checklist

BEFORE implementing any CodeRabbit suggestion:

- [ ] **Technically correct** for THIS codebase?
- [ ] **Breaks existing functionality?** Check tests, grep for usage
- [ ] **Reason for current implementation?** May be intentional
- [ ] **Works on all platforms/versions?** Check compatibility
- [ ] **Does reviewer understand full context?** AI may lack context

### YAGNI Check

```
IF suggestion adds "proper" or "professional" features:
  grep codebase for actual usage

  IF unused: Consider removing (YAGNI) instead of improving
  IF used: Then implement properly
```

---

## When To Push Back

Push back when:
- Suggestion breaks existing functionality
- Reviewer lacks full context (common with AI reviewers)
- Violates YAGNI (unused feature)
- Technically incorrect for this stack
- Legacy/compatibility reasons exist
- Conflicts with architectural decisions

**How to push back:**
```
"Checked [X] - current implementation does [Y] because [reason].
Changing to [suggestion] would [break/conflict with] [Z].
Keep current approach? Or is there context I'm missing?"
```

---

## Processing CodeRabbit Feedback

### Step 1: Categorize Each Item

| Category | Priority | Action |
|----------|----------|--------|
| Security/Breaking | HIGH | Verify immediately, fix if confirmed |
| Type errors/Bugs | HIGH | Verify locally, fix if real |
| Style/Formatting | LOW | Check if matches project conventions |
| "Best practices" | VERIFY | Check if actually applies here |
| Refactoring suggestions | VERIFY | Check if code is actually used |

### Step 2: Verify Before Acting

For each suggestion:
1. **Read the referenced file** - understand current implementation
2. **Check tests** - does current code pass? Would change break them?
3. **Grep for usage** - is this code actually called?
4. **Consider context** - why might it be written this way?

### Step 3: Implementation Order

```
IF multiple items:
  1. Clarify anything unclear FIRST
  2. Then implement in order:
     - Security/Breaking issues
     - Confirmed bugs
     - Simple fixes (imports, typos)
     - Complex changes (refactoring)
  3. Test each fix individually
  4. Verify no regressions
  5. RESOLVE each comment after addressing (see Resolution Protocol)
```

---

## Acknowledging Correct Feedback

When feedback IS correct:
```
- "Fixed. [Brief description of what changed]"
- "Good catch - [specific issue]. Fixed in [location]."
- [Just fix it and show in the code]
```

When you pushed back and were wrong:
```
"Verified this and you're correct. [Brief reason]. Fixing."
```

No long apologies. State correction factually and move on.

---

## Resolution Protocol

**Every CodeRabbit comment MUST be resolved after processing.**

> **Note:** Resolving review threads requires the GraphQL API. The REST API does not support thread resolution.

### Step 1: List Unresolved Review Threads

```bash
# Get all review threads with resolution status (GraphQL required)
gh api graphql -f query='
query($owner: String!, $repo: String!, $pr: Int!) {
  repository(owner: $owner, name: $repo) {
    pullRequest(number: $pr) {
      reviewThreads(first: 100) {
        nodes {
          id
          isResolved
          path
          line
          comments(first: 10) {
            nodes {
              body
              author { login }
            }
          }
        }
      }
    }
  }
}' -F owner="{owner}" -F repo="{repo}" -F pr="$(gh pr view --json number -q .number)"
```

### Step 2a: Resolve After Implementation

When you implement a suggestion, resolve the thread directly (reply is optional - the commit speaks for itself):

```bash
# Resolve a review thread by its GraphQL node ID
gh api graphql -f query='
mutation($threadId: ID!) {
  resolveReviewThread(input: {threadId: $threadId}) {
    thread { isResolved }
  }
}' -f threadId="THREAD_NODE_ID"
```

### Step 2b: Reply and Resolve Without Implementation

When you decide NOT to implement, reply with reasoning then resolve:

```bash
# Reply to a review thread (requires thread's GraphQL node ID)
gh api graphql -f query='
mutation($threadId: ID!, $body: String!) {
  addPullRequestReviewThreadReply(input: {
    pullRequestReviewThreadId: $threadId,
    body: $body
  }) {
    comment { body }
  }
}' -f threadId="THREAD_NODE_ID" -f body="Not implementing: [reason]

- Current implementation does X because Y
- Suggested change would [break/conflict with] Z"

# Then resolve the thread
gh api graphql -f query='
mutation($threadId: ID!) {
  resolveReviewThread(input: {threadId: $threadId}) {
    thread { isResolved }
  }
}' -f threadId="THREAD_NODE_ID"
```

### Helper: Get Owner and Repo

```bash
# Extract owner/repo from current git remote
gh repo view --json owner,name -q '"\(.owner.login)/\(.name)"'
```

### Resolution Checklist

For EACH CodeRabbit comment:
- [ ] Evaluated (implemented or rejected with reason)
- [ ] Response added (if rejecting - explain why)
- [ ] Thread resolved via GraphQL mutation

**Goal: Zero unresolved CodeRabbit comments when done.**

---

## Common CodeRabbit Patterns

| Pattern | Verify |
|---------|--------|
| "Consider using X instead of Y" | Check if X works in this context |
| "This could be simplified" | Check if simplification handles edge cases |
| "Missing error handling" | Check if errors are handled elsewhere |
| "Unused import/variable" | Verify with grep, may be used dynamically |
| "Type could be more specific" | Check if generic type is intentional |
| "Add documentation" | Check project conventions on docs |

---

## Red Flags - STOP and Verify

If you catch yourself:
- Agreeing without checking the code
- Implementing before understanding why current code exists
- Not testing changes
- Batch implementing without individual verification

**STOP. You are being performative. Return to verification.**

---

## Summary

**External AI feedback = suggestions to evaluate, not orders to follow.**

1. Read all feedback first
2. Verify each item against codebase
3. Push back on incorrect suggestions
4. Implement confirmed issues one at a time
5. Test each change
6. **Resolve every comment** (implemented or rejected with reason)

No performative agreement. Technical rigor always. Zero unresolved comments.

---

--- title: Vitest: Run Tests and Fix Failures description: Runs Vitest test suite and systematically fixes any failing tests tool: claude category: instruction tags: ['testing', 'vitest', 'debugging', 'workflow'] url: https://alexop.dev/prompts/claude/claude-vitest-command ---

# Vitest: Run Tests and Fix Failures

description: Run Vitest tests and fix any failing tests
allowed-tools: Bash(pnpm run test:vitest), Bash(pnpm test:vitest), Bash(vitest)

# Vitest Test Runner

I have run the Vitest test suite. Here are the results:

<test_results>
!`pnpm run test:vitest --run 2>&1 || true`
</test_results>

## Instructions
1. **Analyze the `<test_results>`** above.
   - If all tests pass, no action is needed.
   - If tests are failing, identify the root cause from the error messages.
2. **Fix failing tests** by either:
   - Fixing bugs in the source code that caused the test to fail
   - Updating tests if they are outdated or incorrect
3. **Verify** by running the test command again to confirm all tests pass.

---

--- title: Learn: Analyze Conversation for Documentation description: Analyzes conversation for insights worth preserving and saves them to the project's documentation tool: claude category: skill tags: ['documentation', 'learning', 'knowledge-capture', 'workflow'] url: https://alexop.dev/prompts/claude/claude-learn-command ---

# Learn: Analyze Conversation for Documentation

description: Analyze conversation for learnings and save to docs folder
argument-hint: [optional topic hint]
model: claude-opus-4-5-20251101
allowed-tools: Read, Write, Edit, Glob, Grep, AskUserQuestion

# Learn from Conversation

Analyze this conversation for insights worth preserving in the project's documentation.

**If a topic hint was provided via `$ARGUMENTS`, focus on capturing that specific learning.**
**If no hint provided, analyze the full conversation for valuable insights.**

## Phase 1: Deep Analysis

Think deeply about what was learned in this conversation:
- What new patterns or approaches were discovered?
- What gotchas or pitfalls were encountered?
- What architecture decisions were made and why?
- What conventions were established?
- What troubleshooting solutions were found?

Only capture insights that are:
1. **Reusable** - Will help in future similar situations
2. **Non-obvious** - Not already common knowledge
3. **Project-specific** - Relevant to this codebase

If nothing valuable was learned, say so and exit gracefully.

## Phase 2: Categorize & Locate

Read existing docs to find the best home. Look for a `docs/` folder or similar documentation directory in the project.

If no existing doc fits, propose a new doc file with kebab-case naming.

**Note:** CLAUDE.md stays stable as the entry point. All detailed learnings go to `/docs` only.

## Phase 3: Draft the Learning

Format the insight to match existing doc style:
- Clear heading describing the topic
- Concise explanation of the insight
- Code examples if applicable
- Context on when this applies

## Phase 4: User Approval (BLOCKING)

Present your proposed changes:
1. What insight you identified
2. Where you'll save it (existing doc + section, or new file)
3. The exact content to add

**Wait for explicit user approval before saving.**

## Phase 5: Save

After approval, save the learning and confirm what was captured.

---

--- title: Genereate new Prompt for Copilot description: Custom instructions for TypeScript development with strict typing tool: copilot category: prompt tags: ['typescript', 'code-quality'] url: https://alexop.dev/prompts/copilot/copilot-make-prompt ---

# Genereate new Prompt for Copilot


agent: agent
model: Claude Sonnet 4.5 (copilot)
tools: ['edit', 'search/codebase', 'think']
description: From a short task description, generate a Copilot `.prompt.md` file at `.github/prompts/`


## Copilot Prompt File Generator (VS Code prompt files)

Turn a short description into a complete VS Code Copilot **prompt file** (`.prompt.md`) saved under `.github/prompts`, following the official prompt-file structure and best practices.

> If any required value is missing, infer sensible defaults **without** back-and-forth.

## Behavior priority (in order)

1. Successfully create a valid `.prompt.md` file that VS Code can run.
2. Do **not** ask follow-up questions; infer sensible defaults from inputs.
3. If a step is impossible, stop and briefly explain the problem in chat.

---

## Inputs

Normalize all inputs by trimming whitespace.

- **Task description** (required) → `${input:desc:Briefly describe what the prompt should do}`
  - If empty or only whitespace, stop and report the error in chat.
- **Prompt file base name (kebab-case, filename-safe)** → `${input:name:${fileBasenameNoExtension}-prompt}`
- **Prompt display name** (optional; shown after `/` in chat) → `${input:promptName}`
- **Argument hint** (optional; hint text in chat input) → `${input:argumentHint}`
- **Agent / mode** (`ask` | `edit` | `agent`; default `agent`) → `${input:agent:agent}`
  - If `${input:agent}` is not one of `ask`, `edit`, `agent`, treat it as `agent`.
- **Model** (optional; defaults to model picker) → `${input:model}`
- **Tools** (optional; comma-separated tool or tool-set names) → `${input:tools}`
  - Parse into an array: split by `,`, trim, drop empty entries, deduplicate.
  - Support patterns like `serverName/*` for MCP servers when provided.
- **Additional references** (optional; comma-separated relative paths) → `${input:refs}`
  - Parse into an array: split by `,`, trim, drop empty entries, deduplicate.

> Treat “workspace prompt files” as files under `.github/prompts`. This generator only creates **workspace** prompt files.

---

## What to generate

Create **one** `.prompt.md` file with the official VS Code prompt-file structure:

### 1) YAML frontmatter (only non-empty keys)

Use the following keys, matching the VS Code docs:

- `description`: ≤ 90 chars summary crafted from `${input:desc}`.
  - If `${input:desc}` is longer, truncate at a word boundary.
- `name`: from `${input:promptName}` if provided, otherwise:
  - Use the computed base filename (without extension) as a reasonable default.
- `argument-hint`: from `${input:argumentHint}` if provided.
- `agent`: from normalized `${input:agent}` (`ask`, `edit`, or `agent`).
- `model`: from `${input:model}` if provided.
- `tools`: from parsed `${input:tools}` if non-empty (YAML list).

Omit any key whose value is empty, `null`, or an empty array.

Example shape (for preview only):

```yaml
description: Review Python code for security issues and suggest fixes
name: review-python-security
argument-hint: Paste the Python code you want reviewed
agent: ask
model: gpt-4.1
tools:
  - search
  - githubRepo
```

### 2) Body (clear, actionable, self-contained)

The body is the prompt text VS Code sends to the LLM when the prompt is run. It must be structured and aligned with best practices.

Use the following sections in this **exact order**:

1. `## Task`
   - 1–3 sentences summarizing what the prompt does and when to use it, based on `${input:desc}`.

2. `## Instructions`
   - Numbered, deterministic steps to accomplish `${input:desc}`.
   - Use imperative mood and active voice.
   - Clearly describe:
     - What the AI should do.
     - How it should use any selections, files, or inputs.
     - Any language / framework / version constraints that are explicitly implied by the task (do not invent constraints).

   _When relevant, encourage using VS Code prompt variables to make the prompt reusable and flexible, for example:_
   - `${selection}` or `${selectedText}` for code under review or to transform.
   - `${file}`, `${fileBasename}`, `${fileDirname}`, `${fileBasenameNoExtension}` when operating on the current file.
   - `${workspaceFolder}`, `${workspaceFolderBasename}` for workspace-level operations.
   - `${input:variableName}` / `${input:variableName:placeholder}` to pass user parameters into the prompt (for things like component names, API names, etc.).

3. `## Expected output`
   - A bulleted or numbered list describing the exact output format the AI should produce, for example:
     - Required sections and headings.
     - When to use fenced code blocks (and which languages).
     - When to use tables, lists, or checklists.
     - Any JSON or structured formats, including required fields.

4. `## References` (include only if `${input:refs}` is non-empty)
   - Bullet list of reference files, each as a **relative Markdown link**, for example:
     - `[API specification](docs/api.md)`

   - Use the parsed `${input:refs}` values directly as relative paths from `.github/prompts`.
   - Do not reference files that are not listed in `${input:refs}`.
   - When relevant, suggest how the AI should use these references (for example, “Follow the guidelines in [custom instructions](../docs/custom-instructions.md) instead of duplicating them here”).

   _If the prompt benefits from agent tools (like `githubRepo`, `search`, or others), you may mention them in the body using the VS Code tool reference syntax, for example: `#tool:githubRepo`._

5. `## Done when`
   - A checklist that clearly states the completion criteria for this prompt.
   - Use `- [ ]` items.
   - Include checks like:
     - Output matches the described structure.
     - Any required examples of input and output are included.
     - Any referenced files are linked correctly and actually used.
     - The prompt does not depend on hidden context beyond the described variables and references.

In the body:

- Encourage `${selection}`, `${file}`, and input variables **only when they add clarity and reuse**, not by default.
- Avoid depending on external context beyond:
  - Workspace-relative files you’ve linked.
  - Built-in variables (`${selection}`, `${file}`, `${workspaceFolder}`, input variables).

- Use **Markdown** consistently (headings, lists, code blocks).
- Do **not** leak internal environment details or paths outside `.github/prompts`.

---

## File operations

Use the available workspace/file tools (for example, `edit`) to actually modify the repository; do not simulate edits in prose.

1. **Compute base slug:**
   - If `${input:name}` is provided and non-empty, start from that.
   - Otherwise, **slugify** `${input:desc}` as follows:
     - Lowercase the string.
     - Replace any sequence of characters outside `[a-z0-9]` with a single `-`.
     - Collapse repeated `-` into one.
     - Trim leading and trailing `-`.
     - Optionally truncate the slug to a safe length (for example, 60 characters) without cutting inside a word if practical.

2. **Apply extension:**
   - Use `<slug>.prompt.md` as the base filename.

3. **Ensure folder exists:**
   - Ensure `.github/prompts` exists, creating it if necessary.
   - Treat this folder as the workspace prompt-file folder.

4. **Resolve collisions:**
   - If `.github/prompts/<slug>.prompt.md` already exists, try:
     - `.github/prompts/<slug>-1.prompt.md`,
     - `.github/prompts/<slug>-2.prompt.md`, etc.

   - Increment the numeric suffix until a unique path is found.

5. **Write file:**
   - Write the YAML frontmatter and body to `.github/prompts/<final-name>.prompt.md`.
   - Never overwrite existing files; always create a new file.

---

## Return in chat (always)

After successfully writing the file:

- Provide a one-line confirmation with the final saved **path**, wrapped in backticks, for example:
  _`Created \`.github/prompts/my-task.prompt.md`._`

- Show a short frontmatter preview (3–6 lines) in a fenced `yaml` code block, using the final values, for example:

  ```yaml
  description: Review Python code for security issues and suggest fixes
  name: review-python-security
  agent: ask
  model: gpt-4.1
  tools:
    - search
    - githubRepo
  ```

- If `${input:refs}` parsed to a non-empty list, output:
  - “Reference files:” followed by a bullet list of the detected reference paths.

- If `${input:refs}` is empty or only whitespace, output:
  - “No reference files provided.”

If any required step fails (for example, unable to write the file), explain briefly what failed and which step you reached.

---

## Tool selection (least-privilege)

Start with **no additional tools** beyond those configured for this agent. Add tools only if strictly necessary and available in the current environment.

- Prefer read-only tools when you need to inspect the workspace (for example, `search`, `search/codebase`, `problems`, `usages`, `extensions`, `vscodeAPI`), if they exist.
- Use write/exec tools only when needed:
  - Create scaffolding/files → `edit` or `new`.
  - Run commands → `runCommands`.
  - Build/run/test → `runTasks`, `runTests`.
  - Local preview → `openSimpleBrowser`.
  - Public code examples → `githubRepo`.
  - Fetch a specific URL’s content → `fetch`.

If a tool mentioned above is not available in this environment, omit it and choose the minimal available alternative. Do **not** substitute more powerful or riskier tools than necessary.

---

## Implementation algorithm (you execute now)

1. Parse `${input:desc}`, `${input:name}`, `${input:promptName}`, `${input:argumentHint}`, `${input:agent}`, `${input:model}`, `${input:tools}`, and `${input:refs}` and normalize them as described above.
2. Validate that `${input:desc}` is non-empty; if it is empty, report the error in chat and stop.
3. Craft the `description` field (≤ 90 chars) from `${input:desc}`.
4. Build the YAML frontmatter with `description`, `name`, `argument-hint`, `agent`, `model`, and `tools`, omitting empty keys.
5. Write the body with:
   - `## Task` summary,
   - `## Instructions` numbered steps (using variables and tools when helpful),
   - `## Expected output` section,
   - optional `## References` section (if refs exist),
   - `## Done when` checklist.

6. Ensure `.github/prompts` exists, compute a safe, unique filename, and write the file.
7. Reply in chat with the confirmation line, frontmatter preview, and reference files list (or “No reference files provided”).

---

## Style & best practices (aligning with VS Code docs)

- Clearly describe what the prompt should accomplish and what output format is expected.
- Provide or request examples of expected input and output when that helps guide responses.
- Prefer referencing common guidelines or custom instructions via Markdown links instead of duplicating them.
- Leverage built-in variables like `${selection}`, `${file}`, `${workspaceFolder}`, and `${input:*}` to keep prompts flexible and reusable.
- Use the editor’s run/play button (and `/promptName` in chat) to test prompts, then refine wording and output format instructions to improve determinism.
- Be concise, precise, and neutral; no emojis or fluff.
- Use **active voice** and imperative mood.
- Avoid ambiguous language like “a few” or “some”.
- Do **not** leak internal environment details or paths outside `.github/prompts`.

---

## Example transformation (illustrative; do **not** save)

**Input desc:** “Create a prompt to review Python code for security issues and suggest fixes.”

- `description:` “Review Python code for security issues and suggest fixes”
- `name:` `review-python-security`
- `argument-hint:` “Paste the Python code you want reviewed”
- `agent:` `ask`
- `tools:` might include `search`, `githubRepo`

**Body should:**

- Use `${selection}` to receive the code under review.
- In `## Instructions`, instruct the AI to identify common security issues (injection, insecure deserialization, SSRF, secrets, weak crypto) and suggest fixes.
- In `## Expected output`, require a Markdown list grouped by severity with code examples of safer alternatives.
- In `## Done when`, ensure the output follows the described format and covers all detected issues.

---

## “Done when” checklist

- A unique file exists at `.github/prompts/<name>.prompt.md`.
- Frontmatter uses only official VS Code fields (`description`, `name`, `argument-hint`, `agent`, `model`, `tools`) with non-empty valid values.
- Body contains `## Task`, `## Instructions`, `## Expected output`, optional `## References` (if refs exist), and `## Done when`.
- Any `${input:refs}` were linked via relative Markdown paths in the `## References` section.
- The prompt body uses VS Code variables and tool references (`${selection}`, `${input:*}`, `#tool:<name>`) when beneficial.
- Chat reply includes the final path, frontmatter preview, and reference files list (or “No reference files provided”).

---