Lokstra

Modern Go Web Framework with Declarative Service Management

Quick Start • Features • Examples • Documentation • GitHub

What is Lokstra?

Lokstra is a versatile Go web framework that works in two ways:

🎯 Track 1: As a Router (Like Echo, Gin, Chi)

Use Lokstra as a fast, flexible HTTP router with elegant middleware support. Perfect when you just need routing without the complexity of DI frameworks.

r := lokstra.NewRouter("api")
r.GET("/", func() string {
    return "Hello, Lokstra!"
})
app := lokstra.NewApp("hello", ":3000", r)
app.Run(30 * time.Second)

🏗️ Track 2: As a Business Application Framework (Like NestJS, Spring Boot)

Leverage the full framework with lazy dependency injection, auto-generated routers, and configuration-driven deployment. Build enterprise applications that scale from monolith to microservices.

// Define services in YAML
service-definitions:
  user-service:
    type: user-service-factory
    depends-on: [database]

// Service-level lazy loading - service created on first access
userService := service.LazyLoad[*UserService]("user-service")
users := userService.MustGet().GetAll()

Choose your path:

• 🚀 Need a Router? → Read Router Guide (like Echo/Gin)
• 🏢 Building Enterprise Apps? → Read Framework Guide (like NestJS/Spring)
• � New to Lokstra? → Start with Introduction

Quick Start

Install Lokstra CLI

go install github.com/primadi/lokstra/cmd/lokstra@latest

Create New Project

# Interactive template selection
lokstra new myapp

# Or choose specific template
lokstra new myapp -template 02_app_framework/01_medium_system

Install Framework Library

go get github.com/primadi/lokstra

Hello World (30 seconds)

package main

import "github.com/primadi/lokstra"

func main() {
    r := lokstra.NewRouter("api")
    
    r.GET("/", func() string {
        return "Hello, Lokstra!"
    })
    
    r.GET("/ping", func() string {
        return "pong"
    })
    
    app := lokstra.NewApp("hello", ":3000", r)
    if err := app.Run(30 * time.Second); err != nil {
      log.Fatal(err)
    }
}

With Services & Configuration (2 minutes)

1. Define configuration (config.yaml):

service-definitions:
  user-service:
    type: user-service-factory

deployments:
  production:
    servers:
      api:
        base-url: https://api.example.com
        addr: ":8080"
        published-services: [user-service]

2. Register factory (one-time setup):

lokstra_registry.RegisterServiceType("user-service-factory", 
    func() any { return service.NewUserService() }, nil)

3. Use anywhere (zero overhead after first access):

var userService = service.LazyLoad[*UserService]("user-service")

func handler() {
    users := userService.MustGet().GetAll()  // Loaded once, cached forever
}

👉 Full Tutorial

Key Features

🎯 Service-Level Lazy Loading

Type-safe service loading with zero overhead. Services created only when needed, dependencies eagerly resolved.

// Define once, use everywhere
var db = service.LazyLoad[*Database]("database")
var cache = service.LazyLoad[*Cache]("cache")

// Service loaded on first access, cached forever
users := db.MustGet().GetAll()

Benefits:

• No initialization order issues
• Thread-safe via sync.Once
• Memory efficient
• Fail-fast with clear errors

Learn More →

🔄 Auto-Generated Routers

Generate REST APIs from service definitions automatically.

service-definitions:
  user-service:
    type: user-service-factory

deployments:
  production:
    servers:
      api:
        published-services: [user-service]  # Auto-creates REST router!

Generated routes:

GET    /users       → List all users
GET    /users/{id}  → Get user by ID
POST   /users       → Create user
PUT    /users/{id}  → Update user
DELETE /users/{id}  → Delete user

With overrides:

router-definitions:
  user-service-router:
    path-prefix: /api/v1
    path-rewrites:
      - pattern: "^/api/v1/(.*)$"
        replacement: "/api/v2/$1"
    middlewares: [auth, logging]
    hidden: [InternalMethod]

Learn More →

🏗️ Flexible Deployment Topologies

One codebase, multiple deployment strategies. Switch from monolith to microservices without code changes.

Monolith:

deployments:
  production:
    servers:
      all-in-one:
        base-url: https://api.example.com
        published-services: [user-service, order-service, payment-service]

Microservices:

deployments:
  production:
    servers:
      user-api:
        base-url: https://user-api.example.com
        published-services: [user-service]
      
      order-api:
        base-url: https://order-api.example.com
        published-services: [order-service]

Same code, different topology!

Learn More →

🛣️ Path Rewrites & Overrides

Powerful URL transformation without touching code.

router-definitions:
  api-router:
    path-rewrites:
      - pattern: "^/api/v1/(.*)$"
        replacement: "/api/v2/$1"
    middlewares: [auth, rate-limiter]

Use cases:

• API versioning
• Multi-tenant paths
• A/B testing
• Legacy URL migration

Learn More →

📝 Type-Safe Request Binding

Automatic validation with struct tags. Lokstra automatically injects and validates parameters.

type CreateUserParams struct {
    Name  string `json:"name" validate:"required"`
    Email string `json:"email" validate:"required,email"`
    Age   int    `json:"age" validate:"min=18,max=100"`
}

// Parameters automatically injected and validated!
func createUser(ctx *request.Context, params *CreateUserParams) error {
    // params are already validated and ready to use
    user := db.CreateUser(params.Name, params.Email, params.Age)
    return ctx.Api.Ok(user)
}

No manual binding code needed! Lokstra handles:

• JSON/Form parsing
• Validation via struct tags
• Clear error messages on failure

Learn More →

🚀 Lokstra CLI

Create new projects from templates in seconds!

# Install CLI
go install github.com/primadi/lokstra/cmd/lokstra@latest

# Create project (interactive)
lokstra new myapp

# Create with specific template
lokstra new blog-api -template 02_app_framework/01_medium_system

# Generate code for Enterprise templates
lokstra autogen ./myproject

Available Templates

Router Patterns (Learning & Simple APIs):

• 01_router/01_router_only - Pure routing basics
• 01_router/02_single_app - Production single app
• 01_router/03_multi_app - Multiple apps server

Framework Patterns (Production Apps):

• 02_app_framework/01_medium_system - Domain-driven (2-10 entities)
• 02_app_framework/02_enterprise_modular - DDD with bounded contexts
• 02_app_framework/03_enterprise_router_service - Annotation-based enterprise

What CLI Does Automatically

✅ Downloads template from GitHub
✅ Fixes all import paths
✅ Runs go mod init
✅ Runs go mod tidy
✅ Ready to run immediately!

📖 Full CLI Documentation →

Examples

📚 Introduction & Examples

Quick Examples - Get started in minutes:

• Hello World - Minimal 10-line setup
• JSON API - REST API responses
• CRUD API - Complete service example with lazy DI
• Multi-Deployment - Monolith vs microservices

Comparing Approaches:

• Code vs Config - When to use which approach
• Architecture Overview - Framework design principles

🎓 Essential Guides

Step-by-step learning path:

1. Quick Start - Get up and running in 5 minutes
2. Service Management - Master lazy dependency injection
3. Routing & Handlers - Request handling patterns
4. Configuration - YAML setup and environment management

Each guide includes:

• Clear explanations
• Working code examples
• Best practices
• Common pitfalls to avoid

📖 API Reference

Complete technical documentation:

• Registry API
  • Service Registration
  • Router Registration
• Configuration
  • YAML Schema - Complete reference
  • Deployment Patterns - Topology strategies

Advanced Topics:

• Auto-generated routers
• Path rewrites & overrides
• Multi-environment deployments
• Remote service integration

Why Lokstra?

🎯 Two Ways to Use Lokstra

Use as Router Only (Track 1)

Compare with Echo, Gin, Chi, Fiber:

// Just routing - no DI, no config files
r := lokstra.NewRouter("api")
r.GET("/users", getUsersHandler)
r.Use(cors.Middleware("*")

app := lokstra.NewApp("api", ":8080", r)
if err := app.Run(30 * time.Second); err != nil {
  log.Fatal(err)
}

✅ Flexible handler signatures (29+ forms!)
✅ Clean middleware support
✅ Group routing for API versioning
✅ No framework lock-in

→ Router Guide

Use as Full Framework (Track 2)

Compare with NestJS, Spring Boot, Uber Fx:

# config.yaml
service-definitions:
  user-service:
    type: user-service-factory
    depends-on: [database]

deployments:
  production:
    servers:
      api:
        published-services: [user-service]  # Auto-router!

// Type-safe lazy DI
var userService = service.LazyLoad[*UserService]("user-service")

func handler() {
    users := userService.MustGet().GetAll()
}

✅ Lazy dependency injection (type-safe)
✅ Auto-generated REST routers from services
✅ Configuration-driven deployment
✅ Monolith → Microservices without code changes

→ Framework Guide

vs Traditional DI Frameworks

• ✅ Type-safe with generics (no any casting)
• ✅ Zero reflection overhead in hot path
• ✅ Optional YAML (start with code, scale with config)
• ✅ No code generation required

vs Manual Dependency Management

• ✅ No initialization order issues
• ✅ Declarative service definitions
• ✅ Environment-based configuration
• ✅ Easy testing (mock via registry)

vs Other Go Frameworks

• ✅ Lazy loading by default (memory efficient)
• ✅ Auto-generated routers from services
• ✅ Multi-deployment support (monolith → microservices)
• ✅ Path rewrites via YAML (no code changes)

Community & Support

• 📖 Full Documentation - Complete guide
• 🤖 AI Agent Guide - For AI assistants (Copilot, Claude, ChatGPT)
• ⚡ Quick Reference - Cheatsheet for common patterns
• 💡 Examples - Working code samples
• 🐛 GitHub Issues - Bug reports & features
• 🗺️ Roadmap - Upcoming features

Quick Links