Getting Started

Overview

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/threatmatic/netra.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

Title

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:

Title

Reference: The Ultimate Guide to Organizing Your Next.js Project Structure

Monorepo

my-app/
├── apps/
│   ├── web/      # (Next.js app structure)
│   └── admin/    # (Next.js app structure)
│   ├── api/      # tRPC backend (type-safe goodness)
│   └── edge/     # Cloudflare Workers entry point
├── packages/
│   ├── ui/
│   ├── config/
│   └── utils/    # Shared modules and utilities
├── db/           # Database schemas and migrations
├── infra/        # Terraform infrastructure configuration
├── docs/         # Documentation (you are here!)
└── package.json  # Monorepo root

apps/web -> The src Directory

├── src/
│   ├── app/
│   ├── components/
│   ├── lib/
│   ├── stores/
│   ├── models/
│   └── styles/
├── public/
├── package.json
└── next.config.js

The app Directory

src/app/
├── layout.tsx
├── page.tsx
├── (auth)/
│   ├── login/
│   └── register/
├── dashboard/
│   ├── layout.tsx
│   ├── page.tsx
│   └── settings/
└── api/

Organizing Components

src/components/
├── ui/
│   ├── Button/
│   │   ├── Button.tsx
│   │   ├── Button.test.tsx
│   │   └── index.ts
│   ├── Card/
│   └── Modal/
├── layout/
│   ├── Header/
│   ├── Footer/
│   └── Sidebar/
└── features/
    ├── auth/
    └── dashboard/

Managing Utilities and Libraries

src/
├── utils/
│   ├── formatting.ts
│   ├── validation.ts
│   └── helpers.ts
└── lib/
    ├── auth.ts
    ├── api.ts
    └── database.ts

State Management and Models

src/
├── store/
│   ├── auth.store.ts
│   ├── user.store.ts
│   └── theme.store.ts
└── models/
    ├── user.model.ts
    └── product.model.ts

Styling Organization

src/
├── styles/
│   ├── global.css
│   ├── variables.css
│   └── themes/
│       ├── light.css
│       └── dark.css
└── components/
    └── Button/
        ├── Button.tsx
        └── Button.module.css

First Steps

Start Development Server

Fire up the development environment:

bun dev

This starts:

🚀 Frontend dev server at http://localhost:5173
🔥 API server with hot reload
💾 Database connection (local SQLite)

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)

Explore the Stack

Open your browser and check out:

Frontend: http://localhost:5173 — Your React app with TanStack Router
Database GUI: Run bun --filter @repo/db studio to explore your database

Make It Yours

Time to customize:

Update branding → Edit apps/web/index.html with your app's title
Homepage content → Modify apps/web/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 Cloudflare D1 (SQLite) 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"

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 run bun --filter @repo/db generate and push
Component Library: ShadCN UI components are ready to use — check apps/web/components/ui
State Management: Global state lives in apps/web/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 --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 --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

Happy coding! 🚀

On this page