Installation

Requirements

Go 1.27.3 or newer. The core and every module declare go 1.27.3 in their go.mod.

Gas is pre-1.0, so a minor version may contain breaking changes. Read the changelog before upgrading. These docs describe v0.6.0.

Install the core

In a Go module, add the core package:

go get github.com/gasmod/gas

The core holds the app, the DI container, the router, handlers, middleware, errors, and events. It is enough for an HTTP app with no infrastructure.

Add modules

Everything else is a separate Go module under github.com/gasmod/gas/, so an app adds only the modules it uses. For example, configuration, logging, a database, and migrations:

go get github.com/gasmod/gas/config \
  github.com/gasmod/gas/log \
  github.com/gasmod/gas/database \
  github.com/gasmod/gas/migrate

The modules are auth, cache, config, database, email, log, migrate, queue, storage, template, and ui. Modules overview says what each one is for, and each module’s page lists what it needs from the container.

Database drivers

gas/database does not import a SQLite driver. For SQLite, add one as well, such as modernc.org/sqlite, and import it for its side effect. The tutorial does this, and Database covers the PostgreSQL drivers.

The smallest app

Create a module with one file:

mkdir hello && cd hello
go mod init example.com/hello
go get github.com/gasmod/gas

main.go

import (
  "log"
  "net/http"

  "github.com/gasmod/gas"
)

func main() {
  app := gas.NewApp()

  app.Router().Get(nil, "/", func(ctx gas.Context) error {
    return ctx.Text(http.StatusOK, "Hello, Gas!")
  })

  if err := app.Run(); err != nil {
    log.Fatal(err)
  }
}

gas.NewApp creates the app with its router, event bus, and DI container. Router().Get registers a handler for GET /. Its first argument is the service that owns the route; nil hands it to the router itself, which is why the log below names gas/router. A service passes itself, which ties the route to that service (see Ownership and teardown). Run initializes the registered services, starts the HTTP server, and blocks until the process gets SIGINT or SIGTERM.

Check that it works

Run it:

go run .

... WARN no logger registered reason="no registration for gas.Logger"
... INFO route registered service=gas/router method=GET path=/
... INFO server started environment="" addr=0.0.0.0:8080

No gas.Logger is registered, so Gas warns once and logs through slog.Default(). The server listens on 0.0.0.0:8080, the default Server.Host and Server.Port.

From another terminal:

curl localhost:8080/

Hello, Gas!

Stop the app with Ctrl+C. It closes its services and exits:

... INFO shutdown signal received signal=interrupt
... INFO closing service service=gas/router
... INFO closing service service=gas/eventbus
... INFO shutdown complete

Next

The tutorial builds a complete JSON API on SQLite, with configuration, logging, migrations, API keys, and a test. Project structure shows how to lay out a larger app.