alexop.dev

How to Write UI Components That Stay Flexible

alex.opalic.dev@gmail.com (Alexander Opalic) — Wed, 29 Apr 2026 00:00:00 GMT

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. 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 shows one of those copies in practice:

<!-- 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 shows the version that grew out of covering two real call sites (confirm-delete and edit-profile) with one component:

<!-- 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:

<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:

<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:

// 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:

<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:

<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 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:

<script setup>
const open = ref(false);
provide("dialog-open", open);
</script>

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

<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>, 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() 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:

// 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 is shaped exactly around that — it takes a setup function and returns a [useProvide, useInject] tuple. The same useDialog.ts becomes:

// 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:

<!-- 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.

<!-- 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>

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

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

<!-- 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:

<!-- 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:

<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:

<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:

<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.

<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>

<script setup>
const open = ref(false);

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

<template>
  
</template>

<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>

<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>

<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:

// 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:

<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:

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

The consumer styles against the attribute:

<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:

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

<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:

<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

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.
Stable surface. Refactor the primitive’s utility classes tomorrow; data-state="open" survives because it is the public contract.
Inspectable. Open DevTools, see the state in the DOM. No closure spelunking.
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.

<!-- 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:

<!-- 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:

<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:

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.
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.
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.
Split the children. Each child component reads only the slice it needs from useX(). Keep them dumb. No business logic in the leaves.
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. 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 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 composition prop, which lets consumers swap the rendered element while keeping the behavior. The Radix philosophy doc 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 (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, The 6 Levels of Reusability, and the small applied exercise Building a (Totally) 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: the source code referenced in this post
Reka UI: the headless primitives shadcn-vue is built on
Radix Primitives: the React parent of Reka UI; same patterns, different binding
Fernando Rojo, Composition Is All You Need: the talk that prompted this post
Kent C. Dodds, Compound Components with React Hooks: canonical React treatment
Vue docs: provide / inject
VueUse: createInjectionState: the factory that collapses the manual provider boilerplate

A Modern Quality Pipeline and Testing Strategy for Frontend Projects

alex.opalic.dev@gmail.com (Alexander Opalic) — Sat, 25 Apr 2026 00:00:00 GMT

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
became the default dev/build engine across the major frameworks.
Vitest replaced Jest.
Playwright became the default for E2E.
ESLint adopted flat config; Biome
and Oxlint emerged as much faster
alternatives in Rust. TypeScript strict mode
became table stakes. Renovate replaced
Dependabot. In March 2026,
VoidZero shipped Vite+ as
the open-source culmination of that trend: one CLI that wraps Vite,
Rolldown, Vitest, Oxlint,
Oxfmt, and Tsdown.

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) is
the unified toolchain from VoidZero, Evan You’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× faster, fast enough to run on every keystroke
Prettier	Oxfmt	~30× faster, Prettier-compatible defaults
Jest	Vitest	ESM-native, browser mode, same matchers
webpack	Vite + Rolldown	~40× 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, Valibot, ArkType). 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 why as is a shortcut to avoid.

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 and your framework’s plugin. The 2026 alternative is Oxlint (Rust-based,
~50× 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 my opinionated ESLint setup for Vue projects.

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

eslint-plugin-regexp – ~60 correctness rules for regular
expressions. Cheap to add, catches real bugs.
@e18e/eslint-plugin – 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 guide to testing Vue composables with Vitest.

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/* 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 my Vue 3 testing pyramid guide.

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 (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). 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, or
hosted PactFlow). 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 spec and the contract is the
spec. Consumers validate their requests and assertions against it with
Schemathesis (property-based
fuzzing of every operation), Dredd (replays
example requests from the spec against the running provider), or
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).
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
(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
  catching hydration errors in Playwright tests
  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
(React/JSX), eslint-plugin-vuejs-accessibility
(Vue), eslint-plugin-astro — catch
missing alt, role mismatches, and other static violations before tests run.
Component. axe-core via
jest-axe for jsdom, or
@axe-core/playwright 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 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 on a list of routes for a dedicated, auditable
report.
Manual. Storybook’s a11y addon,
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 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
my Vue accessibility blueprint.

9. Visual regression

Catches unintended UI drift that unit and E2E tests miss.

Chromatic (hosted,
Storybook-native) or Playwright screenshots + a
diff tool like Lost Pixel for self-hosted. For a Vitest-native approach, see
how to do visual regression testing in Vue with Vitest.
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 on a
preview deployment. Run it against both a light and dark color scheme;
contrast regressions show up only in one.
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 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 for vulnerabilities
and Gitleaks for secrets, gated
to high-severity only to avoid alert fatigue.
Generate an SBOM (Software Bill of Materials) on every build with
Syft, Trivy, or
cdxgen, in
CycloneDX or SPDX format. This
is shifting from “nice to have” to “regulated requirement” in 2026
(EU CRA,
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 – i18next,
vue-i18n,
FormatJS / react-intl, and
Lingui 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
and
@intlify/eslint-plugin-vue-i18n
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 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, Netlify, or
Cloudflare Pages 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,
Greptile, and
Vercel 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 how I run automated QA with Claude Code, Agent Browser, and GitHub Actions.

15. Runtime observability

Layers 1–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 as the SDK. It’s the
only vendor-neutral option, and the JS ecosystem caught up in 2025–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
plus the auto-instrumentations emits OTLP/HTTP. Wrap
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 → SSR → hydration → client interaction,
all in one trace.
One collector, two backends. Run an
OpenTelemetry Collector with
two exporters. In dev, point it at Jaeger
or Grafana 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,
Grafana Cloud,
Dash0, or
Sentry’s OTel ingest.
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 has
become the default modern alternative to
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 (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 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:

[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 (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
(Mike Cohn) puts most of the weight on unit tests and very little on
E2E. Kent C. Dodds’
Trophy
moves the weight to integration tests because frontend bugs live at the
component-interaction layer. Spotify’s
Honeycomb
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”. Pactflow, from the
contract-testing camp, goes further: at scale, full E2E is
a tax with diminishing returns
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:

TypeScript strict + a fast linter + a formatter, wired into Lefthook
so format and lint run on staged files at commit time.
Vitest for utilities, run on PR.
MSW handlers for any module that hits the network, shared between
tests and the dev server.
Playwright for the single most important user journey, with hydration
and CSP listeners wired into a shared fixture.
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.
Preview deployments and Lighthouse CI (light and dark).
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.
Storybook + visual regression once the design system stabilises.
Accessibility audits in component tests and E2E.
Knip and bundle-size budgets once the codebase has weight.
i18n drift checking once you ship a second locale.
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–2026 wave of npm attacks (Shai-Hulud, the Rspack postinstall cryptominer, the axios 1.14.1 hijack) made the package manager’s defaults a real part of your security posture. I use pnpm 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:

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+ – unified toolchain from VoidZero (Vite, Rolldown, Vitest, Oxlint, Oxfmt, Tsdown)
pnpm supply chain security – the full list of defaults and settings discussed above
Vitest – including browser mode
Playwright
MSW – network-level API mocking for browser and Node
Pact and PactFlow – consumer-driven and bi-directional contract testing
Schemathesis, Dredd, Spectral – OpenAPI-based contract testing and linting
Lefthook – fast Git hooks manager (modern Husky alternative)
Storybook
Knip
Oxlint
Biome
Lighthouse CI
Lunaria – i18n drift detection
size-limit
axe-core
Syft – SBOM generation
CodeRabbit, Greptile – AI code review

Reference

The Practical Test Pyramid – Ham Vocke’s canonical write-up of Mike Cohn’s pyramid.
The Testing Trophy – Kent C. Dodds’ model for where to put the weight of your tests.
Testing of Microservices (Honeycomb) – Spotify’s case for integrated tests over isolated unit tests in a microservices world.
Pyramid or Crab? Find a testing strategy that fits – web.dev on choosing a shape for your context.
Proving E2E tests are a scam – Pactflow’s contract-first counter-position.
Contract Testing in Action – Marie Cruz & Lewis Prescott (Manning) on consumer-driven and bi-directional contracts in practice.
GitHub Actions in Action – Kaufmann, Bos & de Vries (Manning) on workflows, reusable actions, matrix builds, and self-hosted runners.
Frontend testing guide: 10 essential rules for naming tests

Exploratory QA with AI Agents: Building a Site-Agnostic Harness

alex.opalic.dev@gmail.com (Alexander Opalic) — Sun, 19 Apr 2026 00:00:00 GMT

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.

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.

git clone the repo, bun install, bun link
Open the folder in Claude Code and run /onboard-site https://yoursite.com
qa to pick a charter, agent, and browser in an interactive wizard
Read the report under qa-runs/charters/<charter>/

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.

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:

---
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, Codex’s exec reference, and GitHub Copilot CLI’s docs. They all do roughly the same thing. None of them agree on how to do it.

Claude Code:

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:

# 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:

# 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:

Write three shell scripts (one per CLI) that each build the right flag combo.
Materialize AGENTS.md for Codex and Copilot but use --append-system-prompt for Claude.
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.
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:

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 and Microsoft’s 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):

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):

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 and one line of prompt in _browser-workflow.md:

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:

{ "browser": "playwright-cli" }

Or override per invocation:

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:

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.
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 (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! Chapter 2 and Michael Bolton’s An Exploratory Tester’s Notebook 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.

How to Use Claude Code as an AI QA Tester with Agent Browser, the single-charter version that predated this harness
Building an AI QA Engineer with Claude Code and Playwright MCP, the MCP-based cousin
Spec-Driven Development with Claude Code in Action, how I plan non-trivial work with parallel subagents

The agent forgets. Your charters don’t.

How to Use Claude Code as an AI QA Tester with Agent Browser

alex.opalic.dev@gmail.com (Alexander Opalic) — Sat, 11 Apr 2026 00:00:00 GMT

Overview

Claude Code and 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.

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:

Opens your app in a real browser
Claude explores it like a user: clicking navigation, filling forms, checking for JS errors
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 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.

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:

Claude runs snapshot -i and sees: nav[@e10] > a[@e11] "Home" | a[@e12] "Workouts" | a[@e13] "Settings"
Claude decides to test navigation and runs click @e12
Claude runs snapshot -i again and sees the Workouts page loaded
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.

Install Agent Browser globally and set up the browser:

npm install -g agent-browser
agent-browser install  # Download Chrome from Chrome for Testing

Open a website:

agent-browser open https://www.otto.de

You’ll see:

✓ OTTO - Mode, Möbel & Technik » Zum Online-Shop
  https://www.otto.de/

Take a snapshot to see the page structure:

agent-browser snapshot -i

The -i flag shows only interactive elements. You’ll see something like:

- 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.

Try clicking a nav link:
```
agent-browser click @e9
```
The browser navigates to the Damen-Mode page. Take another snapshot to see the new page:
```
agent-browser snapshot -i
```

Try filling the search box and submitting:

agent-browser fill @e3 "Sneaker"
agent-browser press Enter

Check for JavaScript errors:
```
agent-browser console
```
Close the browser when you’re done:
```
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`

claude -p runs Claude Code with a one-shot prompt from the terminal. No interactive session, no back-and-forth.

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:

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:

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.

Now give Claude a more structured QA prompt:

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:

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:

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:

## 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

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

Point Claude at your app (here we use otto.de, but swap in your own URL):

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.

Run Claude with a JSON schema to get a structured QA report:

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):

{
  "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.

Extract the structured output with jq:

# 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:

{
  "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": []
}

Use it in a script to make pass/fail decisions:
```
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

Building an AI QA Engineer with Playwright MCP, the MCP-based version with richer browser control
Claude Code Skills, Hooks, and Subagents, creating reusable skills for your QA prompts
Claude Code Customization Guide, deeper coverage of CLAUDE.md, skills, and subagents
Agent Browser documentation, full command reference and setup guide

How to Catch Hydration Errors in Playwright Tests (Astro, Nuxt, React SSR)

alex.opalic.dev@gmail.com (Alexander Opalic) — Mon, 06 Apr 2026 00:00:00 GMT

Your E2E tests pass. The page loads, buttons work.

But open the browser console:

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:

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.

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

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.

I first saw this approach in the 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:

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

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 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.

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.

App Screenshots: An AI Coding Agent Skill for Visual Documentation

alex.opalic.dev@gmail.com (Alexander Opalic) — Fri, 27 Mar 2026 00:00:00 GMT

TLDR

I built a skill 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 guide to CLAUDE.md, skills, and subagents.

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, 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:

Discovers pages by reading the site’s navigation
Screenshots each page with SVG annotations injected directly into the DOM
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 walkthrough skill does something similar for codebases with interactive Mermaid diagrams.

## 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:

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

If you’re building your own skill library, see how I built a skill for searching Claude’s conversation history.

The Software Factory: Why Your Team Will Never Work the Same Again

alex.opalic.dev@gmail.com (Alexander Opalic) — Sun, 22 Mar 2026 00:00:00 GMT

We Already Have Everything We Need

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:

“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 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 lets you run Claude Code programmatically in CI/CD pipelines, GitHub Actions, or any automation script
Scheduled tasks let agents run on a timer: daily code reviews, dependency checks, morning briefings
Subagents are specialized agents you can create for specific tasks, each with their own tools and permissions
Agent teams let you orchestrate multiple Claude Code sessions working in parallel on different parts of a problem
Skills extend what your agents can do with simple Markdown files
The Claude Agent SDK lets you build production multi-agent systems with orchestration, guardrails, and tracing
Claude 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:

Understanding Claude Code’s Full Stack: MCP, Skills, Subagents, and Hooks

But first, how we used to work.

How We Worked Before: Beer Commerce

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

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.

Steve Yegge built this for real with Gas Town. He calls it “Kubernetes for AI coding agents”, 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: 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, 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:

“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 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:

Spec-Driven Development with Claude Code in Action

What Are Skills?

A factory is only as good as its tooling. For AI coding agents, that tooling is skills.

As Simon Willison explains, 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:

How to Speed Up Your Claude Code Experience with Slash Commands

The New Team: Everyone Is a Builder

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 “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 that “we are already seeing the end of two-pizza teams (6-10 people) thanks to AI.” Andres Max goes further: “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: “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, 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

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 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: “An agent cannot be held accountable.” The platform becomes the orchestration layer where humans and agents interact.

Combined with their Cursor integration, 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. 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 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:

7 Agent Team Patterns for Claude Code

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.

Moss calls this 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

Claude Code runs in the cloud. You can schedule agents and build skills. Early adopters are doing this now.

As Andres Max put it: “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?

In Five Years, Developers Won’t Write Code By Hand

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

Building a Real-Time Todo App with Jazz and Vue 3

alex.opalic.dev@gmail.com (Alexander Opalic) — Sat, 07 Mar 2026 00:00:00 GMT

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.

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:

const Counter = co.map({ count: z.number() });

That’s one line of schema. Now subscribe to it in a Vue component:

<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>

Counter.create({ count: 0 }) creates a new CoValue instance and persists it locally.
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.
$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).

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:

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.

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:

The high-level architecture:

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:

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:

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:

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.

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:

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:

@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:

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:

<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

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

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

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:

Vue Composables Style Guide: Lessons from VueUse’s Codebase

Dynamic Page Title

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

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(...):

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:

<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 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 (by Rocicorp, based on this Observable post 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:

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:

Building a Pinia Plugin for Cross-Tab State Syncing

Running It

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 for more, and the community-jazz-vue package (source code) for the full Vue API.

Source code: github.com/alexanderop/vue-jazz-todo-example

How I Turned Claude Code's Thinking Indicator into a One Piece Adventure

alex.opalic.dev@gmail.com (Alexander Opalic) — Thu, 12 Feb 2026 00:00:00 GMT

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.

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.

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.

{
  "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:

[
  "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

Open ~/.claude/settings.json.
Add the spinnerVerbs block anywhere at the top level.
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 customize the status line or how I added sound effects with hooks. For a broader overview of all the customization options, see the full customization guide.

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.

How I Added Sound Effects to Claude Code with Hooks

alex.opalic.dev@gmail.com (Alexander Opalic) — Wed, 11 Feb 2026 00:00:00 GMT

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 setting up Claude Code notification hooks. 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 overview of the full Claude Code feature stack.

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:

// ~/.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 custom status line script. The status line reads these files to show the current Claude Code state in my terminal prompt.

How to Set This Up Yourself

Create the sounds directory: mkdir -p ~/.claude/sounds
Drop your MP3 files in there (any short sound clips work)
Add the hooks config to ~/.claude/settings.json
Restart Claude Code

On Linux, replace `afplay` with `aplay` or `paplay`. On Windows WSL, you can use `powershell.exe -c (New-Object Media.SoundPlayer "path").PlaySync()`.

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.

Building a Walkthrough Skill for AI Coding Agents

alex.opalic.dev@gmail.com (Alexander Opalic) — Sun, 08 Feb 2026 00:00:00 GMT

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 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.

What It Does

You ask your agent something like “walkthrough how does authentication work” and it:

Spawns 2–4 subagents to explore relevant parts of your codebase in parallel
Synthesizes findings into 5–12 key concepts with connections
Generates a self-contained HTML file with an interactive Mermaid diagram
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:

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:

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:

Scope understanding — The main agent clarifies what you’re asking about and identifies which areas of the codebase are relevant
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
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

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 using AI for diagrams 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

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.

From Tasks to Swarms: Agent Teams in Claude Code

alex.opalic.dev@gmail.com (Alexander Opalic) — Sun, 08 Feb 2026 00:00:00 GMT

In my previous post 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.

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:

Agent teams are disabled by default. Enable them by adding `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` to your `settings.json` or environment.

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.

// 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.

// 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.

// 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.

// 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.

// 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.

// 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.

// 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:

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.

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:

Use a team of agents that will do QA against my blog. It's running at http://localhost:4321/

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:

// ~/.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:

// ~/.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:

// .claude/settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Then tell Claude what you want:

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.

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.

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.

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.

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.

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.

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.

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.

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 spec-driven development post

VMark: Hand-Drawn Annotations for Presentations

alex.opalic.dev@gmail.com (Alexander Opalic) — Tue, 03 Feb 2026 00:00:00 GMT

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 stand out.

VMark creates a “live drawing” effect that grabs attention and guides your audience’s focus.

Getting Started

Import VMark from the presentation feature:

Basic usage wraps text in the component:

<VMark>text to emphasize</VMark>

The default is underline, and it animates on click.

Annotation Types: Underline & Circle

Underline is the default. Use it for general emphasis.

Circle draws attention to key terms or important words.

<VMark type="underline">emphasis</VMark>
<VMark type="circle" color="red">key term</VMark>

Annotation Types: Box & Highlight

Box frames content like code or definitions.

Highlight creates a marker effect. It uses 40% opacity so text stays readable.

<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:

This approach is wrong

Don’t do this

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

The brackets prop controls direction:

<VMark type="bracket" brackets={['left', 'right']}>
  phrase
</VMark>

Options: left, right, top, bottom

Color Presets

VMark includes 24 color presets:

Custom CSS colors also work: #ff6b6b, rgb(100, 200, 150), rgba(255, 0, 0, 0.5)

Controlling Timing: Sequential

By default, VMark annotations appear sequentially with each click.

This one appears second.

And this one third.

Just place VMark components in order. Each one advances the click counter.

Controlling Timing: Explicit

Use at to specify an exact click number:

Third (at=3)

First (at=1)

Second (at=2)

<VMark at={3}>appears on click 3</VMark>
<VMark at={1}>appears on click 1</VMark>

Advanced Timing: Relative & Ranges

Relative positioning with +N:

+1 from previous

Ranges show content only during a window:

<VMark at={[3, 5]} type=“highlight” color=“yellow”>Visible from click 3 to 4

<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 rough-notation 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

Import from @features/presentation

7 annotation types: underline, circle, box, highlight, strike-through, crossed-off, bracket

24 color presets plus custom CSS colors

Full click system integration with at prop for timing control

Press Escape to exit presentation mode.

Spec-Driven Development with Claude Code in Action

alex.opalic.dev@gmail.com (Alexander Opalic) — Sun, 01 Feb 2026 00:00:00 GMT

I’m building a simplified sync engine from scratch using Nuxt 4.
My approach: study how production-grade frameworks solve the hard problems, then implement a minimal version myself.

Jazz 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 local-first web development and why it matters, see my earlier post.)

The Workflow

Instead of diving into code, I used Claude Code as an AI development teamwith 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.

Phase 1: Research with Parallel Subagents

The 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

What Happened

Claude spawned 5 parallel research agents, each investigating a specific aspect of Jazz:

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.

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

research longer and improve the plan

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

# 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

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

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:

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

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 customization guide covers the fundamentals.)

The 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

Understanding Claude Code’s Task System

Claude Code’s task systeminspired by 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:

{
  "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

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 would be more appropriate. Ralph is elegantly simplea bash loop that feeds a markdown file into Claude Code repeatedly:

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

Why This Pattern Works

Context isolation: Each subagent starts fresh, reading only what it needsno accumulated cruft
Persistent progress: Tasks survive session restarts; pick up where you left off
Dependency-aware parallelism: Claude identifies which tasks can run concurrently
Atomic commits: Every task = one commit, making rollbacks trivial
Spec as contract: Subagents reference the spec, ensuring consistency

Backpressure: Let the System Catch Mistakes

One crucial element that makes atomic commits powerful: backpressure. Instead of manually reviewing every change, set up pre-commit hooks that run tests, linting, and type checking automatically.

# .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 (includes additional manual changes).

And despite orchestrating 14 subagents, the main session’s context stayed manageable:

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

spin up multiple subagents for your research task

Triggers Claude to spawn parallel agents, each investigating independently. Much faster than sequential research.

2. Spec-First Development

your goal is to write a report/document

Forces Claude to produce a written artifact before any code. This becomes the source of truth.

3. Interview Before Implementation

use the ask_user_question tool... before we implement

Surfaces ambiguities and design decisions before they become bugs.

4. Task Delegation with Commits

use the task tool and each task should only be done by a subagent after each task do a commit before you continue

Creates the orchestration pattern with atomic commits.

5. Role Assignment

you are the main agent and your subagents are your devs

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:

CLAUDE_CODE_TASK_LIST_ID=myproject claude

Or add to .claude/settings.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

Claude Code CLI (latest version with task tools)
A spec document (markdown works great)
Reference codebases if learning from existing implementations
Git for atomic commits

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.

My Opinionated ESLint Setup for Vue Projects

alex.opalic.dev@gmail.com (Alexander Opalic) — Sat, 31 Jan 2026 00:00:00 GMT

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:

How to Write Clean Vue Components explains why I separate business logic into pure functions
How to Structure Vue Projects covers my feature-based architecture approach
Building a Modular Monolith with Nuxt Layers applies feature isolation to Nuxt projects
The Problem with as in TypeScript covers why I ban type assertions
Robust Error Handling in TypeScript introduces the Result pattern behind my tryCatch rule
Vue 3 Testing Pyramid explains my integration-first testing strategy
Frontend Testing Guide shares my test naming conventions

ESLint rules are how I enforce these patterns automatically—so the codebase stays consistent even as the team grows.

**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.

Why Two Linters? Oxlint + ESLint

I run two linters: Oxlint first, then ESLint. Why? Speed and coverage.

Oxlint: The Speed Demon

Oxlint is written in Rust. It runs 50-100x faster than ESLint on large codebases. My pre-commit hook completes in milliseconds instead of seconds.

# 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.

// eslint.config.ts
export default defineConfigWithVueTs(
  // ... other configs
  ...pluginOxlint.buildFromOxlintConfigFile('./.oxlintrc.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.

// eslint.config.ts
{
  rules: {
    'complexity': ['warn', { max: 10 }]
  }
}

```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... } } } } } } ``` ```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'
  }
}

```typescript const label = isLoading ? 'Loading...' : hasError ? 'Failed' : 'Success' ``` ```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'
    }]
  }
}

`as const` assertions are always allowed, even with `assertionStyle: 'never'`. Const assertions don't bypass type checking—they make types more specific. ```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()
}

TypeScript ESLint: 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.

// eslint.config.ts
{
  rules: {
    'no-restricted-syntax': ['error', {
      selector: 'TSEnumDeclaration',
      message: 'Use literal unions or `as const` objects instead of enums.'
    }]
  }
}

```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]

ESLint: no-restricted-syntax

No else/else-if

else and else-if blocks increase nesting. Early returns are easier to read and reduce cognitive load.

// 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.'
      }
    ]
  }
}

```typescript function getDiscount(user: User) { if (user.isPremium) { return 0.2 } else if (user.isMember) { return 0.1 } else { return 0 } } ``` ```typescript function getDiscount(user: User) { if (user.isPremium) return 0.2 if (user.isMember) return 0.1 return 0 } ```

ESLint: 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.

// 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].'
    }]
  }
}

```typescript async function fetchUser(id: string) { try { const response = await api.get(`/users/${id}`) return response.data } catch (error) { console.error(error) return null } } ``` ```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'
  }
}

```vue ``` ```vue

```

ESLint: 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 How to Structure Vue Projects for more on this approach.

// 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)

```typescript // src/features/workout/composables/useWorkout.ts // Cross-feature import! ``` ```typescript // src/features/workout/composables/useWorkout.ts // Use shared database layer instead ```

eslint-plugin-import-x: no-restricted-paths

Vue Component Naming

Consistent naming makes components easy to find and identify.

// 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']
  }
}

```vue Click ``` ```vue Click ```

eslint-plugin-vue: component rules

Dead Code Detection in Vue

Find unused props, refs, and emits before they become tech debt.

// 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'
  }
}

```vue

Click ``` ```vue

Click ```

eslint-plugin-vue: no-unused-properties

No Hardcoded i18n Strings

Hardcoded strings break internationalization. The @intlify/vue-i18n plugin catches them.

// 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.

```vue Save Changes

No items found

``` ```vue {{ t('common.save') }}

```

eslint-plugin-vue-i18n

No Disabling i18n Rules

Prevent developers from bypassing i18n checks with eslint-disable comments.

// eslint.config.ts
{
  files: ['src/**/*.vue'],
  plugins: {
    '@eslint-community/eslint-comments': pluginEslintComments
  },
  rules: {
    '@eslint-community/eslint-comments/no-restricted-disable': [
      'error',
      '@intlify/vue-i18n/*'
    ]
  }
}

```vue Save Changes ``` ```vue {{ t('common.save') }} ```

@eslint-community/eslint-plugin-eslint-comments

No Hardcoded Route Strings

Use named routes instead of hardcoded path strings for maintainability.

// 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.'
      }
    ]
  }
}

```typescript router.push('/workout/123') router.push(`/workout/${id}`) ``` ```typescript router.push({ name: RouteNames.WorkoutDetail, params: { id } }) ```

ESLint: 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 Vue 3 Testing Pyramid: A Practical Guide with Vitest Browser Mode.

// 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.'
        }
      ]
    }]
  }
}

```typescript const { getByText } = render(MyComponent) const wrapper = mount(MyComponent) ``` ```typescript const { page } = await createTestApp({ route: '/workout' }) ```

This ensures all tests use consistent setup with routing, i18n, and database.

ESLint: no-restricted-imports

Enforce pnpm Catalogs

When using pnpm workspaces, enforce that dependencies use catalog references.

// eslint.config.ts
export default defineConfigWithVueTs(
  // ... other configs
  ...pnpmConfigs.recommended,
)

This ensures dependencies are managed centrally in pnpm-workspace.yaml.

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.

// eslint.config.ts
{
  files: ['src/**/*.vue'],
  rules: {
    'vue/define-props-destructuring': 'error',
    'vue/prefer-use-template-ref': 'error'
  }
}

```vue

Click ``` ```vue

Click ```

eslint-plugin-vue: define-props-destructuring

Explicit Component APIs

Require defineExpose and defineSlots to make component interfaces explicit.

// eslint.config.ts
{
  files: ['src/**/*.vue'],
  rules: {
    'vue/require-expose': 'warn',
    'vue/require-explicit-slots': 'warn'
  }
}

```vue ``` ```vue

```

eslint-plugin-vue: require-expose

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.

// eslint.config.ts
{
  files: ['src/**/*.vue'],
  rules: {
    'vue/max-template-depth': ['error', { maxDepth: 8 }],
    'vue/max-props': ['error', { maxProps: 6 }]
  }
}

```vue

Too deep!

``` ```vue Title Content ```

eslint-plugin-vue: max-template-depth

Better Assertions in Tests

Use specific matchers for clearer test failures.

// 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'
  }
}

```typescript expect(value === null).toBe(true) expect(arr.length).toBe(3) expect(arr.includes('foo')).toBe(true) ``` ```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'
  }
}

```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()

eslint-plugin-vitest

Prefer Vitest Locators in Tests

Use Vitest Browser locators instead of raw DOM queries.

// 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.'
    }]
  }
}

```typescript const button = container.querySelector('.submit-btn') await button?.click() ``` ```typescript const button = page.getByRole('button', { name: 'Submit' }) await button.click() ```

Vitest Browser Mode

Unicorn Rules

The eslint-plugin-unicorn package catches common mistakes and enforces modern JavaScript patterns.

// 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:

// 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

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 Vue Composables Style Guide: Lessons from VueUse’s Codebase.

// 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' })
        }
      }
    }
  }
}

```typescript // src/composables/useFormatter.ts export function useFormatter() { return { formatDate: (d: Date) => d.toISOString() // No Vue imports! } } ``` ```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 } })
        }
      }
    }
  }
}

```vue Click ``` ```vue Click ``` 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.

No let in describe Blocks

Mutable variables in test describe blocks create hidden state. Use setup functions instead.

// 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' })
        }
      }
    }
  }
}

```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')
  })
})

Extract Complex Conditions

Complex boolean expressions should have names. Extract them into variables.

// 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])

```typescript if (user.isActive && user.role === 'admin' && !user.isBanned) { showAdminPanel() } ``` ```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' })
      }
    }
  }
}

```typescript const workouts = await getWorkoutRepository().findAll() // Might throw! ``` ```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,
)

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.

Next Level GitHub Copilot: Agents, Instructions & Automation in VS Code

alex.opalic.dev@gmail.com (Alexander Opalic) — Sat, 24 Jan 2026 00:00:00 GMT

Next Level GitHub Copilot

Agents.md Subagents & Skills

by Alexander Opalic

Workshop Outline

What is an Agent? (LLM → Agent transformation)
Context Engineering (the real skill)
Back Pressure (core validation concept)
AGENTS.md (open standard)
Subagents (specialized invocation)
Skills (portable workflows)
Live Demo

🙋 Who has used GitHub Copilot in VS Code?

About me

Alex Opalic

🚀 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

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)

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)

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

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

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:

1. **Compaction** — Summarize history, reset periodically 2. **Structured note-taking** — External memory systems 3. **Sub-agent architectures** — Distribute work across focused contexts

Back Pressure

Why Back Pressure Matters

Back pressure = automated feedback that validates agent work

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

“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

# 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

❌ Bloated (847 lines)

# 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...]

40% context consumed before work starts

✅ Lean (58 lines)

# 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 |

Docs loaded on-demand when needed

The /learn Skill

# 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:

Enable tools in Copilot Chat (hammer icon)
Call explicitly with #runSubagent
Or accept when Copilot suggests one

Use Cases

- Specialized searches (explore codebase, web, docs) - Long-running tasks (data analysis, refactoring) - TDD workflows (test generation, validation) - Multi-step processes (research, summarize, act) --- ## Explore Subagent Flow

Click Start to see how the main agent delegates file search to a specialized Explore subagent.

Parallel Subagent Execution

Click Start to see the fan-out/fan-in pattern where multiple subagents search in parallel.

Subagent in nanocode: Fetch Tool

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

.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?”

Description matches → skill.md loads (~500 tokens)
Agent runs: bun cli top-pages --range 7d --pattern "/vue/"
Agent reads references/seo/thresholds.md for interpretation
Agent fetches actual pages with WebFetch
Returns specific fixes based on real content

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:

Mac (Homebrew):

brew install node python

Windows (winget):

winget install OpenJS.NodeJS Python.Python.3.12

Or download from: nodejs.org | python.org

Verify:

node --version && npx --version && python --version

Demo: Building a Skill

Enable Skills in VS Code settings
Install skill-creator via CLI
Prompt to generate a new skill

Step 1: Enable Skills

VS Code Setting:

{
  "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

---
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

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

◇  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

---
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.

help me to create a workout tracking app use the #askQuestions tool to find out how the tech specs should be

┌─────────────────────────────────────────────────────────────┐
│                     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:

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

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

Key Takeaways

Agents = LLM + Tools + Loop (nanocode shows this simply)
Context is finite — treat tokens as budget
AGENTS.md — standardized project context
Subagents — specialized agents for complex tasks
Skills — portable workflows that load on demand

Thank You!

Questions?

Resources

VS Code: Using Agents - Agent types and session management
Anthropic: Effective Context Engineering - Context engineering guide
VS Code: Introducing Agent Skills - Agent Skills deep dive
VS Code: Context Engineering Guide - Microsoft’s context engineering workflow
AGENTS.md - Open standard for agent documentation
Agent Skills Spec - Open standard for portable agent skills
nanocode - Minimal agent implementation in TypeScript
Writing a Good CLAUDE.md - Best practices for agent documentation
Plausible SEO Skill - Skills deep dive with Plausible example
Don’t Waste Your Back Pressure - Why automated feedback loops make agents more effective
Workshop Solution - Complete code examples from this workshop
Learn Prompt - Skill that helps agents learn from conversations

What's New in VS Code Copilot: January 2026 Update

alex.opalic.dev@gmail.com (Alexander Opalic) — Sat, 24 Jan 2026 00:00:00 GMT

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.

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.

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:

---
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 Claude Code handles skills and subagents with tool restrictions.

Control Subagent Availability

Use the infer attribute to control whether an agent can be used as a subagent:

---
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:

Creating Your First Skill

Create a directory structure:

SKILL.md:

---
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:

{
  "chat.agentSkillsLocations": [
    ".github/skills",
    "~/shared-skills",
    "/team/copilot-skills"
  ]
}

Extension-Contributed Skills

Extensions can now contribute skills via their package.json:

{
  "contributes": {
    "copilotSkills": [
      {
        "name": "docker-compose",
        "description": "Helps create and debug Docker Compose configurations",
        "path": "./skills/docker-compose"
      }
    ]
  }
}

Or dynamically via the new API:

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

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 progressive disclosure approach where context is loaded on-demand rather than crammed into a single file.

Example copilot-instructions.md:

# 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

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:

{
  "github.copilot.chat.claude.showThinking": true
}

Model Picker

You can now select which Claude model to use:

Open the Chat view
Click the model selector dropdown
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:

Kitty Keyboard Protocol (CSI u)

VS Code’s terminal now supports the 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:

{
  "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:

{
  "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 The output auto-expands on command execution and collapses on success #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 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, 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, #287773, #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
sed -i when editing files within the workspace #288318
od, xxd, and safe docker commands #287652

SGR 221/222 Escape Sequences

The terminal now supports SGR 221 and 222 escape sequences #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 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, 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 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 for quick access:

Agents ▼
├── Local Agent
├── Background Agent
├── Cloud Agent
└── Codex Agent       ← New!

New MCP Server Command

A new workbench.mcp.startServer command #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—no more losing your chat history when you want a fresh start.

New Local Chat Command

A new “New Local Chat” command #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, 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 MCP server configuration #283945:

{
  "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:

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, and increased locally persisted chat sessions #283123.

Resizable Sessions Sidebar

You can now resize the sessions sidebar in the Chat view by dragging the separator #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

Accessible View Streams Thinking Content

The Accessible View now dynamically streams thinking content #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. Enterprise and Business users also get access to the Manage Models action #287814.

Editor & Language Improvements

Improved Shebang Detection

VS Code now recognizes Deno, Bun, and other modern JavaScript runtimes #287819 for better language detection when opening scripts.

Better Ghost Text Visibility

Improved visibility of ghost text in next edit suggestions #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—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 lets you control whether file paths and glob patterns match case-sensitively.

Bracket Match Foreground Color

New editorBracketMatch.foreground theme color #85775 enables customization of matched bracket text color.

Parallel Build Tasks

Dependent build tasks can now run in parallel #288439, improving build performance for projects with multiple independent compilation steps.

Git Delete File Command

A new “Git: Delete File” command #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:

Create a custom agent at .github/agents/researcher.md with restricted tools
Create a skill at .github/skills/my-skill/SKILL.md
Ask Copilot: “What skills and subagents do you have available?”
Test parallel execution: “Use subagents to research three different topics simultaneously”
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 Building Your Own Coding Agent from Scratch for a hands-on guide to the underlying patterns.

Key settings to know:

{
  "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

Claude Integration

Terminal

MCP

Chat & Sessions

Editor & Other

Iteration Plan

#286040 - January 2026 Iteration Plan

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.

Presentation Mode: Turn Your Blog Posts into Slides

alex.opalic.dev@gmail.com (Alexander Opalic) — Fri, 23 Jan 2026 00:00:00 GMT

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!

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!

---
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:

↖ 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)

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?

Circle important code sections
Draw arrows connecting concepts
Add quick annotations for Q&A
Highlight key points in diagrams
Sketch ideas during discussions

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:

Keeps audience focused on the current point
Creates natural pacing for your talk
Prevents information overload
Makes complex topics digestible

V-Click Syntax

In MDX files, use components to control reveals:


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:

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:

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:

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 format */}

# My Title

---

{/* .md format */}
<!--slide:{"layout":"cover"}-->
# My Title

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

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

Content Length

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

Accessibility Features

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

Speaker Notes & Presenter View

Press N to open the presenter view popup!

The presenter view shows:

Current and next slide previews
Speaker notes with click-step highlighting
A timer you can start/pause/reset
Navigation controls

{“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.”}

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!

{“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.”}

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!

Stop Bloating Your CLAUDE.md: Progressive Disclosure for AI Coding Tools

alex.opalic.dev@gmail.com (Alexander Opalic) — Sun, 18 Jan 2026 00:00:00 GMT

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.

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.

That’s the constraint. Your context is just an array of tokens—a sliding window that forgets everything the moment the conversation ends.[^1]

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.

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:

# 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:

## Code Style
- Use 2-space indentation
- Prefer single quotes
- Always add trailing commas
- Maximum line length: 100 characters

✅ Let ESLint handle it:

{
  "extends": ["@nuxt/eslint-config"]
}

The rules are already there—you just don’t repeat them in prose:

// 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:

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). It:

Analyzes the conversation for reusable, non-obvious insights
Finds the right place in /docs to save it (or proposes a new file)
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:

## 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 detailed comparison of CLAUDE.md, skills, and subagents.

.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 why I use custom research agents instead of MCPs.

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:

## 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:

# 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:

# 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:

## 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.

[^2]: HumanLayer’s guide on 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. 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. Dex is the founder of HumanLayer and creator of the Ralph technique for autonomous AI coding. His 12 Factor Agents manifesto includes “Make Your Agent a Stateless Reducer” as Factor 12.

[^7]: Moss, Don’t Waste Your Back Pressure. 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. 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. 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.

How I Built a Skill That Lets Me Talk to Claude's Conversation Memory

alex.opalic.dev@gmail.com (Alexander Opalic) — Sat, 17 Jan 2026 00:00:00 GMT

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.

How Claude Code Stores Conversations

Every Claude Code session gets saved as a JSONL file in ~/.claude/projects/. The directory structure looks like this:

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:

{"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:

The SKILL.md file tells Claude when to activate this skill:

---
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:

@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:

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:

# 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:

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:

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:

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:

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:

No more re-solving problems - Claude finds past solutions instantly
Daily digests for standups - “What did we work on yesterday?” gives a ready summary
Commands are preserved - You can recreate exact solutions with the same commands
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.

If you want to extend Claude Code with custom skills, check out my post on building a Claude Code plugin for packaging and sharing skills across projects.

In Five Years, Developers Won't Write Code By Hand

alex.opalic.dev@gmail.com (Alexander Opalic) — Wed, 14 Jan 2026 00:00:00 GMT

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 guide to Claude Code’s architecture.)

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 The Age of the Generalist—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 how I use LLMs in my daily work.)

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
[^2]: Ralph - Automation framework for AI-driven development
[^3]: Kent Beck, 90% of My Skills Are Now Worth $0
[^4]: Burke Holland, Opus 4.5 is Going to Change Everything
[^5]: Lee Robinson, AI codes better than me. Now what?
[^6]: Martin Fowler, How AI Will Change Software Engineering
[^7]: Geoffrey Huntley, What do I mean by some software devs are “ngmi”?
[^8]: 12 Factor Agents - Principles for production-grade AI agents

Mutation Testing with AI Agents When Stryker Doesn't Work

alex.opalic.dev@gmail.com (Alexander Opalic) — Tue, 13 Jan 2026 00:00:00 GMT

The Coverage Lie

Code coverage lies. A test that exercises a line doesn’t mean it verifies that line does the right thing:

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:

// 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:

Mutate: Introduce a small bug (change > to >=, swap && for ||, delete a line)
Run tests: Execute your test suite against the mutated code
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:

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.

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.

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

My testing strategy 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:

Read your source code
Apply mutations systematically
Run pnpm test --run
Record whether tests passed or failed
Restore the original code
Report surviving mutants with suggested fixes

I adapted a Claude Code skill originally created by Paul Hammond that codifies this workflow.

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

// 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

// 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

// 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:

// 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:

Full Mutation Testing Skill (click to expand)

---
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`
- ...

Step 2: Invoke It

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

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. 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 an automated QA agent 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.

Key Takeaways

Coverage doesn’t equal confidence. High code coverage can coexist with ineffective tests.
Mutation testing reveals test gaps. By breaking code and checking if tests notice, you find what’s actually being verified.
AI agents can execute manual mutation testing. When tooling doesn’t support your stack, an agent can apply the algorithm systematically.
Focus on surviving mutants. Each one is a potential bug your tests wouldn’t catch.
This complements, not replaces. Use this alongside coverage reports, not instead of automated mutation testing where available.

Resources

Paul Hammond’s Mutation Testing Skill - The original skill this post is based on
Mutation Testing on Wikipedia
Stryker Mutator - When your stack supports it
My TDD workflow with Claude Code - Related approach for test-first development

Why You Don't Need the Nuxt MCP When You Use Claude Code

alex.opalic.dev@gmail.com (Alexander Opalic) — Wed, 31 Dec 2025 00:00:00 GMT

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 in their engineering blog.

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).

If you want to dive deeper into what MCP is and how it works, check out my post on What Is the Model Context Protocol (MCP)?.

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 how I added llms.txt to my own blog—it’s becoming a standard way for sites to expose their content to AI.

This approach has several advantages:

Only the description gets loaded as context — The agent description is minimal, not the entire tool schema
You can customize it — Full control over what the agent knows and how it behaves
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 Claude Code subagents — agents keep your main context clean by delegating specialized tasks.

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.

Example: Nuxt Content Specialist Agent

Here’s how my Nuxt Content agent looks. Just put it under .claude/agents:

````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\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\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\n\n\n\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\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\n\n\n\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\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\n\n\n\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\nSince this involves MDC (Markdown Components) syntax, use the nuxt-content-specialist agent to fetch relevant documentation about component usage in Markdown files.\n\n\n\n\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\nSince search requires specific Nuxt Content APIs, use the nuxt-content-specialist agent to fetch the latest documentation on search implementation patterns.\n\n 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

Collections: Defining collections in content.config.ts, schema validation with Zod, collection types (page, data), import sources
Content Files: Markdown, YAML, JSON, CSV support and their appropriate use cases
MDC Syntax: Embedding Vue components in Markdown, props, slots, block vs inline components
Querying: queryCollection(), queryCollectionNavigation(), queryCollectionItemSurroundings(), queryCollectionSearchSections()
Rendering: <ContentRenderer>, <Slot>, prose components, custom renderers
Search: Full-text search implementation, search sections, indexing strategies
Sources: Custom data sources, remote content, transformers
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:

Fetch documentation index from https://content.nuxt.com/llms.txt to understand available documentation structure
Categorize user inquiry into appropriate domain (collections, querying, MDC, search, etc.)
Identify specific documentation URLs from the index relevant to the task
Fetch targeted documentation pages for accurate, up-to-date information
Review project context by reading relevant local files (content.config.ts, existing content files)
Provide actionable guidance with TypeScript code examples following project conventions
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

// content.config.ts - Collection definition pattern
export const collections = {
  content: defineCollection({
    type: 'page',
    source: '**/*.md'
  })
}

<!-- 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.

Claude Code Customization: CLAUDE.md, Slash Commands, Skills, and Subagents

alex.opalic.dev@gmail.com (Alexander Opalic) — Sun, 21 Dec 2025 00:00:00 GMT

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

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.

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 (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.

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

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

# 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).

Where It Lives

The Dexie.js Solution

---
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.

````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):

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

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

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:

mkdir -p docs/research

Step 3: Write the Research Document

Structure the document with these sections:

# 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.

How to Customize Your Claude Code Status Line

alex.opalic.dev@gmail.com (Alexander Opalic) — Sun, 14 Dec 2025 00:00:00 GMT

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.

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:

#!/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

chmod +x ~/.claude/statusline.sh

Step 3: Configure Claude Code

Add the status line configuration to ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  }
}

If you already have settings in this file, add the statusLine block alongside your existing configuration.

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:

#!/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

Troubleshooting

Status line not showing?

Check that jq is installed: brew install jq (macOS) or apt install jq (Linux)
Verify the script is executable: ls -la ~/.claude/statusline.sh
Restart Claude Code after making changes

Test your script manually:

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%

The status line script requires `jq` for JSON parsing. If you don't have it installed, the script will fail silently.

Taking it further

The status line is one piece of the Claude Code customization puzzle. Once you’re comfortable with scripts like this, explore:

Notification hooks to get desktop alerts when Claude needs input
Slash commands to automate repetitive tasks
The full Claude Code feature stack 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.

Vue 3 Testing Pyramid: A Practical Guide with Vitest Browser Mode

alex.opalic.dev@gmail.com (Alexander Opalic) — Sun, 14 Dec 2025 00:00:00 GMT

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

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:

Catch bugs before users do
Enable refactoring — change code freely knowing tests will catch regressions
Document behavior — tests act as a “user manual” for your code

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.

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.

<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.

// 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.

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.

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.

Setting Up Vitest Browser Mode

Vitest 4.0+ requires a browser provider package. Install the dependencies:

npm install -D vitest @vitest/browser-playwright vitest-browser-vue playwright

You can use `@vitest/browser-playwright` (recommended) or `@vitest/browser-webdriverio`. Playwright offers the best developer experience with automatic browser downloads.

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:

// 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

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.

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:

// ❌ 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 (...).

// 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:

// ✅ 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:

// ✅ 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.

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.

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.

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.

// 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
  }
}

```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
cleanup: () => void
}

export async function createTestApp(options: CreateTestAppOptions = {}): Promise {
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 =

// 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()
})

Always prefer `getByRole()` over `getByTestId()` or CSS selectors. When you use `getByRole('button', { name: /submit/i })`, you're asserting that:

The element has the correct ARIA role (it’s actually a button)
The element has an accessible name (screen readers can announce it)
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.

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.

// 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:

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

This approach aligns with black box testing principles—testing behavior rather than implementation details.

Stop White Box Testing Vue Components

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).

it('has no accessibility violations', async () => {
  const { container } = await createTestApp()

  // This one line checks for dozens of common a11y bugs!
  await assertNoViolations(container)
})

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.

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.

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:

// 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

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.

**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.

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.

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:

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 Frontend Testing Guide: 10 Essential Rules for Naming Tests.

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.

# .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

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

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.

Additional Resources

Vitest Browser Mode Guide - The official docs are excellent
vitest-browser-vue - Vue rendering for Vitest browser mode
vitest-examples on GitHub - “Hello World” setup examples

Building an AI QA Engineer with Claude Code and Playwright MCP

alex.opalic.dev@gmail.com (Alexander Opalic) — Sat, 13 Dec 2025 00:00:00 GMT

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

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 Model Context Protocol (MCP), Claude can literally browse your app like a real user.

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:

# 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:

## 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:

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:

Trigger: The workflow runs when you add a label to a PR (like qa-verify)
Start the app: Launch your dev server so Claude has something to test
Run Claude: Use Anthropic’s official GitHub Action with Playwright MCP connected

The `--headless` flag runs the browser without a visible window. This is required for CI environments like GitHub Actions where there's no display.

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:

# 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.”

Quinn went to work:

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:

# 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:

--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.

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:

Get Claude Code access — Sign up at Anthropic and get an API token
Create your QA prompt — Give Claude a personality and testing philosophy
Set up the GitHub Action — Use anthropics/claude-code-action with Playwright MCP
Write a verification template — Tell Claude what to test for each PR

If you're new to Claude Code, check out my comprehensive guide to Claude Code features covering MCP, Skills, Hooks, and more. You can also set up desktop notifications via hooks so you know the moment Claude finishes a task locally.

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.

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 - **Accessibility testing** — Verify ARIA labels, keyboard navigation, color contrast - **Content review** — Validate links, check for broken images, lint prose - **Visual regression** — Compare screenshots across deployments

Any task where you’d open a browser and manually check something can be automated this way.

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 — Complete QA workflow with explore/verify modes
Anthropic Claude Code Action — Official GitHub Action
Playwright MCP — Browser automation for Claude
GitHub Actions Documentation — Workflow automation basics

Vue Composables Style Guide: Lessons from VueUse's Codebase

alex.opalic.dev@gmail.com (Alexander Opalic) — Sat, 13 Dec 2025 00:00:00 GMT

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 Mastering Vue 3 Composables: A Comprehensive Style Guide, 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 How to Test Vue Composables

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

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

Export Pattern

// src/composables/index.ts
export { useCounter } from './useCounter'
export { useFetch } from './useFetch'
export type { UseCounterReturn, UseCounterOptions } from './useCounter'
export type { UseFetchReturn, UseFetchOptions } from './useFetch'

For more on project organization, check out How to Structure Vue Projects.

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

// 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:

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

// 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

// 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:

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:

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:

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

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

Document every option with JSDoc
Provide sensible defaults using @default
Use callbacks for events (onError, onSuccess, onChange)
Group related options in nested objects if complex

Extending Base Interfaces

Create reusable option interfaces:

// 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)

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)

export function useOnline(): Readonly<Ref<boolean>> {
  const isOnline = shallowRef(navigator.onLine)

  // ... implementation

  return readonly(isOnline)
}

Tuple Return (When Destructuring Order Matters)

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:

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 How VueUse Solves SSR Window Errors.

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

// 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

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:

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.

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

// 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

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

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

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:

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):

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

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

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:

// 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:

// 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

// 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 How to Test Vue Composables.

15. Documentation

JSDoc Comments

/**
 * 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:

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

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

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

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
Vue Reactivity in Depth
VueUse - Collection of Vue composables (the source of these patterns)
Vitest - 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.

Forcing Claude Code to TDD: An Agentic Red-Green-Refactor Loop

alex.opalic.dev@gmail.com (Alexander Opalic) — Sun, 30 Nov 2025 00:00:00 GMT

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.

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.

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:

Skills (.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

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.

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:

---
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:

---
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.

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.

The Implementer Agent (GREEN Phase)

At .claude/agents/tdd-implementer.md:

---
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:

---
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:

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:

// 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 useWorkoutDetail composable — 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:

// 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. 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: hooks. Claude Code runs hooks at specific lifecycle points, and I used UserPromptSubmit to inject a reminder before every response.

In .claude/settings.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:

#!/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()

With this hook, skill activation jumped from ~20% to ~84%. Now when I say "implement the workout detail view," the TDD skill triggers automatically.

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.

Claude Code Notifications: Get Alerts When Tasks Finish (Hooks Setup)

alex.opalic.dev@gmail.com (Alexander Opalic) — Sun, 23 Nov 2025 00:00:00 GMT

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. Claude Code runs hooks 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:

{
  "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:

The Notification Script

Create .claude/hooks/notification-desktop.ts. This script handles sending the actual notifications:

#!/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 build custom plugins that use hooks 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.

How to Speed Up Your Claude Code Experience with Slash Commands

alex.opalic.dev@gmail.com (Alexander Opalic) — Sat, 22 Nov 2025 00:00:00 GMT

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.

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.

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 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.

Here is a complete example:

---
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:

Create a branch named: $ARGUMENTS

For multiple arguments, use positional parameters $1, $2, etc:

---
argument-hint: [pr-number] [priority]
---

Review PR #$1 with priority $2.

File references

Include file contents with the @ prefix:

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.

---
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

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.

/lint — fix before commit

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.

/vitest — run unit tests

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.

/commit — save your work

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.

/push — commit and push in one step

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.

/fix-pipeline — fix failing CI tests

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.

/pr — create a pull request

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.

/review-coderabbit — address review comments

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.

/merge-to-main — finish the task

I type `/merge-to-main`. It squash merges the PR, deletes the branch, and pulls main. Done.

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 MCP (Model Context Protocol) or package your commands into a shareable plugin.

I don’t think about naming conventions, commit messages, or PR descriptions anymore. The commands handle it.

You can skip the interactive prompt entirely with `claude -p`. Add aliases to your `.zshrc` or `.bashrc`:

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.

Understanding Claude Code's Full Stack: MCP, Skills, Subagents, and Hooks Explained

alex.opalic.dev@gmail.com (Alexander Opalic) — Sun, 09 Nov 2025 00:00:00 GMT

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 overview of how I use LLMs 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

The feature stack

Model Context Protocol (MCP) — the foundation for connecting external tools and data sources
Claude Code core features — project memory, skills, subagents, and hooks
Plugins — shareable packages that bundle skills, hooks, and metadata
Skills — the unified extensibility model (replaces the old command/skill split)
Scheduled Tasks — cloud-based triggers that run Claude on a cron schedule

1) Model Context Protocol (MCP) — connecting external systems

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 Model Context Protocol 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:

# Install a server
claude mcp add playwright npx @playwright/mcp@latest

# Use it
/mcp__playwright__create-test [args]

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`.

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 build an AI QA engineer with Playwright MCP 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:

When you work on src/components/Button.vue, Claude loads context from:

Enterprise CLAUDE.md (if configured)
User ~/.claude/CLAUDE.md (personal preferences)
Project root CLAUDE.md (project-wide info)
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.

Here’s my blog’s CLAUDE.md:

# 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

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

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.

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
XML-tagged prompts 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 Slash Commands Guide. Want to create your own? Use this skill creation guide.

Example: a deploy skill that only you can trigger:

---
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:

---
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

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.

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.

Example structure:

---
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.

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.

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).

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.

2.4) Hooks — automatic event-driven actions

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.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/run-oxlint.sh"
          }
        ]
      }
    ]
  }
}

#!/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 set up desktop notifications when Claude needs your attention. Want to build your own? Use this hook creation guide.

3) Plugins — shareable, packaged configurations

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:

When to use. Share team configurations, package domain workflows, 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.

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.

Check out the [official Anthropic skills repository](https://github.com/anthropics/skills) for ready-to-use examples.

Claude Skills are awesome, maybe a bigger deal than MCP

— Simon Willison, Claude Skills are awesome, maybe a bigger deal than MCP

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.

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

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.

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:

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.

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.

Putting it all together

How these features work together in practice:

Memory (CLAUDE.md) — Establish project context and conventions that Claude always knows
Skills — Define reusable behaviors, from manual workflows to auto-invoked expertise
Subagents — Offload parallel or isolated work to specialized agents
Hooks — Enforce rules and automate repetitive actions at key lifecycle events
Plugins — Package and distribute your entire setup to others
MCP — Connect external systems and make their capabilities available as commands
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

🎉 **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! For a comprehensive visual guide to all Claude Code features, check out the [Awesome Claude Code Cheat Sheet](https://awesomeclaude.ai/code-cheatsheet). Want model name, context usage, and cost displayed in your terminal? See how to customize your Claude Code status line.

Use CLAUDE.md to define lasting project context — architecture, conventions, and patterns Claude should always remember. Best for: static knowledge that rarely changes.
Use Skills 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.

Feature comparison

This comparison table is adapted from [IndyDevDan's video "I finally CRACKED Claude Agent Skills"](https://www.youtube.com/watch?v=kFpLzCVLA20&t=1027s).

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
Run automated SEO audits with browser testing	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
Enforce TDD workflow automatically	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

Building My First Claude Code Plugin

alex.opalic.dev@gmail.com (Alexander Opalic) — Sat, 08 Nov 2025 00:00:00 GMT

If you're unfamiliar with Claude Code or want to understand the full ecosystem (MCP, Skills, Subagents, Hooks, and Plugins), check out my{" "} comprehensive guide to Claude Code's full stack {" "}first. This post assumes you know the basics.

The Problem

I’ve been using Claude Code for a while now. It’s been my daily driver for development work, alongside other AI tools in my workflow.

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.

The Manual Workflow Was Painful

Before the plugin, creating a new command looked like this:

Search the docs for the right frontmatter format
Create .claude/commands/my-command.md
Copy-paste a template
Fill in the blanks
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:

Command Files: Where the Magic Happens

Each command is a markdown file with frontmatter. Here’s the /create-skill command as an example:

---
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...]

Commands are just instructions for Claude. Write them like you're teaching a junior developer the exact steps to follow. Good{" "} prompt engineering principles {" "} apply here too.

Here’s what the plugin generates when you run a command:

Publishing to GitHub

Once I had it working locally, publishing was straightforward:

Push to GitHub
Users add the marketplace: /plugin marketplace add alexanderop/claude-code-builder
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

/plugin install claude-code-builder@claude-code-builder

Step 2: Verify installation

Check that the plugin is loaded:

/plugins

You should see claude-code-builder in the list.

Step 3: Use the new commands

You now have access to seven new commands. Try creating your first skill:

/create-skill commit-helper "Generate clear commit messages; use when committing"

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
MCP server integrations 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.

Building a Modular Monolith with Nuxt Layers: A Practical Guide

alex.opalic.dev@gmail.com (Alexander Opalic) — Sun, 02 Nov 2025 10:00:00 GMT

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. 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.

When I first encountered this problem, I considered micro frontends. While 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.

You compose these layers together using the extends keyword in your main configuration:

// nuxt.config.ts
export default defineNuxtConfig({
  extends: [
    "./layers/shared", // Local folder
    "./layers/products",
    "./layers/cart",
  ],
});

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.

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:

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:

<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:

<!-- 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:

<!-- 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.

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:

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):

<!-- 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.

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:

No cross-feature imports: Cart cannot import from products (or vice versa)
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.

// ❌ 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

Here’s how the validation logic works:

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:

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.

// 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.

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.

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:

# 📥 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:

# 📁 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

3. Add ESLint Enforcement

Install the ESLint plugin:

# 📦 Install ESLint plugin
pnpm add -D eslint-plugin-nuxt-layers

Configure it in your eslint.config.mjs with the layer-boundaries rule:

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.

How to Handle API Calls in Pinia with The Elm Pattern

alex.opalic.dev@gmail.com (Alexander Opalic) — Fri, 17 Oct 2025 00:00:00 GMT

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:

Deterministic: Given the same inputs, it always returns the same output.
No side effects: It does not interact with anything outside its scope.

Here’s a simple example:

// 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:

// 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:

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.

Keep the update function pure.
Move side effects into separate functions that receive a dispatch function.
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.

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.

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.

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.

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

<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.

Because the `update` function is pure and framework-agnostic, you can test it with simple assertions without any mocking:

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.

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.

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, TanStack Vue Query, or RStore.
If you need to stay within Pinia and still maintain a functional structure, this approach is effective.

Define your model and messages.
Keep the update function pure.
Implement effects as separate functions that take a dispatch function.
Connect them inside the store.

This structure keeps your Pinia stores predictable, testable, and easy to extend to any type of side effect.

How to Write Better Pinia Stores with the Elm Pattern

alex.opalic.dev@gmail.com (Alexander Opalic) — Fri, 03 Oct 2025 00:00:00 GMT

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:

// 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:

<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.

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 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.

Understanding The Elm Architecture

Before we dive into the implementation, let’s understand the core concepts of TEA:

Model: The state of your application
Update: Pure functions that transform state based on messages/actions
View: Rendering UI based on the current model

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:

// 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:

// 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:

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");
  });
});

Public Store with Selectors + Dispatch

Finally, combine everything in a single file. The private store is defined but not exported:

// 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 };
});

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

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:

<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.

Usage in Components

Components interact with the public store:

<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:

// 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:

<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>

Benefits of This Approach

Pure business logic: The update function has zero dependencies on Vue or Pinia
Easy testing: Test your update function with simple unit tests
Framework flexibility: Could swap Vue for React without changing update logic
Type safety: TypeScript ensures message types are correct
Devtools support: Still works with Pinia devtools since we’re using real stores
Encapsulation: Private store is an implementation detail

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 and Eduardo San Martin Morote’s “private store” pattern from Mastering Pinia.

How to build Microfrontends with Module Federation and Vue

alex.opalic.dev@gmail.com (Alexander Opalic) — Wed, 10 Sep 2025 00:00:00 GMT

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 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.

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.

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:

packages:
  - "apps/*"
  - "packages/*"

High level view:

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

// 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

Vue `defineAsyncComponent` wraps any loader in a friendly component. It gives lazy loading, built in states, and retries. This is why it fits microfrontends.

const AsyncComp = defineAsyncComponent({
  loader: () => Promise.resolve(/* component */),
  delay: 200,
  timeout: 3000,
  onError(error, retry, fail, attempts) {
    if (attempts <= 1) retry();
    else fail();
  },
});

// 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();
    },
  });
}

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.

Module Federation runtime

The host bootstraps Module Federation and exposes a single loader.

// 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.

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

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.

Navigation through custom events

Remotes dispatch mf:navigate with { to }. The host listens and calls router.push.

// 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.

// 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:

/* decide */
.d_ProductPage__title {
  font-size: 2rem;
  color: var(--color-primary);
}
.d_ProductPage__title--featured {
  color: var(--color-accent);
}

Or Vue scoped styles:

<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:

/* 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.

// 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.

// 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.

{
  "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).

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.

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.

Why You Need Something Hard in Your Life

alex.opalic.dev@gmail.com (Alexander Opalic) — Wed, 10 Sep 2025 00:00:00 GMT

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. 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.

What Is the Model Context Protocol (MCP)? How It Works

alex.opalic.dev@gmail.com (Alexander Opalic) — Sun, 10 Aug 2025 00:00:00 GMT

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 how I use Claude Code for doing SEO audits.
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

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 LLM limits.

The first fix: tools

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

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

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.

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.

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

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.

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.

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:

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

// 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

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

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:

{
  "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

#!/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, 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 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:

// 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

{
  "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.

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.

How VueUse Solves SSR Window Errors in Vue Applications

alex.opalic.dev@gmail.com (Alexander Opalic) — Mon, 14 Jul 2025 00:00:00 GMT

I am a big fan of VueUse. 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:

Server (Node.js) – It renders HTML so the user sees a fast first screen.
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

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:

export const isClient =
  typeof window !== "undefined" && typeof document !== "undefined";

Diagram

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:

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

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:

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

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 to check that:

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):

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
Full VueUse repository: https://github.com/vueuse/vueuse

Mastering GraphQL Fragments in Vue 3: Component-Driven Data Fetching

alex.opalic.dev@gmail.com (Alexander Opalic) — Sun, 06 Jul 2025 00:00:00 GMT

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.

fragment CountryBasicInfo on Country {
  code
  name
  emoji
  capital
}

Fragment masking is the key innovation that makes fragments truly powerful. It ensures that:

Data is encapsulated: Only the component that defines a fragment can access its fields
Dependencies are explicit: Components can’t accidentally rely on data from other fragments
Refactoring is safe: Changing a fragment won’t break unrelated components
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 objects
const basicInfo = { code: "US", name: "United States" };
const fullCountry = { ...basicInfo, capital: "Washington D.C." };

# 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):

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:

<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.

// 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:

// ✅ 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:

Prevents Implicit Dependencies: Parent components can’t accidentally rely on data their children need
Catches Breaking Changes Early: If a child component removes a field, the parent can’t access it anymore
Enforces Component Boundaries: Each component owns its data requirements
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.

// 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:

<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:

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:

# 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:

<!-- 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:

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:

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

Naming: Use ComponentName_TypeNameFragment convention
Vue Reactivity: Always wrap useFragment in computed()
TypeScript: Use FragmentType<typeof MyFragment> for props
Organization: Colocate fragments with components

// ✅ 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:

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

Start with leaf components (no children)
Always use computed() with useFragment for Vue reactivity
Update TypeScript interfaces to use FragmentType
Run npm run codegen after fragment changes

What’s Next?

This is Part 3 of our Vue 3 + GraphQL series:

Part 1: Setting up Apollo Client with Vue 3
Part 2: Type-safe queries with GraphQL Code Generator
Part 3: Advanced fragments and component-driven data fetching (current)
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.

Source Code

Find the full demo for this series here: example

Note: The code for this tutorial is on the part3 branch.

git clone https://github.com/alexanderop/vue-graphql-simple-example.git
cd vue-graphql-simple-example
git checkout part3

How I Use Claude Code for Doing SEO Audits

alex.opalic.dev@gmail.com (Alexander Opalic) — Thu, 26 Jun 2025 00:00:00 GMT

I’m building a Nuxt blog starter called 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, 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 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.

---
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.”

---
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.”

---
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

Speed: Claude Code finished in minutes what would take me hours to do by hand
Complete: Claude Code checked things I might have missed
Useful Results: Not just problems, but solutions with code examples
Documentation: Everything saved in a markdown file I can use later

Getting Started

To copy this workflow:

Install Claude Code: npm install -g @anthropic/claude-code
Set up the Puppeteer MCP server
Start your development server
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!

The Age of the Generalist

alex.opalic.dev@gmail.com (Alexander Opalic) — Sun, 15 Jun 2025 00:00:00 GMT

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.

How I Use LLMs

alex.opalic.dev@gmail.com (Alexander Opalic) — Sun, 25 May 2025 00:00:00 GMT

Motivated by the awesome YouTube video from Andrew Karpathy How I use LLMs, 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.

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

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:

Everyday tasks (like fixing spelling, writing something better)
Quick Refactoring (like adding console logs to debug something, small refactorings)
Technical Tasks (like doing research)
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.

I also wrote a blog post once where I gave o3 a hard chess puzzle to solve. Feel free to read it here.

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.

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

In the book “AI Engineering” by Chip Huyen, she explains that there are three main ways to improve the output of an LLM:

With Prompts
Per RAG
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.

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, 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:

Role Definition
Step-by-Step Instructions
Output Format
Edge Cases
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, 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.

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.

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:

As SVG
As Mermaid
Or as a picture with the new model

I already wrote about how to use ChatGPT to generate mermaid diagrams. Read it here.

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.

One idea when you have a monorepo could be something like this:

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:

---
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 that might help you understand what’s happening under the hood.

No Server, No Database: Smarter Related Posts in Astro with `transformers.js`

alex.opalic.dev@gmail.com (Alexander Opalic) — Sun, 18 May 2025 00:00:00 GMT

I recently read a interesting blog post about Embeddings at Embeddings in Technical Writing:

“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.

Transformers.js in Action

transformers.js lets you run Hugging Face models directly in JavaScript:

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:

Load markdown files (.md or .mdx) from my blog.
Remove markdown formatting to get plain text.
Use transformers.js to create embeddings.
Calculate cosine similarity between all posts.
Find the top 5 most related posts for each post.
Save the results in a JSON file (similarities.json).
Display these related posts with Astro.

Main Script (TypeScript)

// --------- 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:

{
  "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

---
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

Type-Safe GraphQL Queries in Vue 3 with GraphQL Code Generator

alex.opalic.dev@gmail.com (Alexander Opalic) — Sun, 04 May 2025 00:00:00 GMT

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:

<li v-for="c in result?.countries2" :key="c.code"></li>

…slips right 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:

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:

npx graphql-code-generator init

When prompted, answer as follows:

? 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:

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:

{
  "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:

query AllCountries {
  countries {
    code
    name
    emoji
  }
}

Then, generate your types:

npm run codegen

The command writes all generated types to src/gql/.

Update your `CountryList.vue` component to use the generated types

<script setup lang="ts">
const { result, loading, error } = useQuery(AllCountriesDocument);
const countries = computed(() => result.value?.countries);
</script>

Inline queries with the generated `graphql` tag

Alternatively, define the query directly in your component using the generated graphql tag:

<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:

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:

⚠ 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

Note:
The code for this tutorial is on the part-two branch.
After cloning the repository, make sure to check out the correct branch:
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

LLM-Powered Search: o4-mini-high vs o3 vs Deep Research

alex.opalic.dev@gmail.com (Alexander Opalic) — Thu, 01 May 2025 00:00:00 GMT

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)

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, Testing | Speakeasy). 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). 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). 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). 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).

Thought for 41 seconds · 10 sources
Characters: 4,811

Full conversation →

🟡 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)
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)

Thought for 1m 25s · 15 Sources
Characters: 7,483

Full conversation →

🔵 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). The SDK is fully type-safe (using Zod schemas) and provides complete coverage of the Vercel REST API (Introducing the Vercel TypeScript SDK - Vercel) (Using the Vercel SDK - Vercel API Docs). In fact, Vercel’s SDK repo explicitly notes “SDK Created by Speakeasy” (GitHub - vercel/sdk). 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) (Using the Vercel SDK - Vercel API Docs).

Research completed in 3m · 31 sources
Characters: 13,942

Full conversation →

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

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.

Watching OpenAI's o3 Model Sweat Over a Paul Morphy Mate-in-2

alex.opalic.dev@gmail.com (Alexander Opalic) — Sun, 27 Apr 2025 00:00:00 GMT

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.

First the Problem if you want you can try to solve it yourself

This is a famous chess puzzle from Paul Morphy check out this link for more.

See the full conversation here.

1. 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”).

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

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

%%{ 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?”.

You can also find an interesting discussion about this on Hacker News here.

Getting Started with GraphQL in Vue 3 — Complete Setup with Apollo

alex.opalic.dev@gmail.com (Alexander Opalic) — Sat, 26 Apr 2025 00:00:00 GMT

Introduction

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:

query {
  countries {
    name
    emoji
    capital
  }
}

💡 If the embed breaks, open it in a new tab.

Under the hood: 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:

const COUNTRIES = gql`
  query AllCountries {
    countries {
      code
      name
      emoji
    }
  }
`;

Apollo transforms that into a regular POST request:

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)

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

npm create vite@latest vue3-graphql-setup -- --template vue-ts
cd vue3-graphql-setup
npm install

2. Install GraphQL and Apollo

npm install graphql graphql-tag @apollo/client @vue/apollo-composable

3. Create an Apollo plugin

Create src/plugins/apollo.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:

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:

<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:

<template>
  
</template>

<script setup lang="ts">
</script>

Fire up your dev server:

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

Note:
The code for this tutorial is on the part-one branch.
After cloning the repository, make sure to check out the correct branch:
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

How ChatGPT Works (for Dummies)

alex.opalic.dev@gmail.com (Alexander Opalic) — Mon, 21 Apr 2025 00:00:00 GMT

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. 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?” (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?

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 to see how text gets split into tokens:

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

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.

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:

Being informative but not overwhelming is good
Staying focused on the question is important
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:

The model can only do so much computation per token
By spreading reasoning across many tokens, it can solve harder problems
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:

Base cost: 7 × $12.99 = $90.93
Sales tax amount: $90.93 × 0.085 = $7.73
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

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:

Use them as tools, not oracles: Always verify important information
Give them tokens to think: Let them reason step by step
Put knowledge in context: Paste relevant information rather than hoping they remember it
Understand their limitations: Be aware of the “Swiss cheese” problem
Try reasoning models: For complex problems, use models specifically designed for reasoning

Stop White Box Testing Vue Components Use Testing Library Instead

alex.opalic.dev@gmail.com (Alexander Opalic) — Sat, 19 Apr 2025 00:00:00 GMT

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 refs, or using wrapper.vm.

Example:

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.

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 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:

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)

<!-- ❌ 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:

// 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

The Computed Inlining Refactoring Pattern in Vue

alex.opalic.dev@gmail.com (Alexander Opalic) — Thu, 03 Apr 2025 00:00:00 GMT

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

Here’s his example:

function getRating(driver) {
  return moreThanFiveLateDeliveries(driver) ? 2 : 1;
}

function moreThanFiveLateDeliveries(driver) {
  return driver.numberOfLateDeliveries > 5;
}

After applying the Inline Function pattern:

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:

// 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:

// 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

Are LLMs Creative?

alex.opalic.dev@gmail.com (Alexander Opalic) — Tue, 01 Apr 2025 00:00:00 GMT

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.

The Inline Vue Composables Refactoring pattern

alex.opalic.dev@gmail.com (Alexander Opalic) — Tue, 01 Apr 2025 00:00:00 GMT

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.

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.

Fowler’s example:

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:

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.

Before Refactoring

The original component mixes everything in one block:

// 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:

// 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:

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

Math Notation from 0 to 1: A Beginner's Guide

alex.opalic.dev@gmail.com (Alexander Opalic) — Sun, 09 Mar 2025 00:00:00 GMT

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):

Parentheses
Exponents
Multiplication and Division (from left to right)
Addition and Subtraction (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

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
Interpret the following notations:
- $f(x) = |x|$
- $\sum_{i=1}^{5} (2i - 1)$
- ${x \in \mathbb{R} : -1 < x < 1}$

Happy calculating!

How to Implement a Cosine Similarity Function in TypeScript for Vector Comparison

alex.opalic.dev@gmail.com (Alexander Opalic) — Sat, 08 Mar 2025 00:00:00 GMT

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.

I won't explain how embeddings work in this blog post, but only how to use them.

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:

What it does: It tells you if two vectors point in the same direction, opposite directions, or somewhere in between.
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
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
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
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:

Move both vectors by dragging the colored circles at their endpoints
Observe how the angle between them changes
See how cosine similarity relates to this angle
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:

/**
 * 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:

// 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:

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:

// 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:

// 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);
}

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.

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.

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.

How I Added llms.txt to My Astro Blog

alex.opalic.dev@gmail.com (Alexander Opalic) — Mon, 03 Mar 2025 00:00:00 GMT

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:

Gets all blog posts
Converts them to plain text
Formats them with basic metadata
Outputs everything as one big text file

Setting Up the File

First, I created a new TypeScript file in my Astro pages directory:

// 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:

It uses Astro’s getCollection function to grab all published blog posts
It sorts them by date with newest first
It cleans up each post’s content with helper functions
It formats each post with its metadata and content
It returns everything as plain text

How to Use It

Using this is simple:

Visit alexop.dev/llms.txt in your browser
Press Ctrl+A (or Cmd+A on Mac) to select all the text
Copy it (Ctrl+C or Cmd+C)
Paste it into any LLM with adequate context window (like ChatGPT, Claude, Llama, etc.)
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.

How to Do Visual Regression Testing in Vue with Vitest?

alex.opalic.dev@gmail.com (Alexander Opalic) — Sat, 22 Feb 2025 00:00:00 GMT

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:

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.

Vitest Configuration

Start by configuring Vitest with the Vue plugin:

export default defineConfig({
  plugins: [vue()],
});

Setting Up Browser Testing

Visual regression tests need a real browser environment. Install these dependencies:

npm install -D vitest @vitest/browser playwright

You can also use the following command to initialize the browser mode:

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.

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.

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

{
  "scripts": {
    "test": "vitest",
    "test:unit": "vitest --project unit",
    "test:browser": "vitest --project browser"
  }
}

Now we can run tests in separate environments like this:

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:

<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:

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:

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:

// [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.

Save this file with a `.browser.spec.ts` extension (e.g., `BaseButton.browser.spec.ts`) to match your browser test configuration.

Beyond Screenshots: Automated Comparison

Automate image comparison by encoding screenshots in base64 and comparing them against baseline snapshots:

// 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:

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();
    });
  });
});

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).

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.

How to Test Vue Router Components with Testing Library and Vitest

alex.opalic.dev@gmail.com (Alexander Opalic) — Sun, 16 Feb 2025 00:00:00 GMT

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

<!-- 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:

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:

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:

// 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:

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:

<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:

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:

// 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:

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.

Building a Pinia Plugin for Cross-Tab State Syncing

alex.opalic.dev@gmail.com (Alexander Opalic) — Sun, 09 Feb 2025 00:00:00 GMT

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:

Messages are sent using the postMessage() method
Messages are received through the onmessage event handler
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:

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`

const pinia = createPinia();
pinia.use(PiniaSharedState);

Plugin Implementation `plugin/plugin.ts`

Here’s our complete plugin implementation with TypeScript support:

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:

Creating a BroadcastChannel for each store
Subscribing to store changes and broadcasting updates
Handling incoming messages from other tabs
Using timestamps to prevent update cycles
Supporting custom serialization for complex state

Communication Flow Diagram

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:

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.
It also has examples of how to use it with Web Workers.

How to Use AI for Effective Diagram Creation: A Guide to ChatGPT and Mermaid

alex.opalic.dev@gmail.com (Alexander Opalic) — Sun, 09 Feb 2025 00:00:00 GMT

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:

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]

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:

sequenceDiagram
    participant Client
    participant Server
    Client->>Server: Request (GET /resource)
    Server-->>Client: Response (200 OK)

sequenceDiagram
    participant Client
    participant Server
    Client->>Server: Request (GET /resource)
    Server-->>Client: Response (200 OK)

Using ChatGPT with Mermaid

Ask ChatGPT to explain your concept
Request a Mermaid diagram representation
Iterate on the diagram with follow-up questions

Example prompt: “Create a Mermaid sequence diagram showing how Nuxt.js performs server-side rendering”

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

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 for quick prototyping.

VS Code Integration

Install “Markdown Preview Mermaid Support” extension
Create .md file with Mermaid code blocks
Preview with built-in markdown viewer

Web Integration

<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.

The Browser That Speaks 200 Languages: Building an AI Translator Without APIs

alex.opalic.dev@gmail.com (Alexander Opalic) — Sun, 02 Feb 2025 00:00:00 GMT

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

---
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

1. Set Up Your Project

Create a new Vue project with TypeScript:

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:

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, {
        // @ts-ignore - Type definitions are incomplete
        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`)

<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`)

<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:

<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:

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

You type text and select languages
The text goes to a Web Worker
Transformers.js loads the AI model (once)
The model translates your text
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.

Want to learn more? Explore these resources:

Solving Prop Drilling in Vue: Modern State Management Strategies

alex.opalic.dev@gmail.com (Alexander Opalic) — Sat, 25 Jan 2025 00:00:00 GMT

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:

// 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:

<!-- 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:

// 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:

<!-- 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:


// 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:

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.

State Inconsistencies
Multiple components listening to the same event often maintain duplicate state:

// Two components, two sources of truth
eventBus.on("login", () => (this.isLoggedIn = true));
eventBus.on("login", () => (this.userStatus = "active"));

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.

---
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

Start Simple: Begin with props, graduate to composables
Type Everything: Use TypeScript for stores/injections
Name Wisely: Prefix stores (useUserStore) and injection keys (UserKey)
Monitor Performance: Use Vue DevTools to track reactivity
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.

Building Local-First Apps with Vue and Dexie.js

alex.opalic.dev@gmail.com (Alexander Opalic) — Sat, 18 Jan 2025 00:00:00 GMT

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 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:

Works without internet connection
Users stay productive when servers are down
Data syncs smoothly when connectivity returns

The Architecture Behind Local-First Apps

---
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.

---
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

WebSocket Sync: Real-time updates for collaborative apps
HTTP Long-Polling: Default sync mechanism, firewall-friendly
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:

Create a Dexie Cloud Account:
- Visit https://dexie.org/cloud/
- Sign up for a free developer account
- Create a new database from the dashboard
Install Required Packages:
```
npm install dexie-cloud-addon
```
Configure Environment Variables:
Create a .env file in your project root:
```
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.
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:

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

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

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

<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

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:

{
  "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:

Offline Persistence: Your todos are stored locally
Multi-User Support: User data in members and roles
Sync Management: All *_mutations stores track changes
Authentication: Login state in $logins

Understanding Dexie’s Merge Conflict Resolution

%%{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.

Adding Obsidian-Style Wiki Links to My Astro Blog

alex.opalic.dev@gmail.com (Alexander Opalic) — Fri, 10 Jan 2025 00:00:00 GMT

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:

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:

Finds [[...]] patterns in markdown text
Looks up the post metadata from the file system
Generates the full preview card HTML at build time

Supported Syntax

[[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.

// 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:

The target (either slug or collection:slug)
The optional alias after the pipe

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:

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:

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:

Logs a warning during build: [wiki-links] Post not found: blog:missing-slug
Renders the link with error styling (red wavy underline)

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

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:

.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:

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:

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]]

Unlocking Reading Insights: A Guide to Data Analysis with Claude and Readwise

alex.opalic.dev@gmail.com (Alexander Opalic) — Sun, 05 Jan 2025 00:00:00 GMT

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”

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:

Please Claude, analyze this data for me.

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.

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

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:

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:

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:

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:

// Available libraries
// For CSV processing
// For data manipulation
// For UI components
// For visualizations

Data Processing Pipeline

The analysis happens in two main stages:

Initial Data Processing:

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);
}

Visualization Component:

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

Asynchronous File Handling: The window.fs.readFile API provides async file access, similar to Node.js’s fs/promises.
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
React Integration:
- Components use hooks for state management
- Tailwind classes for styling
- Responsive container adapts to screen size
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.

The What Why and How of Goal Settings

alex.opalic.dev@gmail.com (Alexander Opalic) — Tue, 31 Dec 2024 00:00:00 GMT

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:

Write down the goal in specific, measurable terms
Set a realistic timeline for accomplishment
Study and adopt the habits of those who’ve already achieved similar goals
Track your progress consistently
Build a supportive community of like-minded people
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.

XML-Style Tagged Prompts: A Framework for Reliable AI Responses

alex.opalic.dev@gmail.com (Alexander Opalic) — Sun, 22 Dec 2024 00:00:00 GMT

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:

<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:

Learn a beginner-friendly programming language like Python or JavaScript
Master basic concepts like variables, data types, control flow, functions, and object-oriented programming
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:

Choose learning resources:
- Free platforms like freeCodeCamp, The Odin Project, or CS50x
- Paid platforms like Udemy, Coursera, or boot camps
- Technical books and documentation
Build projects:
- Start with small, achievable projects
- Gradually increase complexity
- Create a portfolio to showcase your work
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:

As a system prompt for ongoing AI interactions
As part of individual conversation messages

Basic Implementation

Here’s a simple but effective system prompt structure:

<SystemPromptUI
prompt={`When answering queries:

Think through your reasoning in tags
Provide your answer in tags
If you spot an error, explain and correct it in tags`}
/>

Tagged Response Example

<ChatUI
question=“I want to learn software engineering. What should I do?”
answer={`
Let me break this down systematically:

Software engineering is a broad field - need to cover both fundamentals and practical skills
Should suggest a structured learning path that’s manageable
Important to emphasize both theoretical knowledge and hands-on practice
Need to include guidance on building a portfolio and joining the community
Should consider both formal and self-learning options

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?

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. `} />

Advanced Techniques: Taking Tagged Prompts Further

For more sophisticated applications, we can add quality metrics and step tracking:

<SystemPromptUI
prompt={`Use tags to explore different approaches and viewpoints
Use tags to break down the solution (20 step budget, request more if needed)
Add tags after each step to track remaining budget
Use tags to evaluate progress and be self-critical
Rate quality with 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 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, shows the power of structured prompts in professional tools.

Essential Resources for Mastering Tagged Prompts

For deeper exploration of tagged prompts and related concepts:

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.

How to Use the Variant Props Pattern in Vue

alex.opalic.dev@gmail.com (Alexander Opalic) — Sun, 15 Dec 2024 00:00:00 GMT

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:

// 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:

<!-- 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:

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.

// 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:

<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, 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:

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:

SQLite in Vue: Complete Guide to Building Offline-First Web Apps

alex.opalic.dev@gmail.com (Alexander Opalic) — Mon, 25 Nov 2024 07:44:12 GMT

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!

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

🗃️ 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:

SQLite Wasm: SQLite converted to run in browsers
Web Workers: Runs database code without freezing your app
Origin Private File System: A secure place to store your database

Here’s how they work together:

📝 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:

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:

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.

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:

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:

<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 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:

Each tab has its own Web Worker for SQLite operations
A SharedWorker manages which tab is “active”
Only one tab can write to SQLite at a time
Queries from all tabs are routed through the active tab’s Worker

Key Learnings from Notion

Async Loading: They load the WASM SQLite library asynchronously to avoid blocking initial page load
Race Conditions: They implemented a “racing” system between SQLite and API requests to handle slower devices
OPFS Handling: They discovered that Origin Private File System (OPFS) doesn’t handle concurrency well out of the box
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.

Create Dark Mode-Compatible Technical Diagrams in Astro with Excalidraw: A Complete Guide

alex.opalic.dev@gmail.com (Alexander Opalic) — Sun, 27 Oct 2024 07:00:00 GMT

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

Standard Export

Here's how a typical Excalidraw diagram looks without any customization:

With Our Solution

And here's the same diagram using our custom component:

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:

Automatically adapt to light and dark modes
Support your custom design system colors
Add interactive elements and smooth transitions
Maintain accessibility standards

💡 Quick Start: Need an Astro blog first? Use AstroPaper 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:

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:

Create your diagram at Excalidraw
Export the diagram:
- Select your diagram
- Click the export button
Configure export settings:
- Uncheck “Background”
- Choose SVG format
- Click “Save”

3. Building the ExcalidrawSVG Component

Here’s our custom Astro component that handles the theme-aware transformation:

---
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.

---
---

# My Technical Blog Post

<ExcalidrawSVG
  src={myDiagram}
  alt="Architecture diagram"
  caption="System architecture overview"
/>

Best Practices and Tips for Theme-Aware Technical Diagrams

Simplicity and Focus
- Keep diagrams simple and focused for better readability
- Avoid cluttering with unnecessary details
Consistent Styling
- Use consistent styling across all diagrams
- Maintain a uniform look and feel throughout your documentation
Thorough Testing
- Test thoroughly in both light and dark modes
- Ensure diagrams are clear and legible in all color schemes
Accessibility Considerations
- Consider accessibility when choosing colors and contrast
- Ensure diagrams are understandable for users with color vision deficiencies
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.

Frontend Testing Guide: 10 Essential Rules for Naming Tests

alex.opalic.dev@gmail.com (Alexander Opalic) — Sat, 26 Oct 2024 08:00:00 GMT

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:

Framework-agnostic
Applicable across the entire testing pyramid
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.

// ❌ 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.

// ❌ 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.

// ❌ 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:

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.

// ❌ 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.

// ❌ 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.

// ❌ 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.

// ❌ 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.

// ❌ 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.

// ❌ 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.

// ❌ 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:

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:

// ❌ 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:

Document your naming conventions in detail
Share these guidelines with all team members
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

By following these steps, you can ensure consistent, high-quality test naming across your entire project.

Create a Native-Like App in 4 Steps: PWA Magic with Vue 3 and Vite

alex.opalic.dev@gmail.com (Alexander Opalic) — Sun, 20 Oct 2024 07:44:12 GMT

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.

Prerequisites for Building a PWA with Vue 3 and Vite

Before you start, make sure you have the following tools installed:

Node.js installed on your system
Package manager: pnpm, npm, or yarn
Basic familiarity with Vue 3

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.

Create a new Vue project by running the following command in your terminal:
```
pnpm create vue@latest
```

Follow the prompts to configure your project. Here’s an example configuration:

✔ 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

Once the project is created, navigate to your project directory and install dependencies:
```
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.

First, let’s install the necessary packages:

pnpm add -D vite-plugin-pwa @vite-pwa/assets-generator

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.

Generate the PWA assets by running:

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:

> 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:

<head>

</head>

Now, update your vite.config.ts file with the following configuration:

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,
      },
    }),
  ],
});

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:

When a user visits your PWA, the browser downloads and caches the latest version of your app.
On subsequent visits, the service worker checks for updates in the background.
If an update is available, it’s downloaded and prepared for the next launch.
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:

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.
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:

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
              },
            },
          },
        ],
      },
    }),
  ],
});

Testing Your PWA

Now that we’ve set up our PWA, it’s time to test its capabilities:

Test your PWA locally:
```
pnpm run dev
```
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.
  [
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.
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.
Test installation:
- On desktop: Look for the install icon in the address bar or the three-dot menu.
- On mobile: You should see a prompt to “Add to Home Screen”.
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.

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 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.

For a complete working example of this Vue 3 PWA, you can check out the complete source code at full example.
This repository contains the finished project, allowing you to see how all the pieces come together in a real-world application.

Atomic Architecture: Structuring Vue and Nuxt Projects

alex.opalic.dev@gmail.com (Alexander Opalic) — Tue, 08 Oct 2024 00:00:00 GMT

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

Brad Frost developed Atomic Design as a methodology for creating design systems. He structured it into five levels inspired by chemistry:

Atoms: Basic building blocks (e.g. form labels, inputs, buttons)
Molecules: Simple groups of UI elements (e.g. search forms)
Organisms: Complex components made of molecules/atoms (e.g. headers)
Templates: Page-level layouts
Pages: Specific instances of templates with content

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

Code Example: Before and After

Consider this non-Atomic Design todo app component:

<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

📐 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

<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

<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)

<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:

<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:

<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:

<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:

<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>

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 covers approaches beyond Atomic Design for larger projects.

Bolt Your Presentations: AI-Powered Slides

alex.opalic.dev@gmail.com (Alexander Opalic) — Sat, 05 Oct 2024 00:00:00 GMT

Introduction

Presentations plague the middle-class professional. Most bore audiences with wordy slides. But AI tools promise sharper results, faster. Let’s explore how.

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.

Tools Breakdown

Three key tools enable this approach:

Bolt: AI-powered web app creation in the browser
Slidev: Markdown-based slides with code support
Webcontainers: Browser-based Node.js for instant prototyping

Seven Steps to AI Presentation Mastery

Follow these steps to craft AI-powered presentations:

Open bolt.new in your browser.
Tell Bolt to make a presentation on your topic. Be specific. (add use Slidedev for it)
Review the Bolt-generated slides. Check content and flow.
Edit and refine.
Ask AI for help with new slides, examples, or transitions.
Add code snippets and diagrams.
Deploy to Netlify with one click.

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.

10 Rules for Better Writing from the Book Economical Writing

alex.opalic.dev@gmail.com (Alexander Opalic) — Sat, 28 Sep 2024 00:00:00 GMT

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.

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:

Spell Checker (Grammarly for example)
OED (a real dictionary to look up the origin of words)
Thesaurus (shows you similar words)
<a
href=“https://www.hemingwayapp.com”
target=“_blank”
rel=“noopener noreferrer”
Hemingway Editor

(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 . . .’

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.

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.

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.

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.”

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.

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.

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).

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.

TypeScript Tutorial: Extracting All Keys from Nested Object

alex.opalic.dev@gmail.com (Alexander Opalic) — Mon, 23 Sep 2024 00:00:00 GMT

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:

type User = {
  id: string;
  name: string;
  address: {
    street: string;
    city: string;
  };
};

You want “id”, “name”, and “address.street”. The standard approach is insufficient:

// 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:

Conditional Types (if-then for types)
Mapped Types (change each part of a type)
Template Literal Types (make new string types)
Recursive Types (types that refer to themselves)

Here’s our solution:

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:

We check if T is an object.
For each key in the object:
We either preserve the key as-is, or
If the key’s value is another object, we combine the key with its nested keys
We apply this to the entire type structure

Now let’s use it:

type UserKeys = ExtractKeys<User>;

This gives us all keys, including nested ones.

The practical benefits become clear in this example:

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:

This type implementation may impact performance with complex nested objects.
The type system enhances development-time safety without runtime overhead.
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.

TypeScript Snippets in Astro: Show, Don't Tell

alex.opalic.dev@gmail.com (Alexander Opalic) — Sun, 22 Sep 2024 00:00:00 GMT

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 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:

Update your astro.config.mjs:

export default defineConfig({
  markdown: {
    shikiConfig: {
      themes: { light: "min-light", dark: "tokyo-night" },
      wrap: true,
    },
  },
});

Add a stylish border to your code blocks:

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:

// @errors: 2322
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:

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.

Vue 3.5's onWatcherCleanup: Mastering Side Effect Management in Vue Applications

alex.opalic.dev@gmail.com (Alexander Opalic) — Wed, 04 Sep 2024 00:00:00 GMT

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

<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:

External controller management
Manual request abortion
Cleanup logic separate from effect
Easy to forget proper cleanup

The New Way: onWatcherCleanup

Here’s how onWatcherCleanup improves the process:

<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

Clearer code: Cleanup logic is right next to the effect
Automatic execution
Fewer memory leaks
Simpler logic
Consistent with Vue API
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

watch(dependency, () => {
  const timer1 = setInterval(() => {
    /* ... */
  }, 1000);
  const timer2 = setInterval(() => {
    /* ... */
  }, 5000);

  onWatcherCleanup(() => clearInterval(timer1));
  onWatcherCleanup(() => clearInterval(timer2));

  // More logic...
});

Conditional Cleanup

watch(dependency, () => {
  if (condition) {
    const resource = acquireResource();
    onWatcherCleanup(() => releaseResource(resource));
  }

  // More code...
});

With watchEffect

watchEffect(onCleanup => {
  const data = fetchSomeData();

  onCleanup(() => {
    cleanupData(data);
  });
});

How onWatcherCleanup Works

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:

Before the effect re-runs
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

Register cleanups at the start of your effect function
Keep cleanup functions simple and focused
Avoid creating new side effects within cleanup functions
Handle potential errors in your cleanup logic
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.

How to Build Your Own Vue-like Reactivity System from Scratch

alex.opalic.dev@gmail.com (Alexander Opalic) — Sun, 04 Aug 2024 00:00:00 GMT

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 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:

<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:

State Management: ref creates a reactive reference for the counter.
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:

A method to store data
A way to track changes
A mechanism to update dependencies when data changes

Key Components of Our Reactivity System

A store for our data and effects
A dependency tracking system
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.

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:

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.

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.

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.

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.

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:

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

check out the full example -> click

Beyond the Basics: What’s Missing?

While our implementation covers the core concepts, production-ready frameworks like Vue offer more advanced features:

Handling of nested objects and arrays
Efficient cleanup of outdated effects
Performance optimizations for large-scale applications
Computed properties and watchers
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.

What is Local-first Web Development?

alex.opalic.dev@gmail.com (Alexander Opalic) — Wed, 29 May 2024 15:22:00 GMT

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 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:

Instant Access: Users can immediately access their work without waiting for data to load or sync.
Device Independence: Data is accessible across multiple devices seamlessly.
Network Independence: Basic tasks function without an internet connection.
Effortless Collaboration: The app supports easy collaboration, even in offline scenarios.
Future-Proof Data: User data remains accessible and usable over time, regardless of software changes.
Built-In Security: Security and privacy are fundamental design considerations.
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.

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

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

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:

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.
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.
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 Building Local-First Apps with Vue and Dexie.
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:

Website: Local First Web - An excellent starting point with comprehensive follow-up topics.
Podcast: Local First FM - An insightful podcast dedicated to local-first development.
Community: Join the Local First Discord to connect with fellow developers and enthusiasts.
Resource: Local-First 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.

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.

Vue Accessibility Blueprint: 8 Steps

alex.opalic.dev@gmail.com (Alexander Opalic) — Sat, 18 May 2024 15:22:00 GMT

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

<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

2. Use eslint-plugin-vue-a11y

Add this ESLint plugin to detect accessibility issues during development:

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

3. Test with Vue Testing Library

Adopt Vue Testing Library to write accessibility-focused tests:

test("renders accessible button", () => {
  render(MyComponent);
  const button = screen.getByRole("button", { name: /submit/i });
  expect(button).toBeInTheDocument();
});

Resource: Vue Testing Library Documentation

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

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:

describe("Home Page Accessibility", () => {
  beforeEach(() => {
    cy.visit("/");
    cy.injectAxe();
  });

  it("Has no detectable a11y violations", () => {
    cy.checkA11y();
  });
});

Resource: Cypress Accessibility Testing Guide

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.

How to Structure Vue Projects

alex.opalic.dev@gmail.com (Alexander Opalic) — Sun, 12 May 2024 15:22:00 GMT

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

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.

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.

Pros and Cons

✅ Pros	❌ Cons
Easy to implement	Not scalable
Minimal setup	Becomes cluttered as the project grows
Ideal for small teams or solo developers	Lack of clear separation of concerns

2. Atomic Design: Scalable Component Organization

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.

Pros and Cons

✅ Pros	❌ Cons
Highly scalable	Can introduce overhead in managing layers
Organized component hierarchy	Initial complexity in setting up
Reusable components	Might be overkill for smaller projects
Improves collaboration among teams

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.

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:

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.

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.

Pros and Cons

✅ Pros	❌ Cons
High cohesion and clear separation	Initial complexity in understanding the layers
Scalable and maintainable	Requires thorough planning
Facilitates team collaboration	Needs consistent enforcement of conventions

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.

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

✅ Pros	❌ Cons
Independent deployments	High complexity in orchestration
Scalability across large teams	Requires robust infrastructure
Technology-agnostic approach	Potential inconsistencies in user experience

Conclusion

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

Approach	Description	✅ Pros	❌ Cons
Flat Structure	Simple structure for small projects	Easy to implement	Not scalable, can become cluttered
Atomic Design	Hierarchical component-based structure	Scalable, organized, reusable components	Overhead in managing layers, initial complexity
Modular Approach	Feature-based modular structure	Scalable, encapsulated features	Potential duplication, requires discipline
Feature-Sliced Design	Functional layers and slices for large projects	High cohesion, clear separation	Initial complexity, requires thorough planning
Micro Frontends	Independent deployments of frontend components	Independent deployments, scalable	High complexity, requires coordination between teams

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:

Good:

Related Component Names

Group related components together by naming them accordingly.

Bad:

Good:

Order of Words in Component Names

Component names should start with the highest-level words and end with descriptive modifiers.

Bad:

Good:

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

Approach 2: Inline Test Files

Additional Resources

How to Persist User Data with LocalStorage in Vue

alex.opalic.dev@gmail.com (Alexander Opalic) — Sun, 21 Apr 2024 15:22:00 GMT

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()

Using LocalStorage for Dark Mode Settings

In Vue, you can use LocalStorage to save a user’s preference for dark mode in a component.

<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:

Type Safety and Key Validation: Always check and handle data from LocalStorage to prevent errors.
Decoupling from LocalStorage: Avoid direct LocalStorage interactions in your components. Instead, use a utility service or state management for better code maintenance and testing.
Error Handling: Manage exceptions like browser restrictions or storage limits properly as LocalStorage operations can fail.
Synchronization Across Components: Use event-driven communication or shared state to keep all components updated with changes.
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.

// 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.

// 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

// composables/useDarkMode.ts
export function useDarkMode() {
  const isDarkMode = ref(LocalStorageHandler.getItem("darkMode") ?? false);

  watch(isDarkMode, newValue => {
    LocalStorageHandler.setItem("darkMode", newValue);
  });

  return { isDarkMode };
}

You can check the full refactored example out here

Play with Vue on Vue Playground

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.

How to Write Clean Vue Components

alex.opalic.dev@gmail.com (Alexander Opalic) — Sun, 28 Jan 2024 15:22:00 GMT

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:

View: This is the template section where you design the user interface.
Reactivity: Here, Vue’s features like ref make the interface interactive.
Business Logic: This is where you process data or manage user actions.

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

<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

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.

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:

Predictability: If you give a pure function the same inputs, it always gives back the same output.
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.

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.

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.

<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.

The Problem with as in TypeScript: Why It's a Shortcut We Should Avoid

alex.opalic.dev@gmail.com (Alexander Opalic) — Sun, 21 Jan 2024 15:22:00 GMT

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:

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.

// 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.

// @errors: 2345

// 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:

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.
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.

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.

Exploring the Power of Square Brackets in TypeScript

alex.opalic.dev@gmail.com (Alexander Opalic) — Tue, 19 Dec 2023 15:22:00 GMT

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.

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.

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.

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.

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.

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.

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.

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.

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 provides comprehensive documentation of these features. TypeHero 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.

How to Test Vue Composables: A Comprehensive Guide with Vitest

alex.opalic.dev@gmail.com (Alexander Opalic) — Sat, 25 Nov 2023 15:22:00 GMT

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

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:

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:

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:

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:

<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:

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.

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:

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:

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:

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:

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:

Simulates a component hierarchy
Provides the necessary injection values
Executes the composable in a proper Vue context
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.

Robust Error Handling in TypeScript: A Journey from Naive to Rust-Inspired Solutions

alex.opalic.dev@gmail.com (Alexander Opalic) — Sat, 18 Nov 2023 15:22:00 GMT

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:

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:

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:

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

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:


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?

Explicit Handling: Forces handling of both outcomes, enhancing code robustness.
Clarity: Makes code intentions clear.
Safety: Reduces uncaught exceptions.
Functional Approach: Aligns with TypeScript’s functional programming style.

Leveraging ts-results for Rust-Like Error Handling

For TypeScript developers, the 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.

Mastering Vue 3 Composables: A Comprehensive Style Guide

alex.opalic.dev@gmail.com (Alexander Opalic) — Sat, 16 Sep 2023 15:22:00 GMT

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.

File Naming

Rule 1.1: Prefix with `use` and Follow PascalCase

// Good
useCounter.ts;
useApiRequest.ts;

// Bad
counter.ts;
APIrequest.ts;

Composable Naming

Rule 2.1: Use Descriptive Names

// Good
export function useUserData() {}

// Bad
export function useData() {}

Folder Structure

Rule 3.1: Place in composables Directory

src/
└── composables/
    ├── useCounter.ts
    └── useUserData.ts

Argument Passing

Rule 4.1: Use Object Arguments for Four or More Parameters

// 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

// 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.

// 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.

// 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

// 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.

// 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:

Initializing: Setup logic
Refs: Reactive references
Computed: Computed properties
Methods: Functions for state manipulation
Lifecycle Hooks: onMounted, onUnmounted, etc.
Watch

Pick an order that works for your team and apply it consistently across all composables.

// 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.

Best Practices for Error Handling in Vue Composables

alex.opalic.dev@gmail.com (Alexander Opalic) — Thu, 18 May 2023 15:22:00 GMT

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

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

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.

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.

return {
  pokemon,
  species,
  evolution,
  load,
  loadSpecies,
  loadEvolution,
  error: computed(() => error.value),
};

Full Code

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:

<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.

How to Improve Accessibility with Testing Library and jest-axe for Your Vue Application

alex.opalic.dev@gmail.com (Alexander Opalic) — Wed, 12 Apr 2023 15:22:00 GMT

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:

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:

<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:

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:

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.

Mastering TypeScript: Looping with Types

alex.opalic.dev@gmail.com (Alexander Opalic) — Fri, 23 Sep 2022 15:22:00 GMT

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:

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:

type ReadonlyUser<T> = {
  readonly [P in keyof T]: T[P];
};

This technique is extensible. For example, adding nullability:

type Nullable<T> = {
  [P in keyof T]: T[P] | null;
};

Or filtering out certain types:

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:

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:

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:

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.

alexop.dev

How to Write UI Components That Stay Flexible

Table of Contents

TLDR

See It Before You Read About It

Smell #1: Duplicated Monoliths

Smell #2: One God Component With v-ifs

The Solution: Compose Trees, Don’t Configure Them

Reading shadcn-vue: The Dialog Primitive

A Quick Detour: How provide and inject Work

Building Your Own: A Dialog Component

Step 1: The provider owns state

If you use VueUse, there is a helper for this

Step 2: The root injects, doesn’t render

Step 3: Each child is small and focused

Step 4: Compose distinct variants

The whole thing, running

State Lives in the Provider, Not the Layout

Styling Without Locking Consumers In: cn()

Watch the merge happen

State as Contract: The data-* Pattern

data-state: the current state of the component

data-slot: stable identity for each part

Other attributes you’ll see

Why attributes, not classes

Element Handoff: as-child

The Convenience Layer

How to Apply This in Your Codebase

When Not to Use It

Connections

References

A Modern Quality Pipeline and Testing Strategy for Frontend Projects

Background

My default stack

The layers

1. Type safety

2. Lint and format

3. Unit tests

4. Component tests

5. API mocking

6. Contract testing

7. End-to-end tests

8. Accessibility

9. Visual regression

10. Performance and bundle size

11. Dead code and dependency hygiene

12. Internationalisation drift

13. Preview deployments

14. Automated code review

15. Runtime observability

Where each layer runs

What this gets you

Picking your testing shape

Picking your battles

Supply chain defaults

Related resources

Exploratory QA with AI Agents: Building a Site-Agnostic Harness

A real finding on otto.de

The problem

Overview

What scripted E2E tests are bad at

Six moving parts

The prompt is the config

The {{browser}} --help trick

Three agents, three incompatible CLIs

Two browsers, same charter

Replaying one prompt across agents

A real disagreement

SBTM + PROOF: why the report looks like a tester’s notes

What I’d do differently

Related posts

How to Use Claude Code as an AI QA Tester with Agent Browser

Overview

Table of Contents

Background

The problem

What we’re building

How Agent Browser works

Before you start

Step 1: Agent Browser by hand

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

Styling Without Locking Consumers In: `cn()`

State as Contract: The `data-*` Pattern

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

`data-slot`: stable identity for each part

Element Handoff: `as-child`

The `{{browser}} --help` trick

Step 2: Let Claude drive with `claude -p`

`--system-prompt` vs `--append-system-prompt`

The Problem with `splice`

The Setting: `spinnerVerbs`