I committed a custom event processing system: an event emitter, a task scheduler, an email sender – over a dozen modules, documented across five markdown files totaling 4,000+ lines.

Six days later, I committed back to n8n!!! with three exclamation marks. Two days after that, I deleted all of it. Over 3,000 lines of application code, gone.

This is what I learned about the difference between good architecture and appropriate architecture.

What I Was Trying to Solve

The platform processes inbound work: form submissions, bookings, confirmation emails, calendar events, reminders. Before the event system, all of this orchestration lived in n8n. Workflows were easy to build, execution history was visible, and integrations with Gmail and Google Calendar were pre-built.

But n8n was a separate system with its own database, its own deployment, its own failure modes. Every workflow was a black box from the platform’s perspective. I couldn’t query “what happened after this booking was created?” from my application database. The event-driven purist in me wanted a first-class event system: emit events, route them through handlers, track attempts, support replay.

So I built one.

What I Built

The system had five major components:

Event emission. Typed events (allocation_created, allocation_modified, form_submitted) stored in a database table with idempotency via deduplication keys.

Event processing. An edge function that resolved which handlers should run based on event type and business configuration, executing them in sequence. Each execution was recorded as an event_attempt with status tracking.

Task scheduling. Events triggered scheduled tasks – pickup reminders, return reminders, status transitions – with edge case handling for past dates.

Email sending. A template resolution engine that pulled templates from capability settings, resolved variables against event data, and sent through Gmail via OAuth.

Calendar integration. Created and updated Google Calendar events when allocations were created or modified.

Events were immutable and replayable. Handlers were isolated and testable. Attempt tracking gave complete observability. Deduplication prevented double-processing. It was, by any technical measure, well-designed.

And it came together fast. I leaned heavily on AI coding assistants for this build – the emitter, the processor, the scheduler, all produced and iterated quickly. What might have taken two weeks of solo work compressed into days. I was proud of the system and the velocity.

Why I Deleted It

Within a week of running the system end-to-end, three things became clear:

1. Debugging was miserable. When a confirmation email didn’t send, I had to trace through: Was the event emitted? Check the event table. Was it processed? Check the event_attempt table. Did the handler succeed? Read the error JSON. Was the template correct? Check the capability settings. Was the OAuth token valid? Check the integration table.

With n8n, I opened the execution history, saw the green and red nodes, clicked the failed one, and read the error. Done.

The irony was brutal. I’d built the event system partly for observability. But observability isn’t debuggability. A complete audit trail in database rows doesn’t help when you need to understand why something failed. Visual execution history – data flowing through nodes, with errors highlighted inline – is genuinely superior for diagnosing integration failures.

2. Edge cases multiplied. The custom system handled the happy path well. But real-world orchestration is mostly edge cases. What happens when a calendar event needs updating but the OAuth token expired? What about partial failures where the email sent but the calendar update didn’t? What about timezone conversions for scheduled tasks?

Each edge case required code. In n8n, each required dragging a node and configuring it. The velocity difference was enormous.

3. I was rebuilding n8n, badly. The moment I caught myself writing retry logic with exponential backoff for failed email sends, I stopped. I was building a workflow engine. n8n is a workflow engine, maintained by a team dedicated to exactly this problem. My version would always be worse: fewer integrations, worse error handling, no visual builder, no execution history UI.

Every hour spent on orchestration infrastructure was an hour not spent on the product. For an early-stage platform with one developer, that’s a fatal misallocation.

The Commit That Changed Everything

102b67b  back to n8n!!!

I brought n8n back the same day. Docker Compose setup, database schema restored, handlers migrated back to visual workflows. Two days later, move more logic back to n8n. Then a week of cleanup commits: every event processing file, every handler, every scheduler, every documentation file. The emitter, the processor, the scheduler, the email sender – all of it. Over 3,000 lines of TypeScript and 4,000 lines of documentation, gone.

It felt great.

What I Kept

Not everything was thrown away. The core operations layer stayed: synchronous, request-in/response-out handlers for creating requests, managing allocations, and handling tasks. Pure functions that accept parameters, validate against a schema, call a database RPC, and return a result. No events, no async processing, no orchestration.

The database tables for events still exist in the migration history. I didn’t write a migration to drop them. They sit there empty – a reminder.

The lesson crystallized into a principle: operations should be synchronous and deterministic. Orchestration should be delegated to a purpose-built tool.

The Hybrid Architecture

What I ended up with is a hybrid that plays to each tool’s strength:

Edge functions handle direct operations. Form submissions, allocation creation, resource CRUD. Synchronous, validated, returning immediately. TypeScript on Deno – fast, typed, easy to test.

n8n handles asynchronous orchestration. After a booking is created, n8n orchestrates: confirmation email, calendar event, reminders. It handles retries, OAuth refresh, and integration-specific errors with pre-built nodes.

The platform doesn’t know about orchestration internals. It fires an operation and gets a result. What happens afterward is n8n’s concern. The boundary is clean.

Lessons for Staff+ Engineers

1. Observability and debuggability are not the same thing. A complete event log is great for auditing. But when something breaks at 2 AM, you want a visual execution trace with actual data at each step, not SELECT * FROM event_attempt WHERE status = 'failed'. Know which one you actually need.

2. “I could build this” is not a reason to build it. The question isn’t capability – it’s opportunity cost. Every hour spent on orchestration infrastructure is an hour not spent on the product’s actual differentiator.

3. Deleting code is an engineering skill. Removing 3,000+ lines of working code was one of the hardest and best things I did. The codebase got simpler, the deployment got simpler, and debugging got dramatically better. Sunk cost is real, and overcoming it is a skill.

4. Match your abstraction level to your stage. A custom event-driven architecture makes sense at scale, with a dedicated infrastructure team. For an early-stage product with one developer, it’s over-engineering of the highest order. I knew this. I built it anyway because it was intellectually satisfying. The three exclamation marks in that commit message were aimed at myself.

5. AI coding tools are most dangerous in senior hands, not junior ones. The conventional wisdom is that AI assistants are risky for junior engineers who can’t evaluate the output. This experience convinced me it’s the opposite. Remember the velocity I mentioned? The AI produced genuinely good code – well-typed, well-structured, idiomatic. That was the problem. A junior engineer generating messy code with AI would have hit friction quickly: things wouldn’t compose, they’d get stuck, they’d ask for help. I generated a clean, well-architected system that worked perfectly and shouldn’t have existed. AI didn’t undermine my engineering judgment – it outran it. Ironically, the low cost of producing this code made deleting it easy – had I hand-written it over two weeks, the sunk cost instinct would have been far worse. But that’s exactly the trap: AI removes the friction that normally forces you to question whether a project is worth continuing. When building is nearly free, you don’t stop to ask “should I?” until you’re already done. The industry worries about AI generating bad code. The more insidious risk is AI generating good code so fast that experienced engineers never hit the natural pause where judgment kicks in.

The Meta-Lesson

The best architecture isn’t the most technically elegant one. It’s the one that lets you ship the right thing at the right time. I spent a week building infrastructure I didn’t need, then another week deleting it. The product didn’t advance during either week.

The platform is better now – not because the event system was bad, but because the platform is simpler, and simplicity compounds. Fewer moving parts, fewer failure modes, faster debugging. That’s worth more than architectural purity.

Sometimes the best engineering decision is git rm -r.

This is Part 3 of a three-part series. Part 1 covered schema-driven architecture. Part 2 covered using AI for configuration generation. This post covered knowing when to delete your own work.

My concern isn’t with developers using AI to write code. That’s a productivity tool with a human in the loop who understands what’s being produced. The problem is when code generation is the product, aimed at end users who can’t review what the AI wrote and have no way to verify it’s correct.

I took a different approach. In the platform I’ve been building, AI generates validated configuration – not executable code. The configuration is mechanically validated against strict schemas before it ever touches production. If the AI produces something invalid, it’s a schema error, not a production incident.

This distinction – configuration vs. code – is the difference between AI as a reliable product feature and AI as a liability.

The Setup: Why Configuration Generation Works

In Part 1, I described building a schema-driven platform where every domain model, form, and settings page is defined by JSON schemas. Adding a new capability to the platform means authoring a bundle of JSON files that conform to a meta-schema.

The interesting property of this architecture is that the output space is fully constrained. An LLM generating a capability bundle can only produce:

• JSON Schema objects with specific property types
• UI layout definitions using a fixed vocabulary of layout elements
• Form definitions with a known set of field types and options
• Settings with declared defaults and enumerations

There’s no arbitrary code. No function definitions. No control flow. Just structured data that either passes validation or doesn’t.

The Generation Pipeline

Here’s what actually happens when a new business onboards:

Step 1: Natural Language Requirements. The user describes their business in plain English. “I’m a drywall contractor. I need to track job sites, manage material orders, and let customers request quotes online.”

Step 2: Structured Extraction. The LLM (Claude) extracts structured requirements: industry vertical, core entities, relationships, booking/allocation needs, form intents. This is a constrained extraction task – the model maps free text to a known taxonomy of platform capabilities.

Step 3: Bundle Generation. Using the extracted requirements and the platform’s meta-schema as context, the LLM generates a complete capability bundle. This includes:

• Resource type schemas (the data models)
• UI layouts for create/edit forms
• List configurations for table views
• Public form schemas with field validation
• Parameter bindings that map form fields to backend operations
• Settings schemas with sensible defaults

Step 4: Mechanical Validation. The generated bundle goes through the exact same validation pipeline as human-authored bundles. AJV validates against the meta-schema. Every sub-schema is checked. Invalid bundles are rejected with specific error messages.

Step 5: Storage and Activation. Valid bundles are stored as versioned, immutable records. Each business owns its bundle. The bundle is activated, and the generic UI immediately renders the new capability.

The entire pipeline runs in about 30 seconds. From “I run a yoga studio” to a live system with class scheduling, student management, and booking forms.

What the Meta-Schema Actually Constrains

The power of this approach lives in the meta-schema. It’s a 1,600+ line JSON Schema document that defines:

Resource types must declare traits. A resource is allocatable (can be booked), temporal (has time-based availability), quantified (has inventory), etc. These traits determine which platform behaviors apply. The AI can’t invent new platform behaviors – it can only compose existing ones.

Forms must declare intent. Every form has an intent: create_allocation, cancel_allocation, modify_allocation, or create_inquiry. The intent determines which backend operation runs on submission. The AI doesn’t generate backend logic – it maps form fields to existing operations through a parameter binding DSL.

Parameter bindings use a fixed expression language. Form fields map to RPC parameters through a small set of expressions: field references, literal values, runtime context lookups, time arithmetic, conditional switches. This is expressive enough for real-world forms but constrained enough that every expression is mechanically evaluable.

Settings schemas must use known types and enumerations. The AI can’t introduce arbitrary behavior flags. Settings must conform to what the platform can actually configure.

Why This Is Better Than Code Generation

I’ve seen teams try to use LLMs to generate React components, API endpoints, or database queries. The fundamental problem is verification. How do you know the generated code is correct? You need tests, code review, and runtime monitoring – the same pipeline you use for human-written code, except now you’re doing it for output you didn’t write and may not fully understand.

Configuration generation sidesteps this entirely:

Validation is mechanical. Either the bundle conforms to the meta-schema or it doesn’t. There are no subtle runtime bugs.

The blast radius is bounded. A bad configuration means one business sees incorrect field labels or a missing form section. It doesn’t mean a SQL injection or a broken API for all customers.

Iteration is cheap. If the generated bundle isn’t quite right, regenerate with adjusted requirements. Each generation produces a new immutable version. There’s no merge conflict, no code review, no deployment.

The AI gets better at the right task. When you use an LLM for structured generation against a schema, you can measure accuracy in hard terms: what percentage of generations pass validation on the first attempt? What percentage require human correction? These metrics are actionable. “Did the generated code work?” is much harder to quantify.

The Feedback Loop: Validation Errors as Training Signal

When a generated bundle fails validation, the error messages are specific and actionable: “Resource type ‘yoga_class’ declares trait ‘allocatable’ but schema includes property ‘qty_available’ – platform-managed fields must not appear in resource schemas.”

These errors serve two purposes:

1. LLM self-correction. The errors are fed back to the LLM for a retry. In practice, first-attempt validation pass rates are high, and the retry loop catches most remaining issues.
2. Meta-schema refinement. Repeated generation failures in the same area signal that the meta-schema is ambiguous or that the LLM needs better prompting. This feedback loop has driven several meta-schema revisions that improved both human and AI authoring.

The Staff Engineering Insight

The decision to use AI for configuration generation wasn’t primarily an AI decision. It was an architecture decision. The schema-driven platform had to exist first. The meta-schemas had to be rigorous. The validation pipeline had to be airtight. The generic UI had to be complete.

AI was the last piece, not the first. And it only worked because every preceding layer was designed with constraints that make the AI’s job tractable.

This is the pattern I’d advocate for any team looking to integrate generative AI into their product:

1. Define the output space formally. Use schemas, grammars, type systems – whatever makes the valid output mechanically verifiable.
2. Build the validation pipeline first. If you can’t mechanically verify the output, you don’t have an AI feature. You have an AI experiment.
3. Make the AI generate data, not behavior. Configuration, schemas, mappings, templates – things that are declarative and inspectable. Not code that needs to be understood to be trusted.
4. Version and isolate. Every AI generation should produce an immutable, versioned artifact scoped to a single tenant. No shared mutable state.

The goal isn’t to use AI to write your platform. It’s to design your platform so that AI can configure it safely.

The Uncomfortable Industry Implication

There’s a consequence of this architecture that I think most of the industry is ignoring: AI code generation products are racing toward commodity, while AI configuration generation builds compounding advantage.

Consider the trajectories. Code generation gets less differentiated over time – as models improve, everyone’s AI-generated code converges in quality. The code itself becomes interchangeable. If your product is “AI writes your app,” every foundation model improvement erodes your position, because your competitors get the same improvement for free.

Configuration generation runs in the opposite direction. Every generation tests and refines the meta-schema. Every schema revision makes future generations more accurate. The constraint system is the moat – and it’s a moat that deepens with use rather than eroding with time.

The industry is fixated on making AI generate code faster. But speed of generation was never the bottleneck. The bottleneck is verification – knowing that what the AI produced is correct. Code generation leaves verification as a human problem: review, test, monitor, hope. Configuration generation reduces verification to a mechanical check that runs in milliseconds. That’s not an incremental improvement. It’s a category difference.

What’s Next

The current system generates complete capability bundles from scratch. The next frontier is incremental modification: a business owner saying “I want to add a ‘dietary restrictions’ field to my booking form” and having the AI produce a v2 bundle with that change, validated against the same meta-schemas, without touching anything else.

This is harder than initial generation because it requires understanding the existing bundle, making a targeted change, and preserving everything else. But the architecture supports it – bundles are versioned, immutable, and mechanically diffable.

This is Part 2 of a three-part series. Part 1 covered schema-driven platform architecture. Part 3 covers what I learned from building a custom event-driven architecture, then deleting it.

Early on, I made a decision that shaped everything that followed: JSON Schema would be the single source of truth for validation, UI generation, and runtime behavior. Not just for API validation. For everything.

That decision turned out to be the best architectural call I’ve made in years.

The Problem: Vertical Fields Are a Trap

Every multi-tenant platform eventually faces the same temptation. A customer needs a “color” field. Another needs “square footage.” Another needs “session duration.” The easy path is to add columns to your database tables, write custom UI for each, and move on.

This works for two customers. By the fifth, you’re drowning. Every new customer type requires migrations, new form components, new list columns, new validation logic. Your “platform” is really just a collection of bespoke applications sharing a login page.

I’d seen this pattern destroy codebases at previous companies. So I drew a hard line: no vertical fields in core tables. Domain-specific data lives in JSONB columns, typed entirely by schemas.

The Architecture: One Schema, Three Jobs

Here’s the core insight that makes this work. A single JSON Schema definition does triple duty:

1. Validation. AJV validates data at every boundary – form submissions, API calls, database writes. The schema is the contract.

2. UI Generation. The same schema drives form rendering. A string with an enum becomes a dropdown. A number with minimum and maximum gets range validation. A boolean renders as a toggle. Combined with a UI layout schema (using JSONForms conventions), you get full CRUD interfaces without writing a single component.

3. List Configuration. A companion list schema defines table columns, search paths, sort defaults, and cell formatting. The same generic list component renders any entity type.

The result: adding a new entity type to the platform means authoring four JSON files (schema, UI layout, list config, metadata). No migrations. No new components. No deployments.

What I Actually Built

The platform has a generic resource system. Every domain object – whether it’s an equipment item, a class session, a service offering – is stored in the same table with a JSONB data column. The resource’s type_key points to its schema definition.

The frontend has exactly three resource views: list, form, and detail. They’re completely generic. They accept schemas as props and render accordingly.

ResourceListView  + list.json   = any table
ResourceFormView  + schema.json + ui.json = any form
ResourceDetailView + ui.json    = any detail page

Settings work the same way. Each capability declares a settings schema, and the settings UI is auto-generated. No settings page is hand-coded.

Public-facing forms work the same way. A form schema defines fields, validation, and dynamic options. The same rendering pipeline produces customer-facing booking forms, inquiry forms, cancellation flows – all from JSON.

The Hard Parts Nobody Talks About

This isn’t a free lunch. Here’s what was genuinely difficult:

Schema design is API design. When your schema drives UI, every property name, every title, every description matters. You’re designing a user interface in JSON. It requires the same care as designing a REST API, but the feedback loop is different – you only see problems when you render the form.

UI layout schemas are necessary and annoying. Pure JSON Schema doesn’t encode layout. You need a separate UI schema to specify: which fields go in which section, what order, what hints to give the renderer. I use a Categorization > Category > Control hierarchy. It works, but it’s another artifact to maintain per entity type.

Dynamic behavior requires schema extensions. Standard JSON Schema doesn’t handle “show this field only if that setting is enabled” or “populate this dropdown from a database query.” I ended up defining custom extensions: x-options for dynamic dropdowns (resolved server-side), x-condition for conditional visibility, x-hidden for fields present in data but invisible in forms. These extensions are processed both server-side (before delivery) and client-side (during rendering).

Generic list views need explicit formatting. A schema tells you a field is a number, but not that it’s currency. List configurations need a kind property (text, currency, date, boolean) to format cells correctly. This is domain knowledge that JSON Schema alone can’t express.

Where AI Fits In

Here’s where it gets interesting. Once your entire domain model is expressed as schemas, AI can generate new domain models. A language model that understands your meta-schema can produce valid capability definitions from a natural language description.

“I run a yoga studio with class bookings and student management” becomes a complete set of resource types, forms, and settings – validated against the same meta-schemas, rendered by the same generic UI.

This only works because the target is structured data, not code. The AI generates configuration that’s mechanically validated before it touches production. The blast radius of a bad generation is a validation error, not a runtime crash.

I’ll write more about this in a follow-up post.

Lessons for Staff+ Engineers

If you’re evaluating this pattern for your own platform:

Start with the meta-schema. Before writing any application code, define the schema that validates your schemas. This forces you to think about what abstractions your platform actually needs. My meta-schema went through multiple major revisions before it stabilized, and each revision clarified the platform’s actual capabilities.

Invest in server-side schema processing. Don’t send raw schemas to the client and let the frontend figure out conditional visibility and dynamic options. Process schemas on the server, resolve options against real data, filter invisible fields, and deliver a “ready to render” package. This keeps the frontend simple and prevents data leaks.

Accept that you’ll need extensions. Vanilla JSON Schema won’t be enough. Define your extensions explicitly, document them, and process them in a single pipeline. Don’t scatter x- handling across your codebase.

Generic views are an investment, not a shortcut. Building truly generic list/form/detail views takes longer upfront than building one bespoke page. The payoff comes at entity type three or four, and then it compounds. By entity type ten, you’re adding new domain models in an afternoon.

JSON Schema + JSONB + generic UI = a platform that scales by configuration, not code. That’s the real unlock. Not any single technology, but the discipline of keeping domain meaning out of your core and expressing it entirely in validated, renderable schemas.

The Bigger Shift

Building this platform surfaced an uncomfortable truth that I think the profession hasn’t reckoned with: the future of software engineering looks more like writing constraints than writing implementations.

Schema-driven development inverts the traditional value hierarchy. Engineers treat schemas as “just configuration” – boring, unglamorous, not “real engineering.” But in a schema-driven system, the schema is more valuable than any code that interprets it. Code is increasingly replaceable – by AI, by new frameworks, by rewrites. My schemas encode product decisions, business rules, and domain constraints that represent months of hard-won understanding. They’re the durable artifact. The platform code that renders and validates against them could be rewritten in a weekend.

As AI gets better at generating implementations within constraints, the engineering skill that compounds isn’t writing code – it’s defining the boundaries that make correct output inevitable. The architect who defines a rigorous meta-schema is making thousands of future implementation decisions in advance. That’s leverage.

Most engineers will resist this shift because writing constraints feels less creative than writing implementations. I resisted it too. But the most impactful thing I built this year wasn’t an application. It was a 1,600-line JSON Schema document that makes applications unnecessary.

This is Part 1 of a three-part series on building AI-enabled SaaS platforms. Next up: using generative AI to produce validated product configuration at onboarding time.

Frameworks and libraries provide battle-tested solutions to common problems

Server-side rendering, templating, and routing are just a few challenges you’ll face when building an application. These problems aren’t new. Framework developers have spent thousands of hours solving them, so you don’t have to. Their solutions are battle-tested for performance, reliability, and browser compatibility. Why reinvent the wheel when you can stand on their shoulders and spend your time on features?

Frameworks guide best practices for security

Many frameworks offer a layer of protection against cross-site scripting (XSS). For instance, React uses automatic escaping to prevent developers from rendering untrusted HTML in the DOM. It’s not bulletproof, but it means a developer with no security background is less likely to shoot themselves in the foot.

With vanilla JavaScript, that layer doesn’t exist. One careless innerHTML and 💥 you’ve got a problem.

Frameworks guide best practices for accessibility

In addition to written guidelines, most frameworks provide tooling to improve accessibility. Create React App, for example, ships with an eslint config that checks your code for common accessibility issues. It doesn’t guarantee AAA accessibility, but it nudges developers in the right direction.

React a11y Guidelines
Ember a11y Guidelines

Frameworks provide a common lexicon

After using a framework for a while, you start to speak its language. Components, props, state—these mean the same thing in any React project. Having a common lexicon improves communication and helps new team members ramp up quickly.

Frameworks are inevitable

There’s a tipping point in most software projects where, if you didn’t start with a framework, you begin building one by accident. As you add features, complexity creeps in and you start generalizing pieces of code. Keep doing that and you end up with something that looks like a framework but with more bugs and less documentation than an off-the-shelf option.

Think about the features you could have been building while you were busy debugging that DOM manipulation code. Using a framework lets you focus on delivering value instead of reinventing the wheel.

Frameworks have opinions

There are so many ways to build a modern web application that starting with vanilla JavaScript can lead to decision paralysis. How should your files be organized? How should your build scripts be configured? Opinionated frameworks like Ember make these decisions for you. That way your team can focus on what’s most important: building a great product.

Let’s say you want to use this image as a full page background on your website:

1920x1080.jpg (22 KB)

Using SVG or CSS gradients would be ideal for reducing the file size and providing resolution-independent scaling. Sadly, neither technology supports mesh gradients at this time.

Fortunately, there’s another way to achieve both a tiny file size and vector-like scaling using a raster image.

Here’s how it works:

1. Downsample the image so its dimensions are 32x18.
2. Export the image as a PNG. The resulting file should be around 1 KB.
3. Use the 32x18 image as a CSS background that covers its container:

   .my-background {
     width: 1920px;
     height: 1080px;
     background: url(32x18.png);
     background-size: cover;
   }
   

   or as an <img> element:

   <img src="32x18.png" style="width: 100%; height: auto;" />
   

Here is the result:

32x18.png (1443 bytes)

Can you tell the difference? The stretched image looks almost identical to the original. It scales up infinitely without noticeable distortion. Better yet, the new image is only 1.4KB—a 93.6% reduction 🎉. Click here for a side-by-side comparison.

Here is another example:

1920x1080-2.jpg (143 KB)

This image has more detail than the previous one. In this case, the small image needs to be a bit larger (128x72) to capture the detail. Finding the right size takes some experimenting.

128x72.png (7 KB)

This technique is also suitable for blurred background photos—the kind you typically see behind a text overlay. In this case, saving the image as a JPEG yields a smaller file size.

1920x1080-4.jpg (199 KB)

256x144-4.jpg (10 KB)

Limitations

Before you get too excited, this technique does have one limitation. It works well for smooth gradients and images with less contrast, but look what happens if you blow up this image:

1920x1080-3.jpg (337 KB)

128x72-2.png (21 KB)

What’s going on here?

When the downsampled image is enlarged, the browser uses an interpolation algorithm to fill in the missing data. Smooth images with less contrast can be upsampled without noticeable distortion because the interpolated pixels blend in with the originals.

How is this useful?

This technique is great for reducing the file size of background images that often contain less detail. It’s also great for rendering lightweight, scalable mesh gradients—something you can’t currently do with SVG or CSS. Mesh gradients were planned for SVG 2.0 but the feature has since been removed from the spec.

So the next time you’re about to export a big background image from Photoshop or Sketch, give this technique a try. You might be surprised how well it works.

Say you have a simple button component:

const Button = ({href, children}) => (
  <a href={href}>{children}</a>
)

You can create a snapshot test for it like so:

import React from 'react'
import Button from '../'
import renderer from 'react-test-renderer'

it('renders correctly', () => {
  const tree = renderer
    .create(<Button href="https://myurl.com">My Label</Button>)
    .toJSON()
  expect(tree).toMatchSnapshot()
})

Now any change to the component’s rendered output will cause the test to fail. Sounds great, right?

Consider what happens when you add a new attribute target but mistype it as traget:

const Button = ({href, target, children}) => (
  <a href={href} traget={target}>{children}</a>
)

You expect the test to fail, since the rendered output changed. In haste you skim the diff, miss the typo, and update the snapshot anyway. Now you have a passing test that asserts the wrong output. WTF just happened?

Sorting the Catch

When a snapshot test fails, you must review each change and decide whether it’s a bug or a valid update. That review is tedious and error-prone, especially when lots of changes pile up.

Snapshot testing is like fishing with a giant net. You want bugs, but you also catch plenty of valid changes. Sorting the catch—deciding what to keep and what to throw back—is the hard part. The risk is updating a snapshot because you assume the change is correct, when in fact it’s a bug.

Things get worse with jest-styled-components, which stores style rules with the snapshot. Now you’re reviewing every line of changing CSS, too.

Snapshot Fatigue

Snapshot tests are easy to create because they push all the cognitive load to the reviewer. After a while engineers experience snapshot fatigue and start blindly updating failed snapshots without reviewing them. At that point the tests are useless.

Do You Even Need a Snapshot?

A good test prevents you from accidentally breaking a component’s API. By creating a snapshot test, you’re essentially declaring that the component’s entire rendered output is part of its API and should never change. Sometimes that’s true, but usually a component has specific behaviors you care about. Freezing its entire output makes refactoring painful.

Instead, identify the UI elements that are critical to behavior and test those explicitly.

import React from 'react'
import Button from '../'
import {render, getByText} from 'react-testing-library'
import 'react-testing-library/cleanup-after-each'
import 'jest-dom/extend-expect'

it('renders correctly', () => {
  const {container} = render(<Button href="https://myurl.com" target="_blank">My Label</Button>)
  const button = getByText(container, 'My Label')

  expect(button).toHaveAttribute('target', '_blank')
  expect(button).toHaveAttribute('href', 'https://myurl.com')
})

This test is explicit. It verifies that the link contains the correct text and that its href and target values are correct. As long as those values don’t change, the component should function as expected.

The method requires more thought upfront but eliminates the burden and risk of manually reviewing snapshot diffs over time. It also lets you refactor freely as long as those specific values stay intact.

I come across a lot of React-Redux apps where components, action creators, selectors, and reducers are tested as separate units. It’s a common practice—it’s even described in the Redux docs (archived)—but there’s a better way.

In this post, I’ll show you why the standard approach for testing React-Redux apps is insufficient and makes refactoring harder. I’ll also show you an easier way to test your app that catches more bugs and keeps refactors safe.

Testing Atoms

So what’s the problem with testing components, action creators, selectors, and reducers separately?

First, testing these elements in isolation doesn’t guarantee that they work together. A unit test for an action creator asserts that an action is created but doesn’t verify that the action is ever dispatched. A unit test for a reducer asserts that a new state is returned but doesn’t verify that the UI updates to reflect it. There’s a disconnect.

Second, because these tests require you to mock other parts of the system, you lose confidence in the integration between what you’re testing and the dependency being mocked. For example, the Redux docs recommend redux-mock-store for async action creators. A mock store looks like a real Redux store, but its state is static. It lets you verify that certain actions are dispatched but tells you nothing about how those actions change real state.

Finally, these tests are so granular that refactoring becomes painful. A small change to one module often requires updates to several tests. This slows development and increases the chance of new bugs.

That’s what I call testing the atoms. Knowing that tiny chunks of code work in isolation is great, but to be confident they work together, test the molecules.

Testing Molecules

Components, action creators, selectors, and reducers are like atoms that combine to create a connected component molecule. Testing the molecule verifies the connections between its atoms.

Here’s an example:

// Component (atom)
import React from 'react'

const Counter = ({count, onClick}) => (
  <button title="Click Me" onClick={onClick}>Count: {count}</button>
)

export default Counter

// Action creator (atom)
export const incrementCounter = () => ({
  type: 'INCREMENT_COUNTER'
})

// Reducer (atom)
const counterReducer = (state = {count: 0}, action) => {
  switch (action.type) {
    case 'INCREMENT_COUNTER':
      return {
        count: state.count + 1
      }
    default:
      return state
  }
}

export default counterReducer

// Connected component (molecule)
import {connect} from 'react-redux'
import {incrementCounter} from '/actions'
import Counter from './counter'

export default connect(
  (state) => state,
  {
    onClick: incrementCounter
  }
)(Counter)

The component renders a button that increments a counter when clicked.

Here’s what the molecule test looks like:

import {createStore} from 'redux'
import {Provider} from 'react-redux'
import {render, getByTitle, fireEvent} from 'react-testing-library'
import 'react-testing-library/cleanup-after-each'
import 'jest-dom/extend-expect'

import Counter from '../'
import counterReducer from '/reducers/counter-reducer'

// Create a real redux store
const store = createStore(counterReducer, {
  count: 0
})

it('increments the counter', () => {
  const {container} = render(
    <Provider store={store}>
      <Counter />
    </Provider>
  )

  const button = getByTitle(container, 'Click Me')

  fireEvent.click(button)
  expect(button).toHaveTextContent('Count: 1')

  fireEvent.click(button)
  expect(button).toHaveTextContent('Count: 2')
})

A few takeaways:

• The connected component is the only module under test, but the test covers every line inside the other modules. By testing a molecule, you indirectly test its atoms.
• The test verifies the connections between atoms. It fails if the component’s onClick prop isn’t wired to incrementCounter or if the reducer mishandles the INCREMENT_COUNTER action.
• The test uses a real Redux store instead of redux-mock-store. Using a real store closes the loop between UI event (input) and UI update (output). You fire an event and assert that the UI updates. With a mock store, you can only assert that actions were dispatched.

Because the test focuses on behavior rather than implementation details, you can refactor the atoms without breaking it.

Many people assume integration tests are necessarily broad in scope, while they can be more effectively done with a narrower scope.

@martinfowler

Narrow integration tests give you more confidence in the stability of your application because they verify the connections between smaller units of code. Instead of writing a unit test for every atom in your app, zoom out and write integration tests for the molecules.

Write tests. Not too many. Mostly integration.

@rauchg

There are plenty of scenarios where unit tests make sense (shared libraries, TDD, etc.) but for testing the overall behaviour of your application, integration tests are more likely to catch problems.

Summary

• Unit tests don’t cover the connections between components, action creators, selectors, and reducers.
• Integration tests give you more confidence in the stability of your application because they verify the relationships between units of code.
• Testing a connected component from the UI allows you to refactor its implementation freely.
• Integration tests don’t have to be wide in scope. You can use them to test the connection between just a handful of modules.

On the client side we chose Create React App for its simple, batteries-included tooling. Combining the two is straightforward, but getting local development right can be tricky. Here’s the recipe that worked for us.

Dev servers

If you plan to use Firebase Functions and Firebase Hosting, run the Create React App dev server alongside the Firebase emulator. That way you can emulate HTTP functions and hosting while your React app runs in dev mode.

Install npm-run-all to orchestrate both servers:

yarn add --dev npm-run-all

Add these scripts to package.json:

{
  "scripts": {
    "dev": "run-p --race dev:firebase dev:react",
    "dev:firebase": "firebase serve -p 4000",
    "dev:react": "react-scripts start"
  }
}

Run yarn dev to start both. React stays on http://localhost:3000 while the Firebase project is emulated on port 4000. The --race flag ensures either process exiting will stop the other so you don’t end up with orphaned servers.

Implicit initialization

When deploying to Firebase Hosting, use implicit initialization. It removes the need to juggle environment-specific configs.

Instead of manually configuring each environment:

<script src="https://www.gstatic.com/firebasejs/5.3.0/firebase.js"></script>
<script>
  firebase.initializeApp({
    apiKey: "<API_KEY>",
    authDomain: "<PROJECT_ID>.firebaseapp.com",
    databaseURL: "https://<DATABASE_NAME>.firebaseio.com",
    projectId: "<PROJECT_ID>",
    storageBucket: "<BUCKET>.appspot.com",
    messagingSenderId: "<SENDER_ID>",
  })
</script>

Just load the auto-configured scripts from Firebase Hosting:

<script src="/__/firebase/5.3.0/firebase.js"></script>
<script src="/__/firebase/init.js"></script>

Once deployed, the app is automatically configured for its host project.

You might be wondering about that /__ directory. Because it only exists in the Firebase Hosting environment, tell the React dev server how to proxy those requests locally by adding this to package.json:

{
  "proxy": "http://localhost:4000"
}

The proxy setting sends unknown requests to the target URL. Any request containing /__ now reaches the Firebase Hosting emulator running on port 4000.

Calling Firebase Functions from your app

If you call an HTTP Firebase Function from React, you might be tempted to store environment-specific URLs. A cleaner option is to configure a rewrite in firebase.json that exposes the function behind a friendly path:

{
  "hosting": {
    "public": "build",
    "ignore": ["firebase.json", "**/.*", "**/node_modules/**"],
    "rewrites": [
      {
        "source": "/myFunction", // Some URL to expose
        "function": "myFunction" // Your HTTP function
      },
      {
        "source": "**",
        "destination": "/index.html"
      }
    ]
  }
}

Now your app can call /myFunction and Firebase Hosting will route it to the correct backend.

const myData = await fetch('/myFunction')

To make that rewrite work locally, expand the proxy entry in package.json:

  "proxy": {
    "/__": {
      "target": "http://localhost:4000"
    }
    "/myFunction": {
      "target": "http://localhost:4000"
    }
  }

This approach works, but if you plan to add more functions, a scalable version might look like this:

  "proxy": {
    "/__": {
      "target": "http://localhost:4000"
    }
    "/functions": {
      "target": "http://localhost:4000"
    }
  }

Any request starting with /functions now reaches the emulator, keeping local development predictable while matching production routing.

Say you have a function that adds two numbers:

const add = (a, b) => a + b

add(2, 4)
// 6

Function.prototype.bind lets you partially apply a function by fixing one or more arguments.

For example, if you partially apply add and fix the first argument with 10, you get a new function addTen that adds 10 to whatever you pass in.

const add = (a, b) => a + b
const addTen = add.bind(null, 10)

addTen(3)
// 13

addTen(6)
// 16

That’s a common demo, but here’s a practical use.

Reducing argument repetition

If you want to fetch several resources from an API, your code might look like this:

const apiBaseUrl = 'https://api.myapp.com/api/v1'
const getData = (baseUrl, resource) => fetch(`${baseUrl}/${resource}`)

Promise.all([
  getData(apiBaseUrl, 'products'),
  getData(apiBaseUrl, 'categories'),
  getData(apiBaseUrl, 'tags'),
]).then((responses) => {
  // Do stuff
})

Notice that getData and the first argument apiBaseUrl repeat. You can partially apply getData to remove that duplication.

const apiBaseUrl = 'https://api.myapp.com/api/v1'
const getData = (baseUrl, resource) => fetch(`${baseUrl}/${resource}`)
const getDataFromAPI = getData.bind(null, apiBaseUrl)

Promise.all([
  getDataFromAPI('products'),
  getDataFromAPI('categories'),
  getDataFromAPI('tags'),
]).then((responses) => {
  // Do stuff
})

That’s better: the base URL is declared once, and every call shares it.

Reducing function call repetition

Because getDataFromAPI now takes a single argument, you can pass it directly to map.

const apiBaseUrl = 'https://api.myapp.com/api/v1'
const getData = (baseUrl, path) => fetch(`${baseUrl}/${path}`)
const getDataFromAPI = getData.bind(null, apiBaseUrl)

Promise.all(['products', 'categories', 'tags'].map(getDataFromAPI)).then(
  (responses) => {
    // Do stuff
  }
)

No more repetition—and the intent is clearer. Partial application is a tiny tool, but once you start using it your code often becomes more expressive and easier to refactor.

Notice how the beer can has a transparent area around the edges (there’s a video playing behind it). As a single PNG, the can graphic weighed in at over 1.2 MB. The trick below brought it down to 271 KB without giving up transparency.

First, create two files. The first is a regular JPEG without any transparency; you can compress it aggressively. The second is a tiny 8-bit PNG (alpha mask) that represents the transparent areas. The PNG is only 11 KB because it contains so few colors and no blended transparency.

Next, I created a little snippet of inline SVG:

<svg viewBox="0 0 560 1388">
  <defs>
    <mask id="canTopMask">
      <image
        width="560"
        height="1388"
        xlink:href="img/can-top-alpha.png"></image>
    </mask>
  </defs>
  <image
    mask="url(#canTopMask)"
    id="canTop"
    width="560"
    height="1388"
    xlink:href="can-top.jpg"></image>
</svg>

Load both images inside an inline SVG. The PNG is included as a mask and applied to the JPEG to carve out the transparent area. The result: full transparency with JPEG compression.

Caveats

1. To work in most browsers the SVG must be inline. You can’t move it into an external file and load it with an <img> tag.
2. No IE8 support
3. Masks don’t work in older versions of Android