name: virality
description: |
Viral growth infrastructure. Social sharing, OG images, referral systems, distribution.
Make your product inherently shareable. Audit, implement, verify—every time.
argument-hint: "[focus area, e.g. 'og-images' or 'referrals']"

/virality

Make your product spread. Social sharing, referral loops, distribution channels—every time.

Philosophy

Virality is a feature, not an accident. Products don't go viral by luck. They're engineered to spread.

Every user interaction is a sharing opportunity. Completed a task? Share it. Hit a milestone? Share it. Created something? Share it.

Remove friction from sharing. One click to share. Beautiful previews. Pre-filled copy.

Measure the loop. K-factor (viral coefficient) tells you if growth is self-sustaining.

What This Does

Audits your product for shareability, identifies viral loop opportunities, implements sharing infrastructure, and verifies the mechanics work. Every run does the full cycle.

Branching

Assumes you start on master/main. Before making code changes:

git checkout -b feat/virality-$(date +%Y%m%d)

Process

1. Audit

Social Metadata Check

# OG tags present?
grep -rE "og:title|og:description|og:image" \
  --include="*.tsx" --include="*.ts" --include="*.html" \
  app/ src/ pages/ 2>/dev/null | head -5

# Twitter cards?
grep -rE "twitter:card|twitter:title|twitter:image" \
  --include="*.tsx" --include="*.ts" \
  app/ src/ pages/ 2>/dev/null | head -5

# Dynamic OG images?
[ -f "app/api/og/route.tsx" ] || [ -d "pages/api/og" ] && echo "✓ OG image endpoint" || echo "✗ OG image endpoint"

# Metadata in layout?
grep -q "generateMetadata\|metadata" app/layout.tsx 2>/dev/null && echo "✓ Root metadata" || echo "✗ Root metadata"

Share Mechanics Check

# Share buttons exist?
grep -rE "share|Share|navigator.share|clipboard" \
  --include="*.tsx" --include="*.ts" \
  components/ src/ 2>/dev/null | head -5

# Shareable URLs?
grep -rE "shareUrl|shareLink|getShareUrl" \
  --include="*.tsx" --include="*.ts" \
  . 2>/dev/null | grep -v node_modules | head -5

# Deep linking?
grep -rE "searchParams|useSearchParams|\[.*\]" \
  --include="*.tsx" --include="*.ts" \
  app/ pages/ 2>/dev/null | head -5

Referral System Check

# Referral codes?
grep -rE "referral|invite|inviteCode|refCode" \
  --include="*.tsx" --include="*.ts" --include="*.sql" \
  . 2>/dev/null | grep -v node_modules | head -5

# Attribution tracking?
grep -rE "utm_|referrer|attribution" \
  --include="*.tsx" --include="*.ts" \
  . 2>/dev/null | grep -v node_modules | head -5

Distribution Readiness Check

# Product Hunt assets?
[ -f "public/product-hunt-logo.png" ] || [ -d "public/launch" ] && echo "✓ Launch assets" || echo "✗ Launch assets"

# Press kit / media assets?
[ -d "public/press" ] || [ -d "public/media" ] && echo "✓ Press kit" || echo "✗ Press kit"

# Changelog / updates page?
[ -f "app/changelog/page.tsx" ] || [ -f "pages/changelog.tsx" ] && echo "✓ Changelog page" || echo "✗ Changelog page"

2. Plan

Every shareable product needs:

Essential (every product):
- Open Graph tags on all public pages
- Twitter Card tags
- Dynamic OG images for key content
- Copy-to-clipboard share URLs
- Mobile-friendly share (Web Share API)

For user-generated content:
- Unique shareable URLs per item
- Beautiful social previews per item
- One-click sharing after creation
- "Share your [thing]" prompts

For growth:
- Referral system with tracking
- Invite flows
- Attribution (UTM) tracking
- K-factor measurement

For launches:
- Product Hunt assets and timing
- Press kit with logos/screenshots
- Changelog page for updates
- Social proof (testimonials, stats)

3. Execute

Add Root Metadata

// app/layout.tsx
import type { Metadata } from 'next';

export const metadata: Metadata = {
  metadataBase: new URL(process.env.NEXT_PUBLIC_APP_URL!),
  title: {
    default: 'Your Product - Tagline',
    template: '%s | Your Product',
  },
  description: 'One sentence that makes people want to try it.',
  openGraph: {
    type: 'website',
    locale: 'en_US',
    siteName: 'Your Product',
    images: ['/og-default.png'],
  },
  twitter: {
    card: 'summary_large_image',
    creator: '@yourhandle',
  },
};

Create Dynamic OG Image Endpoint

// app/api/og/route.tsx
import { ImageResponse } from 'next/og';

export const runtime = 'edge';

export async function GET(request: Request) {
  const { searchParams } = new URL(request.url);
  const title = searchParams.get('title') ?? 'Your Product';
  const description = searchParams.get('description') ?? '';

  return new ImageResponse(
    (
      <div
        style={{
          height: '100%',
          width: '100%',
          display: 'flex',
          flexDirection: 'column',
          alignItems: 'center',
          justifyContent: 'center',
          backgroundColor: '#000',
          color: '#fff',
          fontFamily: 'system-ui',
        }}
      >
        <div style={{ fontSize: 60, fontWeight: 'bold' }}>{title}</div>
        {description && (
          <div style={{ fontSize: 30, marginTop: 20, opacity: 0.8 }}>
            {description}
          </div>
        )}
      </div>
    ),
    { width: 1200, height: 630 }
  );
}

Add Page-Specific Metadata

// app/[slug]/page.tsx
import type { Metadata } from 'next';

export async function generateMetadata({ params }): Promise<Metadata> {
  const item = await getItem(params.slug);

  return {
    title: item.title,
    description: item.description,
    openGraph: {
      title: item.title,
      description: item.description,
      images: [`/api/og?title=${encodeURIComponent(item.title)}`],
    },
  };
}

Create Share Component

// components/share-button.tsx
'use client';

import { useState } from 'react';

interface ShareButtonProps {
  url: string;
  title: string;
  text?: string;
}

export function ShareButton({ url, title, text }: ShareButtonProps) {
  const [copied, setCopied] = useState(false);

  const share = async () => {
    // Try native share first (mobile)
    if (navigator.share) {
      try {
        await navigator.share({ url, title, text });
        return;
      } catch {
        // User cancelled or not supported
      }
    }

    // Fallback to clipboard
    await navigator.clipboard.writeText(url);
    setCopied(true);
    setTimeout(() => setCopied(false), 2000);
  };

  return (
    <button onClick={share}>
      {copied ? 'Copied!' : 'Share'}
    </button>
  );
}

Add Share Prompts at Key Moments

// After user completes an action
function onComplete() {
  // Show share prompt
  showShareModal({
    title: "You did the thing!",
    prompt: "Share your achievement?",
    url: `${baseUrl}/share/${resultId}`,
    prefilledText: "I just [did thing] with @YourProduct!",
  });
}

Implement Referral System

// lib/referrals.ts
export function generateReferralCode(userId: string): string {
  // Short, memorable codes
  return `${userId.slice(0, 4).toUpperCase()}${randomChars(4)}`;
}

export function getReferralUrl(code: string): string {
  return `${process.env.NEXT_PUBLIC_APP_URL}?ref=${code}`;
}

// Track on signup
export async function trackReferral(newUserId: string, refCode: string | null) {
  if (!refCode) return;

  const referrer = await getUserByRefCode(refCode);
  if (!referrer) return;

  await db.referrals.create({
    referrerId: referrer.id,
    referredId: newUserId,
    code: refCode,
    createdAt: new Date(),
  });

  // Reward referrer (if applicable)
  await grantReferralReward(referrer.id);
}

Track Attribution (UTMs)

// middleware.ts or on page load
export function captureAttribution() {
  if (typeof window === 'undefined') return;

  const params = new URLSearchParams(window.location.search);
  const attribution = {
    utm_source: params.get('utm_source'),
    utm_medium: params.get('utm_medium'),
    utm_campaign: params.get('utm_campaign'),
    ref: params.get('ref'),
    referrer: document.referrer,
  };

  // Store for later (signup, conversion)
  sessionStorage.setItem('attribution', JSON.stringify(attribution));
}

Measure K-Factor

// K-factor = invites sent per user × conversion rate
// K > 1 means viral growth

export async function calculateKFactor(timeWindow: string = '30d') {
  const activeUsers = await countActiveUsers(timeWindow);
  const invitesSent = await countInvitesSent(timeWindow);
  const inviteConversions = await countInviteConversions(timeWindow);

  const invitesPerUser = invitesSent / activeUsers;
  const conversionRate = inviteConversions / invitesSent;
  const kFactor = invitesPerUser * conversionRate;

  return {
    kFactor,
    invitesPerUser,
    conversionRate,
    isViral: kFactor > 1,
  };
}

4. Verify

Test OG tags:

# Use a validator
open "https://www.opengraph.xyz/url/$(echo $YOUR_URL | jq -sRr @uri)"

# Or curl and check
curl -s "$YOUR_URL" | grep -E "og:|twitter:" | head -10

Test dynamic OG images:

# Check the endpoint works
curl -I "https://yoursite.com/api/og?title=Test"
# Should return image/png content-type

Test share flow:
1. Create/complete something in the app
2. Click share button
3. Verify URL is correct and copyable
4. Paste URL in Twitter/LinkedIn preview checker
5. Verify preview looks good

Test referral flow:
1. Get your referral link
2. Open in incognito
3. Sign up
4. Verify referral tracked
5. Verify referrer credited

Test mobile share:
1. Open on mobile device
2. Click share
3. Verify native share sheet appears
4. Complete share to an app

If any verification fails, go back and fix it.

Viral Loop Patterns

The Creation Loop

User creates something → Prompted to share → Friend sees → Creates their own → ...

Best for: Tools, generators, creative apps

The Achievement Loop

User hits milestone → Shareable achievement card → Social proof → Friend tries → ...

Best for: Games, learning apps, fitness apps

The Invitation Loop

User invites friend → Friend joins → Both rewarded → Friend invites → ...

Best for: Marketplaces, social apps, collaboration tools

The Content Loop

User creates content → Content has product watermark → Viewer sees → Visits product → ...

Best for: Design tools, video editors, meme generators

Launch Checklist

For Product Hunt and similar:

• [ ] OG image at exactly 1200x630
• [ ] Tagline under 60 characters
• [ ] Description under 260 characters
• [ ] 4-6 screenshots/GIFs
• [ ] Maker comment prepared
• [ ] First comment prepared
• [ ] Launch day = Tuesday/Wednesday
• [ ] Launch time = 12:01 AM PT
• [ ] Notify your network to upvote early

CLI Tools

# Validate OG tags
npx open-graph-scraper https://yoursite.com

# Generate social images locally
npx @vercel/og-image "Title" --output og.png

# Check Twitter card
open "https://cards-dev.twitter.com/validator"

Related Skills

• launch-strategy - Product launch planning
• social-content - Social media content creation
• marketing-ideas - Growth tactics