## BRP Stack: The Ultimate Web Framework You Need **A Modern Approach to Full-Stack Development with Bun, React, and Payload** --- ### Introduction After analyzing countless technologies and balancing trade-offs, I discovered what I believe to be the ultimate web framework stack: **BRP Stack** (Bun + React + Payload). This combination has revolutionized how I build modern web applications, and I want to share why this stack is a game-changer for developers seeking simplicity, performance, and developer experience. In this article, I'll walk you through how I built [Paideia LMS](https://paideialms.com) - a complete Learning Management System - in just 30 days using this stack, and why I believe it's the future of full-stack development. --- ### What is BRP Stack? **BRP Stack** is a powerful combination of three technologies: - **Bun**: A lightning-fast JavaScript runtime, bundler, and package manager all-in-one - **React**: The mature, battle-tested UI library with a massive ecosystem - **Payload**: A headless CMS with local API support, built on Drizzle ORM Together, these technologies create a full-stack framework that handles everything from database migrations to authentication, from server-side rendering to client-side reactivity, all while maintaining type safety from database to frontend. --- ### Why BRP Stack is Game-Changing #### 1. Cross-Platform Single Binary Deployment One of the most compelling features of BRP Stack is the ability to compile your entire application into a single, cross-platform binary. This means: - **One executable** that runs on Windows, macOS, and Linux - **No dependency management** on the deployment server - **Instant deployment** - just send the binary and run it - **Support for multiple architectures** (x86_64, ARM64, etc.) This is a game-changer for deployment. Instead of managing Node.js versions, package installations, and environment configurations, you simply compile once and deploy everywhere. #### 2. Dual Server Architecture BRP Stack uses a dual-server architecture where both backend and frontend run in the same process: - **Backend Server**: Elysia-based API server with OpenAPI integration - **Frontend Server**: React Router with server-side rendering Both servers run simultaneously, sharing the same Payload instance and database connection. This architecture provides: - **Type-safe API calls** using Elysia's Treaty - **Automatic OpenAPI documentation** generation - **Server-side rendering** for SEO and performance - **Client-side reactivity** for interactive UIs #### 3. Type Safety End-to-End Type safety is built into every layer of the stack: - **Database**: Drizzle ORM provides type-safe database queries - **API**: Elysia + Treaty generates type-safe API clients - **Frontend**: React Router with full TypeScript support - **Payload**: Type-safe collections and globals This means you catch errors at compile time, not runtime, and your IDE provides intelligent autocomplete throughout your entire application. #### 4. Built-in Features You'd Otherwise Implement Separately Payload CMS provides an incredible amount of functionality out of the box: ##### Database Management - **Automatic schema generation** using Drizzle ORM - **Database migrations** with up/down functions - **Type-safe queries** with full TypeScript support - **Relationship handling** with depth control ##### Authentication & Authorization - **Built-in authentication** system - **Fine-grained access control** at collection and field levels - **Role-based permissions** with custom access hooks - **Session management** with secure cookies ##### File Storage - **S3 integration** out of the box - **Local file storage** support - **Image optimization** and resizing - **Media management** with metadata ##### Background Jobs - **Job queue** system built-in - **Cron job** support - **Task scheduling** and execution - **Job history** and logging ##### Email Integration - **Multiple email providers** supported (SMTP, Resend, etc.) - **Email templates** and customization - **Email logging** and debugging ##### Search Functionality - **Full-text search** capabilities - **Search indexing** and optimization - **Custom search implementations** All of this is configured in a single `payload.config.ts` file, making it incredibly easy to manage and understand your entire backend. --- ### Technical Deep Dive #### Architecture Overview ``` ┌─────────────────────────────────────────┐ │ Single Binary Executable │ ├─────────────────────────────────────────┤ │ │ │ ┌──────────────┐ ┌──────────────┐ │ │ │ Backend │ │ Frontend │ │ │ │ (Elysia) │ │ (React │ │ │ │ │ │ Router) │ │ │ └──────┬───────┘ └──────┬───────┘ │ │ │ │ │ │ └────────┬────────┘ │ │ │ │ │ ┌────────▼────────┐ │ │ │ Payload Local │ │ │ │ API │ │ │ └────────┬────────┘ │ │ │ │ │ ┌────────▼────────┐ │ │ │ Drizzle ORM │ │ │ └────────┬────────┘ │ │ │ │ │ ┌────────▼────────┐ │ │ │ PostgreSQL │ │ │ └──────────────────┘ │ └─────────────────────────────────────────┘ ``` #### Backend: Elysia Server The backend server is built with Elysia, a fast web framework for Bun: ```typescript const backend = new Elysia() .state("payload", payload) .use(openapi()) .listen(port, () => { console.log(`🚀 Backend running at http://localhost:${port}`); }); ``` **Key Features:** - **OpenAPI integration** for automatic API documentation - **Type-safe routes** with TypeScript inference - **Treaty client** for type-safe API calls - **Plugin system** for extensibility #### Frontend: React Router The frontend uses React Router v7 with server-side rendering: ```typescript const frontend = new Elysia() .use(reactRouter(e, { getLoadContext: ({ request }) => { const c = new RouterContextProvider(); c.set(globalContextKey, { payload: payload, elysia: backend, api, // ... other context }); return c; }, })) .listen(frontendPort, () => { console.log(`🚀 Frontend running at http://localhost:${frontendPort}`); }); ``` **Key Features:** - **Server-side rendering** for initial page load - **Client-side navigation** for smooth UX - **Type-safe loaders and actions** - **Context sharing** between server and client #### Payload Configuration Everything is configured in a single file: ```typescript export default buildConfig({ db: postgresAdapter({ // Database configuration }), collections: [ Users, Courses, Enrollments, // ... 27+ collections ], globals: [ SystemGradeTable, RegistrationSettings, // ... global settings ], email: { // Email configuration }, plugins: [ // Custom plugins ], }); ``` This single configuration file manages: - Database schema - Collections and their relationships - Access control rules - Email settings - Storage configuration - Search implementation - Job queue setup --- ### Real-World Implementation: Paideia LMS I built [Paideia LMS](https://paideialms.com) - a complete Learning Management System - using BRP Stack. Here's what it demonstrates: #### Features Implemented 1. **User Management** - Authentication with multiple roles (admin, instructor, student) - User profiles with avatars - Session management 2. **Course Management** - Course creation and editing - Hierarchical course categories - Course sections and modules - Activity modules (pages, assignments, quizzes, discussions) 3. **Enrollment System** - Student enrollment - Teacher assignments - Group management - Enrollment status tracking 4. **Gradebook** - Layered grade system - Gradebook categories - Gradebook items - User grades with adjustments 5. **Content Management** - Rich text editor (TipTap) - Syntax highlighting - Mermaid diagram support - D2 diagram rendering - Whiteboard functionality 6. **Admin Panel** - System information - User management - Course management - Category management - Migration management - Database dump functionality #### CLI Mode One of the most powerful features is the CLI mode built with Commander.js: ```bash # Start the server paideia server # Check migration status paideia migrate status # Run migrations paideia migrate up # Fresh migration (drop all and recreate) paideia migrate fresh # Dump database paideia migrate dump ``` All of this is packaged in a single binary that can be deployed anywhere. --- ### Benefits of BRP Stack #### Developer Experience 1. **Single Configuration File**: Everything is configured in `payload.config.ts` 2. **Type Safety**: End-to-end type safety catches errors early 3. **Hot Reloading**: Fast development with instant feedback 4. **Rich Ecosystem**: Leverage React's massive component library 5. **Great Documentation**: Payload and Elysia have excellent docs #### Performance 1. **Fast Runtime**: Bun is significantly faster than Node.js 2. **Efficient Bundling**: Single binary with optimized bundle size 3. **Server-Side Rendering**: Fast initial page loads 4. **Client-Side Navigation**: Smooth, app-like experience #### Deployment 1. **Single Binary**: No dependency management needed 2. **Cross-Platform**: One binary for all platforms 3. **Easy Distribution**: Just send the binary file 4. **Quick Setup**: Deploy in seconds, not minutes #### Maintainability 1. **Type Safety**: Catch errors at compile time 2. **Clear Architecture**: Dual server architecture is easy to understand 3. **Modular Design**: Collections and globals are well-organized 4. **Built-in Features**: Less code to write and maintain --- ### Getting Started #### Prerequisites - Bun (latest version) - PostgreSQL database - Basic knowledge of TypeScript and React #### Installation 1. **Create a new project**: ```bash bun create paideia-app my-app cd my-app ``` 2. **Install dependencies**: ```bash bun install ``` 3. **Configure environment variables**: ```bash cp .env.example .env # Edit .env with your database credentials ``` 4. **Run migrations**: ```bash bun run payload migrate ``` 5. **Start development server**: ```bash bun run dev ``` #### Project Structure ``` my-app/ ├── app/ # React Router frontend │ ├── routes/ # Route components │ ├── components/ # React components │ └── utils/ # Frontend utilities ├── server/ # Backend server │ ├── collections/ # Payload collections │ ├── contexts/ # React Router contexts │ └── utils/ # Backend utilities ├── src/ │ └── migrations/ # Database migrations └── payload.config.ts # Payload configuration ``` --- ### Comparison with Other Stacks #### Vs. Next.js + Prisma **BRP Stack Advantages:** - Single binary deployment - Built-in authentication and authorization - Job queue and cron jobs included - File storage integration - Less boilerplate code **Next.js Advantages:** - Larger community - More third-party packages - Better SEO tools (though BRP has SSR too) #### Vs. Remix + Drizzle **BRP Stack Advantages:** - Payload provides CMS features - Built-in admin panel - Access control system - Media management - Single binary deployment **Remix Advantages:** - More mature framework - Better documentation - Larger community #### Vs. Traditional MERN Stack **BRP Stack Advantages:** - Type safety throughout - Single binary deployment - Built-in features (auth, storage, jobs) - Faster runtime (Bun vs Node.js) - Less configuration needed --- ### Challenges and Solutions #### Challenge 1: Payload with React Router (Not Next.js) **Problem**: Payload officially supports Next.js, not React Router. **Solution**: Use Payload's local API, which works with any framework. This allows us to use React Router while still getting all of Payload's benefits. #### Challenge 2: Single Binary Compilation **Problem**: Ensuring all dependencies compile into a single binary. **Solution**: Bun's bundler handles this well, but we need to be careful with native dependencies. We created a build script that checks for native dependencies before bundling. #### Challenge 3: Migration Management **Problem**: Managing database migrations in a compiled binary. **Solution**: We include migrations in the binary and use Payload's migration system. Migrations are stored as TypeScript files that are bundled with the application. --- ### Future of BRP Stack The BRP Stack represents a new approach to full-stack development that prioritizes: 1. **Simplicity**: Less configuration, more functionality 2. **Performance**: Fast runtime and optimized bundles 3. **Developer Experience**: Type safety and great tooling 4. **Deployment**: Single binary for easy distribution As Bun matures and Payload continues to evolve, this stack will only get better. I'm excited to see how the community adopts and extends this approach. --- ### Resources - **Paideia LMS**: https://paideialms.com - **Live Demo**: https://demo.paideialms.com - **Documentation**: https://docs.paideialms.com - **Bun**: https://bun.sh - **React Router**: https://reactrouter.com - **Payload CMS**: https://payloadcms.com - **Elysia**: https://elysiajs.com --- ### Conclusion BRP Stack (Bun + React + Payload) is a powerful combination that provides everything you need to build modern web applications. With its single binary deployment, type safety, built-in features, and excellent developer experience, it's a stack worth considering for your next project. I built Paideia LMS in 30 days using this stack, and the result exceeded my expectations. The combination of Bun's performance, React's ecosystem, and Payload's features creates a development experience that's both powerful and enjoyable. If you're looking for a modern, efficient, and developer-friendly way to build full-stack applications, give BRP Stack a try. You might find it's exactly what you've been looking for. --- **About the Author** I'm the creator of [Paideia LMS](https://paideialms.com), a modern Learning Management System built with BRP Stack. I'm passionate about creating developer-friendly tools and sharing knowledge with the community. **Connect with me:** - Website: https://paideialms.com - GitHub: [email protected] - Twitter: https://x.com/yomaru_1999 --- *This article was written based on my experience building Paideia LMS. If you have questions or want to discuss BRP Stack, feel free to reach out!*