README
¶
gin-kit
gin-kit is an opinionated Go framework built on Gin. Everything included, nothing hidden: a versioned runtime, an interactive project CLI, consistent HTTP contracts, SQL integrations, and explicit application architecture without a reflection-based dependency container.
The default runtime project type keeps generic infrastructure in the gin-kit module while leaving your routes, handlers, services, domains, repositories, configuration, migrations, and UI fully editable. A Standalone project type preserves the source-visible learning experience.
Install
With Go
go install github.com/Alfian57/gin-kit/cmd/gin-kit@latest
gin-kit requires Go 1.26 or newer when installed from source.
Prebuilt binaries
Download a binary for Linux, macOS, or Windows from the release page. Verify the downloaded archive before running it:
sha256sum -c checksums.txt --ignore-missing
gh attestation verify gin-kit_<version>_<os>_<arch>.tar.gz -R Alfian57/gin-kit
Check the installed version:
gin-kit --version
Create a project
gin-kit new my-project
The interactive installer asks for the project type, application mode, database, data-access layer, authentication, guided example, and Docker support.
Choose the default runtime project type for a thin application backed by the
versioned gin-kit runtime. Choose standalone when you want a Standalone project
with the infrastructure source included:
gin-kit new my-project --project-type standalone
For scripts, provide complete choices:
gin-kit new my-project \
--non-interactive \
--project-type runtime \
--module example.com/my-project \
--mode api \
--database sqlite \
--orm gorm
Every application starts with request IDs, secure recovery, security headers, spoof-resistant client addresses (forwarded headers are honored only from proxies you explicitly trust), body limits, graceful shutdown, database-backed readiness checks, and endpoint-class rate limiting. API responses use one stable envelope, including detailed field-level validation errors.
Project workflow
gin-kit run
gin-kit build
gin-kit check
gin-kit generate resource tasks
gin-kit db up
gin-kit explain architecture
The generated server can be built directly with go run ./cmd/server, and
migrations can be run with go run ./cmd/migrate up. Standalone projects are
self-contained; Runtime projects pin their gin-kit runtime version and can be built
without the gin-kit CLI installed.
Design principles
- Keep Gin and standard Go types accessible.
- Prefer constructors and explicit dependencies over magic.
- Hide generic runtime plumbing, not application behavior.
- Provide stable response and validation contracts by default.
- Keep SQL schema changes versioned and reviewable.
- Make application-owned generated code easy to delete or change.
- Treat AI agents as collaborators that must follow the same architecture and tests.
Documentation
The documentation site tracks the next gin-kit release from main:
alfian57.github.io/gin-kit.
Until the next runtime release is tagged, the latest GitHub release remains
the stable CLI.
Contributing
Participation is covered by the Code of Conduct.
Read CONTRIBUTING.md, AGENTS.md, and SECURITY.md before opening a pull request. Maintainers should also read docs/releasing.md.
License
gin-kit is released under the MIT License.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
doccheck
command
Command doccheck verifies gin-kit source documentation conventions.
|
Command doccheck verifies gin-kit source documentation conventions. |
|
gin-kit
command
Command gin-kit provides a gin-kit development command.
|
Command gin-kit provides a gin-kit development command. |
|
internal
|
|
|
cli
Package cli provides gin-kit cli implementation support.
|
Package cli provides gin-kit cli implementation support. |
|
Package runtime provides gin-kit's explicit application lifecycle and production-safe HTTP defaults on top of Gin.
|
Package runtime provides gin-kit's explicit application lifecycle and production-safe HTTP defaults on top of Gin. |
|
apptest
Package apptest provides small helpers for exercising a gin-kit application in tests and decoding its envelope responses.
|
Package apptest provides small helpers for exercising a gin-kit application in tests and decoding its envelope responses. |
|
auth
Package auth provides signed access and rotating refresh-token primitives.
|
Package auth provides signed access and rotating refresh-token primitives. |
|
authz
Package authz provides explicit, allowlist-style authorization decisions.
|
Package authz provides explicit, allowlist-style authorization decisions. |
|
browsertest
Package browsertest provides Playwright helpers for end-to-end browser tests against a gin-kit application.
|
Package browsertest provides Playwright helpers for end-to-end browser tests against a gin-kit application. |
|
cache
Package cache provides a small cache contract with in-memory and Redis drivers behind one small interface.
|
Package cache provides a small cache contract with in-memory and Redis drivers behind one small interface. |
|
config
Package config loads and validates environment configuration for gin-kit runtime applications and converts it into runtime options.
|
Package config loads and validates environment configuration for gin-kit runtime applications and converts it into runtime options. |
|
database
Package database provides explicit SQL, GORM, and sqlx connectors.
|
Package database provides explicit SQL, GORM, and sqlx connectors. |
|
devtools
Package devtools serves gin-kit's development dashboard: a request log, mail outbox, route list, redacted config report, and queue statistics behind a single mount point.
|
Package devtools serves gin-kit's development dashboard: a request log, mail outbox, route list, redacted config report, and queue statistics behind a single mount point. |
|
events
Package events provides a dependency-free, in-process, typed event bus.
|
Package events provides a dependency-free, in-process, typed event bus. |
|
factory
Package factory provides model factories for tests and seeders: define how a model is built once, then Make in-memory instances or Create persisted ones in tests and seeders.
|
Package factory provides model factories for tests and seeders: define how a model is built once, then Make in-memory instances or Create persisted ones in tests and seeders. |
|
flags
Package flags provides a small, in-memory set of boolean feature flags.
|
Package flags provides a small, in-memory set of boolean feature flags. |
|
httpx
Package httpx provides gin-kit httpx implementation support.
|
Package httpx provides gin-kit httpx implementation support. |
|
mail
Package mail provides transactional email with a fluent message builder, an SMTP driver, and a development log driver.
|
Package mail provides transactional email with a fluent message builder, an SMTP driver, and a development log driver. |
|
metrics
Package metrics provides opt-in Prometheus instrumentation for gin-kit applications.
|
Package metrics provides opt-in Prometheus instrumentation for gin-kit applications. |
|
oauth
Package oauth provides explicit OAuth 2.0 and OpenID Connect sign-in flows.
|
Package oauth provides explicit OAuth 2.0 and OpenID Connect sign-in flows. |
|
openapi
Package openapi builds OpenAPI 3.0.3 documents for gin-kit applications without annotations: every live route is documented from the router table, and operations described by generated code are enriched with typed schemas.
|
Package openapi builds OpenAPI 3.0.3 documents for gin-kit applications without annotations: every live route is documented from the router table, and operations described by generated code are enriched with typed schemas. |
|
password
Package password provides Argon2id password hashing with encoded parameters.
|
Package password provides Argon2id password hashing with encoded parameters. |
|
query
Package query provides allowlist-based filtering, sorting, and pagination for list endpoints, driven by bracketed query parameters.
|
Package query provides allowlist-based filtering, sorting, and pagination for list endpoints, driven by bracketed query parameters. |
|
queue
Package queue provides explicit background jobs with typed handler registration, an inline sync driver for development, and a Redis (asynq) driver for production with retries, delays, and graceful drain.
|
Package queue provides explicit background jobs with typed handler registration, an inline sync driver for development, and a Redis (asynq) driver for production with retries, delays, and graceful drain. |
|
realtime
Package realtime provides explicit, in-process fan-out over WebSocket and server-sent events.
|
Package realtime provides explicit, in-process fan-out over WebSocket and server-sent events. |
|
schedule
Package schedule provides cron-style task scheduling on robfig/cron with per-job panic recovery, optional overlap skipping, and graceful stop as an application runner.
|
Package schedule provides cron-style task scheduling on robfig/cron with per-job panic recovery, optional overlap skipping, and graceful stop as an application runner. |
|
session
Package session provides encrypted cookie sessions, one-shot flash messages, and CSRF protection for UI-mode applications.
|
Package session provides encrypted cookie sessions, one-shot flash messages, and CSRF protection for UI-mode applications. |
|
storage
Package storage provides a file storage abstraction with a path-confined local driver and an S3-compatible driver.
|
Package storage provides a file storage abstraction with a path-confined local driver and an S3-compatible driver. |
|
validation
Package validation provides gin-kit validation implementation support.
|
Package validation provides gin-kit validation implementation support. |
|
whatsapp
Package whatsapp sends approved WhatsApp Business Platform templates through Meta's Cloud API.
|
Package whatsapp sends approved WhatsApp Business Platform templates through Meta's Cloud API. |