Installation

Introduction

Reepolee has one hard prerequisite - Bun. The CLI is the runtime, the package manager, the bundler, and the test runner all in one. Four more global tools (Tailwind, .ree template formatter, SQL formatter and VSCode Extension) round out the development environment, but they install once and apply across every Reepolee project on your machine.

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

Installing Bun

Use the official installer:

macOS / Linux / WSL
curl -fsSL https://bun.sh/install | bash
Windows
powershell -c "irm bun.sh/install.ps1|iex"

Verify the install:

bun --version

Upgrade to canary, already Rust-based, as we need the latest and greatest:

bun upgrade --canary

The output should be the Bun version (1.4.0 at time of writing). 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:

macOS / Linux / WSL
curl -fsSL https://bun.sh/install | bash -s "bun-v1.4.0"
Windows
iex "& {$(irm https://bun.com/install.ps1)} -Version 1.4.0"

Then leave bun upgrade alone until you've tested a newer version against your project. Reepolee's README documents the Bun version it tracks; running with the same version (or newer) is safe.

Creating Your First Project

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

1. Create a Project Folder

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:

mkdir __PROJECT_DIR__
cd __PROJECT_DIR__

2. Receive the Alpha Archive

Reepolee is currently closed alpha. Invited participants receive the .tar.gz archive by email; save it in the project folder, ready to unpack and run.

3. Unpack the Archive

tar -xzf reepolee.tar.gz

Or use your preferred archive tool (7-Zip, WinRAR, etc.).

4. Run the reepolee:install Script

The archive includes an initialization script that installs global tools and sets up your project.

bun reepolee:install

This script installs:

  • Project dependencies - via bun install
  • @tailwindcss/cli - the Tailwind v4 CLI
  • concurrently - runs the Tailwind watcher and dev server side-by-side
  • reettier - the Ree template formatter
    • reesql - the SQL formatter
  • vendor folder - vendored packages
  • libvips - VIPS CLI

5. Verify the Setup

bun dev

If you see Listening on http://<localhost>:2338 and the page loads in a browser, your setup is complete.

6. 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.

Optional Tooling

A few tools are useful but not required:

  • gh (GitHub CLI) - creates pull requests, manages issues, and runs the deploy workflow 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) what you want local network access thru h3.

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.