Skip to content

README.md

Latest commit

 

History

History
130 lines (97 loc) · 4.62 KB

README.md

File metadata and controls

130 lines (97 loc) · 4.62 KB
Cool animation

Animation by Yup Nguyen

GO HTMX TailwindCSS Alpine.js

go-htmx

One way — not the way — to build full-stack Go apps with HTMX + Alpine.js.

A batteries-included starter framework that wires together Chi, Templ, HTMX 2, and Alpine.js into a coherent project structure. SQLite out of the box, Postgres/MySQL with one env-var change.

Note: Chi was chosen out of personal interest, not because it is the only option. The standard library alone can take you very far — here is a great talk showing exactly that.

Features

Package What it does
htmx/ Inspect every HTMX request header; set every response header (HX-Redirect, HX-Trigger, HX-Reswap…)
flash/ Stateless HMAC-signed cookie flash messages — no session store needed, survive HTMX redirects
validation/ Explicit form validation helpers (Required, MinLen, IsEmail, Matches, Unique)
middleware/ JWT stored in an HttpOnly cookie — Protect and Optional route guards, UserFromCtx helper
db/ database/sql connection + embedded SQL migration runner (auto-runs on startup, no CLI needed)
db/models/ User CRUD: GetByID, GetByUsername, GetByEmail, Create, Update, Delete
services/ Auth service (register / login / logout with bcrypt + JWT) and a base web-handler helper
views/ Templ layouts and pages wired to Tailwind CDN — swap in a build step when you're ready

Project layout

cmd/
  main.go          ← entry point: connect DB, run migrations, start server
  seed/main.go     ← optional database seeder
config/            ← env-based config loader
db/
  migrations/      ← SQL migrations (auto-applied on startup)
  models/          ← database model types + queries
htmx/              ← HTMX request/response helpers
flash/             ← cookie flash message helpers
middleware/        ← JWT auth middleware
routes/            ← route registration
services/          ← business logic
utils/             ← shared utilities
validation/        ← form validation
views/
  layouts/         ← base HTML layout, nav, flash
  pages/           ← home, login, register
static/            ← embedded static assets (HTMX, Alpine, Bootstrap JS)

Quick start

# 1. Clone
git clone https://github.com/livghit/go-htmx && cd go-htmx

# 2. Configure
cp example.env app.env
# Open app.env and set JWT_SECRET and FLASH_SECRET to long random strings:
#   openssl rand -hex 32

# 3. Run (with hot-reload)
make dev

# 4. Or build a binary
make build && ./bin/app

The server starts on :3000. The SQLite database is created automatically and migrations are applied on startup.

Make targets

Target Description
make dev Hot-reload via air
make run Run without hot-reload
make build Compile production binary to bin/app
make templ Regenerate Go code from .templ files
make migrate-up Apply pending migrations via goose CLI
make migrate-down Roll back the latest migration
make seed Seed the database
make lint Run golangci-lint
make test Run all tests
make clean Remove bin/ and app.db

Configuration

Copy example.env to app.env (never commit app.env).

APP_NAME="MyApp"
PORT=":3000"

DB_ENGINE=sqlite          # sqlite | postgres | mysql
DB_NAME=app.db

JWT_SECRET=change-me      # openssl rand -hex 32
JWT_EXPIRY=24             # hours

FLASH_SECRET=change-me    # openssl rand -hex 32

To use Postgres, set:

DB_ENGINE=postgres
DB_CONN=postgres://user:pass@localhost:5432/myapp?sslmode=disable

Contributing

Open a pull request or an issue — see Contributing.md for details.