Getting started

Requirements

Go 1.26 or newer. Gas is pre-1.0, so minor versions may contain breaking changes; see the changelog.

Your first app

1. Install the core package.

   go get github.com/gasmod/gas

2. Serve a route.

   main.go

   import (
     "log"
     "net/http"
   
     "github.com/gasmod/gas"
   )
   
   func main() {
     app := gas.NewApp()
   
     app.Router().Handle("", http.MethodGet, "/", func(ctx gas.Context) error {
       return ctx.Text(http.StatusOK, "Hello, World!")
     })
   
     if err := app.Run(); err != nil {
       log.Fatal(err)
     }
   }

3. Run it.

   go run .
   # listening on 0.0.0.0:8080

gas.NewApp builds a router, an event bus, and a DI container. Run initializes every registered service, applies pending migrations, executes ready hooks, starts the HTTP server, and blocks until a shutdown signal arrives. On shutdown it closes services in reverse initialization order.

Adding a module

Modules are registered as services. Most of them ask the container for a gas.ConfigProvider and a gas.Logger, so those go in first.

main.go

cfg := config.New(config.WithProvider(providers.NewEnvProvider()))
if err := cfg.Load(); err != nil {
  log.Fatal(err)
}

main.go

app := gas.NewApp(
  // Infrastructure every module draws on.
  gas.WithServiceInstance[gas.ConfigProvider](cfg),
  gas.WithSingletonService[gas.Logger](gaslog.NewSlogLogger()),

  // Modules, registered under the provider interface your services inject.
  gas.WithSingletonService[gas.StorageProvider](storages3.New()),
)

Register under the interface, not the concrete type

The container resolves dependencies by exact type. A service registered as *s3.Service will not satisfy a dependency declared as gas.StorageProvider, and startup fails with no registration for gas.StorageProvider. Register infrastructure under its provider interface and your own services under their concrete type. See Services and DI.

Where to go next

• Concepts explains services, lifetimes, and ownership tracking.
• Modules lists everything you can bolt on.
• Examples has five runnable applications, from a bare hello world to a full API server.
• pkg.go.dev is the API reference.