start
Installation
Requirements
Section titled “Requirements”- Go 1.27.0 or newer. Use 1.27.4 or newer in production: earlier 1.27 releases can crash an HTTP/1 server (GO-2026-6859).
That is all the core needs. Some modules talk to outside services, such as PostgreSQL, Valkey or AWS, and only need them when you use those backends.
Add the core
Section titled “Add the core”In your Go module:
go get github.com/gasmod/gasThe core is enough for a working HTTP app. See the example on the home page.
Add modules
Section titled “Add modules”Each module is its own Go module. Add only the ones you use:
go get github.com/gasmod/gas/configgo get github.com/gasmod/gas/loggo get github.com/gasmod/gas/databaseAll modules share one version and are released together. Keep them on the same version as the core.
To upgrade to vX.Y.Z, set every Gas module in your go.mod to it, then
tidy:
go mod edit \ -require=github.com/gasmod/gas@vX.Y.Z \ -require=github.com/gasmod/gas/config@vX.Y.Z \ -require=github.com/gasmod/gas/log@vX.Y.Z \ -require=github.com/gasmod/gas/database@vX.Y.Zgo mod tidyAvoid one go get per module, such as go get github.com/gasmod/gas@vX.Y.Z
followed by go get github.com/gasmod/gas/config@vX.Y.Z. Once the core at the
new version is in your module cache, go get of a module at that version can
fail with “module github.com/gasmod/gas@vX.Y.Z found, but does not contain
package github.com/gasmod/gas/config” without asking the proxy. A single
go get naming every module fails the same way if the core is already cached.
Register modules
Section titled “Register modules”Modules are services. You register them with the App, and its container builds them, wires their dependencies and runs their lifecycle. This app reads its settings from environment variables, logs through slog, and opens a SQLite database:
package main
import ( "context" "log" "net/http"
"github.com/gasmod/gas" "github.com/gasmod/gas/config" "github.com/gasmod/gas/database" gaslog "github.com/gasmod/gas/log" _ "modernc.org/sqlite")
func main() { cfg := config.New(config.WithProvider( config.NewEnvProvider(config.WithEnvPrefix("APP_")), )) if err := cfg.Load(); err != nil { log.Fatal(err) }
app := gas.NewApp( gas.WithServiceInstance[gas.ConfigProvider](cfg), gas.WithSingletonService[gas.Logger](gaslog.NewSlogLogger()), gas.WithSingletonService[gas.DatabaseProvider](database.New()), )
app.Router().Handle(nil, http.MethodGet, "/", func(ctx gas.Context) error { return ctx.Text(http.StatusOK, "Hello, World!") })
if err := app.Run(context.Background()); err != nil { log.Fatal(err) }}A few things to know:
- Configuration needs a prefix. The environment provider only reads
variables that start with the prefix you give it, here
APP_. Other tools’ variables, such as their API keys, stay out of your config. - Nested keys use
__.APP_DATABASE__DSNsets the keydatabase.dsn. GAS_ENVpicks the environment. It holdsdevelopment, the default,testing,stagingorproduction. Any other value failscfg.Load, so a typo such asprodstops the app.- SQLite needs a driver. Import
modernc.org/sqlite, or another driver registered assqlite. PostgreSQL and MySQL drivers come with the database module. - Modules log through a
gas.Logger. Register one, as above. The container resolves dependencies, so the order of registrations does not matter.
Run it
Section titled “Run it”go get modernc.org/sqliteAPP_DATABASE__DIALECT=sqlite APP_DATABASE__DSN=file:app.db go run .INFO service initialized service=gas/database mode=sql dialect=sqliteINFO server started environment=development addr=0.0.0.0:8080curl localhost:8080 answers Hello, World!.
Next steps
Section titled “Next steps”- Project layout: where the entry point, the wiring, the modules and their migrations go as the app grows.
- Core: services, routing, handlers and middleware.
- config: every provider and how values bind to structs.
- database: dialects, connection settings and transactions.
- llms.txt: these docs for LLMs and coding
agents. Every page is also served as Markdown, at its URL plus
index.md.