modkit

A Go framework for building modular backend services, inspired by NestJS.

Note: modkit is in early development. Read the Stability and Compatibility Policy before adopting in production.

modkit brings NestJS-style module organization to Go—without reflection, decorators, or magic. Define modules with explicit imports, providers, controllers, and exports. The kernel builds a dependency graph, enforces visibility, and bootstraps your app deterministically.

⭐ If modkit helps you build modular services, consider giving it a star!

What it does

modkit takes module definitions and deterministically bootstraps a dependency graph into runnable controllers:

flowchart LR
A["Module definitions\n(imports, providers, controllers, exports)"] --> B["Kernel\n(graph + visibility)"]
B --> C["Container\n(lazy singletons)"]
C --> D["Controllers"]
D --> E["HTTP adapter\n(chi router)"]

Loading

• Module system: explicit imports / exports boundaries
• Explicit DI: resolve via tokens (module.Get[T](r, token)), no reflection
• Visibility enforcement: only exported tokens are accessible to importers
• Deterministic bootstrap: predictable init order with clear errors
• Thin HTTP adapter: register controllers on a chi router

Why modkit?

modkit is a Go-idiomatic alternative to decorator-driven frameworks. It keeps wiring explicit, avoids reflection, and makes module boundaries and dependencies visible in code.

If you want...	modkit gives you...
NestJS-style modules in Go	imports, providers, controllers, exports
Explicit dependency injection	String tokens + resolver, no reflection
Debuggable bootstrap	Deterministic graph construction with clear errors
Minimal framework overhead	Thin HTTP adapter on chi, no ORM, no config magic

Compared to Other Go Frameworks

If you use...	modkit is different because...
google/wire	modkit adds module boundaries + visibility enforcement
uber-go/fx	No reflection, explicit Build functions
samber/do	Full module system with imports/exports
No framework	Structured module organization without boilerplate

See the full comparison for details.

Requirements

• Go 1.25.x (CI pinned to 1.25.7)

Installation

Library

go get github.com/go-modkit/modkit

CLI Tool

Install the modkit CLI using go install:

go install github.com/go-modkit/modkit/cmd/modkit@latest

Or download a pre-built binary from the releases page.

Quickstart (CLI)

Use this as the canonical first-run path:

modkit new app myapp
cd myapp
go run cmd/api/main.go
curl http://localhost:8080/health

Expected output:

ok

If this path fails, use the troubleshooting section in Getting Started.

Quick Example

// Define a moduletypeUsersModulestruct{}
func (m*UsersModule) Definition() module.ModuleDef {
return module.ModuleDef{
Name: "users",
Providers: []module.ProviderDef{{
Token: "users.service",
Build: func(r module.Resolver) (any, error) {
returnNewUsersService(), nil
},
}},
Controllers: []module.ControllerDef{{
Name: "UsersController",
Build: func(r module.Resolver) (any, error) {
svc, err:=module.Get[UsersService](r, "users.service")
iferr!=nil {
returnnil, err
}
returnNewUsersController(svc), nil
},
}},
Exports: []module.Token{"users.service"},
}
}
// Bootstrap and servefuncmain() {
app, err:=kernel.Bootstrap(&UsersModule{})
iferr!=nil {
log.Fatal(err)
}
router:=mkhttp.NewRouter()
mkhttp.RegisterRoutes(mkhttp.AsRouter(router), app.Controllers)
mkhttp.Serve(":8080", router)
}

Features

• Module System — Compose apps from self-contained modules with explicit boundaries
• Dependency Injection — Providers built on first access, cached as singletons
• Visibility Enforcement — Only exported tokens are accessible to importers
• HTTP Adapter — Chi-based router with explicit route registration
• No Reflection — Everything is explicit and type-safe
• Deterministic Bootstrap — Predictable initialization order with clear error messages

Feature Matrix

Pattern	Guide	Example Code	Example Tests
Authentication	Authentication Guide	examples/hello-mysql/internal/modules/auth/	examples/hello-mysql/internal/modules/auth/integration_test.go
Validation	Validation Guide	examples/hello-mysql/internal/validation/ + examples/hello-mysql/internal/modules/users/types.go	examples/hello-mysql/internal/modules/users/validation_test.go
Middleware	Middleware Guide	examples/hello-mysql/internal/middleware/ + examples/hello-mysql/internal/httpserver/server.go	examples/hello-mysql/internal/middleware/middleware_test.go
Lifecycle and Cleanup	Lifecycle Guide	examples/hello-mysql/internal/lifecycle/cleanup.go + examples/hello-mysql/cmd/api/main.go	examples/hello-mysql/internal/lifecycle/lifecycle_test.go
Database Providers	Database Providers Guide	examples/hello-postgres/ + examples/hello-sqlite/	examples/hello-postgres/internal/smoke/smoke_test.go + examples/hello-sqlite/internal/smoke/smoke_test.go

Migration note: if you used the MySQL example tokens (database.TokenDB), prefer the shared SQL contract tokens (sqlmodule.TokenDB, sqlmodule.TokenDialect) going forward. The MySQL example preserves backward compatibility via token aliases.

Packages

Package	Description
modkit/module	Module metadata types (ModuleDef, ProviderDef, Token)
modkit/config	Typed environment config module helpers
modkit/kernel	Graph builder, visibility enforcer, bootstrap
modkit/http	HTTP adapter for chi router
modkit/logging	Logging interface with slog adapter
modkit/testkit	Test harness for bootstrap, overrides, and typed test helpers

Architecture

flowchart LR
subgraph Input
A[📦 Module Definitions]
end
subgraph Kernel
B[🔗 Graph Builder]
C[📦 Container]
end
subgraph Output
D[🎮 Controllers]
E[🌐 HTTP Adapter]
end
A --> B
B --> C
C --> D
D --> E
style A fill:#e1f5fe,stroke:#01579b,color:#01579b
style B fill:#fff3e0,stroke:#e65100,color:#e65100
style C fill:#fff3e0,stroke:#e65100,color:#e65100
style D fill:#e8f5e9,stroke:#2e7d32,color:#2e7d32
style E fill:#e8f5e9,stroke:#2e7d32,color:#2e7d32

Loading

See Architecture Guide for details.

Documentation

Guides:

• Getting Started — Your first modkit app
• Stability and Compatibility Policy — Versioning guarantees and upgrade expectations
• Adoption and Migration Guide — Incremental adoption strategy and exit paths
• Fit and Trade-offs — When to choose modkit and when not to
• Modules — Module composition and visibility
• Graph Visualization — Export module graph as Mermaid or DOT
• Providers — Dependency injection patterns
• Lifecycle — Provider lifecycle and cleanup
• Controllers — HTTP handlers and routing
• Middleware — Request/response middleware
• Interceptors — Request/response interception patterns
• Error Handling — Error patterns and Problem Details
• Validation — Input validation patterns
• Authentication — Auth middleware and guards
• Configuration — Typed environment configuration patterns
• Context Helpers — Typed context keys and helper functions
• Testing — Testing patterns
• NestJS Compatibility — Feature parity and Go-idiomatic differences
• Comparison — vs Wire, Fx, and others
• Maintainer Operations — Triage SLAs and adoption KPI cadence

Reference:

• API Reference — Types and functions
• Architecture — How modkit works under the hood
• FAQ — Common questions
• Release Process — CI and versioned CLI release flow

Examples:

• hello-simple — Minimal example, no Docker
• hello-mysql — Full CRUD API with MySQL
• hello-postgres — Postgres provider + smoke tests
• hello-sqlite — SQLite provider + fast local smoke tests

How It Compares to NestJS

Concept	NestJS	modkit
Module definition	@Module() decorator	ModuleDef struct
Dependency injection	Constructor injection via metadata	Explicit module.Get[T](r, token)
Route binding	@Get(), @Post() decorators	RegisterRoutes(router) method
Middleware	NestMiddleware interface	func(http.Handler) http.Handler
Guards/Pipes/Interceptors	Framework abstractions	Standard Go middleware

Support

• Questions / ideas: use GitHub Discussions
• Bugs / feature requests: open a GitHub Issue
• Security: see SECURITY.md

Branding

Branding assets (logo + social preview images) are in assets/branding/stacked-modules/.

Development

make fmt
make lint
make vuln
make test
make test-coverage

Community

Questions? Start a Discussion.

Contributing

See CONTRIBUTING.md. We welcome issues, discussions, and PRs.

Contributors

License

MIT — see LICENSE