Setup Wizard Guide

The TinyKit Pro setup wizard provides an ultra-minimal, streamlined setup experience that gets you from git clone to bun dev in under 60 seconds. Additional configuration is done via the Admin panel after initial setup.

Overview

Quick Start (60 seconds)

git clone https://github.com/your-repo/tinykit-pro-convex
cd tinykit-pro-convex
bun install
bun setup     # Interactive setup + browser login
bun dev       # You're running!

Note: bun dev starts the frontend and Convex backend without Stripe. This is intentional - most development doesn't require billing features. When you're ready to test subscriptions, use bun dev:full (requires Stripe CLI setup).

Philosophy: Smart Defaults

The setup wizard uses smart defaults so you can start building immediately:

Everything can be customized later - the goal is to get you developing as fast as possible.

Prerequisites

Required:

• Node.js 22+ and bun (recommended)
• Git (for cloning)

Optional (configure later):

• Convex account (free tier) - created during setup
• Stripe for billing
• Resend for emails
• OAuth accounts (GitHub, Google)

Running the Setup Wizard

Main Setup (Recommended)

bun setup        # With bun (recommended)
# OR
npm run setup    # With npm
yarn setup       # With yarn
pnpm setup       # With pnpm

Step-by-Step Process

1. Welcome & Confirmation

The wizard shows a professional welcome banner and asks one question:

🚀 Quick Start Setup

This wizard will set up your TinyKit Pro template with smart defaults.
You can customize everything later in Admin > Site Settings.

? Ready to start? › (Y/n)

2. Convex Setup (Browser Login)

If Convex isn't already configured:

• Opens browser for Convex authentication
• Creates new deployment automatically
• Configures all necessary environment variables

3. Smart Defaults Applied

The wizard automatically:

• Generates .env.local with Convex configuration
• Syncs environment variables to Convex backend
• Sets BETTER_AUTH_SECRET and API webhook secrets

4. Database Initialization

Choose your mode:

• Development mode (recommended): Sample users, organizations, and content
• Production mode: Clean setup, first user becomes admin
• Skip: Initialize manually later with bun convex:seed

5. Completion

Shows next steps and a setup checklist for features that need additional configuration.

Admin Setup Banner

After signing in as admin, you'll see a setup banner if configuration is incomplete:

┌─────────────────────────────────────────────────────────┐
│ ⚙️  Complete Your Setup                                  │
│                                                         │
│ Your TinyKit is running but some features need config:  │
│                                                         │
│ ○ Site Settings - Configure domain, name, support email │
│ ○ Authentication - Add OAuth providers (GitHub, Google) │
│ ○ Billing - Connect Stripe for subscriptions            │
│ ○ Email - Connect Resend for transactional emails       │
│                                                         │
│ [Configure Now]                               [Dismiss] │
└─────────────────────────────────────────────────────────┘

Each item links to the appropriate settings page or documentation.

Additional Commands

Guided Credentials Setup

For interactive configuration of external services:

bun setup:credentials           # All services
bun setup:credentials --oauth   # Just OAuth providers
bun setup:credentials --stripe  # Just Stripe
bun setup:credentials --email   # Just Resend
bun setup:credentials --analytics # Just PostHog

Database Seeding

bun convex:seed         # Full seed (users, orgs, assets)
bun convex:seed:init    # Just database initialization
bun convex:seed:assets  # Just sample images

Reset Convex

Start fresh with a new deployment:

bun convex:reset

⚠️ Warning: This destroys all existing data.

Manual Configuration Alternative

If you prefer manual setup:

cp .env.local.example .env.local
# Edit .env.local manually
npx convex dev
# Configure Convex environment variables manually

See Environment Variables Reference for complete configuration.

Configuration Reference

For complete environment variable documentation, see Environment Variables Reference.

Smart Defaults

These defaults are applied automatically:

Site URL: http://localhost:3000
Site Domain: localhost
Site Name: TinyKit
Support Email: support@localhost
Auth Methods: Password (email/password)
Billing: Disabled
Analytics: Disabled

Environment Variables

Frontend (.env.local):

NEXT_PUBLIC_SITE_URL=http://localhost:3000
SITE_DOMAIN=localhost
CONVEX_DEPLOYMENT=dev:your-project
NEXT_PUBLIC_CONVEX_URL=https://your-project.convex.cloud
NEXT_PUBLIC_CONVEX_SITE_URL=https://your-project.convex.site

Backend (Convex environment):

SITE_URL=http://localhost:3000
BETTER_AUTH_SECRET=<auto-generated>
API_WHSEC=<auto-generated>
CONVEX_ENV=development

# Added when configured:
RESEND_API_KEY=re_...
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOKS_SECRET=whsec_...
GITHUB_CLIENT_ID=...
GITHUB_CLIENT_SECRET=...
GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...

Troubleshooting

Common Issues

"Dependencies not installed"

• Run bun install first
• Supports auto-detection of bun, npm, pnpm, yarn

"Convex initialization not detected"

• Run bun setup again - it will detect existing deployment
• Or manually run npx convex dev first

"Setup cancelled"

• Press Ctrl+C anytime to safely exit
• Safe to restart - existing config is preserved

"Failed to set environment variables"

• Check Convex authentication: npx convex auth
• Verify deployment is active

Getting Help

1. Check the troubleshooting guide
2. Verify prerequisites are met
3. Join the Convex Discord

Migration from Previous Setup

If you have an existing TinyKit Pro installation:

1. Your existing .env.local is preserved (wizard asks before overwriting)
2. Run bun setup:credentials to add any new services
3. The admin banner shows what's still unconfigured

Best Practices

Development Workflow

1. Run bun setup once to initialize
2. Start developing immediately with bun dev
3. Configure additional services as needed via admin panel
4. Use bun setup:credentials for guided service configuration
5. When testing billing features, use bun dev:full (requires Stripe CLI)

Development Commands

Production Deployment

1. Re-run setup with production URLs
2. Configure all services (Stripe, Resend, OAuth)
3. Update OAuth callback URLs
4. Test all integrations before go-live

The streamlined setup wizard is designed to get you developing as fast as possible. All configuration can be done later through the admin panel or bun setup:credentials.