VEF Framework Go

An opinionated Go framework for enterprise applications, built with Fiber, Uber FX, and Bun.

Unified API resources, generic CRUD, authentication, RBAC, validation, caching, events, storage, MCP, and more.

English | 简体中文 | Quick Start | Documentation | API Reference

VEF Framework Go combines dependency injection, HTTP routing, and data access into a cohesive application framework, with built-in support for API resources, authentication, RBAC, validation, caching, events, storage, MCP, and more.

This README is intentionally brief. Detailed tutorials and reference material are available on the documentation site.

Development status: the project is still pre-1.0. Expect breaking changes while conventions and APIs continue to evolve.

Why VEF

• One resource model for both RPC and REST APIs
• Generic CRUD primitives that reduce repetitive backend code
• Modular composition with Uber FX for clean wiring and extension
• Built-in auth, RBAC, rate limiting, audit, caching, events, storage, MCP, and other infrastructure you would otherwise assemble yourself

Quick Start

Requirements:

• Go 1.26.0 or newer
• A supported database such as PostgreSQL, MySQL, or SQLite

Install:

go get github.com/coldsmirk/vef-framework-go

Create main.go:

package main

import "github.com/coldsmirk/vef-framework-go"

func main() {
	vef.Run()
}

Create configs/application.toml:

[vef.app]
name = "my-app"
port = 8080

[vef.data_source]
type = "sqlite"
path = "./my-app.db"

This is the smallest runnable configuration. Sections such as vef.monitor, vef.mcp, and vef.approval are optional.

Run:

go run main.go

VEF loads application.toml from ./configs, ., ../configs, or the path pointed to by VEF_CONFIG_PATH.

Core Concepts

• vef.Run(...) starts the framework and wires the default module chain: config, database, ORM, middleware, API, security, event, CQRS, cron, redis, mold, storage, sequence, schema, monitor, MCP, and app.
• API endpoints are defined as resources with api.NewRPCResource(...) or api.NewRESTResource(...).
• Business modules are composed with FX options, for example vef.ProvideAPIResource(...), vef.ProvideMiddleware(...), and vef.ProvideMCPTools(...).
• CRUD-heavy modules can build on the generic helpers in crud/ instead of writing repetitive handlers from scratch.

Typical application layout:

my-app/
├── cmd/
├── configs/
└── internal/
    ├── auth/
    ├── sys/
    ├── <domain>/
    └── web/

Documentation

• Documentation site: https://coldsmirk.github.io/vef-framework-go-docs
• API reference: https://pkg.go.dev/github.com/coldsmirk/vef-framework-go
• Repository knowledge map: https://deepwiki.com/coldsmirk/vef-framework-go
• Testing conventions: TESTING.md

If you need step-by-step guides, architectural deep dives, or feature-specific reference, prefer the documentation site rather than expanding this README.

Development

Common verification commands:

go test ./...
go test -race ./...
golangci-lint run
go run golang.org/x/tools/gopls/internal/analysis/modernize/cmd/modernize@latest -test ./...

License

Licensed under the Apache License 2.0.