ProGate: A 3-Tier React Server Component Pattern for SaaS...

A small Server-Component pattern that wraps tab content with a license-tier gate. Replaces a 24-line if/if/return block we had duplicated across nine pages with a single 100-line component. Here is the shape, the trade-offs, and why we ended up with two modes instead of one.

If you build a SaaS dashboard with multiple subscription tiers, you have written this code.

if (!license.hasLicense) {
  return <SubscribeCta />;
}
if (!license.isPro) {
  return <UpgradeCta />;
}
return <ActualTabContent />;

That is fine for one page. By the time you have nine — three tabs across three sub-products — it is a problem. The branches drift. The CTA labels go out of sync. Free vs Pro logic gets re-implemented slightly differently.

This post is about the small React Server Component we made to fix that. Nothing fancy. Two props. Worth writing down.

The naive version

Start with the obvious.

export function ProGate({ license, t, shopHref, children }) {
  if (!license.hasLicense) {
    return <EmptyState
      title={t("emptyTitle")}
      description={t("emptyDescription")}
      action={{ label: t("emptyCta"), href: shopHref }}
    />;
  }
  if (!license.isPro) {
    return <EmptyState
      title={t("proTitle")}
      description={t("proDescription")}
      action={{ label: t("proCta"), href: shopHref }}
    />;
  }
  return <>{children}</>;
}

That works for the CRM dashboard. Three pages, three calls, three identical gates. Solid DRY win.

Then we tried to use the same component on the Memory dashboard and hit the first edge case.

Edge case one: single-stage gates

The Memory dashboard sidebar already filters by hasLicense. If you do not have an active Memory subscription, you do not see Memory tabs at all. By the time you reach /portal/memory/knowledge, you definitely have a license. The only question is whether your license is high enough.

So the two-stage CTA — "subscribe first" then "upgrade to Pro" — is wasted UX. We only need one CTA: "upgrade to Pro".

The Memory pages had used a different pattern from CRM, with translation keys named lockedTitle / lockedDescription / lockedCta instead of the two-stage emptyX / proX keyset.

Two options. Migrate the i18n keys to match CRM (and write 27 new translations across DE/EN/ES). Or extend the component to support both shapes.

We extended the component. Adding a mode prop is one line in the consumer; rewriting i18n is touching nine files in three locales.

Edge case two: the Scale tier

Memory has a third tier — Scale — that unlocks the Activity tab. The naive isPro check passes for Team users (paying $49/mo), so they would see the Scale-only tab even though they cannot use it.

We added a second prop, requiredTier, that defaults to "pro" and accepts "scale". When set to "scale", the component checks license.isScale instead of license.isPro.

const passes = requiredTier === "scale" ? license.isScale : license.isPro;

That is the whole switch. Two characters of logic, one prop in the consumer.

The final shape

export type ProGateTier = "pro" | "scale";
export type ProGateMode = "two-stage" | "single";

interface ProGateProps {
  license: ServiceLicenseInfo;
  t: (key: string) => string;
  shopHref: string;
  children: React.ReactNode;
  requiredTier?: ProGateTier;
  mode?: ProGateMode;
}

export function ProGate({
  license,
  t,
  shopHref,
  children,
  requiredTier = "pro",
  mode = "two-stage",
}: ProGateProps) {
  const passes = requiredTier === "scale" ? license.isScale : license.isPro;

  if (passes) {
    return <>{children}</>;
  }

  if (mode === "single") {
    return <EmptyState
      title={t("lockedTitle")}
      description={t("lockedDescription")}
      action={{ label: t("lockedCta"), href: shopHref }}
    />;
  }

  if (!license.hasLicense) {
    return <EmptyState
      title={t("emptyTitle")}
      description={t("emptyDescription")}
      action={{ label: t("emptyCta"), href: shopHref }}
    />;
  }

  return <EmptyState
    title={t("proTitle")}
    description={t("proDescription")}
    action={{ label: t("proCta"), href: shopHref }}
  />;
}

Four call shapes: pro+two-stage, pro+single, scale+two-stage, scale+single. Sensible defaults so existing CRM code does not change. Each call site reads as one line of intent:

// CRM (default — two-stage, pro)
<ProGate license={license} t={t} shopHref={shopHref}>
  <CrmDashboard />
</ProGate>

// Memory Knowledge (single, pro)
<ProGate license={license} t={t} shopHref={shopHref} mode="single">
  <KnowledgeGraph />
</ProGate>

// Memory Activity (single, scale)
<ProGate license={license} t={t} shopHref={shopHref} mode="single" requiredTier="scale">
  <ActivityTimeline />
</ProGate>

The thing we almost did and were glad we did not

We almost made the component "smart" — let it figure out the right mode by inspecting the translation namespace, falling back automatically, choosing the right set of keys.

Magic components are seductive at first and miserable two months in. Every fallback is a question you have to re-answer when something does not render the way you expect. Explicit props are a contract. The component does what you tell it. There is no inferring.

The two props doubled the surface area of the component but kept all four shapes explicit. Every consumer says exactly which gate it wants. No magic, no guessing.

Why Server Component, not Client

Two practical reasons.

License lookups are server-side anyway. The license info comes from a database query keyed by the authenticated session. That has to happen on the server. Doing the gate on the client means you have to ship the license info to the client to render the gate, which is a small but real privacy leak.

Server Components compose cleanly with async data. The page is async, awaits the license, passes to ProGate, ProGate renders the EmptyState or the children — which can be a Client Component for interactive content. The boundary is clean.

In Next.js App Router this is the default shape. Pages are Server Components, components inherit that unless they say "use client".

What we tested

Twelve test cases.

Three license states (no license, has-license-no-pro, has-license-pro) crossed with two tiers (pro, scale) crossed with two modes (two-stage, single). Plus shopHref propagation and snapshot of the EmptyState content per state.

The full test file is around 200 lines. Vitest, no jsdom needed — we just render to static markup with react-dom/server and assert on the string. Sub-second test runs.

The lesson, generalized

Three pages with the same gate is a pattern. Nine pages with subtly different gates is a problem. The fix is not always "more abstraction". Sometimes it is "the same abstraction with two carefully-named props that cover the cases".

If you see yourself writing the same if/if/return block more than twice, ask: how many pages will eventually have this? If the answer is more than three, the abstraction pays off. If two of them have a slightly different shape, decide whether to migrate them or extend the abstraction.

We extended. Twelve months from now, when the next sub-product gets added, the gate is a one-liner.

What you do today

If you have any tier gating in your SaaS dashboard, find the duplicated logic. If it is in two files, leave it. If it is in three or more, extract it.

Resist the urge to make the abstraction smart. Pick a shape, name it explicitly, give it props for the variants you actually need. Add modes when reality demands them.

The whole thing for us was 100 lines of component plus 200 lines of tests. The day we extracted it, we deleted 81 lines from page files. Net win.

推荐订阅源

DEV Community