Skip to content
Gasv0.10.0

start

Installation

  • 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.

In your Go module:

Terminal window
go get github.com/gasmod/gas

The core is enough for a working HTTP app. See the example on the home page.

Each module is its own Go module. Add only the ones you use:

Terminal window
go get github.com/gasmod/gas/config
go get github.com/gasmod/gas/log
go get github.com/gasmod/gas/database

All 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:

Terminal window
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.Z
go mod tidy

Avoid 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.

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__DSN sets the key database.dsn.
  • GAS_ENV picks the environment. It holds development, the default, testing, staging or production. Any other value fails cfg.Load, so a typo such as prod stops the app.
  • SQLite needs a driver. Import modernc.org/sqlite, or another driver registered as sqlite. 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.
Terminal window
go get modernc.org/sqlite
APP_DATABASE__DIALECT=sqlite APP_DATABASE__DSN=file:app.db go run .
INFO service initialized service=gas/database mode=sql dialect=sqlite
INFO server started environment=development addr=0.0.0.0:8080

curl localhost:8080 answers Hello, World!.

  • 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.
⌂ 换网址