Getting Started

Install the Kern Go web framework, create your first API server, and learn the core setup for routing, middleware, and production-ready request handling.

Prerequisites

Go 1.22 or higher: Kern leverages Go 1.22's enhanced routing features.
Basic understanding of Go and HTTP concepts.
A Go development environment set up.

Kern requires Go 1.22+ for the enhanced net/http.ServeMux pattern matching features. Please ensure your Go version is up to date (go version).

Installation

Install Kern using go get:

go get github.com/mobentum/kern

This will download Kern and add it to your go.mod file. Since Kern has zero dependencies, the installation is instant.

If you want structured logging via slog + zerolog, add the optional module:

go get github.com/mobentum/kern/extensions/xlog

If you want .env loading and environment binding, add the optional config module:

go get github.com/mobentum/kern/extensions/xconfig

If you want OpenAPI JSON + Swagger UI endpoints, add the optional OpenAPI module:

go get github.com/mobentum/kern/extensions/xopenapi

If you want struct validation via go-playground/validator, add the optional validation module:

go get github.com/mobentum/kern/extensions/xvalidator

If you want distributed tracing with OpenTelemetry, add the optional tracing module:

go get github.com/mobentum/kern/extensions/xotel

Your First Application

1. Create a Project

mkdir myapp
cd myapp
go mod init myapp
go get github.com/mobentum/kern

2. Write the Code

Create a file named main.go:

package main

import (
    "github.com/mobentum/kern"
)

func main() {
    // Initialize a new kern application
    app := kern.New()

    // Add global middleware (optional but recommended)
    app.Use(kern.Logger())
    app.Use(kern.Recovery())

    // Define a simple GET route
    app.GET("/", func(c *kern.Context) {
        c.Text(200, "Hello, World!")
    })

    // Define a route with a path parameter
    app.GET("/hello/{name}", func(c *kern.Context) {
        name := c.Param("name")
        c.JSON(200, map[string]string{
            "message": "Hello " + name,
        })
    })

    // Start the server on port 8080
    app.Run(":8080")
}

3. Run the Application

go run main.go

You should see output indicating the server has started. Open your browser to http://localhost:8080 to see "Hello, World!".

Try visiting http://localhost:8080/hello/kern to see the JSON response:

{"message": "Hello kern"}

Why start with Kern?

You want a Go web framework that stays close to net/http.
You want low framework overhead with predictable request/response behavior.
You want middleware, routing, and request helpers without taking on a large dependency tree.

Running with TLS

Kern makes it easy to serve over HTTPS using RunTLS, which is crucial for modern secure web applications.

// Start an HTTPS server
err := app.RunTLS(":8443", "cert.pem", "key.pem")
if err != nil {
    panic(err)
}

Using Defaults

For a quick start with sensible defaults (Logger and Recovery middleware pre-configured), use kern.Default():

app := kern.Default() 
// Equivalent to:
// app := kern.New()
// app.Use(kern.Logger())
// app.Use(kern.Recovery())

Structured Logging with xlog (Optional)

kern supports slog directly in both app lifecycle logs and request logger middleware.

package main

import (
    "github.com/mobentum/kern"
    "github.com/mobentum/kern/extensions/xlog"
)

func main() {
    app := kern.New(
        kern.WithSlogLogger(xlog.NewLogger(xlog.Config{Format: "json"})),
    )

    app.Use(kern.Logger(kern.LoggerConfig{
        SLogger: xlog.NewLogger(xlog.Config{Format: "console"}),
        Fields: map[string]interface{}{
            "service": "myapp",
            "env":     "dev",
        },
    }))

    app.GET("/", func(c *kern.Context) {
        _ = c.Text(200, "ok")
    })

    _ = app.Run(":8080")
}

Configuration with xconfig (Optional)

Use the optional xconfig module when you want .env file loading and typed environment access.

package main

import (
    "github.com/mobentum/kern/extensions/xconfig"
)

type Config struct {
    Host string
    Port int
}

func loadConfig() (*Config, error) {
    loader, err := xconfig.New(
        xconfig.WithPrefix("APP"),
        xconfig.WithDotEnv(".env"),
    )
    if err != nil {
        return nil, err
    }

    port, err := loader.Int("PORT", 8080)
    if err != nil {
        return nil, err
    }

    return &Config{
        Host: loader.String("HOST", "127.0.0.1"),
        Port: port,
    }, nil
}

OpenAPI with xopenapi (Optional)

Use the optional xopenapi module when you want explicit API docs endpoints without reflection.

package main

import (
    "net/http"

    "github.com/mobentum/kern/extensions/xopenapi"
)

xopenapi.Register(app, xopenapi.Config{
    Info: xopenapi.Info{Title: "My API", Version: "1.0.0"},
    Routes: []xopenapi.Route{
        {
            Method:      http.MethodGet,
            Path:        "/hello/{name}",
            Summary:     "Get greeting",
            OperationID: "getGreeting",
            Tags:        []string{"greetings"},
        },
    },
})

// Docs endpoints:
// - /openapi.json
// - /docs

Scaffolding with kern-cli

Kern provides a CLI tool to scaffold new projects:

# Install the CLI
go install github.com/mobentum/kern-cli@latest

# Create a new project
kern-cli new myapp

# Create a REST API project with config, logging, and health checks
kern-cli new myapi -template rest-api

The CLI generates a ready-to-run project with go.mod, main.go, middleware setup, and development helpers.

What's Next?

Now that you have your first app running:

Routing - Learn about route groups, path parameters, and static files
Context API - Handle requests and responses
Middleware - Add authentication, logging, CORS, and more
Middleware Catalog - Browse first-party middleware options
Migration Guide - Adopt new routing and middleware capabilities safely
Examples - Check the examples folder for complete, runnable examples