README
¶
Irmik
Irmik is a Go framework for Gin applications with server-rendered pages, sessions, security helpers, and opt-in packages.
Core promise: file-based app/ routes, SSR/SSG/ISR render modes, and
security-minded admin helpers (opt-in session/CSRF/RBAC/HTMX).
It is for:
- Admin and internal tools that need sessions, CSRF, RBAC, and a JSON API.
- Server-rendered sites with file-based routes.
- Teams that want optional database, upload, realtime, and queue packages.
v0.1.1: opt-in responsive images (imagex.Pipeline, upload variants) and a
development overlay (badge, errors, live reload with irmik dev). See the
changelog.
Quick start
go install github.com/boracomet/go-irmik/cmd/irmik@latest
irmik new hello
cd hello && go run .
See examples/admin for the complete admin and API example.
cfg := config.Default()
app, err := irmik.New(cfg)
if err != nil { panic(err) }
app.Engine.GET("/", handler)
For production, set IRMIK_JWT_SECRET to a strong random value. Empty and demo
JWT secrets are rejected outside development. Do not store access tokens in
localStorage; use an httpOnly BFF cookie or a server session.
Core lives in the root module:
go get github.com/boracomet/go-irmik
That does not download AWS, GORM, the OpenTelemetry SDK, gRPC, or asynq. SQL drivers, Redis, migrate, and similar opt-in packages that still live in the root module are downloaded with it; they are linked only if you import them.
Heavy catalog backends are nested modules. Import paths are unchanged;
go get the nested path when you need one:
go get github.com/boracomet/go-irmik/irmik/db/gormx
go get github.com/boracomet/go-irmik/irmik/storage/s3x
go get github.com/boracomet/go-irmik/irmik/observe/otelx
go get github.com/boracomet/go-irmik/irmik/grpcx
go get github.com/boracomet/go-irmik/irmik/queue/asynqx
Nested modules are versioned with their own tags (for example
irmik/db/gormx/v0.2.0) once that cut is tagged. Until then, pin a commit or
@main. See catalog.
Links: catalog · auth · security · devtools · comparison · changelog · examples
License
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
irmik
command
|
|
|
examples
|
|
|
admin
command
|
|
|
auth
command
|
|
|
blog
command
|
|
|
realtime
command
|
|
|
internal
|
|
|
build
Package build pre-renders SSG / ISR / Static / CSR routes into out/.
|
Package build pre-renders SSG / ISR / Static / CSR routes into out/. |
|
cli
Package cli implements the irmik command-line interface.
|
Package cli implements the irmik command-line interface. |
|
hmr
Package hmr watches the filesystem and notifies on template/route changes.
|
Package hmr watches the filesystem and notifies on template/route changes. |
|
Package irmik is a Gin meta-framework for server-rendered pages, sessions, and an opt-in catalog (auth, admin, upload, queues, images, and more).
|
Package irmik is a Gin meta-framework for server-rendered pages, sessions, and an opt-in catalog (auth, admin, upload, queues, images, and more). |
|
admin
Package admin provides thin HTMX CRUD conventions for admin UIs: session flash ↔ HX-Trigger helpers, pagination re-export patterns, and embeddable table/form/delete-confirm template snippets.
|
Package admin provides thin HTMX CRUD conventions for admin UIs: session flash ↔ HX-Trigger helpers, pagination re-export patterns, and embeddable table/form/delete-confirm template snippets. |
|
api
Package api provides thin REST helpers: JSON responses, a standard error envelope, and an /api/v1 group mount.
|
Package api provides thin REST helpers: JSON responses, a standard error envelope, and an /api/v1 group mount. |
|
audit
Package audit provides a simple audit-log interface with slog and memory sinks.
|
Package audit provides a simple audit-log interface with slog and memory sinks. |
|
auth
Package auth provides session login helpers, JWT access tokens, password hashing, OAuth provider stubs, and Gin middleware.
|
Package auth provides session login helpers, JWT access tokens, password hashing, OAuth provider stubs, and Gin middleware. |
|
cache/redisx
Package redisx registers a Redis-backed cache.Store.
|
Package redisx registers a Redis-backed cache.Store. |
|
compress
Package compress provides Gin middleware for response compression.
|
Package compress provides Gin middleware for response compression. |
|
compress/brotlix
Package brotlix provides optional Brotli Gin middleware.
|
Package brotlix provides optional Brotli Gin middleware. |
|
content
Package content loads Markdown collections with YAML/TOML/JSON frontmatter.
|
Package content loads Markdown collections with YAML/TOML/JSON frontmatter. |
|
cors
Package cors provides a lean CORS middleware for Gin (no heavy dependency).
|
Package cors provides a lean CORS middleware for Gin (no heavy dependency). |
|
csrf
Package csrf provides CSRF token generation and Gin middleware for cookie/session-backed forms.
|
Package csrf provides CSRF token generation and Gin middleware for cookie/session-backed forms. |
|
db
Package db opens and wraps database/sql connections for Irmik apps.
|
Package db opens and wraps database/sql connections for Irmik apps. |
|
db/mysql
Package mysql registers the MySQL database/sql driver.
|
Package mysql registers the MySQL database/sql driver. |
|
db/postgres
Package postgres registers the pgx database/sql driver for PostgreSQL.
|
Package postgres registers the pgx database/sql driver for PostgreSQL. |
|
db/sqlite
Package sqlite registers the pure-Go SQLite driver (modernc.org/sqlite).
|
Package sqlite registers the pure-Go SQLite driver (modernc.org/sqlite). |
|
devtools
Package devtools injects a development-only overlay (badge, errors, live reload).
|
Package devtools injects a development-only overlay (badge, errors, live reload). |
|
forms
Package forms provides form parse/validate glue and CSRF field HTML helpers.
|
Package forms provides form parse/validate glue and CSRF field HTML helpers. |
|
fsutil
Package fsutil provides small filesystem helpers shared by build, cache, and tooling.
|
Package fsutil provides small filesystem helpers shared by build, cache, and tooling. |
|
health
Package health provides named readiness dependency checks (DB, Redis, custom).
|
Package health provides named readiness dependency checks (DB, Redis, custom). |
|
htmx
Package htmx — quick reference for admin handlers:
|
Package htmx — quick reference for admin handlers: |
|
imagex
Package imagex provides image decode/resize/encode helpers and an opt-in responsive-image pipeline for SSR pages and uploads.
|
Package imagex provides image decode/resize/encode helpers and an opt-in responsive-image pipeline for SSR pages and uploads. |
|
island
Package island wires React/Vite islands into html/template pages.
|
Package island wires React/Vite islands into html/template pages. |
|
mail
Package mail defines a small email Sender interface with a net/smtp implementation.
|
Package mail defines a small email Sender interface with a net/smtp implementation. |
|
meta
Package meta holds page rendering mode and metadata shared by router and app.
|
Package meta holds page rendering mode and metadata shared by router and app. |
|
migrate
Package migrate runs versioned SQL migrations using golang-migrate.
|
Package migrate runs versioned SQL migrations using golang-migrate. |
|
observe
Package observe provides structured slog helpers for Irmik apps.
|
Package observe provides structured slog helpers for Irmik apps. |
|
openapi
Package openapi provides a lightweight OpenAPI 3 document builder and Gin serve helper.
|
Package openapi provides a lightweight OpenAPI 3 document builder and Gin serve helper. |
|
paginate
Package paginate parses list query params (page, per_page, sort, order, q) with clamped limits and SQL-friendly Offset/Limit plus whitelist OrderBy.
|
Package paginate parses list query params (page, per_page, sort, order, q) with clamped limits and SQL-friendly Offset/Limit plus whitelist OrderBy. |
|
proxy
Package proxy provides a small reverse-proxy helper for Gin using httputil.
|
Package proxy provides a small reverse-proxy helper for Gin using httputil. |
|
queue
Package queue provides a small job-queue interface and an in-memory implementation with a worker Run loop.
|
Package queue provides a small job-queue interface and an in-memory implementation with a worker Run loop. |
|
rbac
Package rbac provides a simple role/permission registry and Gin middleware.
|
Package rbac provides a simple role/permission registry and Gin middleware. |
|
rbac/store
Package store provides opt-in persistence for irmik/rbac.
|
Package store provides opt-in persistence for irmik/rbac. |
|
render
Package render provides an html/template engine with layouts, partials, and an island helper stub for the Vite/React island package to replace.
|
Package render provides an html/template engine with layouts, partials, and an island helper stub for the Vite/React island package to replace. |
|
router
Package router discovers file-based app/ routes and binds them to Gin with SSR / SSG / ISR / Static / CSR handlers.
|
Package router discovers file-based app/ routes and binds them to Gin with SSR / SSG / ISR / Static / CSR handlers. |
|
scheduler
Package scheduler provides an opt-in job registry with fixed intervals and timezone-aware cron (robfig/cron/v3).
|
Package scheduler provides an opt-in job registry with fixed intervals and timezone-aware cron (robfig/cron/v3). |
|
secrets
Package secrets provides a small secret Provider interface with env and file backends.
|
Package secrets provides a small secret Provider interface with env and file backends. |
|
seo
Package seo builds page meta tags, JSON-LD, sitemaps, and robots.txt.
|
Package seo builds page meta tags, JSON-LD, sitemaps, and robots.txt. |
|
session/redisx
Package redisx registers a Redis-backed session.Store.
|
Package redisx registers a Redis-backed session.Store. |
|
slug
Package slug converts titles and paths into URL-safe slugs.
|
Package slug converts titles and paths into URL-safe slugs. |
|
sse
Package sse provides Server-Sent Events helpers for Gin handlers.
|
Package sse provides Server-Sent Events helpers for Gin handlers. |
|
storage
Package storage defines a small object-storage interface with a local filesystem implementation.
|
Package storage defines a small object-storage interface with a local filesystem implementation. |
|
testkit
Package testkit provides HTTP test helpers for Gin and Irmik-style apps.
|
Package testkit provides HTTP test helpers for Gin and Irmik-style apps. |
|
tmplfunc
Package tmplfunc provides shared html/template helpers for Irmik render engines.
|
Package tmplfunc provides shared html/template helpers for Irmik render engines. |
|
upload
Package upload provides multipart file upload helpers with size and MIME limits.
|
Package upload provides multipart file upload helpers with size and MIME limits. |
|
validate
Package validate provides request/struct validation helpers for Gin, built on go-playground/validator.
|
Package validate provides request/struct validation helpers for Gin, built on go-playground/validator. |
|
ws
Package ws provides WebSocket upgrade helpers and a room-aware Hub for Gin.
|
Package ws provides WebSocket upgrade helpers and a room-aware Hub for Gin. |
Click to show internal directories.
Click to hide internal directories.