Guide/guides

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.

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.

The instructions target macOS and Linux, and also work on Windows with WSL2.

Note

If any term is unfamiliar, see the Glossary.

Part A: Quickstart (SQLite — no Docker)

Prerequisites

Bun 1.1 or later — that is all.

curl -fsSL https://bun.sh/install | bash

1. Scaffold a project

bunx create-guren-app my-app
cd my-app

The scaffolder asks two questions — the defaults are right for getting started:

Rendering mode: SSR (default) or SPA. SSR gives you server-rendered HTML with automatic Vite asset discovery.
Database: SQLite (default, zero-config), PostgreSQL, or MySQL.

It then installs dependencies and creates a .env file with a generated APP_KEY for you. To skip the prompts, pass flags: --mode ssr, --db sqlite, or --auth to include authentication scaffolding from the start.

2. Start the dev server

bun run dev

This regenerates the typed route/page manifests (codegen) and boots the server. Open http://localhost:3333.

3. What you should see

A crimson ASCII banner in the terminal with the Guren version and URLs, and the welcome page in your browser. The SQLite database file is created on demand at ./data/guren.db — the fresh app defines no tables yet, so there is nothing to migrate before your first run.

Tip

Backend changes hot-reload via Bun, and the dev server spawns Vite automatically for frontend assets. Set GUREN_DEV_VITE=0 to run Vite yourself, or GUREN_DEV_BANNER=0 to silence the banner in scripts.

Add your first feature

You have a running app — now build something with it. The Build a Mini Blog tutorial is the recommended next step: a three-part course that adds a posts CRUD, authentication, and comments with relationships to the app you just created.

Part B: Full Setup

Everything below is optional for your first session, but you will want it as your app grows.

Use PostgreSQL or MySQL

Pass --db postgres (or --db mysql) when scaffolding, or pick it at the prompt. The scaffolder then writes a docker-compose.yml for the matching database and points DATABASE_URL at it. With Docker Desktop (Compose v2) installed, start the database with:

docker compose up -d

Default connection strings:

PostgreSQL: postgres://guren:guren@localhost:54322/guren
MySQL: mysql://guren:guren@localhost:33306/guren

Stop the container with docker compose down when you are done.

Tip

Already running Postgres locally or in the cloud? Skip Docker entirely and point DATABASE_URL at that instance — the rest of the guide works unchanged. An existing SQLite app can switch later by updating config/database.ts; see the Database Guide.

Environment variables

The scaffolder creates .env from .env.example and fills in a fresh APP_KEY. Key settings:

APP_URL: Base URL reported to Inertia (default http://localhost:3333).
DATABASE_URL: Connection string — a file path for SQLite, a URL for Postgres/MySQL.
PORT: HTTP port for the dev server (default 3333).
SESSION_DRIVER, CACHE_STORE, QUEUE_CONNECTION: In-memory/sync defaults; switch to redis for multi-process deployments.

Caution

Keep .env out of version control. If credentials leak in a commit, rotate the database user and regenerate any API keys referenced in the file.

Add authentication and resources

Guren ships with generators that scaffold whole features:

bunx guren add auth
bunx guren add resource posts --fields "title:string,body:text,published:boolean"

add auth sets up registration, login, logout, and session middleware. add resource creates a model, migration, controller, validator, resource, and Inertia pages for the given fields. Run bunx guren add --help for all available generators (queue, mail, events, storage, and more).

Generate typed manifests

bun run codegen

Codegen writes the typed route helpers and page manifest that power end-to-end type safety. bun run dev and bun run build run it automatically, so you only need it manually after adding or renaming routes and pages while the server is stopped.

Run migrations and seed data

Once you have added resources (and therefore migrations), apply the schema and populate sample data:

bun run db:migrate && bun run db:seed

This works the same for SQLite, Postgres, and MySQL — migrations come from your Drizzle schema in db/schema.ts.

Typecheck and test

bun run typecheck

Fix type errors as they appear — catching issues early is much easier than debugging a running app. As you add tests (see the Testing Guide), run them with bun test.

Production build

When you are ready to ship:

bun run build
bun run preview

build emits hashed client (and, in SSR mode, server) assets under public/assets/ plus the manifests the runtime reads. preview starts the production server locally so you can verify the build. See the Deployment Guide for hosting options.

Where to go next

Build a Mini Blog tutorial — the recommended hands-on course for newcomers: posts CRUD, authentication, then comments and relationships.
First Steps — a ten-minute tour of how one request flows through the framework.

Then continue through the guides in this order:

Keep the CLI Reference handy along the way, and if you spot issues or have ideas, please open an issue or PR — we welcome contributions.