Skip to content

README.md

Latest commit

 

History

History
248 lines (194 loc) · 9.91 KB

README.md

File metadata and controls

248 lines (194 loc) · 9.91 KB
Raw

Clojure Stack Lite

This is ontopro's fork of abogoyavlensky/clojure-stack-lite, kept as the application template that the KIT — short for the Clojure Agent Kit — brings with it.

  • kit (the default branch) is the KIT's line of the template. git diff master..kit is everything it changes, and none of it is specific to the KIT: a generated project is an ordinary Clojure Stack Lite application.
  • master is an untouched mirror of upstream.
  • kit-v1, kit-v1.1, … are versions of THIS TEMPLATE as the KIT pins it. They are not versions of the KIT, and the upstream project's own tags (0.2.1 …) are left as they came. kit-v1.1 is kit-v1 with its security defaults completed: the security headers and a Referrer-Policy on every response, an error page that names nothing of the error, and a SameSite=Lax session cookie. kit-v1.2 is kit-v1.1 with its dependencies past their published HIGH advisories - Jetty and Jackson pinned at the top level of deps.edn over what brings them, until those releases catch up - and every GitHub Action pinned to a commit.

To use the template on its own, the coordinate is io.github.ontopro/clojure-stack-lite. All credit for the template is upstream's; the licence is theirs, MIT, unchanged.

A quick way to start a full-stack Clojure app with server-side rendering. Built on a powerful yet lightweight stack featuring SQLite/PostgreSQL, HTMX, AlpineJS, and TailwindCSS v4.

This template is designed to be lightweight and easy to use, with a focus on rapid development and deployment. Minimal distraction and sane defaults. Everything is streamlined to give you a solid foundation for building modern web applications.

Get started building your new Clojure application in seconds and be productive!

Usage

  1. Create a new Clojure project using Clojure CLI:

    clojure -Ttools install-latest :lib io.github.seancorfield/deps-new :as new
clojure -Tnew create :template io.github.ontopro/clojure-stack-lite :name myproject

    Requires Clojure CLI tools version 1.12.0.1479 or later.

    Or alternatively using neil:

    brew install babashka/brew/neil
neil new io.github.ontopro/clojure-stack-lite myproject

  2. Start development (with mise):

    cd myproject
mise trust && mise install
bb clj-repl
(reset)

    The server should be available at http://localhost:8000. Check out project's README.md and template documentation for more information on how to use the project.

Tip

Edit some details before going to production: label in Dockerfile, domain in resources/public/manifest.json and description in README.md

Features

  • 🏗️ Robust Clojure stack powered by Integrant and Reitit/Ring
  • 🎨 Lightweight frontend using HTMX, AlpineJS and TailwindCSS v4 (with optional DaisyUI components)
  • 📦 SQLite/PostgreSQL database (you choose)
  • 🔄 Zero-downtime deployment via Kamal
  • ⚡ GitHub Actions CI/CD pipeline
  • 🧪 Integration and unit testing setup with coverage
  • 🔍 Linting, formatting and deps version management
  • ⚙️ deps.edn and Babashka Tasks for efficient project management
  • 📱 Basic PWA support out of the box (without service worker)
  • 🔒 Optional authentication and registration flow

Stack

Backend

  • Integrant: Component lifecycle management for application
  • Reitit: Fast data-driven routing
  • Ring/Jetty: HTTP server adapter
  • Hiccup: HTML generation from Clojure data structures
  • Malli: Data validation and specification

Database

  • SQLite/PostgreSQL: Choose between file-based SQLite or enterprise-grade PostgreSQL
  • next.jdbc: JDBC-based database access
  • HoneySQL: SQL as Clojure data structures
  • Ragtime: Database migrations

Frontend

  • HTMX 2: HTML extensions for AJAX without writing JavaScript
  • AlpineJS 3: Lightweight JavaScript framework for adding behavior
  • TailwindCSS 4: Utility-first CSS framework
  • [OPTIONAL] DaisyUI: A UI Component library (:daisyui true option)

Development

  • Babashka: Project management with tasks
  • clj-kondo: Static analyzer and linter
  • cljfmt: Code formatter
  • eftest/cloverage: Testing and code coverage

Deployment

  • Docker: Containerization
  • Kamal: Zero-downtime deployments
  • GitHub Actions: CI/CD workflows

Features

  • Authentication and registration flow (:auth true option)
    • Login, logout, registration, password reset, password change, account page

Project structure

The template generates a Clojure project with the following structure:

├── .clj-kondo/            # Clojure linting configuration
├── .github/               # GitHub Actions workflows and configurations
├── .kamal/                # Kamal deployment configuration (only used with Kamal)
├── db/                    # Empty database directory for database files (only used with SQLite)
├── dev/                   # Development configuration directory
│   └── user.clj           # User-specific development configuration
├── resources/             # Static resources and configuration files
│   ├── public/            # Public assets (CSS, JS, images)
│   ├── migrations/        # Database migration files
│   ├── config.edn         # Main configuration file for the application
│   ├── config.dev.edn     # Development-specific configuration
│   └── logback.xml        # Logging configuration file
├── src/                   # Source code directory
│   └── {{name}}           # Main namespace directory
│       ├── core.clj       # Application entry point
│       ├── db.clj         # Database system component and main operations
│       ├── handlers.clj   # HTTP request handlers
│       ├── routes.clj     # Route definitions
│       ├── server.clj     # Server system component
│       └── views.clj      # HTML templates and components with Hiccup
├── test/                  # Test files directory
│   └── {{name}}           # Test namespace directory
│       ├── handlers_test.clj      # The pattern to copy: a handler tested as a function of a request map
│       ├── system_smoke_test.clj  # The one test that boots the whole system; not a pattern to copy
│       └── test_utils.clj # Test utilities
├── .cljfmt.edn            # Formatting configuration
├── .gitignore             # Git ignore rules
├── .mise.toml             # mise-en-place configuration with system dependencies
├── .dockerignore          # Docker ignore rules
├── bb.edn                 # Babashka tasks configuration for managing application
├── deps.edn               # Clojure dependencies and aliases
├── Dockerfile             # Dockerfile for building the application image
├── docker-compose.yaml    # Run PostgreSQL database for local development (only used with PostgreSQL)
└── README.md              # Project documentation

Options

The template offers customization options for generating your project:

  • :db - Choose between SQLite or PostgreSQL for your database (Default: :sqlite)
    • Available values: :sqlite or :postgres
  • :daisyui - Include DaisyUI, a component library for TailwindCSS (Default: false)
    • Available values: true
  • :deploy - Choose between Kamal and no deployment configuration (Default: :kamal)
    • Available values: :kamal or :none
  • :auth - Add authentication and registration flow (Default: false)
    • Available values: true

Possible values: false | true

Usage example:

clojure -Tnew create :template io.github.ontopro/clojure-stack-lite :name myproject :daisyui true

Authentication flow preview

lite_auth_preview.mp4

Roadmap

  • DaisyUI support
  • PostgreSQL support
  • No deployment option
  • Register/Auth flow
  • Sentry support
  • More frontend tool options (TwinSpark, Datastar)
  • Queue support
  • Websocket support

Links

Template Development

Requirements

To work with this template, you need:

  1. mise (recommended) or manual installation of:
    • Java
    • Clojure
    • Babashka

Getting Started

All management tasks:

bb tasks
The following tasks are available:

test    Run tests for the template config
new     Create a new project
release Create and push a new git tag based on provided version

After you updated the template and ran tests bb test, you can create a new project to check if everything works as expected:

bb new

The new project will be created in the tmpl directory at the root that is ignored by git.

Release

Once you are ready to release a new version of the template, bump version in deps.edn:

:aliases -> :build -> :exec-args -> :version -> "0.1.1

and then run the following command:

bb release

A new git tag based on latest version will be created and pushed to the repository.

License

MIT License Copyright (c) 2025 Andrey Bogoyavlenskiy