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:
git clone -o seed -b master --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.2.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:
- Navigate to github.com/kriasoft/react-starter-kit
- Click the green "Use this template" button
- Choose "Create a new repository"
- Name your project (avoid "my-awesome-app" — be creative!)
- Clone your new repository:
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?
# Clone the template with a custom remote name
git clone -o seed -b master --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:
# Add your own repository as origin
git remote add origin https://github.com/YOUR_USERNAME/YOUR_PROJECT.git
git push -u origin master
# Later, when you want template updates
git fetch seed
git merge seed/master
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:
my-app/
├── apps/
│ ├── app/ # React 19 frontend with TanStack Router
│ ├── web/ # Astro static site (landing/marketing)
│ ├── api/ # tRPC backend (type-safe goodness)
│ └── edge/ # Cloudflare Workers entry point
├── 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 development environment:
bun dev
This starts:
- 🚀 App dev server at
http://localhost:5173
(React app) - 🌐 Web dev server for Astro static site (when running
bun --filter @repo/web dev
) - 🔥 API server with hot reload
- 💾 Database connection (Neon PostgreSQL)
What's happening under the hood?
The bun dev
command runs multiple processes concurrently:
- Vite dev server for the React app
- tRPC API server with file watching
- TypeScript compiler in watch mode
- Database migrations (if needed)
2. Explore the Stack
Open your browser and check out:
- App:
http://localhost:5173
— Your React app with TanStack Router - Database GUI: Run
bun --filter @repo/db studio
to explore your database - Astro Site: Run
bun --filter @repo/web dev
separately for the static site
3. Make It Yours
Time to customize:
- Update branding → Edit
apps/app/index.html
with your app's title - Homepage content → Modify
apps/app/routes/index.tsx
- API endpoints → Check out
apps/api/routers/
for tRPC routes - Data models → Explore
db/schema/
for database structure
Database Setup
The template uses Neon PostgreSQL with Drizzle ORM. To set up your database:
# Generate the initial schema
bun --filter @repo/db generate
# Apply migrations to your local database
bun --filter @repo/db push
# (Optional) Seed with sample data
bun --filter @repo/db seed
Database GUI
Want to explore your data visually? Run bun --filter @repo/db studio
to open Drizzle Studio in your browser.
Authentication
Better Auth is pre-configured but needs your touch:
- Create environment file → Create
.env.local
(excluded from Git) - Add OAuth credentials → Google, GitHub, etc.
- Client setup → Check
apps/web/lib/auth.ts
- Server config → See
apps/api/lib/auth.ts
Example .env.local
# OAuth Providers
GOOGLE_CLIENT_ID="your-google-client-id"
GOOGLE_CLIENT_SECRET="your-google-client-secret"
GITHUB_CLIENT_ID="your-github-client-id"
GITHUB_CLIENT_SECRET="your-github-client-secret"
# Auth Secret (generate with: openssl rand -hex 32)
AUTH_SECRET="your-random-secret-here"
UI Components Management
The template includes powerful shadcn/ui component management utilities:
# 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:
# Start everything
bun dev
# Run tests (yes, we have tests!)
bun test
# Lint your code (keep it clean)
bun lint
Type Checking
TypeScript checking happens automatically in your editor. For CI/CD, run bun --filter @repo/api build
to verify types.
💡 Hot Tips for Development
- API Types: After modifying tRPC routes, types auto-generate — no manual sync needed
- Database Changes: Edit
db/schema/
, then runbun --filter @repo/db generate
andpush
- 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 withbun 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:
# First, login to Cloudflare
bun wrangler login
# Deploy to production
bun wrangler deploy --config apps/edge/wrangler.jsonc --env=production
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 Cloudflare D1 — you must run migrations there separately:
bun wrangler d1 migrations apply YOUR_DATABASE --config apps/edge/wrangler.jsonc --env=production
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 --filter @repo/api build
first. This regenerates type definitions.
Next Steps
Now that you're up and running:
- Browse the example components for inspiration
- Check out the deployment guide for advanced Cloudflare setup
- 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
- 💬 GitHub Discussions
- 🐛 Report Issues
- ⭐ Star us on GitHub (it helps!)
Happy coding! 🚀