DEV Community: Eugene Yakhnenko

Why I Built an Identity Provider in Go and SQLite

Eugene Yakhnenko — Thu, 26 Mar 2026 23:44:40 +0000

When I set out to build Auténtico, my primary goal was to create a fully-featured OpenID Connect Identity Provider where operational simplicity was the first-class design principle.

Identity infrastructure is notoriously complex. A typical self-hosted setup involves a database server, a cache tier like Redis, a worker queue, and the identity service itself. When I needed a lightweight OpenID Connect (OIDC) server to run on a small 2GB RAM VPS, I realized the existing landscape was either operationally exhausting or structurally flawed for my specific needs.

This is the story of how (and why) I built Auténtico, a self-contained, single-binary OIDC provider backed by SQLite that removes the ceremony from identity management.

The Itch: Finding the Right Lightweight IdP

My journey started because I was researching and implementing a frontend OIDC library for product needs at my company. That scratched an itch, and I evolved it into a functional backend OIDC protocol server in Go.

Months later, when I needed a lightweight Identity Provider, I evaluated the popular options but quickly hit roadblocks:

Casdoor: I didn't like how they treated private data. Their demo instances recycle accounts every 5 minutes, making it impossible to truly test account deletion.
PocketId: This is a fantastic tool, but it had a critical UX flaw for my needs: it is passkey-only by default.

While passkeys are the future, the current ecosystem is heavily fragmented. If a user is on an older OS or a restrictive browser, a passkey-only IdP completely locks them out.

The Antidote: Zero-Ceremony Architecture

I decided to convert my OIDC protocol server into a full IdP, ensuring that every architectural decision was evaluated against a single question: does this reduce or increase the operational burden on the person running this?

Auténtico removes the entire traditional identity stack:

Single Binary: The entire IdP runs as one Go binary.
Embedded SQLite: There is no separate database server. The entire state lives in one file. Eliminating the external database removes connection pool tuning, credential rotation, and network partitions.
No External Infrastructure: No Redis, no Postgres, no message queues. Background cleanup goroutines automatically purge expired tokens, sessions, and auth codes.
Embedded UIs: Both the Admin dashboard (React/Ant Design) and the user-facing Account UI (React/Tailwind) are compiled directly into the binary using go:embed. There are zero separate frontend deployments.

Flexibility Over Dogma: Solving the Passkey Trap

To solve the hardware and OS fragmentation issues I experienced with passkeys, I ensured Auténtico wouldn't trap operators into a single authentication path.

Instead, Auténtico offers three distinct authentication modes that are switchable at runtime without restarting the server:

password
password_and_passkey
passkey_only

If you deploy passkey_only and discover your users' specific browser combinations are failing, you can instantly flip a setting in the Admin UI to fall back to passwords. For robust security without passkeys, it includes standard fallback methods like TOTP (with in-browser QR enrollment) and Email OTP. For users with modern browsers, it fully supports hardware-backed FIDO2 authentication and even allows first-login registration in one seamless flow.

The "Deliberately Un-clever" Architecture & The AI Accelerator

To make this work, the codebase had to be deliberately un-clever. I designed a strict vertical-slice architecture where each package (like pkg/login or pkg/token) owns its exact slice of functionality with a predictable structure:

model.go
handler.go
service.go
Database CRUD

This strictness had a massive secondary benefit: it created the perfect environment for AI. Because I spent the time establishing this blueprint, I reached a tipping point where I could hand off the boilerplate. AI agents seamlessly followed the patterns to generate the CRUD operations and rapidly write over 700 tests (hitting 80% coverage) precisely because the architectural constraints were so rigid.

The Scale Ceiling (And Why It Doesn't Matter)

The immediate pushback to this architecture is always: "SQLite doesn't scale."

I am intentionally honest about the scale ceiling: SQLite serializes writes. Auténtico is not designed for active-active multi-region deployments or massive enterprise horizontal scaling.

However, let's look at the math:

Concurrency	Error rate	Login p95	Token p95	Assessment
20 VUs	0%	86ms	54ms	Comfortable — imperceptible to users
100 VUs	0%	611ms	647ms	Supported — fully functional
500 VUs	0%	3.36s	3.89s	Degraded — users feel the wait

Performance tests with k6 show the system degrades gracefully via SQLite's busy timeout—queueing requests and adding latency rather than throwing errors.

For most teams running internal tools, small-to-mid-sized apps, or self-hosted environments, trading infinite horizontal scaling for zero operational overhead is absolutely the right choice.

Conclusion

Operational simplicity does not mean protocol simplicity.

Auténtico strictly enforces:

OIDC Discovery — publishes /.well-known/openid-configuration so relying parties auto-configure without hardcoding endpoints
JWK Set — exposes public signing keys at /.well-known/jwks.json for independent token verification
RS256 JWT Signing — asymmetric signing; the private key never leaves the IdP
Auth2/OIDC protocol: ImplementsOIDC protocol
Admin UI: For admins to manage clients, users and session
Account UI: For users to manage they profile
Swagger OpenAPI docs: Publishes api specs docs

If you are a small team, an indie developer, or just someone who wants to deploy an Identity Provider without taking on a second job as a sysadmin, sometimes the best architecture is the one you barely have to think about.

The Lightweight JavaScript Framework Renaissance of 2026

Eugene Yakhnenko — Tue, 24 Mar 2026 01:43:52 +0000

Best JavaScript Frameworks in 2026: For AI and Humans

The JavaScript framework landscape in 2026 looks different from what it did three years ago. Not because React disappeared or Vue lost relevance, but because something shifted in how code gets written. AI coding assistants now author a significant portion of frontend code. That changes the evaluation criteria in ways the existing framework rankings haven't caught up with yet.

This article covers both the established giants and the growing category of lightweight libraries that are having a quiet renaissance. The goal is to help you pick the right tool given who, or what, will be writing most of your code.

The New Evaluation Criteria

The classic framework checklist covered performance, ecosystem, learning curve, and job market. Those still matter. But in 2026, two new questions belong on that list:

How much does this framework cost an AI to get right?

Every framework has footguns. The question is whether those footguns require deep framework-specific knowledge to avoid, or whether they're the kind of mistakes any developer (human or AI) would catch on a first read. Frameworks with fewer implicit rules produce more reliable AI-generated code.

Can you run it without a build pipeline?

For quick prototypes, internal tools, and AI-generated demos, the ability to drop a script tag and go is genuinely valuable. Not every project needs a bundler, and forcing one adds friction that compounds when an AI agent is setting up the environment.

The Heavy Framework Tax

React, Vue, Angular, and Svelte dominate the ecosystem. They dominate for real reasons: massive communities, mature tooling, rich ecosystems, and years of production hardening. None of what follows is an argument to abandon them.

But they carry weight.

React requires understanding hooks ordering rules, useEffect dependency arrays, stale closure behavior, and the distinction between controlled and uncontrolled components. These are not obvious from the surface syntax. AI agents generating React code make predictable, repeatable mistakes in all of these areas. The community has documented them extensively, which means LLMs have seen the patterns, but also means the footguns are well-established and hard to train away.

Vue 3 is more approachable. The Composition API is clean, and <script setup> reduces boilerplate significantly. The reactivity model is intuitive. But the template compiler is a black box, the distinction between ref and reactive trips up new users (human and AI alike), and the ecosystem split between Options API and Composition API adds cognitive overhead.

Angular is the most structured of the group. Structure helps, but Angular's DI system, decorators, zone.js, and now the signals migration mean there is a lot of framework-specific knowledge required before you can write idiomatic code. It remains the right choice for large enterprise teams where that structure is the point.

Svelte compiles away at build time, which is elegant. But the compiler is the framework. You cannot use Svelte without a build step, the template syntax is non-standard HTML, and the reactivity model (especially the $: syntax in Svelte 4 and the runes in Svelte 5) requires knowing Svelte specifically. An AI agent that hasn't seen enough Svelte in training will produce subtly wrong reactive code.

None of this is fatal. Millions of applications run on these frameworks and will continue to. But there is a real cost, and it is higher when an AI is holding the pen.

The Light Library Renaissance

A different category of tools has been growing steadily: small, focused libraries that add reactivity and component structure on top of the browser's native model rather than replacing it. They tend to share a few traits:

No build step required for core functionality
Templates that stay close to HTML, or use standard JS tagged literals
Signal-based or proxy-based reactivity with simple rules
Minimal framework-specific concepts to learn

In 2026, this category is no longer a niche. It is a legitimate choice for a wide range of projects, and in many cases the better choice for AI-generated code.

Arrow.js

Arrow.js (@arrow-js/core) is one of the most technically interesting entries in this space. It was built by Standard Agents and has an architecture that reads like a deliberate response to framework complexity.

The core model is simple: reactive state is a plain object wrapped in reactive(), and templates are JavaScript tagged literals using the html tag.

import { reactive, html } from '@arrow-js/core'

const state = reactive({ count: 0 })

html`
  <div>
    <p>Count: ${() => state.count}</p>
    <button @click="${() => state.count++}">+</button>
  </div>
`(document.getElementById('app'))

A few things stand out here. Reactive expressions in templates are just arrow functions. Static values render once; functions are tracked and re-run when dependencies change. That distinction is explicit in the syntax, not hidden behind a compiler.

The reactivity model is proxy-based rather than signal-based. This means you mutate properties directly (state.count++), and array mutations like .push() trigger updates without requiring a reassignment. For developers coming from plain JavaScript, this feels natural.

Components are defined with component(), a factory function that runs once per slot and returns a template. Local state, side effects, and cleanup all live inside the factory.

const Counter = component((props) => {
  const local = reactive({ clicks: 0 })
  return html`<button @click="${() => local.clicks++}">
    ${() => local.clicks}
  </button>`
})

Arrow's package ecosystem is notably complete. Beyond the core, it ships SSR with @arrow-js/ssr, client-side hydration with @arrow-js/hydrate, hydration boundary recovery, and a QuickJS/WASM sandbox (@arrow-js/sandbox) for safely running user-authored Arrow code in the browser. That last one is unusual and speaks to an AI-native use case: letting agents generate and execute code without granting them access to the host page.

The tradeoff is that templates live in JavaScript. The html tagged literal approach means your markup is a JS string, not a file an HTML tool understands natively. That is a different philosophy from the HTML-first camp, and whether it is a feature or a limitation depends on the project.

Kasper.js

Kasper.js takes the opposite position on the templates-vs-JavaScript question. Templates are valid HTML. Directives are standard HTML attributes prefixed with @. Any developer who knows HTML can read a Kasper template without knowing Kasper.

<template>
  <div>
    <p>Count: {{count.value}}</p>
    <button @on:click="increment()">+</button>
    <div @if="count.value > 10">You clicked a lot.</div>
  </div>
</template>

<script>
import { Component, signal } from 'kasper-js'

export class Counter extends Component {
  count = signal(0)
  increment() { this.count.value++ }
}
</script>

The reactivity model uses signals with explicit .value reads and writes. This is more verbose than Arrow's proxy approach, but it makes reactive reads visible in both code and templates. An AI agent reading a Kasper template knows exactly which values are reactive and when they update.

Components are classes. This is a deliberate choice for AI compatibility: classes have well-defined ownership, explicit methods, and a lifecycle that maps directly to familiar OOP patterns. There are no hook rules, no dependency arrays, no rules about where you can call what. onMount, onChanges, onRender, onDestroy: the lifecycle is what it says it is.

Cleanup is handled through a single AbortController that every component owns. this.watch(), this.effect(), this.computed(), and all @on: event listeners are released automatically when the component is destroyed. No return () => cleanup(). No forgetting to unsubscribe.

The expression evaluator is worth noting: it is a custom recursive-descent parser, not eval and not new Function. This means Kasper templates work under strict Content Security Policies, which matters for enterprise and regulated environments. The parser is more capable than it might sound: it covers the full practical range of JavaScript expressions, including arrow functions, optional chaining, nullish coalescing, object and array literals with spread, typeof, instanceof, postfix and prefix operators, and a pipeline operator (|>). The only meaningful gaps compared to full JavaScript are statement-level constructs like async/await, for loops, and switch, none of which belong in a template expression anyway.

The no-build-step story is genuine. One CDN import (16KB gzipped) and you have signals, a router, slots, and lazy loading. The Vite plugin adds single-file .kasper components on top, but it is optional.

<script type="module">
  import { App, Component, signal } from 'https://cdn.jsdelivr.net/npm/kasper-js/dist/kasper.min.js'

  class Counter extends Component {
    count = signal(0)
  }
  Counter.template = `<button @on:click="count.value++">{{count.value}}</button>`

  App({ root: document.body, entry: 'counter', registry: { counter: { component: Counter } } })
</script>

Kasper also ships an llms.txt at kasperjs.top/llms.txt, a machine-readable reference file specifically for AI agents. It covers the full API surface in a compact format designed for context windows, which reflects where the framework sees the ecosystem going.

Others Worth Knowing

Alpine.js is the simplest entry point in the light library category. Directives live directly on HTML elements as attributes (x-data, x-show, x-on:click). There is no component system, no build step, and very little to learn. It is excellent for adding interactivity to server-rendered pages. It is not the right tool for building SPAs.

Lit comes from Google and is built on Web Components. Templates use tagged literals like Arrow, and reactivity is property-based. Lit components are real custom elements, which means they work in any framework or no framework. The tradeoff is that Web Component conventions (shadow DOM, attribute reflection, property vs attribute distinctions) add complexity that pure library approaches avoid.

Solid.js is a compiler-based framework like Svelte, but its output is fine-grained reactive updates with no virtual DOM. Performance is exceptional. The JSX surface looks like React, which helps with adoption, but the mental model is fundamentally different: components run once, and reactivity is tracked through signal reads. Solid is worth learning if performance is a primary concern and you are comfortable with a build step.

Petite-Vue is a distribution of Vue designed for progressive enhancement. It is small, requires no build step, and works well when you need Vue's template syntax on an existing server-rendered page. It is not a full SPA framework.

Comparison at a Glance

Framework	Build Required	Reactivity	Template Style	AI-Friendly
React	Yes	Hooks	JSX	Moderate
Vue 3	Optional	Proxy/Ref	HTML + compiler	Moderate
Angular	Yes	Signals/Zone	HTML + compiler	Low
Svelte 5	Yes	Runes	HTML + compiler	Moderate
Arrow.js	No	Proxy	JS tagged literals	High
Kasper.js	No	Signals	Valid HTML	High
Alpine.js	No	Proxy	Inline HTML	High
Lit	No	Properties	JS tagged literals	High
Solid	Yes	Signals	JSX	Moderate

How to Choose

Use React, Vue, or Angular when you are joining an existing team, building a product that needs a large ecosystem, or hiring for a team that already knows the framework. The community, tooling, and hiring pool are real advantages that lightweight alternatives cannot match yet.

Use Svelte or Solid when bundle size and runtime performance are primary constraints and you are comfortable with a compiler in the pipeline.

Use Arrow.js when you want the smallest possible runtime, prefer JavaScript-centric templates, need SSR with hydration out of the box, or are building tooling where the sandbox package is relevant.

Use Kasper.js when HTML-first templates matter (for readability, CSP compliance, or AI-generated code), when you want class-based components with automatic cleanup, or when a no-build-step option has real value for your workflow.

Use Alpine.js when you have server-rendered HTML and want to add interactivity without touching the build pipeline.

Use Lit when Web Components interoperability is a requirement.

Conclusion

The right framework in 2026 is still context-dependent. The established four are not going anywhere, and for many teams they remain the correct answer.

But the light library category has matured. Arrow.js and Kasper.js in particular are not toys or experiments: they are complete, well-tested solutions with clear architectural philosophies. They are simpler by design, not by omission. And in an era where AI agents write a growing share of frontend code, simpler-by-design has compounding returns.

The best framework is the one your team, and your tools, can use correctly. In 2026, that calculation includes AI as a member of the team.

Building a JavaScript Framework (and Failing Twice at Reactivity)

Eugene Yakhnenko — Mon, 23 Mar 2026 01:46:01 +0000

About five years ago, I didn't set out to build a framework I'd use in production.

I just wanted to understand them.

I had already written parsers and interpreters before, so I knew the mechanics: tokenization, ASTs, execution. But frameworks felt different. They weren't just about parsing code; they were about state, updates, and keeping the UI in sync. Reactivity was the part I didn't understand. So I decided to build one from scratch.

I started with the pieces I knew: a scanner, a parser, a JavaScript interpreter, and an HTML template parser. After a while, I had a working system: a small component model and a template engine that could render real views. It looked like a framework.

But it was missing the one thing that actually makes a framework feel alive: reactivity.

<template>
  <h1>{{count.value}}</h1>
  <div class="actions">
    <button @on:click="count -= 1">-</button>
    <button @on:click="count += 1">+</button>
  </div>
</template>

<script>
  import { signal, Component } from "kasper-js";

  export class Counter extends Component {
    count = signal(0);
  }
</script>

<style>
  h1 {
    font-size: 2rem;
  }
</style>

The Part That Failed Twice

I tried implementing reactivity early on. It didn't work. I've tried with using Proxy, I tried just using a render() function, it was not clicking. There where other parts of the framework I struggled with as well, but reactivity left an imprint.

Later, I tried again. This time I got something running; but it was fragile. It only worked for a single component. Child updates broke. State invalidation was inconsistent. It looked like reactivity, but you couldn't trust it.

So I dropped it again.

Coming Back to It

The project sat dormant for a long time, almost abandoned. Other projects took over. Life moved on. After a few years away, I returned to it. This time, I approached it differently. Instead of trying to "add reactivity," I focused on correctness first, testing everything, and simplifying assumptions.

With the help of AI agents, I rebuilt the system around signals.

That changed everything.

Once signals were in place, the architecture became much simpler: no virtual DOM, no diffing, direct updates to real DOM nodes, fine-grained reactivity. But the real breakthrough wasn't just the model. It was the process.

600 Tests Later

I started adding tests. Then more tests. Then hundreds more. With AI assistance, I reached 600+ test cases. At that point, something unexpected happened: the AI couldn't generate any new meaningful tests. Everything obvious and most non-obvious cases were already covered.

The test were meaningful. It felt complete.

But it wasn't. Of course it wasn't. Just because 600+ tests pass it doesn't mean your system has no bugs.

The Real Test Wasn't Tests

The codebase looked solid. The tests passed. But there was still a problem: no one had actually used the framework to build real apps.

So I tried something different. Instead of writing apps manually, I asked AI agents to build them.

And they failed immediately.

Not because the framework was broken; but because the AI didn't know how to use it. This was a surprising moment. The system worked, but it wasn't understandable.

The Missing Piece: Documentation for AI

That's when I introduced something modern: llms.txt.

A dedicated, structured specification designed for AI agents. Not marketing docs. Not tutorials. Just syntax, rules, constraints, and examples. Think of it as a "principal engineer version" of the API.

Then I started a loop: give the AI the spec, ask it to build an app, observe where it fails, update the spec, repeat.

After a few iterations, something remarkable happened. The AI started generating full apps on the first try: todo apps, CRUD interfaces, Kanban boards, tree views, infinite scroll, even Game of Life. All working.

Article about my experience with llms.txt

A Surprising Insight About AI

At one point, the AI became very confident about a "necessary" architectural change. It proposed a redesign that would require around 100 lines of changes. We tried it. It failed repeatedly.

After stepping back and analyzing the problem, the real fix was 5 lines of code.

That moment stuck with me. AI can be incredibly helpful but it can also confidently overcomplicate problems.

When Tests Stop Helping

With 600+ tests, the system looked stable. But once the AI started generating real applications, new edge cases appeared: subtle rendering issues, lifecycle timing problems, data edge cases that no unit test would have caught in isolation.

So I kept going. Built more apps (shopping cart, dashboards, editors, product listing, interractive tables with pagination), fed failures back into the system, and added more tests. Real usage found things that testing alone never would.

What Actually Made the Framework Stable

Looking back, it wasn't one thing. It was the combination of:

A simple reactive model (signals)
Relentless testing (600+ cases)
Real-world usage (apps, not just tests)
AI as both a developer and a user

The Unexpected Win

One design choice I made years ago turned out to be critical: the template syntax was valid HTML. Originally, this was just for better syntax highlighting. But later, it made the framework significantly more AI-friendly. No custom grammar. No ambiguity. Just HTML with extensions.

What I'd Do Differently

If I started today, I would design the reactive model first, write tests earlier (a lot earlier), treat AI as a first-class user from day one, and create a machine-readable spec alongside human docs.

Where It Ended Up

After years of on-and-off work, multiple failures, and hundreds of tests, the framework is stable. Not because it's perfect, but because it survived repeated redesigns, real usage, and constant pressure from both humans and machines.

Building the framework wasn't the hardest part. Making it correct, usable, and understandable for both humans and AI was the real challenge.

Try it out!

Learn more about kasper.js at:

We Had to Write Docs for AI: llms.txt Changed Everything

Eugene Yakhnenko — Mon, 23 Mar 2026 01:37:14 +0000

Most developers write documentation for humans.

While building my JavaScript framework, I ran into a problem I didn't expect: the framework worked but AI couldn't use it. Not "wasn't perfect." Not "made small mistakes." It completely failed to build even basic apps correctly unless it had the source code of the framework available.

The Moment Things Broke

After years of work, I finally had a stable system: a custom scanner, parser, interpreter, a template engine with components, a signal-based reactivity system, and around 600 tests covering edge cases. I thought I was done.

So I tried something simple: "Build a todo app using this framework."

What I got back looked confident, but was completely wrong. Wrong syntax. Wrong mental model. Invented features that didn't exist.

This wasn't a bug in the framework. It was a documentation failure.

README Is Not Enough Anymore

Traditional documentation is designed for humans: narrative explanations, gradual onboarding, examples mixed with storytelling.

AI doesn't work like that. It doesn't "read" docs. It pattern-matches and guesses. So when the documentation is incomplete, ambiguous, or too prose-heavy, AI fills in the gaps. Confidently. Incorrectly.

The Solution: llms.txt

The solution was simple in hindsight: treat AI like a strict compiler, not a reader.

I created a new file: llms.txt. Not marketing docs. Not tutorials. Just raw, explicit specification.

The rules were strict:

No prose. No storytelling, no explanations. Only syntax, rules, and constraints.

No ambiguity. There's a big difference between:

You can use @if for conditional rendering.

and:

@if="condition"
- condition must be a valid JS expression
- evaluates to truthy/falsy
- false removes node from DOM

Complete surface area. All directives, template expressions, components, lifecycle hooks, signal behavior, everything explicitly defined. Nothing implied.

Minimal but real examples:

<ul>
  <li @each="item in items" @key="item.id">{{ item.name }}</li>
</ul>

Reading the Docs + Source Code

Even with llms.txt, the AI couldn't just guess everything. It needed to read a lot of source code, inspect function signatures, understand how signals propagate, see how component lifecycle worked. Only then could it map the spec to the actual implementation and generate working apps.

Building apps wasn't magic. It was AI + spec + code comprehension.

The Iteration Loop

I didn't just hand over the file and hope. The loop looked like this:

Give AI the current llms.txt and source access
Ask it to build a real app (todo, kanban, etc.)
Observe failures
Fix the spec
Repeat

A few things became clear along the way.

Missing features aren't always obvious. At one point, AI kept trying to use @keydown.enter. I had never documented it but the framework already supported it. The fix was to update the spec, not the code.

Ambiguity is worse than missing features. Undocumented features lead to confident guesses. Vaguely documented features lead to confident wrong guesses. Explicit rules always win.

AI exposes your own blind spots. It suggested massive architectural rewrites; redesign scope tracking, refactor core systems. All seemed convincing. The result: 100 lines of changes, none of which worked. The real fix? Five lines of code. AI can be very persuasive about the wrong solution.

When It Finally Clicked

After a few iterations of refining llms.txt and reading source code, AI could reliably generate todo apps, Kanban boards, tree views, infinite scroll, and Game of Life (first try), fully working, following spec.

Real apps also exposed edge cases that 600 unit tests never would: shopping carts, form wizards, markdown editors, live dashboards. The tests covered everything within a known model. Real usage kept expanding the model.

Two Types of Documentation

There are now two distinct audiences for docs:

Human docs: explain concepts, tell the story, teach mental models.

AI docs (llms.txt): define rules, eliminate ambiguity, maximize correctness.

Both are necessary. They serve completely different purposes and shouldn't be conflated.

The Unexpected Payoff

One design decision made early on turned out to help here too: the template syntax was valid HTML. This meant free syntax highlighting, editor support, and it turns out, AI-friendly defaults. The more your syntax looks like existing patterns, the less AI has to guess.

Final Thought

The hardest part wasn't building the framework. It wasn't reactivity or performance.

It was making the system understandable to something that doesn't actually understand.

We're entering a world where humans write ideas and AI writes implementations. In that world, specification becomes the product. Not just a supplement to the code, the thing that makes the code usable at all.

Learn more about kasper.js at:

Adding Attribute-Based Access Control to a Real-Time Collaborative App with OpenTDF

Eugene Yakhnenko — Fri, 20 Mar 2026 07:52:05 +0000

I built Skedoodle, an open-source real-time collaborative sketching app. Think a lightweight Figma for doodling: multiple users connect over WebSocket, draw on a shared infinite canvas, and see each other's cursors move in real time. It's built with React, TypeScript, Two.js for vector graphics, and Zustand for state management, with an Express backend handling persistence and real-time sync.

Building the interactive parts was the fun challenge. Throttled rendering at 60fps, path simplification algorithms to keep stroke data lean, touch support, pan and zoom on an infinite canvas, undo/redo that works across multiple collaborators. Skedoodle is a proper interactive app, not a toy demo.

But it had a glaring gap: no authorization. Authentication? Sure, users logged in via OIDC. But once you were in, you could access any sketch if you knew the ID. Think YouTube: every video is technically accessible if you have the link, even "unlisted" ones. Skedoodle had the same problem. There was no way to control who could see or edit what.

I needed to fix this. And rather than hand-roll role checks and a collaborators table, I wanted to use a proper policy engine — one that could handle the simple case today and scale to more complex scenarios without rewriting everything.

How This Project Started

This whole project started because I was working with an AI agent to generate an llms.txt for OpenTDF; a structured documentation file designed to give AI agents enough context to work with a platform. Once we had it, the obvious next step was to test it: take a real project with no authorization at all, point an agent at the llms.txt, and see if it could build a correct ABAC integration from scratch.

Skedoodle was the perfect candidate. A real collaborative app, with authentication but zero authorization. The experiment: could an AI agent, armed only with OpenTDF's llms.txt and a description of the access model I wanted, deliver a working integration?

Why OpenTDF

OpenTDF is an open-source platform maintained by Virtru that provides attribute-based access control (ABAC) alongside end-to-end encryption via the Trusted Data Format specification.

What drew me in was how lightweight the authorization integration is. OpenTDF is known for its encryption capabilities, but the ABAC engine stands entirely on its own. You don't need to encrypt anything to use it. You define policies, and the platform makes access decisions. That's exactly what I needed: a centralized policy engine that could answer "does this user have access to this sketch?" based on attributes rather than hardcoded role checks.

The ABAC model is straightforward:

You define namespaces and attributes (e.g., https://skedoodle.com/attr/sketch-access)
Each attribute has values and a rule (AnyOf, AllOf, or Hierarchy)
Subject mappings connect identity provider claims to attribute entitlements
When someone requests access, the platform evaluates their entitlements against the resource's required attributes and returns permit or deny

No SDKs to embed, no agents to deploy. It's a JSON API you call. Your app manages the data, OpenTDF manages the policy.

The Access Model

What I wanted was straightforward:

Owner creates a sketch and always has full access
Owner can invite other users by username
Owner can remove any collaborator
Collaborators can draw on the sketch and can leave voluntarily
Collaborators cannot remove other collaborators or the owner
No public access — every sketch requires an explicit ABAC grant. Read-only public sharing could be layered on later as a separate attribute.

Simple enough for users to understand, but it needs proper enforcement at every layer: REST API, WebSocket connections, and the real-time command stream.

Building It with an AI Agent

I used Claude Code as my coding agent. The agent fetched OpenTDF's llms.txt at runtime, which gave it the architectural overview, API reference, Connect RPC URL patterns, protobuf enum values, and curl examples it needed to understand the platform.

The agent:

Read the docs and correctly chose ABAC authorization over full TDF encryption, understanding that per-command encryption would be impractical for real-time collaboration
Designed an attribute scheme (one attribute value per sketch, AnyOf rule) that maps cleanly to the sharing model
Built the entire integration: REST API, WebSocket authorization, OpenTDF service with subject mapping lifecycle, and client UI

The llms.txt gave the agent enough context to use the right API patterns without guessing — the correct RPC URL format, the exact enum values for condition operators and boolean types, the entity identifier structure for GetDecisions. I described the access model I wanted, and it delivered a working integration.

The ongoing iteration — refining the architecture, debugging access issues, removing redundant layers — was also done collaboratively with the agent, with llms.txt as the shared reference for how OpenTDF's APIs work. When we hit an issue where ABAC returned PERMIT but the app still denied access, the agent was able to trace the problem because it understood the full authorization flow from the docs.

How the Integration Works

ABAC as the Single Source of Truth

There's no collaborators table in the database. OpenTDF is the sole authority for access control. The database stores sketches, commands, and users. Who has access to what is entirely managed through OpenTDF subject mappings.

This is a deliberate design choice. Instead of maintaining a local access control table and keeping it in sync with a policy engine, the application delegates all authorization to OpenTDF. The only local concept of "role" is ownership: the Sketch table has an ownerId field. Everything else — who can access which sketch, whether a given user is permitted — comes from ABAC.

Policy Structure

On server startup, the service registers Skedoodle's policy structure with OpenTDF:

Namespace: https://skedoodle.com
Attribute: sketch-access (rule: AnyOf)

Each sketch gets its own attribute value. Subject mappings are actively managed as part of the application lifecycle:

Sketch created → register an attribute value, create a subject mapping for the owner
Collaborator invited → create a subject mapping linking the user's username to the sketch's attribute value
Collaborator removed → delete the subject mapping
Access check → call GetDecisions to verify the user has a valid entitlement

The Sharing Workflow

Three endpoints handle collaboration:

POST   /api/sketches/:id/collaborators           Owner invites by username
DELETE /api/sketches/:id/collaborators/:username  Owner removes, or user leaves
GET    /api/sketches/:id/collaborators            List who has access

When an owner invites a collaborator, the app creates a subject mapping in OpenTDF:

const result = await rpc(
  "policy.subjectmapping.SubjectMappingService",
  "CreateSubjectMapping",
  {
    attributeValueId: valueId,
    actions: [{ name: "read" }],
    newSubjectConditionSet: {
      subjectSets: [
        {
          conditionGroups: [
            {
              booleanOperator: "CONDITION_BOOLEAN_TYPE_ENUM_OR",
              conditions: [
                {
                  subjectExternalSelectorValue: ".username",
                  operator: "SUBJECT_MAPPING_OPERATOR_ENUM_IN",
                  subjectExternalValues: [username],
                },
              ],
            },
          ],
        },
      ],
    },
  }
);

This tells the platform: when a user's Keycloak .username matches, grant them the sketch's attribute value entitlement.

Listing collaborators queries ListSubjectMappings and filters for mappings that match the sketch's attribute value. Removing a collaborator deletes the mapping. There's no local state to keep in sync.

Access Checks

Every protected operation — loading a sketch, fetching commands, joining a WebSocket room, saving commands — calls GetDecisions:

const result = await rpc("authorization.AuthorizationService", "GetDecisions", {
  decisionRequests: [
    {
      actions: [{ name: "read" }],
      entityChains: [
        {
          id: "user",
          entities: [{ userName: username }],
        },
      ],
      resourceAttributes: [
        {
          attributeValueFqns: [
            `https://skedoodle.com/attr/sketch-access/value/${sketchId}`,
          ],
        },
      ],
    },
  ],
});
const allowed = result.decisionResponses?.[0]?.decision === "DECISION_PERMIT";

If the platform denies access or is unreachable, the request is rejected. This is a deliberate choice — ABAC is the single source of truth, so there's no stale local copy to fall back to. In a production deployment where availability is critical, you'd want to run OpenTDF with redundancy, or introduce a short-lived decision cache as a buffer. For Skedoodle, fail-closed is the right tradeoff: denying access temporarily is better than granting it incorrectly.

WebSocket Enforcement

Real-time collaboration adds a wrinkle. You can't call a policy service on every brush stroke. The approach:

Authorize on join: call GetDecisions when a user connects
Enforce at the room level: owners and collaborators can draw, the role is set once at join time
Kick on revocation: when access is removed via the API, immediately disconnect the user

// When an owner removes a collaborator
const mappingId = await opentdfService.findSubjectMappingId(targetUsername, sketchId);
if (mappingId) {
  await opentdfService.deleteSubjectMapping(mappingId);
}

const room = rooms.get(sketchId);
if (room) {
  room.kickClientByUsername(targetUsername);
}

The client handles revocation gracefully with a dialog explaining what happened and options to go back.

Listing Sketches from ABAC

To show a user their sketches, the app queries both the database and OpenTDF in parallel:

const [ownedSketches, abacSketchIds] = await Promise.all([
  prisma.sketch.findMany({ where: { ownerId: req.userId } }),
  opentdfService.listSketchIdsForUser(req.username),
]);

Owned sketches come from the database. Shared sketches come from OpenTDF by iterating subject mappings and extracting sketch IDs from attribute value FQNs. The two lists are merged, deduped, and returned with roles.

What This Shows About ABAC

This integration replaced what would typically be a collaborators join table, a set of role-checking queries, and manual sync logic — with a handful of API calls to a policy engine.

Where ABAC gets interesting is what happens next. Today Skedoodle's access model is simple: per-sketch, per-user grants. But the same infrastructure supports:

Mapping team membership to sketch access (subject mappings based on group claims instead of individual usernames)
Classification-based access (new attributes with AllOf or Hierarchy rules)
Cross-organization sharing (attribute values scoped to external identity providers)

These would be policy changes — new attributes, new subject mappings — not application code changes. The checkAccess() call stays the same.

The Timeline

The entire integration took one afternoon:

Phase	Time
Switch identity provider to Keycloak	15 min
Create Keycloak client + test users	10 min
Collaborator API + OpenTDF subject mapping lifecycle	15 min
WebSocket authorization + kick-on-revoke	15 min
Client UI (share dialog, access denied, role badges)	20 min
OpenTDF ABAC service integration	15 min
Debugging and polish	20 min

The OpenTDF integration itself was the smallest piece. Most of the work was building the sharing UX and enforcing access at the WebSocket layer. OpenTDF slotted in cleanly because it's designed to be an authorization service you call, not a framework you restructure your app around.

Key Takeaways

ABAC can be your single source of truth for access control. Instead of maintaining a collaborators table and keeping it in sync with a policy engine, Skedoodle delegates all authorization to OpenTDF. The application code doesn't contain access control logic beyond "ask OpenTDF and respect the answer."

The integration surface is small. Six API operations cover the entire authorization model, callable from any language with plain fetch.

Real-time apps need smart enforcement points. You can't call a policy service on every WebSocket message. Authorize on connect, enforce roles at the room level, and handle revocation proactively by kicking disconnected users.

llms.txt makes AI-assisted integration practical. The agent built a working ABAC integration from documentation alone. Structured, machine-readable docs lower the barrier to adoption — not just for AI agents, but for any developer exploring a new platform.

ABAC scales where RBAC doesn't. Roles are fine until you need to express "users in department X with clearance level Y can access resources tagged with classification Z." That sentence maps directly to ABAC attributes. Trying to model it with roles leads to an explosion of role combinations.

Try It

The OpenTDF integration lives in a dedicated fork: skedoodle-opentdf. It includes everything you need to run the full stack locally.

If you're building an app that needs access control beyond basic ownership — especially if you want centralized policy management or the flexibility to evolve your authorization model over time — ABAC with OpenTDF is worth a look.

Kneel Before Zod!

Eugene Yakhnenko — Fri, 16 Jan 2026 02:56:00 +0000

TypeScript has changed the game for JavaScript developers by adding static type checking, but it doesn’t automatically handle data validation. Especially when dealing with external sources like APIs or user inputs.
Lets break down the challenges of data validation in TypeScript, explores possible solutions, and takes a closer look at Zod, a powerful validation library.

Why Data Validation Matters in TypeScript

Data validation is all about making sure the data you receive is in the right format and contains the right information. This is especially important when handling external data, like API responses, user input or data from local storage. When you define types in TypeScript, they help during development, but they don’t actually enforce anything at runtime. So even if you expect an API to return a certain structure, TypeScript won’t stop it from giving you something completely different.
You've probably experienced this issue tons of times with errors like:

VM228:1 Uncaught TypeError: Cannot read properties of undefined (reading 'something')

Compile-Time vs. Runtime-Time Gap

One of the biggest challenges in TypeScript data validation is the difference between what TypeScript checks at compile time and what actually happens at runtime. For example, when you fetch data from an API, TypeScript assumes it matches your type definitions, but in reality, there’s no guarantee.
Same issue when reading from localStorage. Even when JSON.parse() succeeds, there's no guarantee that the data has the shape you're expecting.
This gap means that without extra validation, your app could end up working with incorrect or unexpected data.

interface User {
  id: number;
  email: string;
}

const fetchUser = async (id: number): Promise<User> => {
  const response = await fetch(`/api/users/${id}`);
  const data = await response.json();
  return data; // But nothing ensures data actually matches User interface
}

const retrieveUser = async (): User | null => {
  try {
    const data = localStorage.get('user');
    const user = JSON.parse(data);
    return user; // But nothing ensures data actually matches User interface
  catch {
    return null;
  }
}

API interfaces are contracts, and usually this is not an issue, specially if you are also the maintainer of the API.

Solutions for TypeScript Data Validation

Type Guards and Assertion Functions

TypeScript's built-in type guards provide a simple validation mechanism:
Type Guards Docs

function isUser(data: unknown): data is User {
  return (
    data !== null &&
    typeof data === "object" &&
    "id" in data &&
    typeof data.id === "number" &&
    "username" in data &&
    typeof data.username === "string" &&
    "email" in data &&
    typeof data.email === "string"
  );
}

// Usage
const processUser = (data: unknown) => {
  if (isUser(data)) {
    // TypeScript knows data is User here
    console.log(data.username);
  } else {
    throw new Error("Invalid user data");
  }
};

This approach works but becomes unwieldy for complex objects, requiring manual implementation of validation logic.

Zod as a Solution for TypeScript Validation

Zod is a TypeScript-first schema validation library with static type inference. It allows defining schemas that validate data at runtime while automatically inferring TypeScript types.
Zod Docs

import { z } from "zod";

const UserSchema = z.object({
  id: z.string(),
  email: z.string().email(),
});

// Extract the inferred type
type User = z.infer<typeof UserSchema>;
// { id: string; email: string }

The retrieve from local storage function would look like:

const retrieveUser = async (): User | null => {
  try {
    const data = localStorage.get('user');
    const user = JSON.parse(data);
    const validatedUser = UserSchema.parse(user);
    return validatedUser; // User matches the type
  catch {
    return null;
  }
}

Pros of Zod

TypeScript-First Design

Zod was built specifically for TypeScript, resulting in excellent type inference and integration with TypeScript's type system. This enables catching type errors during development rather than at runtime.

Schema-to-Type Inference

The z.infer<typeof schema> pattern allows extracting TypeScript types directly from validation schemas, ensuring perfect alignment between validation and types.

Comprehensive Schema Options

Zod supports a wide range of validation options, from simple primitives to complex structures including objects, arrays, tuples, unions, and even functions.

Handy Zod utility: validateSchemaOrThrow

Here is a handy utility for validating schemas. It will attempt to validate the schema.
When it succeeds it returns the validated data. It will re-throw the combined zod errors when data is invalid.

import { z, ZodRawShape } from "zod";

export function validateSchemaOrThrow<T extends ZodRawShape>(
  schema: z.ZodObject<T>,
  data: any
): ReturnType<z.ZodObject<T>["parse"]> {
  const parsed = schema.safeParse(data);

  if (!parsed.success) {
    const error = parsed.error.issues.map(issue => issue.message).join(", ");
    throw new Error(error);
  }

  return parsed.data;
}

This is how it would end up being used in a framework route for example:

export async function POST(request: NextRequest) {
  try {
    const req = await request.json();
    const credentials = validateSchemaOrThrow(LoginSchema, req);
    const authUser = await loginUserOrThrow(credentials);

    return NextResponse.json({ data: authUser }, { status: 200 });
  } catch (err: any) {
    const error = err?.message || "Unexpected login error";
    return NextResponse.json({ error, data: null }, { status: 409 });
  }
}

More info at

https://zod.dev/

Handling Tech Debt while Shipping Features

Eugene Yakhnenko — Fri, 16 Jan 2026 02:54:13 +0000

Picture this: You're halfway through building that exciting new feature everyone's been asking for. You're in the zone. The code is flowing. And then... you discover a bug. Not in your new code—in the old system your feature depends on. What do you do? Fix it now? File a ticket and move on? Pretend you didn't see it? Is it actually a bug or is it a bug in your understanding of the requirements?

If you've been there (and honestly, who hasn't?), you know this moment of choice happens constantly during development. The reality of building software isn't a clean, linear path from requirements to deployment. It's more like exploring a house where opening one door reveals three more doors you didn't know existed, and sometimes those doors are stuck.

Let's talk about how to handle this reality without burning out, missing deadlines, or letting your codebase turn into a maintenance nightmare.

Why This Matters More Than You Think

Here's a sobering fact: when you switch from working on your feature to investigating that bug, it takes your brain about a good amount of time to fully get back into the zone afterward. Not the five minutes you hoped. For a team getting interrupted multiple times a day, that's anywhere from 10-20 hours of lost productivity every week.

And it's not just about time. Studies show that interrupted tasks take twice as long to complete and contain twice as many errors. It's a vicious cycle: poor code quality from interrupted work creates new bugs, which create more interruptions, which create more poor code.

But here's some good news: teams that handle these interruptions well don't eliminate them (that's impossible). They build systems to manage them efficiently.

First Things First: Not Everything is Urgent

The fastest way to chaos is treating every discovered issue like a five-alarm fire. Most things aren't. You need a simple way to decide what actually needs your attention right now.

Here's a framework that works:

P0/Critical: System crashes, data loss, security breaches. Drop everything.

P1/High: Significant features broken but workarounds exist. Handle this sprint or immediately after.

P2/Medium: Degraded experience but not blocking. Can wait until next sprint if needed.

P3/Low: Cosmetic issues, minor UX friction. Backlog material.

The key word here is "actually." Is this actually critical, or does it just feel urgent because you discovered it today?

A helpful trick: use RICE scoring for the gray areas. Score each issue on Reach (how many users), Impact (how badly affected), Confidence (how sure you are), and Effort (how hard to fix). Then calculate: (Reach × Impact × Confidence) / Effort. Higher scores win. This removes emotion from the decision.

Plan for the Unexpected (Because It Will Happen)

Here's where some teams go wrong: they plan sprints as if nothing unexpected will happen. Every hour is allocated to planned work. When interruptions inevitably arrive, the sprint explodes.

Successful teams build buffer into every sprint:

10-15% Corporate overhead: Meetings, emails, ceremonies
60-75% Planned work: Your actual features
10-15% Unplanned work: The buffer for surprises

"But that means we'll deliver less!"

I hear you saying. Actually, no. You'll deliver more consistently because you're planning realistically. Some sprints, you'll have fewer interruptions and pull ahead. Others, you'll use the full buffer. Over time, it averages out—but without the constant feeling of failure.

How much buffer do you need? It depends on the team, product, and environment: Track your actual interrupt load for a few sprints and adjust accordingly.

The Superman Strategy: Protecting Focus Time

For teams dealing with production systems or customer support, here's a game-changer: the Superman rotation.

Instead of spreading interrupts across everyone (death by a thousand distractions), one person handles all interrupts for a set period—a week, a sprint, whatever makes sense. Everyone else gets uninterrupted focus time.

Yes, one person's productivity takes a hit. But the rest of the team's productivity increases, and the net result is usually positive. Plus, the Superman builds deep knowledge of system issues and common problems.

Keys to making this work:

Rotate fairly: Nobody should be permanently on interrupt duty
Provide backup: Have a secondary person for escalation
Be realistic: Junior developers might need help; that's okay
Give them side work: They can tackle documentation, tools, or admin tasks between interrupts

Turn Fires Into Fireproofing

The difference between reactive and proactive teams isn't that proactive teams have fewer problems. It's that they prevent the same problem from happening twice.

After any major issue, follow this pipeline:

Fix the immediate problem (the symptom)
Conduct a quick Root Cause Analysis within 24-48 hours: Why did this happen? Was it missing tests? Unclear requirements? Architecture gap?
Create a prevention artifact: A runbook, automated test, monitoring rule, or architectural change
Track and prioritize improvements: Work the highest-impact, lowest-effort ones into your tech debt time

Example: Payment processing bug blocks the team. Don't just fix it, ask why your tests didn't catch it. Should there be integration tests? Add them. Document the scenario. Set up monitoring. Now it won't happen again.

Protect Your Brain: Reduce Context Switching

Even well-managed interrupts cause context switching. Here's how to minimize the damage:

Reserve focus time blocks: Many teams reserve specific hours as interrupt-free. No meetings, no Slack questions (unless production is literally on fire). Make it a team norm.

Set response time expectations:

Interrupt now (call, DM): Production down, security breach
Same-day response: Code reviews, sprint blockers (within 8 hours)
Next-day response: General questions, non-urgent bugs (within 24 hours)
Async only: Status updates, docs (no immediate response needed)

Limit work-in-progress: One or two active items per developer, maximum. Finish before starting new work. It feels slower but actually speeds things up.

The Missing Requirements Problem

Sometimes the "issue" isn't a bug—it's that you start building and realize the requirements were incomplete. This happens constantly. If you are not breaking things, you are not solving hard problems, and incomplete requirements are part of that.

Three-tier response:

Critical path clarification: If it blocks current work, pause and clarify immediately with your product owner. This should be a 30-minute conversation, not a three-day delay.
Scope decision: Is this part of the current feature? If yes, add it. If no, capture it for later.
Document for next time: Update your requirements template so this gap doesn't recur.

Don't fall into the false choice between "delay everything for perfect requirements" and "build something incomplete." Address blocking gaps now; defer the rest.

Measure What Matters

How do you know if your interrupt management is working? Track:

Cycle time: How long from issue discovery to fix? Faster is better.
Deployment frequency: Are you shipping consistently or sporadically?
Bug escape rate: What percentage of bugs reach production?
Developer satisfaction: Survey your team on focus time and stress levels.

If any of these are trending wrong, your process needs adjustment.

Common Traps to Avoid

Priority inflation: If 50% of your issues are "P0 critical," your definitions are broken. Typically, 5-10% should be P0.

Treating interrupts as planning failure: They're not. They're inevitable in live software. The question is how you handle them.

Permanent interrupt duty: Rotate fairly or you'll burn people out.

Skipping root cause analysis: Fixing the 20th payment bug without understanding why they keep happening means you're firefighting forever. Take the time to prevent recurrence.

Process creep: Don't add so much overhead that the meetings about interrupts are worse than the interrupts themselves.

Start Simple

You don't need to implement everything at once. Here is a simple four-week plan to get started:

Week 1:

Define your priority levels and share with the team
Reserve 10-20% of your sprint for unplanned work
Start a weekly 15-minute triage meeting

Week 2-3:

Try Superman rotation if your team handles interrupts
Protect time blocks as focus time
Set max 2 active items per developer

Week 4+:

Do root cause analysis on major issues
Track your metrics
Adjust based on what you learn

The Bottom Line

Building software means dealing with unexpected issues. The question is not if unexpected issues will happen (they will), but rather when.

Teams that excel at this aren't more talented or better equipped. They just accept reality and build around it: clear prioritization, reserved capacity, focused triage, root cause prevention, and protected focus time.

Your codebase will never be perfect. There will always be tech debt, bugs, and surprises. But with the right system, you can ship features, maintain quality, and keep your team healthy.

The best time to start was yesterday. The second-best time is right now.

Custom HTTP Interceptors in HLS.js for Video Streaming

Eugene Yakhnenko — Fri, 16 Jan 2026 02:52:32 +0000

Custom HTTP Interceptors in HLS.js for Video Streaming

When building video streaming applications, you might need to intercept HTTP requests for authentication, custom decryption, or analytics during video playback. HLS.js makes this surprisingly straightforward with custom loaders. Let's explore what HLS.js is and how to implement HTTP interceptors for video fragment loading.

What is HLS.js?

HLS.js is a JavaScript library that enables HTTP Live Streaming (HLS) playback in browsers that don't natively support it. While Safari handles HLS natively, browsers like Chrome, Firefox, and Edge need HLS.js to parse .m3u8 playlists and stream video fragments seamlessly.

The library handles:

Parsing HLS manifests (.m3u8 files)
Downloading and buffering video segments
Adaptive bitrate switching based on network conditions
Video playback coordination

Installation

Install HLS.js via npm or pnpm:

npm install hls.js
# or
pnpm add hls.js

Basic Usage

Here's a minimal React implementation:

import { useEffect, useRef } from "react";
import Hls from "hls.js";

export function HlsPlayer() {
  const videoRef = useRef<HTMLVideoElement>(null);
  const playlistUrl = "https://example.com/video.m3u8";

  useEffect(() => {
    const video = videoRef.current;
    if (!video) return;

    if (Hls.isSupported()) {
      const hls = new Hls();
      hls.loadSource(playlistUrl);
      hls.attachMedia(video);
    }
  }, []);

  return <video ref={videoRef} controls />;
}

Implementing a Custom HTTP Interceptor

The real power comes when you need to intercept fragment requests.
Create a custom loader by extending Hls.DefaultConfig.loader:

class CustomLoader extends Hls.DefaultConfig.loader {
  load(context: any, config: any, callbacks: any) {
    if (context.frag) {
      // Handle video fragments with custom logic
      fetchVideoFragment(callbacks, context);
    } else {
      // Use default loader for playlists
      super.load(context, config, callbacks);
    }
  }
};

The context.frag check distinguishes between playlist requests (handled by the default loader) and video fragment requests (where we apply custom logic).

Custom Fragment Fetcher

Here's how to fetch fragments with custom handling:

async function fetchVideoFragment(callbacks: any, context: any) {
  const start = performance.now();

  try {
    const response = await fetch(context.url, {
      // Add custom headers here if needed
      headers: {
        'Authorization': '{{ Bearer token }}',
        'X-Custom-Header': '{{Custom value}}'
      }
    });

    const buffer = await response.arrayBuffer();
    const end = performance.now();

    callbacks.onSuccess(
      { data: buffer, url: context.url },
      {
        loading: { start, end },
        loaded: buffer.byteLength,
        retry: 0,
      },
      context
    );
  } catch (error) {
    callbacks.onError(
      {
        code: 0,
        text: (error as Error).message,
        type: "networkError",
      },
      { loading: { start, end: performance.now() }, retry: 0 },
      context
    );
  }
}

This approach lets you:

Add authentication tokens to fragment requests
Decrypt encrypted video segments
Track loading performance metrics
Implement custom error handling
Apply transformations to video data before playback

Putting It Together

Wire up the custom loader when initializing HLS:

export function HlsPlayerHttpInterceptor() {
  const videoRef = useRef<HTMLVideoElement>(null);
  const playlistUrl = "https://example.com/video.m3u8";

  useEffect(() => {
    const video = videoRef.current;
    if (!video) return;

    if (Hls.isSupported()) {
      const hls = new Hls({
        // uses the custom loader
        loader: CustomLoader,
      });

      hls.loadSource(playlistUrl);
      hls.attachMedia(video);
    }
  }, []);

  return <video ref={videoRef} controls />;
}

Use Cases

Custom HTTP interceptors are particularly useful for:

Protected content: Adding authentication headers to video fragment requests
DRM workflows: Decrypting video segments before playback
Analytics: Tracking fragment load times and network performance
Caching strategies: Implementing custom caching logic
A/B testing: Routing requests to different CDN endpoints

Shaking Trees in JavaScript Libraries

Eugene Yakhnenko — Tue, 18 Mar 2025 03:51:58 +0000

Tree Shaking in JavaScript Libraries: Default vs. Named Exports

Tree shaking is an optimization technique that eliminates unused code in JavaScript bundles, significantly reducing the size of applications that consume libraries. When developing JavaScript libraries, the export pattern can dramatically impact your consumers' ability to benefit from tree shaking. Let's explore this with some concrete examples.

Understanding Tree Shaking Limitations with Default Exports

Default exports can prevent tree shaking in several patterns used in JavaScript libraries, resulting in bloated bundles for consumers. Let's review some of these patterns.

The Object Pattern Problem

One of the most common anti-patterns that prevents tree shaking occurs when developers use default exports to export multiple functionalities as properties of a single object:

// utils.js
function formatDate(date) { /* implementation */ }
function formatMoney(amount) { /* implementation */ }
function formatPhoneNumber(number) { /* implementation */ }

export default {
  formatDate,
  formatCurrency,
  formatPhoneNumber
}

When consumers import this module, even if they only need one function, they get the entire object:

// consumer.js
import utils from './utils';
utils.formatDate(new Date()); // Only using formatDate

In this scenario, the bundler cannot determine that formatCurrency and formatPhoneNumber are unused because the entire object is being imported as a single unit. This effectively breaks tree shaking, causing all functions to be included in the final bundle. It also makes it impossible for the consumer to only import formatDate function because the whole object is exported.

Namespace Re-exports

Another problematic pattern involves re-exporting namespace imports:

// constants.js
export const foo = 'foo';
export const bar = 'bar';

// namespaced-constants.js
import * as constants from './constants';
export { constants };

// consumer.js
import { constants } from './namespaced-constants';
console.log(constants.foo); // Only using foo

This pattern prevents tree shaking because the bundler cannot analyze which properties of the re-exported namespace are actually used by consumers. Both foo and bar will be included in the final bundle even though only foo is used.

React Component Libraries

This issue is particularly prevalent in React component libraries:

// components.js
const Button = () => { /* implementation */ }
const Input = () => { /* implementation */ }
const Select = () => { /* implementation */ }

export default {
  Button,
  Input,
  Select
}

When a consumer only needs one component, they still receive the entire library:

// App.js
import Components from './components';
function App() {
  return <Components.Button />; // Only using Button
}

Enabling Tree Shaking with Named Exports

Named exports provide a great approach for library authors who want to enable effective tree shaking for their consumers.

Individual Named Exports

The most straightforward pattern uses individual named exports:

// utils.js
export function formatDate(date) { /* implementation */ }
export function formatCurrency(amount) { /* implementation */ }
export function formatPhoneNumber(number) { /* implementation */ }

Consumers can then import only what they need:

// consumer.js
import { formatDate } from './utils';
formatDate(new Date());

With this approach, bundlers can now analyze the import statements and determine that only formatDate is used and avoid bundling the unused functions.

Effective Re-exports

When aggregating exports from multiple files, using the export * syntax provides better tree shaking than re-exporting namespace objects:

// constants/index.js
export * from './dateConstants';
export * from './currencyConstants';
export * from './validationConstants';

// consumer.js
import { isoDateFormatter } from './constants';

This pattern allows bundlers to trace imports through multiple modules and include only the necessary code.

Component Library Example

For React component libraries, named exports provide superior tree shaking:

// components.js
export const Button = () => { /* implementation */ }
export const Input = () => { /* implementation */ }
export const Select = () => { /* implementation */ }

// App.js
import { Button } from './components';
function App() {
  return <Button />;
}

Or when needing to combine multiple exports into single re-exporting module use export * format:

// index.js
export * from "./buttons";
export * from "./inputs";
export * from "./select";

Modern bundlers like webpack and rollup can easily determine that only the Button component is being used and exclude Input and Select from the final bundle.

Practical Impact on Bundle Size

The practical impact of these differences can be substantial in real-world applications. For example, a UI library with 50 components might be 500KB in total size. With proper tree shaking using named exports, an application that only uses 5 of those components might include just 50KB of code. Without tree shaking due to default exports, the entire 500KB library would be included.

Key Takeaways

Use named exports for all public API components to enable effective tree shaking
Avoid exporting objects with multiple properties as default exports
When aggregating exports from multiple files, use export * or individual named exports rather than namespace objects
Consider adding ESLint rules to enforce these patterns across your codebase
When using export default make sure to export from different modules and not re-export from a single one. If you do need to re-export from single one, only do export { default as Name}

Final Thoughts

The choice between default and named exports is not merely stylistic, it has significant implications for the performance of applications that consume your library. Default exports, particularly when used to export multiple functionalities as a single object, can prevent effective tree shaking. In contrast, named exports enable bundlers to precisely identify and include only the code that's actually used.

TLDR; Stick to named exports, they are clear winners when it comes to tree shaking capabilities.

Debouncing State in React

Eugene Yakhnenko — Tue, 17 Sep 2024 17:06:29 +0000

When building interactive components in react that depend on user input and specially keyboard input, it's common to end in a situation where an API call is made for every key pressed which leads to performance and ux issues. Too many unnecessary API calls are made and also it's not guaranteed that those calls are gonna return in order, so the results might not even be for the last searched value. A way to solve this problem is to debounce the user input which is what this article is gonna explore.

What is debouncing?

Debouncing ensures that a value is updated or a function is called only after a certain amount of time has passed since the last function call. The debounced value "lags" behind and is updated less frequently but it guarantees to get the latest value at the end.

Is useDeferredValue debouncing?

No, useDeferredValue is not the same as debouncing. While both useDeferredValue and debouncing help to manage updates efficiently and improve performance, they serve different purposes and work in distinct ways.

The purpose of useDeferredValue is to defer a low-priority update so that higher-priority updates (such as visual UI updates) can be processed first. It allows React to prioritize rendering more critical parts of the UI, improving responsiveness, especially in cases where there are complex or expensive computations happening in the background.

Unlike debouncing, it doesn’t require choosing any fixed delay. If the user’s device is fast (e.g. powerful laptop), the deferred re-render would happen almost immediately and wouldn’t be noticeable. If the user’s device is slow, the list would “lag behind” the input proportionally to how slow the device is.

source

Debouncing with lodash _.debounce

The _.debounce creates a debounced function that delays invoking func until after wait milliseconds have elapsed since the last time the debounced function was invoked.
Using lodash’s debounce combined with useMemo is a good choice especially if lodash is already part of your project (stay tuned for a feature article exploring this combination)

Custom useDebouncedValue hook

This hook takes a value and a delay, and it returns the debounced version of that value. If the value changes, the hook will wait for the specified delay before updating the debounced value. If the value changes again within the delay period, the timer resets, and the value is debounced once more.

Here’s how you can implement it:

import { useEffect, useRef, useState } from "react";

/**
 * Hook that provides a debounced state value and a setter function.
 * The state value only updates after the specified delay has passed without further changes.
 */
export function useDebouncedState<T>(initial: T, timeInMs: number = 250) {
  const [value, setValue] = useState(initial);
  const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
  const lastValue = useRef<T>(initial);

  const setDebouncedValue = (newValue: T) => {
    if (timeoutRef.current) {
      clearTimeout(timeoutRef.current);
    }

    timeoutRef.current = setTimeout(() => {
      if (lastValue.current !== newValue) {
        lastValue.current = newValue;
        setValue(newValue);
      }
    }, timeInMs);
  };

  useEffect(() => {
    return () => {
      if (timeoutRef.current) {
        clearTimeout(timeoutRef.current);
      }
    };
  }, []);

  return [value, setDebouncedValue] as const;
}

How It Works

State Management: The hook uses useState to store the debounced value. Initially, it’s set to the passed-in value.
Effect Hook: Inside useEffect, a setTimeout is triggered, which will update the debouncedValue after the specified delay (in milliseconds).
Cleanup: The return function in useEffect clears the timeout when either the value or the delay changes. This ensures that no outdated updates are applied, preventing memory leaks and keeping the debounce behavior stable.

Usage Example

Imagine you’re building a search bar that triggers an API request on every user input. To avoid making too many unnecessary requests while the user types, you can debounce the search term like this:

import { useDebouncedState } from "@/hooks/use-debounce";
import { useEffect } from "react";

export const Books = () => {
  const [search, setSearch] = useDebouncedState("");

  useEffect(() => {
    console.log(search);
  }, [search]);

  return (
    <input type="text" onInput={(e) => setSearch(e.currentTarget.value)} />
  );
};

(note: it’s possible to use onChange instead of onInput but it does require for the user to focus out of the input to be triggered which in case of an autocomplete, this might not be desired)

useDebouncedState hook has been designed in a way that it can be a “drop in” replacement for “useState” hook when throttling is required, so if you ever need debouncing I hope this article got you inspired and covered!
If you ever needed to debounce in the past, what was your solution at that time? Leave a comment!

Silent Breaking Changes: A Developer’s Guide to Identifying Hidden Bugs

Eugene Yakhnenko — Wed, 20 Dec 2023 05:57:36 +0000

Here's something that's kept me up at night more than once in my career: you push a seemingly harmless change, tests pass green, code reviews look good, and then three days later you're in a war room trying to figure out why a microservice stopped responding. Welcome to the world of silent breaking changes.

What Are Silent Breaking Changes?

A silent breaking change is a backward-incompatible change that doesn't immediately scream at you through compilation errors or failing tests. Instead, it lurks in the shadows, only revealing itself through subtle runtime bugs, weird production behavior, or angry customer reports days (or weeks) after deployment.

They're "silent" because:

Your code still compiles and builds successfully
Automated tests do not catch the changed behavior
Only specific consumers or edge cases are affected
The impact can surface long after deployment

Three General Categories

Before we dive into where these issues hide, it helps to understand the fundamental types of silent breaking changes. Most fall into one of these three categories:

1. Algorithmic Changes

Modifying the underlying logic or implementation without updating documentation, tests, or properly communicating the change. The method signature stays the same, but the way it computes results changes.

Example: Your calculateShippingCost() function used to round prices up to the nearest dollar, but you "improved" it to use standard rounding (nearest). Suddenly, customers who budgeted for $15 shipping are getting charged $14, and your accounting system that expected whole numbers is confused.

2. Behavioral Changes

Changes in input/output expectations, error handling, or side effects that produce undesired behavior. This includes changes to return value semantics, validation rules, or when exceptions are thrown.

Example: Your authentication API used to throw a 405 Method Not Allowed for invalid credentials, and your tests only checked that an error was thrown. You switched to throwing a 401 Unauthorized to be more "RESTful." Now, client apps that specifically checked for a 405 code break, even though your tests still pass, because they didn't verify the exact error code.

3. Side Effect Changes

Modifications that impact global state, interactions with other systems, resource usage, dependencies, or introduce race conditions. These are particularly insidious because they affect things outside the immediate function call.

Example: You optimize a data processing function to use async batch writes instead of synchronous single writes. The function still returns success, but now there's a delay before data appears in the database. Processes that immediately query for the data start failing intermittently.

Now let's look at where these categories manifest across different layers of your stack.

Where Silent Breaking Changes Hide

Silent breaking changes can lurk in any layer of your stack. Here are the most common culprits:

1. API and Interface Changes

Even when schemas appear unchanged, APIs can break consumers in surprising ways:

Semantic shifts: A field that used to mean "internal" or "external" suddenly gains new implications that require different client behavior
Default behavior changes: Switching from "replace entire list" to "merge" semantics on an update endpoint
Error model changes: Altering HTTP status codes or error body formats breaks downstream error handling
Optional → required fields: Making previously optional fields required causes existing clients to fail validation
Ordering assumptions: Changing default sort order, pagination, or filtering behavior
Stricter validation: Tightening rules to disallow characters that were previously accepted

2. Database Schema Evolution

Database changes are classic sources of silent breakage:

Type changes: Converting an int to varchar or reinterpreting a status column's meaning
Renamed or dropped columns: Queries may work initially through ORM caching, then fail under specific conditions
New constraints: Adding NOT NULL, unique, or foreign key constraints without aligning application code first
"Big bang" migrations: Attempting to change schema and code simultaneously

The industry-standard pattern to avoid this is expand-migrate-contract (also called parallel change):

Expand: Add new columns/tables alongside old ones
Migrate: Dual-write, backfill data, gradually move reads to new schema
Contract: Remove old schema only after verifying no dependencies remain

This ensures backward compatibility at every step and makes rollbacks possible.

3. Dependency Updates

This one's particularly insidious. Research has found that roughly one-third of libraries claiming to follow semantic versioning introduced breaking changes in minor versions. For npm, studies running 75,913 test runs across 4,616 packages found at least 263 breaking changes from supposedly non-breaking dependency updates.
I've seen this many times myself when bumping dependencies led to unexpected runtime errors in production, despite all tests passing. Or build failing, which is not silent, but still surprising when you expected a patch update to be safe.

Common patterns:

Behavioral changes: Same method signature, different behavior
ABI incompatibility: Binary layout or calling convention changes in C++/C libraries causing crashes
Default configuration changes: New defaults that alter runtime behavior
Platform shifts: Upgrading runtime versions (JDK, Python, Node) that change edge case behaviors

4. Microservices Contracts

In distributed systems, contracts between services are a fertile ground for silent breakage:

Provider shape changes: Adding/removing fields or changing enum semantics
RPC drift: Tightly coupled gRPC/IDL systems where stubs are regenerated but consumer code isn't updated
Event/message evolution: Changing message formats in queues without ensuring all consumers handle both versions
Side-effect changes: Altering timeout behavior, retry logic, or cascading calls

This is exactly why Consumer-Driven Contract testing (CDC) exists-to let consumers define their expectations and validate providers against them.

5. Machine Learning Models

ML introduces a newer dimension of silent breaking changes that's often overlooked:

A new model might have higher overall accuracy but introduce new errors in places where the old model was correct. If downstream systems were tuned around the old model's behavior, they can start failing unexpectedly.

Researchers formalize this with metrics like:

Backward Trust Compatibility (BTC): Percentage of previously correct predictions that remain correct
Backward Error Compatibility (BEC): Fraction of new model's errors that overlap with old model's errors

High accuracy but low BTC/BEC is a silent breaking change for downstream systems that depend on your model.

6. Configuration and Feature Flags

Operational changes can induce silent breakage without touching code:

Default flag flips: Changing feature flag values that alter validation or filtering logic
Rollout policy changes: Routing traffic to new implementations without behavior parity
Gateway configuration: New rate limits, timeout settings, or routing rules

These are especially tricky because nothing about schemas, APIs, or binaries changes-only runtime behavior shifts.

How to Catch Silent Breaking Changes

1. Static Diff-Based Checks

Your first line of defense is comparing interfaces and schemas between versions:

For REST/OpenAPI:

Use tools like oasdiff to compare OpenAPI definitions and classify changes by severity
Run oasdiff breaking in CI to fail builds on breaking changes
Tools like Optic and Postman templates can enforce semantic diffs in your pipeline

For Protobuf/gRPC:

Use buf breaking to ensure new .proto definitions remain compatible
Integrate with CI systems (GitHub Actions, GitLab, CircleCI) to catch issues in PRs

Language-specific checkers:

Go: Tools like Modver diff modules and suggest version bumps
Kotlin/Java: Binary compatibility checkers compare public APIs between releases

These catch syntactic changes, but behavioral changes require testing.

2. Consumer-Driven Contract Testing

CDC tools like Pact help ensure providers stay compatible with consumer expectations:

Consumers write tests using a mock provider and generate a contract file
Providers verify their implementation satisfies all published contracts
If providers break any consumer's contract, CI fails

This excels at catching silent breaking changes where the schema technically allows change, but consumers depend on specific behaviors.

3. Regression and Integration Testing

Maintain regression suites that include:

Critical use cases and negative paths
Tests for data shape changes (database/schema)
Integration points between services
Dependency update validation

One powerful technique: run your dependent packages' test suites across all minor/patch versions of dependencies. This is how researchers discovered those 263 breaking changes in npm. They ran tests and flagged when they went from passing to failing.

4. Runtime Monitoring

Not all silent breaking changes can be caught pre-production. Mature teams use:

API error monitoring: Watch for spikes in 4xx/5xx rates by endpoint and client version
Business KPI tracking: Monitor conversion rates, abandonment, and other metrics aligned to releases
Traffic shadowing: Route copies of production traffic to new versions and compare responses
Canary deployments: Roll out to small percentages and watch for anomalies

For ML models specifically, measure BTC and BEC alongside accuracy to detect behavioral breaking changes.

5. The Human Element

Don't underestimate thorough code reviews with explicit compatibility checklists:

Does this change remove/rename any public API or field?
Does it alter semantics, defaults, or error behavior?
Are there documented consumers relying on the old contract?
Have we tested with real consumer versions?

Prevention: Building Compatibility Into Your Process

Design-Time Compatibility Rules

Define explicit rules for what's allowed within a major version:

Generally safe (non-breaking):

Adding new optional fields or endpoints
Adding enum values clients can ignore
Adding optional query parameters

Forbidden (breaking within major version):

Removing or renaming fields, methods, or endpoints
Changing field types or wire formats
Moving fields into different structures
Making optional fields required
Tightening validation that rejects previously valid inputs

Document hidden contracts like ordering, error codes, and default behaviors that clients may depend on.

Versioning Strategies

While Semantic Versioning (SemVer) is popular, you need internal definitions that reflect reality:

MAJOR: Incompatible API changes
MINOR: Backward-compatible new features
PATCH: Backward-compatible bug fixes

Note: Some bug fixes alter behavior that clients depend on. These might need to be treated as breaking.

For microservices and APIs:

Use URI or header-based versioning (/v1/..., /v2/...)
Provide long deprecation windows
Support parallel versions during migration

CI/CD Guardrails

Automate compatibility checks in your pipeline:

Run oasdiff breaking on OpenAPI specs
Run buf breaking on protobuf definitions
Integrate CDC tests for critical microservice interactions
Run regression tests with old client versions
Execute dependent package test suites against new versions

These should be release blockers, not warnings.

Documentation and Communication

Release notes matter:

Maintain explicit backward-incompatible sections
Document required actions for integrators
Provide migration guides

Deprecation policies:

Mark deprecated features clearly with timelines
Provide tooling (lints, logs, warnings) to detect usage
Give teams time to migrate before removal

Release candidate channels:

Expose changes early so integrators can test
Platforms like Shopify's REST Admin API do this well

Organizational Patterns

Clear ownership: Assign accountability for APIs and schemas
Architecture reviews: Review high-risk changes before implementation
Compatibility SLOs: Make compatibility measurable (e.g., target BTC/BEC for ML models)
Cultural values: Make "no silent breaking changes" part of engineering principles

When Silent Breaking Changes Escape

Even with strong prevention, some will reach production. Here's how to respond:

1. Detection and Triage

Correlate anomalies with recent changes
Segment by client version or environment
Reproduce using captured logs or traffic replay
Run post-hoc API diffs to pinpoint contract divergence

2. Containment

Roll back the deployment or flip feature flags
Use circuit breakers to isolate failures
Leverage canary/blue-green deployments to limit blast radius

3. Remediation

Fix or provide compatibility shims
Notify impacted consumers with migration guides
If SemVer promises were violated, treat it as a bug and release a fix

4. Learn and Improve

Add regression tests for the broken scenario
Strengthen contract tests or schema diffing
Update compatibility guidelines and review checklists

A Practical Checklist

Here's what I recommend to teams:

Define what "breaking" means:

Document per domain (APIs, DB, libraries, ML)
Include behavioral aspects, not just types
Make it accessible to all engineers

Build CI/CD guardrails:

API/schema diff tools on every change
CDC tests for critical interactions
Language-specific compatibility checkers

Apply safe evolution patterns:

Expand-migrate-contract for schema changes
Additive-only API design
Measure BTC/BEC for ML models

Monitor production:

Error rates by endpoint and client version
Business KPI dashboards aligned to releases
Canary deployments with automatic rollback

Foster the right culture:

Make compatibility a first-class concern
Include compatibility reviews in design processes
Reward teams that maintain strong compatibility

Final Thoughts

Silent breaking changes are fundamentally about mismatched expectations between components over time. The more widely consumed your interfaces, the more costly these mismatches become.

I've learned (sometimes the hard way) that treating compatibility as a managed engineering discipline rather than an afterthought is one of the highest-leverage investments you can make. It's not just about avoiding incidents: it's about maintaining trust with the teams and customers who depend on your systems.

The good news? You don't have to implement everything at once. Start with the layer that's causing you the most pain, add some automated checks, and build from there. Your future self (and your on-call rotation) will thank you.

GraphQL in Your Ember App with Glimmer Apollo

Eugene Yakhnenko — Tue, 05 Dec 2023 20:34:36 +0000

Introduction:

Ember.js, a robust JavaScript framework for building ambitious web applications, has gained popularity for its convention over configuration approach and developer-friendly features. To enhance data fetching and management in Ember applications, integrating GraphQL is a powerful choice. In this article, we'll explore how to unleash the capabilities of GraphQL in your Ember app using Glimmer Apollo.

1. Starting new Ember Project

We can create a new Ember project by using ember-cli. If you don't have it already installed, its as simple as

yarn global add ember-cli
or 
npm install -g ember-cli

Once you have ember-cli installed, to create a new Ember project:

ember new my-project-name
cd my-project-name

2. Adding Typescript Support (optional)

This step is not strictly necessary but without it, you won't get the benefit of type checking on your queries.
Installing ember-cli-typescript allows to write ember component using typescript instead of javascript.

yarn add --dev ember-cli-typescript

3. Installing Glimmer Apollo and Dependencies

We will be using Glimmer Apollo to integrate the Apollo Client. To install the necessary dependencies:

yarn add -dev glimmer-apollo @apollo/client graphql

Thats it, all the Glimmer Apollo dependencies are installed

4. Configuring Apollo Client

To be able to use Apollo Client, we need to configure it and create an instance of the client first.
Create a script file in your project, in this example we are gonna be using /app/config/apollo.ts

// Import the setClient function from the "glimmer-apollo" package.
import { setClient } from "glimmer-apollo";

// Import necessary Apollo Client modules.
import {
  ApolloClient,
  InMemoryCache,
  createHttpLink,
} from "@apollo/client/core";

// Define a function that sets up and configures the Apollo Client.
export default function setupApolloClient(context: object): void {
  // Create an HTTP link that points to the GraphQL server.
  const httpLink = createHttpLink({
    uri: "https://graphqlzero.almansi.me/api",
  });

  // Create an in-memory cache for Apollo Client to store data.
  const cache = new InMemoryCache();

  // Create an instance of Apollo Client with the configured link and cache.
  const apolloClient = new ApolloClient({
    link: httpLink,
    cache,
  });

  // Set the Apollo Client instance on the provided context object.
  setClient(context, apolloClient);
}

The previous code imports the necessary modules from the "apollo/client/core" package, including the ApolloClient class, InMemoryCache, and createHttpLink function. The setupApolloClient function is then defined, which creates an HTTP link pointing to a GraphQL server (in this case, "https://graphqlzero.almansi.me/api" which is a mock graphql api), an in-memory cache for storing Apollo Client data, and finally, an instance of the Apollo Client with the configured link and cache. The created Apollo Client instance is then set on the provided context object using the setClient function from the "glimmer-apollo" package.

Remember to update the createHttpLink uri parameter to the url of your Graphql api

Finally, to instantiate the previous initialization code, we can use Embers Instance Initializer.

Application instance initializers are run as an application instance is loaded. They provide a way to configure the initial state of your application, as well as to set up dependency injections that are local to the application instance.

To create an Instance Initializer for our Apollo Client configuration you can execute:

ember generate instance-initializer apollo

Or simple create a file /app/instance-initializer/apollo.ts

import setupApolloClient from "../config/apollo";

export default {
  initialize: setupApolloClient,
};

We set the setupApolloClient function exported from previous step so that it is run once the application instance is loaded.

And thats it, Glimmer Apollo is ready to be used!

4. Adding 1st Graphql Query

Lets create our first Graphql query and used in a component. We can do so by creating the following files.

app
└── components
    └── first-query
        ├── index.hbs
        ├── index.ts
        └── resources.ts

4.1 Defining Glimmer Apolllo Query in resources.ts

The api we are using for this tutorial has quit a few queries defined, you can explore the schema here: https://graphqlzero.almansi.me/api

For this tutorial we are gonna be fetching the a user name by his id. We can achieve that with the following query

export function useUserByIdQuery<T extends UseQuery<any, any>>(
  ctx: Object,
  args?: T["args"]
): T["return"] {
  return useQuery(ctx, () => [
    gql`
      query UserById($id: ID!) {
        user(id: $id) {
          id
          name
        }
      }
    `,
    args ? args() : {},
  ]);
}

There are three important parts to this code.

The query section query UserById($id: ID!) { where we define the query we want to execute.

The UseQuery<any, any> defines the type of the arguments the query receives and the type of data the query returns. For now its <any, any> but we will fix it in the step 5.

4.2 Using the Glimmer Apollo Query in our component class

import Component from "@glimmer/component";
import { useUserByIdQuery } from "./resources";

export default class FirstQuery extends Component {
  query = useUserByIdQuery(this, () => ({
    variables: {
      id: 1,
    },
  }));
}

The useUserByIdQuery takes in two arguments.
First is the context for the execution of the query. Usually this will be the instance of the component in which the query is used. Its required so that Glimmer Apollo can cleanup properly the resources after the component is destroyed.

Second argument is a list of arguments to pass to the Apollo Client to modify how the query is executed. More info here

We need to pass the Id of the user we want to fetch. We can do that by passing it as the variables property of the arguments

4.3 Fetching the data in the template

{{#if this.query.loading}}
  loading...
{{else if this.query.error}}
  {{this.query.error}}
{{else if this.query.data}}
  {{this.query.data.user.name}}
{{/if}}

When we access the loading or data properties of the query, Glimmer Apollo will execute the query and fetch the data making it available in the data property. And if there was an error it will set the error property of the query.

Finally, to view this in action, use the <FirstQuery /> component.

One thing to note is that the variables passed to the query are reactive. If the variable is a tracked variable, when its value changes the query will execute again.

import Component from "@glimmer/component";
import { tracked } from "@glimmer/tracking";
import { useUserByIdQuery } from "./resources";

export default class FirstQuery extends Component {
  @tracked userId = 1;

  query = useUserByIdQuery(this, () => ({
    variables: {
      id: this.userId,
    },
  }));
}

If we change the value of this.userId = 2 the query will execute again and fetch the data for user with Id 2.

5. Adding Graphql Code Generator (optional)

GraphQL Code Generator is a plugin-based tool that helps you get the best out of your GraphQL stack.

From back-end to front-end, GraphQL Code Generator automates the generation of:

Typed Queries, Mutations and, Subscriptions for React, Vue, Angular, Next.js, Svelte, Ember whether you are using Apollo Client, URQL or, React Query.
Typed GraphQL resolvers, for any Node.js (GraphQL Yoga, GraphQL Modules, TypeGraphQL or Apollo) or Java GraphQL server.

To add graphql-codegen to our project:

yarn add --dev @graphql-codegen/cli @graphql-codegen/typescript @graphql-codegen/typescript-operations @graphql-codegen/named-operations-object

After the dependency is installed we need to initiate the code generator. This can be done by executing:

Add the following config in the root of the project codegen.yml

overwrite: true
hooks:
  afterAllFileWrite:
    - prettier --write
schema: [
  'https://graphqlzero.almansi.me/api',
]
documents: 'app/**/*.{graphql,ts}'
generates:
  types/graphqlzero-api/index.d.ts::
    plugins:
      - typescript
      - typescript-operations
  app/utils/gql-operations.ts:
    plugins:
      - named-operations-object
    config:
      identifierName: namedOperations
  tests/mocks/schema.graphql:
    plugins:
      - schema-ast

The key properties of this config are

schema: the url of the graphql-api schema
documents: the list of files that should be scanned for graphql queries
plugins: sets the plugins used for the code generation

Now you can generate the typescript types for your queries. And also a list of the queries and mutations by name which comes in handy for mock testing. To do that, execute graphql-codegen by passing the config file:

graphql-codegen --config codegen.yml

You can also make it more accessible by adding this line in the scripts of pacakge.json

 "codegen": "graphql-codegen --config codegen.yml"

After the graphql types are generated, we can now update our query to include the proper types. Lets revisit how the resources.ts file looks like for our FirstQuery component:

import { gql, useQuery } from "glimmer-apollo";
import type { UseQuery } from "glimmer-apollo";
import type { UserByIdQuery, UserByIdQueryVariables } from "graphqlzero-api";

export function useUserByIdQuery<T extends UseQuery<UserByIdQuery, UserByIdQueryVariables>>(
  ctx: Object,
  args?: T["args"]
): T["return"] {
  return useQuery(ctx, () => [
    gql`
      query UserById($id: ID!) {
        user(id: $id) {
          id
          name
        }
      }
    `,
    args ? args() : {},
  ]);
}

The main difference is now we can use the proper type for our UseQuery UseQuery<UserByIdQuery, UserByIdQueryVariables>

Conclusion

By integrating Glimmer Apollo into your Ember application, you can seamlessly incorporate GraphQL for efficient data fetching and management. This powerful combination enhances your development experience, providing flexibility and performance in handling complex data requirements.

Copy of this project is available in this repository

DEV Community: Eugene Yakhnenko

Why I Built an Identity Provider in Go and SQLite

The Itch: Finding the Right Lightweight IdP

The Antidote: Zero-Ceremony Architecture

Flexibility Over Dogma: Solving the Passkey Trap

The "Deliberately Un-clever" Architecture & The AI Accelerator

The Scale Ceiling (And Why It Doesn't Matter)

Conclusion

Links

The Lightweight JavaScript Framework Renaissance of 2026

Best JavaScript Frameworks in 2026: For AI and Humans

The New Evaluation Criteria

The Heavy Framework Tax

The Light Library Renaissance

Arrow.js

Kasper.js

Others Worth Knowing

Comparison at a Glance

How to Choose

Conclusion

Building a JavaScript Framework (and Failing Twice at Reactivity)

The Part That Failed Twice

Coming Back to It

600 Tests Later

The Real Test Wasn't Tests

The Missing Piece: Documentation for AI

A Surprising Insight About AI

When Tests Stop Helping

What Actually Made the Framework Stable

The Unexpected Win

What I'd Do Differently

Where It Ended Up

Try it out!

We Had to Write Docs for AI: llms.txt Changed Everything

The Moment Things Broke

README Is Not Enough Anymore

The Solution: llms.txt

Reading the Docs + Source Code

The Iteration Loop

When It Finally Clicked

Two Types of Documentation

The Unexpected Payoff

Final Thought

Adding Attribute-Based Access Control to a Real-Time Collaborative App with OpenTDF

How This Project Started

Why OpenTDF

The Access Model

Building It with an AI Agent

How the Integration Works

ABAC as the Single Source of Truth

Policy Structure

The Sharing Workflow

Access Checks

WebSocket Enforcement

Listing Sketches from ABAC

What This Shows About ABAC

The Timeline

Key Takeaways

Try It

Kneel Before Zod!

Why Data Validation Matters in TypeScript

Compile-Time vs. Runtime-Time Gap

Solutions for TypeScript Data Validation

Type Guards and Assertion Functions

Zod as a Solution for TypeScript Validation

Pros of Zod

TypeScript-First Design

Schema-to-Type Inference

Comprehensive Schema Options

Handy Zod utility: validateSchemaOrThrow

More info at

Handling Tech Debt while Shipping Features

Why This Matters More Than You Think

First Things First: Not Everything is Urgent

Plan for the Unexpected (Because It Will Happen)

The Superman Strategy: Protecting Focus Time

Turn Fires Into Fireproofing

Protect Your Brain: Reduce Context Switching

The Missing Requirements Problem

Measure What Matters