TinyKit Docs

Getting Started

This guide will help you set up TinyKit SaaS locally and get it running in development mode.

Quick Start (60 seconds)

git clone <your-repo-url>
cd tinykit-saas-convex
pnpm install
pnpm run setup     # Interactive setup + browser login
pnpm dev       # You're running!

The streamlined setup wizard uses smart defaults so you can start developing immediately. Additional configuration (Stripe, OAuth, Resend) can be done later via the Admin panel or pnpm run setup:credentials.

Prerequisites

Required:

  • Node.js 22+ and pnpm (install from pnpm.io)

Created during setup:

  • Convex account (free tier) - created via browser login during setup

Optional (configure later via Admin panel):

  • Stripe account (for billing features) - stripe.com
  • Resend account (for email features) - resend.com
  • OAuth provider accounts (GitHub, Google)

Installation

1. Clone and Install

git clone <your-repo-url>
cd tinykit-saas-convex
pnpm install
pnpm run setup

The streamlined wizard:

  1. Asks one question: "Ready to start?"
  2. Opens browser for Convex login/signup
  3. Applies smart defaults automatically
  4. Generates environment files with correct configuration
  5. Initializes database (you choose: development or production mode)

Smart Defaults Applied:

  • Site URL: http://localhost:3001
  • Site Name: TinyKit
  • Auth Methods: Email/Password only
  • Billing/Analytics: Disabled until credentials added

3. Configure Additional Features

After the initial setup, configure additional features as needed:

Option A: Admin Panel (After signing in as admin)

The admin dashboard shows a setup banner with checklist items:

  • Site Settings - Configure domain, name, support email
  • Authentication - Add OAuth providers
  • Billing - Connect Stripe
  • Email - Connect Resend

Option B: Guided CLI Setup

pnpm run setup:credentials           # All services
pnpm run setup:credentials --oauth   # Just OAuth providers
pnpm run setup:credentials --stripe  # Just Stripe
pnpm run setup:credentials --email   # Just Resend

4. Manual Configuration (Alternative)

If you prefer manual setup:

cp .env.local.example .env.local
# Edit .env.local manually
npx convex dev    # Starts Convex backend only
pnpm dev:frontend  # In another terminal, starts Next.js frontend

Note: npx convex dev only starts the Convex backend. Use pnpm dev to start both frontend and backend together, or run them separately with pnpm dev:backend and pnpm dev:frontend.

See Environment Variables Reference for complete configuration.

Note: All secrets (Stripe keys, RESEND_API_KEY, OAuth secrets) must be set in Convex environment variables, not in .env.local. The setup wizard handles this automatically.

5. Start Development Server

pnpm dev

This will start:

  • Next.js frontend on http://localhost:3001
  • Convex backend (automatically configured)
  • Stripe webhooks via Stripe Dashboard (if configured)

Initial Setup Tasks

1. Set Up Convex Environment Variables

Configure backend-only environment variables in Convex:

# Optional: Email system (password reset, notifications)
# Note: Application works without this - email features gracefully disabled
npx convex env set RESEND_API_KEY re_your_api_key_here
npx convex env set RESEND_TEST_MODE true

# Stripe backend configuration (for billing)
npx convex env set STRIPE_SECRET_KEY sk_test_...
npx convex env set STRIPE_WEBHOOK_SECRET whsec_...

Note: Email configuration (support email, domain, site URL) is now managed through the database and configured via the admin panel under "Site Settings → Email Configuration".

2. Configure Email Settings (Database-Driven)

Email configuration is now stored in the database instead of environment variables. After running the setup wizard or seeding the database, you can configure email settings through:

  • Admin Panel: Go to "Site Settings → Email Configuration"
  • Initial Values: Default values are used from siteDefaults.ts during seeding
  • Runtime Updates: Changes take effect immediately without restarting the application

Required email settings:

  • Support Email: Reply-to address for system emails
  • Support Email Name: Display name in email headers
  • Resend Domain: Your verified domain for sending emails
  • Site URL: Base URL for email links

3. Configure Stripe Webhook

Set up a webhook endpoint in the Stripe Dashboard:

  1. Go to Stripe Dashboard > Developers > Webhooks
  2. Click "Add endpoint"
  3. Set the URL to your Convex site URL: https://your-project.convex.site/stripe/webhook
  4. Select all events and click "Add endpoint"
  5. Copy the Signing Secret and set it in Convex: 
    npx convex env set STRIPE_WEBHOOK_SECRET whsec_...

4. Seed Database (Optional)

Add sample data for development:

# Complete seeding with init + assets (includes products, teams, etc.)
pnpm run convex:seed

# Or run individually:
pnpm run convex:seed:init     # Initialize basic seed data only
pnpm run convex:seed:assets   # Upload seed assets only

Quick Commands Reference

Setup & Configuration

pnpm run setup            # Interactive setup wizard (recommended for first-time setup)
pnpm run convex:reset     # Reset Convex deployment (use with caution)

Development

pnpm dev              # Start both frontend (localhost:3001) and Convex backend
pnpm dev:frontend     # Next.js only with Turbopack
pnpm dev:backend      # Convex backend only

Code Quality - MUST pass before completing any task

pnpm lint             # ESLint check - MUST pass
pnpm typecheck        # TypeScript check - MUST pass
# Note: pnpm build is handled by deployment - not needed during development

Database Operations

pnpm run convex:seed         # Complete seeding with init + assets
pnpm run convex:seed:init    # Initialize basic seed data only
pnpm run convex:seed:assets  # Upload seed assets only
npx convex dashboard    # Open Convex admin dashboard

External Services

pnpm dev:email        # Open Resend dashboard

Verification Steps

  1. Frontend Access: Visit http://localhost:3001 - should show landing page
  2. Authentication: Try creating an account or signing in
  3. Database Connection: Check Convex dashboard shows tables
  4. Webhook Testing: Test Stripe webhook forwarding works
  5. Email System: Try password reset or team invitation flows

Next Steps

Once you have the application running:

  1. Review Features: Check out features documentation to understand capabilities
  2. Configure Services: Set up Stripe and Email systems
  3. Read Architecture: Understanding the technical architecture
  4. Development Workflow: Learn the development process

Need Help?

← Back to README

TinyKit SaaS

Production-ready SaaS template with Next.js, Convex, Better Auth, and Stripe

Authentication System

Next Page

On this page

Quick Start (60 seconds)PrerequisitesInstallation1. Clone and Install2. Run Setup Wizard (Recommended)3. Configure Additional Features4. Manual Configuration (Alternative)5. Start Development ServerInitial Setup Tasks1. Set Up Convex Environment Variables2. Configure Email Settings (Database-Driven)3. Configure Stripe Webhook4. Seed Database (Optional)Quick Commands ReferenceSetup & ConfigurationDevelopmentCode Quality - MUST pass before completing any taskDatabase OperationsExternal ServicesVerification StepsNext StepsNeed Help?

Ship your startup faster. In minutes.

Get TinyKit SaaS