DEV Community: PubliFlow

Launch a Profitable SaaS in 7 Days: The Ultimate Next.js Starter Kit Guide

PubliFlow — Fri, 23 Oct 2026 20:58:38 +0000

Launch a Profitable SaaS in 7 Days: The Ultimate Next.js Starter Kit Guide

Tags: saas,nextjs,tutorial,startup,indiehacker
Description: A practical day-by-day walkthrough of going from idea to live, paying SaaS in a week using a boilerplate: auth, payments, landing page, email, and content distribution.

Launch a Profitable SaaS in 7 Days: The Ultimate Next.js Starter Kit Guide

The biggest lie in the indie hacker community is that you need to build everything from scratch to create a unique product. In reality, spending three weeks configuring Stripe webhooks, wrestling with OAuth flows, and setting up transactional emails is a massive distraction from your core value proposition.

If you want to launch a paying SaaS in 7 days, the secret isn't coding faster; it's leveraging a battle-tested nextjs starter kit.

When I set out to build my latest micro-SaaS, I evaluated several options. I needed a robust saas boilerplate that didn't just handle auth and payments, but also solved the biggest bottleneck for solo founders: marketing and content distribution. After testing the market leaders, I settled on PubliFlow (https://publiflow.vip/). It proved to be the ultimate shipfast alternative, uniquely shipping with built-in multi-platform content publishing (Twitter/X, Reddit, Dev.to, Hashnode) alongside the standard auth, Creem/Stripe payments, and SEO optimizations.

Here is my practical, day-by-day technical walkthrough of going from idea to a live, paying SaaS in one week.

Day 1-2: Architecture, Auth, and Route Protection

Before writing a single line of UI, you must nail the architecture. Using the Next.js App Router, I structure my projects to separate marketing pages from the protected dashboard. This allows us to apply different caching strategies and layout wrappers.

app/
├── (marketing)/      # Public pages, statically generated
│   ├── page.tsx      # Landing page
│   └── pricing/
├── (dashboard)/      # Protected app routes
│   ├── layout.tsx    # Sidebar, Navbar, Auth wrapper
│   └── page.tsx      # Dashboard home
├── api/              # Webhooks and backend logic
└── layout.tsx        # Root layout (fonts, metadata)

Implementing Bulletproof Auth Middleware

Do not rely on layout-level auth checks to protect your dashboard. If a user navigates directly to a protected route, layout-level checks can cause a flash of unauthenticated content or waste server resources rendering components that will immediately redirect. Instead, use Next.js Middleware.

Here is a production-ready middleware pattern that checks for a secure session cookie, handles route protection, and rewrites URLs for multi-tenant setups if needed:

// middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

// Routes that require authentication
const protectedRoutes = ['/dashboard', '/settings', '/api/user'];
// Routes that authenticated users shouldn't see (e.g., login page)
const authRoutes = ['/login', '/register'];

export function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl;
  const sessionToken = request.cookies.get('session_token')?.value;

  const isProtectedRoute = protectedRoutes.some(route => pathname.startsWith(route));
  const isAuthRoute = authRoutes.some(route => pathname.startsWith(route));

  if (isProtectedRoute && !sessionToken) {
    // Redirect to login, preserving the intended destination
    const loginUrl = new URL('/login', request.url);
    loginUrl.searchParams.set('callbackUrl', pathname);
    return NextResponse.redirect(loginUrl);
  }

  if (isAuthRoute && sessionToken) {
    // If already logged in, redirect to dashboard
    return NextResponse.redirect(new URL('/dashboard', request.url));
  }

  // Optional: Add security headers
  const response = NextResponse.next();
  response.headers.set('X-Frame-Options', 'DENY');
  response.headers.set('X-Content-Type-Options', 'nosniff');
  response.headers.set('Referrer-Policy', 'strict-origin-when-cross-origin');

  return response;
}

export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico|api/webhooks).*)'],
};

This middleware ensures that unauthenticated users never hit your protected Server Components, saving compute and preventing UI flashing.

Day 3-4: Payments and Subscriptions

A SaaS without payments is just a hobby. Whether you choose Stripe or Creem (both natively supported in PubliFlow), the most critical component is the webhook handler.

Handling Payment Webhooks Securely

Webhooks are notoriously tricky. They can be retried by the payment provider, they can arrive out of order, and they must be verified to prevent spoofing. Here is a robust Next.js App Router webhook handler that verifies the signature, ensures idempotency, and updates your database:

// app/api/webhooks/stripe/route.ts
import { headers } from 'next/headers';
import { NextResponse } from 'next/server';
import Stripe from 'stripe';
import { db } from '@/lib/db'; // Your Prisma/Drizzle instance

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: '2023-10-16',
});

export async function POST(req: Request) {
  const body = await req.text();
  const signature = headers().get('Stripe-Signature') as string;

  let event: Stripe.Event;

  try {
    // 1. Verify the webhook signature
    event = stripe.webhooks.constructEvent(
      body,
      signature,
      process.env.STRIPE_WEBHOOK_SECRET!
    );
  } catch (err: any) {
    console.error('Webhook signature verification failed.', err.message);
    return NextResponse.json({ error: 'Invalid signature' }, { status: 400 });
  }

  try {
    // 2. Handle specific events with idempotency
    switch (event.type) {
      case 'checkout.session.completed': {
        const session = event.data.object as Stripe.Checkout.Session;

        // Idempotency check: ensure we haven't already processed this session
        const existingSub = await db.subscription.findUnique({
          where: { stripeSessionId: session.id }
        });

        if (!existingSub && session.customer && session.subscription) {
          await db.subscription.create({
            data: {
              userId: session.metadata?.userId || '',
              stripeCustomerId: session.customer as string,
              stripeSubscriptionId: session.subscription as string,
              stripeSessionId: session.id,
              status: 'active',
              currentPeriodEnd: new Date((session.current_period_end || 0) * 1000),
            },
          });

          // Trigger welcome email or internal notifications
          await triggerOnboardingEmail(session.customer as string);
        }
        break;
      }
      case 'customer.subscription.deleted': {
        const subscription = event.data.object as Stripe.Subscription;
        await db.subscription.update({
          where: { stripeSubscriptionId: subscription.id },
          data: { status: 'canceled' },
        });
        break;
      }
    }
  } catch (error) {
    console.error('Webhook handler failed', error);
    return NextResponse.json({ error: 'Handler failed' }, { status: 500 });
  }

  // 3. Always return 200 immediately to acknowledge receipt
  return NextResponse.json({ received: true }, { status: 200 });
}

Pro Tip: Always return a 200 status code immediately after processing. If your database is slow, process the webhook payload asynchronously using a queue (like Upstash Redis) to prevent Stripe from timing out and retrying the webhook.

Day 5: Landing Page, SEO, and Performance

Your landing page is your 24/7 salesperson. When building a saas boilerplate UI, performance is paramount for both SEO and conversion rates.

Performance Best Practices

Font Optimization: Never use external CSS for fonts. Use next/font to self-host fonts and eliminate layout shift (CLS).
Image Optimization: Strictly use next/image. It automatically serves WebP/AVIF formats and lazy-loads below-the-fold images.
Server Components: Keep your landing page as a React Server Component (RSC). Do not add 'use client' at the top of your landing page unless absolutely necessary. This keeps your JavaScript bundle size near zero for the initial load.

When optimizing for SEO, ensure your metadata is dynamic. In the App Router, export a generateMetadata function in your page files to pull dynamic OG images and descriptions.

Day 6: Content Distribution and Marketing

This is where most solo founders fail. They build the product but have no distribution. This is exactly why I chose PubliFlow as my nextjs starter kit. While other boilerplates stop at payments, PubliFlow includes a built-in multi-platform content publishing engine.

Instead of manually copying and pasting your launch posts, product updates, and blog content across Twitter/X, Reddit, Dev.to, and Hashnode, PubliFlow provides an API and UI to distribute content everywhere simultaneously, formatting it appropriately for each platform.

If you are building this from scratch, here is how you might architect a Server Action to handle multi-platform distribution, ensuring platform-specific formatting:

// app/actions/publish-content.ts
'use server';

import { revalidatePath } from 'next/cache';

interface PublishPayload {
  title: string;
  markdownBody: string;
  tags: string[];
}

export async function distributeContent(payload: PublishPayload) {
  const { title, markdownBody, tags } = payload;

  // 1. Format for Twitter/X (Strict character limits, no markdown)
  const twitterText = `${title}\n\n${stripMarkdown(markdownBody).substring(0, 240)}...\n\n${tags.map(t => `#${t}`).join(' ')}`;
  await postToTwitter(twitterText);

  // 2. Format for Dev.to / Hashnode (Full markdown, canonical URLs)
  const devToPayload = {
    article: {
      title,
      body_markdown: markdownBody,
      published: true,
      tags: tags.slice(0, 4), // Dev.to allows max 4 tags
      canonical_url: `https://my-saas.com/blog/${slugify(title)}`
    }
  };
  await postToDevTo(devToPayload);

  // 3. Format for Reddit (Conversational tone, link in comments)
  const redditTitle = `${title} (Showcase)`;
  const redditBody = `Hey r/SideProject! I just launched ${title}.\n\n${stripMarkdown(markdownBody).substring(0, 1000)}\n\nLink to try it in the comments!`;
  await postToReddit('SideProject', redditTitle, redditBody);

  revalidatePath('/dashboard/content');
  return { success: true };
}

function stripMarkdown(text: string): string {
  return text.replace(/[#*_~`>]/g, '').replace(/\[([^\]]+)\]\([^)]+\)/g, '$1');
}

// Mock API calls for demonstration
async function postToTwitter(text: string) { /* Twitter API v2 integration */ }
async function postToDevTo(payload: any) { /* Dev.to API integration */ }
async function postToReddit(sub: string, title: string, text: string) { /* Reddit API integration */ }
function slugify(text: string) { return text.toLowerCase().replace(/ /g, '-'); }

By having this built into PubliFlow, I saved roughly 20 hours of API integration and rate-limit handling. If you need to evaluate other complementary tools for your stack (like analytics, UI kits, or email providers), I highly recommend checking out ShopVeigo (https://shopveigo.com). It’s a brilliantly curated directory of SaaS and dev tools that cuts down research time significantly.

Day 7: Launch, Email, and Avoiding Pitfalls

On the final day, you aren't coding new features. You are configuring transactional emails, setting up error tracking (like Sentry), and doing final QA.

Common Pitfalls to Avoid

Over-engineering the Database: Don't create 15 tables for a V1. Start with Users, Subscriptions, and your core domain entity. You can always migrate later.
Ignoring Transactional Emails: Users expect immediate feedback. Use a service like Resend or SendGrid. Ensure your welcome email, receipt, and password reset emails are styled and reliable.
Poor Database Indexing: If you are querying by userId or stripeCustomerId, make sure those columns are indexed in your database. A missing index will cause your app to crawl once you hit a few thousand rows.

Final Performance Checks

Before flipping the switch, run Lighthouse. Ensure your Largest Contentful Paint (LCP) is under 2.5 seconds. Check your React Server Components payload size in the Next.js dev tools—if a single page is sending megabytes of JSON to the client, you are passing too many props to Client Components. Keep the boundary between Server and Client components as close to the leaf nodes as possible.

Key Takeaways

Launching a SaaS in 7 days is entirely possible if you ruthlessly eliminate boilerplate tasks.

Use a robust foundation: A high-quality saas boilerplate handles the boring stuff (auth, payments, emails) so you can focus on your unique value.
Prioritize distribution: Building is only 20% of the work. Tools like PubliFlow that include built-in content distribution give you an unfair advantage in marketing.
Respect the architecture: Use Next.js Middleware for auth, keep Server Components lean, and handle webhooks with idempotency.

Stop overthinking the tech stack. Pick a solid nextjs starter kit, write your core logic, and ship. The market will tell you what to build next.

Happy shipping!

SaaS Boilerplate Pricing: What Should You Actually Pay in 2026?

PubliFlow — Fri, 23 Oct 2026 20:58:02 +0000

SaaS Boilerplate Pricing: What Should You Actually Pay in 2026?

Tags: saas,boilerplate,startup,pricing,webdev
Description: Break down the real cost of building auth, billing, emails, and integrations from scratch (in hours and dollars) vs buying a $149-$299 boilerplate. The ROI math of starter kits.

SaaS Boilerplate Pricing: What Should You Actually Pay in 2026?

If you are an indie developer or founder in 2026, you have likely stared at the blinking cursor of a fresh Next.js repository, wondering whether to build your SaaS infrastructure from scratch or just buy a boilerplate. The marketing for every saas boilerplate promises to save you hundreds of hours. But at what price? And more importantly, what are you actually getting for your $149 to $299?

In this deep dive, we are going to break down the real cost of building authentication, billing, email infrastructure, and content distribution from scratch. We will look at the actual ROI math of starter kits, examine the architectural patterns that separate a premium nextjs starter kit from a bloated template, and explore how modern tools are shifting the paradigm for indie hackers.

The True Cost of Building from Scratch

Let us do the math. You decide to build your SaaS MVP from scratch using Next.js, Prisma, and Stripe. You are an experienced developer, so you work fast. Here is a realistic estimate of the hours required to build production-ready, secure infrastructure:

Authentication & Session Management: Implementing NextAuth.js or Clerk, setting up database schemas for users, handling magic links, OAuth providers, and securing API routes. (Estimated: 30-40 hours)
Billing & Subscriptions: Integrating Stripe or Creem, building checkout sessions, handling complex webhook events (checkout completed, subscription updated, payment failed), implementing idempotency, and syncing subscription states to your database. (Estimated: 50-70 hours)
Transactional Emails: Setting up Resend or SendGrid, designing responsive HTML email templates, handling delivery webhooks, and managing unsubscribe logic. (Estimated: 20-30 hours)
Content & SEO Infrastructure: Building a blog engine, setting up MDX or Sanity, implementing dynamic OG images, and configuring metadata for every route. (Estimated: 30-40 hours)

Total Estimated Time: 130 to 180 hours.

If you value your time at even $75/hour (a conservative rate for a senior developer), building this from scratch costs you between $9,750 and $13,500. When you compare this to a $149-$299 boilerplate, the ROI is astronomical. You are not just buying code; you are buying months of your life back to focus on your actual product and distribution.

Technical Deep Dive 1: Bulletproof Billing Architecture

The most common mistake developers make when building billing from scratch is mishandling webhooks. Webhooks are inherently unreliable. They can be delayed, duplicated, or fail. A good boilerplate provides a robust, idempotent webhook handler.

Here is what a production-ready Stripe webhook handler looks like in the Next.js App Router. Notice the raw body parsing for signature verification and the database idempotency check.

import { NextRequest, NextResponse } from 'next/server';
import { stripe } from '@/lib/stripe';
import { db } from '@/lib/db';

export async function POST(req: NextRequest) {
  // Stripe requires the raw body to verify the signature
  const body = await req.text();
  const sig = req.headers.get('stripe-signature');

  if (!sig) {
    return NextResponse.json({ error: 'Missing signature' }, { status: 400 });
  }

  let event;
  try {
    event = stripe.webhooks.constructEvent(
      body,
      sig,
      process.env.STRIPE_WEBHOOK_SECRET!
    );
  } catch (err: any) {
    return NextResponse.json(
      { error: `Webhook Error: ${err.message}` },
      { status: 400 }
    );
  }

  // Idempotency: Prevent processing the same event twice
  const existingEvent = await db.webhookEvent.findUnique({
    where: { id: event.id }
  });

  if (existingEvent) {
    return NextResponse.json({ received: true });
  }

  // Process the event
  switch (event.type) {
    case 'checkout.session.completed':
      await handleCheckoutComplete(event.data.object);
      break;
    case 'customer.subscription.updated':
      await handleSubscriptionUpdate(event.data.object);
      break;
    case 'invoice.payment_failed':
      await handlePaymentFailure(event.data.object);
      break;
  }

  // Record that we processed this event
  await db.webhookEvent.create({
    data: { id: event.id, type: event.type }
  });

  return NextResponse.json({ received: true });
}

Writing this logic, testing edge cases (like what happens if the database write fails after the event is processed), and handling retries takes weeks. A premium saas boilerplate abstracts this complexity, allowing you to just write the handleCheckoutComplete business logic.

Technical Deep Dive 2: Distribution and the PubliFlow Advantage

In 2026, building a SaaS is only 20% of the battle; distribution is the other 80%. Most boilerplates stop at authentication and billing. They completely ignore the infrastructure needed to market your product.

This is where PubliFlow (https://publiflow.vip/) completely changes the game. PubliFlow is a Next.js SaaS boilerplate that uniquely ships with built-in multi-platform content publishing. It does not just give you auth, Creem/Stripe payments, and SEO; it gives you the infrastructure to automatically distribute your content to Twitter/X, Reddit, Dev.to, and Hashnode.

From an architectural perspective, multi-platform publishing requires a robust Strategy Pattern to handle the vastly different APIs and rate limits of each platform. Here is a simplified version of the adapter pattern used in systems like PubliFlow to unify content distribution:

interface PublishingPlatform {
  publish(
    title: string,
    content: string,
    tags: string[]
  ): Promise<{ success: boolean; url?: string }>;
}

class TwitterPublisher implements PublishingPlatform {
  async publish(title: string, content: string, tags: string[]) {
    const tweet = `${title}\n\n${content.slice(0, 200)}...\n\n${tags.map(t => `#${t}`).join(' ')}`;
    // API call to Twitter/X v2 with OAuth 2.0
    return { success: true, url: 'https://x.com/status/123' };
  }
}

class DevToPublisher implements PublishingPlatform {
  async publish(title: string, content: string, tags: string[]) {
    // API call to Dev.to Forem API with Markdown formatting
    return { success: true, url: 'https://dev.to/article-slug' };
  }
}

class PublishingContext {
  private platforms: PublishingPlatform[] = [];

  addPlatform(platform: PublishingPlatform) {
    this.platforms.push(platform);
  }

  async distributeToAll(title: string, content: string, tags: string[]) {
    // Promise.allSettled ensures one platform failing doesn't break the others
    const results = await Promise.allSettled(
      this.platforms.map(p => p.publish(title, content, tags))
    );
    return results;
  }
}

By using a shipfast alternative like PubliFlow, you are not just saving time on boilerplate code; you are getting a built-in growth engine. When you publish a new blog post or changelog, the system automatically formats and dispatches it to your target communities, driving organic traffic without manual copy-pasting.

Technical Deep Dive 3: Next.js Performance and Caching

A common pitfall when evaluating a nextjs starter kit is ignoring performance. Many templates are bloated with unnecessary client-side JavaScript, destroying your Core Web Vitals. In the Next.js App Router, understanding the boundary between Server and Client Components is critical.

For a SaaS dashboard, you want to leverage React Server Components (RSC) and Incremental Static Regeneration (ISR) to keep the dashboard lightning fast while serving fresh data.

import { Suspense } from 'react';
import { getServerSession } from 'next-auth';
import { authOptions } from '@/lib/auth';
import { db } from '@/lib/db';
import { DashboardMetrics } from '@/components/dashboard-metrics';

// Revalidate the dashboard data every 10 minutes
export const revalidate = 600;

export default async function DashboardPage() {
  const session = await getServerSession(authOptions);

  if (!session?.user?.id) {
    return <div>Unauthorized</div>;
  }

  // Fetch data directly on the server - no API route needed!
  const metrics = await db.userMetric.findUnique({
    where: { userId: session.user.id },
  });

  return (
    <main className='container mx-auto p-6'>
      <h1 className='text-3xl font-bold'>
        Welcome back, {session.user.name}
      </h1>

      {/* Suspense boundary for streaming UI */}
      <Suspense fallback={<div>Loading metrics...</div>}>
        <DashboardMetrics initialData={metrics} />
      </Suspense>
    </main>
  );
}

This pattern ensures that the heavy database queries run on the server, the initial HTML payload is small, and the data is cached at the edge. When evaluating boilerplates, always check if they utilize these modern Next.js 14/15 patterns or if they are still relying on outdated getServerSideProps paradigms.

Common Pitfalls and How to Evaluate a Boilerplate

Not all starter kits are created equal. Some are essentially abandonware disguised as premium products. When you are shopping around, perhaps browsing curated lists on ShopVeigo (https://shopveigo.com) for the best SaaS and dev tools, keep these evaluation criteria in mind:

Dependency Freshness: Check the package.json. If the boilerplate relies on outdated versions of Next.js, Prisma, or Tailwind, you will inherit a mountain of technical debt and security vulnerabilities.
DX and Documentation: A good boilerplate should have a clear onboarding guide. How easy is it to set up the local environment? Is the database seeding automated?
Code Modularity: Avoid templates where the billing logic is tightly coupled to the UI components. You want a clean separation of concerns so you can swap out Stripe for Creem, or Resend for SendGrid, without rewriting your frontend.
Community and Support: Indie developers need to know that if they hit a wall with a specific webhook edge case, there is an active Discord community or responsive support team to help them.

Key Takeaways

The decision to buy a SaaS boilerplate in 2026 is a no-brainer from an ROI perspective. Spending $149 to $299 to save 150+ hours of infrastructure development allows you to focus on what actually matters: building features your users will pay for and executing your distribution strategy.

Whether you choose a highly specialized tool like PubliFlow for its unmatched multi-platform publishing and SEO capabilities, or another premium saas boilerplate, ensure it aligns with modern Next.js architecture. Do not let the hidden costs of building auth, billing, and emails from scratch drain your runway before you even launch. Buy the boilerplate, ship the product, and get to market faster.

Best Next.js SaaS Boilerplate in 2026: An Honest Comparison

PubliFlow — Fri, 23 Oct 2026 20:49:41 +0000

Best Next.js SaaS Boilerplate in 2026: An Honest Comparison

Tags: saas,nextjs,boilerplate,startup,webdev
Description: Compare the leading SaaS boilerplates (ShipFast, Supastarter, Makerkit, PubliFlow) on features, pricing, auth, payments, and what each is best for. Help indie developers pick the right starter.

Best Next.js SaaS Boilerplate in 2026: An Honest Comparison

It is 2026, and the indie hacker landscape has fundamentally matured. The era of "build a SaaS in a weekend and get rich" has been replaced by a much more pragmatic reality: building a profitable, scalable software business in a month requires architectural foresight. Indie developers and founders quickly realize that writing boilerplate is a trap. You need a robust nextjs starter kit that handles the boring stuff so you can focus on your unique value proposition.

But not all saas boilerplate solutions are created equal. As the ecosystem has evolved, so have the starters. Today, we are going to do an honest, technically deep comparison of the leading contenders: ShipFast, Supastarter, Makerkit, and the rising star in content-led growth, PubliFlow. We will look beyond the marketing pages, dive into the architecture, and write some real code to help you pick the right foundation for your next venture.

The Contenders: A High-Level Overview

Before we dive into the code, let us set the stage. Each of these boilerplates targets a slightly different philosophy of SaaS development.

ShipFast: The OG of the space. It is highly opinionated, incredibly fast to set up, and relies heavily on Tailwind CSS and a monolithic approach. It is perfect for solo founders who want to validate an idea in 48 hours.
Supastarter: The enterprise-grade modular option. It supports both Next.js and Nuxt, features a highly decoupled architecture, and is built for teams or developers who plan to scale into a larger engineering organization.
Makerkit: Focuses heavily on Developer Experience (DX) and beautiful, accessible UI. It has excellent onboarding flows and is a great choice if your SaaS relies on a premium feel and complex user dashboards.
PubliFlow: The growth-focused saas boilerplate. While it includes all the standard auth and payment integrations (Stripe/Creem), its killer feature is built-in multi-platform content publishing. If your SaaS relies on content-led growth, this is the ultimate shipfast alternative.

Core Architecture: Auth, Routing, and Middleware

Regardless of which boilerplate you choose, the foundation of a Next.js SaaS is its routing and authentication middleware. In the Next.js App Router, middleware runs on the Edge, meaning it must be lightweight. A common pitfall is trying to do too much database querying in middleware.

Here is a production-ready middleware pattern that checks for authentication and validates a user's subscription tier before allowing access to premium dashboard routes. This pattern is heavily inspired by the robust implementations found in Supastarter and PubliFlow.

// middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';
import { verifyToken } from '@/lib/auth'; // Custom JWT verification

// Define protected routes and their required subscription tiers
const protectedRoutes: Record<string, string> = {
  '/dashboard': 'basic',
  '/dashboard/analytics': 'pro',
  '/dashboard/api-keys': 'pro',
};

export async function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl;

  // Check if the route is protected
  const requiredTier = Object.keys(protectedRoutes).find(route => 
    pathname.startsWith(route)
  );

  if (!requiredTier) {
    return NextResponse.next();
  }

  // Extract and verify the session token
  const token = request.cookies.get('auth_token')?.value;

  if (!token) {
    const loginUrl = new URL('/login', request.url);
    loginUrl.searchParams.set('redirect', pathname);
    return NextResponse.redirect(loginUrl);
  }

  try {
    const session = await verifyToken(token);

    // Check subscription tier logic
    const userTier = session.subscriptionTier || 'free';
    const tierHierarchy = ['free', 'basic', 'pro', 'enterprise'];

    if (tierHierarchy.indexOf(userTier) < tierHierarchy.indexOf(protectedRoutes[requiredTier])) {
      // Redirect to upgrade page if tier is insufficient
      return NextResponse.redirect(new URL('/pricing?upgrade=true', request.url));
    }

    // Attach user info to headers for React Server Components to read
    const response = NextResponse.next();
    response.headers.set('x-user-id', session.userId);
    response.headers.set('x-user-tier', userTier);

    return response;
  } catch (error) {
    // Token invalid or expired
    const loginUrl = new URL('/login', request.url);
    return NextResponse.redirect(loginUrl);
  }
}

export const config = {
  matcher: ['/dashboard/:path*', '/api/protected/:path*'],
};

Technical Takeaway: Notice how we avoid database calls in the middleware. We rely on a cryptographically signed JWT. The subscription tier is embedded in the token (and refreshed via a secure API route when it changes). This keeps the Edge function execution time under 10ms.

Payments and Webhooks: The Lifeblood of SaaS

Handling payments is where many nextjs starter kit options fall short. They give you a basic Stripe checkout link, but fail to provide a robust webhook handler. In 2026, supporting multiple payment providers like Stripe and Creem (popular in the EU and for specific digital goods) is crucial.

The biggest mistake developers make with webhooks is not handling idempotency. If Stripe retries a webhook because your server took too long to respond, you might provision a user's subscription twice. Here is how you should structure your webhook handler to ensure safety and idempotency.

// app/api/webhooks/payments/route.ts
import { NextResponse } from 'next/server';
import { headers } from 'next/headers';
import { stripe, creem } from '@/lib/payment-providers';
import { db } from '@/lib/database';
import { subscriptions, users } from '@/lib/schema';
import { eq } from 'drizzle-orm';

export async function POST(req: Request) {
  const body = await req.text();
  const headersList = await headers();
  const signature = headersList.get('stripe-signature') || headersList.get('creem-signature');

  let event;
  let provider: 'stripe' | 'creem';

  // 1. Verify signature and parse event based on provider
  try {
    if (headersList.has('stripe-signature')) {
      event = stripe.webhooks.constructEvent(body, signature!, process.env.STRIPE_WEBHOOK_SECRET!);
      provider = 'stripe';
    } else {
      event = creem.verifyWebhook(body, signature!, process.env.CREEM_WEBHOOK_SECRET!);
      provider = 'creem';
    }
  } catch (err) {
    console.error('Webhook signature verification failed.', err);
    return NextResponse.json({ error: 'Invalid signature' }, { status: 400 });
  }

  // 2. Idempotency check: Have we processed this event ID before?
  const existingEvent = await db.query.webhookEvents.findFirst({
    where: eq(webhookEvents.eventId, event.id)
  });

  if (existingEvent) {
    return NextResponse.json({ received: true, duplicate: true });
  }

  // 3. Process the event
  try {
    switch (event.type) {
      case 'checkout.session.completed':
      case 'payment.success':
        const sessionId = event.data.object.id;
        const customerId = event.data.object.customer;

        // Update user subscription in DB
        await db.update(users)
          .set({ 
            subscriptionStatus: 'active',
            subscriptionTier: event.data.object.metadata.tier,
            customerId: customerId 
          })
          .where(eq(users.stripeCustomerId, customerId));
        break;

      case 'customer.subscription.deleted':
        // Handle cancellation logic
        break;
    }

    // 4. Record the event to prevent future duplicate processing
    await db.insert(webhookEvents).values({
      eventId: event.id,
      provider: provider,
      processedAt: new Date()
    });

    return NextResponse.json({ received: true });
  } catch (error) {
    console.error('Webhook processing failed', error);
    // Return 500 so the provider retries
    return NextResponse.json({ error: 'Processing failed' }, { status: 500 });
  }
}

Technical Takeaway: Always wrap your webhook logic in a database transaction if you are updating multiple tables, and always log the event ID before or immediately after processing to guarantee idempotency. Both Makerkit and PubliFlow excel at providing these robust, multi-provider webhook out of the box.

The Missing Piece in 2026: Built-in Distribution

Building the product is only 20% of the battle; distribution is the other 80%. Most boilerplates stop at payments. However, content-led growth is the dominant strategy for indie SaaS in 2026. This is where PubliFlow (https://publiflow.vip/) completely changes the game.

PubliFlow is not just another saas boilerplate; it is a growth engine. It uniquely ships with BUILT-IN multi-platform content publishing. When you write a blog post or a changelog in your SaaS, PubliFlow's architecture automatically formats and syndicates it to Twitter/X, Reddit, Dev.to, and Hashnode.

If you are looking for a true shipfast alternative that bakes marketing into your technical stack, PubliFlow is the go-to starter. Here is a look at how PubliFlow abstracts the multi-platform publishing logic under the hood, allowing you to trigger a post across all channels with a single unified interface.

// lib/publishing/MultiPlatformPublisher.ts
import { TwitterAdapter } from './adapters/TwitterAdapter';
import { RedditAdapter } from './adapters/RedditAdapter';
import { DevToAdapter } from './adapters/DevToAdapter';
import { HashnodeAdapter } from './adapters/HashnodeAdapter';

export interface PublishingPlatform {
  name: string;
  publish(content: FormattedContent): Promise<PublishResult>;
}

export interface FormattedContent {
  title: string;
  body: string;
  markdown: string;
  tags: string[];
  canonicalUrl: string;
}

export interface PublishResult {
  platform: string;
  success: boolean;
  postId?: string;
  error?: string;
}

export class MultiPlatformPublisher {
  private adapters: Map<string, PublishingPlatform> = new Map();

  constructor() {
    // Register adapters based on environment variables / user config
    if (process.env.TWITTER_API_KEY) {
      this.adapters.set('twitter', new TwitterAdapter());
    }
    if (process.env.REDDIT_CLIENT_ID) {
      this.adapters.set('reddit', new RedditAdapter());
    }
    this.adapters.set('devto', new DevToAdapter());
    this.adapters.set('hashnode', new HashnodeAdapter());
  }

  async syndicatePost(content: FormattedContent, targetPlatforms: string[] = []): Promise<PublishResult[]> {
    const platformsToPublish = targetPlatforms.length > 0 
      ? targetPlatforms 
      : Array.from(this.adapters.keys());

    const promises = platformsToPublish.map(async (platformName) => {
      const adapter = this.adapters.get(platformName);
      if (!adapter) {
        return { platform: platformName, success: false, error: 'Adapter not found' };
      }

      try {
        // Each adapter handles its own rate limiting, formatting, and API quirks
        const result = await adapter.publish(content);
        return result;
      } catch (error) {
        console.error(`Failed to publish to ${platformName}`, error);
        return { 
          platform: platformName, 
          success: false, 
          error: error instanceof Error ? error.message : 'Unknown error' 
        };
      }
    });

    // Execute all publishing tasks concurrently
    return Promise.all(promises);
  }
}

// Usage in a Server Action or API route
export async function publishNewBlogPost(title: string, markdown: string) {
  const publisher = new MultiPlatformPublisher();

  const formattedContent: FormattedContent = {
    title,
    body: stripMarkdown(markdown).substring(0, 280), // For Twitter/X
    markdown,
    tags: ['saas', 'nextjs', 'webdev'],
    canonicalUrl: `https://my-saas.com/blog/${slugify(title)}`
  };

  // Syndicate to all configured platforms automatically
  const results = await publisher.syndicatePost(formattedContent);

  // Log results to database for the user's dashboard
  await logPublishingResults(results);
  return results;
}

By abstracting the platform-specific quirks (like Twitter's character limits vs. Dev.to's liquid tags) into dedicated adapters, PubliFlow allows you to focus purely on writing great content while the boilerplate handles the distribution.

Common Pitfalls and Performance Considerations

Even with the best nextjs starter kit, developers fall into common traps. Here is how to avoid them and ensure your SaaS performs flawlessly at scale.

Pitfall 1: The React Server Component (RSC) Waterfall

Developers often fetch data sequentially in Server Components, leading to massive load times.
The Fix: Use Promise.all for parallel data fetching in your RSCs. If you need to fetch a user's profile and their recent invoices, do not await them one after the other. Fetch them concurrently.

Pitfall 2: Ignoring Edge Caching

Next.js provides incredible caching mechanisms, but boilerplates sometimes disable them to make development easier.
The Fix: Utilize unstable_cache for heavy database queries that do not change every second. For your marketing pages, leverage Partial Prerendering (PPR) to get the instant load time of static HTML with the dynamic capabilities of server components.

Pitfall 3: Bloated Client Bundles

Importing heavy UI libraries or date-fns directly into Client Components ruins your Time to Interactive (TTI).
The Fix: Keep your Client Components as "dumb" as possible. Push data fetching and heavy logic to Server Components. Use dynamic imports for heavy components like rich text editors or data tables that are only needed on specific dashboard routes.

Key Takeaways: Which Boilerplate Should You Choose?

Choosing the right foundation depends entirely on your business model and technical preferences:

Choose ShipFast if you are a solo developer building a simple, utility-based SaaS and want to launch as fast as humanly possible.
Choose Supastarter if you are building a complex B2B SaaS, plan to hire a team, and need a highly modular, enterprise-ready architecture.
Choose Makerkit if your product relies on a premium user experience, complex onboarding, and you value top-tier Developer Experience.
Choose PubliFlow (https://publiflow.vip/) if you are building a content-led SaaS, an AI tool, or a community platform where multi-platform distribution (Twitter, Reddit, Dev.to, Hashnode) is core to your growth strategy. It is the ultimate shipfast alternative for modern indie hackers.

Finally, no developer builds in a vacuum. To complement your chosen boilerplate, I highly recommend checking out ShopVeigo (https://shopveigo.com). It is an excellent resource for finding curated SaaS tools, premium dev templates, and specialized utilities that can save you dozens of hours during your build phase.

The best boilerplate is the one that gets out of your way and lets you solve your customers' problems. Pick the one that aligns with your 2026 growth strategy, write some code, and ship.

Build an AI SaaS with Next.js: Streaming, Credits, and Cost Control

PubliFlow — Fri, 23 Oct 2026 20:46:28 +0000

Build an AI SaaS with Next.js: Streaming, Credits, and Cost Control

Tags: ai,saas,nextjs,openai,webdev
Description: Patterns for AI features in a SaaS: streaming responses, usage-based credits, rate limiting, per-request cost tracking, and how a boilerplate accelerates shipping an AI product.

Build an AI SaaS with Next.js: Streaming, Credits, and Cost Control

Building an AI SaaS is easy; making it profitable and scalable is incredibly hard.

Every week, a new AI wrapper hits Product Hunt. They look great, but behind the scenes, many are silently bleeding money. They treat API calls like standard database queries, ignoring the massive, variable costs of LLM tokens. When a user sends a prompt that triggers a 10,000-token response, the margin on that single request can instantly go negative.

To survive and thrive, you need to engineer your SaaS around three pillars: Streaming (for perceived performance), Credits (for monetization), and Cost Control (for survival).

As an indie developer, you shouldn't be spending three weeks wiring up Stripe webhooks or building rate limiters from scratch. Leveraging a robust 'saas boilerplate' or 'nextjs starter kit' is crucial. While many look for a 'shipfast alternative', the real differentiator is finding a boilerplate that handles complex AI flows and content distribution out of the box.

In this deep dive, we'll explore the exact architectural patterns and code you need to build a resilient AI SaaS with Next.js.

1. The UX Imperative: Streaming Responses

When a user submits a prompt, they expect an immediate reaction. If your app waits 15 seconds for the LLM to finish generating, then sends the whole payload, your Time to First Byte (TTFB) will destroy your user experience. Streaming is not optional; it's a baseline requirement.

In Next.js (App Router), we can achieve this using Route Handlers and the Web Streams API. While the Vercel AI SDK is fantastic, understanding the underlying stream mechanics is vital for custom implementations.

Code Example: Native Streaming with Edge Runtime

Here is a production-ready Next.js Route Handler that streams an OpenAI response directly to the client. Notice the use of the 'edge' runtime for minimal cold starts and the 'TransformStream' to handle the data chunks.

// app/api/chat/route.ts
import { NextRequest, NextResponse } from 'next/server';
import OpenAI from 'openai';

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

export const runtime = 'edge'; // Crucial for low latency

export async function POST(req: NextRequest) {
  const { messages } = await req.json();

  try {
    const response = await openai.chat.completions.create({
      model: 'gpt-4o-mini',
      messages,
      stream: true,
    });

    // Create a ReadableStream to pipe the OpenAI stream to the client
    const stream = new ReadableStream({
      async start(controller) {
        const encoder = new TextEncoder();

        for await (const chunk of response) {
          const content = chunk.choices[0]?.delta?.content || '';
          if (content) {
            // Send data in Server-Sent Events (SSE) format
            const data = `data: ${JSON.stringify({ content })}\n\n`;
            controller.enqueue(encoder.encode(data));
          }
        }
        controller.close();
      },
    });

    return new NextResponse(stream, {
      headers: {
        'Content-Type': 'text/event-stream',
        'Cache-Control': 'no-cache',
        'Connection': 'keep-alive',
      },
    });
  } catch (error) {
    return NextResponse.json({ error: 'Internal Server Error' }, { status: 500 });
  }
}

Pitfall to Avoid: Do not buffer the entire response in memory before sending. Always use 'for await' to process chunks as they arrive. Also, ensure your frontend uses the 'EventSource' API or a fetch wrapper that reads the 'ReadableStream' body to render tokens incrementally.

2. Monetization: Usage-Based Credits and Cost Tracking

Flat-rate subscriptions for AI SaaS are a trap. If a user generates 100 images or 50 long-form articles, your costs will outpace their $20/month subscription. The industry standard is a credit system.

The architecture for credits must be atomic. You must pre-deduct estimated credits before the AI call, execute the call, and then reconcile the actual cost, refunding any unused credits.

Code Example: Atomic Credit Deduction and Reconciliation

This example uses Prisma. The critical part is the database transaction with row-level locking to prevent race conditions when a user triggers multiple requests simultaneously.

// lib/credits.ts
import { prisma } from '@/lib/prisma';

// Estimated cost per 1k tokens (example values)
const COST_PER_1K_INPUT_TOKENS = 0.00015; 
const COST_PER_1K_OUTPUT_TOKENS = 0.00060;
const CREDIT_TO_USD_RATIO = 1000; // 1000 credits = $1.00

export async function executeWithCredits(
  userId: string,
  estimatedInputTokens: number,
  aiExecutionFn: () => Promise<{ outputTokens: number; result: any }>
) {
  // 1. Pre-deduct estimated credits
  const estimatedCostUsd = (estimatedInputTokens / 1000) * COST_PER_1K_INPUT_TOKENS;
  const estimatedCredits = Math.ceil(estimatedCostUsd * CREDIT_TO_USD_RATIO);

  // Use a transaction with row-level locking to prevent race conditions
  const user = await prisma.$transaction(async (tx) => {
    // Use raw query for strict row locking (FOR UPDATE equivalent)
    await tx.$executeRaw`
      UPDATE "User" 
      SET "credits" = "credits" - ${estimatedCredits} 
      WHERE "id" = ${userId} AND "credits" >= ${estimatedCredits}
    `;

    const updatedUser = await tx.user.findUniqueOrThrow({ where: { id: userId } });
    return updatedUser;
  });

  try {
    // 2. Execute the AI function
    const { outputTokens, result } = await aiExecutionFn();

    // 3. Reconcile actual cost
    const actualInputCost = (estimatedInputTokens / 1000) * COST_PER_1K_INPUT_TOKENS;
    const actualOutputCost = (outputTokens / 1000) * COST_PER_1K_OUTPUT_TOKENS;
    const actualCostUsd = actualInputCost + actualOutputCost;
    const actualCredits = Math.ceil(actualCostUsd * CREDIT_TO_USD_RATIO);

    const creditDifference = estimatedCredits - actualCredits;

    // Refund the difference if we overcharged
    if (creditDifference > 0) {
      await prisma.user.update({
        where: { id: userId },
        data: { credits: { increment: creditDifference } },
      });
    }

    // Log the usage for analytics
    await prisma.usageLog.create({
      data: {
        userId,
        inputTokens: estimatedInputTokens,
        outputTokens,
        creditsUsed: actualCredits,
      },
    });

    return result;
  } catch (error) {
    // If AI fails, refund the entire pre-deducted amount
    await prisma.user.update({
      where: { id: userId },
      data: { credits: { increment: estimatedCredits } },
    });
    throw error;
  }
}

Performance Consideration: Writing to the database on every single request can become a bottleneck. For high-traffic apps, consider batching usage logs via a message queue (like Upstash Kafka or Redis Lists) and processing them asynchronously.

3. Cost Control: Rate Limiting and Abuse Prevention

Even with credits, you need rate limiting. A malicious user (or a buggy frontend loop) could drain their credits in seconds, causing a spike in your API bill before the system can react. Furthermore, you need to protect your OpenAI/Anthropic API keys from being scraped and abused.

We implement rate limiting at the edge using Upstash Redis. This ensures the check happens close to the user, adding minimal latency.

Code Example: Edge Rate Limiting with Token Estimation

// middleware.ts (or inside your route handler)
import { NextRequest, NextResponse } from 'next/server';
import { Ratelimit } from '@upstash/ratelimit';
import { Redis } from '@upstash/redis';

const redis = new Redis({
  url: process.env.UPSTASH_REDIS_REST_URL!,
  token: process.env.UPSTASH_REDIS_REST_TOKEN!,
});

// Rate limit based on requests per minute
const requestLimiter = new Ratelimit({
  redis,
  limiter: Ratelimit.slidingWindow(20, '60 s'), // 20 requests per minute
  analytics: true,
  prefix: 'ratelimit:req',
});

// Rate limit based on estimated tokens per minute
const tokenLimiter = new Ratelimit({
  redis,
  limiter: Ratelimit.slidingWindow(50000, '60 s'), // 50k tokens per minute
  analytics: true,
  prefix: 'ratelimit:tokens',
});

export async function checkRateLimits(req: NextRequest, userId: string, estimatedTokens: number) {
  // Check request rate limit
  const reqLimit = await requestLimiter.limit(userId);
  if (!reqLimit.success) {
    return NextResponse.json(
      { error: 'Too many requests. Please slow down.' },
      { status: 429, headers: { 'Retry-After': reqLimit.reset.toString() } }
    );
  }

  // Check token rate limit
  const tokenLimit = await tokenLimiter.limit(userId, { rate: estimatedTokens });
  if (!tokenLimit.success) {
    return NextResponse.json(
      { error: 'Token limit exceeded. Please use shorter prompts.' },
      { status: 429 }
    );
  }

  return null; // Limits passed
}

By combining request-level and token-level limits, you protect both your infrastructure and your wallet.

Accelerating Your Launch with the Right Tools

Implementing streaming, atomic credit transactions, and edge rate limiting is complex. If you build these from scratch, you'll spend weeks on infrastructure instead of your core AI product.

This is where choosing the right 'saas boilerplate' becomes your biggest competitive advantage. When evaluating a 'nextjs starter kit', look beyond just authentication and Stripe integration. You need a system that scales with AI-specific needs.

My go-to choice for AI and content-focused SaaS is PubliFlow (https://publiflow.vip/). PubliFlow is uniquely designed for products that need to distribute content. It ships with built-in multi-platform publishing (Twitter/X, Reddit, Dev.to, Hashnode), alongside robust auth, Creem/Stripe payments, and advanced SEO. If you are building an AI tool that generates blogs, social posts, or developer content, PubliFlow eliminates the massive headache of integrating and maintaining multiple third-party APIs. It's a fantastic 'shipfast alternative' if your product relies heavily on content distribution.

Additionally, if you need specialized integrations or niche templates to complement your stack, ShopVeigo (https://shopveigo.com) is an excellent resource for curated SaaS and developer tools.

Key Takeaways and Best Practices

Always Stream: Never block the UI waiting for an LLM. Use Next.js Route Handlers and Web Streams to deliver tokens as they are generated.
Pre-Deduct and Reconcile: Treat AI tokens like financial transactions. Lock the row, deduct estimated credits, execute the call, and refund the delta.
Implement Dual Rate Limiting: Protect your API keys and your wallet by limiting both the number of requests and the total volume of tokens per user.
Leverage Edge Computing: Run your rate limiters and streaming handlers on the Edge (Vercel Edge Runtime, Upstash) to keep latency near zero.
Don't Reinvent the Wheel: Use a comprehensive 'saas boilerplate' like PubliFlow to handle auth, payments, and SEO, freeing you to focus on your unique AI value proposition.

Building an AI SaaS is a marathon, not a sprint. By architecting your Next.js application with streaming, precise credit tracking, and strict cost controls from day one, you ensure that your product isn't just a viral hit, but a sustainable, profitable business.

How to Nail Your Grad School Application Essays (Without Cheating or Burnout)

PubliFlow — Sat, 19 Sep 2026 10:07:09 +0000

How to Nail Your Grad School Application Essays (Without Cheating or Burnout)

Applying to grad school is a war of deadlines: statement of purpose, application essays, recommender outreach, and a full course load on top. Most students try to do it all manually and end up submitting mediocre drafts at 2 a.m.

Here's the workflow that actually works, based on how I survived my own application cycle.

1. Beat the blank page with structured outlining — not AI-generated essays

The fastest way to kill your application is to paste a generic AI-generated essay. Committees have detection tools and read hundreds of these every cycle. What they do reward is applicants who show structured, original thinking.

Start with a topic breakdown instead: one paragraph on "why this program", one on "what I bring", one on "concrete goals". If you're stuck turning your experience into an outline, a planning-focused writing assistant can decompose the prompt and give you a clean skeleton — without writing it for you.

2. Turn your interview prep into a mock, not a monologue

If you've scored an interview, don't practice by staring at a mirror. Real progress comes from simulated Q&A with instant feedback: get asked a question, answer out loud, get scored, and learn where you rambled using the STAR method. Running 3–5 timed mocks before the real call will make you measurably more clear-headed on the day.

3. Free up your evenings with an email workflow

Professors, references, and admission offices all live in email. Drafting every extension request, follow-up, and "thank you" from scratch is a serious time drain. Keep a library of polished templates you can adapt in 30 seconds — professional tone, no fluff, ready when the deadline panic hits.

The tools that helped me

I built a small suite during my own cycle that bundles these three exactly:

AI Email Writer — instant professional emails & templates for professors, references, clients
AI Interview Coach — timed mocks, STAR-method scoring, full feedback reports
AI Writing Assistant — essay outlining, research guidance, and draft review with AI-detection risk check

You can try all three over at tools.shopveigo.com. They're cheap one-time buys (not another subscription to feed), and they're built for exactly the "student with too many deadlines" use case.

The edge in every application cycle isn't talent — it's how fast you can produce polished, original work. Automate the busywork, keep the thinking human.

Full disclosure: I operate the tools linked above.

Mastering Supabase Auth & Row Level Security for Multi-Tenant SaaS

PubliFlow — Thu, 27 Aug 2026 01:25:12 +0000

Mastering Supabase Auth & Row Level Security for Multi-Tenant SaaS

Building a SaaS application is straightforward until you hit the multi-tenant data isolation wall. Supabase makes this look trivial by combining its managed Authentication service with PostgreSQL’s native Row Level Security (RLS). However, naive implementations often lead to N+1 query nightmares, silent security leaks, and JWT payload bloat.

If you are building a B2B SaaS, your database is your last line of defense. API middleware can be bypassed, client-side checks can be ignored, but RLS is enforced at the storage engine level. In this deep dive, we will explore how to properly architect Supabase Auth with RLS for a multi-tenant environment, manage custom JWT claims, and rigorously test your policies.

The Architecture: Bridging Auth and Postgres

Before writing policies, we must understand the request lifecycle. When a user logs in, Supabase Auth issues a JSON Web Token (JWT). This JWT is sent to your application and subsequently to the Supabase Postgres instance via the Authorization Bearer header.

Inside Postgres, the auth.jwt() function parses this token. By default, it only contains the user's ID (sub), email, and role. For a multi-tenant SaaS, this is insufficient. You need to know which tenant_id the user is currently acting on behalf of, and what their specific role is within that tenant.

Deep Dive 1: Injecting Custom Claims into the JWT

A common mistake is trying to override the internal auth.jwt() function or using heavy Auth Edge Functions for every request. The most robust, performant, and officially supported way to add custom claims (like tenant_id) to a Supabase JWT is by syncing data to the raw_user_meta_data column in the auth.users table. Supabase Auth automatically includes this metadata in the generated JWT.

Here is a production-ready pattern using a database trigger to keep the JWT in sync when a user's tenant membership changes.

Code Example 1: Syncing Tenant Context to JWT via Trigger

-- 1. Create a function to sync tenant_id and role to user metadata
CREATE OR REPLACE FUNCTION public.sync_user_tenant_metadata()
RETURNS TRIGGER AS $$
BEGIN
  -- Update the auth.users table with the new tenant context
  UPDATE auth.users
  SET raw_user_meta_data = jsonb_build_object(
    'tenant_id', NEW.tenant_id,
    'role', NEW.role,
    'email', (SELECT email FROM auth.users WHERE id = NEW.user_id)
  )
  WHERE id = NEW.user_id;

  RETURN NEW;
END;
$$ LANGUAGE plpgsql SECURITY DEFINER;

-- 2. Attach the trigger to your tenant membership table
-- Assuming you have a table: public.tenant_members (user_id, tenant_id, role, is_active)
CREATE TRIGGER on_tenant_member_change
AFTER INSERT OR UPDATE ON public.tenant_members
FOR EACH ROW
WHEN (NEW.is_active = true)
EXECUTE FUNCTION public.sync_user_tenant_metadata();

Why this works: When a user switches workspaces (tenants) in your frontend, you update their active tenant_id in tenant_members. The trigger fires, updating raw_user_meta_data. The frontend then calls supabase.auth.refreshSession(), fetching a fresh JWT that now contains the new tenant_id.

Deep Dive 2: Writing Bulletproof RLS Policies

Now that our JWT contains the tenant_id, we can write RLS policies. A critical best practice is to avoid scattering auth.jwt() ->> 'tenant_id' across dozens of policies. Instead, create a helper function. This centralizes your logic, makes policies readable, and allows you to add caching or complex fallback logic later.

Code Example 2: Centralized RLS Helper and Policies

-- 1. Create a STABLE helper function to extract the tenant ID
-- Marking it STABLE tells the Postgres query planner it can be optimized
CREATE OR REPLACE FUNCTION public.get_current_tenant_id()
RETURNS UUID AS $$
  SELECT NULLIF(auth.jwt() ->> 'tenant_id', '')::UUID;
$$ LANGUAGE sql STABLE;

-- 2. Enable RLS on your tenant-scoped tables
ALTER TABLE public.documents ENABLE ROW LEVEL SECURITY;
ALTER TABLE public.projects ENABLE ROW LEVEL SECURITY;

-- 3. Create comprehensive policies
-- USING controls SELECT, UPDATE, DELETE
-- WITH CHECK controls INSERT, UPDATE
CREATE POLICY tenant_isolation_documents
ON public.documents
FOR ALL
USING (tenant_id = public.get_current_tenant_id())
WITH CHECK (tenant_id = public.get_current_tenant_id());

CREATE POLICY tenant_isolation_projects
ON public.projects
FOR ALL
USING (tenant_id = public.get_current_tenant_id())
WITH CHECK (tenant_id = public.get_current_tenant_id());

The USING vs WITH CHECK Trap: Notice that we defined both. If you only define USING, a user can UPDATE a row to change its tenant_id to a different tenant, effectively stealing data. WITH CHECK ensures that the result of an INSERT or UPDATE still complies with the policy.

Deep Dive 3: Testing RLS Strategies

Testing RLS via your REST API or GraphQL endpoint is slow and conflates application logic with database security. You must test RLS directly at the database layer. Postgres allows you to simulate authenticated sessions using set_config.

Code Example 3: Direct Database RLS Testing

-- A robust testing block for your CI/CD pipeline or local dev
DO $$
DECLARE
  mock_user_id UUID := '00000000-0000-0000-0000-000000000001';
  mock_tenant_id UUID := '11111111-1111-1111-1111-111111111111';
  hostile_tenant_id UUID := '22222222-2222-2222-2222-222222222222';
  doc_count INT;
BEGIN
  -- 1. Simulate the JWT claims for our mock user
  PERFORM set_config('request.jwt.claim.sub', mock_user_id::TEXT, TRUE);
  PERFORM set_config('request.jwt.claim.tenant_id', mock_tenant_id::TEXT, TRUE);

  -- 2. Test SELECT isolation
  SELECT COUNT(*) INTO doc_count FROM public.documents;
  -- In a real test framework (like pgTAP), you would assert this count
  -- matches exactly the documents belonging to mock_tenant_id.
  RAISE NOTICE 'User can see % documents for their tenant.', doc_count;

  -- 3. Test INSERT isolation (The Cross-Tenant Attack)
  BEGIN
    INSERT INTO public.documents (tenant_id, title)
    VALUES (hostile_tenant_id, 'Data Exfiltration Attempt');

    -- If we reach here, RLS failed!
    RAISE EXCEPTION 'CRITICAL: RLS failed to block cross-tenant insert!';
  EXCEPTION
    WHEN OTHERS THEN
      RAISE NOTICE 'SUCCESS: Blocked cross-tenant insert.';
  END;

  -- 4. Test UPDATE isolation
  BEGIN
    UPDATE public.documents
    SET tenant_id = hostile_tenant_id
    WHERE tenant_id = mock_tenant_id;

    RAISE EXCEPTION 'CRITICAL: RLS failed to block cross-tenant update!';
  EXCEPTION
    WHEN OTHERS THEN
      RAISE NOTICE 'SUCCESS: Blocked cross-tenant update.';
  END;

  -- 5. Clean up session context
  PERFORM set_config('request.jwt.claim.sub', '', TRUE);
  PERFORM set_config('request.jwt.claim.tenant_id', '', TRUE);
END $$;

Performance Considerations

RLS policies can silently destroy your database performance if not written carefully.

Index Matching: Postgres can only use indexes if the RLS policy expression matches the index definition. If your policy uses tenant_id = get_current_tenant_id(), you must have a standard B-Tree index on tenant_id.
JWT Size Limits: JWTs have a hard limit of 4KB. Never store arrays of granular permissions in the JWT. Store the tenant_id and role, and resolve granular permissions via a fast, indexed database lookup or a lightweight Redis cache.
Function Volatility: Always mark your RLS helper functions as STABLE (as shown in Example 2). If you leave them as VOLATILE (the default), Postgres will execute the function for every single row evaluated, bypassing query planner optimizations.

Common Pitfalls to Avoid

Forgetting to Enable RLS: It sounds obvious, but ALTER TABLE ... ENABLE ROW LEVEL SECURITY is easily forgotten in migrations. A table with policies but without RLS enabled is completely open.
Caching JWTs Too Long: If you set your JWT expiry to 24 hours, a user removed from a tenant will still have database access for 24 hours. Keep JWT lifespans short (e.g., 1 hour) and use refresh tokens.
Using SECURITY INVOKER on Helpers: If your get_current_tenant_id() function is SECURITY INVOKER, it runs with the permissions of the caller. If the caller doesn't have permission to read the auth.jwt() context properly in some edge cases, it fails. Use SECURITY DEFINER for helper functions that read auth contexts, but be extremely careful to validate inputs. (Note: For simple SQL functions reading auth.jwt(), LANGUAGE sql is usually sufficient and safe).

Key Takeaways

Treat your database as the ultimate source of truth for security.
Use database triggers on membership tables to sync tenant_id into raw_user_meta_data for clean JWT custom claims.
Abstract JWT parsing into STABLE helper functions to keep policies clean and performant.
Always define both USING and WITH CHECK in your RLS policies to prevent privilege escalation via updates.
Test your RLS policies directly in Postgres using set_config to simulate JWTs, rather than relying solely on API tests.

When I was architecting the multi-tenant isolation for PubliFlow (a Next.js 15 SaaS Starter Kit I built, available at publiflow.vip), I initially tried stuffing all user permissions and workspace contexts directly into the JWT. It quickly led to token bloat and complex refresh logic. By shifting to the database trigger pattern for JWT claims and centralizing the RLS logic into STABLE helper functions, I reduced the auth overhead by over 60% and made the security model infinitely easier to reason about. Building SaaS is hard enough; let Postgres do the heavy lifting for your security.

Next.js 15 Server Actions Deep Dive: Patterns for Production SaaS

PubliFlow — Thu, 27 Aug 2026 01:23:45 +0000

Next.js 15 Server Actions Deep Dive: Patterns for Production SaaS

If you are building a SaaS product today, the way you handle data mutations has fundamentally changed. For years, we relied on a strict separation between frontend and backend: React components fetched data via fetch calls to REST or GraphQL endpoints, and mutations were handled by sending POST or PUT requests to API routes.

Next.js Server Actions shatter this paradigm. They allow you to invoke asynchronous server-side functions directly from your React components, blurring the line between client and server. But as any mid-to-senior developer knows, "magic" abstractions often hide complex mechanics. If you don't understand what happens under the hood, you will inevitably hit serialization errors, performance bottlenecks, and security vulnerabilities.

In this deep dive, we will strip away the magic. We will explore the underlying mechanics of Next.js 15 Server Actions and walk through three production-grade patterns: advanced form handling, optimistic UI updates, and secure context passing.

Under the Hood: The Mental Model

Before writing code, you must understand the mental model. A Server Action is not an RPC call in the traditional sense. When you invoke a Server Action from a Client Component, Next.js intercepts the call and translates it into an HTTP POST request to the same URL.

The payload of this request is a serialized representation of the arguments you passed. On the server, Next.js deserializes this payload, executes the function, and returns the result. This result is then serialized and sent back to the client to update the React state.

This architecture introduces the Serialization Boundary. You cannot pass class instances, Date objects, Map, Set, or functions across this boundary. If you try to pass a Date object to a Server Action, it will arrive on the server as a string, or throw an error. You must strictly pass JSON-serializable primitives and plain objects.

Furthermore, because Server Actions are just POST requests under the hood, they inherently support Progressive Enhancement. If a user has JavaScript disabled, or if the JS bundle hasn't loaded yet, a form submission using a Server Action will still work as a standard HTML form submission.

Pattern 1: Advanced Form Handling with `useActionState`

In Next.js 15 (powered by React 19), the useActionState hook is the standard for handling form submissions. It replaces the older useFormState and provides a seamless way to manage pending states, validation errors, and success messages without writing a single useState for form tracking.

Let's look at a robust implementation for creating a new project, complete with Zod validation and progressive enhancement.

The Server Action

// app/actions/createProject.ts
'use server';

import { z } from 'zod';
import { revalidatePath } from 'next/cache';
import { db } from '@/lib/db';
import { auth } from '@/lib/auth';

const CreateProjectSchema = z.object({
  name: z.string().min(3, 'Project name must be at least 3 characters').max(50),
  description: z.string().max(200).optional(),
});

export type CreateProjectState = {
  errors?: {
    name?: string[];
    description?: string[];
  };
  message?: string;
  success?: boolean;
};

export async function createProject(
  prevState: CreateProjectState,
  formData: FormData
): Promise<CreateProjectState> {
  const session = await auth();
  if (!session?.user?.id) {
    return { message: 'Unauthorized', success: false };
  }

  const validatedFields = CreateProjectSchema.safeParse({
    name: formData.get('name'),
    description: formData.get('description'),
  });

  if (!validatedFields.success) {
    return {
      errors: validatedFields.error.flatten().fieldErrors,
      message: 'Validation failed',
      success: false,
    };
  }

  try {
    await db.project.create({
      data: {
        name: validatedFields.data.name,
        description: validatedFields.data.description,
        ownerId: session.user.id,
      },
    });

    revalidatePath('/dashboard/projects');
    return { message: 'Project created successfully!', success: true };
  } catch (error) {
    return { message: 'An unexpected error occurred', success: false };
  }
}

The Client Component

// app/dashboard/projects/CreateProjectForm.tsx
'use client';

import { useActionState } from 'react';
import { useFormStatus } from 'react-dom';
import { createProject, CreateProjectState } from '@/app/actions/createProject';

function SubmitButton() {
  const { pending } = useFormStatus();
  return (
    <button type="submit" disabled={pending} className="btn-primary">
      {pending ? 'Creating...' : 'Create Project'}
    </button>
  );
}

export default function CreateProjectForm() {
  const initialState: CreateProjectState = { errors: {}, message: '' };
  const [state, formAction] = useActionState(createProject, initialState);

  return (
    <form action={formAction} className="space-y-4">
      <div>
        <label htmlFor="name">Project Name</label>
        <input id="name" name="name" type="text" defaultValue="" />
        {state.errors?.name && (
          <p className="text-red-500 text-sm">{state.errors.name[0]}</p>
        )}
      </div>

      <div>
        <label htmlFor="description">Description</label>
        <textarea id="description" name="description" defaultValue="" />
        {state.errors?.description && (
          <p className="text-red-500 text-sm">{state.errors.description[0]}</p>
        )}
      </div>

      {state.message && !state.success && (
        <p className="text-red-600 font-medium">{state.message}</p>
      )}
      {state.success && (
        <p className="text-green-600 font-medium">{state.message}</p>
      )}

      <SubmitButton />
    </form>
  );
}

Notice how we don't manage isSubmitting or error states manually. useFormStatus handles the pending state, and useActionState manages the return payload. Because we use standard <form> and <input> elements, this form works perfectly even if JavaScript fails to load.

Pattern 2: Optimistic Updates for Instant UI

SaaS users expect instant feedback. When they toggle a setting or check off a task, they don't want to wait 300ms for the server to respond before the UI updates. React 19's useOptimistic hook, combined with Server Actions, makes implementing optimistic UI incredibly straightforward.

Here is how we handle toggling a task's completion status.

The Server Action

// app/actions/toggleTask.ts
'use server';

import { revalidateTag } from 'next/cache';
import { db } from '@/lib/db';

export async function toggleTaskCompletion(taskId: string, currentStatus: boolean) {
  // In a real app, verify the user has permission to modify this task
  await db.task.update({
    where: { id: taskId },
    data: { isCompleted: !currentStatus },
  });

  revalidateTag('tasks-list');
  return { success: true };
}

The Client Component

// app/components/TaskList.tsx
'use client';

import { useOptimistic, useTransition } from 'react';
import { toggleTaskCompletion } from '@/app/actions/toggleTask';

type Task = { id: string; title: string; isCompleted: boolean };

export default function TaskList({ initialTasks }: { initialTasks: Task[] }) {
  const [isPending, startTransition] = useTransition();

  const [optimisticTasks, setOptimisticTask] = useOptimistic(
    initialTasks,
    (state, { taskId, newStatus }: { taskId: string; newStatus: boolean }) => {
      return state.map((task) =>
        task.id === taskId ? { ...task, isCompleted: newStatus } : task
      );
    }
  );

  const handleToggle = (taskId: string, currentStatus: boolean) => {
    const newStatus = !currentStatus;

    // 1. Update UI optimistically
    setOptimisticTask({ taskId, newStatus });

    // 2. Trigger the server action
    startTransition(async () => {
      try {
        await toggleTaskCompletion(taskId, currentStatus);
      } catch (error) {
        // Optional: Implement rollback logic here if the server action fails
        console.error('Failed to toggle task', error);
      }
    });
  };

  return (
    <ul className="space-y-2">
      {optimisticTasks.map((task) => (
        <li key={task.id} className="flex items-center gap-2">
          <input
            type="checkbox"
            checked={task.isCompleted}
            onChange={() => handleToggle(task.id, task.isCompleted)}
            disabled={isPending}
          />
          <span className={task.isCompleted ? 'line-through text-gray-500' : ''}>
            {task.title}
          </span>
        </li>
      ))}
    </ul>
  );
}

The useOptimistic hook takes the current state and a reducer function. When setOptimisticTask is called, it immediately updates the UI. The actual server request happens inside startTransition. If the server action succeeds, the revalidateTag triggers a re-render with the fresh server data, seamlessly replacing the optimistic state. If it fails, you can catch the error and implement a rollback mechanism.

Pattern 3: Secure Context Passing and Preventing IDOR

A common pitfall when moving to Server Actions is exposing sensitive IDs to the client. If your Server Action accepts an id from the client, a malicious user can intercept the request and change the id to modify someone else's data (Insecure Direct Object Reference, or IDOR).

Because Server Actions are just functions, you can use closures to securely capture server-side context, ensuring the client never has access to sensitive identifiers.

// app/actions/deleteDocument.ts
'use server';

import { auth } from '@/lib/auth';
import { db } from '@/lib/db';
import { revalidatePath } from 'next/cache';

// This action is created dynamically by a Server Component
export async function createDeleteAction(documentId: string, ownerId: string) {
  'use server';

  return async function deleteDocument() {
    const session = await auth();

    // 1. Verify the user is authenticated
    if (!session?.user?.id) {
      throw new Error('Unauthorized');
    }

    // 2. Verify the user owns the document (Preventing IDOR)
    // The documentId and ownerId are captured in the closure, 
    // so the client cannot tamper with them.
    const document = await db.document.findUnique({
      where: { id: documentId, ownerId: ownerId },
    });

    if (!document) {
      throw new Error('Document not found or access denied');
    }

    await db.document.delete({ where: { id: documentId } });
    revalidatePath('/dashboard/documents');
  };
}

In your Server Component, you generate the action and pass it to the client:

// app/dashboard/documents/DocumentCard.tsx
import { createDeleteAction } from '@/app/actions/deleteDocument';
import { DeleteButton } from '@/app/components/DeleteButton';

export default async function DocumentCard({ doc }: { doc: { id: string, title: string, ownerId: string } }) {
  // The sensitive IDs are bound to the action on the server.
  // The client only receives a reference to the function, not the IDs.
  const boundDeleteAction = await createDeleteAction(doc.id, doc.ownerId);

  return (
    <div className="card">
      <h3>{doc.title}</h3>
      <DeleteButton action={boundDeleteAction} />
    </div>
  );
}

This pattern ensures that the documentId and ownerId never traverse the serialization boundary to the client. The client only holds a reference to the bound function. When invoked, it executes entirely on the server with the securely captured context.

Common Pitfalls and Performance Considerations

While Server Actions are powerful, they introduce new failure modes if not handled correctly.

Over-serializing Return Payloads: Do not return entire database records from a Server Action. If you return a User object with 50 fields, all 50 fields are serialized, sent over the network, and deserialized. Return only what the UI needs (e.g., { success: true, newStatus: 'active' }).
Blocking the Main Thread: Server Actions run on the server, but if they perform heavy synchronous operations (like image processing or large data transformations), they can block the Node.js event loop. Offload heavy tasks to background queues (like BullMQ or Inngest) and return immediately.
Ignoring Cache Invalidation: Forgetting to call revalidatePath or revalidateTag is the #1 reason users report "my data didn't update" bugs. Always explicitly invalidate the cache paths affected by your mutation.
Misunderstanding the Serialization Boundary: Attempting to pass complex objects will result in runtime errors. Stick to strings, numbers, booleans, arrays, and plain objects. If you need to pass a date, pass it as an ISO string and parse it on the server.

Key Takeaways

Embrace the Mental Model: Treat Server Actions as POST requests with a serialization boundary, not magic RPC calls.
Leverage React 19 Hooks: Use useActionState for robust form handling and useOptimistic for instant UI feedback.
Secure by Default: Use closures to capture sensitive context on the server, preventing IDOR vulnerabilities.
Optimize Payloads: Keep return values small and explicitly manage cache invalidation.

Mastering these patterns will drastically reduce your boilerplate, improve your application's perceived performance, and result in a much cleaner codebase.

If you're looking to see these patterns applied in a cohesive, production-ready environment, check out PubliFlow (publiflow.vip). It's a Next.js 15 SaaS starter kit I've been building. When architecting the team management and billing modules, leveraging these exact Server Action and optimistic update patterns allowed us to eliminate almost all boilerplate API routes while keeping the UI incredibly snappy. It serves as a great reference if you're looking to bootstrap your next SaaS product with modern, production-grade architecture.

Building a Production-Ready SaaS Starter Kit from Scratch: Architecture & Implementation

PubliFlow — Sat, 15 Aug 2026 01:24:10 +0000

Building a Production-Ready SaaS Starter Kit from Scratch: Architecture & Implementation

Every SaaS journey begins with the "blank canvas" problem. You have a brilliant product idea, but before you can write a single line of business logic, you need to wire up authentication, set up a database, integrate Stripe, configure transactional emails, and establish a CI/CD pipeline. By the time you reach your first paying customer, you’ve spent three weeks just building the scaffolding.

As mid-to-senior developers, we know that a SaaS starter kit isn't just about saving time; it's about establishing a robust architectural foundation. A poorly designed starter kit will haunt you with scaling issues, security vulnerabilities, and developer friction down the line.

In this deep dive, we will architect a production-ready SaaS starter from scratch. We’ll bypass the superficial tutorials and focus on the critical architecture decisions that separate hobby projects from scalable, enterprise-grade SaaS products.

High-Level Architecture

Before writing code, we must define our boundaries. A modern SaaS architecture should leverage the edge for performance and keep the database strictly isolated.

[Client] --> [Edge Network / CDN] --> [Next.js Edge Middleware (Auth/Routing)]
                                              |
                                              v
                                     [Next.js API Routes / Server Actions]
                                              |
                       +----------------------+----------------------+
                       |                      |                      |
               [PostgreSQL DB]       [Stripe Webhooks]       [Resend/Email API]

This architecture relies on Next.js App Router, utilizing Edge Middleware for zero-latency route protection, Server Actions for mutations, and a strict multi-tenant database design.

1. Authentication & Edge Middleware

The most common pitfall in SaaS authentication is checking user permissions inside individual API routes or components. This leads to duplicated logic and security holes. The solution is to centralize auth at the edge.

We use Auth.js (formerly NextAuth) with a JWT strategy. Why JWT? Because it allows the Edge Middleware to verify sessions without hitting the database on every request, keeping latency under 10ms.

The Pitfall: Over-fetching in Middleware

A common mistake is trying to fetch the full user object in the middleware. Middleware runs on the Edge (V8 isolates), which has strict limitations on Node.js APIs and database connections.

The Solution: Lightweight JWT Payloads

Keep the JWT payload minimal. Only include the userId, email, and role. Fetch the full user profile in Server Components or Server Actions where you have full database access.

Here is a production-grade Edge Middleware that handles route protection, role-based access, and tenant routing:

// src/middleware.ts
import { NextResponse, type NextRequest } from 'next/server';
import { getToken } from 'next-auth/jwt';

const PUBLIC_PATHS = ['/', '/login', '/register', '/api/webhooks', '/api/auth'];

export async function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl;

  // 1. Allow public paths and static assets
  if (PUBLIC_PATHS.some(path => pathname.startsWith(path)) || pathname.includes('.')) {
    return NextResponse.next();
  }

  // 2. Verify JWT at the edge (No DB hit)
  const token = await getToken({ req: request, secret: process.env.AUTH_SECRET });

  if (!token) {
    const loginUrl = new URL('/login', request.url);
    loginUrl.searchParams.set('callbackUrl', pathname);
    return NextResponse.redirect(loginUrl);
  }

  // 3. Role-based route protection
  if (pathname.startsWith('/admin') && token.role !== 'ADMIN') {
    return NextResponse.redirect(new URL('/dashboard', request.url));
  }

  // 4. Inject user context into headers for downstream Server Actions/RSC
  const response = NextResponse.next();
  response.headers.set('x-user-id', token.sub!);
  response.headers.set('x-user-role', token.role || 'USER');

  return response;
}

export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
};

Performance Consideration: By handling auth at the edge, we prevent unauthorized requests from ever reaching your origin servers, saving compute costs and improving security.

2. Multi-Tenant Database & Data Isolation

Multi-tenancy is where many SaaS products fail. Whether you choose a shared database with row-level security (RLS) or a database-per-tenant, the biggest risk is data leakage.

If you are using Prisma, relying on developers to manually add where: { tenantId: ctx.tenantId } to every single query is a recipe for disaster. One forgotten clause, and Tenant A sees Tenant B's data.

The Solution: Prisma Client Extensions

Instead of manual scoping, we can use Prisma Client Extensions to automatically inject the tenantId into all read and write operations. This creates a bulletproof abstraction layer.

// src/lib/db/tenant-client.ts
import { PrismaClient } from '@prisma/client';

// We extend the base client to enforce tenant isolation
export function createTenantClient(tenantId: string) {
  const prisma = new PrismaClient().$extends({
    query: {
      $allModels: {
        async findMany({ model, args, query }) {
          // Automatically inject tenantId into all findMany queries
          args.where = { ...args.where, tenantId };
          return query({ model, args });
        },
        async create({ model, args, query }) {
          // Automatically inject tenantId into all create mutations
          args.data = { ...args.data, tenantId };
          return query({ model, args });
        },
        async update({ model, args, query }) {
          args.where = { ...args.where, tenantId };
          return query({ model, args });
        },
        async delete({ model, args, query }) {
          args.where = { ...args.where, tenantId };
          return query({ model, args });
        },
        // Note: In a real app, you'd also cover findFirst, findUnique, updateMany, deleteMany, etc.
      },
    },
  });

  return prisma;
}

In your Server Actions or API routes, you simply initialize this client:

const db = createTenantClient(session.user.tenantId);
const projects = await db.project.findMany(); // tenantId is automatically applied!

Pitfall Avoided: This completely eliminates the risk of accidental cross-tenant data leakage due to developer error. The database layer itself enforces the business logic.

3. Billing, Webhooks, and Idempotency

Integrating Stripe is easy; handling Stripe webhooks reliably is hard. The most common failure mode is processing the same webhook twice (e.g., due to Stripe retrying after a timeout), leading to duplicated subscriptions or double-charged credits.

The Solution: Idempotency Keys and Signature Verification

Every webhook event from Stripe has a unique ID. We must store this ID and check it before processing the event. Furthermore, we must verify the webhook signature to ensure the payload wasn't tampered with.

Here is a robust Next.js Route Handler for Stripe webhooks:

// src/app/api/webhooks/stripe/route.ts
import { headers } from 'next/headers';
import Stripe from 'stripe';
import { createAdminClient } from '@/lib/db/admin-client';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET!;
const db = createAdminClient(); // Admin client bypasses tenant scoping for webhooks

export async function POST(req: Request) {
  const body = await req.text();
  const headersList = headers();
  const signature = headersList.get('stripe-signature');

  let event: Stripe.Event;

  try {
    // 1. Verify signature to prevent spoofing
    event = stripe.webhooks.constructEvent(body, signature!, webhookSecret);
  } catch (err: any) {
    console.error(`Webhook signature verification failed: ${err.message}`);
    return new Response(`Webhook Error: ${err.message}`, { status: 400 });
  }

  // 2. Idempotency check: Have we already processed this exact event?
  const existingEvent = await db.processedWebhook.findUnique({
    where: { stripeEventId: event.id },
  });

  if (existingEvent) {
    // Already processed, return 200 to tell Stripe to stop retrying
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  // 3. Process the event based on type
  try {
    switch (event.type) {
      case 'checkout.session.completed': {
        const session = event.data.object as Stripe.Checkout.Session;
        // Fulfill the order, create subscription, etc.
        await fulfillCheckout(session);
        break;
      }
      case 'customer.subscription.updated': {
        const subscription = event.data.object as Stripe.Subscription;
        await updateSubscriptionStatus(subscription);
        break;
      }
      // Handle other events...
    }

    // 4. Record the event as processed to ensure idempotency
    await db.processedWebhook.create({
      data: { stripeEventId: event.id, type: event.type },
    });

    return new Response(JSON.stringify({ received: true }), { status: 200 });
  } catch (error) {
    console.error(`Webhook handler failed for event ${event.id}:`, error);
    // Return 500 so Stripe will retry the webhook
    return new Response(`Webhook handler failed`, { status: 500 });
  }
}

Performance Consideration: Webhook handlers should be fast. If your fulfillment logic takes too long (e.g., sending emails, generating reports), offload it to a background job queue (like Inngest, Trigger.dev, or BullMQ) immediately after recording the webhook ID.

4. Email, Deployment, and Developer Experience

Transactional Email

For emails, we use React Email combined with Resend. The key architectural decision here is never sending emails synchronously in the request lifecycle. Always queue them. Using a tool like Trigger.dev or a simple database-backed queue ensures that a slow email API doesn't block your user's UI.

Deployment Strategy

Deploy to Vercel or Cloudflare Pages. Utilize the Edge Runtime for API routes where possible to take advantage of global distribution. However, keep database-heavy routes in the standard Node.js runtime to avoid cold starts and connection pool exhaustion.

Developer Experience (DX)

A starter kit is only as good as its DX.

Monorepo: Use pnpm workspaces and Turborepo. Keep your web app, shared UI components, and database schema in one repository.
Strict Typing: Enable strict: true in tsconfig.json. Use Zod for runtime validation of API inputs.
Linting & Formatting: Biome or ESLint + Prettier configured to run on pre-commit via Husky.

Key Takeaways

Shift Security Left: Handle auth and tenant isolation at the lowest possible layer (Edge Middleware and DB extensions) rather than in UI components.
Embrace Idempotency: Assume webhooks will be delivered multiple times. Design your billing and state-mutation logic to be safely re-runnable.
Optimize for the Edge: Use JWTs for edge auth, keep payloads small, and separate your edge-compatible routes from your heavy database routes.
Abstract the Boring Stuff: A good starter kit removes the cognitive load of boilerplate so you can focus on your unique value proposition.

Building a SaaS is a marathon, not a sprint. The architecture you choose on day one will dictate your velocity on day one hundred. When I was architecting PubliFlow (publiflow.vip), a Next.js 15 SaaS starter kit I recently released, I applied this exact tenant-scoped database pattern and edge middleware setup. Finding the right balance between edge performance and database consistency was the biggest hurdle, but abstracting it into a reusable starter made all the difference.

Take these patterns, adapt them to your stack, and stop reinventing the wheel. Your future self, staring at a scaling production app, will thank you.

Building a Multi-Platform Content Publishing System with Next.js 15

PubliFlow — Mon, 10 Aug 2026 03:20:38 +0000

Building a Multi-Platform Content Publishing System with Next.js 15

If you've ever tried to publish the same article across Dev.to, Medium, and Hashnode, you know it's not as simple as copy-pasting. Each platform has its own API, its own Markdown flavor, its own image handling, and its own SEO metadata requirements. Automating this pipeline is a genuinely interesting engineering problem.

In this post, I'll walk through how to build a multi-platform content publishing system using Next.js 15, covering the key technical challenges and how to solve them. I'll use patterns from PubliFlow — a template I built for content-first SaaS products — as a practical reference.

Let's get into it.

The Architecture Overview

Before writing any code, here's the high-level architecture:

┌─────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  Content     │────▶│  Transformation  │────▶│  Platform       │
│  Editor      │     │  Pipeline        │     │  Adapters       │
│  (Markdown)  │     │  (Normalize +    │     │  (Dev.to,       │
│              │     │   Transform)     │     │   Medium, etc.) │
└─────────────┘     └──────────────────┘     └─────────────────┘
                            │
                     ┌──────┴──────┐
                     │  Image CDN   │
                     │  Upload &    │
                     │  Rewrite     │
                     └─────────────┘

The flow is:

Author writes content in standard Markdown through the editor
Content passes through a transformation pipeline that normalizes it and generates platform-specific variants
Images are uploaded to a CDN and references are rewritten
Platform adapters handle the final formatting and API calls for each destination

Step 1: Setting Up the Content Model

The first decision is how to model content in a way that's platform-agnostic but still captures platform-specific needs.

// lib/content/schema.ts

export interface ContentArticle {
  id: string;
  title: string;
  slug: string;
  body: string;                // Raw Markdown
  excerpt?: string;
  coverImage?: string;
  tags: string[];
  status: 'draft' | 'published' | 'scheduled';
  seo: SEOConfig;
  platformConfig: Map<Platform, PlatformOverrides>;
  createdAt: Date;
  updatedAt: Date;
}

export interface SEOConfig {
  metaDescription: string;
  canonicalUrl?: string;
  ogImage?: string;
  ogTitle?: string;
  structuredData?: Record<string, unknown>;
}

export interface PlatformOverrides {
  title?: string;         // Some platforms benefit from different titles
  tags?: string[];        // Tag taxonomies differ per platform
  publishedAt?: Date;     // Schedule per-platform independently
  canonicalUrl?: string;  // Cross-platform canonical management
}

export type Platform = 'devto' | 'medium' | 'hashnode';

The key insight here is the PlatformOverrides pattern. You don't want to force identical content across all platforms — Dev.to audiences respond to different titles than Medium audiences. But you do want a single source of truth for the body content.

Step 2: The Markdown Transformation Pipeline

This is the heart of the system. Raw Markdown from your editor needs to be transformed in several ways before it's ready for each platform.

2.1 Markdown Normalization

Different editors produce slightly different Markdown. Some use **bold**, others might produce HTML <strong> tags. Some preserve code block language annotations, others don't.

// lib/content/transformer.ts

import { unified } from 'unified';
import remarkParse from 'remark-parse';
import remarkGfm from 'remark-gfm';
import remarkRehype from 'remark-rehype';
import rehypeStringify from 'rehype-stringify';
import rehypeSanitize from 'rehype-sanitize';

export async function normalizeMarkdown(rawMarkdown: string): Promise<string> {
  const result = await unified()
    .use(remarkParse)
    .use(remarkGfm)            // GitHub Flavored Markdown support
    .use(remarkRehype)
    .use(rehypeSanitize)       // Strip potentially dangerous HTML
    .use(rehypeStringify)
    .process(rawMarkdown);

  return String(result);
}

Using the unified/remark/rehype ecosystem gives you a composable transformation pipeline. You can add plugins for syntax highlighting, custom containers, or any platform-specific extensions.

2.2 Image Extraction and CDN Upload

One of the trickiest parts of cross-platform publishing is image handling. Dev.to, Medium, and Hashnode all handle images differently:

Dev.to: You can reference external image URLs
Medium: Prefers images uploaded through their API (with size limits)
Hashnode: Has its own image hosting but also supports external URLs

The safest approach is to upload all images to your own CDN first, then reference the CDN URLs everywhere:

// lib/content/image-pipeline.ts

import { visit } from 'unist-util-visit';

interface ImageResult {
  markdown: string;
  uploadedUrls: Map<string, string>;  // original -> CDN URL
}

export async function processImages(
  markdown: string,
  uploadFn: (buffer: Buffer, filename: string) => Promise<string>
): Promise<ImageResult> {
  const tree = unified().use(remarkParse).parse(markdown);
  const uploadedUrls = new Map<string, string>();

  // Find all image nodes
  const imageNodes: ImageNode[] = [];
  visit(tree, 'image', (node) => {
    imageNodes.push(node);
  });

  // Upload each image to CDN in parallel
  const uploadPromises = imageNodes.map(async (node) => {
    const originalUrl = node.url;

    // Skip if already a CDN URL
    if (originalUrl.startsWith(process.env.CDN_BASE_URL!)) {
      return { original: originalUrl, cdn: originalUrl };
    }

    const buffer = await fetchImageBuffer(originalUrl);
    const filename = generateFilename(originalUrl);
    const cdnUrl = await uploadFn(buffer, filename);

    uploadedUrls.set(originalUrl, cdnUrl);
    return { original: originalUrl, cdn: cdnUrl };
  });

  await Promise.all(uploadPromises);

  // Rewrite image URLs in the Markdown AST
  visit(tree, 'image', (node) => {
    const cdnUrl = uploadedUrls.get(node.url);
    if (cdnUrl) {
      node.url = cdnUrl;
    }
  });

  return {
    markdown: unified().use(remarkStringify).stringify(tree),
    uploadedUrls,
  };
}

2.3 Platform-Specific Transformations

Each platform needs its content formatted slightly differently:

// lib/content/platform-transformers.ts

export interface PlatformContent {
  body: string;
  title: string;
  tags: string[];
  metadata: Record<string, unknown>;
}

// Dev.to expects frontmatter-style metadata and has a tag limit of 4
export function transformForDevTo(article: ContentArticle): PlatformContent {
  const tags = article.tags.slice(0, 4);  // Dev.to limit

  const body = [
    '---',
    `title: "${article.title}"`,
    `published: ${article.status === 'published'}`,
    `cover_image: ${article.coverImage || ''}`,
    `description: "${article.seo.metaDescription}"`,
    `tags: ${tags.join(', ')}`,
    '---',
    '',
    article.body,
  ].join('\n');

  return { body, title: article.title, tags, metadata: { published: true } };
}

// Medium API expects JSON fields, not frontmatter
export function transformForMedium(article: ContentArticle): PlatformContent {
  // Medium requires content in HTML or Markdown
  // Canonical URL is critical for Medium to avoid duplicate content penalties
  return {
    body: article.body,
    title: article.title,
    tags: article.tags.slice(0, 5),  // Medium limit
    metadata: {
      contentFormat: 'markdown',
      canonicalUrl: article.seo.canonicalUrl,
      publishStatus: article.status === 'published' ? 'public' : 'draft',
    },
  };
}

// Hashnode has its own content format
export function transformForHashnode(article: ContentArticle): PlatformContent {
  return {
    body: article.body,
    title: article.title,
    tags: article.tags.map(tag => ({
      name: tag,
      // Hashnode requires tag slugs for existing tags
      slug: tag.toLowerCase().replace(/\s+/g, ''),
    })),
    metadata: {
      coverImage: article.coverImage,
      // Hashnode-specific: enable cover image stickiness
      stickCoverToBottom: false,
      // Delivered to Hashnode's newsletter if enabled
      enableNewsletter: true,
    },
  };
}

Step 3: Platform API Adapters

Each platform adapter encapsulates the API communication logic:

// lib/platforms/adapter.ts

export interface PublishingResult {
  platform: Platform;
  success: boolean;
  articleUrl?: string;
  articleId?: string;
  error?: string;
  publishedAt?: Date;
}

export interface PlatformAdapter {
  name: Platform;
  authenticate(token: string): Promise<boolean>;
  publish(content: PlatformContent): Promise<PublishingResult>;
  update(articleId: string, content: PlatformContent): Promise<PublishingResult>;
  delete(articleId: string): Promise<boolean>;
}

// lib/platforms/devto.ts

export class DevToAdapter implements PlatformAdapter {
  name = 'devto' as const;
  private apiKey: string;
  private baseUrl = 'https://dev.to/api';

  constructor(apiKey: string) {
    this.apiKey = apiKey;
  }

  async authenticate(): Promise<boolean> {
    const response = await fetch(`${this.baseUrl}/users/me`, {
      headers: { 'api-key': this.apiKey },
    });
    return response.ok;
  }

  async publish(content: PlatformContent): Promise<PublishingResult> {
    const response = await fetch(`${this.baseUrl}/articles`, {
      method: 'POST',
      headers: {
        'api-key': this.apiKey,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        article: {
          title: content.title,
          body_markdown: content.body,
          published: content.metadata.published,
          tags: content.tags,
        },
      }),
    });

    if (!response.ok) {
      return {
        platform: this.name,
        success: false,
        error: `Dev.to API error: ${response.status} ${await response.text()}`,
      };
    }

    const data = await response.json();
    return {
      platform: this.name,
      success: true,
      articleUrl: data.url,
      articleId: String(data.id),
      publishedAt: new Date(data.published_at),
    };
  }

  // ... update and delete implementations
}

Step 4: Orchestrating the Publishing Pipeline

Now tie it all together with a pipeline that handles the full flow:

// lib/content/publish-pipeline.ts

export async function executePublishPipeline(
  article: ContentArticle,
  adapters: PlatformAdapter[],
  imageUploadFn: ImageUploadFunction
): Promise<PublishingResult[]> {
  // Step 1: Normalize the base Markdown
  const normalizedBody = await normalizeMarkdown(article.body);
  article.body = normalizedBody;

  // Step 2: Process and upload images
  const { markdown: processedBody, uploadedUrls } = await processImages(
    article.body,
    imageUploadFn
  );
  article.body = processedBody;
  if (article.coverImage && uploadedUrls.has(article.coverImage)) {
    article.coverImage = uploadedUrls.get(article.coverImage);
  }

  // Step 3: Transform for each target platform in parallel
  const transformedContent = adapters.map(adapter => ({
    adapter,
    content: transformForPlatform(article, adapter.name),
  }));

  // Step 4: Publish to all platforms in parallel
  // Using allSettled ensures one failure doesn't block others
  const results = await Promise.allSettled(
    transformedContent.map(({ adapter, content }) =>
      adapter.publish(content)
    )
  );

  // Step 5: Aggregate results
  return results.map((result, index) => {
    if (result.status === 'fulfilled') {
      return result.value;
    }
    return {
      platform: adapters[index].name,
      success: false,
      error: `Pipeline error: ${result.reason?.message || 'Unknown error'}`,
    };
  });
}

Step 5: SEO Considerations for Multi-Platform Publishing

When the same content lives on multiple platforms, SEO can become a nightmare if you're not careful. Here are the critical things to get right:

Canonical URLs

Always set a canonical URL pointing to your own site. This tells search engines where the original content lives and prevents duplicate content penalties.

// Every platform transform should include canonical URL management
function setCanonicalUrl(content: PlatformContent, originalUrl: string): PlatformContent {
  return {
    ...content,
    metadata: {
      ...content.metadata,
      canonicalUrl: originalUrl,
    },
  };
}

Staggered Publishing

Consider publishing to your own site first, then to platforms 24-48 hours later. This gives search engines time to index your original version before the syndicated copies appear.

// lib/content/scheduler.ts

export function scheduleStaggeredPublish(
  article: ContentArticle,
  platforms: Platform[]
): Map<Platform, Date> {
  const schedule = new Map<Platform, Date>();
  const baseTime = new Date();

  // Your own site publishes immediately
  // Dev.to: +24 hours
  // Medium: +48 hours
  // Hashnode: +24 hours (different audience from Dev.to)
  const delays: Partial<Record<Platform, number>> = {
    devto: 24 * 60 * 60 * 1000,
    hashnode: 24 * 60 * 60 * 1000,
    medium: 48 * 60 * 60 * 1000,
  };

  platforms.forEach(platform => {
    const delay = delays[platform] || 0;
    schedule.set(platform, new Date(baseTime.getTime() + delay));
  });

  return schedule;
}

Open Graph and Social Metadata

Each platform generates its own OG tags, but you should ensure your content includes rich metadata that platforms can use for social sharing previews:

High-quality cover image (at least 1200x630px for optimal social previews)
Compelling meta description (150-160 characters)
Article tags that match the platform's taxonomy

Handling Rate Limits and Errors

Platform APIs have different rate limits:

Dev.to: 30 requests per 30 seconds
Medium: Not publicly documented, but aggressive
Hashnode: Generous but undocumented

Build retry logic with exponential backoff:

async function publishWithRetry(
  adapter: PlatformAdapter,
  content: PlatformContent,
  options: { maxRetries: number; baseDelay: number } = { maxRetries: 3, baseDelay: 1000 }
): Promise<PublishingResult> {
  for (let attempt = 0; attempt <= options.maxRetries; attempt++) {
    const result = await adapter.publish(content);

    if (result.success) return result;

    // Don't retry on authentication errors
    if (result.error?.includes('401') || result.error?.includes('403')) {
      return result;
    }

    // Exponential backoff
    if (attempt < options.maxRetries) {
      const delay = options.baseDelay * Math.pow(2, attempt);
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }

  return {
    platform: adapter.name,
    success: false,
    error: `Max retries (${options.maxRetries}) exceeded`,
  };
}

Putting It All Together in a Next.js 15 Route

Here's how the entire pipeline looks as a Next.js 15 server action:

// app/dashboard/articles/publish/action.ts

'use server';

export async function publishArticle(articleId: string) {
  const article = await getArticle(articleId);
  const user = await getCurrentUser();

  // Initialize adapters for user's connected platforms
  const adapters = getActiveAdapters(user.platformTokens);

  // Execute the publishing pipeline
  const results = await executePublishPipeline(
    article,
    adapters,
    uploadToCDN  // Your CDN upload function
  );

  // Update article status based on results
  await updateArticlePublishStatus(articleId, results);

  // Revalidate the dashboard cache
  revalidatePath('/dashboard/articles');

  return results;
}

What I Learned Building This

A few non-obvious lessons from building a real multi-platform publishing system:

Content transformation is never "done." Each platform updates its API and content requirements regularly. Build your adapters to be easily modifiable.
Image handling is 50% of the complexity. If you underestimate image pipeline requirements, the whole system will suffer. Upload to your own CDN first, always.
Error handling per platform is critical. One platform being down shouldn't prevent publishing to others. Promise.allSettled is your friend.
Test with real API responses. Dev.to and Medium API documentation is decent but incomplete. Build your adapters against the actual API, not just the docs.
SEO requires platform-specific thinking. It's not just about canonical URLs — it's about understanding how each platform handles content discovery.

Want to See a Full Implementation?

If you want to see these patterns implemented in a complete, production-ready codebase, check out PubliFlow — a Next.js 15 SaaS template built for content-first products. It includes the multi-platform publishing pipeline described here, plus authentication, Stripe payments, AI writing assistance, and an affiliate system.

PubliFlow: https://publiflow.vip/
Starter: $149 · Pro: $399 · Enterprise: $999 (one-time payment)

Whether you use PubliFlow or build your own, I hope this gives you a solid foundation for thinking about multi-platform content publishing architecture. The patterns here are battle-tested and designed to scale.

Got questions about the implementation? Drop a comment — happy to dive deeper into any part of the pipeline.

My Other Projects

VEIGO — An all-in-one platform for overseas life. Find rental housing, job listings, gig work, and bidding services. Simplify your life abroad with a single platform.

VEIGO: https://shopveigo.com/ — Your one-stop overseas life platform
PubliFlow: https://publiflow.vip/ — Multi-platform content publishing SaaS template

Building a Bulletproof Multi-Platform Content Publishing Architecture

PubliFlow — Sat, 08 Aug 2026 01:20:18 +0000

Building a Bulletproof Multi-Platform Content Publishing Architecture

If you’ve ever written a high-quality technical article, you know the drill. You finish the draft, hit publish on your personal blog, and then the real work begins. You copy the text into Medium, only to find your code blocks lost their syntax highlighting. You paste it into Dev.to, and realize your cover image is broken because they require images to be uploaded to their specific CDN. You try Hashnode, and the GraphQL mutation rejects your payload because of a missing canonical URL tag.

Copy-pasting and manually tweaking content across platforms is a massive waste of time and a breeding ground for inconsistencies. As developers building SaaS products or personal brands, we need a unified engine. We need a "Write Once, Publish Everywhere" (WOPE) architecture.

In this article, we’ll dive deep into designing a robust, multi-platform content publishing system. We will cover content normalization, the adapter pattern for disparate APIs, and resilient job queuing.

The Core Architecture: Normalization, Adaptation, and Execution

A scalable publishing pipeline isn't just a script that loops through an array of API keys. It requires a decoupled architecture that separates the content representation from the platform delivery.

The architecture consists of three main phases:

Normalization Engine: Converts raw Markdown/MDX into a normalized Abstract Syntax Tree (AST), resolving platform-specific quirks (like image hosting or liquid tags).
Adapter Layer: Translates the normalized payload into the specific API formats required by Medium (GraphQL), Dev.to (REST), and Hashnode (GraphQL).
Execution & Scheduling Layer: A message queue (like BullMQ) that handles rate limiting, retries, idempotency, and scheduled publishing.

Let’s break down each layer with production-ready code.

Phase 1: Content Normalization via AST Transformation

The biggest mistake developers make is treating Markdown as a raw string. Markdown parsers have subtle differences. To build a reliable system, we must parse the Markdown into an AST, transform it, and serialize it back. We'll use the unified ecosystem (specifically remark) to handle this.

A common pitfall is image hosting. Medium rejects external image URLs, and Dev.to requires images to be uploaded to their CDN to prevent hotlinking. Instead of handling this in the API adapter, we handle it in the normalization phase.

Here is a robust remark plugin that extracts external image URLs, flags them for a secondary upload queue, and replaces them with platform-specific placeholders.

import { visit } from 'unist-util-visit';
import { Plugin } from 'unified';
import { Root, Image } from 'mdast';

// Define a custom node type for our upload placeholders
interface UploadPlaceholder {
  type: 'uploadPlaceholder';
  originalUrl: string;
  placeholderId: string;
}

export const remarkImageExtractor: Plugin<[], Root> = () => {
  return (tree, file) => {
    const imageQueue: { originalUrl: string; placeholderId: string }[] = [];

    visit(tree, 'image', (node: Image, index, parent) => {
      if (node.url.startsWith('http')) {
        const placeholderId = `img_${Math.random().toString(36).substring(7)}`;

        // Queue the image for async uploading to platform CDNs
        imageQueue.push({ originalUrl: node.url, placeholderId });

        // Replace the image node with a placeholder that the adapter will resolve
        const placeholder: any = {
          type: 'uploadPlaceholder',
          originalUrl: node.url,
          placeholderId,
          alt: node.alt,
          title: node.title
        };

        if (parent && typeof index === 'number') {
          parent.children[index] = placeholder;
        }
      }
    });

    // Attach the queue to the file data for the orchestrator to process
    file.data.imageQueue = imageQueue;
  };
};

By the time the content reaches the adapter, all external images have been swapped with {{upload_image:img_xxx}} placeholders. The orchestrator processes the imageQueue, uploads the images to the target platform's API, and replaces the placeholders with the final CDN URLs.

Phase 2: The Adapter Pattern for Platform APIs

Every platform has a different API paradigm. Dev.to uses REST, Medium uses GraphQL, and Hashnode uses a slightly different GraphQL schema. Hardcoding these into a single service violates the Open/Closed Principle. We need an Adapter pattern.

We define a strict contract for what a "published post" requires, and let each adapter handle the platform-specific translation.

import { z } from 'zod';

// Strict schema for our normalized internal payload
export const PublishPayloadSchema = z.object({
  title: z.string().min(1),
  contentMarkdown: z.string().min(1),
  tags: z.array(z.string()).max(5), // Dev.to limits to 5 tags
  canonicalUrl: z.string().url().optional(),
  publishedAt: z.date().optional(),
  coverImageUrl: z.string().url().optional(),
});

export type PublishPayload = z.infer<typeof PublishPayloadSchema>;

export interface PlatformAdapter {
  readonly name: string;
  publish(payload: PublishPayload): Promise<{ postId: string; url: string }>;
  update(postId: string, payload: Partial<PublishPayload>): Promise<void>;
}

export class DevToAdapter implements PlatformAdapter {
  readonly name = 'dev.to';
  private apiKey: string;

  constructor(apiKey: string) {
    this.apiKey = apiKey;
  }

  async publish(payload: PublishPayload) {
    const response = await fetch('https://dev.to/api/articles', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'api-key': this.apiKey,
      },
      body: JSON.stringify({
        article: {
          title: payload.title,
          body_markdown: payload.contentMarkdown,
          published: true,
          tags: payload.tags,
          canonical_url: payload.canonicalUrl,
          series: null, // Dev.to specific
        },
      }),
    });

    if (!response.ok) {
      const errorText = await response.text();
      throw new Error(`Dev.to API Error: ${response.status} - ${errorText}`);
    }

    const data = await response.json();
    return { postId: data.id.toString(), url: data.url };
  }

  async update(postId: string, payload: Partial<PublishPayload>) {
    // Implementation for PUT /api/articles/{id}
    // ...
    throw new Error('Not implemented');
  }
}

Notice how the DevToAdapter maps our internal PublishPayload to Dev.to's specific article wrapper. If we add Hashnode tomorrow, we just write a HashnodeAdapter that maps the same payload to their GraphQL mutation. The core business logic remains untouched.

Phase 3: Resilient Execution with BullMQ

Publishing to multiple APIs simultaneously is a recipe for rate-limit bans and partial failures. If Dev.to succeeds but Medium fails, you end up with fragmented content. Furthermore, API calls are slow. You shouldn't block the user's HTTP request while waiting for three external APIs.

We must offload this to a background queue. We'll use BullMQ (backed by Redis) to handle job scheduling, retries, and concurrency control.

import { Queue, Worker, Job } from 'bullmq';
import IORedis from 'ioredis';
import { DevToAdapter, PublishPayload } from './adapters';

const connection = new IORedis(process.env.REDIS_URL!);

// 1. Define the Queue
export const publishingQueue = new Queue('multi-platform-publish', { connection });

// 2. Define the Job Data Type
interface PublishJobData {
  payload: PublishPayload;
  platforms: string[]; // e.g., ['dev.to', 'medium']
  idempotencyKey: string; // Crucial for preventing duplicate posts
}

// 3. The Worker
export const publishingWorker = new Worker<PublishJobData>(
  'multi-platform-publish',
  async (job: Job<PublishJobData>) => {
    const { payload, platforms, idempotencyKey } = job.data;

    // Check idempotency key in DB to ensure we haven't already processed this exact draft
    const alreadyPublished = await db.checkIdempotency(idempotencyKey);
    if (alreadyPublished) {
      console.log(`Job ${job.id} already processed. Skipping.`);
      return { status: 'skipped' };
    }

    const adapters = getAdaptersForPlatforms(platforms);
    const results: Record<string, any> = {};

    // Process sequentially or with controlled concurrency to respect rate limits
    for (const adapter of adapters) {
      try {
        console.log(`Publishing to ${adapter.name}...`);
        const result = await adapter.publish(payload);
        results[adapter.name] = result;

        // Add a small delay between API calls to avoid triggering rate limits
        await new Promise(resolve => setTimeout(resolve, 1500));
      } catch (error) {
        console.error(`Failed to publish to ${adapter.name}:`, error);
        // Depending on your business logic, you might throw here to trigger a BullMQ retry,
        // or log and continue to publish to the remaining platforms.
        // For critical platforms, throw an error to trigger exponential backoff.
        if (adapter.name === 'dev.to') {
          throw error;
        }
      }
    }

    // Mark idempotency key as processed
    await db.markIdempotencyProcessed(idempotencyKey);

    return { status: 'success', results };
  },
  {
    connection,
    limiter: {
      max: 10, // Max 10 jobs
      duration: 60000, // per 60 seconds (Global rate limiting)
    },
  }
);

This worker implementation includes three critical features for production systems:

Idempotency Keys: Prevents duplicate posts if a job is retried or manually re-queued.
Global Rate Limiting: The limiter config ensures we don't blast the platforms with concurrent requests.
Inter-job Delays: The setTimeout between adapter calls prevents hitting per-minute rate limits on specific endpoints.

Common Pitfalls and Performance Considerations

When building this architecture, you will inevitably run into a few edge cases. Here is how to avoid them:

The Canonical URL Trap: Always set the canonical_url to your own domain. If you publish to Medium and Dev.to without a canonical URL, those platforms will index the content first, destroying your personal blog's SEO.
Tag Normalization: Dev.to limits tags to 5 and requires them to be lowercase without spaces. Medium uses "topics". You need a normalization function in your payload validation (using Zod, as shown above) to strip spaces and enforce limits before the data reaches the adapters.
Handling API Token Expiry: OAuth tokens for Medium expire. Your adapter layer needs a mechanism to refresh tokens or alert the user via a webhook when a token becomes invalid, rather than just failing silently in the queue.
Performance: Image processing is CPU intensive. If you are resizing or optimizing images before uploading them to platform CDNs, do not do this in the BullMQ worker if it's running on the same Node.js instance as your web server. Offload image processing to a separate service or use edge functions to prevent blocking the event loop.

Key Takeaways

Never treat Markdown as a raw string. Parse it into an AST to handle platform-specific transformations reliably.
Use the Adapter Pattern. Abstract the API differences behind a common interface to keep your core logic clean and extensible.
Embrace Asynchronous Execution. Use a robust queue like BullMQ to handle retries, rate limiting, and idempotency.
Protect your SEO. Always inject canonical URLs and normalize tags before publishing.

Building a resilient multi-platform publishing system transforms content distribution from a manual chore into an automated, scalable asset. When I was architecting the content delivery layer for PubliFlow (publiflow.vip), my Next.js 15 SaaS Starter Kit, I relied heavily on this exact adapter-and-queue pattern. Handling multi-tenant content distribution at scale taught me that the queue layer isn't just a nice-to-have; it's the backbone of a resilient publishing system. If you're building a SaaS that involves content generation or distribution, looking into how Next.js 15 handles server actions and background queues can save you weeks of debugging edge cases.

By implementing these patterns, you can ensure your content reaches your audience, wherever they read, without compromising on quality or your own sanity.

How I Integrated AI Video Generation into a SaaS Platform — Seedance API + Credit System

PubliFlow — Sun, 02 Aug 2026 16:23:03 +0000

AI video generation is no longer a novelty — it's becoming a core feature in SaaS products. But integrating it into a production application comes with real engineering challenges: asynchronous processing, credit-based billing, cost management, and user experience design.

In this article, I'll walk through how I integrated Seedance 2.0 Mini into VEIGO's platform, built a credit system around it, and what I learned about pricing AI-generated content.

The Challenge

I needed to add AI video generation to a SaaS platform with these requirements:

Users should be able to generate videos from text prompts or images
The system needs to handle long-running generation tasks (30s to 5min)
Monetization through a credit/point system rather than per-video pricing
Seamless UX — users shouldn't feel like they're waiting for a batch job

Why Seedance 2.0 Mini

After evaluating Runway, Pika, Kling, and Stable Video Diffusion, I chose Seedance 2.0 Mini for several reasons:

Cost-effectiveness: Competitive pricing for the quality output
API reliability: Consistent uptime and response times
Resolution flexibility: Multiple output options (480p, 720p, 1080p)
Image-to-video capability: Critical for property listings and product showcases
Chinese market alignment: Better support for Chinese text prompts and cultural context

Architecture: The Async Task Pattern

Video generation isn't instant. Even "fast" models take 30+ seconds. Here's the architecture I implemented:

User Request → Task Queue → Seedance API → Polling Service → Result Storage → User Notification

Step 1: Task Creation

When a user submits a generation request, we don't wait for the video. Instead:

// app/api/studio/generate/route.ts
export async function POST(req: Request) {
  const { prompt, imageUrl, resolution, duration } = await req.json();

  // Calculate credit cost based on parameters
  const creditCost = calculateCredits(resolution, duration);

  // Check user balance
  const user = await getUserWithBalance(session.userId);
  if (user.credits < creditCost) {
    return Response.json({ error: "Insufficient credits" }, { status: 402 });
  }

  // Create task record
  const task = await db.videoTask.create({
    data: {
      userId: session.userId,
      status: "PENDING",
      prompt,
      imageUrl,
      resolution,
      duration,
      creditsCharged: creditCost,
    }
  });

  // Submit to Seedance API (non-blocking)
  const seedanceTaskId = await submitToSeedance({
    prompt,
    imageUrl,
    resolution,
    duration
  });

  // Update task with external ID
  await db.videoTask.update({
    where: { id: task.id },
    data: { externalTaskId: seedanceTaskId, status: "PROCESSING" }
  });

  return Response.json({ 
    taskId: task.id, 
    creditsCharged: creditCost,
    estimatedTime: getEstimate(duration)
  });
}

Step 2: Polling Service

A background service polls the Seedance API for task completion:

// lib/services/video-poller.ts
export async function pollTaskCompletion() {
  const pendingTasks = await db.videoTask.findMany({
    where: { status: "PROCESSING" },
    take: 10 // Batch processing
  });

  for (const task of pendingTasks) {
    try {
      const result = await seedance.getTaskStatus(task.externalTaskId);

      if (result.status === "COMPLETED") {
        // Download and store the video
        const videoUrl = await downloadAndStore(result.videoUrl, task.id);

        await db.videoTask.update({
          where: { id: task.id },
          data: { 
            status: "COMPLETED",
            videoUrl,
            completedAt: new Date()
          }
        });

        // Notify user
        await notifyUser(task.userId, {
          type: "VIDEO_READY",
          taskId: task.id
        });
      } else if (result.status === "FAILED") {
        // Refund credits on failure
        await refundCredits(task.userId, task.creditsCharged);
        await db.videoTask.update({
          where: { id: task.id },
          data: { status: "FAILED", failureReason: result.error }
        });
      }
      // If still processing, just wait for next poll cycle
    } catch (error) {
      console.error(`Poll error for task ${task.id}:`, error);
    }
  }
}

Step 3: User-Facing Status

The frontend polls for task status with a progress indicator:

// components/VideoTaskStatus.tsx
export function VideoTaskStatus({ taskId }: { taskId: string }) {
  const [status, setStatus] = useState<TaskStatus>("PROCESSING");
  const [progress, setProgress] = useState(0);

  useEffect(() => {
    const interval = setInterval(async () => {
      const res = await fetch(`/api/studio/task/${taskId}`);
      const data = await res.json();
      setStatus(data.status);
      setProgress(data.progress);

      if (data.status === "COMPLETED" || data.status === "FAILED") {
        clearInterval(interval);
      }
    }, 3000); // Poll every 3 seconds

    return () => clearInterval(interval);
  }, [taskId]);

  return (
    <div className="task-status">
      <ProgressBar value={progress} />
      <StatusBadge status={status} />
      {status === "COMPLETED" && <VideoPlayer url={status.videoUrl} />}
    </div>
  );
}

The Credit System Design

Instead of per-video pricing (which feels unpredictable), I designed a credit bundle system:

Plan	Credits	Price	Per-Credit Cost
Starter	100	$5	$0.050
Professional	400	$15	$0.038
Business	1,000	$30	$0.030
Enterprise	2,500	$50	$0.020

Credit Cost Per Generation

Different parameters consume different credit amounts:

function calculateCredits(resolution: string, duration: number): number {
  const baseCost = {
    "480p": 2,
    "720p": 4,
    "1080p": 8
  };

  const durationMultiplier = duration <= 5 ? 1 : duration <= 10 ? 1.5 : 2;

  return Math.ceil(baseCost[resolution] * durationMultiplier);
}

Why Credits Work Better Than Per-Video Pricing

Predictable revenue: Users buy bundles upfront
Flexible usage: A credit can generate a 480p clip or contribute toward a 1080p video
Reduced decision fatigue: Users don't calculate cost per video
Upsell opportunity: Running low? Here's a bigger bundle at a better rate
Graceful degradation: If API costs change, adjust credit costs without changing user-facing prices

Pricing Strategy Thoughts

After 3 months of operation, here's what I've observed:

The $5 tier is the acquisition engine. Most users start here. It's low-risk enough to try, and 100 credits let them generate ~25 480p videos or ~12 720p videos.

The $30 tier is the sweet spot. Users who find value quickly upgrade here. The per-credit savings (40% vs Starter) feels significant.

Enterprise users negotiate. At $50 for 2,500 credits, businesses generating content at scale often reach out for custom pricing.

Key insight: The pricing isn't really about the credits — it's about removing friction. Users who buy credits generate more content, which makes the platform stickier, which reduces churn.

Cost Management

Seedance API costs aren't trivial. Here's how I keep margins healthy:

Resolution-tiered pricing: Higher resolution costs more credits, matching higher API costs
Batch processing: Group API calls to reduce overhead
Caching: Similar prompts with same seed get cached results
Failure handling: Failed generations refund credits immediately (maintaining trust)
Usage monitoring: Alert when a user's generation pattern suggests abuse

Lessons Learned

1. Set expectations early
Users need to know generation takes time. We show estimated wait times upfront and use optimistic UI updates.

2. Always refund on failure
Nothing destroys trust faster than charging credits for failed generations. We refund immediately and send a notification explaining why it failed.

3. Offer a free tier
We give 10 free credits on signup. This lets users experience the product before committing money. Conversion rate from free to paid is ~15%.

4. Monitor API costs vs. credit revenue
We track the ratio weekly. Target is 60%+ gross margin. If API costs spike, we adjust credit costs (not plan prices — that would break trust).

5. Content moderation is mandatory
AI-generated video can be misused. We run all prompts through a content filter before submission and have a reporting system for generated content.

Try It Out

The AI Video Studio is live and integrated into the VEIGO platform. It's particularly useful for:

Real estate agents creating property walkthrough videos
E-commerce sellers generating product demos
Content creators producing short-form video content
Marketers creating social media ads

🎬 AI Video Studio: shopveigo.com/studio
💳 Credit Plans: shopveigo.com/pricing
🏠 Full Platform: shopveigo.com

Have you integrated AI video generation into your product? What challenges did you face? Share your experience in the comments.

I Built an All-in-One Platform for Expats — Renting, Jobs, Freelancing, and AI Tools in One Place

PubliFlow — Sun, 02 Aug 2026 16:22:01 +0000

As an expat who's lived in multiple countries, I know the struggle: finding an apartment in a foreign city, landing a job that matches your skills, picking up freelance gigs to make ends meet — all while navigating language barriers and unfamiliar platforms. Each task lives in a different app, each with its own login, its own verification process, and zero integration with the others.

After years of dealing with this fragmented experience, I decided to build something different. VEIGO is an all-in-one platform designed specifically for the global Chinese community — expats, students, professionals, and immigrants — bringing renting, jobs, freelancing, and AI tools under one roof.

The Problem: A Fragmented Expat Experience

When you move to a new country, you quickly realize how siloed existing tools are:

Renting: Zillow doesn't work in Spain. Idealista doesn't cover Japan. Each country has its own dominant platform, often only in the local language.
Jobs: LinkedIn is global but generic. For Chinese speakers, BOSS直聘 dominates the domestic market but has no international presence.
Freelancing: Upwork and Fiverr are competitive and commission-heavy. Finding Chinese-speaking clients abroad is nearly impossible.
AI Tools: ChatGPT, Midjourney, Runway — each requires a separate subscription, often with region-locked pricing.

The result? You're juggling 5-10 different platforms, each with its own UX patterns, notification systems, and payment methods. It's exhausting.

The Solution: VEIGO's Unified Architecture

VEIGO (available at shopveigo.com) addresses this through a multi-tenant architecture built on Next.js. Here's how the platform is structured:

1. Housing & Rental Module

Covering 5 countries with localized listing systems, currency support, and lease management. The module includes:

Map-based property search with geocoding
Multi-currency rent calculation and conversion
Landlord verification and review system
Lease document templates adapted to local regulations

2. Recruitment Module (BOSS直聘 Model)

Instead of the traditional resume-submit-and-wait approach, VEIGO's job module implements a direct chat model:

Real-time messaging between candidates and employers
Skill-based matching algorithm
Work authorization verification (visa status, permits)
Salary range transparency requirements

3. Freelance & Gig Economy

A marketplace for short-term work, specifically designed for expats who need flexible income:

Gig posting and discovery
Escrow-based payment protection
Multi-language project descriptions
Rating and reputation system

4. Bidding & Procurement

For businesses and contractors operating across borders, this module handles:

Tender document submission
Bid comparison and evaluation
Compliance checking across jurisdictions

5. AI Tool Suite

Integrated directly into the platform:

AI writing assistant for resumes, cover letters, and listings
Image generation for property listings and marketing
Translation support across all modules

6. Video Production Studio

Technical Architecture

The platform is built with a Next.js frontend and a multi-tenant backend that handles:

┌─────────────────────────────────────────┐
│              Next.js Frontend            │
├─────────────────────────────────────────┤
│         API Gateway (Route Handler)      │
├─────────┬──────────┬──────────┬─────────┤
│ Rental  │  Jobs    │  Gigs    │  AI     │
│ Service │  Service │  Service │  Service│
├─────────┴──────────┴──────────┴─────────┤
│         Shared Auth & Tenant Layer       │
├─────────────────────────────────────────┤
│         Database (Multi-tenant Schema)   │
└─────────────────────────────────────────┘

Key technical decisions:

Tenant isolation: Each country operates as a logical tenant with localized content, currency, and legal compliance
Shared authentication: Single sign-on across all modules — your rental profile feeds into your job application
Modular API design: Each service is independently deployable but shares common utilities (auth, payment, i18n)
Edge-ready: Next.js API routes with ISR for content-heavy pages

What I Learned Building This

1. Localization is deeper than translation
Each country's rental market has different norms. In Japan, key money (礼金) is standard. In Spain, deposits are regulated differently. Your schema needs to accommodate these variations without becoming unmaintainable.

2. Trust is the real product
Expats are vulnerable to scams. Every module includes verification layers — ID verification for landlords, business registration checks for employers, portfolio verification for freelancers.

3. Cross-module data is the moat
The real value isn't any single module — it's how they connect. A tenant's rental history informs their creditworthiness for job applications. A freelancer's project portfolio doubles as a resume. This interconnectedness is what makes VEIGO more than the sum of its parts.

What's Next

We're expanding to more countries, adding more AI-powered features, and building out the video production studio for property marketing and personal branding.

If you're an expat, student abroad, or part of the global Chinese community, I'd love for you to try it out and share feedback.

🔗 Try VEIGO: shopveigo.com
🎬 AI Video Studio: shopveigo.com/studio
💳 Premium Plans: shopveigo.com/pricing

What's your biggest pain point as an expat? I'd love to hear in the comments.

DEV Community: PubliFlow

Launch a Profitable SaaS in 7 Days: The Ultimate Next.js Starter Kit Guide

Launch a Profitable SaaS in 7 Days: The Ultimate Next.js Starter Kit Guide

Launch a Profitable SaaS in 7 Days: The Ultimate Next.js Starter Kit Guide

Day 1-2: Architecture, Auth, and Route Protection

Implementing Bulletproof Auth Middleware

Day 3-4: Payments and Subscriptions

Handling Payment Webhooks Securely

Day 5: Landing Page, SEO, and Performance

Performance Best Practices

Day 6: Content Distribution and Marketing

Day 7: Launch, Email, and Avoiding Pitfalls

Common Pitfalls to Avoid

Final Performance Checks

Key Takeaways

SaaS Boilerplate Pricing: What Should You Actually Pay in 2026?

SaaS Boilerplate Pricing: What Should You Actually Pay in 2026?

SaaS Boilerplate Pricing: What Should You Actually Pay in 2026?

The True Cost of Building from Scratch

Technical Deep Dive 1: Bulletproof Billing Architecture

Technical Deep Dive 2: Distribution and the PubliFlow Advantage

Technical Deep Dive 3: Next.js Performance and Caching

Common Pitfalls and How to Evaluate a Boilerplate

Key Takeaways

Best Next.js SaaS Boilerplate in 2026: An Honest Comparison

Best Next.js SaaS Boilerplate in 2026: An Honest Comparison

Best Next.js SaaS Boilerplate in 2026: An Honest Comparison

The Contenders: A High-Level Overview

Core Architecture: Auth, Routing, and Middleware

Payments and Webhooks: The Lifeblood of SaaS

The Missing Piece in 2026: Built-in Distribution

Common Pitfalls and Performance Considerations

Pitfall 1: The React Server Component (RSC) Waterfall

Pitfall 2: Ignoring Edge Caching

Pitfall 3: Bloated Client Bundles

Key Takeaways: Which Boilerplate Should You Choose?

Build an AI SaaS with Next.js: Streaming, Credits, and Cost Control

Build an AI SaaS with Next.js: Streaming, Credits, and Cost Control

Build an AI SaaS with Next.js: Streaming, Credits, and Cost Control

1. The UX Imperative: Streaming Responses

Code Example: Native Streaming with Edge Runtime

2. Monetization: Usage-Based Credits and Cost Tracking

Code Example: Atomic Credit Deduction and Reconciliation

3. Cost Control: Rate Limiting and Abuse Prevention

Code Example: Edge Rate Limiting with Token Estimation

Accelerating Your Launch with the Right Tools

Key Takeaways and Best Practices

How to Nail Your Grad School Application Essays (Without Cheating or Burnout)

How to Nail Your Grad School Application Essays (Without Cheating or Burnout)

1. Beat the blank page with structured outlining — not AI-generated essays

2. Turn your interview prep into a mock, not a monologue

3. Free up your evenings with an email workflow

The tools that helped me

Mastering Supabase Auth & Row Level Security for Multi-Tenant SaaS

Mastering Supabase Auth & Row Level Security for Multi-Tenant SaaS

The Architecture: Bridging Auth and Postgres

Deep Dive 1: Injecting Custom Claims into the JWT

Code Example 1: Syncing Tenant Context to JWT via Trigger

Deep Dive 2: Writing Bulletproof RLS Policies

Code Example 2: Centralized RLS Helper and Policies

Deep Dive 3: Testing RLS Strategies

Code Example 3: Direct Database RLS Testing

Performance Considerations

Common Pitfalls to Avoid

Key Takeaways

Next.js 15 Server Actions Deep Dive: Patterns for Production SaaS

Next.js 15 Server Actions Deep Dive: Patterns for Production SaaS

Under the Hood: The Mental Model

Pattern 1: Advanced Form Handling with useActionState

The Server Action

The Client Component

Pattern 2: Optimistic Updates for Instant UI

The Server Action

The Client Component

Pattern 3: Secure Context Passing and Preventing IDOR

Common Pitfalls and Performance Considerations

Key Takeaways

Building a Production-Ready SaaS Starter Kit from Scratch: Architecture & Implementation

Building a Production-Ready SaaS Starter Kit from Scratch: Architecture & Implementation

High-Level Architecture

Pattern 1: Advanced Form Handling with `useActionState`