SaaS Builder – React + Supabase Starter

Modern SaaS starter template built with React 19, Vite, TypeScript, Supabase, Stripe-ready billing hooks, and a polished marketing/demo experience.

---

Overview

SaaS Builder is a simple base that shows how to assemble a modern React + Supabase stack without a huge boilerplate. It is intentionally small, but wired with real building blocks:

• Supabase CLI for local database, types generation, auth, and storage buckets.
• Built in State management using Tanstack
• Storybook already configured so you can build and document UI components in isolation.

The goal is to give a solid, realistic base for simple Saas.

---

Tech Stack

• Frontend: React 19, React Router, TypeScript, Vite
• Styling: Tailwind CSS, Shadcn
• Data: Supabase + Supabase CLI (database, types, auth, storage)
• State management: TanStack Query
• Payments: Stripe SDK + starter plans configuration
• Tooling: ESLint (flat config), Storybook, Cypress

---

Getting Started

Prerequisites

• Node.js v20+ (recommended)
• npm (comes with Node)

1. Clone and install

git clone https://github.com/Rovis91/saas-builder.git
cd saas-builder
npm install

2. Configure environment variables

Copy the example env file and fill in your values:

cp .env.example .env

At minimum, set:

• VITE_SUPABASE_URL
• VITE_SUPABASE_ANON_KEY

The app will still start without real credentials; Supabase and Stripe calls will simply fail gracefully with console warnings until you configure them.

3. Run the dev server

npm run dev

Vite will print the local URL (usually http://localhost:5173). Open it in your browser to see the landing page and demo.

---

Environment Variables

All environment variables are prefixed with VITE_ so they are available in the browser build. Use .env for local development (never commit secrets).

Core / Supabase

• VITE_SUPABASE_URL – Supabase project URL
• VITE_SUPABASE_ANON_KEY – Supabase public anon key

These are consumed by:

• src/lib/supabase.ts – main Supabase client singleton
• src/hooks/useCheckout.ts – Supabase Edge Function calls for Stripe Checkout
• src/hooks/useBillingPortal.ts – Supabase Edge Function calls for Stripe Customer Portal

Stripe pricing

• VITE_STRIPE_PRICE_PROFESSIONNEL_MONTH
• VITE_STRIPE_PRICE_PROFESSIONNEL_YEAR
• VITE_STRIPE_PRICE_ENTREPRISE_MONTH
• VITE_STRIPE_PRICE_ENTREPRISE_YEAR

Used in src/lib/stripe-plans.ts to wire plan metadata to Stripe price IDs.

Telegram notifications (optional)

• VITE_TELEGRAM_BOT_TOKEN
• VITE_TELEGRAM_CHAT_ID

Used by src/utils/telegram.utils.ts to send optional alerts and feedback to a Telegram chat. If they are missing, the app logs a warning and skips Telegram calls.

---

Architecture & Conventions

This template follows a few opinionated patterns to keep things predictable and easy to extend:

• Components vs hooks vs services
  • Components: UI only. Receive data via props and call callbacks for actions.
  • Hooks: orchestrate UI state and call services (no direct Supabase calls in components).
  • Services: pure functions that talk to Supabase/Stripe and throw errors on failure.
• URL-based UI state for shareable filters, tabs, and dialog state (see hooks like useCoreData examples).
• React Query as a cache for server data, with pages reading from hooks instead of fetching directly.
• Error handling centralised in error.service.ts, with user feedback via toasts and optional Telegram notifications.

These conventions are documented in more detail for AI agents under .agent/System, but the code is readable without that context.

---

Scripts

Common npm scripts defined in package.json:

• npm run dev – start Vite dev server
• npm run build – type-check the project and build for production
• npm run preview – preview the production build locally
• npm run lint – run ESLint with the flat config
• npm run storybook – run Storybook for isolated UI development
• npm run build-storybook – build the Storybook static site

Database-related scripts (for Supabase CLI users):

• npm run db:start – start local Supabase
• npm run db:stop – stop local Supabase
• npm run db:reset – reset local database and seed
• npm run db:types – regenerate Supabase TypeScript types

---

CI / CD

This template ships with a minimal GitHub Actions workflow that:

• Installs dependencies
• Runs npm run lint
• Runs npm run build

You can find and customise it under .github/workflows/ci.yml. Extend it with tests, Storybook builds, or deploy steps as you evolve the project.

---

License

This project is open source and available under the terms of the MIT License. See the LICENSE file for details.

---

Contributing & custom work

If you see something that can be improved, issues and pull requests are very welcome—whether it’s better DX, clearer examples, or extra integrations that stay within the lean template philosophy.

If you’d like help adapting this starter to your own SaaS (custom flows, integrations, or architecture reviews), you can also reach out directly via GitHub.