DEV Community: knot crochet

I Rebuilt ClickFunnels' One-Click Upsell. The Hard Part Wasn't the UI.

knot crochet — Thu, 27 Aug 2026 20:01:37 +0000

One-click upsell is the page that appears right after someone buys: "add this for $29, no need to re-enter your card." ClickFunnels built a business on it. I rebuilt it, and I want to be precise about where the work actually was, because the visible part is a button and a price.

The button took an afternoon. The four failure orderings behind it took weeks.

Problem one: the two providers have opposite shapes

I support Stripe and PayPal. "Charge the customer again without asking for the card" means two genuinely different things.

Stripe. Vault the payment method during the base checkout, then create a second, independent charge later. The vaulting happens at intent creation:

// Vault the card for later one-click upsell charges: a Customer + setup_future_usage=off_session
// makes the confirmed payment method reusable off-session.
setup_future_usage: customerId ? 'off_session' : undefined,

with one rule that is not negotiable: vaulting is best-effort and must never block the base sale.

} catch {
  customerId = undefined; // vaulting is best-effort; never block the base sale
}

If creating the Customer object fails, the buyer still buys. They just don't get offered upsells. Losing the $79 base order to protect a hypothetical $29 upsell is the wrong trade, and it's an easy one to get backwards when you're writing the upsell feature and the upsell feels like the point.

PayPal. There is no second charge. The order sits approved-but-not-captured, and an upsell is a PATCH that raises the amount, followed by exactly one capture when the buyer leaves the upsell chain:

// PayPal: the order is approved-but-not-captured. PATCH it to add the upsell amount + record the
// line in the snapshot (no charge). When the buyer leaves the upsell chain, capture once - the order
// then materializes with base + all accepted upsells.

So for one provider "accept upsell" means money moved. For the other it means a number in a pending authorization changed and money hasn't moved at all, including for the base order.

I tried to hide this behind one chargeUpsell() port. Don't. The abstraction has to sit further out, at the HTTP boundary, where both paths converge on the same response shape (success, action, order, nextStepUrl). Everything below that is two flows, and pretending otherwise produces a port whose contract is a lie for one of its implementations.

Problem two: idempotency, twice, differently

A buyer double-clicks. A phone loses signal mid-request and the browser retries. This is not an edge case on a page whose entire design encourages one impulsive click.

Stripe gets an idempotency key scoped to the specific upsell step:

idempotencyKey: `${tenantId}:${saleRef}:upsell:${upsellIndex}`

and the local ledger row is written with the same key, with the unique-violation swallowed:

} catch (err) {
  if ((err as { code?: string })?.code !== 'P2002') throw err;
}

PayPal can't use an idempotency key for this, because the operation isn't "create a charge", it's "set the total to a new value". A retried PATCH with the same intent would be indistinguishable from a legitimate second upsell at the same price. So idempotency is a state check against the snapshot:

if (!snapshot.lines.some((l) => l.upsellIndex === upsellIndex)) {
  // append the line, recompute the total, patch the order
}

Same guarantee, completely different mechanism, because the underlying operation is set rather than add.

Problem three: getting it into the merchant's store

This is the part nobody writes about and the part that generates support tickets.

The merchant's actual fulfillment happens in Shopify or WooCommerce. So a sale with three accepted upsells has to arrive there. As what, exactly?

Two legitimate answers, and I made it a setting rather than picking one:

merged: base plus all accepted upsells as one external order. One shipment, one packing slip. This is what a single-warehouse merchant wants.
split: the base as one order, plus one standalone order per upsell, each tagged back to the parent. This is what a merchant with per-supplier dropshipping needs, because those items ship from different places.

The dispatch is one function, and the interesting lines are the two short-circuits:

export async function executeHandoffForSale(saleRef: string, deps: HandoffForSaleDeps): Promise<void> {
  const mode = await deps.getFulfillmentMode();
  if (mode !== 'split') {
    await deps.runMergedHandoff(saleRef);
    return;
  }
  const ctx = await deps.loadSplitContext(saleRef);
  if (!ctx || ctx.upsellLines.length === 0) {
    await deps.runMergedHandoff(saleRef);
    return;
  }
  await deps.runBaseOnlyHandoff(saleRef);
  for (const u of ctx.upsellLines) {
    try {
      await deps.pushIndependentUpsell({ saleRef, upsellIndex: u.upsellIndex, parentOrderNumber: ctx.orderNumber, line: u.line, customer: ctx.customer });
    } catch (err) {
      logger.error('split upsell push failed', { error: err, saleRef, upsellIndex: u.upsellIndex });
    }
  }
}

A sale with zero upsells is byte-identical in both modes, so it takes the merged path regardless of the setting. That's not an optimization, it's a correctness statement: the mode should not be able to produce two different results for the same input.

And the loop is deliberately best-effort. One failing sub-order must not prevent the other sub-orders or the main order from existing. A retry job picks up the failure; a thrown exception would strand the whole sale.

Problem four: the one that actually loses money

Here's the ordering that took the longest to see.

In merged mode the push to the merchant's store is held until the buyer finishes the upsell chain, so the order can be assembled complete. Fine. But the buyer isn't obligated to follow that script. They can close the tab, come back from an email an hour later, and accept an upsell after the main order has already been pushed.

Now the upsell cannot be folded into an order that already exists downstream. If you do nothing, the charge succeeds and the item is never fulfilled. The customer paid and gets nothing. That is the worst failure mode in the entire system, and it is completely silent - your payment numbers look great.

The handling is a degrade, not an error:

} else {
  // The main order was already pushed to the backend (handoff not deferred), so this late upsell
  // cannot be folded into it - push it as an independent external order tagged to the parent.
  // Covers merged late-degrade and split late-accept; prevents the upsell from being lost.
  await pushUpsellIndependently(saleRef, intent, line, upsellIndex).catch((err) =>
    logger.error('Independent upsell push failed (cron will retry)', { error: err, saleRef, upsellIndex }));
}

A merchant configured for merged fulfillment gets a second order they didn't ask for, tagged parent:<mainOrderNumber> so it's traceable. That's strictly better than the alternative, and the tag is what makes it defensible when they ask why.

The ordering rule I'd keep

Charge, then persist, then push, and treat everything after the charge as retryable:

const order = await appendLineToOrder(saleRef, line, locals).catch((err) => {
  logger.error('Upsell charged but appending to order failed', { error: err, saleRef, upsellIndex });
  return undefined;
});

The buyer sees a success page even if the internal bookkeeping failed, because from their side the transaction is complete - it is. The log line is written so that the reconciliation job and the human reading it both know exactly which sale is inconsistent.

The general rule: the irreversible step goes last among things that can fail independently, and everything after it must be retryable and must not be able to fail the response. Every bug I hit in this feature was a violation of that sentence in one direction or another.

The UI is a button. Everything worth writing down is in what happens after someone taps it twice on a train.

I Built Runtime Islands for Astro Because My Pages Live in a Database

knot crochet — Tue, 25 Aug 2026 20:01:27 +0000

Astro's island model has one assumption baked into it: you know at build time which components need JavaScript. You write client:load on a component in a .astro file, the compiler sees it, and it emits exactly the right script tag.

I don't know that at build time. The pages my app renders are drag-and-drop pages. A user arranges blocks in a visual builder, and the result is a JSON tree in Postgres. At build time, the page doesn't exist yet. At request time, I have a tree of maybe forty component instances, of which perhaps three actually need to run in the browser.

So I built runtime islands: server-render the whole tree to static HTML, mark only the interactive nodes, and let a single client script figure out at runtime what to mount and what to download.

The two options I rejected first

Render the whole page as one React root. This is the obvious move and it's what I did first. It works, and it means a landing page with a hero image, an FAQ accordion and a footer ships the entire component library to the browser so that React can re-render markup that will never change.

Mark every component as interactive. Same outcome with more ceremony.

Both fail for the same reason: the ratio. On a typical landing page in this system, the interactive components are the countdown timer and nothing else. On a checkout page, it's the address form, the card form and the coupon field. The static-to-interactive ratio is somewhere around 10:1, and paying for the 10 to get the 1 is the whole thing island architecture exists to avoid.

The server half

Puck (the builder library) takes a config of components and a data tree, and renders it. I wrap the config before rendering: any component whose name is in the interactive set gets its render replaced by one that emits a marker div plus its own props, serialized.

function islandRenderer(componentName: string, renderComponent: (props: any) => any) {
  return function RenderIsland(props: any) {
    return createElement(
      'div',
      { 'data-island': componentName, 'data-island-id': props.id || '' },
      createElement(renderComponent, props),
      serializedPropsScript(props),
    );
  };
}

function wrapInteractiveComponent(name: string, component: any) {
  if (!INTERACTIVE_COMPONENTS.has(name)) return component;
  return { ...component, render: islandRenderer(name, component.render) };
}

Then the page is just renderToStaticMarkup. Note that it's renderToStaticMarkup, not renderToString: there are no hydration markers in the output, because nothing is going to hydrate in React's sense. More on that below.

The props script is a JSON script tag, which means the one escaping rule you cannot skip:

dangerouslySetInnerHTML: {
  __html: JSON.stringify(props).replace(/</g, '\\u003c'),
}

Any user-authored string in those props can contain </script>. If you forget this line, your builder becomes an XSS delivery mechanism the first time someone types the wrong thing into a headline field.

The client half

The entire client-side runtime is one component, mounted once per page with client:only="react". It queries the DOM, collects the distinct island types actually present, and dynamically imports only those:

async function hydrateIslands() {
  const islands = Array.from(document.querySelectorAll<HTMLElement>('[data-island]'));
  if (islands.length === 0) return;

  const components = await loadComponents(collectIslandTypes(islands));

  for (const island of islands) {
    const type = island.getAttribute('data-island');
    const Component = type ? components[type] : null;
    if (!type || !Component) continue;
    const props = readIslandProps(island, type);
    if (props) mountIsland(island, Component, props, 'en');
  }
}

loadComponents walks a plain map of dynamic imports:

const coreLoaders: Record<string, ComponentLoader> = {
  ShippingAddressForm: () => import('./blocks/ShippingAddressForm').then(m => m.ShippingAddressForm),
  PaymentEntryForm:    () => import('./blocks/PaymentEntryForm').then(m => m.PaymentEntryForm),
  CountdownTimer:      () => import('./blocks/CountdownTimer').then(m => m.CountdownTimer),
  // ...
};

The bundler splits every one of those into its own chunk. A page with a countdown timer downloads the countdown chunk. It does not download the Stripe form.

Three things that bit me

1. There are two lists, and they have to agree.

The server decides what to wrap (INTERACTIVE_COMPONENTS). The client decides what can mount (islandLoaders). They live in separate files because they're consumed by separate bundles, and nothing in the type system connects them.

Add a component to the server list only, and you ship a data-island div that never comes alive. It renders correctly, it looks fine, and the button does nothing. That is a genuinely nasty bug class because the failure is silent and visual inspection passes.

I fixed it the only way that actually holds: a test that renders a page through the server path and asserts the island wrapper plus the serialized props survive the round trip.

it('emits an island wrapper carrying default-merged scalar props', () => {
  const html = renderPuckToHtmlWithIslands(pageWith('CountdownTimer'));
  expect(html).toContain('data-island="CountdownTimer"');

  const props = extractIslandProps(html, 'CountdownTimer');
  expect(props.hours).toBe(2);
  expect(props.theme).toBe('block');
});

2. It's createRoot, not hydrateRoot.

This is the part I'd argue about with someone, so let me state the trade honestly. React hydration wants the client's first render to match the server's markup exactly. My props don't come from a React render on the server; they come from a JSON blob that a user edited in a builder. Insisting on hydration means fighting mismatch warnings forever for a class of component that is about to re-render anyway (a countdown timer's server output is wrong by definition the moment it's serialized).

So the server markup is a paint placeholder, and createRoot replaces it on mount. What I get: no mismatch warnings, and one simple contract (props in a script tag) rather than two coupled ones. What I pay: the interactive subtree is rendered twice, and for anything time-dependent there's a visible correction on mount. For a countdown that's fine and arguably correct. If your interactive components are large and stable, real hydration is the better trade and you should take it.

3. Defaults must be merged before serialization.

The builder stores only the props a user explicitly changed. Everything else lives in the component's defaultProps. Server-side, Puck merges those for you during render, so the HTML looks right. But if you serialize the raw stored props, the client mounts the component with half its props undefined and the island renders differently from the markup it just replaced.

The fix is one call (applyPuckDefaults) before rendering, and the assertion props.hours === 2 in that test above exists specifically to catch its removal.

When not to do this

If your pages are known at build time, use client:load and stop reading. This entire mechanism exists to buy back a capability the compiler gives you for free when the page structure is static.

It pays off exactly when the content tree is authored at runtime by someone who is not you: a CMS, a page builder, a template marketplace. In that case the compiler can't help, and the choice is between shipping everything and building this.

The whole runtime is 246 lines across four files, and two of those files are just lists. That is the actual reason I'd recommend it over a framework: it's small enough to read in one sitting, which matters a lot for something sitting between your server output and your users' browsers.