Quick Start

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 Repository

Reepolee isn't published to a package registry. Create a project with bun create reepolee/reepolee my-project - the install script runs automatically as part of the fetch. Prefer to clone the MIT-licensed repository instead? Your first bun install fires the same installer there. Installation walks through it in full. By the time you reach this page you should already have a project folder in which the 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.

With bun create the project starts as a tarball fetch with a fresh repository and initial commit; with a clone it starts as a source checkout. Either way, the same project-specific setup is applied.

You can remove or rename the original remote after installation because a Reepolee project is a starting point rather than a package dependency. When a newer version contains changes you want, use Reesync to compare a fresh checkout with your project and choose the files to adopt.

The Quickest Path - bun reeman

Most of the steps below - picking a database, applying SQL files, choosing a session backend, and generating resources - are also available in the project's interactive setup tool:

bun reeman

On an initialised project the tasks are available from the grouped menu, alongside generators ("Single table", "All tables", "Bulk CRUD", "Nested children"), "Simple Table Page", "Remove route", "Add locale", 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.

On a fresh database, Quick Start uses ADMIN_USERNAME, ADMIN_EMAIL, and ADMIN_PASSWORD from .env as reviewed defaults for its admin-user prompts. You can change any value before confirming creation.

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. Reeman's Set database type updates both CONNECTION_STRING and TEST_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 (scripts/dev_run.ts, the dev orchestrator):

• Builds CSS once, then runs tailwindcss --watch=always (the CSS compiler, incremental)
• bun --hot server.ts --dev - the application server with hot reload on file changes
• The orchestrator also starts the queue worker (worker.ts) when --worker is passed or REDIS_URL is set, and restarts the dev process when .env or config/ changes

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 Installed Demo Users

bun reepolee:install creates two verified demo users:

This is intentional. Alice can open the system Users CRUD but initially cannot open /admin/*. Sign in as Alice, edit Alice in Users, and add the admin module. After the session reflects the updated assignment, the admin navigation for Developers and Languages becomes available. Bob remains a user and can work with Frameworks and Books under /user/*.

Alice and Bob are documentation fixtures with intentionally trivial passwords. Remove or replace them before production. See Authorization.

Generating Your First Resource

The documentation example uses the shipped incremental SQL files instead of modifying the core init file:

1. Run sql/sqlite/demos/05-frameworks.sql to add Developers, Languages, Frameworks, the Frameworks view, and demo data.
2. Run sql/sqlite/demos/06-init-books.sql to add Books and its demo data.
3. Generate Developers and Languages with the admin prefix.
4. Generate Frameworks and Books with the user prefix.

Apply each file with bun reeman -> "Run SQL file". Then use its resource generator for each table and choose the matching prefix.

bun reeman
# admin: developers, languages
# user: frameworks, books

The generated folders mirror their authorization modules: routes/admin/developers, routes/admin/languages, routes/user/frameworks, and routes/user/books. Their public paths are /admin/developers, /admin/languages, /user/frameworks, and /user/books.

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.