Every large migration eventually forces a choice between two bad options.

The first is the mega-PR. Models like Fable or Astra can now produce tens of thousands of lines of code in under an hour, which makes merging massive projects in one big swing more tempting than ever. But massive PRs are near-impossible to review closely, can be a mess to rollback properly, and are not a good fit for a product like Ambrook that is a critical finance system for thousands of businesses across the country.

The second is the more classical, conservative approach: build new components or classes alongside the old ones and move call sites over gradually. Each PR is safe to review and merge, but the codebase lives in two systems for months at a time. While mid-migration, engineers and agents need to learn both APIs, and new code keeps being written against the old API, leading to delays, confusion, and headache.

This summer we migrated Ambrook’s design system from Material UI (MUI) to Base UI. After years of being well served by MUI, we had reached a breaking point, having overridden nearly all of MUI’s style defaults in favor of our own styles. Base UI’s headless, agent-friendly approach gave us the web accessibility best practices both libraries include without the drawbacks.

The migration was massive, spanning 54k line changes across 794 files, in a cross-platform design system that targets React web and React Native, and we completed it in just over two weeks without any major regressions or customer disruption.

To get this outcome, we wanted to break the false choice between mega-PR and drawn out migration, in favor a few project goals:

• All changes should be packaged in small or simple diffs a human can actually review

• No “overlap” period where the codebase has a confusing mix of old and new patterns

• No user disruption or component regressions

• No API churn for web or native consumers (the change should remain within the design system wherever possible)

• Leave the system better tested at the end.

Rather than building as a mega-PR or one massive stack, we ran the migration as a graph. We combined long-lived planner agents, groups of cloud worker agents, thoughtful testing, human review, and rapid bug bash iteration in a process we coordinated to get the best of both worlds. Here’s how we broke it down:

Our Graph Design

Stacking our migration into a hundred small pieces wasn’t tenable because stacks are serial, with each change affecting the next downstream. Instead, we worked to simplify to create isolated, verifiable, parallelizable tasks that allowed us to break down the project into four phases. Each phase fanned out parallel worker agents, then brought their output back through human review, following the same basic steps:

1. A long-lived Fable planner agent running in Claude Code held the context for the migration, writing and proposing a plan.

2. A human reviews the plan, giving feedback on prototype PRs and the proposed batching to minimize conflicts.

3. The planner writes a brief per batch and files it as a Linear ticket assigned to Niteshift, one of our cloud-based coding agents, running either Opus or Sonnet, depending on the ticket complexity. Niteshift allows these tickets to be addressed by an independent cloud agent with its own environment, branch, and context window, not as a sub-agent inside the planner’s session, so one crashed or rate-limited session can’t take the batch down with it.

4. Each Niteshift agent returns a separately mergeable PR, incorporating agentic code review feedback.

5. A human reviews and merges, either independently or as a stack (depending on the phase).

We routed tasks to the appropriate coding model based on the kind of judgment they needed. Mechanical, well-specified batches (test writing, simple bug-fixes) went to Sonnet. Planning, dispatching, and the core migration, where one agent had to hold the whole system in context, went to Fable. Visual polish and complex component migrations went to Opus with a long context window. For review, we used multiple adversarial code review agents from different providers, so the reviewers didn’t share the authors‘ blind spots.

1. Planning & Prototyping

The first phase was prototyping, and most of it was meant to be thrown away. Agents produced exploratory mega-PRs that migrated large parts of the app at once, so we could see how it felt and where it broke. Alongside them, a handful of careful single-component PRs showed what “done right” looked like for one component.

From those, the plan made a decision for every component:

• Base UI, where it had the right primitive. Tooltips, menus, dialogs, selects, and popovers all moved onto Base UI’s headless components.

• Plain JSX and CSS, where MUI had been doing little. Our AmSpinner, AmSkeleton, and AmLink components were easier to write from scratch than use a library for.

• A dedicated library, where Base UI had nothing to offer. Calendars and date pickers specifically aren’t provided by Base UI, so we used React Aria, whose timezone-less CalendarDate matches how we store dates.

We also leaned on standard best practices for planning large migrations. In our design system, component props live in a .types.ts file shared with native, and those interfaces stayed frozen (with one planned exception, covered under Codemods), so that we didn’t run into conflicts between PRs while updating consumers. We also worked to avoid bundling any forward fixes that could clutter or complicate reviews.

2. Tests

Before we migrated the component implementation, we first filled in the gaps in our component tests. We worked to ensure that both component behavior and appearance was tested, so that our reviewers could more easily spot regressions in our migration PRs.

First, we expanded our Storybook harness. Prop galleries and auto-docs render each component in isolation, one prop at a time, but the regressions we were worried about would appear in a specific combination of props: a chip whose padding collapses inside a dense ledger row, a destructive menu item that loses focus styling, a form that misbehaves inside a dialog’s focus trap. We added dozens of stories, modeling the combinations of component props for each story based on the real-world use cases across our product, and used sanitized fixture data to ensure the cases were realistic.

Second, we ensured that every component had a suite of component tests for the behavior stories can’t see: keyboard navigation, focus, value parsing, and accessibility roles, all of which were provided by Material UI. A planner enumerated test cases per component and split them into eight batches, each a ticket referencing the shared plan. The resulting nine PRs added about 11,000 lines of tests (roughly 1,270 cases), giving future migration workers a spec to build against.

Because these test PRs were independent of each other, we didn’t need to stack them all up, and could merge them as they were ready, without any coordination overhead.

3. Codemods

Most of the migration left component interfaces untouched and required the flexibility of an LLM to decide how to best adapt Material to Base UI. Icons, we realized, were the only exception. AmIcon, the component every icon in the app renders through, wasn’t easily compatible with Base UI without API change, which meant editing the hundreds of call sites across our app. That kind of change is formulaic, so a codemod fit it better than hand-written or agent-written edits, and we ran it before swapping any implementations to Base UI. Getting the one interface change out of the way first lets every later change keep true to our “don’t change the component API” rule.

The change touched about over 600 files, with eight batches of roughly 100 files ran in parallel. Once each PR passed CI, we cherry-picked all eight onto a throwaway branch and tested the combined result for visual regressions. The batches were then reviewed separately, stacked, and merged together as a single squashed commit.

4. Component Migrations

What was left after merging tests and codemods was the actual migration of our design system components from MUI to Base UI. Our goal was to merge a single stack of PRs in one go.

We forked this phase out like the others. A Fable session planned the migration, using example PRs we had carefully reviewed beforehand as a template, fanning out ten Niteshift agents by component family (menus, dialogs, selects, popovers, text fields, and so on), each building its part of the stack with one commit per component.

With the stack assembled, we deployed it to a staging link and bug bashed the whole app on the new foundation. While bashing and fixing and bashing and fixing could have taken weeks, with Supercut, we cut this down to just two days end-to-end with a far simpler process.

1. Designers, engineers, and other Ambrook team members all recorded themselves bashing the app on real devices, narrating issues they saw along the way. Instead of having to type or capture perfect bug reproductions, Supercut allowed them to just record one hour-long session, vocalizing bugs naturally: “this chip’s padding collapses,” “make this button one size bigger,” etc.

2. We passed all the Supercut URLs to a single Fable session, which used the MCP to read the transcript, identify issues, merge duplicates identified by multiple people, and filing Linear tickets for each. The Supercut MCP allows agents to get a screengrab at a particular timestamp, which meant that the tickets were rich with context, ready to be picked up.

3. After a quick review, we sent all these tickets to their own Niteshift agents in parallel, stacking fixes onto our main migration branch. A quick review on our stack’s staging link confirmed the fixes.

In parallel with the visual bashing by humans, we put the stack through its paces through a number of other checks and reviews:

• Our adversarial code review agents checked for accessibility, keyboard, focus, contract, styling, effect leaks and worked with Niteshift to automatically fix detected issues.

• We sent Fable to smoke test our most critical pages, using browser-use to visually diff production and the staging link.

• The tests introduced earlier (storybook and component tests) ran and flagged issues to Niteshift until they were all green.

• Humans reviewed every PR in the stack.

Then, just three days after opening this stack, we merged the rebuilt components into main.

5. Fast Follows

Removing MUI was our first milestone, but after merging, we set to work shipping enhancements that had been too awkward or complex to add before we migrated to Base UI. In the weeks since launch, we’ve shipped dozens of improvements to our design system:

• Accessibility. We enhanced the accessibility of dozens of components, from accordion triggers and tabs to selects and autocompletes. Nested menus now work entirely from the keyboard, and every control shares one consistent set of visible focus ring styles.

• Motion. A motion token system replaced MUI’s JavaScript transitions, with popups scaling and fading from their origin, optimized drawers’ sliding animations, and reduced-motion preferences respected everywhere.

• More powerful date pickers. We shipped a brand new set of calendar and date picker components built on React Aria, enabling us to understand dates entered in shorthand formats.

• Design token coverage. We moved all hardcoded colors to tokens, menus, selects, and autocompletes share one compact treatment, and popups no longer open behind dialogs.

• Performance. We reduced our bundle size by removing MUI and Emotion, moved transitions to run on compositor-friendly properties, and removed unnecessary re-renders.

• Component API Changes. We intentionally avoided changing our component APIs to move towards Base UI’s preference for composition over configuration (the opposite of Material UI’s approach) during the migration itself. We are now decomposing large components like AmMenu into components like AmMenu.Root, AmMenu.Trigger, AmMenu.Item, and so on.

The cleanup mattered just as much for engineers. We removed style overrides written against .Mui* class names, aligned on a consistent dataTestId contract on web and native, deleted unused components, and added lint rules to prevent backsliding.

Silence is Golden

Two weeks after the first commit, our new design system launched into production to very little external fanfare. Across the project, we merged 60 PRs across over 120 agent sessions, modified 794 files and changed 54,000 lines of code, a total of 4.5B total tokens. When it comes to migrations like these, no news is good news – we had replaced MUI without any major regressions.

We’re using agent graphs to ship large features, tech debt cleanup, and other larger migrations across Ambrook; we no longer have to choose between a mega-PR and a slow, prolonged migration. Using graphs and parallel PRs that factor out dependencies, we can merge code faster and more confidently.

Human review is a critical part of moving quickly and confidently, especially when building accounting and payments software. By designing our graphs to optimize for reviewability, we built the confidence we needed to make sweeping, ambitious changes.

Ambrook models complex financial worlds. For books to be accurate, there must be a database entry that represents each financial record that makes up a business’s finances. These records are interconnected in a complex web that also changes over time, which means that having an auditable changelog is essential. The paper trail enables us to confidently make changes and have the flexibility to reverse engineer how data was changed whenever we need.

Earlier this year, our changelog system hit a breaking point. We’d stored changelog records in Firestore for years, but coming off a massive period of growth (a 40x increase in our customer base and our changelogs collections growing to be 100x the size of the original set of records), we knew a change was needed.

This is how we migrated our changelogs to BigQuery with no downtime and saved over $100K in projected annual infrastructure costs.

The changelog stack

Changelogs tell a story about a resource. They’re useful for analytical insight and debugging, storing a before and after carbon copy of a resource along with some metadata.

type ChangelogRecord<T> = {
  id: string;
  before: T | null; // null on a create
  after: T | null; // null on a delete
  metadata: {
    version: number; // monotonically increasing, derived from the change time
    changeTime: Milliseconds;
    createTime: Milliseconds;
  };
};

Each tracked collection stores its changelogs in a subcollection nested under the document they track. A transaction at ocean/{oceanId}/fish/{fishId} keeps its history at ocean/{oceanId}/fish/{fishId}/fishChangelogs/{changelogId}, where the changelog ID is derived from the nanosecond timestamp of the change.

Changelog generation happens asynchronously. Every tracked collection has a deployed Firestore on-write listener. When a document is created or modified, the listener enqueues a task on a dedicated changelog queue with the before and after snapshots, and the task handler builds and writes the record. Nothing on the request path ever reads or writes a changelog.

We’ve also built read-path tooling on top of changelogs for our two primary use cases:

• Restores. Given a document and a point in time, we can restore it to any prior snapshot. This gives us a way of salvaging data corrupted by a bug or a rogue internal script that wasn’t reversible in our app.

• Diff inspection. Internal tools walk a document’s changelog history to answer questions like “when did this field change to its current value”, ”what did this look like before it was deleted“, or “what was the exact relationship between these twenty entities at 7:33PM thirty days ago”. While the need for asking such specific questions is fortunately rare, having the ability to ask these questions has been critical for incident response or asserting the correctness of our accounting system.

While this previous write path proved to be reliable, it was expensive due to the large volume of documents being stored in a database not designed for high-volume use cases.

To reduce cost, we’d need a different data store, and a replacement for Firestore’s built-in hooks.

Moving to BigQuery

BigQuery was the natural choice for a cheap, queryable interface for changelogs. It is inexpensive to store, ingest, and index at multi-terabyte scale. With the right partitioning and clustering strategy, it supports both console and programmatic querying, supporting our changelogs use cases at a fraction of the price.

Moving changelogs to BigQuery removed approximately 35 TB of billable Firestore storage, including document data, indexes, and metadata. That reduced storage charges by roughly $116/day, with another $116/day saved on point-in-time recovery (PITR). Removing changelogs from the nightly full-database export also reduced billable Firestore reads, saving an estimated $98/day, or approximately $2,950 per 30-day month. Write and delete operation costs were comparatively small.

Firestore’s default indexing amplified the cost of retaining this history. It creates ascending and descending indexes for non-array, non-map fields, including nested fields. Each index entry adds storage overhead. For large, deeply nested changelog records used primarily for debugging and investigations, maintaining those indexes was expensive.

The changelog archive now contains approximately 315 million records and 1.79 TB of logical data in BigQuery, costing about $33/month in storage. BigQuery’s US logical storage rate is $0.02/GiB-month, compared with our Firestore region’s $0.108/GiB-month. The savings come from both the lower storage rate and eliminating Firestore’s indexing overhead. BigQuery also includes time-travel storage under logical billing.

Pub/Sub handles approximately 331,000 changelog messages and 2.33 GB of payload per day. Publishing costs $40/TiB, and delivery into BigQuery costs $50/TiB, including ingestion. Together, those charges total approximately $0.19/day, or $5.72/month. Even at 25 times the current ingestion volume, streaming would cost only about $143/month, with storage increasing separately as the archive grows.

Together, storage, PITR, and estimated Firestore read reductions represent approximately $330/day in savings, or $9,900 per 30-day month, after accounting for the main BigQuery archive’s storage and current streaming costs. Current streaming adds less than $6/month. These estimates exclude query costs, network charges, and storage for the retained backfill table.

Designing the migration

For a migration of this scale where data loss is completely unacceptable, we wanted to have a zero-trust approach, assuming anything can break. The design had three main requirements:

1. Operate atomically;

2. Check redundantly; and

3. Fail loudly.

The migration steps overlap by design, and all steps are independent, and can be paused to confirm stability before moving on. Here’s the approach we landed on:

We started with a core, unopinionated Pub/Sub publisher class that is deliberately schema-agnostic and extensible to changelogs and beyond. This layer handles all the inner-working of the intermediate Pub/Sub layer. Early on, we started dual-writing to Firestore and BigQuery in order to monitor Pub/Sub health, primarily watching for backpressure and any dropped messages. We left the system dual-writing for a period of time so we can build up enough data to confidently compare the diffs.

For backfilling and parity-checks, a one-off script across 26TiB of data would have taken days to run. In addition to being slow, it would risk hotspotting Firestore read throughput and affecting production latency, overwhelming our disk space with intermediate local files, and potentially causing machines to fail unrecoverably.

We chose instead to launch an Apache Beam pipeline and run it on GCP Dataflow. For each collection it issues a Firestore collection-group query to create several hundred partitions, which workers then read in parallel. From there, the pipeline is a chain of ParDo transforms, each doing one unit of work per changelog: resolve the Ambrook organization ID, serialize the row, write it to BigQuery. Each transform is atomic, so a failed worker can retry without a partial write.

The real run copied 295M changelog documents in four hours. 3,000 Firestore partitions fanned across a worker pool that peaked at 500 workers and 388 vCPU-hours. Dataflow automatically scaled to the appropriate amount of workers, and our total migration cost was less than $100 for both backfilling and parity check.

As a precautionary measure, all of the rows written to BigQuery were written initially to a temporary table that was eventually merged into the finalized production table, to prevent pipeline defects affecting production tables. Rows could be validated against Firestore before the merge, and any bad batch could be discarded by dropping the temporary table.

Finally, came deleting the Firestore changelogs. To build confidence that we could take this final step, we verified signals below that made us confident that the migration had completed without failures and that we were ready to cut over:

1. Our dual-writing to BigQuery had run for several weeks without producing any unexpected diffs or monitoring alerts.

2. We had backfilled and verified parity in isolated and separate Dataflow jobs.

3. We had refactored all in-app changelog reads to read from BigQuery, monitoring read traffic to confirm that the Firestore collections were unused.

4. We ran the deletion on a test collection in our staging environment before running it in production.

While Dataflow worked well for backfill, it’s not a viable option for deletion. Firestore recommends ramping writes at 500 operations per second, increasing 50% every 5 minutes. Dataflow at 500 workers would exceed that immediately and hotspot the collection. Instead, we built a simple throttled read-then-delete process built on Firestore’s BulkWriter, tuned to what Firestore could actually sustain. Within several hours of writing, the Firestore collections were deleted.

Scale ready

This migration removed over $100K of annual Firestore costs while preserving full changelog fidelity, and the pattern we established generalizes to any large scale data migration where the old and new systems need to run in parallel before cutover.

Our new BigQuery-based changelog system holds more than 300M records at a compressed storage size of 46 GB, a 38x compression factor from 2TB. Pub/Sub processes around 330,000 messages per day and only operates at just $50 in daily storage cost.

Every engineering team feels the pull between two kinds of work. One is the steady stream of fixes and quality improvements that keep a product polished and resilient. The other is the large, ambitious features that open up new business opportunities.

With this tension in mind, Ambrook’s Product Pod set out to automate as much of the former as possible so we can focus more engineering bandwidth on the latter. Our goal was simple: increase the throughput of small and medium sized improvements without spending more time on them. We started this project during Momentum Month, where the entire company spent six weeks building agents for every function in the company. In the end, we built a “software factory” that allows operators (i.e., not engineers) to go from product problem definition to a merged PR in less than an hour, and yielded a 5x faster time-to-fix for bugs.

The Automation Pipeline

Our automation pipeline consists of four major components:

1. Linear: the state

2. Zapier: the plumbing

3. Amos: our homegrown general purpose background agent

4. Niteshift: the coding agent

Linear was the natural choice for our state, because it already holds the context of the feature requests and bugs that the agents will act on. We built a simple set of labels to identify each ticket’s state, and used label-driven webhook events to trigger agents via Zapier[0] which update labels in Linear after completing their work.

[0]: There are other ways of reacting to webhooks events. We introduced Zapier as an operator-friendly if-X-then-Y interface but will soon move these production loops to something more easily configured via code.

Triaging Tickets

The state machine begins when a ticket receives an Agent Triage label. This will trigger a Linear webhook that proxies through our application to Zapier with the ticket information as well as an idempotency key to deduplicate requests. The Zap will then split paths, separating tickets with a “Bug” label from feature request tickets which do not have that label.

Each path sends a request to our homegrown cloud agent, Amos. Anyone at Ambrook can interact with Amos in Slack or use it programmatically for automation. Amos has a shared set of skills that help it triage our tickets, root causing them, sizing the fix, flagging scope creep, and suggesting priority.

Amos will investigate the ticket, post a Linear comment with its findings, and label the ticket with its classification and reasoning.

Tickets are then sized to qualify or disqualify them for agentic implementation. Features are given a t-shirt size (small, medium, and large), with large features being set aside for an engineer to own.

Bugs are designated into three categories:

• Agent Fixable when the fix is well-defined and an agent wouldn’t reasonably find any alternative. Examples might include UI issues like a button not opening the correct dialog, a cache not busting and leading to UI inaccuracies, or an off-by-one invoicing date issue caused by timezones.

• Needs Engineer when the fix is trickier, often requiring in-depth knowledge of our accounting or payments systems. They could also be just not easily traceable by the triaging agent, or with a fix complex enough that we don’t have confidence the agent will get it right on its own. This is a dynamic set as the set of things models can do on their own is always increasing.

• Not a Bug when the behavior was intended, or the request is really a new feature.

Tickets labeled Not a Bug, labeled Needs Engineer, or sized as a large feature request exit the loop. Humans take over to either re-triage, rewrite the ticket, or close it.

Implementation

Any Agent Fixable tickets will trigger Niteshift, our model-independent cloud coding agent. Once a PR is up, Niteshift will iterate with one of several automated review agents to get the PR into a healthy shape. When this process is complete, Amos leaves a comment on the original ticket letting the ticket owner know a PR is ready and requests them to preview the fix on a staging deployment.

If required, Amos can also request input from the ticket assignee or creator and will include instructions on how to send the ticket back to the triage phase with updated context.

Review

We have a team-wide policy that the creator of a ticket shepherds it through automation. An operator who files a bug is responsible for answering Amos when it comes back with “Needs Info,” and for testing the fix on the preview link once a PR is up. Niteshift includes a short manual-testing path in every PR description to make that quick. If the fix is wrong, the operator iterates with Niteshift or pulls in an engineer.

Wherever possible we lean on automated code review to shorten review times and raise our confidence in a fix. We use Greptile, Claude code review, and run a home-grown agentic risk assessment that flags large diffs, changes to sensitive systems like accounting or authentication, and anything with undefined behavior. Today, though, nothing ships through the loop without a human looking at it.

Which human a PR goes to depends on how the ticket was classified:

• Agent Fixable bug PRs go to an engineering review rotation shared across the whole team.

• Needs Engineer bug tickets go to a separate, dedicated set of engineers.

• Feature requests go first to a member of our operations team trained to do a first pass on the complexity of the code, acting as a second set of eyes on the automated review. They pull in an engineer when the code seems more involved.

The goal of this split is to give engineers confidence that we are shipping high-quality code without cluttering the standard review request lane with auto-generated PRs.

Iterating on the loop

We use two sources of data to improve the loop over time: OTEL sessions from the individual agent runs and GitHub PRs. OTEL session data gives us details on where agents are inefficient: excessive tool calls, errors, duration. GitHub PRs (in particular, the reviews left by both automations and humans) give us insight into what the agent actually produced. Three times a week we run another automation that reviews OTEL session data and reviews to suggest automated improvements to agent instructions, tools, and so forth.

We also maintain several views of the loop in Hex and Linear in order to identify places where the tickets are getting stuck. We surface metrics like time-to-fix, time-to-merge, merges per week, human touches in the pipeline, and how long tickets are remaining stuck when humans are intended to intervene.

Faster, safer shipping across our team

Today, if a customer success operator is on a customer call and notices that some timeline events are off by a day (somewhere in the app, there’s a timezone bug), they can file a ticket, add the agent triage label, and move on to their next call. Meanwhile Amos triages the ticket, Niteshift opens a PR, and automated systems review that PR. The rep tests the fix on the preview link, an engineer merges, and the rep emails the customer back the same afternoon.

That speed of turnaround back to the customer is paramount. We’ve seen the median time to completion for bugs drop 80% since the beginning of the year, with a time to close under 24 hours and 1 in 4 bugs being resolved in under three hours.

We’ve also seen our teammates in sales, CX, and marketing make tons of small improvements to the app, often shipping improvements that could have otherwise been easily lost in the backlog. Just as importantly, the Ambrook’s engineering team is not underwater trying to fight our backlog. Instead, we’ve carefully engineered a system that ships the backlog.

In the end, we didn’t build this to ship more code. We built it so the small fixes and improvements don’t need to compete with our more ambitious work, because both are important in building the best product possible for our customers.

I’ve always been more interested in the application of software than software itself. I feel real excitement when I can map my code to a meaningful real-world contribution, whether that’s responding to a small piece of user feedback or tackling a larger-than-yourself mission like the climate crisis.

As someone with no prior experience in agriculture, Ambrook’s specific approach to climate caught my eye because it was bold; it states there can be positive-sum scenarios, where profitability on farms is linked to resilient and nutrient-rich land. Determined to contribute, I joined and have since been able to work on projects directly related to this mission.

Listening and Learning

Last year, I traveled to North Carolina with a small group to visit the Sustainable Ag Summit, where producers expressed a genuine desire to build resilient food systems — but still need the math to pencil out. I also visited and learned from our customer Bread & Butter Farm in Vermont, as they expressed a need for managerial accounting in order to secure an agroforestry grant. And most recently, I traveled to Kansas with my team to meet with another customer, Silver Creek Farm; we dove into their involvement in the CarbonNow program, where they help producers receive funding for implementing practices that sequester carbon.

From our farm visits and the many talks at the Sustainable Ag Summit, we heard one thing over and over again: Profitability is the core driver in any business decision, including regenerative and other conservation practices.

Something that has really struck me in listening to our customers is how much farmers, ranchers, and other agribusiness owners want to steward their land well. The main hurdle is that they need to trust that these decisions are financially sound — changing practices is a risk that many can’t literally bet the farm on — and there is a gap in the industry for reliable, easy-to-use tools that connect conservation practices to a farmer’s bottom line.

Bread & Butter needed assurance they could maintain profitability while adopting agroforestry practices that reduce greenhouse gases and soil erosion. Silver Creek Farm saw the CarbonNow program as an opportunity to expand their operation and increase profitability by promoting biological agents which sequester carbon.

I was really proud to work on two products that exemplify Ambrook’s commitment to bridging this gap — smart tags and receipts.

Smart Tags and Metrics

Profitability insights have always been offered at Ambrook in the form of multidimensional tagging: Tag your transactions once across different tag types (e.g., the Schedule F “Supplies” Category and the “Apples” enterprise) and receive a profit-loss statement that can be used to file taxes or view a dashboard that describes how your enterprise is performing.

From our visits with both farms, we learned where tags came up short:

1. There were missing tag types: There was no way to model a location or a conservation project.

2. Tags did not offer a solution to simple managerial accounting.

   1. Conservation grant income is distributed to Brandon Bless at Bread & Butter per acre and if he cannot track costs by this measurement he can’t know if a practice is profitable.

   2. Allen & Paul Schrag at Silver Creek farm need profitability by field in order to make land purchase decisions and know which combinations of seed, inputs, and practices are most profitable.

But after a couple months of user experience research, product requirement drafting, and engineering, we were able to ship smart tags, introducing metrics and more tag types!

Now, the Schrags can tag by location in addition to enterprises, projects, and funding programs. On their location tags, they can record metrics to assist with splitting field input costs by acre while they tag. For example, a $1000 fertilizer input cost used across 3 fields (50, 100, and 150 acres) would be automatically split (16.7%, 33.33%, 40%).

These splits roll up to our dashboards and reporting features so the Schrags can view field-level profitability, as a whole, or per-acre, at the click of a button, rather than spending hours wrangling data in spreadsheets to try to get those numbers.

Both Silver Creek Farm and Bread & Butter can perform similar analyses across many other tag types and generate per location or per enterprise profit-loss statements!

Receipt Management

Managing conservation grants (compiling paperwork, receipts, and financial data) tends to be a time-consuming activity which limits practice adoption … but not with Ambrook!

With our receipts product, users can bulk upload receipts and our system will parse receipt fields with AI, either creating a new transaction or matching the receipt to an existing one. When the time comes for a customer like Brandon to fulfill grant obligations and provide evidence of practice adoption, our filtered attachments export can instantly generate a set of attachments for transactions tagged to a certain practice.

By offering real-time profitability insights and improving grant management workflows, these features have seen lots of traction. As of this month, our platform has 190 metrics and over 400 metric quantities across enterprise, funding, project, and location tags. We also have roughly 150,000 attachments — our most dedicated receipt user has uploaded around 10,000!

From my various farm visits and coding sprints, my big takeaway is you can’t improve what you don’t measure and, as Ambrook’s platform continues to enrich the profitability insights we offer to farms and agribusinesses, we will continue to make meaningful progress toward our climate mission.

In Ambrook’s early days, when there were only a handful of farmers and ranchers using the platform, we made personalized customer service our top priority. Now, serving more than 2,000 businesses, this commitment hasn’t wavered — even when contending with the challenges of scaling up.

Our Customer Success (CX) team has always played a pivotal role in product development, ensuring that outside feedback directly influenced what we built. We know that quick iteration with our customers — including responding to bugs they surface — helps us build a better product. A side effect is that our customers build a deep sense of trust in our team that gives us the time to continue building new features that turn them into loyal customers.

Balancing Growth and Stability

As we scaled, we faced a classic challenge: balancing the need to fix existing issues with the demand to develop new features. In fall of 2024, we introduced several key features, including solving the messy inbox problem, location and project tracking, and the ability to slice a user’s data by operational units — all while seeing a huge growth in our customer base. Given the complexity of the businesses we support, this expansion inevitably surfaced previously unidentified bugs.

While major issues were always resolved quickly, smaller usability “papercuts” — like needing to refresh a page to load content or inconsistencies with newly launched tags — were often overlooked. With a small team focused on larger feature sets, it became hard to show steady progress to customers. We needed a way to build trust with our users by addressing the pain points that affected their daily bookkeeping, without slowing down new feature development.

Introducing “Bug Day”

This past January, after 40xing our customer base in the previous year, we restructured how we tackled bugs. Instead of assigning tickets to engineers at the start of the week and letting them slot fixes into their individual workflows, we dedicate one full day each week for the entire engineering team to focus on resolving customer pain points identified by the CX team. We run the day like a high-energy hackathon — regularly checking in on how the team is doing and aiming to burn down the list of issues as much as possible. At the end of the day, the engineers demo these changes to the CX team so that they can communicate changes back to customers — such as performance increases on page loads, or cutting down bookkeeping time by retaining tags on copied entries.

Over the last five months, we’ve reduced the number of bugs reported per thousand users by 56%.

These demo sessions have quickly become the CX team’s favorite weekly meeting — filled with numerous 🎉, 🙌, and ♥️s — to show our customers’ (and our) appreciation for these fixes. For the engineering team, it’s turned bug fixing into a shared, high-energy effort, with a tight feedback loop and real momentum. It’s also created a space for our distributed engineering team to come together and rally around a single objective for the day.

The Impact of a Tighter Feedback Loop

The results of this shift have been profound:

• Greater empathy and alignment: By having dedicated time and a clear process for working through outstanding bugs, engineering and CX are more in sync with one another. The CX team better understands the tradeoffs that the team needs to make between developing new features or fixing existing problems, and engineers have greater empathy for how solving seemingly small problems can have an outsized impact on customers.

• Balancing individual customers with collective impact: As we’ve grown, we’ve shifted our approach from addressing individual requests to tackling common customer pain points. By involving the CX team in solving these issues, we ensure that our solutions not only address widespread concerns while feeling connected to the impact on individual customers.

• More effective bug fixes: We’re spending the same amount of time on bugs, but resolving issues in a way that connects engineering and CX more closely. The greater customer understanding and empathy among the engineering team has led to improved testing coverage for new features and a reduction in newly created bugs: Over the last five months, we’ve reduced the number of bugs reported per thousand users by 56%.

By strengthening team collaboration and instilling a customer-first mindset, we’ve kept the customer experience as the foundation for what we build daily. This approach has helped us maintain trust and responsiveness with our customers, even as our user base expands.

What’s Next?

We grew exponentially in 2024, and we’re just beginning. This year, we’re planning more big feature launches — like inventory and more AI-enabled features — all of which are centered around what our existing and prospective customers need to be successful. As we build these features and think towards another massive year of growth, we also need to ensure we’re building the right things at the right time to maintain the growth we saw last year and draw in a new set of customers.

We’re working on more ways for us to stay close to what a user experiences in our product every day:

• More time hearing from customers during All Hands: We’ve always shared clips from the CX and sales teams conversations with our customers during our Friday All Hands meeting. We’re going to build on this by hosting a conversation with a customer during this meeting each month.

• Focusing on improvements as well as bugs: We strive to build an incredibly high quality product. As we’ve worked through the backlog of bugs on Bug Day, we’ve started to look at bringing in the small workflow improvements that add up to big improvements but often get overlooked for bigger changes. This gives us the opportunity to continue to work closely across teams while showing customers that their experience is improving all the time.

• Design Partner programs: We built our core product with a group of amazing customers who have agreed to give us early feedback and beta test new features, called Design Partners. As we grow, we’re continuing to build groups of Design Partners who can help us create the tools that they need to see their business grow.

If you’re interested in learning from customers every day in ways like this and more, we’re hiring across teams! See more at ambrook.com/careers.

At Ambrook, we’re building a comprehensive financial management system for farmers — the stewards of our most vital natural resources. As a product for farmers across the United States, we’re serving a customer base constantly on the move, using network connections of varying quality on a wide array of devices. Our customers trust us with their operations, and we have an obligation to provide a product that lives up to their expectations. And when it comes to financial software, performance and reliability are non-negotiable.

Incidents of inconsistent or delayed data or slow interactions across our web and native applications can impact customer trust. To gain better visibility beyond basic metrics and ensure the reliability our expanding user base expects, we chose to adopt OpenTelemetry for full tracing of our platform.

Ambrook’s systems are entirely in TypeScript, and rely heavily on open-source software. Our application is a Next.js monolith, and to support our React Native mobile app we serve all data to clients via a GraphQL API, powered by Apollo Server. Our data primarily lives in Firestore, though we’re in the process of migrating to PostgreSQL. This stack serves us well, and we had hoped that being built on open-source, battle-tested technologies would ease our tracing implementation.

Ultimately this was less straightforward than we had hoped; we encountered a number of challenges building out our tracing data. However, overcoming these challenges allowed us to improve the performance of our application by 30%, giving our customers a responsive experience they can trust.

Challenge #1: Instrumenting Apollo Server

Once we instrumented basic request tracing with the @opentelemetry/auto-instrumentations-node package, the next challenge was instrumenting Apollo Server. While OpenTelemetry has a GraphQL auto-instrumentation, when deployed in production our GraphQL tracing data had disappeared.

This particular auto-instrumentation patches specific JS files in the graphql npm package, which are not available in production because Next.js bundles our backend code into optimized bundles. Thus, the specific files in that package are not available in the filesystem and no GraphQL operations were instrumented properly.

We were ultimately unable to find an open-source implementation of a runtime GraphQL tracing solution, so we wrote a custom Apollo Server plugin to create spans for each Query or Mutation. We use Apollo’s lifecycle hooks to create an active span at the start of each query, and end it when the query finishes resolving.

This instrumented our queries, but didn’t give us much visibility into the cost of each component of our query execution. We paired this plugin with code that wraps every resolver in our schema with a span, to give our traces high-fidelity data about each GraphQL query’s execution.

With our custom Apollo tracing in place, we had a clear understanding of high-level performance, and creating custom spans with the OpenTelemetry SDK allowed us to generate finer-grained spans for internal codepaths. The last piece of the puzzle was tracing our database to understand where we had slow queries or were executing too many database operations.

Challenge #2: Database Tracing

Tracing our database operations presented its own set of challenges. We use both Firestore and PostgreSQL, each requiring different instrumentation approaches. PostgreSQL was easy to instrument, thanks to an existing instrumentation package for postgres.js which worked out of the box.

While the official Firestore SDK does include tracing events, they’re incredibly high-volume and unfortunately have limited useful data attached, such as the specific collection being queried. We chose to write our own wrapper around the Firestore client that created spans for each database operation. Fortunately, since each of our database collections passes through a shared ORM-like abstraction, this proved fairly straightforward. We simply wrapped every Firestore operation with tracing code similar to our Apollo resolver code:

Challenge #3: Client Tracing

As a team, we made the decision to not build any infrastructure to link backend traces to client traces. Given our backend is fully isolated from our frontend via our GraphQL API, a full-stack trace for our app is unnecessary, and would likely produce traces so overwhelming they’d be difficult to grok and consume. Instead, we implemented separate client and server tracing to allow us to optimize the runtime user experience separately from our backend performance and reliability.

Tracing client code is deceptively hard, as OpenTelemetry’s browser instrumentation was not designed for modern client-side applications which comprise more than a static HTML file. Because modern applications have minimal markup in their HTML file by default, markup is mostly hydrated in JavaScript, and API requests are executed outside the scope of the initial HTML page load, traditional client tracing misses most of the interesting parts of loading Ambrook.

Instead we built more custom instrumentation. We hijacked the basic OpenTelemetry browser instrumentation and introduced a concept of a “session” on top of it, which starts when the user opens the page and completes when the page’s main content is rendered. This gives us visibility into the full lifecycle of loading JavaScript bundles, rendering, and executing API requests that make up a full client-side page load.

Picking a Storage Provider

Picking a provider to store and serve our tracing data proved tricky. Many providers that would allow us to send a high volume of data had very restrictive limits on the amount and types of data we could send. As a startup with a wide distribution of customer needs, the ability to track granular attributes like account IDs within our tracing data is critical. In addition to traces, we also need this platform to support timeseries metrics for data that isn’t well-suited to tracing. Lastly, we need the ability to run complex queries across spans to build dashboards and track SLOs for our platform.

Honeycomb ultimately emerged as our preferred option. Honeycomb encourages “wide” events, allowing up to 2,000 attributes on each span in a trace, with no limits on unique values. Their pricing structure simply prices by event, meaning we can send as much data as we want for a fixed cost. Most importantly, timeseries metrics in Honeycomb are just “events,” so they fit nicely into the billing, and their advanced query and visualization capabilities allow us to dive deep into traces, performance problems, and error rates. For just $130 per month we are able to send 100 million events with near-zero operational cost, and perform important tasks like alerting on performance changes and defining team-wide SLOs.

The Payoff: Real-Time Insights

Despite the challenges, the payoff has been substantial. We now have unprecedented visibility into our application’s behavior. We can see exactly what happens when a customer interacts with our application, how that interaction flows through our system, and where any bottlenecks or errors occur.

This visibility has already helped us identify and fix several issues that were previously difficult to reproduce or understand. We discovered certain GraphQL queries which were triggering unnecessary database reads, allowing us to save over 10 million unnecessary reads from Firestore each month. We learned about several N+1 query problems in our financial reporting product, reducing the time required to generate financial statements by 85 percent. Lastly, we were able to uncover several smaller data duplication issues in core APIs that reduced our 90th percentile query duration for queries outside of our reporting product from 0.9 seconds to 0.7 seconds.

With new tracing in place and increased visibility into the exact set of operations that make up the most complicated parts of our product, these issues were immediately visible and actionable to the team, allowing us to serve our customers’ needs better than ever before. All of these improvements have compounded to improve overall application performance more than 30 percent, and our newly improved ability to dive deep into errors has helped solve even more issues that would have otherwise gone unnoticed.

If you want to improve the experience of your application, the first step is having the right data to do so. Gathering detailed data about your systems enables a data-driven approach to ensuring your customers see a product you can be proud of.

“Why can’t we just write this code once and have it just work across Web, Android and iOS?” As a mobile engineer who has spent both a significant portion of his career copying the exact same product from iOS to Android, I’ve asked myself this question many times.

At Ambrook, we’re lucky to have the opportunity to approach the challenge of supporting multiple platforms without the constraints of legacy engineering decisions. As a result, we’ve been able to share code across web and mobile, allowing all of our entire engineering team (currently four engineers) to contribute with little overhead.

Ambrook is building a suite of financial tools for farmers that needs to be consistent and fully-featured across desktop and mobile. So that farmers can use our tools in the field, they must work well on slower internet connections and while offline. As an early stage company, we are prioritizing rapid delivery of new features as we get feedback from our users.

The Project

When I first joined the Ambrook team, I was tasked with figuring out how to translate our existing web app to mobile. The web app was written in Typescript using React DOM and Next.js, which made it a tempting target to try using React Native. If successful, using React Native would mean that we could share code between platforms, greatly reducing both the cost of copying existing features and (more importantly) the cost of every new feature we’d need to build going forward.

At the same time, we wanted to be humble about the reasons why other companies have struggled to adopt cross-platform technologies. ​​A common issue that we avoided is the need to work with existing native product code, a requirement that can significantly negate the productivity advantages of using a cross-platform framework.

There were three main questions that we set out to address from the beginning:

1. Can we define best practices and patterns around cleanly separating presentation and business logic to allow for the inevitable UI divergence between platforms?

2. Do third-party libraries exist that cover common app needs (ex. navigation, API access, graphing), and do they work well across platforms?

3. Does working cross-platform significantly speed up development time compared to just writing the code twice? Is the system easy for someone familiar with our existing codebase to be productive in?

We decided to leverage React Native as a compatibility layer between the shared business logic from our existing React (Web) codebase and platform-specific APIs. React Native allows us to bridge the differences between the UI APIs on each platform: DOM on Web, UIKit on iOS, and Android’s View system. We chose to adopt this cross-platform approach because it lets us share business logic between platforms, leverage high quality open source libraries, and rapidly develop and QA new changes to the app.

Sharing Business Logic

One of the main benefits of our cross-platform strategy is that we are able to share business logic between web and mobile. In fact, all major screens in our app share the same business logic across platforms; it was easier to adapt the existing Typescript-based business logic to be platform agnostic than to rewrite the same business logic multiple times.

An area where we chose not to share code is in the UI layer above the business logic. The guiding principle that we used was to share as much code as practical (business logic and some views) while allowing for some level of divergence to allow for native-feeling UIs and to use the APIs and technologies that felt best for each platform.

On the web front, this means using CSS-based media queries to create a responsive website and using CSS for things like sticky headers. On mobile, we add support for pull to refresh and double tapping on the navigation bar to scroll to the top of a screen. For both platforms, the lowest level components (like buttons, forms, etc.) are implemented separately as part of our design system, which we talked about in a previous post.

Leveraging Open Source Libraries

By using React Native, we’re also able to tap into a rich open source ecosystem that has largely removed the need for us to write platform specific native code. Our experience has been that most common app use cases have mature, well-maintained libraries.

Some of our favorite libraries in use are:

• Apollo Client, a GraphQL client implementation with support for optimistic mutations, cache normalization and persistence, and client-side state. Apollo scales well from a limited persistence web environment to an offline, stateful mobile environment.

• Victory, a charting library with support for many different chart types.

• React Navigation, a mobile navigation library with support for tabbed navigation, modals, and navigation stacks. It also has first class URL handling, which makes bridging the gap with web very simple: just use URL-based navigation everywhere.

Rapid Local Development

Making a small code change and having it be reflected on device can take anywhere from a few seconds to several minutes in the largest apps. Reducing this incremental build time pays dividends beyond simple time savings. As the iteration time gets shorter, we’re able to both make more rapid and isolated code changes, greatly enhancing comprehension of the code that those changes are being applied to.

Both our web app (via Next.js) and our mobile app (via React Native) support Fast Refresh, allowing changes to components to be reflected in a matter of seconds without losing either app or individual component state. Fast Refresh has been indispensable. When I’m not sure of how a UI will look, I can save small changes several times in a row, tweaking one layout property until everything looks right. Frequently, I keep a browser window and simulator open side by side to reflect live changes on two platforms simultaneously.

Rapid QA on Pull Requests

As an early-stage company, we frequently ship new features and fixes to our app. In order to prevent new bugs from being introduced during this process, we made it easy for developers to manually test changes as a normal part of their review flow.

On web, we deploy every open pull request to a unique Google Cloud Run URL so that opening the new version of the app is a single click away.

On mobile, we generate a QR code that can be scanned by a phone running the Ambrook app to download and run the latest Javascript bundle live on the phone. Native code changes can’t be previewed using this system, but it’s worked well for us because most of our changes do not involve native code. The technical approach used here is similar to that of Shopify’s React Native app, which they’ve described in this blog post.

Our Takeaways

For Ambrook, building a cross-platform web and mobile app from a single codebase has saved us significant time and effort. Other teams considering a similar approach can take a few points away from our experience:

• You can expect near-full sharing of business logic between platforms, but having divergent UIs (either at a design system level or at an entire screen level) may be most practical and preferable to create an app that feels native on each platform.

• Open source libraries currently cover most common app needs and effectively abstract away platform differences, removing the need to write native code for feature development.

• The developer experience improvements in React Native (Fast Refresh and QA via QR codes) are significant and would be difficult to accomplish in native due to its use of statically compiled languages.

Finally, as a quick catch-all, a few bonus recommendations for adopting our stack:

• We found it very helpful to use boilerplate apps when starting, both to understand solutions for common issues (global state management, i18n, etc) and to reduce initial setup time.

• Although most engineers on this stack don’t need to know about the underlying iOS / Android systems, you’ll still need someone with a working knowledge of the native build systems and IDEs in practice to debug build and configuration issues. This is something that the Expo community is working on.

• Not all React libraries work well across both native and web, so you’ll need to be deliberate when choosing which to use.

Conclusion

Thanks to our lack of legacy code, we’ve been able to pick the best of breed tools for our situation: React Native on Mobile and React/Next.js on Web. This technology is instrumental in our ability to rapidly and efficiently iterate on our mission of helping to make farmers more profitable and sustainable.

As an early-stage company, it’s imperative that we build and test ideas quickly. And, with limited engineering and design resources, we want to be able to build high quality interfaces without robust design speccing or redlining each iteration. To accomplish this, we decided to invest early in a strong design system foundation, not just in our design tools, but also in code.

Investing early in our design system and maintaining parity between Figma and code base enables our engineering team to autonomously and meaningfully contribute to our product without needing a pixel-perfect mockup in every situation.

All of Ambrook’s products, from our marketing website to our Funding Library, cards and bookkeeping tools are built with these same components, written once by engineers then used everywhere. We’ve built our design system on a single design stack:

• Figma components with variants for design

• React, Styled Components, and Material UI on web

• Storybook for visual testing

When used in concert, these design system components let us plug together high quality user interfaces without engineers having to worry about things not looking right.

It all begins in Figma

Ambrook uses Figma component variants to design consistent interfaces. With components, we can have a central style that gets reused everywhere. And, with Figma variants, we spec out what each possible combination of properties looks like, and then can select the size, color, lightness, hover state, etc from the sidebar easily. This means that when engineers see the button component, they know that it’s the same one that we have in code.

When constructing UIs in Figma, all we need to do is customize the properties of our components to construct interfaces. We use autolayout, which correlates directly with flexbox in code. When engineers view our Figma projects, they can inspect to see which components are used with what configurations, and translate that directly into React code.

Shared Code and Interfaces

Basic foundational values like colors are shared across components. Because our frontend, backend, and mobile app are all written in Typescript, these type definitions are shared across our stack.

We separate business logic and design implementation, creating an agnostic UI layer that we can use with multiple implementations per platform. This layer makes it easy for us to remove third-party dependencies like down the line if we need to optimize for performance, for example.

For each component in Figma, we define a React component that takes on similar properties to those outlined in Figma. For our button, that means size, color, light, disabled, etc. We prefix Ambrook design system components with Am, and we keep them in a frontend/design-system folder.

// frontend/design-system/buttons/AmButton.tsx
import { StyledAmButton } from './AmButton.style';
// ...
const AmButton = (props: AmButtonProps): JSX.Element => {
  // ...
  return (
    <StyledAmButton ... />
  );
};
export default AmButton;

This allows us to write easy-to-read code:

<AmButton size="large" color="blue" href="/careers" light>
  Click Me
AmButton>

The AmButton component is responsible for any business logic, like support for situations where the caller passed an href (e.g. a button that is actually a link), an onClick prop (e.g. a button that submits a form), both (e.g. a button that is a link but also logs to Segment in the background), or neither (e.g. a button nested in a card which doesn’t actually do anything but passes the click event to its parent). By supporting all the different possible use cases for what a “button” can do in a single AmButton component, we ensure that all buttons look the same, regardless of what clicking them does.

Importantly, the AmButton component isn’t responsible for presentation. We have per-platform implementations, using Styled Components and Material UI on web, and React Native Paper for iOS and Android. We store these implementations in neighboring .style.tsx and .style.native.tsx files:

// frontend/design-system/buttons/AmButton.style.tsx

import Colors from 'styles/colors';
//..
export const StyledAmButton = styled(Button)<StyledAmButtonProps>`
  background-color: ${({ $color, $light }) => $light
    ? Colors[$color][10]
    : Colors[$color][50]};
  // ...
`;

The main component file is then responsible for rendering a StyledAmButton. The props prefixed with a $ will not be passed to the HTML, and will just be used within the styled component itself.

<StyledAmButton $size="large" $color="blue" href="/careers" {...moreProps} />

For some design system components, we build them directly from View components or HTML elements. For more complex ones, we wrap Material UI and React Native Paper components, which offer robust style implementations like ripples and animations, as well as accessibility features out-of-the-box.

Visualizing in Storybook

In the examples above, we’ve been using a simplified version of our components. In reality, AmButton takes over 20 different props! As components become more complex, being able to verify how components are supposed to look and work in all of their variants can be difficult. To make this easier, we’re starting to use Storybook.

Storybook plugs into the type definitions for our components, and creates properties and controls that can be played with in their pre-built UI.

We can define stories with just a few lines of code, which reduces the maintenance effort to near-zero. We store our stories next to our components, as a neighboring .stories.tsx file. Here’s what our button stories look like:

// frontend/design-system/buttons/AmButton.stories.tsx

import AmButton, { AmButtonProps } from 'frontend/design-system/buttons/AmButton';
import { Meta, Story } from '@storybook/react/types-6-0';
import React from 'react';

export const Normal: Story<AmButtonProps> = (args) => (
  <AmButton {...args}>Hello World</AmButton>
);

export const WithStartIcon = Normal.bind({});
WithStartIcon.args = { ...Normal.args, startIcon: <Decagram /> };

export const WithEndIcon = Normal.bind({});
WithEndIcon.args = { ...Normal.args, endIcon: <ArrowRight /> };

export default {
  component: AmButton,
  title: 'Components/AmButton',
} as Meta;

Our storybook components allow us to play around with the possible properties that can be provided to a component, and see how they interact.

Moving Fast

Bringing our design system into code takes time up front, as well as maintenance along the way. But so far, our investment has paid off, letting us experiment and iterate on our product without worrying about getting the design details right.

When I started working on Ambrook, adopting Next.js was a clear choice. I liked that it flexibly combines statically generated (SSG) pages (like blog posts, marketing sites), with server-side rendered (SSR) pages (like our app and account pages), and merges it all together with a smart client-side navigation scheme.

Firebase Authentication has been my go-to authentication choice for years. It handles all of the complexities of managing multiple authentication methods (password, Facebook, Google, phone number, magic link) into a single account system.

In using both, I hoped to create a best-in-class user experience. Here’s what I wanted:

• Server-side rendered private pages that load the user’s data without lots of spinners.

• Statically generated public pages, that show the same content for all users.

• Cookie-based authentication that lets users start to input their information and use our app before being asked to make an account, saving progress as they go.

• Server-side redirects for users that load a private page without being logged in.

• Client-side redirects for users that click an onsite link to a private page without being logged in.

Furthermore, I had some developer experience requirements:

• Make it easy to introduce new pages and API routes that are auth-guarded.

• Reduce the likelihood that private pages are accidentally exposed.

While the basic integration was straightforward, the combination of these two tools created a fair number of cases to consider. Next.js lets users access pages by client side navigation and server side navigation. Firebase Authentication issues ID tokens that only last for an hour, after which they need to be refreshed using the client-side SDKs.

Authentication and SSR

Authenticating pages accessed via client side navigation is easy – the Firebase SDK will log users in automatically if they have an account, and private pages can check the currentUser. But for the initial HTTP request, we’ll need to use a cookie to store the user’s ID token to be verified on the server. Here’s how it works:

First, we sign in the user using the Javascript SDK:

const { user } = await auth().signInWithCredential(cred);

Then, on the client, we generate an ID token and write it to the user’s cookies.

import cookie from 'js-cookie';

export const persistUserCredential = (user: firebase.User) => {
  const token = await user.getIdToken();
  cookie.set('token', token, {
    expires: 1,
    path: '/',
  });
}

Finally, when the user next requests an SSR-powered page, the cookies are passed along in the request headers. We can then verify the ID token to validate a user’s identity.

// Some code is missing here, I'll go into more detail later.
const token = getCookie('token', ctx.req.headers);
const { uid, email } = await verifyIdToken(token);

Maintaining State When Users Refresh

We want users to save our user’s progress before they enter their email address, and connect their saved progress with a full account later if they wish. To do this, we’re using Firebase’s authentication method built for this purpose. To integrate this into Next.js, we modify our custom _app.tsx. Here’s how it works:

1. Every time a page renders on the client, our _app.tsx‘s render function will run. We use the useEffect hook to run our setup code on the first render only.

2. We set up a listener to changes in the Firebase Authentication state using firebase.auth.onAuthStateChanged, which takes a callback that contains the current user. It runs first with null, and then once Firebase has loaded the logged in user from the local session.

3. We either persist the user’s credentials to the cookie, if they’re logged in, or log them in anonymously if they are not.

// pages/_app.tsx
import { AppProps } from 'next/app';
import React, { FC, useEffect } from 'react';
import firebase from 'firebase/app';
import persistUserCredential from 'utils/auth/persistUserCredential';

const MyApp: FC<AppProps> = ({ Component, pageProps }: AppProps): JSX.Element => {
  // ...
  useEffect(() => {
    return firebase.auth().onAuthStateChanged((user) => {
      if (user) {
        // If the user just signed in, we call the code to create the cookie.
        persistUserCredential(user);
      } else {
        firebase.auth()
          .signInAnonymously()
          .catch(function (error) {
            // Handle Errors here.
          });
      }
    });
  }, []);
  // ...
  return (<Component {...pageProps} />);
};

export default MyApp;

Next, we’ll set up the code that verifies token on the server.

Handling redirects

It’s important that users get redirected to the login page if they’re logged out but trying to access a private resource, no matter if they navigate on the client or directly to a private URL. I use the redirect feature introduced in Next.js 10, which allows GetServerSideProps to return a redirect object that will be executed on the client or server, depending on the user’s context.

Initially, I was able to make all of this work using Next.js’s GetInitialProps, which runs when a page is first loaded, on the client on client-side navigation, and on the server on server-side navigation. This method is deprecated in favor of GetServerSideProps however, and not recommended. Read more about data fetching in Next.js and getInitialProps.

I wrote a wrapper function, withPrivateServerSideProps that wraps a page’s GetServerSideProps function:

// withPrivateServerSideProps.ts
import { GetServerSideProps } from 'next';
import isAuthenticated from 'utils/auth/isAuthenticated';

/**
 * This function wraps a page's GetServerSideProps function. It passes the
 * `redirect` object if the user needs to authenticate, and calls the wrapped
 * function otherwise.
 */
export default function withPrivateServerSideProps<P>(
  getServerSidePropsFunc?: GetServerSideProps,
): GetServerSideProps {
  const withPrivateSSP: GetServerSideProps = async (ctx) => {
    const _isAuthenticated = await isAuthenticated(ctx);

    // If not authenticated, we return a redirect object that instructs
    // Next.js to redirect to our login page.
    if (!_isAuthenticated) {
      return {
        redirect: {
          destination: `/login?redirectTo=${ctx.resolvedUrl}`,
          permanent: false,
        },
      };
    }

    if (getServerSidePropsFunc) {
      return await getServerSidePropsFunc(ctx);
    }
    return { props: {} };
  };

  return withPrivateSSP;
}

This code uses a helper function, isAuthenticated, to determine if the user is authenticated. It uses the Firebase Admin SDK’s verifyIdToken function to validate the token and look up the user’s basic details.

// utils/auth/isAuthenticated.ts
import { GetServerSidePropsContext } from 'next';
import { getCookie } from 'utils/auth/cookies';

export default async function isAuthenticated(
  ctx: GetServerSidePropsContext
): Promise<boolean> {
  const token = getCookie('token', ctx.req.headers);

  if (token) {
    const { uid, email } = await verifyIdToken(token);
    // An anonymous user may have a UID, but authenticated users must have an
    // account (an email address).
    return !!email;
  }

  return false;
}

Here, the getCookie function is parsing the cookie header, and either returning the token key or undefined.

This makes for a very simple integration into a private page, like /account:

// pages/account.tsx
import withPrivateServerSideProps from 'hocs/withPrivateServerSideProps';
import React from 'react';
import { getAccountDetails } from 'lib/account'
import Account, { AccountProps } from 'screens/Account/Account';

const AccountPage = (props: AccountProps): JSX.Element => {
  return (
    <Account {...props} />
  );
};

export const getServerSideProps = withPrivateServerSideProps(
  async (ctx) => {
    try {
      const accountDetails = await getAccountDetails();
      return { props: accountDetails };
    } catch (error) {
      return { props: {} };
    }
  },
);

export default AccountPage;

Handling expired tokens

Firebase’s ID tokens expire after about an hour, so it’s likely that users that request a page will need to refresh their token in order to be authenticated. If this is the case, we redirect to the /login page, just like if they were logged out. However, in this case, we detect the presence of an existing token and attempt to refresh it. Here, we use firebase.auth().onIdTokenChanged, which detects not just changes in the user’s logged in status, but also when their ID token is refreshed automatically by Firebase. On the login page, we detect this state, persist their new ID token to the cookie, and redirect them to where they where going.

// pages/login.tsx
import firebase from 'firebase/app';
import { useRouter } from 'next/router';
import persistUserCredential from 'utils/auth/persistUserCredential';
import { useEffect } from 'react'

const LoginPage = ({
  redirectUrl
}: {redirectUrl: string}): JSX.Element => {
  const router = useRouter();

  // ...

  useEffect(() => {
    return firebase.auth().onIdTokenChanged((user) => {
      if (user && !user.isAnonymous) {
        persistUserCredential(user).then(() => {
          router.push(redirectUrl);
        });
      }
    });
  }, [redirectUrl, router]);

  return (
    /* login page content */
  )
};

export default LoginPage;

Lots of cases to handle!

Between client-side and server side navigation, private and public pages, and the user’s authentication state (logged out, logged in, expired token), there are a lot of cases to handle. But by carefully managing and correctly passing around the ID token, we can allow Next.js to authenticate a user from their ID token in whatever context we find them.

There were a couple of features we added that I didn’t include here, but they all follow from the structure outlined above. Asynchronous API requests using fetch() do not pass cookies by default, so I had to write a wrapper that includes the ID token in requests to my API routes. Also, we ended up building out “account-enhanced” pages that load basic content for logged out users and more content for logged in users. These pages follow the more traditional SPA model: Load the page and show a spinner, request the authentication state asynchronously, and then load the logged-in content (or not). We also use Redux in our app, but I removed that code from the samples above for clarity.

Hopefully this guide is helpful for your next project! If you have any questions, feel free to reach out to me on Twitter.