React Starter Kit

Appearance

23k4.2k

Getting Started ​

Welcome to React Starter Kit — your shortcut to building modern web apps without the usual setup headaches. This guide will get you from zero to hero faster than you can say "webpack configuration" (which, thankfully, you won't have to).

Quick Start

Just want to dive in? Run these commands and you're good to go:

bash
git clone -o seed -b main --single-branch \
  https://github.com/kriasoft/react-starter-kit.git my-app
cd my-app && bun install && bun dev

Prerequisites ​

Before diving in, make sure you have these essentials:

  • Bun 1.3.0+ (install here) — trust us, it's worth it
  • A Cloudflare account for deployment (free tier works great)
  • Your favorite code editor (VS Code recommended, but we won't judge)

Node.js Optional

While many developers have Node.js installed, this template runs entirely on Bun. You don't need Node.js unless you're integrating with Node-specific tools.

Create Your Project ​

You've got two paths to choose from. Pick your adventure:

Option 1: GitHub Template (The Quick Way) ​

Perfect if you want to get started immediately and keep your project cleanly separated:

  1. Navigate to github.com/kriasoft/react-starter-kit
  2. Click the green "Use this template" button
  3. Choose "Create a new repository"
  4. Name your project (avoid "my-awesome-app" — be creative!)
  5. Clone your new repository:
bash
git clone https://github.com/YOUR_USERNAME/YOUR_PROJECT.git
cd YOUR_PROJECT
bun install

TIP

This method creates a clean repository history without the template's commit history.

Option 2: Git Clone (The Smart Way) ​

This approach lets you pull updates from the template later  because who doesn't love staying current?

bash
# Clone the template with a custom remote name
git clone -o seed -b main --single-branch \
  https://github.com/kriasoft/react-starter-kit.git my-app

# Jump into your project
cd my-app

# Install dependencies (Bun makes this blazing fast)
bun install

The magic here is naming the remote "seed" instead of "origin". This way, you can add your own repository as "origin" later while keeping the template connection alive:

bash
# Add your own repository as origin
git remote add origin https://github.com/YOUR_USERNAME/YOUR_PROJECT.git
git push -u origin main

# Later, when you want template updates
git fetch seed
git merge seed/main

WARNING

Be careful when merging template updates — always review changes and test thoroughly before deploying.

Project Structure ​

Once you're set up, here's what you're working with:

bash
my-app/
├── apps/
│   ├── app/      # React 19 frontend with TanStack Router
│   ├── web/      # Astro static site (landing/marketing)
│   ├── api/      # tRPC backend (type-safe goodness)
│   └── email/    # React Email templates (authentication & transactional)
├── packages/
│   ├── core/     # Shared modules and utilities
│   ├── ui/       # Shared UI components (shadcn/ui)
│   └── ws-protocol/ # WebSocket protocol template
├── db/           # Database schemas and migrations
├── infra/        # Terraform infrastructure configuration
├── docs/         # Documentation (you are here!)
├── scripts/      # Build and utility scripts
└── package.json  # Monorepo root

First Steps ​

1. Start Development Server ​

Fire up the full development environment:

bash
bun dev  # Starts web + api + app concurrently

This starts:

  • App dev server at http://localhost:5173 (React app)
  • API server at http://localhost:8787 (tRPC with hot reload)
  • Web dev server at http://localhost:4321 (Astro marketing site)

You can also start individual services:

bash
bun app:dev    # React app only
bun api:dev    # API server only
bun web:dev    # Marketing site only
bun email:dev  # Email preview server at http://localhost:3001
What's happening under the hood?

Each command starts its specific development server:

  • app:dev: Vite dev server for the React app with HMR
  • api:dev: Wrangler dev server for the tRPC API with file watching
  • email:dev: React Email preview server for template development
  • web:dev: Astro dev server for the marketing site

2. Explore the Stack ​

Open your browser and check out:

  • App: http://localhost:5173 — Your React app with TanStack Router
  • API: http://localhost:8787 — tRPC API endpoints
  • Database GUI: Run bun db:studio to explore your database
  • Email Templates: Run bun email:dev for preview at http://localhost:3001

3. Make It Yours ​

Time to customize:

  1. Update branding → Edit apps/app/index.html with your app's title
  2. Homepage content → Modify apps/app/routes/index.tsx
  3. API endpoints → Check out apps/api/routers/ for tRPC routes
  4. Data models → Explore db/schema/ for database structure

Database Setup ​

The template uses Neon PostgreSQL with Drizzle ORM (referral link). To set up your database:

bash
# Generate the initial schema
bun db:generate

# Apply migrations to your local database
bun db:push

# (Optional) Seed with sample data
bun db:seed

Database GUI

Want to explore your data visually? Run bun db:studio to open Drizzle Studio in your browser.

Authentication ​

Better Auth is pre-configured with multiple authentication methods:

  • Email OTP - One-time passwords via email (6 digits, 5-min expiry)
  • Email/Password - Traditional authentication with password reset
  • Passkeys - WebAuthn biometric authentication
  • Google OAuth - Social login via Google
  • Anonymous - Guest access that can be upgraded later
  • Organizations - Multi-tenant workspaces with roles

Configuration ​

  1. Create environment file → Create .env.local (excluded from Git)
  2. Add OAuth credentials → Google (and other providers you add)
  3. Configure email → Set up Resend for email delivery
  4. Client setup → Check apps/app/lib/auth.ts
  5. Server config → See apps/api/lib/auth.ts
Example .env.local
bash
# OAuth Providers
GOOGLE_CLIENT_ID="your-google-client-id"
GOOGLE_CLIENT_SECRET="your-google-client-secret"

# Email Service (Resend)
RESEND_API_KEY="re_xxxxxxxxxx"
RESEND_EMAIL_FROM="Your App <[email protected]>"

# Auth Secret (generate with: openssl rand -hex 32)
BETTER_AUTH_SECRET="your-random-secret-here"

Email Templates ​

The template includes React Email templates for authentication:

bash
# Preview email templates
bun email:dev

# Build for production
bun email:build

# Export static HTML
bun email:export

UI Components Management ​

The template includes powerful shadcn/ui component management utilities:

bash
# Add specific components
bun run ui:add button dialog

# Install essential components (37 pre-selected)
bun run ui:essentials

# List installed components
bun run ui:list

# Update components to latest versions
bun run ui:update

Quick Setup

Running bun run ui:essentials gives you 37 carefully selected components that cover 90% of typical UI needs — forms, layout, navigation, and feedback components.

For detailed component management documentation, see the UI Components Guide.

Development Workflow ​

Here's your daily routine:

bash
# Start development (all services concurrently)
bun dev

# Run tests
bun test

# Lint your code
bun lint

# Type check
bun typecheck

# Build for production (order matters)
bun build  # Builds email → web → api → app

Type Checking

TypeScript checking happens automatically in your editor. For CI/CD, run bun typecheck (which runs tsc --build).

💡 Hot Tips for Development ​

  • API Types: After modifying tRPC routes, types auto-generate — no manual sync needed
  • Database Changes: Edit db/schema/, then run bun db:generate and bun db:push
  • Component Library: shadcn/ui components are ready to use — check packages/ui/components
  • UI Components: Add new components with bun run ui:add <component> or install essentials with bun run ui:essentials
  • State Management: Global state lives in apps/app/lib/store.ts using Jotai

Deploy to Production ​

Ready to ship? Let's deploy to Cloudflare Workers:

bash
# First, login to Cloudflare
bun wrangler login

# Build all packages (order matters)
bun build  # email → web → api → app

# Deploy applications
bun web:deploy    # Deploy marketing site
bun api:deploy    # Deploy API server
bun app:deploy    # Deploy React app

Environment Configuration

The project includes multiple environments (development, preview, production). Always specify --env=production for production deployments.

Your app will be live at https://your-app.workers.dev in seconds. Yes, really.

⚠️ Common Gotchas ​

Environment Variables

Remember to set them in Cloudflare dashboard for production — local .env files are NOT deployed!

Database Migrations

Production uses Neon PostgreSQL — ensure your production database is configured:

bash
# Apply migrations to production
bun db:migrate:prod

API Routes

All API calls go through /api/trpc — the client handles this automatically. No need to configure endpoints.

Build Errors

If TypeScript complains, try bun typecheck to see all type errors across the monorepo.

Next Steps ​

Now that you're up and running:

  1. Browse the example components for inspiration
  2. Check out the deployment guide for advanced Cloudflare setup
  3. Join our Discord community for help and updates

Remember: This template is intentionally minimal. It's not trying to be everything to everyone — it's a solid foundation that respects your ability to make architectural decisions. Build something amazing!

🆘 Need Help? ​

Community Support

Happy coding! 🚀

Released under the MIT License.

Copyright © 2014-present Kriasoft