# Golang Uber Fx

> Build, review, or test Go applications using `go.uber.org/fx`. Covers providers, invokes, modules, annotations, names and groups, lifecycle hooks, replacements, event logging, graph validation, and fxtest; use Dig when only a container graph is needed.

- Skill: `reagin/golang-uber-fx` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add reagin/golang-uber-fx`
- Raw SKILL.md: https://api.skillmd.com/api/skills/reagin/golang-uber-fx/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: reagin (https://skillmd.com/u/reagin)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/reagin/golang-uber-fx

---


# Uber Fx application wiring

Use the application's existing Fx composition and lifecycle conventions, including its process-level start, stop, and signal ownership.

## Inspect before editing

Locate `fx.New`, modules, providers, invokes, annotations, names and groups, decorators, lifecycle hooks, event logging, start/stop entry points, and `fxtest` coverage. Confirm the selected version in `go.mod` before using newer options.

## Construction and start are different phases

`fx.New` builds the application definition and executes registered invokes; constructors needed by those invokes can therefore run while the app is being created. `Start` runs lifecycle `OnStart` hooks, and `Stop` runs corresponding `OnStop` hooks. Do not put work in a constructor on the assumption that it begins only during `Start`.

Check `app.Err()` or the error returned by the application's existing construction path. Use `Run`, `Start`/`Stop`, or signal handling according to how the host program already owns its process.

## Preserve the executable boundary

Determine whether Fx owns the process run loop or is embedded in another command, server, or test harness. Keep one owner for signals, startup timeout, shutdown timeout, and final error rendering. An embedded application should normally expose bounded `Start` and `Stop` behavior rather than starting a second signal loop.

Keep construction errors distinct from start-hook and stop-hook failures because they imply different cleanup and retry behavior.

## Modules and graph boundaries

- Keep providers independently testable and avoid retaining the Fx container as a service locator.
- Use `fx.In`, `fx.Out`, or annotations where they make names, groups, optional inputs, or interface exposure explicit. Verify annotation support in the selected version.
- Treat names and groups as API. Value-group order is unspecified; assemble ordered chains explicitly.
- Use optional dependencies only when absence is a supported state, not to mask an incomplete graph.
- Keep module-local decorators and replacements scoped intentionally. Review their visibility before moving options across module boundaries.
- Avoid invokes whose only purpose is hidden initialization; make the owned behavior and lifecycle visible.

Read [references/api-and-testing.md](references/api-and-testing.md) for concrete `fx.Provide`, `fx.Invoke`, annotations, lifecycle hooks, replacements, and `fxtest` patterns.

## Lifecycle invariants

Register hooks before the application starts. Start hooks run in registration order, and stop hooks run in reverse order for hooks whose starts succeeded. Respect the supplied contexts and the application's configured time budgets.

An `OnStart` hook should return after the resource is ready enough for dependents rather than blocking for the lifetime of a server. If it starts background work, retain ownership, surface startup failures, and stop or join it from `OnStop`.

Make partial-start failure safe: resources started before a later hook fails must still be stoppable. Keep shutdown idempotent only when the underlying resource contract supports it.

## Validation and testing

Use the selected Fx version's graph-validation facility when only wiring needs validation; understand that validation may not execute constructors. Use `fxtest` or the project's equivalent when constructor behavior and lifecycle hooks matter. Test start failure, partial startup, cancellation, reverse-order shutdown, replacements, groups, and event logging affected by the change.

Run formatting, compilation, and relevant tests. Construct and start each changed application root under bounded test contexts, then stop it and verify owned resources are released.

## Official references

- [Fx documentation](https://uber-go.github.io/fx/)
- [Fx package documentation](https://pkg.go.dev/go.uber.org/fx)
- [Fx repository](https://github.com/uber-go/fx)