Yokai: a Go framework that wires observability before your business logic

The boilerplate Yokai is trying to delete

The README states the problem plainly: building production-grade Go backends requires effort and boilerplate that has nothing to do with application logic, and it names dependencies wiring, configuration management and observability instrumentation as examples. Yokai's answer is to treat those as core modules rather than as code each service writes again.

The intended audience is teams running more than one Go backend service. A single binary with one HTTP handler does not need a framework to register a logger. The cost of Yokai is a dependency injection container and a module system; that cost only pays back when several services must expose the same metrics, the same trace propagation and the same health endpoints, and when a new service should start from a template rather than from a blank file. The README frames the goals as simple, modular and observable, and the second and third of those are the ones that carry weight here.

Core modules, extension modules and the DI container

The architecture image in the README separates three things. Core modules preload logging, tracing, metrics and health check instrumentation, and expose a private HTTP server for infrastructure and debugging needs. Extension modules add application-facing features: the README lists public HTTP and gRPC servers, workers and ORM as examples, and points to a separate contrib repository for more. Both kinds of module are made available in the dependency injection system, which is where application logic is expected to pull them from.

That is the whole data flow as far as the README describes it. Configuration is read by Viper, the container is Fx, HTTP servers are Echo, gRPC servers are grpc-go, and observability instrumentation is OpenTelemetry. Yokai is not reimplementing those libraries; it is choosing them, wiring them into a container, and giving them a module boundary. The private HTTP server is the detail worth noticing: infrastructure endpoints are deliberately not on the public listener, so health and debugging surface on a separate port from application traffic.

Because the container is Fx, the injection model is Fx's. Anything you write that needs a logger or a tracer declares it as a dependency and receives it. The README does not spell out the provider signatures or the exact constructor names, so treat the documentation site as the source for those rather than the README.

Four templates, four demo applications

The README's getting started section points at ready-to-use application templates for gRPC, HTTP, MCP and worker applications, each with its own documentation page. A separate showroom repository holds demo applications for the same four shapes, described as ready to run. The MCP template is the unusual one: MCP server is listed among the repository topics, and an MCP application template sits alongside the HTTP and gRPC ones, which suggests model context protocol servers are treated as a first-class application shape rather than an afterthought.

This is where the README stops being enough. It gives no go install command, no git clone line, no module path, and no configuration keys. The honest reading is that getting started means opening the template page for your application shape, and that the concrete commands live there. If you want to evaluate Yokai without committing, the showroom demos are the lower-friction path, because they are described as ready to run.

Where Yokai is the wrong tool

The framework's own structure is the limitation. Core modules are preloaded, which means the container, the private HTTP server and the observability stack arrive together whether or not a given service needs all of them. If you are adding one endpoint to an existing binary, or writing a CLI, or building something where a private infrastructure listener is meaningless, you are paying for wiring you will not use.

The second limitation is the dependency injection system itself. Fx is a real abstraction with a learning curve, and it changes how a codebase is organised: constructors, providers and lifecycle hooks instead of direct initialisation. Teams that have deliberately avoided DI containers in Go will find Yokai's central design choice to be the thing they disagree with, not a detail they can configure away.

Third, the README does not state a supported Go version beyond the badge reading Go 1.20 or later, and it does not describe a compatibility policy across the independently versioned modules. The release list shows httpclient, fxhttpclient and worker versioned separately, which is normal for a multi-module repository but does mean upgrade planning happens per module rather than per framework.

Yokai against plain Fx plus OpenTelemetry

The closest comparison is not another framework but the manual assembly of the same parts. Fx is public, OpenTelemetry's Go SDK is public, and the wiring Yokai performs can be written by hand: create the Fx app, build a tracer provider, register a Prometheus exporter, add a health endpoint, start a second HTTP listener for it. The difference in approach is ownership. Hand-wired, each service owns its own version of that setup and drifts from its siblings. With Yokai, the setup is a module you depend on, and the version you get is the version you pin.

The trade is control. Hand-wired, you can shape the private server, the metric naming and the trace sampling exactly as you like without working around a module boundary. Yokai's module system is the mechanism for changing behaviour, and the README says extension modules can be built-in, from the contrib repository, or your own, so the escape hatch exists. It is still an escape hatch: you are writing a module, not editing a line of configuration.

Licence, releases and what maintenance looks like

Yokai is MIT-licensed, which permits commercial use and modification with the licence and copyright notice retained. Nothing in the README suggests dual licensing, a contributor licence agreement, or a commercial tier, but this is a description of the repository metadata and not legal advice; if licence terms matter to your organisation, read the LICENSE file and the MIT text itself.

The repository is not archived and the most recent push recorded is July 2026, with releases in the same window. The release process is automated with release-please, and the README carries an explicit instruction that commits must be atomic and conventional because the release tooling derives version numbers and release notes from them. That has a practical consequence for anyone forking or contributing: a non-conventional commit message can break the release automation's ability to decide what version to cut.

Upgrade cost is per module. Because httpclient, fxhttpclient and worker carry their own version tags, a bump to one does not imply a bump to the others, and the release notes generated by release-please are where the change detail lives. Budget for reading those notes per module rather than treating Yokai as a single versioned dependency.

Editorial conclusion

Adopt Yokai if your team already accepts Fx-style dependency injection and wants logging, tracing, metrics and health checks resolved at startup rather than assembled per service. Do not adopt it if you want a library you can drop into an existing main.go, because the core modules, the private HTTP server and the DI container arrive together. Before committing, verify the Go version your toolchain supports against the README's stated Go 1.20 or later, and read the core module and extension module documentation to confirm the exact configuration keys and injection patterns, since the README itself does not list them.

Official sources

1. ankorstore/yokai on GitHub
2. License: MIT
3. Project website
4. README
5. Releases