Introduction

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

Quick Start (60 seconds)

git clone <your-repo-url>
cd tinykit-pro-convex
bun install
bun setup     # Interactive setup + browser login
bun 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 bun setup:credentials.

Prerequisites

Required:

• Node.js 22+ and bun (install from bun.sh)

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-pro-convex
bun install

2. Run Setup Wizard (Recommended)

bun 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:3000
• 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

bun setup:credentials           # All services
bun setup:credentials --oauth   # Just OAuth providers
bun setup:credentials --stripe  # Just Stripe
bun 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
bun dev:frontend  # In another terminal, starts Next.js frontend

Note: npx convex dev only starts the Convex backend. Use bun dev to start both frontend and backend together, or run them separately with bun dev:backend and bun 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

bun dev

This will start:

• Next.js frontend on http://localhost:3000
• Convex backend (automatically configured)
• Stripe webhook forwarding (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_WEBHOOKS_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 webhook forwarding for local development:

# In a separate terminal (keeps webhook forwarding active)
bun dev:stripe

# Copy the webhook signing secret to Convex environment
npx convex env set STRIPE_WEBHOOKS_SECRET whsec_...

4. Seed Database (Optional)

Add sample data for development:

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

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

Quick Commands Reference

Setup & Configuration

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

Development

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

Code Quality - MUST pass before completing any task

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

Database Operations

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

External Services

bun dev:stripe       # Forward Stripe webhooks to Convex
bun email:dev        # Open Resend dashboard

Verification Steps

1. Frontend Access: Visit http://localhost:3000 - 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

Why Bun?

This project uses Bun specifically for Claude Code integration:

Claude Code Benefits:

• 🔍 Real-time Console Visibility: Console.logs and errors appear directly in terminal
• 🎨 Color-coded Output: Frontend logs in cyan, backend in yellow with clear prefixes
• ⚡ Faster Development: Superior performance for installs and updates
• 🛠️ Better Error Tracking: All JavaScript errors immediately visible to Claude Code
• 🔄 Live Development Feedback: Real-time application behavior visibility

Performance Benefits:

• 📦 Lightning Fast Installs: 2-3x faster than npm/yarn/pnpm
• 🚀 Quick Script Execution: Faster script execution for development tasks
• 💾 Efficient Caching: Smart caching reduces repeated work
• 🔗 Native TypeScript: Built-in TypeScript support

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?

• Troubleshooting: Check troubleshooting.md for common issues
• API Reference: Review api-reference.md for development patterns
• Community Support: Join the Convex Discord

← Back to README