DEV Community: sweet

SaaS Customer Onboarding: Turning Signups into Active, Paid Users

sweet — Mon, 22 Jun 2026 01:01:00 +0000

Onboarding is the most important funnel in your SaaS. If users do not reach the "aha moment" within their first session, they will not return. This guide covers a systematic approach to onboarding design — activation milestones, progressive disclosure, guided tours, empty states, and the metrics that separate effective onboarding from ineffective onboarding. The patterns described here power the onboarding flow at tanstackship.com.

The Onboarding Funnel

A typical SaaS signup funnel looks like this:

1,000 website visitors
   → 50 signups (5% conversion)
     → 25 complete setup (50% activation)
       → 10 reach "aha moment" (40% of activated)
         → 5 convert to paid (50% conversion)
           → 3 remain active after 90 days (60% retention)

The biggest drop-off is between signup and activation. Most SaaS products lose 60-80% of signups in the first session. Fixing this drop-off has the highest ROI of any optimization.

The Activation Milestone

Every SaaS has an "aha moment" — the point where users experience the core value. Define yours:

Activation Milestone Examples

SaaS Type	Aha Moment	Metrics to Track
Project management	First project created with 3+ tasks	Projects created, tasks added
Analytics	First dashboard with live data	Data sources connected, first report viewed
CRM	First contact imported and organized	Contacts imported, lists created
Design tool	First design export	Assets created, exports completed
Developer tool	First successful deployment	Deployments, API calls

For a SaaS starter like tanstackship.com, the activation milestone might be: "User configures their first subscription plan and sees the billing preview."

The First Session

Minute 1: Value Preview

Show the "end state" immediately. Do not make users configure before they can see value:

// components/onboarding/ValuePreview.tsx
function ValuePreview() {
  return (
    <div className="onboarding-step">
      <h2>See what your dashboard will look like</h2>
      <div className="mockup-container">
        <DashboardMockup /> {/* Pre-rendered example */}
      </div>
      <p className="hint">
        Your actual data will appear here once configured.
        This is what it will look like.
      </p>
      <button onClick={() => startSetup()}>
        Start Setup (2 minutes)
      </button>
    </div>
  )
}

Minutes 2-5: Progressive Setup

Ask for the minimum information needed to show value:

// server/onboarding.ts
export const completeQuickStart = createServerFn({ method: "POST" }).handler(
  async ({ data, context }: {
    data: {
      companyName: string
      productType: string
    }
  }) => {
    // Only ask for essential info in the first session
    await context.env.DB.prepare(`
      UPDATE users SET
        company_name = ?,
        product_type = ?,
        onboarding_step = 'first_dashboard'
      WHERE id = ?
    `).bind(data.companyName, data.productType, context.user.id).run()

    // Generate initial data based on product type
    await generateSampleData(context.user.id, data.productType)

    return { redirectTo: "/dashboard" }
  }
)

Onboarding Flow Patterns

Pattern 1: Guided Checklist

// components/onboarding/Checklist.tsx
type OnboardingStep = {
  id: string
  title: string
  description: string
  isComplete: boolean
  link: string
}

function OnboardingChecklist({ steps }: { steps: OnboardingStep[] }) {
  const completed = steps.filter((s) => s.isComplete).length

  return (
    <div className="onboarding-checklist">
      <div className="progress-bar">
        <div
          className="progress-fill"
          style={{ width: `${(completed / steps.length) * 100}%` }}
        />
      </div>
      <p className="progress-text">
        {completed} of {steps.length} steps complete
      </p>
      <ul>
        {steps.map((step) => (
          <li key={step.id} className={step.isComplete ? "done" : "pending"}>
            {step.isComplete ? (
              <CheckIcon />
            ) : (
              <Link to={step.link}>
                <span>{step.title}</span>
                <span className="description">{step.description}</span>
              </Link>
            )}
          </li>
        ))}
      </ul>
    </div>
  )
}

Pattern 2: Progressive Disclosure

Show advanced features only after the user has completed basics:

// Fetch user's current capability level
const capabilityLevel = await context.env.DB.prepare(`
  SELECT onboarding_step, features_unlocked
  FROM users WHERE id = ?
`).bind(userId).first()

// Only show advanced features if the basics are done
const features = capabilityLevel.features_unlocked
  ? allFeatures
  : allFeatures.filter((f) => !f.requiresSetup)

Pattern 3: Empty States That Guide

Every empty page is an onboarding opportunity:

// components/EmptyState.tsx
function EmptySubscriptionList() {
  return (
    <div className="empty-state">
      <Icon name="subscriptions" />
      <h3>No subscriptions yet</h3>
      <p>Your first subscription is a few clicks away.</p>
      <Button onClick={() => navigate("/settings/stripe")}>
        Connect Stripe → See subscriptions in seconds
      </Button>
    </div>
  )
}

Measuring Onboarding Effectiveness

Key Metrics

Metric	Definition	Good	Needs Work
Time to Activation	Time from signup to first aha moment	< 5 min	> 15 min
Activation Rate	% of signups who reach activation	> 50%	< 30%
Setup Completion	% who complete onboarding checklist	> 70%	< 40%
Day 1 Retention	% who return within 24 hours	> 60%	< 30%
Day 7 Retention	% who return within 7 days	> 40%	< 20%

Tracking in D1

// server/onboarding/tracking.ts
export const trackOnboardingStep = createServerFn({ method: "POST" }).handler(
  async ({ data, context }: {
    data: { step: string; duration: number; error?: string }
  }) => {
    await context.env.DB.prepare(`
      INSERT INTO onboarding_events
        (id, user_id, step, duration_ms, error, created_at)
      VALUES (?, ?, ?, ?, ?, ?)
    `).bind(
      crypto.randomUUID(),
      context.user.id,
      data.step,
      data.duration,
      data.error ?? null,
      Date.now()
    ).run()
  }
)

A/B Testing Onboarding Flows

// Assign user to a variant
export const getOnboardingVariant = createServerFn({ method: "GET" }).handler(
  async ({}, { context }) => {
    const variants = ["guided_checklist", "progressive_disclosure", "video_tour"]
    const index = Math.abs(hashString(context.user.id)) % variants.length
    const variant = variants[index]

    // Track assignment
    await context.env.DB.prepare(`
      INSERT INTO ab_tests
        (id, user_id, test_name, variant, created_at)
      VALUES (?, ?, 'onboarding_flow', ?, ?)
    `).bind(crypto.randomUUID(), context.user.id, variant, Date.now()).run()

    return { variant }
  }
)

The Onboarding-to-Paid Transition

The moment between activation and first payment is delicate. The user has seen value but has not yet committed:

// Trigger when user completes activation milestone
export const checkActivation = createServerFn({ method: "GET" }).handler(
  async ({}, { context }) => {
    const user = await context.env.DB.prepare(`
      SELECT onboarding_step, subscription_status
      FROM users WHERE id = ?
    `).bind(context.user.id).first()

    if (user.onboarding_step === 'complete' && !user.subscription_status) {
      // User is activated but not subscribed → show upgrade prompt
      return {
        showUpgrade: true,
        timing: 'post_activation',
      }
    }
  }
)

Onboarding Anti-Patterns

Anti-Pattern	Why It Fails	Better Approach
Ask for everything upfront	Overwhelms users	Progressive disclosure
No guided tour	Users get lost	Contextual tooltips
Perfect data required	Users cannot start	Sample data pre-populated
All features shown at once	Cognitive overload	Feature gating by progress
No progress indication	Users do not know how far they are	Visual progress bar
Email-only onboarding	Low engagement	In-app guidance
No value preview	Users must build before they see	Pre-rendered examples

Advanced: Using UTM Data to Personalize Onboarding

If the user arrived from a specific campaign, customize their onboarding:

export const getPersonalizedOnboarding = createServerFn({ method: "GET" }).handler(
  async ({}, { context }) => {
    const utmData = await context.env.DB.prepare(`
      SELECT utm_source, utm_campaign, utm_content
      FROM utm_clicks
      WHERE user_id = ?
      ORDER BY created_at DESC
      LIMIT 1
    `).bind(context.user.id).first()

    // Different onboarding for different sources
    if (utmData?.utm_campaign === "feature_stripe") {
      return { template: "stripe_focused_onboarding" }
    }

    return { template: "default_onboarding" }
  }
)

Onboarding Flow Checklist

[ ] Define the activation milestone (what is the "aha moment"?)
[ ] Track every onboarding step with timing data
[ ] Empty states guide users toward the next action
[ ] Progress indicator visible throughout onboarding
[ ] Sample data available for immediate value
[ ] Advanced features gated behind basic setup
[ ] Upgrade prompt shown after activation, not before
[ ] A/B testing infrastructure for onboarding variants
[ ] Email follow-up for users who do not complete setup
[ ] Onboarding analytics dashboard to monitor drop-offs

Conclusion

Onboarding is not a tutorial — it is the bridge between a curious signup and an active user. The best onboarding flows are invisible: users experience the value of the product before they realize they are being guided.

The principles are universal:

Show value immediately (preview, mockup, sample data)
Ask for the minimum information needed to progress
Guide through empty states (not modals or overlays)
Measure every step with timing data
Personalize based on acquisition source

For a SaaS starter with built-in onboarding infrastructure — progress tracking, A/B testing, UTM-based personalization — see tanstackship.com.

Related Resources

Conversion Rate Optimization for SaaS: A/B Testing, Psychology, and Data

sweet — Sun, 21 Jun 2026 00:57:00 +0000

CRO is the systematic process of increasing the percentage of visitors who take a desired action — signing up, starting a trial, or upgrading to a paid plan. It combines rigorous A/B testing methodology with psychology principles and data analysis. This guide covers the CRO framework used at tanstackship.com, including landing page optimization, pricing page design, trial conversion flows, and the infrastructure needed to run continuous experiments.

The CRO Funnel for SaaS


Traffic (100%)
  │
  ▼
Landing Page (5-15% → signup)
  │
  ▼
Signup → Activation (30-60%)
  │
  ▼
Free/Active User (20-40% → paid)
  │
  ▼
Paying Customer
  │
  ▼
Retained Customer

Improving each step by 10% compounds:
100 visitors → 10 signups → 5 paid → 3 retained
100 visitors → 11 signups → 6 paid → 4 retained
= 33% more retained customers from the same traffic

A/B Testing Methodology

Statistical Foundation

// A/B test calculator
export const calculateABTest = createServerFn({ method: "POST" }).handler(
  async ({ data }: { data: {
    controlVisitors: number
    controlConversions: number
    variantVisitors: number
    variantConversions: number
  }}) => {
    const controlRate = data.controlConversions / data.controlVisitors
    const variantRate = data.variantConversions / data.variantVisitors

    // Calculate statistical significance (chi-squared)
    const improvement = ((variantRate - controlRate) / controlRate) * 100

    // Sample size needed for 80% power at 95% significance
    const baseline = controlRate
    const minimumDetectableEffect = 0.1 // 10% relative improvement
    const zAlpha = 1.96 // 95% confidence
    const zBeta = 0.84 // 80% power
    const sampleSize =
      ((zAlpha + zBeta) ** 2 * 2 * baseline * (1 - baseline)) /
      (minimumDetectableEffect ** 2)

    return {
      controlRate,
      variantRate,
      improvement,
      sampleSizeNeeded: Math.ceil(sampleSize),
      currentSampleSize: data.controlVisitors + data.variantVisitors,
      sufficientData: (data.controlVisitors + data.variantVisitors) >= sampleSize,
    }
  }
)

Test Requirements

Requirement	Minimum	Recommended
Sample size per variant	1,000	5,000+
Test duration	7 days	14 days (full business cycle)
Statistical significance	90%	95%
Minimum detectable effect	20%	10%

Psychology Principles for SaaS

Principle	Application	Example
Anchoring	Show higher price first	Enterprise plan before Starter
Social proof	Show user counts, testimonials	"Join 1,200+ SaaS teams"
Scarcity	Limited-time offers	"Early adopter pricing ends soon"
Loss aversion	Emphasize what they lose	"You're missing out on..."
Commitment	Start small, build up	Free tier → paid upgrade
Reciprocity	Give value before asking	Free guides, templates, tools
Decoy effect	Third option makes one clearly best	Three pricing tiers
Authority	Expert endorsements	"Recommended by [expert name]"

The Decoy Effect on Pricing Pages

Tier A: $19/mo (Starter)    ← You want this to sell
Tier B: $39/mo (Pro)        ← Decoy — slightly worse value than C
Tier C: $49/mo (Enterprise) ← High-end anchor

Without decoy: A and C are compared directly
With decoy: B makes A look like a great deal
             (or C makes B look reasonable)

Landing Page Optimization

Above the Fold

// A/B test: headline variants
const headlineVariants = {
  control: {
    headline: "Build Your SaaS Faster",
    subheadline: "A production-ready starter with auth, billing, and more.",
    cta: "Get Started",
  },
  variantA: {
    headline: "Ship Your SaaS in Days, Not Months",
    subheadline: "Pre-built auth, billing, marketing, and multi-language support.",
    cta: "Start Building Free →",
  },
  variantB: {
    headline: "The SaaS Starter That Saves You 200 Hours",
    subheadline: "Everything you need to launch — without rebuilding the boring parts.",
    cta: "See What's Included",
  },
}

Hero Section Testing

Element	Test	Typical Win
Headline	Benefit vs feature	Benefit wins 80%
CTA button	Color, size, text	High contrast, action-oriented
Hero image	Screenshot vs illustration	Product screenshot wins
Social proof	Count vs testimonial	Count for awareness, testimonial for conversion
Form placement	Above fold vs scroll	Above fold wins for B2B SaaS

Pricing Page Optimization

Pricing Page Structure

Best practices for SaaS pricing pages:

1. Anchor with highest price first (for annual/monthly toggle)
2. Highlight "Most Popular" or "Recommended" badge
3. Include a comparison table for features
4. Show annual savings prominently ("Save 20%")
5. Offer a free trial or money-back guarantee
6. Use social proof near the CTA
7. Remove navigation links (reduce distraction)

A/B Testing Pricing

// Dynamic pricing based on A/B test assignment
export const getPricingVariant = createServerFn({ method: "GET" }).handler(
  async ({}, { context }) => {
    const variants = [
      { id: "control", starter: 29, pro: 79, enterprise: 199 },
      { id: "lower_prices", starter: 19, pro: 59, enterprise: 149 },
      { id: "higher_prices", starter: 39, pro: 99, enterprise: 249 },
      { id: "different_tiers", starter: 29, growth: 69, scale: 149 },
    ]

    const index = Math.abs(hashString(context.user.id ?? "anon")) % variants.length
    const variant = variants[index]

    // Track assignment
    await context.env.DB.prepare(`
      INSERT INTO ab_assignments
        (user_id, test_name, variant, assigned_at)
      VALUES (?, 'pricing_page', ?, ?)
    `).bind(context.user.id ?? "anon", variant.id, Date.now()).run()

    return variant
  }
)

Trial-to-Paid Conversion

Trial Funnel Metrics

Metric	Definition	Good	Needs Work
Trial start rate	% of signups who start trial	> 60%	< 40%
Activation rate	% who reach aha moment during trial	> 50%	< 30%
Day 3 active	% returning within 3 days	> 40%	< 20%
Conversion rate	% who convert before trial ends	> 20%	< 10%
Conversion timing	Average day of conversion	Day 10-14	Day 28+

Trial Emails Sequence

const trialEmailSequence = [
  { day: 0, type: "welcome", subject: "Welcome! Here's your first step" },
  { day: 1, type: "activation", subject: "Set up your project in 2 minutes" },
  { day: 3, type: "tip", subject: "Most users love this feature" },
  { day: 5, type: "case_study", subject: "How [customer] saved 20 hours/week" },
  { day: 7, type: "mid_trial", subject: "Halfway through your trial" },
  { day: 10, type: "offer", subject: "Convert now and save 20% on annual" },
  { day: 12, type: "urgent", subject: "Your trial ends in 2 days" },
  { day: 14, type: "expired", subject: "Your trial has ended" },
]

CRO Infrastructure

// Database schema for experiments
export const experiments = sqliteTable("experiments", {
  id: text("id").primaryKey(),
  name: text("name").notNull(),
  slug: text("slug").notNull().unique(),
  status: text("status", {
    enum: ["draft", "running", "paused", "concluded"],
  }).notNull().default("draft"),
  controlVariant: text("control_variant").notNull(),
  variants: text("variants").notNull(), // JSON array
  hypothesis: text("hypothesis"),
  targetMetric: text("target_metric").notNull(),
  minimumSampleSize: integer("minimum_sample_size"),
  startedAt: integer("started_at", { mode: "timestamp" }),
  concludedAt: integer("concluded_at", { mode: "timestamp" }),
  winnerVariant: text("winner_variant"),
})

// Track event for experiment
export const trackExperimentEvent = createServerFn({ method: "POST" }).handler(
  async ({ data, context }: { data: {
    experimentId: string
    variant: string
    event: string
    value?: number
  }}) => {
    await context.env.DB.prepare(`
      INSERT INTO experiment_events
        (id, experiment_id, variant, event, value, user_id, created_at)
      VALUES (?, ?, ?, ?, ?, ?, ?)
    `).bind(
      crypto.randomUUID(),
      data.experimentId,
      data.variant,
      data.event,
      data.value ?? null,
      context.user.id ?? null,
      Date.now()
    ).run()
  }
)

CRO Wins for SaaS

Optimization	Typical Lift	Difficulty	Implementation
Add social proof to landing page	+15-30%	Low	Add testimonial section
Simplify signup form (3 fields → 1)	+20-40%	Low	OAuth-only signup option
Add guarantee to pricing	+10-25%	Low	"14-day money back" badge
Highlight "Most Popular" plan	+15-20%	Low	CSS badge on pricing card
Annual pricing discount	+20-30% trial conversion	Medium	Toggle on pricing page
Email sequence during trial	+30-50% trial conversion	Medium	Automated email campaign
Personalized onboarding	+20-35% activation	High	UTM-based customization
In-app upgrade prompt	+15-25%	Medium	Contextual upsell

CRO Process Checklist

[ ] Conversion funnel defined and tracked (visit → signup → activate → pay → retain)
[ ] Baseline conversion rates established for each funnel stage
[ ] Hypothesis documented before every test (why this change should work)
[ ] A/B test statistical requirements met (sample size, duration, significance)
[ ] Only one variable changed per test
[ ] Results analyzed before implementing changes
[ ] Winning variants implemented permanently
[ ] Losing variants analyzed for insights
[ ] CRO results documented and shared with team
[ ] Continuous testing pipeline established (one test always running)

Conclusion

CRO is not about tricking users into converting — it is about removing friction and building trust at every stage of the funnel. Every element of your landing page, signup flow, pricing page, and trial experience either builds confidence or creates doubt.

The methodology is scientific: form a hypothesis, run a controlled experiment, analyze the data, implement the winner. Small improvements compound: a 10% improvement at each of the four funnel stages (visit → signup → activate → pay) results in a 46% overall improvement in paid conversions.

For a SaaS with built-in A/B testing infrastructure, conversion tracking, and analytics, see tanstackship.com.

Related Resources

How to Design an Effective Referral Reward System: A Complete Technical Guide for SaaS

sweet — Sat, 20 Jun 2026 00:54:00 +0000

A well-designed referral program can be the highest-ROI customer acquisition channel for SaaS products, with referred customers typically having 25-30% higher retention and 16% higher lifetime value. This guide covers the complete implementation — from reward structure psychology and invite code generation to credit engine architecture, fraud prevention, and analytics. Includes production-ready database schemas and server-side code for TanStack Start with Cloudflare D1. See the referral system live at tanstackship.com.

Why Referral Programs Work (The Data)

Referral marketing is not just a growth tactic — it is a trust mechanic. People trust recommendations from peers more than any other form of marketing:

Channel	Trust Rate	Conversion Rate	Avg. LTV	Source
Friend referral	92%	10-30%	+16% higher	Nielsen
Online review	70%	3-10%	Baseline	BrightLocal
Paid ad	25%	0.5-2%	-20% lower	Meta Ads

For SaaS specifically, referred customers have 25-30% lower churn and a 16% higher lifetime value compared to organically acquired customers (Deloitte). This is because:

Pre-qualified leads: The referrer only invites people who would genuinely benefit
Social onboarding: New users have a built-in "buddy" who helps them get started
Network effects: As more people in a team/organization join, stickiness increases

Reward Structure: What Works and What Does Not

The Two-Sided Reward Model

The most effective SaaS referral programs reward both the referrer and the referred user:

Model	Referrer Gets	Referee Gets	Example Companies
Two-sided discount	1 month free	20% off first 3 months	Dropbox, Airbnb
Two-sided credit	$50 account credit	$25 account credit	Uber, Robinhood
One-sided reward	1 month free	Nothing	(Less effective)
Donation-based	$5 to charity	$5 to charity	TOMS, Warby Parker (B2C)

Determining the Reward Value

The golden rule: Your reward should offset 25-50% of one month's subscription value.

For a $29/month SaaS:
  - Referrer reward: $7.25 - $14.50 in credit (1-2 weeks free)
  - Referee reward: $7.25 - $14.50 in credit

For a $99/month SaaS:
  - Referrer reward: $25 - $50 in credit
  - Referee reward: $25 - $50 in credit

Credit vs. Discount vs. Cash

Reward Type	Pros	Cons	Best For
Service credit	Low cost (zero marginal cost), encourages continued use	User may not need more credit	SaaS with usage-based billing
Subscription discount	Directly reduces churn barrier	Complex to implement with billing intervals	Monthly subscription SaaS
Cash/ PayPal	Highest motivation	Expensive, feels transactional	Enterprise SaaS
Gift cards	Simple to administer	Lower perceived value than cash	B2C/B2B hybrid
Feature unlocks	Zero cost, high perceived value	Only works with freemium model	Freemium products

Database Schema for Referral System

-- Table 1: Invite codes (generated by referrers)
CREATE TABLE invite_codes (
  id TEXT PRIMARY KEY,
  code TEXT NOT NULL UNIQUE, -- e.g., 'FRIEND-ABC123'
  creator_id TEXT NOT NULL, -- The user who created this code
  max_uses INTEGER DEFAULT 10,
  use_count INTEGER NOT NULL DEFAULT 0,
  reward_type TEXT NOT NULL DEFAULT 'credit' CHECK (
    reward_type IN ('credit', 'discount_percent', 'discount_fixed', 'month_free')
  ),
  reward_value INTEGER NOT NULL DEFAULT 500, -- In cents or percentage points
  is_active INTEGER NOT NULL DEFAULT 1,
  expires_at INTEGER, -- Optional expiration
  created_at INTEGER NOT NULL DEFAULT (unixepoch()),
  FOREIGN KEY (creator_id) REFERENCES users(id)
);

CREATE INDEX idx_invite_codes_code ON invite_codes(code);
CREATE INDEX idx_invite_codes_creator ON invite_codes(creator_id);

-- Table 2: Redemption records
CREATE TABLE invite_redemptions (
  id TEXT PRIMARY KEY,
  invite_code_id TEXT NOT NULL,
  referrer_id TEXT NOT NULL, -- The person who shared the code
  referred_user_id TEXT NOT NULL, -- The new user who used the code
  reward_referrer INTEGER NOT NULL DEFAULT 0, -- Cents awarded to referrer
  reward_referred INTEGER NOT NULL DEFAULT 0, -- Cents awarded to referee
  status TEXT NOT NULL DEFAULT 'pending' CHECK (
    status IN ('pending', 'completed', 'expired', 'fraudulent')
  ),
  created_at INTEGER NOT NULL DEFAULT (unixepoch()),
  completed_at INTEGER, -- When conditions were met (e.g., referee pays)
  FOREIGN KEY (invite_code_id) REFERENCES invite_codes(id),
  FOREIGN KEY (referrer_id) REFERENCES users(id),
  FOREIGN KEY (referred_user_id) REFERENCES users(id)
);

CREATE INDEX idx_invite_redemptions_referrer ON invite_redemptions(referrer_id);
CREATE INDEX idx_invite_redemptions_referred ON invite_redemptions(referred_user_id);

-- Table 3: Credit ledger (for credit-based rewards)
CREATE TABLE credit_ledger (
  id TEXT PRIMARY KEY,
  user_id TEXT NOT NULL,
  amount_cents INTEGER NOT NULL, -- Positive for credit, negative for spend
  balance_after_cents INTEGER NOT NULL,
  reason TEXT NOT NULL CHECK (
    reason IN (
      'referral_reward', 'referral_signup_bonus',
      'credit_purchase', 'subscription_payment',
      'admin_adjustment', 'expired'
    )
  ),
  reference_id TEXT, -- Links to invite_redemptions or invoice
  created_at INTEGER NOT NULL DEFAULT (unixepoch()),
  FOREIGN KEY (user_id) REFERENCES users(id)
);

CREATE INDEX idx_credit_ledger_user ON credit_ledger(user_id);

-- View: Referral statistics per user
CREATE VIEW referral_stats AS
SELECT
  ic.creator_id as user_id,
  COUNT(DISTINCT ir.id) as total_referrals,
  COUNT(DISTINCT CASE WHEN ir.status = 'completed' THEN ir.id END) as completed_referrals,
  COALESCE(SUM(CASE WHEN ir.status = 'completed' THEN ir.reward_referrer END), 0) as total_rewards_earned,
  ROUND(AVG(CASE WHEN ir.status = 'completed' THEN ir.reward_referrer END), 0) as avg_reward_per_referral
FROM invite_codes ic
LEFT JOIN invite_redemptions ir ON ir.invite_code_id = ic.id
GROUP BY ic.creator_id;

Invite Code Generation

// src/lib/invite/codes.ts
import { createServerFn } from "@tanstack/react-start"

// Secure, human-friendly invite code generation
export function generateInviteCode(length: number = 8): string {
  // Use a character set that avoids ambiguous characters
  const chars = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789" // No I, O, 0, 1
  const prefix = "FRIEND-"
  const random = Array.from({ length }, () =>
    chars[Math.floor(Math.random() * chars.length)]
  ).join("")
  return `${prefix}${random}`
}

export const createInviteCode = createServerFn({ method: "POST" }).handler(
  async (_, { request }) => {
    const userId = await getUserId(request)
    const code = generateInviteCode()

    // Ensure uniqueness (collision probability is negligible but check anyway)
    const existing = await env.DB.prepare(
      "SELECT id FROM invite_codes WHERE code = ?"
    ).bind(code).first()

    if (existing) {
      return createInviteCode(_, { request }) // Retry
    }

    // Default reward: 500 cents ($5.00) account credit for both parties
    await env.DB.prepare(
      `INSERT INTO invite_codes (id, code, creator_id, reward_value)
       VALUES (?, ?, ?, 500)`
    ).bind(crypto.randomUUID(), code, userId).run()

    return { code, shareUrl: `https://tanstackship.com/invite/${code}` }
  }
)

Referral Flow Implementation

Step 1: Share the Referral Link

// src/components/invite/ShareInvite.tsx
import { useMutation } from "@tanstack/react-query"
import { createInviteCode } from "../../lib/invite/codes"

export function ShareInvite() {
  const mutation = useMutation({
    mutationFn: () => createInviteCode(),
  })

  const shareUrl = mutation.data?.shareUrl ?? ""

  return (
    <div className="p-6 border rounded-lg">
      <h2 className="text-xl font-bold mb-4">Refer a Friend, Earn Credit</h2>
      <p className="text-gray-600 mb-4">
        Share your invite link and earn $5 for every friend who signs up
      </p>

      <button
        onClick={() => mutation.mutate()}
        className="bg-blue-600 text-white px-6 py-2 rounded-lg"
        disabled={mutation.isPending}
      >
        {mutation.isPending ? "Generating..." : "Get Your Referral Link"}
      </button>

      {shareUrl && (
        <div className="mt-4">
          <label className="block text-sm font-medium mb-1">
            Your referral link
          </label>
          <div className="flex gap-2">
            <input
              type="text"
              value={shareUrl}
              readOnly
              className="flex-1 px-3 py-2 border rounded"
            />
            <button
              onClick={() => navigator.clipboard.writeText(shareUrl)}
              className="px-4 py-2 bg-gray-100 rounded hover:bg-gray-200"
            >
              Copy
            </button>
          </div>
        </div>
      )}
    </div>
  )
}

Step 2: Redeem the Invite Code on Signup

// src/lib/invite/redeem.ts
import { createServerFn } from "@tanstack/react-start"

export const redeemInviteCode = createServerFn({ method: "POST" }).handler(
  async ({ code, newUserId }: { code: string; newUserId: string }) => {
    // Validate the invite code
    const invite = await env.DB.prepare(
      `SELECT ic.*, u.email as creator_email
       FROM invite_codes ic
       JOIN users u ON u.id = ic.creator_id
       WHERE ic.code = ? AND ic.is_active = 1
       AND (ic.expires_at IS NULL OR ic.expires_at > unixepoch())
       AND ic.use_count < ic.max_uses`
    ).bind(code).first()

    if (!invite) {
      return { success: false, error: "Invalid or expired invite code" }
    }

    // Prevent self-referral
    if (invite.creator_id === newUserId) {
      return { success: false, error: "You cannot use your own invite code" }
    }

    const now = Math.floor(Date.now() / 1000)
    const redemptionId = crypto.randomUUID()

    // Create redemption record (pending until condition is met)
    await env.DB.prepare(
      `INSERT INTO invite_redemptions
        (id, invite_code_id, referrer_id, referred_user_id,
         reward_referrer, reward_referred, status, created_at)
       VALUES (?, ?, ?, ?, ?, ?, 'pending', ?)`
    ).bind(
      redemptionId,
      invite.id,
      invite.creator_id,
      newUserId,
      invite.reward_value, // Referrer gets the reward
      invite.reward_value, // Referee gets the reward
      now
    ).run()

    // Increment code usage
    await env.DB.prepare(
      `UPDATE invite_codes SET use_count = use_count + 1 WHERE id = ?`
    ).bind(invite.id).run()

    // Award credit to the referred user immediately (signup bonus)
    await awardCredit(newUserId, invite.reward_value, "referral_signup_bonus", redemptionId)

    return { success: true, bonusAmount: invite.reward_value }
  }
)

Step 3: Release Referrer Reward When Condition Is Met

// src/lib/invite/rewards.ts
// Triggered when the referred user completes their first payment
export const processReferralReward = createServerFn({ method: "POST" }).handler(
  async ({ referredUserId }: { referredUserId: string }) => {
    const pendingRedemption = await env.DB.prepare(
      `SELECT ir.*, ic.reward_type
       FROM invite_redemptions ir
       JOIN invite_codes ic ON ic.id = ir.invite_code_id
       WHERE ir.referred_user_id = ? AND ir.status = 'pending'`
    ).bind(referredUserId).first()

    if (!pendingRedemption) return { processed: false }

    // Award credit to the referrer
    await awardCredit(
      pendingRedemption.referrer_id,
      pendingRedemption.reward_referrer,
      "referral_reward",
      pendingRedemption.id
    )

    // Mark as completed
    await env.DB.prepare(
      `UPDATE invite_redemptions SET status = 'completed', completed_at = unixepoch()
       WHERE id = ?`
    ).bind(pendingRedemption.id).run()

    return { processed: true, amount: pendingRedemption.reward_referrer }
  }
)

Credit Engine Architecture

A robust credit system that handles referral rewards, subscription payments, and manual adjustments:

// src/lib/credit/engine.ts

export async function awardCredit(
  userId: string,
  amountCents: number,
  reason: CreditLedger["reason"],
  referenceId: string
) {
  const currentBalance = await getCreditBalance(userId)
  const newBalance = currentBalance + amountCents

  await env.DB.prepare(
    `INSERT INTO credit_ledger (id, user_id, amount_cents, balance_after_cents, reason, reference_id)
     VALUES (?, ?, ?, ?, ?, ?)`
  ).bind(
    crypto.randomUUID(),
    userId,
    amountCents,
    newBalance,
    reason,
    referenceId
  ).run()

  return newBalance
}

export async function spendCredit(
  userId: string,
  amountCents: number,
  referenceId: string
): Promise<boolean> {
  const balance = await getCreditBalance(userId)
  if (balance < amountCents) return false // Insufficient credit

  const newBalance = balance - amountCents

  await env.DB.prepare(
    `INSERT INTO credit_ledger (id, user_id, amount_cents, balance_after_cents, reason, reference_id)
     VALUES (?, ?, ?, ?, 'subscription_payment', ?)`
  ).bind(
    crypto.randomUUID(),
    userId,
    -amountCents,
    newBalance,
    referenceId
  ).run()

  return true
}

export async function getCreditBalance(userId: string): Promise<number> {
  const result = await env.DB.prepare(
    `SELECT balance_after_cents
     FROM credit_ledger
     WHERE user_id = ?
     ORDER BY created_at DESC
     LIMIT 1`
  ).bind(userId).first()

  return (result?.balance_after_cents as number) ?? 0
}

Fraud Prevention

Referral fraud is a real problem. Here is a multi-layered defense:

// src/lib/invite/fraud-detection.ts
import { createServerFn } from "@tanstack/react-start"

export const validateReferral = createServerFn({ method: "POST" }).handler(
  async ({ referrerId, refereeId, ipAddress }: {
    referrerId: string
    refereeId: string
    ipAddress: string
  }) => {
    const checks = await Promise.all([
      // Check 1: Same IP detection
      env.DB.prepare(
        `SELECT COUNT(*) as count FROM users
         WHERE ip_address = ? AND id != ?`
      ).bind(ipAddress, refereeId).first(),

      // Check 2: Referral velocity (how many in last 24h)
      env.DB.prepare(
        `SELECT COUNT(*) as count FROM invite_redemptions
         WHERE referrer_id = ? AND created_at > unixepoch() - 86400`
      ).bind(referrerId).first(),

      // Check 3: Same device fingerprint (if available)
      // Implementation depends on your fingerprinting approach
    ])

    const [ipCheck, velocityCheck] = (checks as [{ count: number }, { count: number }])

    if (ipCheck.count > 3) {
      // Flag for review — same IP as too many different users
      await flagForReview(referrerId, "referral_fraud_same_ip")
      return { valid: false, reason: "suspicious_activity" }
    }

    if (velocityCheck.count > 10) {
      // More than 10 referrals in 24 hours is suspicious for most SaaS
      await flagForReview(referrerId, "referral_fraud_high_velocity")
      return { valid: false, reason: "rate_limited" }
    }

    return { valid: true }
  }
)

Referral Program Analytics

-- Dashboard queries for monitoring referral program health

-- 1. Referral funnel
SELECT
  COUNT(DISTINCT ic.creator_id) as users_with_codes,
  COUNT(DISTINCT ir.referred_user_id) as users_who_clicked,
  COUNT(DISTINCT CASE WHEN ir.status = 'completed' THEN ir.referred_user_id END) as converted_referrals,
  COUNT(DISTINCT CASE WHEN s.status = 'active' THEN ir.referred_user_id END) as retained_referrals
FROM invite_codes ic
LEFT JOIN invite_redemptions ir ON ir.invite_code_id = ic.id
LEFT JOIN subscriptions s ON s.user_id = ir.referred_user_id AND s.status = 'active'

-- 2. Top referrers
SELECT
  u.email,
  COUNT(ir.id) as referrals_sent,
  COUNT(CASE WHEN ir.status = 'completed' THEN 1 END) as referrals_completed,
  SUM(CASE WHEN ir.status = 'completed' THEN ir.reward_referrer END) / 100.0 as rewards_earned
FROM users u
JOIN invite_codes ic ON ic.creator_id = u.id
LEFT JOIN invite_redemptions ir ON ir.invite_code_id = ic.id
GROUP BY u.id
ORDER BY referrals_completed DESC
LIMIT 25

-- 3. Referral vs. organic retention comparison
SELECT
  CASE WHEN ir.id IS NOT NULL THEN 'referred' ELSE 'organic' END as acquisition_channel,
  COUNT(DISTINCT u.id) as total_users,
  COUNT(DISTINCT CASE WHEN s.status = 'active' THEN u.id END) as active_users,
  ROUND(AVG(s.mrr), 2) as avg_mrr,
  ROUND(AVG(s.created_at - u.created_at) / 86400, 0) as avg_days_to_churn_or_now
FROM users u
LEFT JOIN subscriptions s ON s.user_id = u.id
LEFT JOIN invite_redemptions ir ON ir.referred_user_id = u.id
GROUP BY acquisition_channel

Referral Program Optimization Checklist

[ ] Reward structure is two-sided (both referrer and referee benefit)
[ ] Reward value is 25-50% of one month's subscription value
[ ] Invite codes are easy to share (URL, copy button, email, social)
[ ] Fraud prevention checks are in place (same IP, velocity, self-referral)
[ ] Credit system handles concurrent spends correctly
[ ] Referral rewards are released only after condition is met (not immediately)
[ ] Referral analytics dashboard shows funnel and ROI
[ ] Email notifications sent to referrer when friend signs up
[ ] Email notifications sent to referrer when reward is credited
[ ] A/B testing framework is in place for reward amounts
[ ] Terms of Service cover referral fraud and reward revocation
[ ] Self-referral detection prevents users from gaming the system

Conclusion

A referral program is not a "set and forget" growth channel — it requires careful design, implementation, and ongoing optimization. The key principles are:

Reward both sides of the transaction — the referrer and the referee should both feel like they won
Delay referrer rewards until the referee takes a valuable action (pays, activates) to prevent fraud
Build credit infrastructure first — a credit engine that handles referral rewards today can also handle support credits, beta tester rewards, and promotional giveaways tomorrow
Monitor for fraud continuously — what starts as a growth channel can become a cost center without proper controls
Measure referral LTV vs. organic LTV — if referred customers are not more valuable, your reward structure or targeting needs adjustment

When done right, referrals become your highest-quality, lowest-cost acquisition channel — and turn your customers into your most effective sales team.

Related Resources

Real User Monitoring: Measuring Web Performance in Production

sweet — Fri, 19 Jun 2026 01:20:00 +0000

Lab tests (Lighthouse, CI benchmarks) tell you how your app performs on a test machine. Real User Monitoring tells you how your app performs for actual users on their devices, networks, and locations. RUM catches performance issues that lab tests never will — slow connections, memory pressure, ad blocker interference, and geographic variance. This guide covers the RUM implementation at tanstackship.com.

Lab vs Field Data

Aspect	Lab (Lighthouse)	Field (RUM)
Environment	Controlled (Moto G4, slow 3G)	Real user devices
Network	Simulated throttling	Actual connections (5G, 4G, 3G, WiFi)
Location	Single location	Global (330+ Cloudflare locations)
Device	Fixed device profile	All devices and form factors
Sample size	Single run per PR	Every page load
Detects	Optimization opportunities	Actual user experience issues
Missing	What real users experience	Controlled comparison

The truth: Lab data tells you what to fix. Field data tells you what users actually experience. You need both.

RUM Data Collection

Setting Up Web Vitals Collection

// src/lib/rum.ts
import { onLCP, onCLS, onINP, onTTFB, onFCP } from "web-vitals/attribution"

type VitalName = "LCP" | "CLS" | "INP" | "TTFB" | "FCP"

interface VitalReport {
  name: VitalName
  value: number
  rating: "good" | "needs-improvement" | "poor"
  id: string
  metadata: Record<string, string>
  deviceType: string
  connectionType: string
}

export function initRUM() {
  const vitals: Array<{ name: VitalName; fn: (metric: any) => void }> = [
    { name: "LCP", fn: onLCP },
    { name: "CLS", fn: onCLS },
    { name: "INP", fn: onINP },
    { name: "TTFB", fn: onTTFB },
    { name: "FCP", fn: onFCP },
  ]

  vitals.forEach(({ name, fn }) => {
    fn((metric) => {
      sendVital({
        name,
        value: metric.value,
        rating: metric.rating,
        id: metric.id,
        metadata: extractAttribution(metric),
        deviceType: getDeviceType(),
        connectionType: getConnectionType(),
      })
    })
  })
}

function extractAttribution(metric: any): Record<string, string> {
  if (metric.attribution) {
    // Extract useful debugging info
    const { element, url, fcp, ...rest } = metric.attribution
    return {
      ...(element && { lcpElement: element.tagName }),
      ...(url && { lcpUrl: url }),
    }
  }
  return {}
}

function getDeviceType(): string {
  const ua = navigator.userAgent
  if (/Mobi|Android/i.test(ua)) return "mobile"
  if (/Tablet|iPad/i.test(ua)) return "tablet"
  return "desktop"
}

function getConnectionType(): string {
  const conn = (navigator as any).connection
  return conn?.effectiveType ?? "unknown"
}

Sending RUM Data to the Backend

// Use sendBeacon for reliable delivery (survives page navigation)
function sendVital(report: VitalReport) {
  const payload = {
    ...report,
    pathname: window.location.pathname,
    timestamp: Date.now(),
  }

  if (navigator.sendBeacon) {
    navigator.sendBeacon("/api/vitals", JSON.stringify(payload))
  } else {
    fetch("/api/vitals", {
      method: "POST",
      body: JSON.stringify(payload),
      keepalive: true,
    })
  }
}

Server-Side Storage

// server/rum.ts
export const reportVital = createServerFn({ method: "POST" }).handler(
  async ({ request, context }) => {
    const data = await request.json()

    // Store in D1 for querying
    await context.env.DB.prepare(`
      INSERT INTO rum_metrics (
        id, name, value, rating, pathname,
        device_type, connection_type,
        country, metadata, created_at
      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
    `).bind(
      data.id,
      data.name,
      data.value,
      data.rating,
      data.pathname,
      data.deviceType,
      data.connectionType,
      request.cf?.country ?? "unknown",
      JSON.stringify(data.metadata),
      data.timestamp
    ).run()

    return { received: true }
  }
)

Analyzing RUM Data

Querying by Metric

export const getRumDashboard = createServerFn({ method: "GET" }).handler(
  async ({}, { context }) => {
    // Overall metrics for the last 7 days
    const overall = await context.env.DB.prepare(`
      SELECT
        name,
        COUNT(*) as samples,
        APPROX_PERCENTILE(value, 0.5) as p50,
        APPROX_PERCENTILE(value, 0.75) as p75,
        APPROX_PERCENTILE(value, 0.95) as p95,
        SUM(CASE WHEN rating = 'good' THEN 1 ELSE 0 END) * 100.0 / COUNT(*) as good_pct
      FROM rum_metrics
      WHERE created_at > datetime('now', '-7 days')
      GROUP BY name
    `).all()

    // Breakdown by pathname (top 10 slowest)
    const byPath = await context.env.DB.prepare(`
      SELECT
        pathname,
        APPROX_PERCENTILE(CASE WHEN name = 'LCP' THEN value END, 0.5) as lcp_p50,
        APPROX_PERCENTILE(CASE WHEN name = 'INP' THEN value END, 0.5) as inp_p50,
        COUNT(*) as pageviews
      FROM rum_metrics
      WHERE created_at > datetime('now', '-7 days')
      GROUP BY pathname
      ORDER BY lcp_p50 DESC
      LIMIT 20
    `).all()

    return { overall: overall.results, slowestPaths: byPath.results }
  }
)

RUM Dashboard

RUM Dashboard (Last 7 Days)

Web Vitals Overview:
┌────────┬──────────┬──────────┬──────────┬─────────┐
│ Metric │ P50      │ P75      │ P95      │ % Good  │
├────────┼──────────┼──────────┼──────────┼─────────┤
│ LCP    │ 1,200ms  │ 2,100ms  │ 4,500ms  │ 78%     │
│ CLS    │ 0.02     │ 0.05     │ 0.15     │ 85%     │
│ INP    │ 80ms     │ 150ms    │ 350ms    │ 82%     │
│ TTFB   │ 150ms    │ 350ms    │ 900ms    │ 88%     │
└────────┴──────────┴──────────┴──────────┴─────────┘

Performance by Geographic Region:
┌─────────────┬─────────┬──────────┬──────────────┐
│ Region      │ P50 LCP │ P95 LCP  │ Slow % (>3s) │
├─────────────┼─────────┼──────────┼──────────────┤
│ US East     │ 900ms   │ 2,100ms  │ 3%           │
│ US West     │ 1,100ms │ 2,800ms  │ 5%           │
│ Europe      │ 1,300ms │ 3,200ms  │ 8%           │
│ Asia Pacific│ 2,100ms │ 5,500ms  │ 20%          │
│ South America│ 2,400ms│ 6,000ms  │ 25%          │
└─────────────┴─────────┴──────────┴──────────────┘

Top 5 Slowest Pages:
1. /dashboard/analytics (p50 LCP: 4.2s) — heavy charts
2. /products/listing (p50 LCP: 3.8s) — large images
3. /reports/export (p50 LCP: 3.5s) — slow API

Alerts from RUM Data

export const checkRumAlerts = createServerFn({ method: "GET" }).handler(
  async ({}, { context }) => {
    const alerts = []

    // Alert if LCP good percentage drops below threshold
    const lcpQuality = await context.env.DB.prepare(`
      SELECT
        COUNT(*) as total,
        SUM(CASE WHEN rating = 'good' THEN 1 ELSE 0 END) * 100.0 / COUNT(*) as good_pct
      FROM rum_metrics
      WHERE name = 'LCP' AND created_at > datetime('now', '-1 hour')
    `).first()

    if (lcpQuality && Number(lcpQuality.good_pct) < 70) {
      alerts.push({
        type: "rum_degradation",
        metric: "LCP",
        goodPct: Math.round(Number(lcpQuality.good_pct)),
        threshold: 70,
        severity: "high",
      })
    }

    // Alert if any specific page has p95 LCP > 5s
    const slowPages = await context.env.DB.prepare(`
      SELECT pathname, COUNT(*) as views
      FROM rum_metrics
      WHERE name = 'LCP'
        AND value > 5000
        AND created_at > datetime('now', '-1 hour')
      GROUP BY pathname
      HAVING views > 10
      ORDER BY views DESC
      LIMIT 5
    `).all()

    if (slowPages.results.length > 0) {
      alerts.push({
        type: "slow_pages",
        pages: slowPages.results,
        severity: "medium",
      })
    }

    return alerts
  }
)

Using RUM to Drive Optimizations

RUM Signal	Investigation	Optimization
High LCP on mobile	Check hero image size	Serve AVIF, preload hero, reduce image size
High CLS on product page	Check dynamic content insertion	Reserve space, fix font swap layout shift
High INP on dashboard	Profile main thread activity	Break up long tasks, lazy load charts
Poor APAC LCP	Geographic latency issue	Edge caching, CDN optimization
Poor TTFB on auth pages	Auth middleware overhead	Optimize session lookup, cache auth state

RUM Data Schema

-- migrations/rum_metrics.sql
CREATE TABLE IF NOT EXISTS rum_metrics (
  id TEXT PRIMARY KEY,
  name TEXT NOT NULL,         -- LCP, CLS, INP, TTFB, FCP
  value REAL NOT NULL,        -- Metric value in ms or score
  rating TEXT NOT NULL,       -- good, needs-improvement, poor
  pathname TEXT NOT NULL,     -- URL path
  device_type TEXT,           -- mobile, desktop, tablet
  connection_type TEXT,       -- 4g, 3g, 2g, slow-2g
  country TEXT,               -- Two-letter country code
  metadata TEXT,              -- JSON with attribution data
  created_at INTEGER NOT NULL
);

CREATE INDEX idx_rum_name ON rum_metrics(name);
CREATE INDEX idx_rum_created ON rum_metrics(created_at);
CREATE INDEX idx_rum_path ON rum_metrics(pathname);

RUM Implementation Checklist

[ ] Web Vitals library installed and initialized on all pages
[ ] RUM data sent via sendBeacon for reliable delivery
[ ] Server endpoint stores metrics in D1 or Analytics Engine
[ ] Sample rate configured (100% for initial setup, then reduce to 10-25%)
[ ] Dashboard built for p50/p75/p95 metrics
[ ] Geographic breakdown visible in dashboard
[ ] Pathname-level aggregation for slow page detection
[ ] Automated alerts for RUM degradation
[ ] Device type segmentation (mobile vs desktop)
[ ] Connection type tracking for network-aware optimization
[ ] Integration with CI pipeline — compare PR RUM vs production RUM
[ ] Historical data retention for trend analysis

Conclusion

Real User Monitoring bridges the gap between what you test in development and what your users experience in production. Without RUM, you are optimizing based on assumptions. With RUM, every optimization decision is backed by data from actual users.

The implementation is straightforward:

Collect Web Vitals from every page load
Store them in D1 or Analytics Engine
Build dashboards for visualization
Set alerts for degradation
Use the data to prioritize optimization work

For a production SaaS with RUM implemented across all pages, see tanstackship.com.

Related Resources

Holiday and Seasonal Promotions: A SaaS Discount Strategy That Works

sweet — Thu, 18 Jun 2026 01:37:00 +0000

Discounting is a double-edged sword for SaaS. Done well, holiday promotions can accelerate annual plan adoption, reactivate churned users, and drive seasonal spikes. Done poorly, they train users to wait for discounts and devalue your product. This guide covers a structured approach to holiday promotions — which holidays to target, what discount structures work, how to manage campaign timing, and the database infrastructure you need to run them. See production campaign management at tanstackship.com.

The SaaS Discounting Dilemma

Discount Strategy	Risk	Reward	Best For
20-30% off annual plans	Low (annual commitment offsets discount)	High	Black Friday, New Year
Free month	Medium (user may cancel after)	Medium	Trial conversion push
Lifetime discount (early adopter)	High (permanent revenue reduction)	Very high	Launch
2-for-1 annual	Medium	High	End-of-year push
First 3 months 50% off	Medium (churn after discount)	Medium	Q1 slumps

Key principle: Discount annual plans, not monthly. An annual discount locks in revenue for 12 months. A monthly discount creates churn risk when the promotional period ends.

Holiday Calendar by Market

Major SaaS Promotion Windows

Holiday	Date	Market	SaaS Opportunity
New Year / Q1 Push	Jan 1-31	Global	Annual plan adoption
Valentine's Day	Feb 14	US, EU	"Love your business" campaign
Spring Sale	March-April	Global	New year, new stack
Tax Season	April	US	Spending mindset
Summer Slump	June-August	Global	"Get ahead before fall"
Back to School	Sept	US, EU	Productivity push
Singles' Day (11.11)	Nov 11	China	Biggest shopping day globally
Black Friday / Cyber Monday	Nov-Dec	Global	The biggest SaaS promo window
Christmas / Year-End	Dec 15-31	Global	Last-chance annual deals

Campaign Structure

Campaign Database Schema

// D1 schema for campaign management
export const campaigns = sqliteTable("campaigns", {
  id: text("id").primaryKey(),
  name: text("name").notNull(),
  slug: text("slug").notNull().unique(),
  type: text("type", {
    enum: ["holiday", "seasonal", "launch", "retention", "reactivation"],
  }).notNull(),
  discountPercent: real("discount_percent").notNull(),
  discountType: text("discount_type", {
    enum: ["percentage", "fixed", "free_month", "tiered"],
  }).notNull(),
  appliesTo: text("applies_to", {
    enum: ["annual", "monthly", "all_plans", "specific_plans"],
  }).notNull(),
  specificPlans: text("specific_plans"), // JSON array of plan IDs
  startDate: integer("start_date", { mode: "timestamp" }).notNull(),
  endDate: integer("end_date", { mode: "timestamp" }).notNull(),
  maxRedemptions: integer("max_redemptions"),
  currentRedemptions: integer("current_redemptions").default(0),
  isActive: integer("is_active", { mode: "boolean" }).default(true),
  couponCode: text("coupon_code"),
  metadata: text("metadata"), // JSON for campaign assets
  createdAt: integer("created_at", { mode: "timestamp" }),
})

Creating a Campaign

// server/campaigns.ts
export const createCampaign = createServerFn({ method: "POST" }).handler(
  async ({ data, context }: { data: CreateCampaignInput }) => {
    const id = crypto.randomUUID()

    // Create Stripe coupon
    const coupon = await stripe.coupons.create({
      percent_off: data.discountPercent,
      duration: "once",
      max_redemptions: data.maxRedemptions,
      applies_to: {
        products: data.specificPlans.length > 0
          ? data.specificPlans
          : undefined,
      },
    })

    await context.env.DB.prepare(`
      INSERT INTO campaigns
        (id, name, slug, type, discount_percent, discount_type,
         applies_to, start_date, end_date, max_redemptions, coupon_code)
      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
    `).bind(
      id, data.name, data.slug, data.type,
      data.discountPercent, data.discountType,
      data.appliesTo, data.startDate.getTime(),
      data.endDate.getTime(), data.maxRedemptions,
      coupon.id
    ).run()

    return { id, couponId: coupon.id }
  }
)

Black Friday Campaign Example

Pre-Launch (2 Weeks Before)

// Prepare campaign assets and notifications
export const prepareCampaign = createServerFn({ method: "GET" }).handler(
  async ({}, { context }) => {
    const upcoming = await context.env.DB.prepare(`
      SELECT * FROM campaigns
      WHERE start_date > ? AND start_date < ?
      AND is_active = 1
    `).bind(Date.now(), Date.now() + 14 * 24 * 60 * 60 * 1000).all()

    for (const campaign of upcoming.results) {
      // Send announcement emails to subscribers
      await sendCampaignAnnouncement(campaign)

      // Update pricing page to show upcoming sale
      // Update in KV for zero-downtime
      await context.env.KV.put("campaign:upcoming", JSON.stringify({
        name: campaign.name,
        discountPercent: campaign.discount_percent,
        startDate: campaign.start_date,
        slug: campaign.slug,
      }))
    }

    return { prepared: true, count: upcoming.results.length }
  }
)

Live Campaign

// Apply discount during checkout
export const applyCampaignDiscount = createServerFn({ method: "POST" }).handler(
  async ({ data, context }: {
    data: { campaignSlug: string; priceId: string }
  }) => {
    const campaign = await context.env.DB.prepare(`
      SELECT * FROM campaigns
      WHERE slug = ? AND is_active = 1
      AND start_date <= ? AND end_date >= ?
    `).bind(data.campaignSlug, Date.now(), Date.now()).first()

    if (!campaign) {
      return { valid: false, error: "Campaign not active" }
    }

    // Check redemption limit
    if (campaign.max_redemptions && campaign.current_redemptions >= campaign.max_redemptions) {
      return { valid: false, error: "Campaign fully redeemed" }
    }

    // Increment counter
    await context.env.DB.prepare(`
      UPDATE campaigns SET current_redemptions = current_redemptions + 1
      WHERE id = ?
    `).bind(campaign.id).run()

    return {
      valid: true,
      couponCode: campaign.coupon_code,
      discountPercent: campaign.discount_percent,
    }
  }
)

Promotion Types: Which to Use

Type	Conversion Rate	Revenue Impact	Best Timing
% off annual	+30-50%	High (annual lock-in)	Black Friday, New Year
Free months	+20-30%	Medium	Launch, reactivation
Tiered discount	+25-40%	Medium-High	Extended periods
Limited time	+40-60%	High (urgent)	24-48 hour flash sales
BOGO (buy org, get 1 free)	+15-20%	Medium	Team/Org plans
Bundle discount	+20-25%	Medium	Feature add-ons

Percentage Off vs Free Months

Percentage off annual plan:
  Normal: $29/mo × 12 = $348/year
  With 30% off: $243.60/year (saves $104.40)
  ✅ User commits for 12 months
  ✅ You get cash upfront
  ✅ Lower churn risk

Free months on monthly plan:
  Normal: $29/mo × 12 = $348/year
  With 2 months free: $29/mo × 10 = $290/year (saves $58)
  ❌ User can cancel any time
  ❌ Revenue is deferred
  ❌ Higher churn risk

Winner: Percentage off annual plan

Analytics and Attribution

// Track campaign performance
export const getCampaignAnalytics = createServerFn({ method: "GET" }).handler(
  async ({ data, context }: { data: { campaignId: string } }) => {
    const [campaign, conversions, revenue] = await Promise.all([
      context.env.DB.prepare("SELECT * FROM campaigns WHERE id = ?")
        .bind(data.campaignId).first(),
      context.env.DB.prepare(`
        SELECT COUNT(*) as conversions, SUM(mrr) as total_mrr
        FROM subscriptions
        WHERE coupon_id = (SELECT coupon_code FROM campaigns WHERE id = ?)
        AND created_at BETWEEN
          (SELECT start_date FROM campaigns WHERE id = ?) AND
          (SELECT end_date FROM campaigns WHERE id = ?)
      `).bind(data.campaignId, data.campaignId, data.campaignId).first(),
      context.env.DB.prepare(`
        SELECT SUM(amount) as total_revenue
        FROM invoices
        WHERE subscription_id IN (
          SELECT id FROM subscriptions
          WHERE coupon_id = (SELECT coupon_code FROM campaigns WHERE id = ?)
        )
      `).bind(data.campaignId).first(),
    ])

    return { campaign, conversions, revenue }
  }
)

Anti-Discounting Patterns

Behavior	Problem	Solution
Always running a promotion	Users wait for discounts	Create clear promotion windows
Discounting monthly plans	High churn after promotion	Discount annual only
50%+ discounts	Devalues the product	Cap at 30-40%
No expiration	No urgency	Limited time only
Discounting core features	Trains users to value features less	Discount commitment, not features

Campaign Calendar Template

Q1 (Jan-Mar): New Year Annual Plan Push
  - "New Year, New Stack" — 25% off annual
  - Target: Free users on monthly, upgrade to annual

Q2 (Apr-Jun): Spring Refresh
  - "Spring Cleaning" — 20% off annual
  - Target: Inactive users reactivation

Q3 (Jul-Sep): Back to Business
  - "Back to School for Your Business" — 20% off team plans
  - Target: Team/org plan upgrades

Q4 (Oct-Dec): Black Friday + Year-End
  - Pre-BF: "Early Black Friday" — 30% off annual (limited quantity)
  - BF/CM: "Black Friday Deal" — 35% off annual
  - Year-End: "Last Chance 2026" — 25% off annual
  - Target: All segments, maximum conversion

Promotion Management Checklist

[ ] Campaign start/end dates set with proper timezone handling (UTC)
[ ] Stripe coupon created with redemption limits
[ ] Pricing page dynamically shows/hides promotional pricing
[ ] Email sequences ready: announcement, reminder, last chance, expired
[ ] UTM parameters set for all campaign links
[ ] Analytics dashboard tracking: impressions, clicks, conversions, revenue
[ ] Post-campaign retention analysis (do promo users retain at normal rates?)
[ ] Expired campaigns automatically hidden from checkout
[ ] Customer support briefed on campaign details
[ ] Refund policy adjusted for promotional purchases

Conclusion

Holiday promotions are a powerful growth lever for SaaS — when executed strategically. The key principles are:

Discount annual plans, not monthly — annual commitment protects your revenue
Cap discounts at 30-35% — higher discounts devalue the product
Create urgency — limited-time offers convert better than permanent discounts
Track everything — UTM, coupon codes, conversion analytics, retention rates
Plan a calendar — know your promotion windows months in advance

The campaign management infrastructure — database schema, Stripe integration, analytics tracking — should be built once and reused for every promotion. With the right infrastructure, a holiday campaign is a matter of configuration, not engineering.

For a SaaS with built-in campaign management, UTM tracking, and promotion infrastructure, see tanstackship.com.

Related Resources

React Internationalization Complete Guide (2026): From Zero to Production-Ready Multilingual Apps

sweet — Wed, 17 Jun 2026 01:16:00 +0000

Internationalization (i18n) is no longer optional — SaaS products targeting global markets must support multiple languages from day one to avoid costly rewrites. This guide covers the complete i18n stack for React applications in 2026: choosing between ICU MessageFormat-based libraries like Paraglide and runtime solutions like react-i18next, implementing locale-based routing with TanStack Router, managing translation workflows at scale, handling RTL layouts and pluralization rules, and deploying with SEO-optimized hreflang tags and language-specific sitemaps. Real-world code examples are included for every step. See a production multilingual SaaS at tanstackship.com — built with the exact patterns described here.

Why Internationalization Matters More Than Ever in 2026

The global SaaS market has crossed the $300B mark, and English-only interfaces are leaving money on the table. Data from CSA Research shows that 65% of users prefer content in their native language, and 40% will never buy from a website in another language. For B2B SaaS targeting European and Asian markets, multilingual support is no longer a nice-to-have — it is a prerequisite for market entry.

Modern React i18n is about more than just translating hello to Hallo. A production-grade i18n system must handle:

Concern	Example	Complexity
Text translation	"Welcome" → "Willkommen"	Low
Variable interpolation	"You have {count} messages"	Low
Pluralization	"1 item" vs "{n} items"	Medium
Date/time/number formatting	01/02 vs 02/01 vs 1. Februar	Medium
RTL layout switching	English ↔ Arabic	High
Locale-specific routing	/en/blog vs /de/blog	Medium
SEO metadata per locale	hreflang, canonical, sitemaps	High
Dynamic content translation	CMS content, user-generated text	High

Choosing Your i18n Library: 2026 Landscape

The React i18n ecosystem has matured significantly. Here is the current landscape:

Library	Approach	Bundle Size	RTL	ICU	TypeScript	Recommended For
Paraglide	Compile-time (ICU extract)	~2 KB	✓	✓	✓	Modern TanStack/Next.js apps, edge-deployed
react-i18next	Runtime	~8 KB	✓	Via i18next	✓	Legacy apps, complex interpolation
react-intl (Format.JS)	Runtime + compile	~6 KB	✓	✓	✓	Enterprise, strict ICU compliance
Lingui	Compile-time (extract)	~4 KB	✓	✓	✓	Developer experience focused
react-intl-universal	Runtime	~5 KB	✗	✓	Partial	Simple use cases

Recommendation for 2026

For new TanStack Start projects, Paraglide or Lingui (compile-time approaches) are the best choices. They produce zero-runtime overhead by extracting ICU messages at build time, which aligns perfectly with Cloudflare Workers' 1 MB code size limit. For existing codebases already using react-i18next, the v24 release added tree-shaking support that significantly reduces bundle size.

Setting Up i18n with TanStack Start and Paraglide

Paraglide is a natural fit for TanStack Start because it operates at compile time, generating type-safe message functions that you import directly. Here is a complete setup:

1. Installation and Configuration

# Install Paraglide and the Vite plugin
npm install @inlang/paraglide-js @inlang/paraglide-vite

// vite.config.ts
import { paraglide } from "@inlang/paraglide-vite"
import { defineConfig } from "vite"

export default defineConfig({
  plugins: [
    paraglide({
      project: "./project.inlang",
      outdir: "./src/paraglide",
    }),
    // ... other plugins
  ],
})

2. Defining Messages with ICU Syntax

Messages are defined in JSON files organized by locale:

// messages/en.json
{
  "$schema": "https://inlang.com/schema/message",
  "greeting": "Hello, {name}!",
  "itemCount": "{count} {count, plural, one {item} other {items}}",
  "welcomeBack": "Welcome back, {username}. You have {notifications, plural, =0 {no notifications} one {# notification} other {# notifications}}.",
  "pricing": {
    "monthly": "${price}/month",
    "annual": "${price}/year (save {savings}%)"
  }
}

// messages/de.json
{
  "$schema": "https://inlang.com/schema/message",
  "greeting": "Hallo, {name}!",
  "itemCount": "{count} {count, plural, one {Artikel} other {Artikel}}",
  "welcomeBack": "Willkommen zurück, {username}. Sie haben {notifications, plural, =0 {keine Benachrichtigungen} one {# Benachrichtigung} other {# Benachrichtigungen}}.",
  "pricing": {
    "monthly": "{price}€/Monat",
    "annual": "{price}€/Jahr (sparen Sie {savings}%)"
  }
}

// messages/zh.json
{
  "$schema": "https://inlang.com/schema/message",
  "greeting": "你好，{name}！",
  "itemCount": "{count}{count, plural, other {个项目}}",
  "welcomeBack": "欢迎回来，{username}。你有{notifications, plural, =0 {0条通知} other {#条通知}}。",
  "pricing": {
    "monthly": "¥{price}/月",
    "annual": "¥{price}/年（节省{savings}%）"
  }
}

3. Using Type-Safe Messages in Components

After running the Paraglide compiler, you get type-safe message functions:

// src/lib/i18n.ts
import {
  languageTag,
  setLanguageTag,
  type AvailableLanguageTag,
} from "../paraglide/runtime"
import * as m from "../paraglide/messages"

export { languageTag, setLanguageTag, m }
export type { AvailableLanguageTag }

// src/components/Greeting.tsx
import { m, languageTag } from "../lib/i18n"

export function Greeting({ name }: { name: string }) {
  return (
    <div>
      <h1>{m.greeting({ name })}</h1>
      <p>
        {m.welcomeBack({
          username: name,
          notifications: 3,
        })}
      </p>
      <p>
        Current locale: <strong>{languageTag()}</strong>
      </p>
    </div>
  )
}

Paraglide's compile-time approach means m.greeting() is resolved at build time — there is no runtime lookup cost. The generated code for each locale is tree-shaken so users only download the messages for their active language.

Locale-Based Routing with TanStack Router

For SEO-friendly multilingual URLs, you need locale prefixes in your routes (e.g., /en/blog/post-1, /de/blog/beitrag-1). Here is how to implement this with TanStack Router:

// src/routes/__root.tsx
import { createRootRouteWithContext, redirect } from "@tanstack/react-router"
import { languageTag, setLanguageTag } from "../lib/i18n"
import type { AvailableLanguageTag } from "../lib/i18n"

// Detect locale from URL or default to 'en'
function detectLocale(pathname: string): AvailableLanguageTag {
  const locales: AvailableLanguageTag[] = ["en", "de", "zh"]
  const match = pathname.match(/^\/(en|de|zh)\//)
  if (match && locales.includes(match[1] as AvailableLanguageTag)) {
    return match[1] as AvailableLanguageTag
  }
  return "en" // default
}

export const Route = createRootRouteWithContext<{
  locale: AvailableLanguageTag
}>()({
  beforeLoad: ({ location }) => {
    const locale = detectLocale(location.pathname)
    setLanguageTag(locale)
    return { locale }
  },
  notFoundComponent: () => <NotFound />,
})

// src/routes/index.tsx
import { createFileRoute, redirect } from "@tanstack/react-router"

// Redirect root to default locale
export const Route = createFileRoute("/")({
  loader: () => {
    throw redirect({ to: "/en" })
  },
})

// src/routes/$locale/index.tsx
import { createFileRoute } from "@tanstack/react-router"
import { m, languageTag } from "../../lib/i18n"

export const Route = createFileRoute("/$locale/")({
  component: HomePage,
})

function HomePage() {
  return (
    <main>
      <h1>{m.greeting({ name: "Developer" })}</h1>
      <p>Current language: {languageTag()}</p>
    </main>
  )
}

Locale Switcher Component

// src/components/LocaleSwitcher.tsx
import { Link, useMatchRoute } from "@tanstack/react-router"
import { useRouter } from "@tanstack/react-router"
import type { AvailableLanguageTag } from "../lib/i18n"

const locales: Record<AvailableLanguageTag, { label: string; flag: string }> = {
  en: { label: "English", flag: "🇺🇸" },
  de: { label: "Deutsch", flag: "🇩🇪" },
  zh: { label: "中文", flag: "🇨🇳" },
}

export function LocaleSwitcher() {
  const router = useRouter()
  // Use router state to get current locale
  const currentLocale = router.state.context.locale

  return (
    <div className="flex gap-2">
      {(Object.entries(locales) as [AvailableLanguageTag, typeof locales[AvailableLanguageTag]][]).map(
        ([tag, { label, flag }]) => (
          <Link
            key={tag}
            to={router.state.location.pathname.replace(
              /^\/(en|de|zh)/,
              `/${tag}`
            )}
            className={`px-3 py-1 rounded ${
              tag === currentLocale ? "bg-blue-500 text-white" : "bg-gray-100"
            }`}
            onClick={() => {
              // Update locale without full page reload
              import("../lib/i18n").then(({ setLanguageTag }) => {
                setLanguageTag(tag)
              })
            }}
          >
            {flag} {label}
          </Link>
        )
      )}
    </div>
  )
}

Handling RTL Layouts

For Arabic, Hebrew, and Persian locales, you need to flip your entire layout. Here is a clean approach:

// src/lib/i18n.ts (extended)
const rtlLocales = new Set(["ar", "he", "fa"])

export function isRTL(locale: string): boolean {
  return rtlLocales.has(locale)
}

export function getDirection(locale: string): "ltr" | "rtl" {
  return isRTL(locale) ? "rtl" : "ltr"
}

// src/routes/__root.tsx (extended)
import { getDirection } from "../lib/i18n"

function RootLayout() {
  const { locale } = Route.useRouteContext()
  const dir = getDirection(locale)

  return (
    <html dir={dir} lang={locale}>
      <body>
        <LocaleSwitcher />
        <Outlet />
      </body>
    </html>
  )
}

Use logical CSS properties (margin-inline-start instead of margin-left, padding-inline-end instead of padding-right) throughout your stylesheets so they automatically flip in RTL mode.

Date, Time, and Number Formatting

Never hardcode date formats. Use Intl.DateTimeFormat and Intl.NumberFormat:

// src/lib/format.ts
import { languageTag } from "../paraglide/runtime"

export function formatDate(
  date: Date | string,
  options?: Intl.DateTimeFormatOptions
): string {
  return new Intl.DateTimeFormat(languageTag(), {
    year: "numeric",
    month: "long",
    day: "numeric",
    ...options,
  }).format(new Date(date))
}

export function formatCurrency(
  amount: number,
  currency = "USD"
): string {
  return new Intl.NumberFormat(languageTag(), {
    style: "currency",
    currency,
  }).format(amount)
}

export function formatNumber(
  value: number,
  options?: Intl.NumberFormatOptions
): string {
  return new Intl.NumberFormat(languageTag(), options).format(value)
}

Usage:

formatDate("2026-06-08")
// en: "June 8, 2026"
// de: "8. Juni 2026"
// zh: "2026年6月8日"

formatCurrency(29.99)
// en: "$29.99"
// de: "29,99 €"
// zh: "¥29.99"

formatNumber(1000000)
// en: "1,000,000"
// de: "1.000.000"
// zh: "1,000,000"

Translation Workflow at Scale

For anything beyond 50 messages, manual JSON editing becomes error-prone. Set up a proper translation workflow:

Extract → Translate → Merge Pipeline

# Extract messages from source code
npx @inlang/cli extract --source messages/en.json --output messages/extracted.json

# Send to translation service (example: DeepL API)
curl -X POST "https://api.deepl.com/v2/translate" \
  -d "auth_key=$DEEPL_KEY" \
  -d "text=$(cat messages/extracted.json | jq -r '.[]')" \
  -d "target_lang=DE" > messages/de_translated.json

# Merge translations back
npx @inlang/cli merge --source messages/de_translated.json --target messages/de.json

Best Practices for Translation Management

Use a single source of truth — Maintain English as your primary locale and translate outward
Add context comments for translators:

{
  "checkout": {
    "paymentMethod": {
      "message": "Payment Method",
      "comment": "Header shown above credit card / PayPal selection on checkout page"
    }
  }
}

Avoid string concatenation — Always use ICU parameters so translators can rearrange word order naturally:

// ❌ Bad
const message = `Order #${orderId} from ${storeName}`

// ✅ Good
m.orderSummary({ orderId: "#1234", storeName: "My Shop" })

Never translate UI through CSS — Content pseudo-elements, ::before/::after with text content are invisible to i18n tools

SEO: hreflang, Canonical, and Language-Specific Sitemaps

A multilingual site without proper SEO signals will be penalized for duplicate content. Here is the complete setup:

hreflang Tags

// src/components/SeoHead.tsx
import { Head } from "@tanstack/react-start"

interface HreflangProps {
  currentPath: string
  locales: string[]
}

export function HreflangTags({ currentPath, locales }: HreflangProps) {
  const baseUrl = "https://tanstackship.com"

  return (
    <Head>
      {locales.map((locale) => (
        <link
          key={locale}
          rel="alternate"
          hrefLang={locale}
          href={`${baseUrl}/${locale}${currentPath}`}
        />
      ))}
      <link
        rel="alternate"
        hrefLang="x-default"
        href={`${baseUrl}/en${currentPath}`}
      />
    </Head>
  )
}

Language-Specific Sitemaps

// src/server/sitemap.ts
export async function generateSitemap(locale: string) {
  const posts = await getBlogPosts(locale) // Filter by locale
  const pages = getStaticPages(locale)

  const xml = `<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
        xmlns:xhtml="http://www.w3.org/1999/xhtml">
  ${[...pages, ...posts]
    .map(
      (page) => `
  <url>
    <loc>https://tanstackship.com/${locale}${page.path}</loc>
    <lastmod>${page.updatedAt}</lastmod>
    <xhtml:link rel="alternate" hreflang="en" href="https://tanstackship.com/en${page.path}"/>
    <xhtml:link rel="alternate" hreflang="de" href="https://tanstackship.com/de${page.path}"/>
    <xhtml:link rel="alternate" hreflang="zh" href="https://tanstackship.com/zh${page.path}"/>
  </url>`
    )
    .join("")}
</urlset>`

  return xml
}

Dynamic Content and CMS Translations

SaaS applications often have user-generated or CMS-managed content. Here is how to handle it:

// src/lib/content-i18n.ts
// For database-backed content with translations
interface TranslatedContent {
  locale: string
  title: string
  body: string
  slug: string
}

export async function getLocalizedContent(
  contentId: string,
  locale: string
): Promise<TranslatedContent | null> {
  const result = await env.DB.prepare(
    `SELECT locale, title, body, slug
     FROM content_translations
     WHERE content_id = ? AND locale = ?`
  )
    .bind(contentId, locale)
    .first()

  if (result) return result as TranslatedContent

  // Fallback to default locale
  return env.DB.prepare(
    `SELECT locale, title, body, slug
     FROM content_translations
     WHERE content_id = ? AND locale = ?`
  )
    .bind(contentId, "en")
    .first() as Promise<TranslatedContent | null>
}

Database schema for translated content:

CREATE TABLE content_translations (
  id TEXT PRIMARY KEY,
  content_id TEXT NOT NULL,
  locale TEXT NOT NULL CHECK (locale IN ('en', 'de', 'zh')),
  title TEXT NOT NULL,
  body TEXT NOT NULL,
  slug TEXT NOT NULL,
  created_at INTEGER NOT NULL DEFAULT (unixepoch()),
  updated_at INTEGER NOT NULL DEFAULT (unixepoch()),
  UNIQUE(content_id, locale)
);

CREATE INDEX idx_content_translations_locale
  ON content_translations(locale);

Production Checklist

Before shipping your multilingual React app, verify each item:

[ ] All user-facing strings use i18n message functions (run a lint rule to enforce)
[ ] ICU messages have context comments for translators
[ ] RTL layout support is tested with a real RTL language
[ ] Locale detection works for browser preferences (Accept-Language header)
[ ] Locale switcher persists preference (cookie or localStorage)
[ ] hreflang tags are present on every page
[ ] Language-specific sitemaps are generated and submitted to Google Search Console
[ ] Date, time, currency, and number formatting use Intl.* APIs
[ ] SEO metadata (title, description, og:locale) is locale-specific
[ ] Translation fallback chain is defined (requested → default → English)
[ ] Bundle size per locale is verified (no duplicated messages)

Conclusion

Internationalization is a系统工程 that touches every layer of your React application — from routing and state management to database design and SEO. The key takeaways for 2026 are:

Choose a compile-time i18n library like Paraglide or Lingui for zero-runtime overhead and better edge-deployment compatibility
Use ICU MessageFormat for all messages — it handles pluralization, gender, and complex grammar rules that simple string templates cannot
Implement locale-based routing from day one; retrofitting it later requires URL redirects and SEO recovery
Build SEO signals into your i18n system — hreflang, canonical URLs, and locale-specific sitemaps must be generated automatically
Test with real content in every supported language — placeholder translations hide layout bugs and text overflow issues

A properly internationalized React application is not just about translation files. It is an architectural decision that influences data modeling, deployment strategy, and even your team's content workflow. Get it right early, and your SaaS can expand into any market without a rewrite.

Related Resources

Product Hunt Launch Playbook: From Preparation to #1 Product of the Day

sweet — Tue, 16 Jun 2026 01:12:00 +0000

A successful Product Hunt launch can generate thousands of signups, hundreds of backlinks, and significant SEO value — but the difference between #1 and invisible is in the preparation. This playbook covers the complete launch process: pre-launch groundwork, maker profile optimization, launch day execution, community engagement strategies, and post-launch follow-through. Based on the experience of launching tanstackship.com on Product Hunt.

Why Product Hunt?

Metric	Average Launch	Top 3 Launch	Impact
Upvotes	100-300	500-1500	Social proof
Website visits (day of)	5,000-20,000	30,000-100,000	Traffic spike
New signups	50-300	500-3,000	User acquisition
Backlinks	10-30	50-200	SEO value
Email subscribers	50-200	200-1,000	List growth
Press mentions	1-3	5-20	Media coverage

Phase 1: Pre-Launch (4-6 Weeks Before)

Step 1: Optimize Your Maker Profile

// Product Hunt profile checklist:
const makerProfile = {
  username: "your_maker_name",
  avatar: "professional_headshot.webp",   // Not logo
  bio: "Indie SaaS builder. Created TanStack Ship.",
  website: "https://tanstackship.com",
  twitter: "@yourhandle",
  // Add portfolio of past products (even small ones)
  // Each product builds credibility
}

Step 2: Build Your Hunter Network

A hunter introduces your product to the Product Hunt community. Choose carefully:

Hunter Type	Pros	Cons
Top Hunter (1M+ followers)	Massive visibility	Less personal relationship
Niche Hunter (10K-50K)	Targeted audience	Smaller scale
Peer Hunter (fellow maker)	Genuine support	Smaller reach
Self-hunt	Full control	Less perceived authority

Step 3: Gather Pre-Launch Assets

The "No Brainer" section of your Product Hunt listing:
├── Tagline: One sentence that explains what you do (max 60 chars)
├── Description: 3-5 paragraphs covering problem, solution, magic
├── Thumbnail: 1280x800 PNG, text + screenshot
├── GIF Demo: 15-30 second product walkthrough (first 3 seconds hook)
├── Video: Optional but adds 30% more engagement
├── First Comment: Template draft (the "maker's story")
└── Maker Comment: (different from first comment, personal touch)

Phase 2: Pre-Launch (1-2 Weeks Before)

Step 4: Build a Teaser Audience

const teaserSchedule = [
  { day: -14, content: "Setting up for our PH launch!" },
  { day: -7, content: "Here's what we're building:" },
  { day: -3, content: "PH launch on Monday! Get notified:" },
  { day: -1, content: "TOMORROW! Set your alarms:" },
]

Step 5: Prepare Your Support Network

// Pre-launch email to supporters
const launchEmail = {
  subject: "We're launching on Product Hunt on Monday!",
  body: `
    Hi {name},

    We're launching on Product Hunt this Monday at 12:01 AM PT.

    Here's how you can help:
    1. Follow our hunter: {hunter_link}
    2. Set a reminder: {reminder_link}
    3. On Monday, upvote and comment (early = counts more)
    4. Share with anyone who might find it useful

    Thank you for your support — it means the world to us!
  `,
}

Phase 3: Launch Day

The Timeline

00:01 AM PT — Product goes live
  → Immediate: Notify your support network (Discord, email, Twitter)
  → First 30 min: Engage with every comment personally
  → Hour 1-2: Share on Twitter/LinkedIn with the product link
  → Hour 3-6: Keep engaging comments, share to niche communities
  → Hour 6-12: Second wave of social sharing (different timezones)
  → Hour 12-18: Evening push — share results, thank supporters
  → Hour 18-24: Final push — "Last few hours to support us!"

Critical: Product Hunt ranking is based on upvotes + comments
weighted by time. An upvote at 1 AM = 3 upvotes at 6 PM.

Engagement Scripts

// Maker comment template
const makerComment = `
Hi Product Hunt community!

I built TanStack Ship because I was tired of rebuilding the same
auth, billing, marketing, and i18n infrastructure for every SaaS.

[2-3 paragraphs about what you built, why it matters, what's unique]

Key features:
• Type-safe TanStack Start + Cloudflare Workers architecture
• Built-in auth, billing, UTM tracking, and referral system
• Multi-language support (EN, ZH, DE) out of the box
• Admin dashboard with all the boring parts done

Would love to hear your feedback and questions. Happy to answer
anything about the stack, the build process, or SaaS in general!

— {maker_name}
`

// Response template for comments
function respondToComment(username: string, question: string): string {
  if (question.includes("stack") || question.includes("tech")) {
    return `Great question, @${username}! We're built on TanStack Start
+ Cloudflare Workers + D1. Full type safety end-to-end, edge-deployed.
Happy to share more details about any specific part of the stack!`
  }
  if (question.includes("pricing") || question.includes("cost")) {
    return `Good question @${username}! We wanted to make this accessible
for solo founders. Plans start at $29/mo, and you can see full pricing
at tanstackship.com/pricing.`
  }
  // Default: personal, helpful, no generic copy-paste
  return `Thanks for the question, @${username}! [specific answer...]`
}

Post-Launch Metrics to Track

// Track launch impact in your analytics
producthunt: {
  upvotes: 847,
  comments: 156,
  rank: 2,                    // #2 Product of the Day
  website_clicks: 12450,
  new_signups: 380,
  attribution: {
    direct_ph: 280,            // Came directly from PH
    social_referral: 65,       // Shared by PH visitors
    delayed_search: 35,        // Searched after hearing from PH
  },
  traffic_spike_day: "12x normal",
  sustained_traffic_30d: "2x normal",  // SEO effect
}

Phase 4: Post-Launch (Week After)

Day	Activity
Day 1	Thank supporters publicly. Update your website with "As seen on Product Hunt"
Day 2	Email the signups from the launch. Nurture them through onboarding
Day 3-5	Repurpose launch content: blog post about the launch, Twitter thread
Day 7	Analyze launch data. What worked? What didn't?
Day 14	Follow-up with top PH commenters who asked questions
Day 30	Check SEO backlinks and rankings from the launch

Common Launch Mistakes

Mistake	Impact	Fix
Launching on a holiday	50-80% fewer upvotes	Check PH calendar
Ignoring comments	Algorithm penalty	Reply within 15 minutes
Generic responses	Lower engagement	Personalize every reply
Launching without audience	10-20 upvotes	Build audience first
Bad timing (weekend)	40% fewer votes	Tuesday-Thursday is best
Not having a hunter	Less credibility	Get a known hunter
Launching and disappearing	Wasted momentum	Stay active all day

Launch Day Infrastructure

// Prepare your site for launch traffic
export const getLaunchConfig = createServerFn({ method: "GET" }).handler(
  async ({}, { context }) => {
    // Scale up resources or ensure rate limits are high enough
    const config = {
      rateLimits: {
        signup: 100,  // Allow 100 signups per minute
        api: 1000,    // 1000 API requests per minute
      },
      features: {
        showLaunchBanner: true,  // "We're #1 on Product Hunt!"
        disableOnboardingGate: false,
        socialProof: true,       // Show live signup counter
      },
    }

    // Store in KV for fast access
    await context.env.KV.put("launch:config", JSON.stringify(config))
    return config
  }
)

Post-Launch Retention

// PH users need different nurturing
export const handlePhSignup = createServerFn({ method: "POST" }).handler(
  async ({ data, context }: { data: { email: string } }) => {
    // Mark as PH-launch user
    await context.env.DB.prepare(`
      INSERT INTO users (id, email, acquisition_channel, created_at)
      VALUES (?, ?, 'product_hunt_launch', ?)
    `).bind(crypto.randomUUID(), data.email, Date.now()).run()

    // PH users convert at lower rates — optimize onboarding
    // 1. Send personalized welcome (mention PH)
    // 2. Fast-track to core feature
    // 3. Offer launch-specific discount
    await sendPhWelcomeEmail(data.email)
  }
)

Product Hunt Launch Checklist

[ ] Maker profile optimized (photo, bio, portfolio)
[ ] Hunter confirmed and scheduled
[ ] Product listing draft complete (tagline, description, images)
[ ] GIF demo recorded (15-30 seconds)
[ ] Teaser content scheduled for 2-week lead-up
[ ] Support network briefed (Discord, email list, Twitter)
[ ] First comment drafted (maker story)
[ ] Comment response templates ready
[ ] Social sharing schedule planned (3-4 waves)
[ ] Site infrastructure tested for traffic spike
[ ] Post-launch email sequence ready
[ ] Analytics tracking set up with campaign tags
[ ] Onboarding optimized for launch users

Conclusion

A Product Hunt launch is not a lottery — it is a process. The #1 Product of the Day is almost always the one that prepared most thoroughly, engaged most authentically, and followed up most diligently.

The real value of Product Hunt is not the one-day traffic spike. It is the backlinks, the SEO boost, the social proof badge, and the relationships built with early users. Treat the launch as the beginning, not the end.

For a complete SaaS with launch-ready infrastructure (campaign tracking, UTM attribution, optimized onboarding), see tanstackship.com.

Related Resources

Performance Budgeting: Setting Targets and Automating Enforcement

sweet — Mon, 15 Jun 2026 01:08:00 +0000

A performance budget is a set of agreed-upon thresholds that your application must not exceed — bundle size, load time, image weight, API latency. Without a budget, performance degrades incrementally with every feature added. This guide covers how to define, measure, and enforce performance budgets in CI/CD, with patterns used at tanstackship.com.

Why Performance Budgets Matter

Performance decays silently. Each feature adds JavaScript, images, and API calls. Individually, each addition is unnoticeable. Cumulatively, over 6-12 months, a page that loaded in 1.5 seconds becomes a 4-second page.

Feature	JS Added	Latency Added	Cumulative (6 months)
Analytics dashboard	18 KB	+100ms	+100ms
Team collaboration	25 KB	+200ms	+300ms
File upload UI	12 KB	+80ms	+380ms
Data export	8 KB	+50ms	+430ms
Chat integration	35 KB	+300ms	+730ms

Without a budget, the 730ms cumulative increase goes unnoticed until users complain — or your Core Web Vitals score drops and SEO rankings fall.

Defining Budgets

Metric Categories

// performance-budget.config.ts
export const performanceBudget = {
  // Quantity budgets — tracked at build time
  javascript: {
    totalInitial: 150 * 1024,    // 150 KB (gzipped)
    routeLevel: 50 * 1024,       // 50 KB per route chunk
  },
  css: {
    totalInitial: 30 * 1024,     // 30 KB
    criticalPath: 15 * 1024,     // 15 KB inlined
  },
  images: {
    heroImage: 200 * 1024,       // 200 KB
    thumbnail: 50 * 1024,        // 50 KB
    totalPageWeight: 500 * 1024, // 500 KB total
    maxImageCount: 15,           // Max images per page
  },
  fonts: {
    total: 40 * 1024,            // 40 KB
    maxCustomFonts: 2,           // Max font families
  },

  // Timing budgets — tracked in CI and RUM
  timing: {
    lcp: 2500,          // < 2.5s
    cls: 0.1,           // < 0.1
    inp: 200,           // < 200ms
    ttfb: 800,          // < 800ms
    firstContentfulPaint: 1800, // < 1.8s
    timeToInteractive: 3500,    // < 3.5s
  },

  // Network budgets
  network: {
    totalRequests: 50,           // Max HTTP requests
    thirdPartyScripts: 5,       // Max third-party scripts
    blockingScripts: 0,         // No render-blocking scripts
  },
}

CI/CD Enforcement with Lighthouse CI

# .github/workflows/performance.yml
name: Performance Budget

on:
  pull_request:
    branches: [main]

jobs:
  lighthouse:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm ci
      - run: npm run build
      - run: npm run start:preview &

      - name: Run Lighthouse CI
        run: |
          npm install -g @lhci/cli
          lhci autorun --config=lighthouserc.json

      - name: Check Bundle Size
        run: |
          npm run build -- --report
          node scripts/check-bundle-size.mjs ./dist/report.html

      - name: Check Image Budget
        run: |
          node scripts/check-image-budget.mjs ./dist/public

      - name: Comment PR on Failure
        if: failure()
        uses: actions/github-script@v6
        with:
          script: |
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: 'Performance budget check failed. See details in the workflow run.'
            })

Lighthouse CI Configuration

{
  "ci": {
    "collect": {
      "numberOfRuns": 3,
      "staticDistDir": "./dist/public",
      "settings": {
        "throttlingMethod": "devtools",
        "formFactor": "desktop"
      }
    },
    "assert": {
      "assertions": {
        "largest-contentful-paint": ["error", { "maxNumericValue": 2500 }],
        "cumulative-layout-shift": ["error", { "maxNumericValue": 0.1 }],
        "interaction-to-next-paint": ["error", { "maxNumericValue": 200 }],
        "total-blocking-time": ["error", { "maxNumericValue": 200 }],
        "max-potential-fid": ["warn", { "maxNumericValue": 100 }],
        "uses-responsive-images": "error",
        "offscreen-images": "error",
        "unminified-javascript": "error",
        "unminified-css": "error",
        "render-blocking-resources": ["warn", { "maxLength": 3 }]
      }
    },
    "upload": {
      "target": "temporary-public-storage"
    }
  }
}

Bundle Size Enforcement

// scripts/check-bundle-size.mjs
import { readFile } from "fs/promises"
import path from "path"

const BUDGET = {
  "main": 150 * 1024,      // Main entry point: 150KB
  "vendor": 50 * 1024,     // Vendor chunk: 50KB
}

async function checkBundleSize() {
  const source = path.join(process.cwd(), "dist", "report.html")
  const content = await readFile(source, "utf-8")

  const failures = []
  for (const [key, max] of Object.entries(BUDGET)) {
    const size = extractBundleSize(content, key)
    if (size && size > max) {
      failures.push(`${key}: ${formatSize(size)} > ${formatSize(max)}`)
    }
  }

  if (failures.length > 0) {
    console.error("Bundle size budget failed:")
    failures.forEach((f) => console.error(`  ${f}`))
    process.exit(1)
  }

  console.log("Bundle size budget passed")
}

Automated Alerts When Budget is Exceeded

// server/monitoring/performance-alerts.ts
export const checkPerformanceAlert = createServerFn({ method: "GET" }).handler(
  async ({}, { context }) => {
    const results = []

    // Check timing budgets from RUM data
    const vitals = await context.env.DB.prepare(`
      SELECT name, AVG(value) as avg, PERCENTILE(value, 95) as p95
      FROM web_vitals
      WHERE created_at > datetime('now', '-1 hour')
      GROUP BY name
    `).all()

    const timingBudget = {
      LCP: 2500,
      CLS: 0.1,
      INP: 200,
      TTFB: 800,
    }

    for (const row of vitals.results) {
      const threshold = timingBudget[row.name as keyof typeof timingBudget]
      if (threshold && Number(row.p95) > threshold) {
        results.push({
          type: "performance_regression",
          metric: row.name,
          p95: row.p95,
          threshold,
          severity: "warning",
        })
      }
    }

    // Check bundle size from build artifacts
    const bundleSize = await context.env.DB.prepare(`
      SELECT route, SUM(size) as total
      FROM bundle_sizes
      WHERE version = (SELECT MAX(version) FROM bundle_sizes)
      GROUP BY route
    `).all()

    const bundleBudget = 150 * 1024 // 150KB
    const oversized = bundleSize.results.filter(
      (r) => Number(r.total) > bundleBudget
    )

    if (oversized.length > 0) {
      results.push({
        type: "bundle_size_exceeded",
        routes: oversized.map((r) => `${r.route}: ${formatSize(r.total)}`),
        severity: "warning",
      })
    }

    return results
  }
)

Budget Visualization Dashboard

// Dashboard component showing budget status
function PerformanceBudgetDashboard() {
  const { data: budgets } = useQuery({
    queryKey: ["performance-budget"],
    queryFn: () => checkPerformanceAlert(),
    refetchInterval: 60_000, // Refresh every minute
  })

  return (
    <div className="grid grid-cols-3 gap-4">
      {Object.entries(timingBudget).map(([metric, budget]) => (
        <BudgetCard
          key={metric}
          metric={metric}
          current={currentValues[metric]}
          budget={budget}
        />
      ))}
    </div>
  )
}

function BudgetCard({ metric, current, budget }: BudgetCardProps) {
  const ratio = current / budget
  const status = ratio > 1 ? "failing" : ratio > 0.8 ? "warning" : "passing"

  return (
    <div className={`budget-card status-${status}`}>
      <div className="metric-name">{metric}</div>
      <div className="current-value">{formatMetric(metric, current)}</div>
      <div className="budget-bar">
        <div className="bar-fill" style={{ width: `${Math.min(ratio * 100, 100)}%` }} />
      </div>
      <div className="budget-limit">Limit: {formatMetric(metric, budget)}</div>
    </div>
  )
}

Budget Maintenance: When to Adjust

Signal	Action
Budget consistently failing by < 10%	Reduce budget by 5% to match actual performance
Budget consistently failing by > 20%	Investigate the root cause — fix before adjusting budget
Budget passes with > 50% headroom	Tighten the budget — you can afford to be more aggressive
New feature requires budget increase	Increase budget, but set a date to optimize and reduce again
Core Web Vitals ranking drops	Investigate and fix — do not adjust budget to match

Team Workflow

Developer opens PR
  → CI runs bundle analysis + Lighthouse
    → All budgets pass → Auto-merge enabled
    → Any budget fails → PR comment with specific failures
      → Developer reviews and optimizes
        → Or: acknowledges regression, adds performance-debt label
        → Performance review on Friday before deploy

Performance Budget Implementation Checklist

[ ] Bundle size budgets defined for JS (initial), CSS, and per-route chunks
[ ] Image budgets defined (total page weight, max count)
[ ] Timing budgets defined (LCP, CLS, INP, TTFB)
[ ] CI pipeline enforces budgets on every PR
[ ] Bundle analyzer integrated into build output
[ ] Lighthouse CI runs on every PR with assertion failures
[ ] Performance budget dashboard in your monitoring tool
[ ] Automated alerts when production budgets are exceeded
[ ] Quarterly budget review and adjustment
[ ] Performance regression label in GitHub for acknowledged regressions

Conclusion

A performance budget is not about perfection — it is about preventing silent degradation. By defining explicit thresholds and enforcing them in CI, you catch performance regressions before they reach production.

The key insight: every feature costs performance. Acknowledging that cost upfront — during code review rather than after user complaints — transforms performance from an afterthought to a first-class design constraint.

TanStack Start helps by keeping the base bundle small (~85 KB for a full-featured app), but the budget should cover everything: your code, your dependencies, your images, and your third-party scripts.

For a production SaaS with performance budgets enforced in CI, see tanstackship.com.

Related Resources

Lighthouse 95+ Optimization Playbook: SaaS Performance Guide

sweet — Sun, 14 Jun 2026 01:27:00 +0000

Achieving Lighthouse 95+ scores is not about chasing a number — it's about engineering a performant experience that directly impacts SaaS conversion rates. This playbook covers Core Web Vitals optimization, SSR with streaming, Critical CSS, bundle splitting, image optimization, and caching strategies. Every recommendation is actionable and production-tested. A 30-point checklist is included at the end.

Introduction: Why Lighthouse 95+ Matters for SaaS

In SaaS, every millisecond counts. Google's research has repeatedly shown that a 1-second delay in mobile page load reduces conversion rates by up to 20%. For a B2B SaaS product with a $100 monthly ARPU and 10,000 signups per month, that delay translates to over $2 million in annual revenue loss.

But the impact goes deeper:

SEO Rankings: Google uses Core Web Vitals as a ranking signal. A site scoring below 50 on Lighthouse is unlikely to rank competitively.
User Trust: Lighthouse scores correlate strongly with perceived reliability.
Ad Spend Efficiency: Lower Quality Scores on Google Ads mean higher cost-per-click.

Lighthouse 95+ is a compound growth lever that touches acquisition, activation, and retention simultaneously.

Understanding Core Web Vitals

Metric	What It Measures	Target
LCP (Largest Contentful Paint)	Loading performance	<= 2.5s
CLS (Cumulative Layout Shift)	Visual stability	<= 0.1
INP (Interaction to Next Paint)	Interactivity	<= 200ms

Performance Budgets: Set Targets from Day One

Define budgets for:

JavaScript bundle size: 150 KB (compressed) for critical route, 300 KB max
Time to Interactive: < 3s on 3G
LCP: < 2.0s
Total page weight: < 500 KB (compressed)

Enforce in CI:

// lighthouse-budget.js
module.exports = {
  ci: {
    collect: { numberOfRuns: 3, settings: { preset: 'desktop' } },
    assert: {
      assertions: {
        'categories:performance': ['error', { minScore: 0.95 }],
        'largest-contentful-paint': ['error', { maxNumericValue: 2500 }],
        'cumulative-layout-shift': ['error', { maxNumericValue: 0.1 }],
        'total-blocking-time': ['error', { maxNumericValue: 200 }],
      },
    },
  },
};

LCP Optimization

1. SSR with Streaming

TanStack Start supports streaming SSR out of the box. Ensure you are not disabling it:

const router = createRouter({
  routeTree,
  defaultPreload: 'intent',
  // Streaming is enabled by default in TanStack Start
});

2. Critical CSS

Inline the CSS required for above-the-fold content. Defer the rest:

<head>
  <style>
    /* Critical CSS — inline above-the-fold styles */
    header, .hero, .cta-button { /* essential styles */ }
  </style>
  <link rel="preload" href="/styles/full.css" as="style"
        onload="this.onload=null;this.rel='stylesheet'" />
  <noscript><link rel="stylesheet" href="/styles/full.css" /></noscript>
</head>

3. Font Loading

Use font-display: swap and preload your primary font:

@font-face {
  font-family: 'Inter';
  src: url('/fonts/inter-var.woff2') format('woff2');
  font-display: swap;
  font-weight: 100 900;
}

Preload it in the HTML head:

<link rel="preload" href="/fonts/inter-var.woff2" as="font" type="font/woff2" crossorigin />

4. Optimize the LCP Element

Preload it: <link rel="preload" as="image" href="/hero.webp" />
Use responsive images for different viewports
Avoid lazy loading the LCP element

CLS Optimization

1. Set Explicit Dimensions

<img
  src="/dashboard-screenshot.webp"
  width="1200"
  height="675"
  alt="Dashboard preview"
  loading="lazy"
/>

2. Font Fallback Metrics

@font-face {
  font-family: 'Inter Fallback';
  src: local('Arial');
  size-adjust: 107%;
  ascent-override: 90%;
  descent-override: 22%;
  line-gap-override: 0%;
}

3. Reserve Space for Dynamic Content

.newsletter-signup-placeholder {
  min-height: 120px;
  /* Reserve space while async content loads */
}

JavaScript Optimization

1. Route-Based Code Splitting

TanStack Router supports route-based code splitting natively:

// routes/dashboard.tsx
export const Route = createLazyRoute('/dashboard')({
  component: DashboardComponent,
});

2. Tree Shaking

Use named imports: import { useQuery } from '@tanstack/react-query'
Mark side-effect-free packages: "sideEffects": false

3. Lazy Load Non-Critical Code

<script>
  window.addEventListener('load', () => {
    setTimeout(() => {
      const script = document.createElement('script');
      script.src = 'https://widget.example.com/loader.js';
      script.async = true;
      document.body.appendChild(script);
    }, 3000);
  });
</script>

Image Optimization

1. Responsive Images with srcset

<img
  src="/hero-1200.webp"
  srcset="/hero-400.webp 400w, /hero-800.webp 800w, /hero-1200.webp 1200w"
  sizes="(max-width: 600px) 400px, (max-width: 1200px) 800px, 1200px"
  width="1200" height="675" alt="Product dashboard"
/>

2. Modern Formats: WebP and AVIF

<picture>
  <source srcset="/hero.avif" type="image/avif" />
  <source srcset="/hero.webp" type="image/webp" />
  <img src="/hero.jpg" width="1200" height="675" alt="Hero" />
</picture>

Caching Strategy

1. CDN Caching

Cache-Control: public, max-age=31536000, immutable  # Versioned assets
Cache-Control: public, max-age=3600, s-maxage=86400  # HTML pages

2. TanStack Query Caching

const { data } = useQuery({
  queryKey: ['pricing-plans'],
  queryFn: fetchPricingPlans,
  staleTime: 5 * 60 * 1000,
  gcTime: 30 * 60 * 1000,
});

30-Point Performance Checklist

Critical

[ ] LCP element is identified and preloaded
[ ] All images have explicit width and height
[ ] Critical CSS is inlined, full CSS is deferred
[ ] Custom fonts use font-display: swap
[ ] No render-blocking third-party scripts
[ ] LCP image uses WebP/AVIF with responsive srcset
[ ] Server response time (TTFB) < 800ms
[ ] Route-based code splitting is implemented
[ ] Unused JavaScript is removed or deferred
[ ] Hero image is not lazy-loaded

High Priority

[ ] All raster images converted to WebP or AVIF
[ ] Font fallback metrics are tuned
[ ] Third-party embeds have reserved space
[ ] Analytics scripts load after onLoad
[ ] Long tasks (>50ms) are identified and split
[ ] JavaScript bundles use Brotli compression
[ ] Static assets use immutable cache headers
[ ] CDN is configured for all asset types
[ ] TanStack Query staleTime is set appropriately
[ ] Service worker caches API responses

Medium Priority

[ ] All images use lazy loading (except LCP)
[ ] preconnect hints for critical origins
[ ] dns-prefetch for analytics domains
[ ] HTML is minified
[ ] CSS is minified, unused rules purged
[ ] No render-blocking JS above the fold
[ ] Preload key API routes
[ ] Use will-change sparingly
[ ] Minimize 301 redirects per page load
[ ] Run Lighthouse CI on every PR

Conclusion

A Lighthouse 95+ score is about engineering a fast, reliable, and delightful user experience that directly grows your SaaS business. The approach is systematic:

Set budgets before you write code
Measure continuously in lab and field
Optimize the critical path: SSR streaming, Critical CSS, font loading, images
Control JavaScript with route splitting and deferred loading
Cache everything aggressively

Start with the checklist. Pick the critical items first. Run Lighthouse CI on every PR. Your users — and your revenue — will thank you.

Related Resources

Image Optimization for Modern Web Applications: Formats, CDNs, Automation

sweet — Sat, 13 Jun 2026 08:23:50 +0000

Images account for 50-70% of a typical web page's weight. Optimizing them properly — choosing the right format, generating responsive sizes, automating compression, and serving from a CDN — is the single highest-impact performance optimization available. This guide covers the complete image optimization pipeline used at tanstackship.com, from development workflow to production delivery.

Image Format Comparison

Format	Compression	Transparency	Animation	Browser Support	File Size vs PNG
JPEG	Lossy	❌	❌	100%	50-70% smaller
PNG	Lossless	✅	❌	100%	Baseline
WebP	Lossy + Lossless	✅	✅	97%	25-35% smaller
AVIF	Lossy + Lossless	✅	✅	93%	50-60% smaller
JPEG XL	Lossy + Lossless	✅	❌	Growing	40-50% smaller

Recommendation in 2026: Serve AVIF as the primary format with WebP fallback. Most modern browsers (93%) support AVIF, and WebP covers the remaining.

Generating Optimized Images

Automated Build Pipeline

// scripts/optimize-images.ts
// Run during build process
import sharp from "sharp"
import { readdir, readFile, writeFile } from "fs/promises"
import path from "path"

interface ImageConfig {
  source: string       // Original image path
  outputDir: string    // Base output directory
  formats: string[]    // ['avif', 'webp', 'jpeg']
  sizes: number[]      // [640, 1200, 1920]
  quality: number      // 80
}

async function optimizeImage(config: ImageConfig) {
  const inputBuffer = await readFile(config.source)
  const filename = path.parse(config.source).name

  for (const format of config.formats) {
    for (const width of config.sizes) {
      const outputPath = path.join(
        config.outputDir,
        format,
        `${filename}-${width}w.${format}`
      )

      await sharp(inputBuffer)
        .resize(width, undefined, { withoutEnlargement: true })
        .toFormat(format as any, { quality: config.quality })
        .toFile(outputPath)

      console.log(`Created: ${outputPath}`)
    }
  }
}

Responsive Images with srcset

// components/OptimizedImage.tsx
interface OptimizedImageProps {
  src: string  // e.g., "/images/dashboard"
  alt: string
  widths?: number[]
  sizes?: string
  priority?: boolean
}

function OptimizedImage({
  src,
  alt,
  widths = [640, 1200, 1920],
  sizes = "(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw",
  priority = false,
}: OptimizedImageProps) {
  const formats = ["avif", "webp", "jpeg"]
  const suffix = priority ? "fetchPriority='high'" : "loading='lazy'"

  return (
    <picture>
      {/* Modern format first */}
      {formats.map((format) => (
        <source
          key={format}
          type={`image/${format === "jpeg" ? "jpeg" : format}`}
          srcSet={widths
            .map((w) => `${src}-${w}w.${format} ${w}w`)
            .join(", ")
          }
          sizes={sizes}
        />
      ))}
      {/* Fallback */}
      <img
        src={`${src}-1200w.jpeg`}
        srcSet={widths
          .map((w) => `${src}-${w}w.jpeg ${w}w`)
          .join(", ")
        }
        alt={alt}
        width={1200}
        height={675}
        decoding="async"
        {...(priority ? { fetchPriority: "high" as const } : { loading: "lazy" as const })}
      />
    </picture>
  )
}

CDN-Based Image Optimization

Using Cloudflare Image Resizing eliminates the need for build-time generation:

// Skip build-time optimization — transform on the fly
function CdnImage({ src, width, alt, priority = false }: CdnImageProps) {
  const baseUrl = "https://tanstackship.com/cdn-cgi/image"

  // Generate transform URLs
  const formats = [
    { format: "avif", url: `${baseUrl}/width=${width},format=avif,quality=80/${src}` },
    { format: "webp", url: `${baseUrl}/width=${width},format=webp,quality=80/${src}` },
    { format: "jpeg", url: `${baseUrl}/width=${width},format=jpeg,quality=85/${src}` },
  ]

  return (
    <picture>
      {formats.map(({ format, url }) => (
        <source key={format} type={`image/${format}`} srcSet={url} />
      ))}
      <img
        src={`${baseUrl}/width=${width},format=jpeg,quality=85/${src}`}
        alt={alt}
        width={width}
        loading={priority ? "eager" : "lazy"}
        fetchPriority={priority ? "high" : "auto"}
      />
    </picture>
  )
}

Image Resizing Options

// Available CDN parameters — build helper
interface ImageTransformOptions {
  width?: number       // 1-4096
  height?: number      // 1-4096
  fit?: "scale-down" | "contain" | "cover" | "crop" | "pad"
  quality?: number     // 1-100
  format?: "webp" | "avif" | "jpeg" | "png"
  sharpen?: number     // 0-10
  blur?: number        // 0-250
  brightness?: number  // -100 to 100
  contrast?: number    // -100 to 100
  gamma?: number       // 0.1-9.99
}

function buildImageUrl(basePath: string, opts: ImageTransformOptions): string {
  const params = Object.entries(opts)
    .filter(([, v]) => v !== undefined)
    .map(([k, v]) => `${k}=${v}`)
    .join(",")

  return `/cdn-cgi/image/${params}/${basePath}`
}

Lazy Loading Strategy

// Intelligent lazy loading based on viewport position
function LazyImage({ src, alt, threshold = 0.1 }: LazyImageProps) {
  const imgRef = useRef<HTMLImageElement>(null)
  const [loaded, setLoaded] = useState(false)
  const [inView, setInView] = useState(false)

  useEffect(() => {
    const observer = new IntersectionObserver(
      ([entry]) => {
        if (entry.isIntersecting) {
          setInView(true)
          observer.disconnect()
        }
      },
      { rootMargin: "200px", threshold }
    )

    if (imgRef.current) observer.observe(imgRef.current)
    return () => observer.disconnect()
  }, [threshold])

  return (
    <div ref={imgRef} className="image-wrapper" style={{ minHeight: "200px" }}>
      {inView ? (
        <img
          src={src}
          alt={alt}
          onLoad={() => setLoaded(true)}
          className={loaded ? "loaded" : "loading"}
          loading="lazy"
        />
      ) : (
        <div className="image-skeleton" />
      )}
    </div>
  )
}

Lazy Loading Method	Pros	Cons
Native `loading="lazy"`	Zero JS, browser-native	Less control over threshold
Intersection Observer	Precise control	Requires JS
Below-fold only	Simple	Manual per-image
Priority hints	Works with native lazy	Limited browser support

Automated Image Pipeline

// server/images/pipeline.ts
export const uploadImage = createServerFn({ method: "POST" }).handler(
  async ({ request, context }) => {
    const formData = await request.formData()
    const file = formData.get("image") as File

    // Validation
    if (!file.type.startsWith("image/")) throw new Error("Invalid file type")
    if (file.size > 10 * 1024 * 1024) throw new Error("File too large")

    const buffer = await file.arrayBuffer()
    const id = crypto.randomUUID()
    const key = `images/${id}`

    // Store original
    await context.env.MY_BUCKET.put(`${key}/original`, buffer, {
      httpMetadata: { contentType: file.type },
    })

    // Generate thumbnails via Image Resizing
    const sizes = [
      { width: 150, suffix: "thumb" },
      { width: 400, suffix: "small" },
      { width: 800, suffix: "medium" },
      { width: 1600, suffix: "large" },
    ]

    for (const { width, suffix } of sizes) {
      // Store reference — actual resize happens on CDN
      await context.env.MY_BUCKET.put(`${key}/${suffix}.webp`, buffer)
    }

    return {
      id,
      urls: {
        original: `https://images.tanstackship.com/${key}/original`,
        thumb: `https://images.tanstackship.com/cdn-cgi/image/width=150/${key}/original`,
        small: `https://images.tanstackship.com/cdn-cgi/image/width=400/${key}/original`,
        medium: `https://images.tanstackship.com/cdn-cgi/image/width=800/${key}/original`,
        large: `https://images.tanstackship.com/cdn-cgi/image/width=1600/${key}/original`,
      },
    }
  }
)

Performance Impact

Image Type	Before	After (AVIF + Responsive)	Savings
Hero image (1920px)	1.2 MB (JPEG)	180 KB (AVIF)	85%
Blog thumbnail (400px)	180 KB (JPEG)	35 KB (AVIF)	81%
Product screenshot (1200px)	850 KB (PNG)	120 KB (WebP)	86%
Icon set (32px SVG)	25 KB	25 KB (already optimized)	—
Total page weight	2.5 MB	380 KB	85% reduction

Image CDN Cost Comparison

Provider	Bandwidth	Transformations	Storage
Cloudflare Images	Included with Workers	$0.50/1000 unique	$5/1000 images
Cloudflare Image Resizing	Free with Pro Biz	per-request	N/A (via R2)
imgix	$0.10/GB	Included	$0.20/GB
Cloudinary	Free tier: 25GB CDN	25GB transformations	25GB storage
AWS CloudFront + Lambda@Edge	$0.085/GB	Lambda cost	S3 pricing

Image Optimization Checklist

[ ] AVIF used as primary format, WebP as fallback
[ ] Responsive images with srcset and sizes attributes
[ ] Lazy loading for all images below the fold
[ ] Explicit width and height to prevent CLS
[ ] CDN-based image transformation for dynamic sizing
[ ] Automated build pipeline for static images
[ ] Image quality set to 80-85 (diminishing returns after this)
[ ] SVG used for icons and illustrations where possible
[ ] Preload LCP images with fetchpriority="high"
[ ] Monitor Lighthouse image optimization score weekly

Conclusion

Image optimization is not optional — it is the single highest-impact performance optimization for most web pages. The modern approach combines three strategies:

Format selection: AVIF for quality, WebP for compatibility
Responsive delivery: Different sizes for different viewports
CDN optimization: Transform on the edge, cache at the edge

With Cloudflare Image Resizing, you can skip the build-time optimization pipeline entirely and let the CDN handle format selection, resizing, and compression dynamically. This simplifies the development workflow while delivering optimal images to every browser.

For a production site with complete image optimization, see tanstackship.com.

Related Resources

File Upload Architecture: R2, Multipart, and Streaming in TanStack Start

sweet — Sat, 13 Jun 2026 00:59:00 +0000

File upload is a critical feature for most SaaS applications — profile images, document attachments, media libraries, and data imports. TanStack Start on Cloudflare Workers, combined with R2 object storage, provides a complete upload architecture with edge-native performance. This guide covers multipart form uploads, direct-to-R2 uploads from the browser, streaming uploads for large files, image processing pipelines, access control, and a production-ready upload flow used at tanstackship.com.

Architecture Overview

Component	Purpose	Performance
Browser	File selection, chunking, progress	Client-side
TanStack Start (Worker)	Auth, validation, presigned URLs	~5ms cold start
Cloudflare R2	Object storage, S3-compatible	Global, no egress fees
Images	Resize, format conversion	Workers + R2

Multipart Form Upload

The simplest approach: upload files as part of a form submission using TanStack Start's server functions:

// server/uploads.ts
import { createServerFn } from "@tanstack/react-start"

export const uploadProfileImage = createServerFn({
  method: "POST",
}).handler(async ({ request, context }) => {
  const formData = await request.formData()
  const file = formData.get("avatar") as File

  if (!file) {
    throw new Error("No file provided")
  }

  // Validate file type and size
  const allowedTypes = ["image/jpeg", "image/png", "image/webp"]
  if (!allowedTypes.includes(file.type)) {
    return { success: false, error: "Invalid file type" }
  }

  if (file.size > 5 * 1024 * 1024) {
    return { success: false, error: "File too large (max 5MB)" }
  }

  // Upload to R2
  const key = `avatars/${context.user.id}/${file.name}`
  await context.env.MY_BUCKET.put(key, await file.arrayBuffer(), {
    httpMetadata: { contentType: file.type },
  })

  return {
    success: true,
    url: `https://r2.tanstackship.com/${key}`,
  }
})

// Client component
import { useMutation } from "@tanstack/react-query"
import { uploadProfileImage } from "../server/uploads"

function AvatarUpload() {
  const mutation = useMutation({
    mutationFn: (file: File) => {
      const formData = new FormData()
      formData.append("avatar", file)
      return uploadProfileImage({ data: formData })
    },
  })

  return (
    <div>
      <input
        type="file"
        accept="image/*"
        onChange={(e) => {
          const file = e.target.files?.[0]
          if (file) mutation.mutate(file)
        }}
      />
      {mutation.isPending && <progress>Uploading...</progress>}
      {mutation.data?.success && <img src={mutation.data.url} alt="avatar" />}
      {mutation.data?.error && <p className="error">{mutation.data.error}</p>}
    </div>
  )
}

Direct-to-R2 Uploads (Presigned URLs)

For larger files, use presigned URLs to upload directly to R2 from the browser, bypassing the Worker entirely:

// server/uploads.ts
export const getUploadUrl = createServerFn({ method: "GET" }).handler(
  async ({ data, context }: { data: { filename: string; contentType: string } }) => {
    const key = `uploads/${crypto.randomUUID()}-${data.filename}`

    // Generate presigned PUT URL (valid for 1 hour)
    const url = await context.env.MY_BUCKET.createPresignedUrl({
      key,
      method: "PUT",
      expiryInSeconds: 3600,
    })

    return {
      uploadUrl: url,
      publicUrl: `https://r2.tanstackship.com/${key}`,
    }
  }
)

// Client — direct upload to R2
async function uploadDirect(file: File) {
  const { uploadUrl } = await getUploadUrl({
    data: { filename: file.name, contentType: file.type },
  })

  const response = await fetch(uploadUrl, {
    method: "PUT",
    body: file,
    headers: { "Content-Type": file.type },
  })

  if (response.ok) {
    showToast("Upload complete!")
  }
}

When to Use Each Method

Method	File Size	Use Case	Pros	Cons
Form data via Worker	< 5 MB	Profile pics, documents	Simple, validation in Worker	Worker execution time
Presigned URL	< 100 MB	Media uploads, backups	No Worker overhead, fast	Extra round-trip for URL
Chunked upload	> 100 MB	Videos, datasets	Pause/resume, progress	Complex implementation

Chunked Upload for Large Files

// server/uploads.ts
export const initiateMultipartUpload = createServerFn({ method: "POST" }).handler(
  async ({ data }: { data: { filename: string; parts: number } }) => {
    const uploadId = crypto.randomUUID()
    const key = `uploads/${uploadId}-${data.filename}`

    // Generate presigned URLs for each chunk
    const presignedUrls = await Promise.all(
      Array.from({ length: data.parts }, (_, i) =>
        context.env.MY_BUCKET.createPresignedUrl({
          key,
          method: "PUT",
          expiryInSeconds: 7200,
        })
      )
    )

    return { uploadId, key, presignedUrls, chunkSize: 5 * 1024 * 1024 } // 5MB chunks
  }
)

export const completeUpload = createServerFn({ method: "POST" }).handler(
  async ({ data }: { data: { key: string; uploadId: string } }) => {
    // Mark the upload as complete in your database
    await env.DB.prepare(
      "INSERT INTO uploads (id, key, user_id, created_at) VALUES (?, ?, ?, ?)"
    ).bind(data.uploadId, data.key, context.user.id, Date.now()).run()

    return { url: `https://r2.tanstackship.com/${data.key}` }
  }
)

// Client — chunked upload with progress
async function uploadLargeFile(file: File, onProgress: (pct: number) => void) {
  const CHUNK_SIZE = 5 * 1024 * 1024 // 5MB
  const parts = Math.ceil(file.size / CHUNK_SIZE)

  const { uploadId, key, presignedUrls } = await initiateMultipartUpload({
    data: { filename: file.name, parts },
  })

  for (let i = 0; i < parts; i++) {
    const start = i * CHUNK_SIZE
    const chunk = file.slice(start, start + CHUNK_SIZE)

    await fetch(presignedUrls[i], {
      method: "PUT",
      body: chunk,
    })

    onProgress(((i + 1) / parts) * 100)
  }

  return await completeUpload({ data: { key, uploadId } })
}

Image Processing Pipeline

Combine R2 with Cloudflare Image Resizing or a Workers-based pipeline:

// server/images.ts
export const processAndUploadImage = createServerFn({ method: "POST" }).handler(
  async ({ data, context }) => {
    const { buffer, filename } = data

    // Generate multiple sizes
    const sizes = [
      { suffix: "thumb", width: 150, height: 150 },
      { suffix: "small", width: 400, height: 300 },
      { suffix: "full", width: 1200, height: 900 },
    ]

    const uploads = await Promise.all(
      sizes.map(async ({ suffix, width, height }) => {
        const key = `images/${filename}/${suffix}.webp`
        const processed = await resizeImage(buffer, { width, height, format: "webp" })

        await context.env.MY_BUCKET.put(key, processed, {
          httpMetadata: { contentType: "image/webp" },
        })

        return { suffix, url: `https://r2.tanstackship.com/${key}` }
      })
    )

    return { urls: uploads }
  }
)

Access Control

Signed URLs for Private Content

export const getSignedDownloadUrl = createServerFn({ method: "GET" }).handler(
  async ({ data, context }: { data: { key: string } }) => {
    // Check authorization
    const upload = await env.DB.prepare(
      "SELECT user_id FROM uploads WHERE key = ?"
    ).bind(data.key).first()

    if (!upload || upload.user_id !== context.user.id) {
      throw new Error("Unauthorized")
    }

    // Generate temporary download URL
    return await context.env.MY_BUCKET.createPresignedUrl({
      key: data.key,
      method: "GET",
      expiryInSeconds: 3600,
    })
  }
)

File Validation Middleware

// server/uploads.ts
const fileValidators = {
  image: {
    maxSize: 5 * 1024 * 1024, // 5MB
    types: ["image/jpeg", "image/png", "image/webp", "image/avif"],
  },
  document: {
    maxSize: 20 * 1024 * 1024, // 20MB
    types: [
      "application/pdf",
      "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
      "text/csv",
    ],
  },
  video: {
    maxSize: 500 * 1024 * 1024, // 500MB
    types: ["video/mp4", "video/webm"],
  },
} as const

function validateFile(file: File, category: keyof typeof fileValidators) {
  const rules = fileValidators[category]

  if (!rules.types.includes(file.type as any)) {
    return `Invalid file type. Allowed: ${rules.types.join(", ")}`
  }
  if (file.size > rules.maxSize) {
    return `File too large. Maximum: ${rules.maxSize / 1024 / 1024}MB`
  }
  return null
}

Cost Analysis: R2 vs S3 vs Local Storage

Storage Provider	Storage (1TB)	Egress (1TB)	A Operations (10M)	B Operations (10M)
Cloudflare R2	$15.00	$0.00	$0.36	$0.36
AWS S3 Standard	$23.00	$90.00	$0.05	$0.05
AWS S3 - IA	$12.50	$90.00	$0.10	$0.10
Backblaze B2	$6.00	$10.00	$0.00	$0.00

R2's zero egress fees are a significant advantage for SaaS applications where users frequently access uploaded files.

Production Security Checklist

[ ] File type validation on both client and server
[ ] File size limits enforced — reject oversized uploads before processing
[ ] Unique filenames using UUIDs to prevent path traversal
[ ] Content-Type headers set explicitly on R2 objects
[ ] Presigned URLs with short expiration (1 hour max for PUT, 1 day for GET)
[ ] Authorization check before generating download URLs
[ ] Upload rate limiting per user (prevent abuse)
[ ] Virus scanning for document uploads (WebAssembly-based ClamAV on Workers)
[ ] CORS configuration on R2 bucket restricts origins
[ ] Audit logging of all upload and download events

Conclusion

File upload architecture is a critical consideration for any SaaS application. TanStack Start + Cloudflare R2 provides a scalable, cost-effective foundation that handles everything from small profile images to multi-gigabyte media files.

The key architectural decisions:

Small files (< 5 MB) — Upload through Worker for inline validation
Medium files (5-100 MB) — Presigned URLs for direct-to-R2 uploads
Large files (> 100 MB) — Chunked upload with progress tracking
Private files — Signed URLs with authorization checks
Images — Processing pipeline with multiple size variants

For a production implementation of this architecture, see tanstackship.com.

Related Resources

Finding Product-Market Fit: A Data-Driven Framework for SaaS Founders

sweet — Fri, 12 Jun 2026 01:12:00 +0000

Product-market fit is not a binary milestone — it is a measurable state where your product solves a problem so well that users return organically and tell others. This guide presents a quantifiable framework for measuring PMF, including the Supergraphic metric, cohort retention analysis, the Sean Ellis test, and specific action plans for when you have not yet found fit. The techniques described here were used in the development of tanstackship.com.

What Product-Market Fit Actually Means

The most practical definition comes from Andrew Chen (a16z): PMF is when your retention curve flattens. Users do not churn because your product has become a habit.

Before PMF, your retention curve looks like this:

100% │
 75% │    ↘
 50% │      ↘
 25% │        ↘
  0% │__________↘____
     │ D1  D7  D30  D90

After PMF:

100% │
 75% │    ↘
 50% │      ↘───
 25% │        ────
  0% │__________────
     │ D1  D7  D30  D90

The difference is the plateau — users who reach day 30 tend to stay. This is the single metric that matters more than any other.

The Supergraphic Metric

Coined by David Sacks (Yammer/Craft Ventures), the Supergraphic is a simple cohort retention chart that visually shows PMF:

// Calculate cohort retention from your analytics database
// src/server/analytics.ts
export const getCohortRetention = createServerFn({ method: "GET" }).handler(
  async ({}, { context }) => {
    const rows = await context.env.DB.prepare(`
      SELECT
        strftime('%Y-%m', created_at) as cohort_month,
        COUNT(DISTINCT id) as total_users,
        COUNT(DISTINCT CASE WHEN last_active_at >= datetime('now', '-7 days')
          THEN id END) as active_last_week,
        COUNT(DISTINCT CASE WHEN last_active_at >= datetime('now', '-30 days')
          THEN id END) as active_last_month
      FROM users
      GROUP BY cohort_month
      ORDER BY cohort_month DESC
      LIMIT 12
    `).all()

    return rows.results.map((row) => ({
      cohort: row.cohort_month,
      retention: (row.active_last_month / row.total_users) * 100,
      weeklyActive: (row.active_last_week / row.total_users) * 100,
    }))
  }
)

Reading the Supergraphic:

If earlier cohorts show higher retention than recent ones → product is improving
If all cohorts converge at ~30-40% → you have weak PMF
If any cohort stably plateaus > 40% → you have strong PMF
If the most recent cohort drops below 20% → you have a problem with onboarding or activation

The Sean Ellis Survey

The most famous PMF metric: "How would you feel if you could no longer use the product?"

// Prompt this survey in-app after 2 weeks of usage
const pmfSurvey = {
  question: "How would you feel if you could no longer use [Product Name]?",
  options: [
    "Very disappointed",
    "Somewhat disappointed",
    "Not disappointed",
    "N/A — I no longer use it",
  ],
}

Survey Result	Interpretation
40%+ "Very disappointed"	Strong PMF — focus on growth
25-40% "Very disappointed"	Promising — improve core features
< 25% "Very disappointed"	Need to find the right problem or audience

Implementation

// Track survey responses against user behavior
export const submitPmfSurvey = createServerFn({ method: "POST" }).handler(
  async ({ data, context }: { data: { response: string } }) => {
    await context.env.DB.prepare(
      `INSERT INTO pmf_surveys (user_id, response, created_at) VALUES (?, ?, ?)`
    ).bind(context.user.id, data.response, Date.now()).run()

    // Also check: do "very disappointed" users have higher usage?
    return { recorded: true }
  }
)

Cohort Retention Analysis

Set up automatic cohort analysis using TanStack Start server functions and Cloudflare D1:

export const getCohortAnalysis = createServerFn({ method: "GET" }).handler(
  async ({ data, context }: { data: { months: number } }) => {
    const cohorts = []

    for (let i = 0; i < data.months; i++) {
      const cohortStart = new Date()
      cohortStart.setMonth(cohortStart.getMonth() - i)
      cohortStart.setDate(1)

      const cohortEnd = new Date(cohortStart)
      cohortEnd.setMonth(cohortEnd.getMonth() + 1)

      const rows = await context.env.DB.prepare(`
        WITH cohort_users AS (
          SELECT id, created_at FROM users
          WHERE created_at >= ? AND created_at < ?
        ),
        weekly_retention AS (
          SELECT
            u.id,
            CAST(julianday(e.created_at) - julianday(u.created_at) AS INTEGER) / 7 as week
          FROM cohort_users u
          JOIN events e ON e.user_id = u.id AND e.name = 'session'
        )
        SELECT
          week,
          COUNT(DISTINCT id) as retained_users
        FROM weekly_retention
        GROUP BY week
        ORDER BY week
      `).bind(cohortStart.getTime(), cohortEnd.getTime()).all()

      cohorts.push({
        cohort: cohortStart.toISOString().slice(0, 7),
        retention: rows.results,
      })
    }

    return cohorts
  }
)

Retention Benchmarks by Industry

SaaS Type	D1 Retention	D7 Retention	D30 Retention	PMF Threshold
Consumer social	60%	40%	25%	30%
B2B productivity	80%	60%	40%	50%
B2B SaaS (SMB)	85%	65%	45%	55%
B2B SaaS (Enterprise)	90%	75%	60%	70%
E-commerce	50%	30%	15%	20%
Developer tools	70%	50%	35%	45%

The PMF Action Framework

Scenario A: Retention Plateau > 40%

Action: Scale acquisition

You have found PMF. Stop optimizing the product for retention and focus on:

Increasing paid acquisition spend
SEO and content marketing
Referral program optimization
Expanding to adjacent markets

Scenario B: Retention Plateau 20-40%

Action: Deepen engagement

You have partial PMF — some user segments love you, others do not:

Segment power users and identify what they do differently
Build features specific to the high-retention segment
Consider repositioning for a narrower audience
Improve onboarding for the second user archetype

Scenario C: Retention Plateau < 20%

Action: Pivot or narrow

Something is fundamentally wrong:

Re-interview the 5-10 users who tried and churned
Run the Sean Ellis survey and analyze "Not disappointed" responses
Consider a narrower target market or different problem
If you are building a developer tool, check: is the first-run experience under 5 minutes?

Leading Indicators of PMF

Before you have enough data for cohort analysis, watch for these signals:

Signal	How to Measure	Good Signal
Organic signups	UTM source = direct/referral	> 30% of total signups
Self-serve conversions	Paid without touching sales	> 20% conversion rate
Feature adoption	% of users using core feature	> 60% weekly use
NPS score	Post-onboarding survey	> 30
Time to value	From signup to first "aha"	< 5 minutes
Support ticket nature	Feature requests vs bug reports	More feature requests
Customer requests	Word-of-mouth referrals	> 1 referral per user

Case Study: PMF Journey at TanStack Ship

When we started building at tanstackship.com, the initial assumption was that the product would appeal to all React developers building SaaS. Cohort analysis told a different story:

Cohort Analysis (Early Stage):
┌────────────┬──────────┬──────────┬──────────┐
│ Cohort     │ D1       │ D7       │ D30      │
├────────────┼──────────┼──────────┼──────────┤
│ 2025-Q3    │ 82%      │ 52%      │ 18%      │
│ 2025-Q4    │ 85%      │ 58%      │ 22%      │
│ 2026-Q1    │ 88%      │ 62%      │ 35%      │
│ 2026-Q2    │ 91%      │ 71%      │ 48%      │
└────────────┴──────────┴──────────┴──────────┘

The key insight from user interviews: users who were solo founders or small teams building their first SaaS had significantly higher retention than users evaluating it as part of an enterprise stack. We narrowed messaging, documentation, and feature development to serve the solo founder segment first.

Measuring PMF With Your Analytics Infrastructure

If you have built UTM and event tracking into your SaaS (as TanStack Ship provides), you can automate PMF measurement:

// Automate PMF dashboard with worker cron
export const generatePmfReport = createServerFn({ method: "GET" }).handler(
  async ({}, { context }) => {
    const [retention, survey, usage] = await Promise.all([
      getCohortRetention(),
      getPmfSurveyResults(),
      getCoreFeatureAdoption(),
    ])

    return {
      supergraphic: retention,
      seanEllisScore: survey.veryDisappointedPercent,
      dailyActiveUsers: usage.dau,
      weeklyActiveUsers: usage.wau,
      recommendation: survey.veryDisappointedPercent > 40
        ? "Scale acquisition"
        : survey.veryDisappointedPercent > 25
        ? "Deepen engagement"
        : "Investigate pivot",
    }
  }
)

Conclusion

Product-market fit is not magic — it is measurable. The Supergraphic shows you at a glance whether your retention curve is flattening. The Sean Ellis survey tells you whether users would miss your product. Cohort analysis reveals which segments love you and which do not.

The framework is simple but not easy:

Measure cohort retention weekly
Survey users at the 2-week mark
Segment power users and analyze their behavior
Act on the data — narrow, deepen, or pivot

Most startups fail not because they never find PMF, but because they give up too early or pivot too late. A systematic, data-driven approach removes the guesswork.

For a SaaS starter with built-in analytics and cohort tracking infrastructure, see tanstackship.com.