Allons-y Studio

Introducing envoy: environment setup, handled

2026-03-26T00:00:00Z

Here's what nobody tells you about onboarding: the hardest part isn't the architecture docs, the branching strategy, or even getting the right access. It's .env.

Every project I've ever worked on starts the same way. Copy .env.example to .env. Open Notion, or 1Password, or a Slack thread from six months ago. Track down the values. Paste them in. Repeat. In a monorepo, this ritual scales badly — five packages, five .env.example files, five rounds of the same scavenger hunt. It's not hard work. It's just tedious work, and tedious work is the kind that gets skipped, done wrong, or turned into a half-finished onboarding doc that nobody updates.

I built envoy to eliminate it.

Let's be honest about what .env setup actually is: a key lookup exercise. You have a template (.env.example) that tells you what keys a project needs, and you have the real values stored somewhere on your machine or in your secrets manager. The only "work" involved is matching those two things together — and yet we do it manually, every time, for every project.

There are a few ways this tends to go wrong in practice.

The incomplete setup. A contributor clones the repo, misses a value in the .env.example, and spends the next hour debugging why a feature isn't working. The error message points nowhere near the actual problem.

The stale example file. Someone adds a new required key to the codebase and forgets to document it in .env.example. Now the example file lies. Every new contributor is set up to fail before they write a single line of code.

The monorepo multiplication problem. Package A needs DATABASE_URL. Package B needs API_KEY. Package C needs both plus three others. You're now maintaining five different .env files by hand and hoping none of them drift out of sync. In practice, they always drift.

The solution to all three is the same: treat .env setup as a deterministic process that can be automated, not a manual ritual that depends on tribal knowledge.

The premise is straightforward. You probably already have a ~/.env on your machine — or you will after using envoy for five minutes — with the real values: API keys, database URLs, tokens, secrets. The values that follow you from project to project.

envoy reads your .env.example as a template, pulls matching keys from ~/.env, and writes a complete .env file alongside it. Comments, blank lines, and keys you haven't defined yet all survive the process exactly as written.

yarn dlx @allons-y/envoy
# ✨ Created /your/project/.env

That's the whole thing. No config files, no network calls, no global state. Just a template and a source of truth, merged together.

Why ~/.env instead of a secrets manager? The short answer: zero dependencies. envoy works offline, doesn't require an account, and integrates with whatever secrets workflow you already have. Pull values from 1Password or Vault into ~/.env as a sync step — that's a separate concern and envoy doesn't try to own it.

Safe by default

envoy will never overwrite an existing .env without your permission. If a .env already exists, it skips that file and moves on. This is the behavior you want — running envoy repeatedly on an established project should be a no-op, not a destructive operation.

When you do want to overwrite — say, you've added keys and need to regenerate — pass --force:

yarn dlx @allons-y/envoy --force

Monorepo-aware

envoy recursively walks your project directory, finds every .env.example it can, and processes each one. It skips node_modules automatically. You don't have to tell it where your packages live or configure a list of paths — it just finds them.

# Finds and processes all of these:
# packages/api/.env.example
# packages/web/.env.example
# packages/workers/.env.example

Non-destructive key handling

If a key exists in .env.example but not in ~/.env, envoy falls back to the example value instead of dropping the key entirely. This matters: you don't want a missing global key to silently produce a broken .env. You want the key present with a placeholder, so the next person knows it needs a real value.

Preview before writing

Not sure what envoy is going to write? Run it with --dry-run first:

yarn dlx @allons-y/envoy --dry-run

You'll see a full diff of what would be created or changed — nothing touches the filesystem. This is especially useful the first time you run it on an existing monorepo.

This is the highest-value use case by a significant margin. Wire envoy into your project's postinstall script:

{
  "scripts": {
    "postinstall": "envoy"
  }
}

Now every contributor who clones the repo and runs npm install or yarn gets a populated .env automatically. No onboarding doc to write. No values to chase down in Slack. No "why doesn't this work" messages on day one.

If your package is published to npm, use pinst to strip the postinstall hook from your tarball. You don't want consumers running envoy when they install your library — only developers working on the project itself should trigger it.
{
  "scripts": {
    "postinstall": "envoy",
    "prepublishOnly": "pinst --disable",
    "postpublish": "pinst --enable"
  }
}

The practical effect: onboarding goes from "follow these twelve steps in the right order" to "clone the repo and run install." That's not a small improvement in developer experience — that's the difference between a smooth first day and a frustrated one.

If you're running Claude Desktop or Claude Code, envoy exposes a copy_env tool through an MCP server. The same options available in the CLI — --force, --dry-run, and a target path — are available directly from your AI tools.

# Start the MCP server
envoy --mcp

This means you can ask Claude to set up your environment as part of a broader workflow — scaffolding a new package, bootstrapping a project, or running a setup checklist — without breaking out to the terminal. The tool validates paths, respects the --force flag, and returns the same output you'd see from the CLI.

Practical example: You're scaffolding a new package in your monorepo. Claude creates the directory structure, writes the package.json and tsconfig.json, and calls copy_env to generate the .env — all in the same workflow, without manual steps between.

For envoy to do its job, you need a ~/.env with your real values. If you're starting from scratch, the pattern is simple: collect every key you use across all your projects and put the real values here.

# ~/.env

# Shared database
DATABASE_URL=postgresql://localhost:5432/dev

# API keys
STRIPE_SECRET_KEY=sk_test_...
OPENAI_API_KEY=sk-...
GITHUB_TOKEN=ghp_...

# Internal services
INTERNAL_API_BASE_URL=http://localhost:3001

If you're already using a secrets manager, the recommended pattern is to sync into ~/.env as part of your shell startup or a manual pull command. envoy reads whatever is there — it doesn't care how it got there.

Do

Add envoy to postinstall so environment setup happens automatically on npm install or yarn
Commit .env.example with sensible placeholder values — the fallback behavior depends on those placeholders being meaningful
Use --dry-run the first time you run envoy on an existing project
Keep ~/.env as your source of truth for shared values across projects
Use pinst if your package is published to npm

Don't

Don't commit real values to .env.example — that file belongs in source control; treat it like documentation, not secrets
Don't run envoy without --force expecting it to update an existing .env — safe-by-default means it won't
Don't rely on envoy to sync secrets from a remote source — that's a separate concern; handle it at the ~/.env layer
Don't use envoy as a replacement for proper secrets management in CI — it's a local developer tool, not a deployment pipeline

No installation required:

npx @allons-y/envoy --dry-run

The source is small, readable, and fully tested. Apache 2.0.

→ GitHub: github.com/castastrophe/envoy → npm: @allons-y/envoy

The best developer tooling solves problems so completely that you stop thinking about them. Environment setup is one of those problems — it's not interesting, it doesn't require expertise, and the only thing it produces (when done manually) is friction. envoy makes it automatic, repeatable, and boring in the best way possible.

Set up ~/.env once. Add envoy to postinstall. Clone any project. Run install. Done.

That's the goal: the setup ritual disappears, and you get straight to the work that matters.

Performance monitoring for web components

2025-11-23T00:00:00Z

Here's what nobody tells you about building web components: you can follow all the best practices, optimize your Shadow DOM, and keep your bundle sizes tiny, but if you're not measuring performance, you're flying blind. Sure, components perform well on your beefy MacBook Pro, but what about on a mid-range Android device over spotty 3G connection?

The good news? There's a browser API specifically designed for this. The User Timing API lets you drop performance markers directly into your component lifecycle and see exactly where time is being spent. No third-party libraries, no complex setup, just widely-available native browser capabilities that integrate beautifully with dev tools and Lighthouse.

This guide will walk you through instrumenting your web components with performance tracking that actually matters; measurements you can act on with insights into the user experience.

Performance isn't just about making things fast, it's about understanding where your components spend their time. These insights help you make informed decisions about where to spend your user's attention. Did that fancy animation you added slow down initial render? By how much? Is your component's first paint happening fast enough that users don't notice a delay? You won't know unless you track the data.

The web can be unforgiving. Users expect instant responses with limited attention to spare; every millisecond counts. Performance marks show up in your dev tools, giving you visibility into what's actually happening when your components hit the DOM.

Before we dive into implementation, let's talk about what the User Timing API actually does. It provides high-precision timestamps that are part of the browser's performance timeline, and it does this through two simple concepts: marks and measures.

Marks are timestamps you place at specific points in your code. Think of them as performance breadcrumbs—they tell you when something happened.

Measures calculate the elapsed time between two marks. They're the answer to "how long did that take?"

The beauty of this API is simplicity. No complex configuration or heavyweight monitoring solutions. You're just saying "mark this moment" and "measure from here to there."

When instrumenting web components, you want to capture the moments that matter most to users. Here's a few things you could be tracking:

Component registration: When the component is defined and added to the custom elements registry

DOM connection: When the component is first inserted into the document

First render: When the component completes its initial render and becomes visible

Upgrade time: The total time from registration to first render

These measurements tell you the complete story of your component's lifecycle performance. Let's look at how to implement this.

Setting up performance marks

The first step is identifying where to place your marks. For web components, there are natural lifecycle hooks that map perfectly to performance milestones.

When your component connects to the DOM, drop a mark:

connectedCallback() {
  performance.mark(`${this.localName}:connected`);

  // Trigger initial render
  this.render();
}

In this and following examples, this.localName represents a property on the web component that stores it's tag name, i.e., custom-button.

After your first render completes, drop another. You'll need to track whether this is the first render:

render() {
  // Your rendering logic here
  this.shadowRoot.innerHTML = `
    <button>Click me</button>
  `;

  // Mark first render complete
  if (!this._hasRendered) {
    this._hasRendered = true;
    performance.mark(`${this.localName}:first-render`);
  }
}

For component registration, you'll want to add a mark when you define the custom element:

customElements.define('my-component', MyComponent);
performance.mark('my-component:defined');

Creating meaningful measures

Now that you have marks in place, you can create measures that tell you how long critical paths are taking. The measure between connection and first render is especially valuable because it represents the user-facing initialization time:

render() {
  // Your rendering logic here
  this.shadowRoot.innerHTML = `
    <button>Click me</button>
  `;

  // Mark and measure first render
  if (!this._hasRendered) {
    this._hasRendered = true;
    performance.mark(`${this.localName}:first-render`);

    performance.measure(
      `${this.localName}:upgrade`,
      `${this.localName}:connected`,
      `${this.localName}:first-render`
    );
  }
}

Using consistent naming conventions

This is crucial: establish a naming convention and stick with it. I recommend using the component's tag name followed by a colon and the event name:

component-name:defined
component-name:connected
component-name:first-render
component-name:upgrade

This pattern makes it easy to filter and analyze your metrics later. When you're looking at DevTools with dozens of components on the page, clear naming saves you from the cognitive overhead of figuring out which measurement belongs to what.

Rather than duplicating this code across every component, there are a few optimization options you can use: create or add it to a base class or use a mixin. Both approaches give you performance tracking for free, once set up, but they serve different architectural needs.

Option 1: Base class

A base class works well when you want a standardized component foundation. You set it up once, and every component that extends it gets performance tracking ✨automagically✨.

export class PerformanceTrackedElement extends HTMLElement {
  constructor() {
    super();
    this.attachShadow({ mode: 'open' });
    this._hasRendered = false;
  }

  connectedCallback() {
    // Only mark the first connection
    if (!this.hasAttribute('data-perf-marked')) {
      performance.mark(`${this.localName}:connected`);
      this.setAttribute('data-perf-marked', '');
    }

    // Trigger initial render
    this.render();
  }

  _markFirstRender() {
    if (!this._hasRendered) {
      this._hasRendered = true;
      performance.mark(`${this.localName}:first-render`);

      // Measure the upgrade time
      performance.measure(
        `${this.localName}:upgrade`,
        `${this.localName}:connected`,
        `${this.localName}:first-render`
      );
    }
  }
}

Now any component can extend this base class:

export class MyButton extends PerformanceTrackedElement {
  render() {
    this.shadowRoot.innerHTML = `
      <style>
        button {
          padding: 0.5rem 1rem;
          border: none;
          border-radius: 4px;
          background: #007bff;
          color: white;
          cursor: pointer;
        }
      </style>
      <button>Click me</button>
    `;

    // Mark that first render is complete
    this._markFirstRender();
  }
}

Option 2: Mixin

If you already have a base class hierarchy or want more flexibility, a mixin lets you add performance tracking to any class without changing your inheritance chain. This is particularly useful when working with existing component libraries or when you need to compose multiple behaviors.

export const PerformanceTrackingMixin = (SuperClass) => {
  return class extends SuperClass {
    constructor() {
      super();
      this._hasRendered = false;
    }

    connectedCallback() {
      // Only mark the first connection
      if (!this.hasAttribute('data-perf-marked')) {
        performance.mark(`${this.localName}:connected`);
        this.setAttribute('data-perf-marked', '');
      }

      // Call parent connectedCallback if it exists
      if (super.connectedCallback) {
        super.connectedCallback();
      }
    }

    _markFirstRender() {
      if (!this._hasRendered) {
        this._hasRendered = true;
        performance.mark(`${this.localName}:first-render`);

        // Measure the upgrade time
        performance.measure(
          `${this.localName}:upgrade`,
          `${this.localName}:connected`,
          `${this.localName}:first-render`
        );
      }
    }

    disconnectedCallback() {
      // Clean up performance marks
      performance.clearMarks(`${this.localName}:connected`);
      performance.clearMarks(`${this.localName}:first-render`);
      performance.clearMeasures(`${this.localName}:upgrade`);

      // Call parent disconnectedCallback if it exists
      if (super.disconnectedCallback) {
        super.disconnectedCallback();
      }
    }
  };
};

Apply the mixin to any component class:

// Apply to HTMLElement
export class MyButton extends PerformanceTrackingMixin(HTMLElement) {
  constructor() {
    super();
    this.attachShadow({ mode: 'open' });
  }

  connectedCallback() {
    super.connectedCallback();
    this.render();
  }

  render() {
    this.shadowRoot.innerHTML = `
      <style>
        button {
          padding: 0.5rem 1rem;
          border: none;
          border-radius: 4px;
          background: #007bff;
          color: white;
          cursor: pointer;
        }
      </style>
      <button>Click me</button>
    `;

    this._markFirstRender();
  }
}

Or apply the mixin to your existing base class:

// Or apply to your existing base class
export class MyCard extends PerformanceTrackingMixin(MyBaseElement) {
  // Your implementation
}

Composing multiple mixins

The beauty of mixins is that you can compose multiple behaviors. If you have other mixins for logging, analytics, or error handling, you can stack them:

export class MyComponent extends
  PerformanceTrackingMixin(
    LoggingMixin(
      AnalyticsMixin(HTMLElement)
    )
  ) {
  // Your component with all three behaviors
}

Choosing between base class and mixin

Use a base class when:

You're starting fresh with a new component library
You want a single, consistent foundation for all components
You control the entire inheritance chain
You prefer a simpler mental model

Use a mixin when:

You need to add performance tracking to existing components
You're working with multiple base classes
You want to compose multiple behaviors
You need flexibility to opt-in per component

Once you've instrumented your components, you need to actually look at the data. There are several ways to do this, each useful for different purposes.

Using the Performance Timeline

You can retrieve all your marks and measures programmatically:

// Get all marks
const marks = performance.getEntriesByType('mark');

// Get all measures
const measures = performance.getEntriesByType('measure');

// Get entries for a specific component
const buttonMeasures = performance.getEntriesByName('my-button:upgrade');

Viewing in DevTools

Performance marks appear in the Performance tab, where you can see them visualized on a timeline alongside other browser events. This is incredibly useful for understanding how your component initialization fits into the overall page load sequence.

To view your marks:

Open Chrome DevTools
Go to the Performance tab
Record a new profile
Look for your marks in the User Timing section

Integration with Lighthouse

Lighthouse extracts User Timing data and displays it in your reports. This means your custom performance marks show up automatically in your Lighthouse audits without any additional configuration.

Performance marks are only useful if you act on them. For production monitoring, you'll want to send these metrics to your analytics platform so you can track performance over time and across different user segments.

_markFirstRender() {
  if (!this._hasRendered) {
    this._hasRendered = true;
    performance.mark(`${this.localName}:first-render`);

    const measure = performance.measure(
      `${this.localName}:upgrade`,
      `${this.localName}:connected`,
      `${this.localName}:first-render`
    );

    // Report to your analytics platform
    if (window.analytics) {
      window.analytics.track('Component Performance', {
        component: this.localName,
        duration: measure.duration,
        userAgent: navigator.userAgent
      });
    }
  }
}

Conditional instrumentation

You probably don't want performance overhead in production unless you're actively monitoring. Use environment flags to control when instrumentation runs. This works equally well with both the base class and mixin approaches:

With a base class:

export class PerformanceTrackedElement extends HTMLElement {
  constructor() {
    super();
    this.attachShadow({ mode: 'open' });
    this._hasRendered = false;
  }

  connectedCallback() {
    if (this.shouldTrackPerformance() && !this.hasAttribute('data-perf-marked')) {
      performance.mark(`${this.localName}:connected`);
      this.setAttribute('data-perf-marked', '');
    }
    this.render();
  }

  shouldTrackPerformance() {
    // Only track in development or for a sample of production users
    const isDev = !window.location.hostname.includes('production.com');
    return isDev || Math.random() < 0.1;
  }

  _markFirstRender() {
    if (!this._hasRendered && this.shouldTrackPerformance()) {
      this._hasRendered = true;
      performance.mark(`${this.localName}:first-render`);

      performance.measure(
        `${this.localName}:upgrade`,
        `${this.localName}:connected`,
        `${this.localName}:first-render`
      );
    }
  }
}

With a mixin:

export const PerformanceTrackingMixin = (SuperClass) => {
  return class extends SuperClass {
    constructor() {
      super();
      this._hasRendered = false;
    }

    connectedCallback() {
      if (this.shouldTrackPerformance() && !this.hasAttribute('data-perf-marked')) {
        performance.mark(`${this.localName}:connected`);
        this.setAttribute('data-perf-marked', '');
      }

      if (super.connectedCallback) {
        super.connectedCallback();
      }
    }

    shouldTrackPerformance() {
      const isDev = !window.location.hostname.includes('production.com');
      return isDev || Math.random() < 0.1;
    }

    _markFirstRender() {
      if (!this._hasRendered && this.shouldTrackPerformance()) {
        this._hasRendered = true;
        performance.mark(`${this.localName}:first-render`);

        performance.measure(
          `${this.localName}:upgrade`,
          `${this.localName}:connected`,
          `${this.localName}:first-render`
        );
      }
    }

    disconnectedCallback() {
      performance.clearMarks(`${this.localName}:connected`);
      performance.clearMarks(`${this.localName}:first-render`);
      performance.clearMeasures(`${this.localName}:upgrade`);

      if (super.disconnectedCallback) {
        super.disconnectedCallback();
      }
    }
  };
};

Measuring nested component trees

When you have components that render other components, you can track the entire composition tree:

performance.mark('page-header:composition-start');

// Render happens here with nested components

performance.mark('page-header:composition-end');

performance.measure(
  'page-header:full-composition',
  'page-header:composition-start',
  'page-header:composition-end'
);

Tracking lazy-loaded components

For components loaded dynamically, track the time from import to render:

performance.mark('my-component:import-start');

const { MyComponent } = await import('./my-component.js');

performance.mark('my-component:import-end');

performance.measure(
  'my-component:lazy-load',
  'my-component:import-start',
  'my-component:import-end'
);

customElements.define('my-component', MyComponent);

Performance entries accumulate in the browser's performance buffer. Use clearMarks and clearMeasures to clean up once data is no longer needed.

// Clear specific marks
performance.clearMarks('my-component:connected');
performance.clearMarks('my-component:first-render');

// Clear specific measures
performance.clearMeasures('my-component:upgrade');

// Or clear all marks and measures
performance.clearMarks();
performance.clearMeasures();

For components that might be added and removed from the DOM multiple times, clear marks in the disconnectedCallback:

disconnectedCallback() {
  performance.clearMarks(`${this.localName}:connected`);
  performance.clearMarks(`${this.localName}:first-render`);
  performance.clearMeasures(`${this.localName}:upgrade`);
}

Not everything needs a performance mark. Focus on the moments that impact user experience:

Measure these

Initial connection to DOM: Users are waiting for the component to appear
First render complete: The component is now visible and interactive
Component upgrade time: Total time from definition to first paint
Critical async operations: Data fetching, heavy computations
User interactions: Click handlers, form submissions, animations

Skip these

Every update cycle: Too noisy, adds overhead
Trivial getters and setters: Not worth the measurement cost
Internal helper methods: Focus on user-facing milestones
Style recalculations: The browser already tracks these

Let's put this all together with a complete example of a button component that tracks its performance:

export class PerformanceTrackedButton extends HTMLElement {
  constructor() {
    super();
    this.attachShadow({ mode: 'open' });
    this._hasRendered = false;
  }

  static get observedAttributes() {
    return ['label', 'disabled'];
  }

  connectedCallback() {
    if (!this.hasAttribute('data-perf-marked')) {
      performance.mark(`${this.localName}:connected`);
      this.setAttribute('data-perf-marked', '');
    }
    this.render();
  }

  attributeChangedCallback(name, oldValue, newValue) {
    if (oldValue !== newValue) {
      this.render();
    }
  }

  render() {
    const label = this.getAttribute('label') || 'Click me';
    const disabled = this.hasAttribute('disabled');

    this.shadowRoot.innerHTML = `
      <style>
        :host {
          display: inline-block;
        }

        button {
          padding: 0.5rem 1rem;
          border: none;
          border-radius: 4px;
          background: var(--button-bg, #007bff);
          color: white;
          cursor: pointer;
          font-family: inherit;
          font-size: inherit;
        }

        button:disabled {
          opacity: 0.5;
          cursor: not-allowed;
        }

        button:not(:disabled):hover {
          background: var(--button-hover-bg, #0056b3);
        }
      </style>
      <button ${disabled ? 'disabled' : ''}>
        ${label}
      </button>
    `;

    // Mark first render complete
    if (!this._hasRendered) {
      this._hasRendered = true;
      performance.mark(`${this.localName}:first-render`);

      const measure = performance.measure(
        `${this.localName}:upgrade`,
        `${this.localName}:connected`,
        `${this.localName}:first-render`
      );

      // Log in development
      if (window.location.hostname === 'localhost') {
        console.log(`${this.localName} upgraded in ${measure.duration.toFixed(2)}ms`);
      }
    }
  }
}

customElements.define('perf-button', PerformanceTrackedButton);
performance.mark('perf-button:defined');

Forgetting to check for existing marks

If a component disconnects and reconnects, you'll create duplicate marks unless you guard against it. Always check if the mark already exists or use a flag to track marking state.

Over-instrumenting

Resist the urge to mark everything. Too many marks create noise and make it harder to find the signals that matter. Focus on initialization and critical user interactions.

Ignoring browser support

The User Timing API is supported in all major browsers, but always check if the performance object exists before calling its methods:

if (window.performance && performance.mark) {
  performance.mark('my-component:connected');
}

Not testing on real devices

Your laptop is fast. Your users' phones might not be. Always test your instrumented components on representative devices to see what the real performance looks like.

Do

Track component lifecycle milestones: connection, first render, upgrade time
Use consistent naming conventions across your component library
Report metrics to analytics for real-world performance tracking
Clean up marks and measures when they're no longer needed
Choose the right pattern: use a base class for new libraries, a mixin for existing ones
Compose mixins when you need multiple behaviors
Always call super methods in mixins to maintain the inheritance chain

Don't

Mark every render cycle: too expensive and noisy
Forget to check for performance API availability: defensive coding matters
Ignore the data: measure, analyze, act
Over-complicate your naming: keep it simple and descriptive
Skip testing on slower devices: that's where performance matters most
Forget to call super methods in mixins: breaks the inheritance chain

Performance monitoring doesn't have to be complicated. The User Timing API gives you exactly what you need to understand how your web components perform in the wild. By instrumenting key lifecycle moments and reporting metrics that matter, you'll have the insights you need to make data-driven decisions about optimization.

The pattern is straightforward: mark important moments, measure the time between them, and act on what you learn. Whether you choose a base class or a mixin depends on your architecture—base classes work great for new projects with a clean slate, while mixins shine when you need to add tracking to existing components or compose multiple behaviors. Either way, you set it up once and suddenly your entire component library has performance visibility without any per-component boilerplate.

Start simple; track connection and first render. See what the numbers tell you. Then expand to track the interactions and operations that matter most to your users. The data will surprise you, and that's exactly the point. You can't optimize what you can't measure, and now you can measure everything that matters.

Six months from now when you're investigating a performance regression or optimizing for a new market with slower network speeds, you'll be grateful you have this data. Your users will be grateful too, even if they never know you're tracking it. Build fast components, measure to prove they're fast, and keep measuring to make sure they stay that way.

A Storybook format that scales

2025-10-31T00:00:00Z

Here's the thing about Storybook: it's incredibly powerful, flexible, and dynamic...but because of that flexibility, it can quickly devolve into a tangled mess of inconsistent patterns, duplicated code, and confusing file structures. We've all been there—you start with good intentions, build a few components, and six months later you're drowning in technical debt wondering why nobody can find anything.

This guide is your roadmap to building a Storybook that actually scales. Whether you're starting fresh or untangling an existing setup, you'll learn the patterns and conventions that separate the maintainable Storybooks from the ones that make developers groan. We're talking about practical, battle-tested approaches that'll make your component library a joy to work with instead of a source of frustration.

If you're new to Storybook, here's the elevator pitch: it's a dedicated workshop for building UI components and pages in isolation, separate from your business logic, APIs, and application state. That means you can develop and test those hard-to-reach edge cases without having to orchestrate your entire app into the right condition. Even better, it brings together your UI, examples, and documentation in one place, creating a single source of truth that makes it easier to discover and reuse existing patterns. It's your front-end playground and living style guide rolled into one.

Before thinking about how you want to structure your Storybook files, you need to determine who your audience is and what they need to know. Storybook has a lot of powerful plugins and tools that can either enhance or confuse, so my advice is to be judicious about what you use and why. Is your audience primarily developers, designers, or product managers? Do they need to know about the component's props, events, and methods? How about accessibility requirements or performance? How many code examples and usage patterns do you need to provide?

Remember that less is more. You don't necessarily need to create a new story for every variant, state, or use case. Sometimes, a single documentation page and one default story with robust props available is enough. Letting your users explore the component through the Storybook interface will often reveal additional use cases and patterns that you may not have considered.

Before we get into the UI patterns and conventions, let's talk about some tooling choices that will help you create a consistent and maintainable Storybook.

Aliasing

Here's a quick win: set up your Storybook with package aliases instead relying on relative imports to reference other components. Your future self will thank you when it's time to refactor, and your paths will be more readable:

// Good
import { Template } from "@my-design-system/button/stories/template.js";

// Avoid
import { Template } from "../../../button/stories/template.js";

Rendering libraries

This suggestion is mostly for projects shipping vanilla HTML, CSS, and JavaScript without a framework. If you're building for React, Vue, or Angular, what rendering engine you use will be dictated by the framework.

For vanilla projects, I recommend leveraging lit to handle your templates. Lit is a library that provides a set of utilities for building web components that are easy to test, debug, and reuse. The lit-html library is lightweight and performant with utilities for dynamic rendering that you'll be grateful for later.

Bonus tip
You can even ship the template file with your component for CMS systems like Drupal or WordPress.

The lit package provides features such as:

Conditional classes: apply classes based on the Storybook args and context
Style maps: dynamically apply inline styles
Conditional rendering: show or hide elements
Optional attributes: only render attributes when they're defined

Compose, don't duplicate

When you're building complex components or patterns that leverage other components, resist the urge to copy and paste markup. Instead, import and call their templates. This keeps everything consistent and cuts down on the maintenance burden.

The best architecture is self-documenting. When your files are organized in a way that is easy to understand and navigate, it becomes easier to contribute to the project and easier to find things when you need to. Though some of this will be dictated by the structure of your component library and the tools you have chosen, there are general principles that will help you create a standardized format. First, it's important to keep component-focused Storybook assets as close to the component source files as possible; this ensures the documentation stays up-to-date with component changes. Inside my component folder, I typically keep a stories folder with the following files:

component.stories.js - story definitions, controls (argTypes), default values (args), and configuration
template.js - reusable render functions that accept arguments and return rendered HTML
[optional] component.docs.mdx - documentation for the component, including usage patterns, code examples, and best practices; alternatively, you can leverage JSDoc comments in your story file
[optional] component.test.js - visual regression testing grids (used to define the component's states and variants for tools like 💕 Chromatic)

The story file (.stories.js) is where all the magic happens—it's where you define your component's stories, controls, and configuration. I like to keep all my stories for a component in a single file. This makes it easier to find and update stories, and it makes it easier to see all the stories for a component at a glance. That said, if a component (or more likely, a pattern) has a lot of stories, it might make sense to split them into multiple files. Let's break down each essential part of a story file.

Default export

Your default export is the entry point for all your stories. It contains all the metadata and configuration for your component:

export default {
  title: "Components/Button",
  component: "Button",
  argTypes: { /* control definitions */ },
  args: { /* default values */ },
  parameters: { /* additional configuration */ },
  tags: [ /* organizational tags */ ]
};

Some of the guidance for these properties will differ based on what framework or rendering library you're using. I'm going to cover how to configure these properties for a vanilla project using lit, however, you can find more detailed information in the Storybook documentation for your specific framework.

Title

Pick a clear, human-readable title that reflects your component hierarchy. If your folder structure maps to how you want to group components in the sidebar, you can use a configuration object in your configuration file (.storybook/main.js):

export default {
  stories: [
      {
        // 👇 Sets the directory containing your stories
        directory: '../packages/components',
        // 👇 Storybook will load all files that match this glob
        files: '*.stories.*',
        // 👇 Used when generating automatic titles for your stories
        titlePrefix: 'MyComponents',
      },
    ],
};

If you want to create a set of custom categorizations for your components, you can add as many paths as you need to the title. Every slash-separated segment will be used as a group in the sidebar, under which the component will appear.

export default {
  stories: [
    {
      title: 'Buttons/Close',
    },
  ],
};

When determining how to group or nest your components, consider what distinctions would be most useful to your users. Does it benefit them to be able to dig into certain categories in one place instead of having to navigate through the entire library to find what they need? A few possible categories to consider are:

Buttons
Forms
Graphs
Layouts
Navigation

Component

Specify the root component name here. This helps Storybook's documentation features understand what you're showcasing. If you're using a framework, this will typically be the component name or the imported component object. See the Storybook documentation for more information.

Controls

This is where you define the controls that users can interact with in the Storybook UI. Here's a pro tip: organize them into logical categories so people can quickly find what they're looking for:

State—interactive states like focused, open, or disabled
Variant—design variations like visual appearance or size
Content—text, images, or nested components
Advanced—edge cases or specialized configurations

argTypes: {
  size: {
    control: "select",
    options: ["small", "medium", "large"],
    description: "The size of the button",
    table: { category: "Variant" }
  },
  isDisabled: {
    control: "boolean",
    description: "Whether the button is disabled",
    table: { category: "State" }
  }
}

Document and restrict these categories to ensure consistency across your component library. If you have a lot of controls, you can also consider creating a shared controls file to import and reuse across your components. You can store these in a controls folder inside your Storybook folder (i.e., .storybook/controls/states.js, .storybook/controls/variants.js, .storybook/controls/content.js, .storybook/controls/advanced.js). This is a great way to keep your controls organized and easy to find.

Bonus tip
If you identify your Storybook folder as a workspace in your package manager, you can import the controls into your story files using the workspace alias. For example, if you have a `controls` folder in your Storybook folder, you can import the controls like this:
import { states, variants, content, advanced } from "local-storybook/controls";
Be sure to export all your controls via an index.js file in your controls folder in order to leverage this syntax most effectively.

Default values

Always provide sensible defaults for all your controls. This way, your primary story renders in a useful state right out of the gate:

args: {
  size: "medium",
  isDisabled: false,
  label: "Click me"
}

Not all controls have to have a default state, though. When given the choice between adding a meaningless normal or default value into the options that doesn't actually trigger a state, I opt for setting the default to undefined.

// Good
["outline", "subtle"]

// Bad
["default", "outline", "subtle"]

Parameters

Parameters let you configure behavior and attach metadata. Think of them as the extra settings that make your stories more useful:

parameters: {
  design: {
    type: "figma",
    url: "https://www.figma.com/..."
  },
  actions: {
    handles: ["click", "focus", "blur"]
  },
  status: {
    type: "stable" // or "experimental", "deprecated"
  }
}

Creating individual stories

Each story represents a specific state or variant of your component. Use .bind({}) to create stories that inherit from your default configuration, then override specific args to demonstrate different use cases:

export const Default = Template.bind({});
Default.args = {
  // Override specific args for this story
};

export const Disabled = Template.bind({});
Disabled.args = {
  isDisabled: true
};

export const WithIcon = Template.bind({});
WithIcon.args = {
  icon: "settings",
  label: "Settings"
};

Naming conventions

Good story names are concise and descriptive. Here are some patterns that work well:

Default—your primary interactive example
With Icon—demonstrating optional features
Loading State—showing specific states
Error Variant—highlighting edge cases

And here's what not to do: don't repeat the component name in every story title. It's redundant and clutters your navigation.

Organizing with tags

Tags are your friends when it comes to controlling where stories appear and how they behave:

Use !dev to hide stories from the sidebar—super useful for documentation-only stories
Use !autodocs to exclude stories from auto-generated docs pages
Combine both tags for visual regression testing grids that shouldn't clutter your UI

Your template file (template.js) is where the actual rendering happens. Think of it as the engine that powers your stories.

Template structure

Export a primary Template(args, context) function that returns your rendered component. If you're using a library like Lit, this would be an html TemplateResult.

Here's the key: import and render nested component templates instead of duplicating their markup. We talked about this earlier, but it bears repeating—composition over duplication.

Standard arguments

Your templates should accept some common arguments to stay flexible:

rootClass—the base CSS class for your component
id and testId—for identification and testing
customClasses—an array of additional classes
customStyles—an object of custom CSS properties

Using directives for dynamic behavior

Most rendering libraries give you directives or utilities to handle dynamic rendering. Here's what you'll typically need:

classMap—for conditional classes based on your rootClass
styleMap—for inline style objects
ifDefined—for optional attributes that should only render when they exist
when—for conditional regions of your template

For interactive examples, use context.updateArgs to toggle arguments (like isOpen for a modal). And when you need to pass modifiable CSS custom properties, do it through customStyles—it's cleaner than hardcoding values.

Composition patterns

When you're composing complex components, use parent wrappers to position the pieces and pass arguments down to child templates. Here are some real-world examples of how this might look:

An action bar might compose a popover, close button, and action group
An action menu might compose a popover with an action button trigger and a menu for content
A coach mark might compose a popover, coach indicator, and internal layout

If you're using a visual regression tool like 💕 Chromatic, you'll want to set up testing grids. These live in a separate component.test.js file.

Test grids

Most visual regression setups use some kind of variants helper to generate grids of different states and variants. You'll typically provide your Template along with arrays of test data and state data.

Here's the strategy: group many states and variants into a single snapshot grid to optimize your test runs. Nobody wants to wait forever for visual tests to complete.

In your main *.stories.js file, export the grid and mark it with !autodocs and usually !dev so it doesn't clutter your documentation or sidebar.

Control patterns

Keep your controls organized and consistent across your component library. If you have common state controls (like isOpen, isSelected, isHovered, or isFocused), put them in a shared location and import them.

Use the same categories we talked about earlier: State, Variant, Content, and Advanced. And here's a neat trick—use if conditions to tie related controls together. For example, only show imageIsFixedHeight when hasImage is true.

Don't be afraid to reuse controls from related components either. If another component already has the perfect icon dropdown setup, import it instead of rebuilding it from scratch.

Actions and events

When you're working with nested components, reuse their action handlers by spreading them into your own parameters.actions.handles. For interactive triggers like popover toggles, wire up onclick to context.updateArgs or leverage the behavior from child templates.

Accessibility

Always provide ARIA attributes through your arguments—things like aria-haspopup, aria-controls, aria-expanded, and aria-pressed. Use the ifDefined directive so they only render when needed.

Keep focus, hover, and active states controllable in your test grids. This makes it way easier to verify your component looks right in all states.

When you're demonstrating popovers or menus, make sure trigger and popup IDs are consistent and exposed as arguments. Your QA team (and screen reader users) will appreciate it.

Design links

Link your stories to design files (like Figma) through parameters.design. This creates a direct connection between your implementation and the design source of truth.

Package information

Include your package.json and any metadata files in your parameters. This powers documentation blocks and helps users understand what version they're looking at.

Component status

Use parameters.status.type to communicate where your component is in its lifecycle—is it stable, experimental, or deprecated? Add tags like "migrated" to track major updates or migrations.

Let's wrap up with some quick guidelines to keep you on the right track:

Do

Import child component templates instead of copying their markup
Keep your template.js focused on the component itself—accept customClasses and customStyles for composition
Categorize your controls and set sensible defaults in args
Hide VRT-only stories from your sidebar and docs using tags
Reuse shared controls from a common location instead of duplicating them

Don't

Don't hardcode IDs—use a helper function to generate random IDs
Don't duplicate markup from nested components—import and compose instead
Don't skip accessibility—always include proper ARIA attributes

Here are some practical code snippets to get you started.

Story default export

Here's what a typical story file default export looks like:

import packageJson from "../package.json";

export default {
  title: "Components/Button",
  component: "Button",
  argTypes: {
    size: {
      control: "select",
      options: ["small", "medium", "large"],
      table: { category: "Variant" }
    },
    isDisabled: {
      control: "boolean",
      table: { category: "State" }
    }
  },
  args: {
    size: "medium",
    isDisabled: false,
    label: "Click me"
  },
  parameters: {
    design: {
      type: "figma",
      url: "https://www.figma.com/..."
    },
    packageJson,
    status: { type: "stable" }
  },
  tags: ["autodocs"]
};

Template composition

When you're composing complex components, here's how you might structure it:

import { Template as Popover } from "@my-design-system/popover/stories/template.js";
import { Template as Button } from "@my-design-system/button/stories/template.js";

export const Template = (args, context) => Popover({
  ...args,
  isOpen: true,
  trigger: (passthroughs, ctx) => Button({
    label: "Open Menu",
    ...passthroughs
  }, ctx),
  content: [/* child content templates */]
}, context);

Test grid setup

If you're setting up visual regression tests, your test file might look like this:

import { Template } from "./template.js";

export const TestGrid = {
  render: Template,
  parameters: {
    chromatic: { disableSnapshot: false }
  }
};

export const Default = TestGrid.bind({});
Default.tags = ["!autodocs", "!dev"];
Default.args = {
  // Test-specific args
};

Building a Storybook that scales isn't about following every best practice to the letter—it's about making intentional choices that serve your team and your users. Throughout this guide, we've covered the foundational decisions that'll keep your component library maintainable: organizing your files so they're easy to navigate, composing components instead of duplicating markup, structuring your story files with clear defaults and well-organized controls, and never forgetting about accessibility.

The most important takeaway? Consistency wins. Pick the patterns that make sense for your project—whether that's keeping all stories in one file or splitting them up, using Lit for vanilla projects or sticking with your framework's conventions, setting up visual regression tests or relying on manual QA. Whatever you choose, document it, share it with your team, and stick with it. A consistent Storybook with clear conventions will always be more valuable than a perfectly optimized one that nobody can navigate.

Six months from now, when you're diving back into a component you haven't touched in ages, you'll be grateful you put in the effort upfront. Your teammates will thank you. Your designers will thank you. And most importantly, you'll avoid that tangled mess of technical debt we talked about at the start. Let's build something great!

AI as a reflection of our values

2025-10-19T00:00:00Z

https://openai.com/index/why-language-models-hallucinate/

I first encountered this article and subsequent white paper a few days ago, and I've been ruminating on it all weekend. The white paper employs the metaphor of students taking a multiple-choice test to illustrate the grading process for the efficacy of an AI model. I find this metaphor particularly evocative because multiple-choice testing is frequently criticized for being an inadequate way to determine a student's understanding of the subject.

The paper highlights that since making a guess increases the likelihood of getting the right answer compared to leaving it blank, AI logically opts to return an assumption or estimate instead of stating, "I don't know." As a student of the United States public education system, I was well acquainted with this advice. After all, leaving an answer blank guarantees a zero, while a guess offers a one-in-four chance of earning a point.

Therefore, it's better to guess, isn't it?

The problem with a child guessing on the test is that the teacher loses an understanding of what the child really learned and where they need to reinforce or take a different approach for previous lessons. On top of this, some children are really good at taking standardized tests. Does that mean they know what it is we wanted them to learn from that lesson?

Map this back to the article on AI hallucinations, and we see that, yet again, AI is holding up a mirror to our flaws. We entered the work with assumptions and expectations, and the models returned answers that in fact reflect our own faulty definitions of reality and truth. It sought to bolster our egos because reinforcing pre-conceived notions is better received by the audience than telling someone their premise is invalid. What can we learn about training AI models from alternative educational models such as Constructivism, which aims to encourage problem-solving and critical thinking, connecting new data with previous knowledge?

How do we grade and assess the success of a model without falling back to assessment methods that we already know to be inconclusive for our children?

From Figma to code: why design systems need continuous collaboration

2025-10-03T00:00:00Z

The most high-performing design systems teams I've been on are ones with designers and engineers working in parallel. This is not to say that it's easy to get into this workflow because so often design projects are iterating well beyond where engineering is able to implement. When we slow down though and talk through this work together, I think we find so much opportunity to ask each other meaningful questions and challenge our pre-held notions and expectations.

What does this look like in practice? Below I'll outline a few of the questions I generally have when engaging with component designers.

The web is a notorious squishy platform. Screen sizes, color palettes, user preferences and needs all vary widely by browser and user. Some features aren't implemented in all browsers and others are implemented but behave in subtly different ways. Some users prefer large text and others want dark themes. There are a thousand ways that we engage with the web and a lot of angles to come at building widgets for those surfaces. So when I'm approaching a new pattern or design, I start by asking myself a few questions:

What are the min and max sizes or ratios where this thing looks good?
Should spacing or padding scale up or down with type? Or should the spacing be static and not influenced by increases or decreases in base font sizes?
What is the general ratio you'd like this widget to take up on the screen?
How do I engage with this element if I don't use a mouse? This is not just an accessibility concern but it also impacts how elements are constructed in the DOM because visual order doesn't necessarily equal semantic order. Even if I reorder elements visually using layouts, my keyboard will continue to navigate the elements in the order they exist in the DOM (unless you update that order with tabindex as well).
Are there any contextual customizations to an element? Should this thing look or behave differently if it exists inside something else or if it only has a certain amount of space available?

What these questions really get at is the heart of the design. When engineers start poking at a design, what they're wanting to do is really get inside your thought process and build something that fully maps to what you, as a designer, envisioned. It's so hard to communicate intent in static design documentation and as dynamic and squishy as the web has become, these back-and-forths are more valuable and important than ever.