Modern Full-Stack Boilerplate

This project provides a solid foundation for building modern web applications using a curated stack of technologies focused on developer experience, performance, and type safety.

Core Technologies

• Framework:TanStack Start on Vite + Vinxi (Modern React foundation with SSR)
• Routing:TanStack Router (Type-safe client and server routing)
• API:tRPC (End-to-end typesafe APIs)
• Database:Drizzle ORM (Type-safe SQL with PostgreSQL, Neon ready)
• UI:React 19, Tailwind CSS, shadcn/ui, Lucide Icons
• State Management:TanStack Query (Server State), TanStack Store (Client State)
• Forms:React Hook Form, TanStack Form, Zod (Validation)
• Authentication:Better Auth (Details below)
• Email:Resend, React Email (Transactional emails)
• Monitoring:Sentry (Error tracking and performance monitoring)
• Testing:Vitest (Unit/Integration testing)
• Tooling & DX:Biome (Linting/Formatting), T3 Env, TypeScript
• AI:@ai-sdk/react, ai (Ready for AI features)
• i18n:i18next (Internationalization)

AI Features

The boilerplate includes several AI-powered chat features and file handling capabilities:

• Basic Chat: Simple streaming chat interface powered by OpenAI's GPT-4o.
• Image Generation: AI-based image generation within chat using the AI SDK.
• RAG (Retrieval Augmented Generation): Chat with context from your knowledge base:
  • Upload documents to be processed into embeddings
  • AI responses enhanced with information retrieved from your documents
  • Knowledge base searching before answering questions
• File Upload: PDF document processing for knowledge base:
  • Drag-and-drop interface with progress indicators
  • PDF text extraction and embedding generation
  • Uses tRPC v11's FormData and non-JSON content type support

The implementation leverages tRPC v11's support for FormData and various content types, making it easy to handle file uploads directly through your type-safe API without additional libraries.

Included Features

Robust Authentication

Powered by Better Auth, providing secure user management features out-of-the-box:

• Core: Sign Up, Sign In, Password Reset Flow (Forgot/Reset).
• Security: Two-Factor Authentication (OTP).
• User Management: Invitation Acceptance Flow.
• Documentation: API reference available at http://localhost:3000/api/auth/reference when running the application.
• (See TODO list for planned additions like Passkey, Admin Dashboard, Org Support)

Development Experience

• Hot Module Replacement (HMR): Fast development cycles with Vite.
• Type Safety: End-to-end type safety from database to frontend.
• Code Quality: Integrated linting and formatting with Biome.
• Environment Variables: Type-safe env management with T3 Env.

Getting Started

1. Install Bun: If you don't have Bun installed, you can install it using:

   # For macOS, Linux, and WSL
   curl -fsSL https://bun.sh/install | bash
   # For Windows (via PowerShell)
   powershell -c "irm bun.sh/install.ps1 | iex"# Verify installation
   bun --version

2. Clone the repository:

   git clone <repository-url>cd<repository-name>

3. Install dependencies:

   bun install

4. Set up environment variables: Copy the .env.example file to .env and configure the required values:

   cp .env.example .env

   Key environment variables to configure:

   • Database: Set up a free Neon Postgres database

     • Sign up at Neon.tech
     • Create a new project
     • Get your connection string from the dashboard
     • Set DATABASE_URL in your .env file:

       DATABASE_URL=postgresql://[user]:[password]@[endpoint]/[database]
       

   • Auth: Generate a secure secret for Better Auth

     # Generate a secure random string
     openssl rand -base64 32

     Add it to your .env file as BETTER_AUTH_SECRET

   • Email: Set up a Resend account for email sending

     • Get your API key and add it as RESEND_API_KEY

   • Monitoring (optional): Configure Sentry for error tracking

     • Get your DSN, organization, and project values from your Sentry dashboard
     • Set the corresponding environment variables

5. Database Setup: Ensure your PostgreSQL database is running and accessible. Push the schema (for development/initial setup):

   bun run db:push

   For production or more controlled migrations, generate migration files:

   # bun run db:generate# Apply migrations (tool/command depends on setup)

   Optional: Use bun run db:studio to explore the schema via Drizzle Studio.

6. Run the development server:

   bun run dev

   The application should now be running on http://localhost:3000.

Project Structure

This project follows a structured organization pattern for better maintainability:

src/
├─ app/ # App specific files
├─ components/ # Reusable UI components (including shadcn/ui)
├─ features/ # Feature-specific components and logic
│ ├─ ai-embedding.ts # Vector embedding generation for RAG functionality
│ ├─ resource-create.ts # Knowledge base resource creation
│ ├─ file-upload.schema.ts # File upload validation schemas
│ ├─ auth/ # Authentication related features
│ └─ organization/ # Organization management features
├─ hooks/ # Custom React hooks
├─ lib/ # Core libraries and utilities
│ ├─ auth/ # Better Auth implementation
│ ├─ db/ # Drizzle ORM setup and schema
│ ├─ intl/ # i18next internationalization setup
│ ├─ trpc/ # tRPC client and server setup
│ ├─ env.client.ts # Type-safe client environment variables (T3 Env)
│ ├─ env.server.ts # Type-safe server environment variables
│ └─ resend.ts # Email sending with Resend and React Email
├─ routes/ # TanStack Router routes with file-based routing
│ ├─ (auth)/ # Authentication related routes (protected)
│ ├─ (public)/ # Public facing routes
│ ├─ api/ # API routes
│ │ ├─ ai/ # AI-related API endpoints │ │ │ ├─ chat.ts # Basic chat API
│ │ │ ├─ chat.rag.ts # RAG-enhanced chat API
│ │ │ └─ chat.image.generation.ts # Image generation chat API
│ ├─ dashboard/ # Dashboard related routes
│ │ ├─ chat/ # Chat interface routes
│ └─ _root.tsx # Root layout component
├─ server/ # Server-side code
│ ├─ router.ts # Main API router setup
│ └─ routes/ # Server-side route handlers
├─ api.ts # API client export
├─ client.tsx # Client entry point
├─ router.tsx # Router configuration
└─ ssr.tsx # Server-side rendering setup
public/ # Static assets

The structure organizes code by feature and responsibility, keeping related code together for better maintainability.

Available Scripts

• bun run dev: Starts the development server.
• bun run build: Builds the application for production.
• bun run start: Starts the production server (requires build first).
• bun run serve: Serves the built production app locally (via Vite preview).
• bun run test: Runs tests using Vitest.
• bun run db:generate: Generates Drizzle ORM migration files.
• bun run db:push: Pushes the current Drizzle schema to the database.
• bun run db:studio: Opens Drizzle Kit Studio.
• bun run add-ui-components <component-name>: Adds shadcn/ui components.
• bun run format: Formats code using Biome.
• bun run lint: Lints code using Biome.
• bun run check: Runs Biome check (format, lint, safety).

TODO List & Potential Improvements

• Implement Planned Auth Features:
  • Passkey Support
  • Admin Dashboard (User Management UI)
  • Organization Support (Multi-tenancy/Teams)
• Refactor Auth Hooks: Ensure auth logic (e.g., useSession) is cleanly extracted into custom hooks.
• Standardize Form Usage: Document preferred approach (React Hook Form vs. TanStack Form) or consolidate.
• Database Seeding: Create scripts for populating development/testing data.
• Advanced RBAC: Implement fine-grained Role-Based Access Control if needed.
• Performance Optimization: Bundle analysis, code splitting, image optimization.
• i18n Management: Add Internationalization (translation platform integration).
• AI SDK Examples: Add examples using @ai-sdk/react.
• Email Templates: Add more examples/implementations using react-email.
• Sentry Configuration: Add details on advanced Sentry setup (sourcemaps, user identification).
• Theme Toggle: Implement UI for switching between light/dark themes (uses next-themes).
• CI/CD: Set up a basic CI/CD pipeline (e.g., GitHub Actions for linting, testing, building).
• Deployment Guides: Add specific guides (Vercel, Docker, etc.).