Skip to content

samber/cc-skills-golang / skills/golang-uber-fx

golang-uber-fx

Verified

Golang application framework using uber-go/fx — fx.New, fx.Provide, fx.Invoke, fx.Module, fx.Lifecycle hooks, fx.Annotate (name/group/As), fx.Decorate, fx.Supply, fx.Replace, fx.WithLogger, and signal-aware Run(). Apply when using or adopting uber-go/fx, when the codebase imports `go.uber.org/fx`, or when wiring services with fx.New. For raw DI without lifecycle, see `samber/cc-skills-golang@golang-uber-dig` skill.

FileKindSize
SKILL.mdskill md11.1 KB
evals/evals.jsonconfig12.5 KB
references/advanced.mdmarkdown5.3 KB
references/recipes.mdmarkdown8.6 KB
references/testing.mdmarkdown4.7 KB

references/advanced.md

View on GitHub
# Advanced — uber-go/fx

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

## Table of Contents

- [fx.Supply, fx.Replace, fx.Decorate](#fxsupply-fxreplace-fxdecorate)
- [Optional Dependencies](#optional-dependencies)
- [Logging fx Events](#logging-fx-events)
- [Manual Lifecycle Control](#manual-lifecycle-control)
- [Quick Reference](#quick-reference)
  - [Application](#application)
  - [Wiring](#wiring)
  - [Annotations](#annotations)
  - [Lifecycle](#lifecycle)
  - [Logging & Testing](#logging--testing)

## fx.Supply, fx.Replace, fx.Decorate

| Option | Purpose |
| --- | --- |
| `fx.Supply(values...)` | Provide pre-built values directly. Use for config, secrets, parsed flags. |
| `fx.Replace(values...)` | Replace an already-provided type. Most useful in tests: swap real for fake. |
| `fx.Decorate(fn)` | Wrap or modify an existing value. Scoped to the surrounding module. |

```go
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.

```go
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:

```go
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:

```go
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

| Function          | Purpose                                                |
| ----------------- | ------------------------------------------------------ |
| `fx.New(opts...)` | Build the application graph                            |
| `app.Run()`       | Start, wait for signal, Stop — single call             |
| `app.Start(ctx)`  | Run OnStart hooks in dependency order                  |
| `app.Stop(ctx)`   | Run OnStop hooks in reverse order                      |
| `app.Done()`      | Channel that closes on SIGINT/SIGTERM                  |
| `app.Err()`       | Wiring error from `fx.New` (validate without starting) |

### Wiring

| Option                     | Purpose                                     |
| -------------------------- | ------------------------------------------- |
| `fx.Provide(ctors...)`     | Register constructors                       |
| `fx.Invoke(fns...)`        | Run functions during Start                  |
| `fx.Supply(values...)`     | Provide pre-built values                    |
| `fx.Replace(values...)`    | Replace previously-provided values (tests)  |
| `fx.Decorate(fn)`          | Wrap an existing value (module-scoped)      |
| `fx.Module(name, opts...)` | Group providers/invokes/decorators          |
| `fx.Options(opts...)`      | Bundle options into a single value          |
| `fx.Populate(targets...)`  | Extract typed values from the graph (tests) |

### Annotations

| Function | Purpose |
| --- | --- |
| `fx.Annotate(fn, opts...)` | Tag/interface-wrap a constructor |
| `fx.ParamTags("...")` | Tag parameters of an annotated constructor |
| `fx.ResultTags("...")` | Tag results of an annotated constructor |
| `fx.As(new(I))` | Provide as one or more interfaces |
| `fx.From(types...)` | Bind annotated parameters to specific provided types |

### Lifecycle

| Helper | Purpose |
| --- | --- |
| `fx.Hook{OnStart, OnStop}` | Full hook with context-aware callbacks |
| `fx.StartHook(fn)` | Adapt a simple Start function |
| `fx.StopHook(fn)` | Adapt a simple Stop function |
| `fx.StartStopHook(start, stop)` | Pair of simple Start/Stop functions |
| `fx.StartTimeout(d)`, `fx.StopTimeout(d)` | Override default 15s lifecycle timeouts |
| `fx.ErrorHook(h)` | Intercept lifecycle errors (e.g. failed OnStart) for alerting or cleanup |

### Logging & Testing

| Helper | Purpose |
| --- | --- |
| `fx.WithLogger(fn)` | Plug in a custom `fxevent.Logger` |
| `fx.NopLogger` | Silence fx event logging |
| `fxevent.ZapLogger{Logger: log}` | Bridge fx events into zap |
| `fxevent.SlogLogger{Logger: log}` | Bridge fx events into log/slog |
| `fxtest.New(t, opts...)` | App that fails the test on errors |
| `app.RequireStart()`, `app.RequireStop()` | Start/Stop with `t.Fatal` on failure |
| `fxtest.NewLifecycle(t)` | Standalone lifecycle for unit tests |
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall