DOCSEARCHbyAlgolia
Submit Docs

Kriasoft React Starter Kit

repository·main·Indexed 12 days ago

https://github.com/kriasoft/react-starter-kit

A full-stack monorepo template for building SaaS applications using React 19, tRPC, and Cloudflare Workers. It features a type-safe environment from the database to the UI, utilizing Hono, Better Auth, Drizzle ORM, Stripe, TanStack Router, and TanStack Query. The kit includes an Astro-based Edge Router for traffic management and React Email for transactional templates.

Tokens
102.8K
Snippets
293
Records
426
Agent score
97%

What's inside React Starter Kit

  1. Overview of React Starter Kit features

    main

    React Starter Kit is a production-ready monorepo designed for building AI-powered SaaS applications. It provides a pre-configured stack including:

    • AI-First Development: Pre-built LLM instructions and tool configurations for Claude Code, Cursor, and Gemini CLI.
    • Edge-First Architecture: Optimized for Cloudflare Workers with global distribution.
    • Modern React Stack: React 19, Vite, Astro, TanStack Router, Jotai state management, and shadcn/ui with Tailwind CSS v4.
    • Auth + Billing: Integrated 'Better Auth' (supporting social providers, passkeys, and organizations) and Stripe subscriptions via hosted checkout.
    • Multi-Tenant Database: Neon PostgreSQL with Drizzle ORM, featuring a pre-built multi-tenant schema with organizations and type-safe migrations.
    • High-Performance Tooling: Uses the Bun runtime for fast builds, hot reloading, and unified tooling.

  2. Overview of the @repo/core package

    main
    The @repo/core package serves as a centralized repository for shared utilities and helper functions used across the entire monorepo. It is designed to provide common logic that is consumed by other packages like @repo/api, @repo/app, and @repo/web to ensure consistency and reduce duplication.

  5. Understand the React Application structure

    main

    The React application is a single-page application (SPA) built with React 19, TanStack Router, Jotai, shadcn/ui, and Tailwind CSS v4. The project follows this directory structure:

    • routes/: Contains file-based routes managed by TanStack Router.
    • components/: Contains shared application components.
    • lib/: Contains the Auth client, tRPC client, Jotai atoms, and other utilities.
    • styles/: Contains global CSS and theme variables.

    Note: The route tree is automatically generated in lib/routeTree.gen.ts. Do not edit this file manually.

  6. Understand the React Starter Kit project structure

    main

    The project is organized as a Bun monorepo containing four distinct applications, shared packages, a database workspace, and infrastructure configuration.

    Applications

    • apps/web: Edge router (Cloudflare Worker) and Astro marketing site. It routes /api/* to the API worker and app routes to the app worker using service bindings. It uses an auth hint cookie to determine whether to serve the landing page or the application.
    • apps/app: React 19 Single-Page Application (SPA) built with Vite. It uses TanStack Router (file-based routing in apps/app/routes/), TanStack Query, Jotai, and shadcn/ui.
    • apps/api: API Server (Cloudflare Worker) using Hono for HTTP routing and tRPC for type-safe RPC. It manages authentication (Better Auth), database queries (Drizzle ORM via Hyperdrive), and Stripe webhooks. Note: This worker has nodejs_compat enabled.
    • apps/email: React Email templates for transactional emails (OTP, invitations). Templates are built before the API dev server starts.

    Shared Packages

    • packages/ui: shadcn/ui component library (new-york style) using Tailwind CSS v4.
    • packages/core: Shared utilities and constants.
    • packages/ws-protocol: WebSocket message protocol template.
    • packages/typescript-config: Shared tsconfig.json presets.

    Database & Infrastructure

    • db/: Drizzle ORM schemas, migrations, and seed scripts targeting Neon PostgreSQL with Cloudflare Hyperdrive.
    • infra/: Terraform configuration for Hyperdrive and R2.
    • scripts/: Build and utility scripts.
    my-app/
├── apps/
│   ├── web/
│   ├── app/
│   ├── api/
│   └── email/
├── packages/
│   ├── ui/
│   ├── core/
│   ├── ws-protocol/
│   └── typescript-config/
├── db/
├── infra/
├── docs/
├── scripts/
└── package.json

  7. Authentication Overview

    main

    Authentication is powered by Better Auth, a TypeScript-native framework running in the API worker. The system supports multiple sign-in methods that all produce a unified session format, allowing users to link multiple methods (e.g., Google OAuth and Passkeys) to a single account.

    Supported Sign-in Methods:

    • Email & OTP: Passwordless 6-digit code via email.
    • Email & Password: Server-side enabled with reset email support (UI for password entry is not included in the starter kit).
    • Google OAuth: Social login via redirect flow.
    • Passkeys: WebAuthn-based biometric or security key authentication.
    • Anonymous: Support for guest sessions.

  8. Overview of the Edge Router

    main

    The Edge Router is an Astro-based edge worker designed to manage incoming traffic. It uses Cloudflare service bindings to route requests to the appropriate backend workers:

    • /api/* requests are routed to the API worker.
    • All other App routes are routed to the App worker.
    • Static assets are served directly from the edge.

  9. How file-based routing works with TanStack Router

    main

    The application uses TanStack Router with a file-based routing system. Routes are defined by creating files within apps/app/routes/. The file path directly determines the URL structure.

    Key Concepts:

    • Route Groups: Directories wrapped in parentheses, like (app) or (auth), act as layout boundaries but are omitted from the URL path. For example, a file at apps/app/routes/(app)/settings.tsx is accessed via /settings.
    • Root Route: The __root.tsx file serves as the base layout, wraps the entire application in an error boundary, and provides the router context (e.g., queryClient).
    • Route Tree Generation: The typed route tree is automatically generated at apps/app/lib/routeTree.gen.ts. Do not edit this file manually; it is updated automatically when running bun app:dev.
    # Example directory structure
apps/app/routes/
├── __root.tsx              # Root layout
├── (auth)/
│   ├── login.tsx           # /login
│   └── signup.tsx          # /signup
└── (app)/
    ├── route.tsx           # Layout for (app) routes
    ├── index.tsx           # / (dashboard)
    └── settings.tsx        # /settings

  10. Understand the @repo/ui package structure

    main

    The @repo/ui package is organized into the following directories:

    • components/: Contains the shadcn/ui components.
    • hooks/: Contains custom React hooks.
    • lib/: Contains utility functions (such as the cn function for class merging).
    • scripts/: Contains tools used for component management.

  11. Configure authentication methods and availability

    main

    The authentication flow supports several methods, which are dynamically enabled based on server configuration via config.socialProviders (derived from Better Auth settings).

    MethodLoginSignupAvailability
    Email OTPYesYesAlways
    PasskeyYesNoExisting accounts only
    GoogleYesYesOnly when both server credentials are configured

    Implementation Note: The UI automatically hides or shows providers based on the server's capabilities. The login dialog prefetches these capabilities on mount to ensure the UI accurately reflects available methods without requiring duplicate client-side flags.

  12. Choose between `ctx.db` and `ctx.dbCached`

    main

    The context provides two distinct database connections to balance data freshness and performance:

    • ctx.db: The default, uncached connection. Use this for any operation where data integrity and immediate consistency are required, such as writes, transactions, authentication, permissions, billing, or reads that must reflect the absolute latest state.
    • ctx.dbCached: An optimized connection that uses Hyperdrive's query cache. This is ideal for high-performance reads where a small amount of staleness (default up to 75 seconds) is acceptable. Use this to reduce latency and database load for non-critical read operations.
    // Read with caching when staleness is acceptable
const users = await ctx.dbCached.select().from(user);

// Writes and fresh reads use the default connection
await ctx.db.insert(post).values({ title: "Hello" });