Golang Uber Fx

Persona: You are a Go architect building a long-running service with fx. You wire the graph at the composition root, push lifecycle into hooks instead of init(), and treat modules as the unit of reuse.

Using uber-go/fx for Application Wiring in Go

Application framework combining a reflection-based DI container (built on uber-go/dig) with a lifecycle, module system, signal-aware run loop, and structured event logging. For long-running services where boot order, graceful shutdown, and modular composition matter.

Official Resources:

• pkg.go.dev/go.uber.org/fx
• uber-go.github.io/fx
• github.com/uber-go/fx

This skill is not exhaustive. Please refer to library documentation and code examples for more information. Context7 can help as a discoverability platform. For Go package docs, versions, symbols, and known vulnerabilities, → See samber/cc-skills-golang@golang-pkg-go-dev skill.

go get go.uber.org/fx

fx vs. dig

fx is built on top of dig and shares the same reflection-based container engine. The DI primitives (Provide, Invoke, In/Out structs, named values, value groups) are identical — fx.In/fx.Out are re-exports of dig.In/dig.Out.

What fx adds on top:

Choose fx for long-running services (HTTP servers, workers, daemons) — lifecycle and signal handling are mandatory there, and modules make large service graphs manageable.

Choose raw dig when you need wiring without a framework: CLI tools, libraries that expose a container to callers, test harnesses, or embedding DI into an existing app that manages its own lifecycle. See samber/cc-skills-golang@golang-uber-dig skill.

The Application

import "go.uber.org/fx"

app := fx.New(
    fx.Provide(NewLogger, NewDatabase, NewServer),
    fx.Invoke(RegisterRoutes),
)
app.Run() // blocks until SIGINT/SIGTERM, then runs OnStop hooks

Boot stages: fx.New validates types (constructors do not run); app.Start(ctx) runs each fx.Invoke and fires OnStart hooks in topological order; main blocks on app.Done(); app.Stop(ctx) fires OnStop hooks in reverse order. Default timeout is 15 seconds — override with fx.StartTimeout / fx.StopTimeout.

Provide and Invoke

fx.New(
    fx.Provide(NewLogger, NewDatabase, NewServer),  // lazy
    fx.Invoke(RegisterRoutes, StartMetricsExporter), // always run during Start
)

fx.Provide registers constructors; fx.Invoke is the trigger — without an Invoke (directly or transitively) referencing a type, its constructor never runs.

Lifecycle Hooks

Inject fx.Lifecycle and append hooks. Constructors should return quickly; long-running work belongs in OnStart.

func NewHTTPServer(lc fx.Lifecycle, log *zap.Logger, cfg *Config) *http.Server {
    srv := &http.Server{Addr: cfg.Addr}

    lc.Append(fx.Hook{
        OnStart: func(ctx context.Context) error {
            ln, err := net.Listen("tcp", srv.Addr)
            if err != nil { return err }
            go srv.Serve(ln)         // blocking work in a goroutine
            return nil
        },
        OnStop: func(ctx context.Context) error {
            return srv.Shutdown(ctx)
        },
    })
    return srv
}

Both callbacks receive a context bounded by StartTimeout/StopTimeout — respect cancellation. OnStart must return quickly — spawn a goroutine for blocking work; otherwise startup hangs and dependent hooks never fire.

fx.StartHook / fx.StopHook / fx.StartStopHook adapt simpler signatures (no context, no error, or both):

lc.Append(fx.StartStopHook(srv.Start, srv.Stop))   // matched pair

Parameter and Result Objects

fx re-exports dig's dig.In / dig.Out as fx.In / fx.Out. Use them when a constructor has 4+ dependencies, or when you need name/group/optional tags.

type ServerParams struct {
    fx.In

    Logger *zap.Logger
    DB     *sql.DB
    Cache  *redis.Client     `optional:"true"`
    Routes []http.Handler    `group:"routes"`
}

func NewServer(p ServerParams) *Server { /* ... */ }

fx.Annotate

fx.Annotate wraps a constructor to add tags or interface bindings without a fx.Out struct. Prefer it for ergonomic name/group/As bindings:

fx.Provide(
    fx.Annotate(NewPrimaryDB, fx.ResultTags(`name:"primary"`)),
    fx.Annotate(NewPostgresDB, fx.As(new(Database))),    // expose interface
    fx.Annotate(NewUserHandler,
        fx.As(new(http.Handler)),
        fx.ResultTags(`group:"routes"`),
    ),
)

Value Groups

Many constructors, one consumer slice — typical for routes, health checks, metrics collectors:

type RouteResult struct {
    fx.Out
    Handler http.Handler `group:"routes"`
}

type ServerParams struct {
    fx.In
    Routes []http.Handler `group:"routes"`
}

Append ,flatten (group:"routes,flatten") to unwrap a slice instead of nesting it. Order is not guaranteed — provide an explicit ordered slice when sequence matters.

fx.Module

fx.Module groups providers, invokes, and decorators under a name. Modules scope decorators to themselves and their children — a logger renamed in fx.Module("db", ...) only appears renamed for code inside that module.

var DatabaseModule = fx.Module("database",
    fx.Provide(NewConnection, NewUserRepository),
    fx.Decorate(func(log *zap.Logger) *zap.Logger {
        return log.Named("db")
    }),
)

func main() {
    fx.New(
        fx.Provide(NewConfig, NewLogger),
        DatabaseModule,
        HTTPModule,
    ).Run()
}

Treat each module as a small library that can be lifted into another app — its public surface is the types it Provides.

For fx.Supply/fx.Replace/fx.Decorate, optional deps, custom logging, manual lifecycle, and Quick Reference, see advanced.md.

Best Practices

1. Keep main() thin — providers, modules, and a single Run(). Push real work into modules so each can be tested in isolation. 2. Use lifecycle hooks instead of init() or goroutines launched from constructors — Start/Stop ordering depends on graph topology, but init() goroutines do not, which leads to races and leaks. 3. OnStart must return promptly — long work goes in a goroutine inside the hook. A blocking OnStart hangs the rest of the boot. 4. Respect ctx.Done() in hooks — a hook that ignores cancellation is reported as a timeout failure but its goroutine continues, leaking resources. 5. Group by module, not by layer — a module owns the providers, lifecycle, and decorators for one concern (HTTP, DB, metrics). 6. Use fx.Annotate for tags rather than wrapping a constructor in an fx.Out struct — keeps the constructor reusable outside fx. 7. Replace fx.Provide with fx.Supply for pre-built values (config, command-line flags). Shorter, signals intent. 8. Validate the graph in CI by booting under fx.New(...).Err() — catches missing providers and cycles before deploy.

Common Mistakes

Testing

Use go.uber.org/fx/fxtest to integrate fx with *testing.T (failures call t.Fatal, RequireStop registers as t.Cleanup). fx.Populate(&target) pulls values out of the graph; fx.Replace swaps real dependencies for fakes. Full patterns in testing.md.

Further Reading

• advanced.md — Supply/Replace/Decorate, optional deps, custom event logging, manual lifecycle, full Quick Reference
• recipes.md — full HTTP service with database/metrics, background workers with graceful drain, multiple impls of the same interface, manual lifecycle for CLI embedding
• testing.md — fxtest patterns, fx.Replace, fx.Populate, isolated lifecycle tests, CI graph validation

Cross-References

• → See samber/cc-skills-golang@golang-uber-dig skill for the underlying container, dig.In/dig.Out, and DI without lifecycle
• → See samber/cc-skills-golang@golang-dependency-injection skill for DI concepts and library comparison
• → See samber/cc-skills-golang@golang-samber-do skill for a generics-based alternative without reflection
• → See samber/cc-skills-golang@golang-google-wire skill for compile-time DI (no runtime container)
• → See samber/cc-skills-golang@golang-structs-interfaces skill for interface design patterns
• → See samber/cc-skills-golang@golang-context skill for context propagation in OnStart/OnStop hooks
• → See samber/cc-skills-golang@golang-testing skill for general testing patterns

If you encounter a bug or unexpected behavior in uber-go/fx, open an issue at <https://github.com/uber-go/fx/issues>.

Advanced — uber-go/fx

Detail topics referenced from SKILL.md. Each section is self-contained.

fx.Supply, fx.Replace, fx.Decorate

fx.Supply(cfg, secret)

// Replace inside fxtest
fx.Replace(fx.Annotate(&fakeDB{}, fx.As(new(Database))))

// Decorate, module-scoped
fx.Module("worker",
    fx.Decorate(func(s metrics.Scope) metrics.Scope {
        return s.Tagged(map[string]string{"component": "worker"})
    }),
)

Optional Dependencies

optional:"true" lets a consumer compile and run when no provider exists. Use it for genuinely optional features (a tracer, a cache) — not for core services like a database.

type Params struct {
    fx.In

    Logger *zap.Logger
    Tracer trace.Tracer `optional:"true"`
}

Logging fx Events

fx emits structured events (provide, invoke, hook execution, errors) through fxevent.Logger. By default it writes to stderr — replace with a Zap logger or silence it in tests:

fx.New(
    fx.Provide(NewZapLogger),
    fx.WithLogger(func(log *zap.Logger) fxevent.Logger {
        return &fxevent.ZapLogger{Logger: log}
    }),
    // Or silence: fx.NopLogger
)

Manual Lifecycle Control

app.Run() is convenient but inflexible. For tests, custom signal handling, or embedding fx in a larger program, drive the lifecycle manually:

app := fx.New(/* ... */)

startCtx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
if err := app.Start(startCtx); err != nil {
    log.Fatal(err)
}

<-app.Done() // waits for SIGINT/SIGTERM

stopCtx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
if err := app.Stop(stopCtx); err != nil {
    log.Fatal(err)
}

fx.StartTimeout and fx.StopTimeout set defaults; pass an explicit context to override per-call.

Quick Reference

Application

Wiring

Annotations

Lifecycle

Logging & Testing

Recipes — uber-go/fx

End-to-end examples that go beyond the SKILL.md basics. Each recipe is self-contained and shows a real wiring problem.

Full HTTP service with database, metrics, and graceful shutdown

package main

import (
    "context"
    "database/sql"
    "fmt"
    "net"
    "net/http"
    "time"

    "github.com/prometheus/client_golang/prometheus"
    "github.com/prometheus/client_golang/prometheus/promhttp"
    "go.uber.org/fx"
    "go.uber.org/fx/fxevent"
    "go.uber.org/zap"
)

func main() {
    fx.New(
        fx.Provide(
            NewConfig,
            NewLogger,
            NewDatabase,
            NewMetricsRegistry,
        ),

        DatabaseModule,
        HTTPModule,
        MetricsModule,

        fx.WithLogger(func(log *zap.Logger) fxevent.Logger {
            return &fxevent.ZapLogger{Logger: log}
        }),

        fx.StartTimeout(30 * time.Second),
        fx.StopTimeout(30 * time.Second),
    ).Run()
}

var DatabaseModule = fx.Module("database",
    fx.Provide(
        NewUserRepository,
        NewPostRepository,
    ),
    fx.Decorate(func(log *zap.Logger) *zap.Logger {
        return log.Named("db")
    }),
)

var HTTPModule = fx.Module("http",
    fx.Provide(
        NewRouter,
        NewHTTPServer,
        // Each handler joins the "routes" group.
        AsRoute(NewUserHandler),
        AsRoute(NewPostHandler),
        AsRoute(NewHealthHandler),
    ),
    fx.Invoke(func(*http.Server) {}), // forces server to be built
)

var MetricsModule = fx.Module("metrics",
    fx.Provide(NewPrometheusHandler),
    fx.Invoke(RegisterMetrics),
)

// Helper to register a handler with the "routes" group.
func AsRoute(ctor any) any {
    return fx.Annotate(
        ctor,
        fx.As(new(Route)),
        fx.ResultTags(`group:"routes"`),
    )
}

type Route interface {
    Pattern() string
    http.Handler
}

type RouterParams struct {
    fx.In
    Routes []Route `group:"routes"`
}

func NewRouter(p RouterParams) *http.ServeMux {
    mux := http.NewServeMux()
    for _, r := range p.Routes {
        mux.Handle(r.Pattern(), r)
    }
    return mux
}

func NewHTTPServer(lc fx.Lifecycle, log *zap.Logger, mux *http.ServeMux, cfg *Config) *http.Server {
    srv := &http.Server{
        Addr:         cfg.Addr,
        Handler:      mux,
        ReadTimeout:  10 * time.Second,
        WriteTimeout: 10 * time.Second,
    }

    lc.Append(fx.Hook{
        OnStart: func(ctx context.Context) error {
            ln, err := net.Listen("tcp", srv.Addr)
            if err != nil {
                return fmt.Errorf("listen %s: %w", srv.Addr, err)
            }
            go func() {
                if err := srv.Serve(ln); err != nil && err != http.ErrServerClosed {
                    log.Error("server error", zap.Error(err))
                }
            }()
            log.Info("listening", zap.String("addr", srv.Addr))
            return nil
        },
        OnStop: func(ctx context.Context) error {
            log.Info("shutting down")
            return srv.Shutdown(ctx)
        },
    })
    return srv
}

Background worker with graceful drain

type Worker struct {
    log    *zap.Logger
    queue  chan Job
    done   chan struct{}
}

func NewWorker(lc fx.Lifecycle, log *zap.Logger) *Worker {
    w := &Worker{
        log:   log,
        queue: make(chan Job, 100),
        done:  make(chan struct{}),
    }

    lc.Append(fx.Hook{
        OnStart: func(ctx context.Context) error {
            go w.run()
            return nil
        },
        OnStop: func(ctx context.Context) error {
            close(w.queue) // signal "no more jobs"
            select {
            case <-w.done:
                w.log.Info("worker drained cleanly")
                return nil
            case <-ctx.Done():
                w.log.Warn("worker stop timeout")
                return ctx.Err()
            }
        },
    })

    return w
}

func (w *Worker) run() {
    defer close(w.done)
    for job := range w.queue {
        job.Do(w.log)
    }
}

The worker honors the stop context — under a 30-second fx.StopTimeout it has 30 seconds to drain. Beyond that, fx reports the timeout and the process exits.

Multiple implementations of the same interface

Use named annotations + fx.As to register two Cache implementations and inject them by name:

fx.Provide(
    fx.Annotate(
        NewRedisCache,
        fx.As(new(Cache)),
        fx.ResultTags(`name:"redis"`),
    ),
    fx.Annotate(
        NewMemcachedCache,
        fx.As(new(Cache)),
        fx.ResultTags(`name:"memcached"`),
    ),
)

type ServiceParams struct {
    fx.In
    Primary  Cache `name:"redis"`
    Fallback Cache `name:"memcached"`
}

fx.Supply for config and secrets

func main() {
    cfg := mustLoadConfig() // parsed flags + env, before fx
    secret := os.Getenv("API_KEY")

    fx.New(
        fx.Supply(cfg),                  // *Config available everywhere
        fx.Supply(fx.Annotate(secret, fx.ResultTags(`name:"apikey"`))),

        fx.Provide(NewLogger, NewAPIClient),
        fx.Invoke(run),
    ).Run()
}

func NewAPIClient(cfg *Config, p struct {
    fx.In
    APIKey string `name:"apikey"`
}) *APIClient {
    return &APIClient{baseURL: cfg.APIBaseURL, key: p.APIKey}
}

fx.Supply makes pre-built values first-class graph members. It is shorter and clearer than fx.Provide(func() *Config { return cfg }).

Module-scoped decorator

var WorkerModule = fx.Module("worker",
    fx.Provide(NewWorker, NewJobQueue),
    // Inside this module, *zap.Logger is automatically named "worker".
    fx.Decorate(func(log *zap.Logger) *zap.Logger {
        return log.Named("worker")
    }),
)

var APIModule = fx.Module("api",
    fx.Provide(NewServer, NewRouter),
    fx.Decorate(func(log *zap.Logger) *zap.Logger {
        return log.Named("api")
    }),
)

The two modules see different loggers — there is no shared mutation of the parent value.

Optional dependency for tracing

type ServerParams struct {
    fx.In

    Logger *zap.Logger
    Tracer trace.Tracer `optional:"true"`
}

func NewServer(p ServerParams) *Server {
    s := &Server{log: p.Logger}
    if p.Tracer == nil {
        s.tracer = trace.NewNoopTracerProvider().Tracer("noop")
    } else {
        s.tracer = p.Tracer
    }
    return s
}

Reach for optional only when the dependency is genuinely optional. A missing core service hidden behind optional becomes a nil-pointer panic at first use.

Manual lifecycle for embedding fx in a CLI

When fx is one component inside a larger program (a CLI tool, a test runner), drive Start/Stop yourself instead of calling Run():

func runFxApp(parent context.Context) error {
    app := fx.New(
        fx.Provide(NewConfig, NewLogger, NewWorker),
        fx.Invoke(func(*Worker) {}),
    )
    if err := app.Err(); err != nil {
        return fmt.Errorf("wire: %w", err)
    }

    startCtx, cancel := context.WithTimeout(parent, 30*time.Second)
    defer cancel()
    if err := app.Start(startCtx); err != nil {
        return fmt.Errorf("start: %w", err)
    }

    select {
    case <-parent.Done():
    case <-app.Done(): // SIGINT/SIGTERM
    }

    stopCtx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
    defer cancel()
    return app.Stop(stopCtx)
}

app.Err() validates wiring without starting — useful for --check style flags.

Custom event logger that filters noise

type ProductionLogger struct {
    inner *fxevent.ZapLogger
}

func (l *ProductionLogger) LogEvent(e fxevent.Event) {
    switch e.(type) {
    case *fxevent.Provided, *fxevent.Supplied, *fxevent.Decorated:
        return // drop the per-Provide chatter
    default:
        l.inner.LogEvent(e)
    }
}

fx.New(
    fx.Provide(NewZapLogger),
    fx.WithLogger(func(log *zap.Logger) fxevent.Logger {
        return &ProductionLogger{inner: &fxevent.ZapLogger{Logger: log}}
    }),
)

In production, filtering provide/decorate noise leaves only lifecycle (start/stop) events and errors — much easier to audit.

Testing with uber-go/fx

go.uber.org/fx/fxtest integrates fx applications with *testing.T: errors fail the test instead of crashing the process, and lifecycle teardown is registered automatically.

Pulling a value out of the graph with fx.Populate

func TestUserService_Create(t *testing.T) {
    var svc *UserService

    app := fxtest.New(t,
        fx.Provide(
            func() Database { return &fakeDatabase{} },
            NewUserService,
        ),
        fx.Populate(&svc),
    )
    defer app.RequireStop()
    app.RequireStart()

    require.NoError(t, svc.Create(context.Background(), "alice@example.com"))
}

fx.Populate(&svc) fills svc with the value the graph would resolve. It replaces ad-hoc fx.Invoke(func(s *UserService) { svc = s }) patterns.

fx.Replace to swap a real dependency for a fake

func TestServer_HandlesDBError(t *testing.T) {
    var srv *http.Server
    fakeDB := &erroringDatabase{}

    app := fxtest.New(t,
        ProductionModule,                                 // the real wiring
        fx.Replace(fx.Annotate(fakeDB, fx.As(new(Database)))),
        fx.Populate(&srv),
    )
    defer app.RequireStop()
    app.RequireStart()

    // Drive the server with a fake DB
    rec := httptest.NewRecorder()
    req := httptest.NewRequest(http.MethodGet, "/users", nil)
    srv.Handler.ServeHTTP(rec, req)
    require.Equal(t, http.StatusInternalServerError, rec.Code)
}

fx.Replace works even when the original provider is buried inside a module — it overrides the resolved type without rewriting the module.

Standalone lifecycle for a unit test

fxtest.NewLifecycle(t) gives you an fx.Lifecycle outside the fx.New machinery, useful for testing a single constructor that registers hooks:

func TestWorker_StartStop(t *testing.T) {
    lc := fxtest.NewLifecycle(t)

    worker := NewWorker(lc, zaptest.NewLogger(t))
    require.NotNil(t, worker)

    lc.RequireStart() // runs OnStart hooks
    require.True(t, worker.IsRunning())

    lc.RequireStop()  // runs OnStop hooks
    require.False(t, worker.IsRunning())
}

This is the lightest test for a constructor — no full graph, no fx.New.

Asserting wire-time errors

func TestWiring_MissingDependency(t *testing.T) {
    app := fx.New(
        fx.Provide(NewServer), // depends on *sql.DB which is not provided
        fx.NopLogger,
    )
    require.Error(t, app.Err())
    require.Contains(t, app.Err().Error(), "missing type: *sql.DB")
}

Use fx.New (not fxtest.New) when you _expect_ the wiring to fail — fxtest.New would call t.Fatal.

Validating the production graph in CI

func TestProductionGraph(t *testing.T) {
    app := fx.New(
        ProductionOptions(), // every fx.Provide / fx.Module the binary uses
        fx.NopLogger,
    )
    require.NoError(t, app.Err())
}

fx.New validates the type graph without starting. The test fails before deploy on any missing-provider, cycle, or annotation mismatch.

Test logger that captures fx events

When you want to assert on lifecycle behavior, route fx events into an in-memory observer:

// go.uber.org/zap/zaptest/observer
core, recorded := observer.New(zap.InfoLevel)
log := zap.New(core)

app := fxtest.New(t,
    fx.WithLogger(func() fxevent.Logger {
        return &fxevent.ZapLogger{Logger: log}
    }),
    fx.Provide(NewWorker),
    fx.Invoke(func(*Worker) {}),
)
defer app.RequireStop()
app.RequireStart()

require.NotEmpty(t, recorded.FilterMessage("OnStart hook executed").All())

Testing a lifecycle hook in isolation

If a constructor returns a value _and_ registers a hook, you often want to test both halves:

func TestNewServer_OnStartFailsBindError(t *testing.T) {
    // Bind a port so :0 is unavailable... no, simpler: pre-bind and pass that addr
    listener, err := net.Listen("tcp", "127.0.0.1:0")
    require.NoError(t, err)
    defer listener.Close()
    addr := listener.Addr().String()

    cfg := &Config{Addr: addr}
    lc := fxtest.NewLifecycle(t)

    NewHTTPServer(lc, zaptest.NewLogger(t), cfg)

    // Use Start directly (not RequireStart) so we can assert the error.
    require.Error(t, lc.Start(context.Background()))
}