Getting Started

Rakiba is a Doom Emacs-style configurable template system for building fullstack Clojure/ClojureScript web applications. Pick your server, frontend, and features from a menu - get a production-ready setup in minutes.

Requirements

Before you begin, make sure you have the following installed:

Quick Start

Clone Rakiba and create your first project:

# 1. Clone Rakiba
git clone https://github.com/anomalyco/rakiba.git
cd rakiba

# 2. Configure your stack
# Edit rakiba.edn - uncomment the modules you want

# 3. Create a new project
bb init my-app

# 4. Start developing
cd projects/my-app
npm install
bb clj    # Terminal 1: Start backend with nREPL
bb cljs   # Terminal 2: Start shadow-cljs with hot reload
bb sass   # Terminal 3: Watch SASS files (optional)

# 5. Open http://localhost:3000

How It Works

Rakiba is a wrapper framework - your projects live as subdirectories inside the Rakiba root:

rakiba/                    # Cloned repo (don't modify)
├── templates/             # Template source files
├── scripts/               # bb task implementations
├── bb.edn                 # Rakiba commands
├── rakiba.edn             # Your configuration (edit this!)
└── projects/
    └── my-app/            # Your generated project
        ├── .git/          # Your own git repo
        ├── bb.edn         # Project commands
        ├── deps.edn       # Clojure deps (managed)
        ├── shadow-cljs.edn
        ├── package.json
        ├── src/
        │   ├── rakiba/lib/    # LIB SPACE - managed by bb sync
        │   └── app/           # USER SPACE - your code
        └── resources/
            ├── public/        # Static assets
            └── sass/          # SASS source files

Key concept: rakiba.edn lives at the Rakiba root, not in each project. This means all your projects share the same configuration.

Project Structure

After bb init my-app, your generated project has this structure:

my-app/
├── bb.edn                 # Project tasks
├── deps.edn               # Clojure dependencies
├── shadow-cljs.edn        # ClojureScript config
├── package.json           # Node dependencies
├── config.edn             # Application config
├── src/
│   ├── rakiba/lib/        # Framework code (managed)
│   │   ├── server/        # Server adapter
│   │   ├── handler/       # Ring handler
│   │   ├── middleware/    # Ring middleware
│   │   ├── config/        # Config loading
│   │   ├── runtime/       # Runtime state
│   │   ├── log/           # Telemere logging
│   │   └── frontend/      # Frontend adapter
│   └── app/               # Your application code
│       ├── core.clj       # Backend entry point
│       └── core.cljs      # Frontend entry point
├── resources/
│   ├── public/            # Static assets, compiled JS/CSS
│   └── sass/              # SASS source files
└── test/                  # Your tests

Space Ownership

Rakiba separates lib space (managed) from user space (yours):

SpacePathbb sync Behavior
Lib Spacesrc/rakiba/lib/Updated (old files backed up)
User SpaceEverything elseNever touched

This means your code in src/app/ is always safe. Framework updates don’t break your app.

Configuration

Rakiba is configured via rakiba.edn in the root directory. See the Configuration page for all available options.

{;; State lifecycle management (required)
 :state-management :mount     ; or :integrant

 ;; Server adapter (required)
 :server :jetty               ; :jetty, :undertow, :http-kit, :aleph, :immutant

 ;; Frontend framework (use nil for API-only projects)
 :frontend :re-frame          ; :re-frame, :uix, :fulcro, or nil

 ;; Database adapters
 :database []                 ; :sql, :datascript, :datomic-pro

 ;; Authentication providers
 :auth []                     ; :google, :github, :email-password

 ;; Optional features
 :features []                 ; :websockets, :clj-reload, :admin-ui
}

Core dependencies always included: Telemere (logging), Reitit (routing), and Malli (schemas) are part of Rakiba’s core and don’t need to be configured.

Updating Rakiba

When Rakiba gets updates, sync your projects:

cd rakiba
git pull

# Update your project(s)
bb sync my-app

# Check for backed up files if you customized lib space
ls my-app/src/rakiba/lib/*.bak

Next Steps