Quick Start

Introduction

This page walks from a fresh project to a running Reepolee application. It assumes you've already installed Bun and the global tools - if not, work through Installation first.

Starting From the Release Archive

Reepolee isn't published to a package registry and you don't clone it from GitHub. During closed alpha, invited participants receive a tagged release archive by email, unpack it, and run the install script, all of which Installation walks through in full. By the time you reach this page you should already have an unpacked project folder in which bun reepolee:install has run, which means the dev dependencies are installed, your .env exists (copied from .env.example with TIME_ZONE set to your machine's timezone), and - because the default CONNECTION_STRING is sqlite:app.db - a local SQLite database has already been initialised with the core schema and English translations.

The archive ships without any git history of its own, so the project starts as a plain folder that is yours from the first commit. Turn it into your own repository whenever you like:

git init
git add -A
git commit -m "Initial commit from Reepolee"

There is no upstream remote to wire up and nothing tracking reepolee/reepolee, because a Reepolee project is a starting point you own outright rather than a dependency you follow. When a later release brings changes you want, you adopt them deliberately, and the Upgrade Guide covers how to bring a newer archive's changes into a project you have already started building on.

The Quickest Path - bun reeman

Most of the steps below - picking a database, applying the schema, choosing a session backend, creating the admin user - are also one menu pick each in the project's interactive setup tool:

bun reeman

On a fresh project (no users table yet) reeman offers a Quick Start flow that walks you through database type → init/seed SQL → session driver → admin user in order. On an initialised project the same tasks are available individually from the grouped menu, alongside generators ("Single table", "All tables", "Bulk CRUD", "Nested children"), "Simple Table Page", "Remove route", "Add language", and "Run SQL file".

Reading the rest of this page is still worth doing - it explains what reeman changes - but bun reeman is the shortest path from clone to running app.

Picking a Database Driver

Reepolee ships with first-class support for both SQLite and MySQL. There's nothing to copy - config/db.ts is a dynamic barrel that picks the right driver based on your CONNECTION_STRING. Set it to one starting with sqlite: and you get the SQLite driver; set it to one starting with mysql: and you get MySQL. The reeman's "Set database type" option toggles CONNECTION_STRING in .env for you.

Environment Variables

bun reepolee:install already created your .env from .env.example, so there is nothing to copy - open the existing .env at the project root and set CONNECTION_STRING to whichever database you want:

# SQLite - the database is a single file in the project directory
CONNECTION_STRING="sqlite:app.db"

# or, for MySQL
# CONNECTION_STRING="mysql://login:pass@localhost/reepolee_dev"

The default is sqlite:app.db, which the installer has already initialised with the core schema and English translations, so a fresh SQLite project runs without any further setup. Point CONNECTION_STRING at a different SQLite file and the server creates it on first start, after which you apply the schema through bun reeman -> "Run SQL file" (or by running the files under sql/sqlite/ yourself).

For MySQL, replace login, pass, and reepolee_dev with your credentials, create the database, and apply sql/mysql/ - reeman's "Set database type" and "Run SQL file" steps do both for you. The TIME_ZONE variable in .env controls the timezone applied to every MySQL connection - set it to match your server's timezone.

config/db.ts creates the connection directly and exits with a clear error at startup if CONNECTION_STRING doesn't start with either sqlite: or mysql: - so a typo gets caught before you load a page.

The full list of environment variables is in Configuration.

Running the Dev Server

Start everything in development mode:

bun dev

This single command runs the Tailwind watcher and the Bun hot-reload server side-by-side. Open http://localhost:2338 in a browser. The port is configurable via the PORT variable in .env.

What's running behind the scenes:

• bun --hot --no-clear-screen server.ts --dev - the application server with hot reload on file changes.
• tailwindcss -i ./css/app.css -o ./static/app-dev.css --watch - the CSS compiler.
• concurrently - the multiplexer that runs both with colour-coded output.

Hot reload picks up template, route, and styling changes within a few hundred milliseconds. For most edits you don't need to refresh the page.

The Seeded Admin Account

The fastest way to get an admin user is the admin-user step of reeman's Quick Start flow (a standalone bun generator/user <email> <password> does the same thing):

bun reeman
# pick "Quick Start" on a fresh DB, or "Reset the database" later
# the last step asks for an email + password and creates the row

Behind the scenes that runs bun generator/user <email> <password>, which writes a verified user straight into the database - no invitation round-trip needed. The first user created this way is granted modules_tags = "system,examples" (full system access); subsequent users get no modules unless you pass --modules, e.g. bun generator/user editor@example.com s3cret --modules user,editor.

For an invitation-based flow (or to add the seed yourself), write an unverified user with an invitation code into sql/sqlite/01-init-sqlite.sql, run the SQL, then visit /register/<email>/<invitation_code> to finish the registration:

INSERT INTO users (id, email, invitation_code, modules_tags) VALUES
    (1, 'you@example.com', 'invite123', 'user,admin');

For production, drop any seeded users entirely once you have real accounts - see Schema & Initialization.

Generating Your First Resource

The CRUD generator scaffolds a complete admin module from a database table - list view, create/edit form, validation, route handlers, the lot. Add a table to sql/sqlite/01-init-sqlite.sql:

DROP TABLE IF EXISTS authors;

CREATE TABLE authors (
    id INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT,
    name TEXT DEFAULT '' NULL,
    email TEXT DEFAULT '' NULL,
    created_at DATETIME DEFAULT current_timestamp,
    updated_at DATETIME DEFAULT NULL
);

CREATE INDEX authors_name ON authors(name);

CREATE TRIGGER authors_update_timestamp
AFTER UPDATE ON authors
FOR EACH ROW
BEGIN
    UPDATE authors SET updated_at = current_timestamp WHERE id = NEW.id;
END;

Apply the new schema with bun reeman → "Run SQL file" (or sqlite3 app.db < sql/sqlite/01-init-sqlite.sql for SQLite). Then scaffold the CRUD module - reeman has options for this too:

bun reeman
# pick "Single table" → enter "authors"
# or "All tables" to scaffold everything in the database in one shot

Behind the scenes reeman runs bun generator/resource crud authors, writes a complete CRUD module to routes/authors/, and registers the route in routes/routes.ts. Visit /authors and you have a working list page; /authors/new creates a record; /authors/:id/edit edits one.

The full generator reference is in Generators.

What's Where

A fresh Reepolee project has a small, opinionated layout. The folders you'll touch day-to-day:

Project Structure covers each in more detail.

Next Steps

You have a running Reepolee application. From here, the natural reading order:

• The Basics - how routes, controllers, and middleware compose.
• ReeTags - the templating language, in detail.
• Forms - the input components, validation, toasts, and uploads patterns that drive most of what you'll build.
• Database - the SQL API, schema management, and the generator.
• Security - the auth flow, authorization tags, and the invitation system.

For a tutorial-style walkthrough of building a real application, see the Recipes section.