Guren at a Glance
The fullstack TypeScript framework that feels like Laravel — powered by Bun.
Documentation
Learn Guren,
end to end.
Guides for every subsystem — routing, models, auth, queues — and tutorials that build a working app. Every page starts with code you can run.
Guides
Getting Started
Why Guren
An honest look at where Guren fits — compared with Hono, Next.js, AdonisJS, and Laravel — and why it is built the way it is.
Getting Started
This guide has two parts. Part A gets a fresh Guren app running in about five minutes with SQLite — no Docker, no database server. Part B covers the full setup: Postgres or MySQL, environment variables, feature generators, and production builds. Start with Part A; come back to Part B when you need it.
First Steps: A 10-Minute Tour of One Request
This tour follows a single request — GET /posts — through every layer of a Guren app: route, controller, validation, model, resource, Inertia page, and test. Read it to build a mental map; each stop links to the guide that goes deeper.
Architecture
Guren reimagines Laravel's design principles in TypeScript, tying together Bun, Hono, Inertia.js, React, and Drizzle ORM into a full-stack MVC framework. This document outlines the end-to-end flow from routing to response generation and explains the main building blocks.
The Basics
Routing
Routes map URLs to your application logic. They define what happens when a user visits /posts, submits a form, or hits an API endpoint. In vNext-style apps, each application owns a Router instance and route files export a registrar function instead of mutating a global registry.
Controllers
Controllers are where your application logic lives. They receive HTTP requests, interact with models and services, and return responses. Think of them as the glue between what the user asks for and what your app delivers.
Middleware Guide
Guren routes and applications share Hono's middleware model but expose Laravel-style ergonomics for common tasks. You can register middleware globally on the Application instance, per-route via the routing DSL, or through named aliases and groups.
CSRF Protection
Cross-Site Request Forgery (CSRF) protection prevents malicious websites from submitting forms on behalf of authenticated users. Guren provides built-in CSRF middleware that integrates seamlessly with sessions.
Validation
Guren's primary validation path is schema-first. Use Zod-compatible schemas in controllers, route definitions, or middleware so request parsing and type inference stay in one place. A legacy FormRequest compatibility layer still exists for migrations.
Error Handling
Guren provides multiple layers of error handling, from a centralized ExceptionHandler to controller-level exception catching. Built on Hono's robust error handling primitives, you can customize how errors are displayed to users in both development and production.
Database
Guren uses Drizzle ORM and supports PostgreSQL, SQLite, and MySQL. You define your schema in TypeScript, derive models from those tables, and get a fluent query API that feels like Laravel Eloquent while staying fully type-safe.
Frontend Guide
Guren delivers a single-page application experience by combining Inertia.js with React. Controllers return Inertia responses, and the frontend renders the matching React components located under resources/js/pages/.
Security
Authentication Guide
Guren ships with a Laravel-inspired authentication stack that sits on top of the session middleware and the ORM layer. The goal is to match the expressiveness of Laravel's guards and user providers while staying idiomatic to TypeScript and Bun.
OAuth Guide
Guren ships an OAuth 2.0 authorization-code flow for "Sign in with GitHub / Google / Discord" style login. It handles the redirect, CSRF-safe state, token exchange, and profile fetch — you wire it into your own login controller and session.
Authorization
Authorization determines what an authenticated user is allowed to do. Guren provides a policy-based authorization system inspired by Laravel.
API Tokens Guide
Guren provides a secure API token system for authenticating API requests. Tokens are hashed before storage, support abilities (scopes), and can have expiration times.
Password Reset Guide
Guren provides a secure password reset system with token generation, verification, and expiration. Tokens are hashed before storage for security.
Email Verification Guide
Guren provides a secure email verification system with token generation, verification, and expiration. Tokens are hashed before storage for security.
Encryption & Hashing
Guren provides utilities for encrypting data and hashing passwords securely.
Digging Deeper
Events Guide
Guren provides a simple yet powerful event system for decoupling components in your application. Events allow you to broadcast occurrences in your application that other parts can listen and react to.
Queue Guide
Guren provides a robust queue system for deferring time-consuming tasks to be processed in the background. This is essential for maintaining fast response times while handling operations like sending emails, processing uploads, or making external API calls.
Cache Guide
Guren provides a unified caching API with support for multiple storage backends. Caching helps improve application performance by storing expensive computations or database queries for quick retrieval.
Mail Guide
Guren provides a fluent API for sending emails with support for multiple transport backends. The mail system integrates with the queue system for async sending and supports HTML templates, attachments, and more.
Notifications Guide
Guren provides a unified API for sending notifications across multiple channels like email, database, Slack, and more. Notifications are class-based, making them reusable and easy to test.
Broadcasting Guide
Guren provides a broadcasting system for real-time event broadcasting to connected clients. This is useful for building features like live notifications, chat applications, and real-time dashboards.
Storage Guide
Guren provides a unified file storage API with support for multiple storage backends. The storage system makes it easy to work with local filesystems, Amazon S3, and other cloud storage providers with a consistent interface.
Task Scheduling Guide
Guren provides a fluent API for defining scheduled tasks within your application. Instead of managing multiple cron entries, you can define your entire task schedule in code.
Rate Limiting Guide
Guren provides a flexible rate limiting system to protect your application from abuse. It supports multiple storage backends, custom key generators, and both fixed and sliding window algorithms.
Logging Guide
Guren provides a flexible logging system with multiple channels, log levels following RFC 5424, and contextual logging support.
Health Checks
Guren provides a comprehensive health checking system to monitor your application's dependencies and services. Use health checks to expose a /health endpoint for load balancers, orchestrators, and monitoring tools.
Internationalization (i18n) Guide
Guren provides a comprehensive internationalization system with translation management, pluralization support for multiple languages, and both file-based and memory-based loading.
API Resources
API Resources provide a transformation layer between your models and API responses. They give you fine-grained control over how data is serialized to JSON.
Testing & Deployment
Testing
A single well-written test catches bugs before your users do. Guren makes testing so convenient that writing tests feels faster than manually checking things in a browser.
Deployment Guide
This guide summarizes the steps required to promote a freshly scaffolded Guren application to production. It assumes you generated your project with create-guren-app and that you have a PostgreSQL instance available.
Serverless Deployment (AWS Lambda)
Guren runs on AWS Lambda via the @guren/core/lambda adapter. This guide covers the full serverless stack — HTTP, queues, scheduled tasks, CLI commands, and infrastructure.
Production Operations Runbook
This runbook defines minimum reliability operations before GA.
Reference
Build an Auth App
This guide walks you through building an application with user registration, login, and protected routes. You will go from an empty directory to a working auth flow in under ten minutes.
Ship an API
This guide walks you through building and shipping a JSON API with Guren. You will scaffold an API-only project, define a database schema, create controllers with validation, and test your endpoints.
Deploy to Production
This guide covers the essential steps to take a Guren application from local development to a production environment. It focuses on Docker-based deployment with Bun.
Troubleshoot a Broken Setup
This guide covers the most common issues you will encounter when developing with Guren and how to fix them quickly. When something goes wrong, start here before diving into individual package documentation.
CLI Reference
Guren ships with two companion CLIs:
Plugin Authoring Guide
This guide walks you through creating, testing, and publishing a Guren plugin.
Support Matrix
| Runtime | Versions | Status |
Upgrading Guren
Use this guide for minor-to-minor upgrades.
Release & Compatibility Policy
This document defines the minimum release contract for production use.
Glossary
Short definitions for common terms in the Guren docs.
Tutorials
Build a Mini Blog
Tutorials: Build a Mini Blog
This tutorial series takes you from an empty directory to a small but real blog application. You build it one layer at a time — schema, model, validator, controller, routes, React pages — so by the end you understand how every piece of a Guren app fits together.
Part 1: Create a Blog Post App
In this part you build the heart of the blog: creating, listing, and reading posts. You write every file by hand — table, model, validator, controller, routes, and pages — so you see exactly how a request travels through a Guren application.
Part 2: Add Authentication
Your blog from Part 1 lets anyone publish posts. In this part you add user accounts with one command, put post creation behind a login wall, and attach an author to every post.
Part 3: Relationships: Comments
Your blog has posts and authors from Part 2. In this final part, readers get a voice: you add a comments table that belongs to both a post and a user, wire up the model relationships, and build a comment form on the post page.