Bun Starter Kit

Bun starter kitopen in new window consists of:

You can also check bun-realworld-appopen in new window which is a JSON API built with Bun starter kit.

App structure

The starter kit has the following structure:

├─ bunapp
│  └─ app.go
│  └─ config.go
│  └─ router.go
│  └─ start.go
│  └─ hook.go
│  └─ embed
│     └─ config
│        └─ dev.yaml
│        └─ test.yaml
├─ cmd
│  └─ bun
│     └─ main.go
│     └─ migrations
│        └─ main.go
│        └─ 20210505110026_init.go
├─ example
│  └─ init.go
│  └─ example_handler.go
│  └─ example_handler_test.go
├─ .gitignore
└─ go.mod

The main entrypoints are:

  • bunapp/app.go contains App struct that maintains the app state. For example, App.DB() creates *bun.DB.
  • bunapp/config.go contains the Config struct to parse YAML configuration, for example, bunapp/embed/config/dev.yaml.
  • cmd/bun/migrations contains database migrations.
  • example/init.go is the package entry point.

You should keep HTTP handlers and DB models in the same package, but split the app into logically isolated packages. Each package should have init.go file with the module initialization logic.

Starting the app

The kit provides convenience methods to start/stop the app:

func main() {
	ctx, app, err := bunapp.Start(ctx, "service_name", "environment_name")
	if err != nil {
	defer app.Stop()

It also provides hooks to execute custom code on the app start/stop. You usually add hooks from the init function in your module's init.go file.

func init() {
	bunapp.OnStart("hook.name", func(ctx context.Context, app *bunapp.App) error {
		app.Router().GET("/endpoint", handler)

		app.OnStop("hook.name", func(ctx context.Context, app *bunapp.App) error {

		return nil


The kit also provides a CLI to manage migrations:

go run cmd/bun/main.go

   bun db - manage database migrations

   bun db [global options] command [command options] [arguments...]

   init        create migration tables
   migrate     migrate database
   rollback    rollback the last migration group
   unlock      unlock migrations
   create_go   create a Go migration
   create_sql  create a SQL migration
   help, h     Shows a list of commands or help for one command

   --help, -h  show help (default: false)