Installation

Reepolee has one hard prerequisite - Bun. The CLI is the runtime, the package manager, the bundler, and the test runner all in one. The project installer then fetches the required command-line tools and browser-side vendor files, while the VSCode extension remains optional editor support.

This page is the first-time setup. Once you've worked through it, Quick Start gets you from a fresh project to a running application in a few minutes.

Installing Bun

Use the official installer:

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

powershell -c "irm bun.sh/install.ps1|iex"

Verify the install:

bun --version

Upgrade to the latest stable release - Bun 1.4 or later:

bun upgrade

The output should be the latest stable Bun version. If bun: command not found, the installer's ~/.bun/bin directory isn't on your $PATH - open a new terminal or run source ~/.bashrc (or ~/.zshrc) to pick up the change.

Pinning a Specific Version

For a project that needs a specific Bun version (matching a teammate's environment, matching production), install that version explicitly by appending the version tag (<version>):

curl -fsSL https://bun.sh/install | bash -s "bun-v<version>"

iex "& {$(irm https://bun.com/install.ps1)} -Version <version>"

Then leave bun upgrade alone until you've tested a newer version against your project. Reepolee works with the latest stable Bun; a recent version is safe.

Creating Your First Project

Follow these steps to get a Reepolee project running on your machine.

1. Create a Project

Pick a name for your project folder. Set it once and every command on this page updates to match, so you can copy-paste them as-is:

bun create reepolee/reepolee __PROJECT_DIR__
cd __PROJECT_DIR__

Reepolee is open source under the MIT License and currently in beta. APIs, generators, and project conventions may still change before 1.0.

Prefer a plain source checkout instead? Clone the public repository and run bun install - the first dependency install fires the same install script:

git clone https://github.com/reepolee/reepolee.git __PROJECT_DIR__
cd __PROJECT_DIR__
bun install

2. Everything Installs Automatically

With bun create reepolee/reepolee, the install script runs by itself as part of project setup - the fetch installs dependencies and the postinstall step fires the installer, so there is no separate command to run. After a git clone, your first bun install triggers the same step. It installs:

• Project dependencies - installed by the same bun install that fires the installer
• Tailwind v4 executable (tw) - standalone binary (avoids npm collision issues)
• TypeScript compiler (tsc) - standalone binary
• reettier - the Ree template formatter
• reesql - the SQL formatter
• Vendored browser packages - Zod, highlight.js, xlsx, the Temporal polyfill, and the DPU polyfill, plus matching Zod type declarations
• libvips - VIPS CLI
• SQLite application database - initialised from the shipped SQL files
• Demo users - Alice with system,user and Bob with user

The dev orchestrator (scripts/dev_run.ts) runs the Tailwind watcher and the dev server side-by-side - bun dev is a single command. With bun create reepolee/reepolee, the fresh repository and its initial commit come from bun create itself; with a git clone, your history stays as it is.

The project-folder name you choose is remembered across the Reepolee documentation. The installer creates Alice with username alice and password a, and Bob with username bob and password b. These short passwords are development fixtures, not production defaults.

If you ever need to re-run the setup manually, the script is bun reepolee:install. Bootstrap is protected by .reepolee/marker, so an already initialized project reports that it was skipped instead of reseeding the database or demo users. Pass --verbose to stream each installer command while diagnosing a failed setup:

bun reepolee:install --verbose

3. Verify the Setup

bun dev

If you see Listening on http://<localhost>:2338 and the page loads in a browser, your setup is complete. To also start the reeman app (generator + sysadmin UI) in the same session, use bun dev:all instead - see Quick Start for the full dev-command matrix.

4. Optional - a linter

If you want JS/TS linting, install whichever linter you prefer (for example bun add -g oxlint). It's not required and nothing in the project depends on it.

Editor Setup

For VSCode, the Ree Templates extension adds syntax highlighting and formatting for .ree files. Install it from the marketplace or with the command-line:

code --install-extension reepolee.ree-templates

For other editors:

• Treat .ree as HTML. The HTML syntax highlighter handles most of Ree fine - the tag prefixes ({=, {~, {_, {-, {#, {:, {/, {{) are visually distinct enough that the HTML grammar ignores them cleanly.
• Tailwind IntelliSense (the official VSCode extension) works inside .ree files if you tell it to - add "tailwindCSS.includeLanguages": { "ree": "html" } to your VSCode settings.

The TypeScript language server picks up .ts files in Reepolee projects natively - no extra configuration needed.

For the full LSP feature set — autocompletion, go-to-definition, hover, and translation-key support — see Editor & LSP.

Optional Tooling

A few tools are useful but not required:

• gh (GitHub CLI) - creates pull requests and manages issues from the command line.
• jq - for filtering NDJSON SQL logs (covered in Logs).
• certbot - only usable on the production server, for TLS certificates (Reverse Proxy).

Install whichever fits your workflow. None are needed to run Reepolee.

A note about libvips for image processing

The image-editor / avatar pipeline (Image Processing) relies on the native libvips library. Reepolee ships a small installer that fetches a prebuilt libvips for your platform so you don't have to install it through a system package manager.

The installer supports Windows (prebuilt from GitHub releases), macOS (Homebrew), and Linux (apt/dnf/pacman), and adds libvips to your PATH automatically.

If you don't use the image editor or avatar uploads, you can skip this - the rest of the app runs without libvips.

What's Next?

After the init script completes, your project is ready. Quick Start walks you through the dev workflow and project structure.

If anything fails during setup - missing Bun, broken bun install, the dev server not starting - fix it now before moving on. The rest of the documentation assumes the install works.