Changelog

SaaS Starter v2.0.0 — Major Release

Version 2.0 is the largest SaaS Starter release to date, delivering core framework upgrades alongside nine major new features and a security hardening pass. Several breaking changes require migration — read the notes carefully.

---

💥 Breaking Changes

• TypeScript 6.0 — strict rootDir enforcement; apps/api/tsconfig.json updated with "rootDir": "../../". exactOptionalPropertyTypes and noUncheckedIndexedAccess are now enabled.
• ESLint 10 flat config — .eslintrc dropped; new eslint.config.mjs at repo root; next lint replaced by eslint src --ext .ts,.tsx in web.
• Zod v4 — z.record() now requires an explicit key schema: z.record(z.string(), valueType).
• Vitest v4 — constructor mocks must use function keyword, not arrow functions.

⬆️ Dependency Upgrades

| Package | From | To | |---|---|---| | TypeScript | 5.5 | 6.0 | | Next.js | 15.x | 16.2.3 | | Hono | 3.x | 4.12 | | React | 18.x | 19 | | ESLint | 8.x | 10.2.0 | | Tailwind CSS | 3.4 | 4.2.2 | | Vitest | 2.x | 4.1.4 | | Zod | 3.x | 4.3.6 | | Stripe SDK | 16.x | 22.0.1 | | OpenAI SDK | 4.x | 6.34.0 | | Anthropic SDK | 0.32 | 0.88.0 | | Groq SDK | 0.7 | 1.1.2 | | Framer Motion | 11.x | 12.38.0 | | Recharts | 2.x | 3.8.1 | | Pino | 9.x | 10.3.1 | | Nodemailer | 7.x | 8.0.5 | | Resend | 4.x | 6.10.0 | | bcryptjs | 2.x | 3.0.3 | | nanoid | 4.x | 5.1.7 | | Vite | 5.x | 8.0.8 | | @types/node | 20.x | 25.6.0 | | Lucide React | 0.447 | 1.8.0 |

🏗️ Template System (13 SaaS Vertical Templates)

Pre-built vertical presets that configure modules, landing page, dashboard sections, and navigation for a specific business domain — expanded from 8 to 13 templates:

1. Developer API Platform (developer) — API-first, usage-based billing, developer tools
2. E-Commerce (ecommerce) — product catalog, cart, order management
3. CRM / Professional Services (professional) — client portals, pipeline management
4. Creator Platform (creator) — content subscriptions, digital storefronts, payouts
5. Internal Tools Builder (internal-tools) — admin panels, workflow automation, audit logs
6. Fintech (fintech) — financial dashboards, transactions, risk monitoring
7. Healthcare (healthcare) — patient portals, appointments, care notes
8. Kanban / Productivity (productivity) — boards, tasks, team collaboration
9. AI SaaS Platform (ai) — multi-provider AI, credit metering, streaming chat, RAG
10. Education / LMS (education) — course creation, student enrollment, certificates
11. Marketplace Platform (marketplace) — multi-vendor, commissions, dispute resolution
12. Social & Community (social) — feeds, groups, messaging, moderation
13. Booking Platform (booking) — scheduling, calendar management, reminders

Each template includes relevant landing page content, dashboard sections, DB schema additions, and visual identity. Generate with pnpm saas-starter init or install from the admin panel at /admin/templates.

💳 Billing Factory (4 Providers)

The billing factory now supports four providers, swappable via BILLING_PROVIDER:

| Provider | Env Value | Notes | |---|---|---| | Stripe | stripe | Checkout, customer portal, subscriptions, metered billing | | Paddle | paddle | Paddle Billing (v2), tax handling, Paddle-specific webhook events | | Lemon Squeezy | lemonsqueezy | License key management, subscriptions, one-time payments | | Polar | polar | Open-source-friendly billing, pay-what-you-want, subscriptions |

Webhook handlers are implemented for all four providers with HMAC verification, idempotent processing (Redis dedup), and BullMQ retry with exponential backoff.

🖥️ Admin Dashboard

Completely overhauled admin experience at /admin:

• MRR, churn, growth, DAU/MAU stats with trend charts
• User impersonation with audit trail
• Feature flags (runtime toggles without redeploy)
• Plan overrides per org
• Trial extensions
• AI usage overview (tokens by provider, spend)
• Billing history and invoice download
• SEO metadata editor
• RBAC permissions matrix viewer
• Real-time notification stream

📊 Monitoring Stack (Prometheus + Grafana)

Production observability out of the box:

• apps/api exposes /metrics endpoint (Prometheus prom-client)
• Pre-built Grafana dashboards covering API latency, p95/p99, request rates by route, error rates, BullMQ queue depth, DB connection pool, and AI token consumption
• docker-compose.monitoring.yml — adds Prometheus + Grafana containers with pre-configured data sources and dashboards
• Alerting rules for error rate spikes, queue backlogs, and certificate expiry

🔧 CLI Tool (packages/cli)

A saas-starter CLI for common operations, run via pnpm saas-starter:

• pnpm saas-starter init — interactive project initialization wizard
• pnpm saas-starter add <module> — enable an optional module
• pnpm saas-starter remove <module> — disable an optional module
• pnpm saas-starter doctor — run 11 environment checks
• pnpm saas-starter deploy <platform> — generate deployment config for Coolify, etc.

⚠️ Always use pnpm saas-starter inside the monorepo. Using npx saas-starter may download an unrelated package from the public npm registry.

🤖 MCP Server (packages/mcp)

Model Context Protocol server for AI agent integration:

• Exposes project context (routes, schema, config, plans) to AI coding tools
• Run with pnpm mcp — compatible with Cursor, Claude Code, Copilot Workspace, and other MCP clients
• Provides real-time schema and route information so agents write correct factory calls and ESM imports

🧠 AI Factory (7 Providers)

Expanded from 4 to 7 AI providers, swappable via AI_PROVIDER:

| Provider | Env Value | Default Model | |---|---|---| | OpenAI | openai | gpt-4.1 | | Anthropic | anthropic | claude-sonnet-4-20250514 | | Google Gemini | gemini | gemini-2.5-pro | | Groq | groq | llama-4-maverick | | Cerebras | cerebras | llama-3.1-8b | | Mistral | mistral | mistral-large-latest | | Together | together | meta-llama/Llama-3.3-70B-Instruct-Turbo |

Streaming and non-streaming chat endpoints unchanged: POST /api/ai/stream and POST /api/ai/chat.

💳 Billing Webhooks (All 4 Providers)

Full webhook handler coverage for Stripe, Paddle, Lemon Squeezy, and Polar:

• HMAC signature verification per provider
• Idempotent event processing via Redis dedup
• BullMQ retry with exponential backoff for failed deliveries
• Events processed: checkout.completed, subscription.created, subscription.updated, subscription.cancelled, subscription.renewed, payment.failed, payment.refunded
• Admin UI for manual retry of failed webhook deliveries

🌗 Dark / Light Theme with 27 Presets

Full theming system powered by CSS custom properties:

• System-preference detection with manual override toggle
• Smooth transitions between light and dark modes
• 27 preset color themes across 4 categories:
  • B2B Corporate: Default (Indigo), Ocean, Forest, Fintech, Enterprise, Banking, Legaltech
  • B2C Friendly: Rose, Amber, Pastel, Bubbly, Wellness, Edtech, Marketplace, Healthcare, Productivity
  • Developer: Dracula, Terminal, GitHub, Monokai, Synthwave, Brutalist, Cyber Minimal
  • VibeCoder: Neon, Retrowave, Aurora, Candy, Frost, Glass, AI Native
• Presets applied at runtime — no rebuild required
• Per-org theme preference persisted in DB

🎨 Dynamic Branding System

Runtime-configurable branding without code changes:

• saas-starter.config.ts — top-level feature toggles, branding colors, module enablement
• Logo, favicon, and OG image served from config
• Primary/accent colors propagated to all UI components including charts, buttons, and email templates
• Plan names and descriptions editable in packages/shared/src/plans.ts

🔒 Module Gating System

Fine-grained control over which features are active:

• Toggle SaaS modules on/off from the admin dashboard (/admin/modules) or via saas-starter.config.ts
• Disabled modules vanish from navigation, routes return 404, and API endpoints are blocked — no dead ends
• 13 built-in modules: AI, storage, roadmap, webhooks, referrals, waitlist, affiliates, feedback, customDomains, projects, announcements, blog, changelog

🛡️ Security Improvements

• Fail-close admin access — if ADMIN_UIDS env var and admin_user DB table are both empty, admin routes return 403 (previously fell through to open access)
• Docker Secrets — all sensitive environment variables (database passwords, API keys, secrets) can be loaded from Docker Secrets (/run/secrets/<name>); supported in apps/api/src/config.ts
• Stealth admin path — configure a custom admin path via ADMIN_PATH env var (defaults to /admin). Set REQUIRE_ADMIN_PATH_COOKIE=true for stealth 404 behavior.
• @types/bcryptjs removed (deprecated; types ship with bcryptjs v3)

🐛 Bug Fixes

• PostgreSQL 15+ schema permissions — setup-local.sh now grants SCHEMA public to saas-starter user on the correct database for both macOS and Linux
• Next.js build-time fetch hang — AbortController (3 s timeout) added to all build-time fetch() calls in page.tsx and demo/layout.tsx
• Stripe API version literal — updated to '2026-03-25.dahlia' (Stripe SDK 22 requirement)
• Recharts v3 formatter types — tooltip formatter updated to handle undefined values
• Nginx reverse proxy generation — scripts/setup-proxy.sh and configs/nginx.conf.template no longer emit map inside server blocks, fixing nginx: "map" directive is not allowed here

📦 Other Changes

• apps/web/src/types/global.d.ts — ambient module declarations for CSS/SVG/image imports (required by TS6)
• eslint.config.mjs — ESLint 10 flat config with TypeScript, Next.js, and React Hooks rules
• LICENSE — Commercial Source License added to repository root

🔄 Migration Guide

1. Update env vars — run pnpm saas-starter doctor to validate; add any new provider keys (CEREBRAS_API_KEY, MISTRAL_API_KEY, TOGETHER_API_KEY, LEMONSQUEEZY_API_KEY, POLAR_ACCESS_TOKEN)
2. Run migrations — pnpm migrate
3. Fix Zod v4 — search for z.record(ValueType) and add explicit key schema: z.record(z.string(), ValueType)
4. Fix Vitest v4 — convert arrow-function constructor mocks to function keyword
5. Fix ESLint — remove .eslintrc* files; use the new eslint.config.mjs
6. Set ADMIN_PATH — configure a custom admin path or use the default /admin
7. Configure monitoring — docker compose -f docker-compose.yml -f docker-compose.monitoring.yml up -d to add Prometheus + Grafana

SaaS Starter v1.4.2 — Documentation accuracy & demo polish

📚 Docs app (apps/docs)

• Removed the default GitHub project icon and “Edit on GitHub” link from the Nextra layout — they implied a public repo; this boilerplate is delivered privately (zip, vendor portal, or your own remote).
• Feedback in the docs TOC now directs readers to email instead of opening GitHub issues.
• README stack table now lists Nextra 4 (matching package.json) and notes the /docs base path.

⚠️ Purchase expectations (Disclaimer, FAQ, README)

• Clarified that updates are not guaranteed and must not be read as a 12‑month window or “lifetime updates” promise: access to the source can be lifetime; delivery of future patches is best-effort only and may continue without a fixed end date.
• Replaced “GitHub issues” wording in FAQs with vendor / purchase-channel support (OAuth “GitHub” as a login provider is unchanged).
• Spanish license bullet no longer implies guaranteed lifetime updates in the same breath as “compras una vez”.

🎨 Demo pricing ribbon (highlighted tier)

• Pricing cards use overflow-hidden with rounded-2xl so the “Most popular” ribbon follows the card’s corner radius.
• Added top padding when the ribbon is shown so the tier label does not sit under the badge.

SaaS Starter v1.4.1 — Bug Fixes & Copy Accuracy

🎯 Demo newsletter widget now interactive

The "Weekly focus digest" block in the Flowspace (productivity) demo previously rendered the email address as static placeholder text. It is now a real <input> with a submit button that simulates a 700 ms delay and shows a success state — making the demo feel like a real product for prospects.

📋 Pricing copy — honest updates language

Replaced all instances of "12 months of updates" and "lifetime updates included" with accurate language: updates are pushed best-effort and are not guaranteed. Affected locations:

• DisclaimerBanner (pre-purchase warning)
• FAQ items ("Is this a one-time purchase?" and "What's NOT included?")
• Pricing card feature list and subtext
• SocialProof badge strip
• /pricing page metadata description

🏷️ Pricing card ribbon badge corners

The "Most popular" ribbon banner on highlighted demo pricing cards was missing the top-left rounded corner (rounded-tl-2xl) — the corner was square against the card's rounded-2xl parent. Added rounded-tl-2xl so the badge contours correctly with the card edge.

SaaS Starter v1.4.0 — Developer Experience & Platform Features

This release adds seven high-value features targeting the day-to-day experience of building and operating a SaaS product.

🎮 API Playground (/dashboard/api-playground)

An interactive API explorer built directly into the dashboard:

• Lists all available API endpoints grouped by category
• Executes requests using the signed-in user's session
• Shows request/response with syntax highlighting
• Accepts custom body JSON for POST/PATCH endpoints
• Powered by the existing OpenAPI schema at /api/docs

Perfect for debugging and for onboarding new devs to the API surface.

🌍 Environment Badge

A persistent badge in the dashboard header shows the current deployment environment:

• DEV — blue badge (development mode)
• STAGING — yellow badge (staging environment)
• PROD — red badge (production)

Driven by NEXT_PUBLIC_APP_ENV. Visual reminder prevents accidentally running production commands in dev and vice versa.

🔐 RBAC Permissions Matrix (/dashboard/team/permissions)

A visual role × action matrix table showing exactly what each role can do:

| Action | Owner | Admin | Member | |--------|-------|-------|--------| | Invite members | ✅ | ✅ | ❌ | | Remove members | ✅ | ✅ | ❌ | | Manage billing | ✅ | ❌ | ❌ | | View audit logs | ✅ | ✅ | ❌ | | Manage webhooks | ✅ | ✅ | ❌ | | ... | | | |

Makes it easy to communicate permission boundaries to new team members and enterprise customers.

🔄 Webhook Retry UI (/dashboard/webhooks)

Webhook delivery history now includes a Retry button on failed deliveries:

• Retries failed webhook payloads on demand
• Updates delivery status in real time
• Shows retry count and next retry timestamp
• Success/failure toast feedback

🔎 SEO Metadata Editor (/admin/seo)

Admin-level SEO editor for key pages:

• Edit page title, meta description, and OG image URL
• Changes saved to the settings DB table (existing KV store)
• Live preview of how the page will appear in search results
• Supports homepage, pricing, blog, changelog, and roadmap pages

📊 AI Usage Dashboard (/dashboard/ai)

The AI page now shows a comprehensive usage dashboard above the chat widget:

• Total tokens used this month (vs. plan limit)
• Breakdown by AI provider (OpenAI, Anthropic, Gemini, Groq)
• Credit balance with "Buy Credits" CTA
• Credit transaction history (paginated)
• Gauge chart showing % of monthly quota consumed

🧾 Billing History Table (/dashboard/billing)

The billing page now includes a Payment History section:

• Lists all invoices from Stripe/Paddle
• Shows date, amount, status, and plan
• Download PDF invoice link per entry
• Powered by the existing /api/billing/invoices endpoint

---

Other Changes

• Landing page hero copy updated to clearly identify SaaS Starter as a SaaS boilerplate
• CSP connect-src now correctly allows http://localhost:* in development mode
• Dashboard layout now has proper error boundary and not-found pages
• 5 new SEO-optimized blog posts added to content/blog/

What's new in v1.1.0

🧠 Prepaid AI Credit Packs

Users can now purchase credit packs (100 / 500 / 2000 credits) via a one-time Stripe payment. Credits are consumed on every AI request. Orgs on lower plans can still use AI by topping up — no plan upgrade required.

• New orgCredits and creditTransaction DB tables
• GET /credits/balance — balance + pack options
• POST /credits/topup — Stripe one-time checkout
• GET /credits/history — full transaction ledger
• 402 Payment Required returned when balance is zero

🤖 MCP Server (packages/mcp)

A Model Context Protocol server that gives AI agents (Claude, Cursor, Codex) deep context about your SaaS Starter codebase — org structure, plans, routes architecture. Agents write correct code faster with zero hallucination about the project layout.

pnpm mcp

🔐 Security Hardening

• secureHeaders() with full CSP, HSTS preload, Permissions-Policy, and X-Frame-Options on all routes
• Brute-force rate limiting on /api/auth/sign-in, /api/auth/forget-password, /api/auth/magic-link (5 req / 15 min per IP)
• Pino logger redacts password, token, secret, authorization, cookie fields — no credential leaks in logs
• All sensitive fields in structured logs are now [REDACTED]

⚡ Code Generator CLI

pnpm generate route payments
pnpm generate component BillingCard
pnpm generate worker cleanup
pnpm generate email welcome

Scaffolds complete files (route with zValidator, shadcn component, BullMQ worker, HTML email template) with the correct imports and patterns pre-filled.

🔄 Automated Dependency Updates

.github/dependabot.yml — weekly PRs for npm + Docker base images, grouped by ecosystem.

🛡️ CI Security Audit

New GitHub Actions job: pnpm audit --audit-level=high + TruffleHog secret scanning on every PR. PRs automatically receive a test coverage comment.

SaaS Starter v1.3.0 — Plugin / Module System

This is the biggest architectural addition since v1.0.0. SaaS Starter now functions as a modular SaaS operating system — each feature is a toggleable plugin, not a hard-wired dependency.

🔌 10 Built-in Modules

| Module | Description | Plan | |--------|-------------|------| | ai | AI assistant, streaming chat, token usage | Starter+ | | billing | Subscription management, invoices, portal | Free | | analytics | Usage charts, event tracking, PostHog | Free | | blog | Public blog with MDX content | Free | | changelog | Versioned changelog, update widget | Free | | notifications | In-app notifications, SSE stream | Free | | webhooks | Outgoing webhooks, delivery history | Pro+ | | storage | File upload, S3/R2 management | Starter+ | | roadmap | Public roadmap, user upvoting | Free | | referrals | Referral codes, tracking dashboard | Free |

⚙️ Plugin Settings Page (/dashboard/settings/plugins)

A new settings page lists all modules with:

• Toggle switch (enabled/disabled)
• Description of what the module provides
• Required plan tier
• Instant save via the feature flags API (no redeploy)

🧭 Plugin-Aware Navigation

The sidebar and mobile nav now filter items based on enabled plugins. When ai is disabled:

• AI Assistant disappears from sidebar
• /dashboard/ai redirects to /dashboard
• No 404, no confusing permission errors

🛡️ Route Guards

Every module page now checks if its module is enabled before rendering. Accessing a disabled module's URL safely redirects to the dashboard.

🏗️ Architecture

The plugin system is built on top of the existing feature flags DB table — no schema changes required. The new PluginContext client provider:

• Fetches flag states from GET /api/admin/feature-flags on mount
• Caches results with React Query (60s stale time)
• Exposes isEnabled(moduleId) and togglePlugin(moduleId) hooks
• Admin users can toggle; member users see current state only

Developer Guide

To add a new module to the registry, add a single entry to apps/web/src/lib/plugins.ts:

export const PLUGINS = {
  // ...existing
  my_feature: {
    id: 'my_feature',
    name: 'My Feature',
    description: 'What this does.',
    icon: '✨',
    requiredPlan: 'starter',
    navItem: { href: '/dashboard/my-feature', label: 'My Feature', icon: '✨' },
  },
}

Then guard your page and the nav item handles itself.

SaaS Starter v1.2.0 — Theme System

This release transforms SaaS Starter's visual layer from a single blue+dark-mode combination into a full multi-theme platform with 25 distinct color palettes and a live preview selector.

🎨 25 Color Themes

Four theme categories covering every SaaS use case:

B2B Corporate

• enterprise — Corporate blue with slate neutrals, squared corners
• banking — Deep navy with gold accents, financial weight
• legaltech — Dark slate, minimal contrast, ultra-tight radius

B2C Friendly

• pastel — Soft lavender/lilac, large radius, gentle UI
• bubbly — Coral primary, large radius, warm and friendly
• wellness — Sage green, soft corners, calming tones
• edtech — Bright orange, high contrast, engaging
• marketplace — Teal primary, optimized for product discovery

Developer & Tech Tools

• dracula — Purple/pink, dark-mode-first, familiar to devs
• terminal — Matrix green, minimal radius, technical aesthetic
• github — Blue-gray, neutral, GitHub-familiar design language
• monokai — Warm orange/amber, editor-inspired
• synthwave — Neon pink/purple, retro-futuristic

VibeCoder / Indie Hacker

• neon — Electric blue, high contrast, modern SaaS
• retrowave — Hot magenta, 80s aesthetic, memorable
• aurora — Emerald/teal gradient-inspired
• candy — Hot pink, maximum rounded corners, playful
• frost — Ice blue, glass-like clarity

All themes also include an updated ocean, forest, rose, amber, fintech, healthcare, and productivity with properly distinct color values (previously all had the same fallback blue).

🎛️ Theme Selector UI (/dashboard/settings)

A new Appearance section in Settings shows a visual swatch grid with:

• Real color previews per theme
• Category grouping (B2B, B2C, Dev, VibeCoder)
• One-click apply with instant preview
• Persisted to localStorage — survives page reloads

🔄 ThemeContext Provider

The new ThemeContext extends next-themes integration:

• Exposes { dataTheme, setDataTheme } across the app
• Applies data-theme attribute on <html> with zero flash
• Co-exists with existing light/dark mode toggle

Bug Fixes

• Fixed: All existing [data-theme] presets had identical primary color (217 91% 59%) — now each has a genuinely distinct palette
• Fixed: BrandingInjector now syncs localStorage theme on mount

SaaS Starter v1.0.0 — Initial Release

The first public release of SaaS Starter — a production-ready TypeScript monorepo boilerplate for B2B SaaS products.

🏢 Multi-Tenant Organizations

• Users can belong to multiple organizations with roles (owner / admin / member)
• Seat limits enforced per plan
• Trial period tracking per org
• X-Org-Id header resolves org context on every API request

🔐 Authentication (Better Auth)

• Email + password with verification
• Google and GitHub OAuth
• Magic link (passwordless)
• TOTP 2FA
• All self-hosted — no Auth0, no Firebase, no vendor lock-in

💳 Billing (Stripe + Paddle)

• Factory pattern: swap between Stripe and Paddle via BILLING_PROVIDER env var
• Full checkout, customer portal, cancellation, and reactivation flows
• Webhook handlers for both providers with idempotency (Redis dedup)
• Annual/monthly billing with 20% annual discount
• Per-seat metered billing

🛠️ Admin Dashboard

• MRR, churn, growth stats, DAU/MAU
• User impersonation with audit trail
• Feature flags (runtime toggles without redeploy)
• Plan override per org
• Trial extension

✉️ Email (SMTP / Resend / SendGrid)

• Factory pattern: swap provider with one env var
• 6 polished templates: welcome, password reset, team invite, subscription confirmed/cancelled, onboarding
• Async delivery via BullMQ queue (concurrency: 5)

⚡ BullMQ Workers

• emailQueue — transactional emails
• webhookQueue — outbound webhooks with retry
• maintenanceQueue — GDPR hard-delete, expired token cleanup
• onboardingQueue — day-3 and day-7 nurture email sequences

🔗 Outgoing Webhooks

• HMAC-SHA256 signed payloads (X-Signature: sha256=...)
• Event subscriptions per webhook
• Delivery history with request/response captured
• Exponential backoff retry (BullMQ)

🐳 Docker + Caddy

• Full production docker-compose.prod.yml with PostgreSQL, Redis (dual), API, Web, Caddy
• Auto-TLS via Caddy (Let's Encrypt / ZeroSSL)
• Docker Secrets support for all sensitive env vars

🔑 CI/CD API Tokens

• nsk_PREFIX_SECRET format tokens (bcrypt stored)
• Optional expiry, last-used tracking
• Feature-gated per plan

📋 Audit Log

• Immutable trail for: plan changes, impersonation, webhook creates, user deletes
• Fire-and-forget (never fails user requests)

🌍 i18n

• next-intl with English and Spanish out of the box
• Add new languages by adding a messages JSON file