nexus

func AppFromGin ¶ added in v1.15.3

func AppFromGin(c *gin.Context) (*App, bool)

AppFromGin returns the *App associated with the current request, set by the framework before a ResponseRenderer runs. It lets a renderer reach per-app state (e.g. App.Value) that can't be threaded through the Render(c, result) signature. Returns (nil, false) outside a renderer-bearing request.

func New ¶

func New(cfg Config) *App

New constructs an *App from a single Config. The canonical (and, since v0.18, only) public constructor — both nexus.Run and the lower-level "build app, then app.Run(addr)" pattern feed through here.

Behavior:

• Manifest-derived defaults (codegen'd by `nexus build --deployment X`) fill any zero Config field; explicit Config fields always win.
• The framework owns engine creation, scope-filter middleware, /__nexus/health + /ready, the cache + ratelimit + metrics stores, and (when EnableDashboard is true) the dashboard mount.
• Listeners with empty Addrs auto-fill from the resolved Config.Addr (admin = port+1000, internal = port+2000).
• Global rate limit and global middlewares are installed at the engine root in registration order.

The returned *App is fully constructed and safe to register endpoints/services on, but listeners aren't bound until Run is invoked (either nexus.Run or App.Run for direct callers).

func AuthRoute ¶ added in v0.28.0

func AuthRoute(flow string) AuthRouteOption

AuthRoute marks the endpoint as part of one of the framework-aware auth flows. Three values are recognized today:

"login"   endpoint that exchanges credentials for a token /
          session cookie. The SDK calls it via auth.login(creds).
"logout"  endpoint that revokes the active session. The SDK calls
          it via auth.logout() and clears its locally-stored
          token on success.
"me"      endpoint returning the current Identity. The SDK calls
          it via auth.me() to bootstrap an existing session on
          page load (cookie-based apps) or check token freshness
          (bearer apps).

Apps stay in control of the actual handler — AuthRoute is purely a metadata marker. Works on both REST (AsRest) and GraphQL ops (AsQuery, AsMutation). The SDK auto-dispatches to the right transport based on the manifest's recorded transport tag:

nexus.AsRest("POST", "/api/login", NewLogin, nexus.AuthRoute("login"))
nexus.AsMutation(NewLogin, nexus.AuthRoute("login"))
nexus.AsQuery(NewMe, nexus.AuthRoute("me"))

AuthRoute does not gate access — combine with auth.Optional() (for /me on bearer apps) or auth.Required() (for /logout) as needed.

Unknown flow values are accepted but ignored by the SDK. The recognized set may grow in future framework versions; the tag is the contract.

func MemoryResolver ¶ added in v0.21.28

func MemoryResolver[T any](getID func(*T) string, setID func(*T, string)) CRUDResolver[T]

MemoryResolver returns a CRUDResolver that always yields the same process-wide MemoryStore[T]. Construction inspects T via reflection to locate ID accessors:

• explicit get/set if both non-nil
• struct field named "ID" otherwise (case-sensitive, kind == String)

Boot fails with a clear error if neither path resolves.

The most common AsCRUD call:

nexus.AsCRUD[User](nexus.MemoryResolver[User](nil, nil))

func LoadConfig ¶ added in v0.97.0

func LoadConfig(path ...string) (Config, error)

LoadConfig reads the runtime block from nexus.toml and returns a Config pre-populated from it. Fields not present in the TOML keep their zero values; the caller is free to mutate the result before passing it to nexus.Run.

LoadConfig also seeds the nexus.Get base layer with the FULL nexus.toml document, so nexus.Get[T]("section.key") resolves any value declared in nexus.toml (dotted key = TOML table path) with no config extension wired. These values are frozen at boot.

Coexists with extension/config — overlapping but distinct:

• nexus.LoadConfig reads `nexus.toml` at STARTUP → the Config struct nexus.Run consumes (listen addr, dashboard, GraphQL, CORS, …) AND the static nexus.Get base layer. Frozen at boot.
• extension/config reads `nexus.config.toml` at RUNTIME and installs a higher-priority, hot-reloadable nexus.Get snapshot (feature flags, sampling rates, remote/server-pushed values). It overrides the nexus.toml base layer for keys it carries.

So nexus.toml alone covers the common case; reach for extension/config when you need hot-reload or a remote source.

Path is optional — pass nothing to read DefaultConfigPath ("nexus.toml") from the current working directory:

cfg, err := nexus.LoadConfig()             // reads nexus.toml
cfg, err := nexus.LoadConfig("alt.toml")   // explicit path

Typical usage in main():

cfg, err := nexus.LoadConfig()
if err != nil { log.Fatal(err) }
cfg.Version = buildVersion // Go-side override (ldflags)
nexus.Run(cfg, /* opts */)

The TOML schema mirrors Config's shape; see RuntimeConfigBlock godoc + the schema sample in docs/. ${VAR} placeholders in string values get env-expanded the same way the deploy manifest does, so secrets / per-env hostnames can live outside the file.

Errors:

• os.ErrNotExist when the file is missing — operators wanting "TOML is optional" should stat the file or use os.IsNotExist to decide whether to fall through to a hardcoded default.
• Parse / schema errors return a wrapped error citing the offending key when go-toml provides one.

Fields NOT representable in TOML (middleware function slices, pluggable Store interfaces) stay Go-only — set those on the returned cfg via direct field assignment before nexus.Run.

func MustLoadConfig ¶ added in v0.97.0

func MustLoadConfig(path ...string) Config

MustLoadConfig is the panic-on-error variant for binaries that REQUIRE a nexus.toml and treat its absence as a fatal startup error. Equivalent to:

cfg, err := nexus.LoadConfig(path...)
if err != nil { panic(err) }

Path is optional — pass nothing to read DefaultConfigPath ("nexus.toml") from cwd:

cfg := nexus.MustLoadConfig()             // reads nexus.toml
cfg := nexus.MustLoadConfig("alt.toml")   // explicit path

Use in main() when the operator has explicitly declared their runtime config in the TOML; saves an `if err != nil` line.

func HideFromDashboard ¶ added in v1.16.0

func HideFromDashboard() DashboardHiddenOption

HideFromDashboard marks an endpoint as exempt from the introspection dashboard (/__nexus): it is dropped from /__nexus/endpoints, the live snapshot, and the architecture graph. The endpoint STILL routes and serves requests normally — this is dashboard-only visibility, not a 404 and not an auth gate. Useful for internal/debug/health ops you don't want cluttering the topology. Works on REST (AsRest / AsRestHandler), GraphQL (AsQuery / AsMutation), and WS (AsWS):

nexus.AsRest("GET", "/internal/debug", NewDebug, nexus.HideFromDashboard())
nexus.AsQuery(NewInternalReport, nexus.HideFromDashboard())
nexus.AsWS("/events", "debug.tap", NewDebugTap, nexus.HideFromDashboard())

func DatabaseSpecFor ¶ added in v1.13.0

func DatabaseSpecFor(name string) (DatabaseSpec, bool)

DatabaseSpecFor returns the parsed [databases.<name>] block, if any. It is the seam db.BindFromConfig uses to read specs without the core importing package db. The lookup is deferred to boot (the binder calls it from its fx constructor), so specs need only exist by boot, not at option-construction time — which is what lets BindFromConfig work under nexus.Boot (Boot builds options before it loads nexus.toml).

func LookupExtensionDecoder ¶ added in v1.0.0

func LookupExtensionDecoder(name string) ExtensionDecoder

LookupExtensionDecoder returns the registered decoder for name, or nil when none is registered. Exposed for the lint command (so it can warn on [extensions.X] blocks for which no decoder exists — typically because the operator forgot to import the extension package).

func FrontendAt ¶ added in v0.21.17

func FrontendAt(path string) FrontendOption

FrontendAt sets a sub-path the SPA is served under, in addition to the deployment-wide route prefix. The two compose: deployment prefix /v1 + FrontendAt("/admin") → SPA at /v1/admin/. Useful when API endpoints live at the deployment root and the frontend should answer on a sibling path. Empty / "/" mean the SPA mounts directly under the deployment prefix (the default).

Trailing slashes are trimmed; a leading slash is added if missing. Pass "/admin" or "admin" — both resolve to "/admin".

func Deprecated ¶ added in v0.3.0

func Deprecated(reason string) GqlOption

Deprecated marks the field deprecated. The reason shows up in SDL and the dashboard "deprecated" badge.

func Desc ¶ added in v0.3.0

func Desc(s string) GqlOption

Desc sets the resolver's description (shown on the dashboard and in SDL documentation).

func GraphMiddleware ¶ added in v0.3.0

func GraphMiddleware(name, description string, mw graph.FieldMiddleware) GqlOption

GraphMiddleware attaches a named graph-only middleware to the resolver. Equivalent to go-graph's WithNamedMiddleware — the name appears in FieldInfo.Middlewares for dashboard rendering (and "auth", "cors", etc. get labelled "builtin" via nexus/middleware.Builtins).

For cross-transport middleware, prefer nexus.Use(middleware.Middleware{...}) — it accepts the same bundle on REST and GraphQL alike.

func OnService ¶ added in v0.3.0

func OnService[S any]() GqlOption

OnService routes this registration onto the given service wrapper type without requiring the handler to take it as a dep. Use when the handler is minimal (`func NewListQuestions(q *QuestionsDB) (...)`) but still belongs to a particular service on the dashboard.

nexus.AsQuery(NewListQuestions, nexus.OnService[*AdvertsService]())

The resolver still needs the owning service to have been provided into the fx graph elsewhere so MountGraphQL can pick up the field.

func Op ¶ added in v0.3.0

func Op(name string) GqlOption

Op overrides the inferred op name.

func RateLimit ¶ added in v0.3.0

func RateLimit(l ratelimit.Limit) GqlOption

RateLimit declares a baseline rate limit for this op. The auto-mount registers it with the app's rate-limit store and wires an enforcement middleware that consults the store on every request. Operators can override the effective limit live from the dashboard — the declared baseline stays in source-of-truth, the override survives in the store.

nexus.AsMutation(NewCreateAdvert,
    nexus.RateLimit(ratelimit.Limit{RPM: 30, PerIP: true}),
)

Burst defaults to RPM/6 when zero (10-second burst window). Set PerIP to true to scope the bucket to the caller's IP; leave false for a shared global bucket.

func WithArgValidator ¶ added in v0.3.0

func WithArgValidator(arg string, vs ...graph.Validator) GqlOption

WithArgValidator adds one or more validators to a named arg, beyond what the struct tags declare. Useful for project-specific rules (graph.Custom validators that call into other code).

func InspectHandlerForExt ¶ added in v0.74.0

func InspectHandlerForExt(fn any) (HandlerShape, error)

InspectHandlerForExt is the public version of inspectHandler. Extensions call this once at registration time, then use the returned HandlerShape to build an fx.Invoke that resolves deps and stamps a bound closure into the extension's dispatch table.

Shape constraints match every other reflective registration in nexus — see the package doc on AsRest for the full grammar.

Errors here are returned to the caller as a Go error rather than wrapped in an fx.Error option, because the caller usually wants to attach its own context ("peer.AsCall(%q): %w") before letting fx see them.

func NewMemoryStore ¶ added in v0.21.28

func NewMemoryStore[T any](getID func(*T) string, setID func(*T, string), newID func() string) *MemoryStore[T]

NewMemoryStore constructs an empty in-memory store. getID/setID are required; newID defaults to uuid.NewString.

func Use ¶ added in v0.3.0

func Use(m middleware.Middleware) MiddlewareOption

Use attaches a transport-agnostic middleware bundle to a registration. Works on AsRest, AsQuery, AsMutation, (future AsSubscription / AsWebSocket) — each transport picks the realization it understands from the bundle (Gin for REST/WS upgrade, Graph for GraphQL). Missing fields are silently ignored so a single bundle can degrade gracefully across transports.

rl := ratelimit.NewMiddleware(store, key, ratelimit.Limit{RPM: 30})
fx.Provide(
    nexus.AsMutation(NewCreateAdvert, nexus.Use(rl)),
    nexus.AsRest("POST", "/quick", NewQuick, nexus.Use(rl)),
)

For app-wide coverage (every REST endpoint + GraphQL POST + WS upgrade + the dashboard itself) put the middleware in Config.GlobalMiddleware instead of naming it on each registration.

func NewNotifier ¶ added in v0.63.0

func NewNotifier() *Notifier

NewNotifier returns a fresh Notifier. Typically created once at app boot and threaded into each mutating subsystem via SetChangeHook (or the equivalent setter on each package).

Production apps don't need to call this directly — nexus.Run wires a singleton into the fx graph; constructors that need a notifier just take a *Notifier param.

func AddStartupTask ¶ added in v0.22.1

func AddStartupTask(t manifest.StartupTask) Option

AddStartupTask produces an Option that registers a startup task. The task's Run is preserved through to integration step 3 where registerLifecycle invokes it before binding listeners.

func AsCRUD ¶ added in v0.21.28

func AsCRUD[T any](resolver any, opts ...Option) Option

AsCRUD registers a default set of CRUD endpoints for type T.

REST surface (default — always on unless WithoutREST() is passed):

GET    /<plural>          → List
GET    /<plural>/:id      → Read
POST   /<plural>          → Create
PATCH  /<plural>/:id      → Update
DELETE /<plural>/:id      → Delete

GraphQL surface (opt-in via WithGraphQL()):

query    list<T>s(limit, offset, sort)
query    get<T>(id)
mutation create<T>(...)
mutation update<T>(id, ...)
mutation delete<T>(id) → Boolean

The `resolver` is a function returning a Store[T] for each request. Its first argument must be context.Context; further arguments are fx-injected at boot, so depending on your DBM (or any other dep) just means putting it in the signature:

nexus.AsCRUD[Note](
    func(ctx context.Context, db *OAtsDB) (nexus.Store[Note], error) {
        return gormstore.For[Note](db.GormDB().WithContext(ctx)), nil
    },
    nexus.WithGraphQL(),
)

Any resolver dep that implements NexusResources() (the framework's resource provider interface — DBs, caches, queues) is automatically linked to the generated endpoints on the dashboard, so the resource node fans out to every action without a manual edge declaration.

Storage is per-request: the resolver runs on every action and the returned Store handles that one request. That makes multi-tenancy / read-replica routing trivial — scope your Store inside the resolver from anything you can pull off ctx.

Convenience: if `resolver` is a `CRUDResolver[T]` (no fx deps), it's accepted as-is — handy for `MemoryResolver[T]` and tests.

nexus.AsCRUD[User](nexus.MemoryResolver[User](nil, nil))                       // REST only
nexus.AsCRUD[User](resolver, nexus.WithGraphQL())                              // REST + GraphQL
nexus.AsCRUD[User](resolver, nexus.WithGraphQL(), nexus.WithoutREST())         // GraphQL only

Options layer over the generated endpoints — auth.Required(), nexus.Use(...), nexus.OnCreate(...) all work as they do for AsRest.

func AsMutation ¶ added in v0.3.0

func AsMutation(fn any, opts ...GqlOption) Option

AsMutation is the mutation analogue of AsQuery.

func AsQuery ¶ added in v0.3.0

func AsQuery(fn any, opts ...GqlOption) Option

AsQuery registers a GraphQL query from a plain Go handler. The handler's signature is inspected reflectively:

• First param should be the service wrapper (e.g. *AdvertsService). Its type is used as the fx value-group key so MountGraphQL[*AdvertsService] picks up this query.
• Subsequent params are fx-injected deps.
• Optional last param is an args struct. Field tags drive arg config: graphql:"name" — arg name (defaults to lowercased field name) graphql:"name,required" — NonNull validate:"required" — graph.Required() validate:"len=3|120" — graph.StringLength(3, 120) validate:"int=1|100" — graph.Int(1, 100) validate:"oneof=a|b|c" — graph.OneOf("a","b","c") Chain multiple rules with commas.
• Return type must be (T, error). T is the resolver's return; pointer and slice wrappers are honored.

Op name defaults to the handler's func name, stripping a leading "New" and lowercasing the first rune ("NewGetAllAdverts" → "getAllAdverts"). Override with nexus.Op("explicit").

fx.Provide(
    nexus.AsQuery(NewGetAllAdverts),
    nexus.AsMutation(NewCreateAdvert,
        nexus.Middleware("auth", "Bearer token", AuthMw)),
)

func AsRest ¶ added in v0.3.0

func AsRest(method, path string, fn any, opts ...RestOption) Option

AsRest registers a REST endpoint from a plain Go handler. The handler's signature is inspected via reflection:

• Leading params are fx-injected deps. The first such param should be your service wrapper (see docs on Service) — its type grounds the endpoint in a service node on the dashboard.
• The optional last param is an "args" struct whose tags direct gin on how to bind from the request: uri:"id" → ShouldBindUri query:"x" → ShouldBindQuery header:"x" → ShouldBindHeader form:"x" → ShouldBind (multipart/url-encoded) json:"x" → ShouldBindJSON (for non-GET; default when other binders are absent)
• The return may be (T, error), (T), (error), or nothing. T gets JSON-marshalled with status 200 (201 for POST) on success; errors become status 500 with {"error": "..."}.

Returns an fx.Option; drop it into fx.Provide.

fx.Provide(
    nexus.AsRest("GET", "/pets",     NewListPets),
    nexus.AsRest("POST", "/pets",    NewCreatePet),
    nexus.AsRest("GET", "/pets/:id", NewGetPet),
)

func AsRestHandler ¶ added in v0.7.3

func AsRestHandler(method, path string, factory any, opts ...RestOption) Option

AsRestHandler registers a REST endpoint whose handler is a plain gin.HandlerFunc supplied by a *factory* function. The factory is the fx-resolved piece: its parameters are the deps needed to build the handler (controllers, resources, other services), its single return is the gin.HandlerFunc that serves requests.

Use this when the handler already manages its own request binding and response shaping (typical for code migrated from ad-hoc Gin routes) but you still want module annotation, metrics, and the dashboard packet-animation treatment AsRest provides:

nexus.Module("oats-rest",
    nexus.AsRestHandler("POST", "/api/devices/register",
        func(d *DeviceController) gin.HandlerFunc { return d.RegisterDevice },
        nexus.Description("Register a device"),
        auth.Required(),
    ),
)

Factory signature requirements:

• Zero or more parameters (fx-injected deps).
• Exactly one return value of type gin.HandlerFunc.

On the dashboard this endpoint appears under its enclosing nexus.Module (same grouping as AsRest / AsQuery), with metrics + trace middleware attached so request.op events drive the live packet animation.

func AsSubscription ¶ added in v0.3.0

func AsSubscription(fn any, opts ...GqlOption) Option

AsSubscription is reserved for a follow-up: subscriptions use a separate builder (SubscriptionResolver[T] with PubSub + channel plumbing) that we haven't taught the reflective path yet. Use graph.NewSubscriptionResolver directly for now; once the reflective SubscriptionResolverFromType exists this helper will mirror AsQuery/AsMutation.

func AsWS ¶ added in v0.9.0

func AsWS(path, msgType string, fn any, opts ...WSOption) Option

AsWS registers one message-type-scoped handler on a WebSocket endpoint. Multiple AsWS calls with the same path share a single connection pool — the framework dispatches inbound messages by their envelope `type` to the matching handler.

type ChatPayload struct{ Text string }

func NewChatSend(svc *ChatSvc, sess *nexus.WSSession,
                 p nexus.Params[ChatPayload]) error {
    sess.EmitToRoom("chat.message",
        map[string]string{"text": p.Args.Text, "user": sess.UserID()},
        "lobby")
    return nil
}

nexus.AsWS("/events", "chat.send", NewChatSend, auth.Required())

Wire protocol — every message is wrapped in the framework's envelope:

{ "type": "chat.send", "data": {...}, "timestamp": <unix> }

The built-in types `ping`, `authenticate`, `subscribe`, `unsubscribe` are handled by the hub directly and never reach user handlers.

Handler signature: same reflective convention as AsRest / AsQuery —

• fx-injected deps anywhere (service wrappers, resources, other services);
• an optional *nexus.WSSession parameter gets the live connection handle;
• an optional nexus.Params[T] carries the decoded message payload in Args;
• return (error) — a non-nil error is sent back on the same connection as an `error` envelope event. The connection stays open.

Middleware (auth.Required, rate limits, etc.) on the FIRST AsWS call for a path is installed on the HTTP upgrade route and gates every subsequent connection. Middleware declared on later AsWS calls for the same path is ignored with a warning log — all dispatches share one upgrade route.

func AsWorker ¶ added in v0.7.0

func AsWorker(name string, fn any) Option

AsWorker registers a long-lived background worker. The framework owns lifecycle — it starts the worker on fx.Start in its own goroutine, cancels its context on fx.Stop, and records status + last-error on the registry so the dashboard can surface it.

Signature requirements:

• First parameter MUST be context.Context. The framework supplies a context that cancels when the app stops; workers are expected to honor it and return.

• Remaining parameters are fx-injected deps (same rules as a constructor — they must exist in the graph).

• Return is optional: a single (error) return lets the worker report a fatal error. context.Canceled / nil is treated as a clean stop; anything else sets Status="failed" + LastError.

  nexus.AsWorker("cache-invalidation", func(ctx context.Context, db *OatsDB, cache *CacheManager, logger *zap.Logger) error { for !db.IsConnected() { select { case <-ctx.Done(): return ctx.Err() case <-time.After(time.Second): } } listener := pq.NewListener(db.ConnectionString(), ...) defer listener.Close() _ = listener.Listen("cache_invalidation") for { select { case <-ctx.Done(): return nil case n := <-listener.Notify: handle(n, cache) } } })

Resource / service deps (for the architecture graph) are detected the same way nexus.ProvideService does it — any param implementing NexusResourceProvider contributes its resources, any param whose type is a service wrapper contributes a service dep.

A worker panic is caught and reported as Status=failed; the app keeps running. For restart semantics, wrap your worker body in a loop that re-dials on ctx.Done() exit OR let the operator restart the app.

func ClientUse ¶ added in v0.28.0

func ClientUse(cfg client.Config) Option

ClientUse is the option-chain alias for setting Config.Client. Most apps wire the SDK via the Config field — one line on the Config literal — but ClientUse is the right choice when:

• You want per-deployment gating: composes with IfDeployment.

  nexus.IfDeployment([]string{"public-api"}, nexus.ClientUse(client.Config{Enabled: true}), )

• The SDK is conditional on runtime state the Config struct can't easily express (env-driven feature flags, multi-binary option chains). ClientUse + nexus.Options(...) compose freely with everything else.

Idempotent: when both Config.Client.Enabled AND ClientUse are in scope, the second mount is skipped (the App already has a live Handler from the first).

Sets cfg.Enabled=true unconditionally — the option-chain caller's intent is "mount it"; the Config-side knob exists for the value- driven path only.

func ClientUseWithContributions ¶ added in v0.54.0

func ClientUseWithContributions(cfg client.Config, buildFactory func(*App) client.ContributionsBuilder) Option

ClientUseWithContributions is ClientUse + a contributions builder factory. When buildFactory is non-nil, the resulting builder is invoked at HTTP-request time so the closure can read live state (contributor list, schema refs) that isn't available at option- construction time. The factory itself runs once inside fx.Invoke with the constructed *App in scope.

Lives in nexus/ because the App's clientHandler field is unexported — keeping the assignment inside the package avoids exposing it as a Setter.

Phase-3 caller: extension/frontend's mountClientSDK helper. Direct user-side wiring is rare; most apps go through frontend.Plugin(...) which composes this transparently.

func DeclareEnv ¶ added in v0.22.1

func DeclareEnv(e manifest.EnvVar) Option

DeclareEnv produces an Option that registers one EnvVar on the app at graph construction. Multiple calls compose:

nexus.Module("cache",
    nexus.DeclareEnv(manifest.EnvVar{Name: "REDIS_HOST", Required: true, BoundTo: "redis.host"}),
    nexus.DeclareEnv(manifest.EnvVar{Name: "REDIS_PORT", Required: true, BoundTo: "redis.port"}),
    nexus.Provide(NewManager),
)

func DeclareEnvList ¶ added in v0.22.1

func DeclareEnvList(es []manifest.EnvVar) Option

DeclareEnvList is the bulk variant of DeclareEnv. Used to splice in a slice an upstream package exposes (e.g. cache.ManifestEnv()):

nexus.Run(cfg,
    cache.Module,
    nexus.DeclareEnvList(cache.ManifestEnv()),
    ...
)

Lets a leaf package describe its env surface as static data without importing nexus (which would cycle). The app composes the declaration at boot.

func DeclareService ¶ added in v0.22.1

func DeclareService(s manifest.ServiceNeed) Option

DeclareService produces an Option that registers one ServiceNeed.

func IfDev ¶ added in v0.84.0

func IfDev(opts ...Option) Option

IfDev applies the supplied options ONLY when running under `nexus dev` (NEXUS_DEV=1). In production the wrapped block is a no-op — useful for dev-only stubs (config.Local, in-memory auth, fake mailers) that have no place in a real deploy.

Variadic so multiple options compose cleanly without a surrounding nexus.Options(...) call. Empty input is a no-op regardless of mode.

func IfNotDev ¶ added in v0.84.0

func IfNotDev(opts ...Option) Option

IfNotDev applies the supplied options ONLY when NOT running under `nexus dev`. The mirror image of IfDev — gate plugins that require production-grade configuration (TLS certs, signing keys, OAuth2 client secrets, config-server URLs) so `nexus dev` boots without forcing the operator to fill those in.

nexus.IfNotDev(
    tls.Module(tls.Config{Domains: []string{"app.example.com"}}),
    oauth2.Module(oauth2.Config{ClientSecret: secret}),
)

`nexus dev` skips both; `./bin/app` wires them normally.

func Invoke ¶ added in v0.3.0

func Invoke(fns ...any) Option

Invoke runs a function at startup, resolving its parameters from the graph. Use for side-effects on boot — attaching resources, registering hooks, seeding state. Multiple Invoke options run in registration order.

nexus.Invoke(func(app *nexus.App, dbs *DBManager) {
    app.OnResourceUse(dbs)
})

func LoadDotenvIfPresent ¶ added in v0.82.0

func LoadDotenvIfPresent(path ...string) Option

LoadDotenvIfPresent reads `./.env` (or the supplied path) and populates os.Environ for any key NOT already set in the process environment. Use it in main() so ${VAR} placeholders in nexus.toml — and any other code calling os.Getenv at boot — resolve from the file:

func main() {
    nexus.Run(nexus.Config{...},
        nexus.LoadDotenvIfPresent(),   // ← reads .env if present
        appModule,
    )
}

Behavior:

• Missing file → silent no-op. Production runs without a .env file boot normally; the platform's injected env vars are the source of truth.
• Existing env vars are preserved. A real `DB_PASSWORD` set by systemd / docker / kubectl always beats the .env entry. This matches Spring's precedence (env vars beat application.yml) and the dotenv convention every other ecosystem uses.
• Parse errors (malformed line, unterminated quotes) fail boot with the line number. A broken .env should not silently produce a partially-loaded environment.

File format — minimal, no shell-style expansion:

KEY=value             # plain
KEY="value with =="   # quoted; quotes stripped
KEY='literal $foo'    # single-quoted; literal, no expansion
# comment
export KEY=value      # leading 'export ' allowed, ignored

What's intentionally NOT supported (lean parser, predictable behavior):

• Variable expansion inside values (no $OTHER references)
• Multi-line values
• Shell command substitution

Operators wanting those features should source the .env in a real shell before launching the binary — the framework's job is to consume what the environment already has, not to be a shell.

func LoadExtensionOptions ¶ added in v1.0.0

func LoadExtensionOptions(path ...string) ([]Option, error)

LoadExtensionOptions reads the [extensions.*] block from nexus.toml at path (defaults to DefaultConfigPath, same as LoadConfig), looks up each declared extension's decoder, and returns the collected Options ready to be spread into nexus.Run.

Operators typically combine with LoadConfig:

cfg := nexus.MustLoadConfig()
extOpts, err := nexus.LoadExtensionOptions()
if err != nil { log.Fatal(err) }
opts := append(extOpts, /* hand-coded options */...)
nexus.Run(cfg, opts...)

Or via the convenience helper LoadExtensions which panics:

nexus.Run(nexus.MustLoadConfig(), nexus.MustLoadExtensions()...)

Behaviour:

• Missing file → returns ([], nil). Operators without a nexus.toml pay nothing; existing code keeps working.
• [extensions.X] declared but no decoder registered for X → returns a wrapped error citing X. Catch via lint at CI time so the error never reaches boot.
• Decoder errors → wrapped with the extension name so the operator knows which block was malformed.

Ordering: decoders execute in alphabetical order of name for repeatable boot behavior. If you need a specific ordering (extension A depends on B's option) wire those via Go code instead — TOML is for data, not graph dependencies.

func LoadField ¶ added in v0.60.0

func LoadField[Parent any, Key comparable, Child any](
	fieldName string,
	keyFn func(Parent) Key,
	fetch any,
) Option

LoadField registers a batched virtual field on the GraphQL Object type for Parent. The field's resolver pulls a per-request Loader from context, enqueues the parent's key, and returns a thunk that graphql-go's executor dethunks breadth-first — collapsing N individual lookups across sibling resolvers into one fetch call.

This is the framework-shaped fix for the N+1 pattern that nested GraphQL resolvers otherwise produce. Parent and Child are Go types; Key is the lookup key (typically int64 / string / UUID).

The fetch argument is one of three shapes; the framework picks the right path by reflecting on it at registration time:

// (a) Direct fetch — no fx deps. Type-check at compile time.
nexus.LoadField[User, int64, *Bank](
    "bank",
    func(u User) int64 { return u.ID },
    func(ctx context.Context, ids []int64) (map[int64]*Bank, error) {
        return db.BanksByUserIDs(ctx, ids)
    },
)

// (b) Constructor returning Fetch[K, V] — fx resolves the
//     constructor's params at boot. Inner Fetch is fully typed.
func NewBankFetcher(db *DB) dataloader.Fetch[int64, *Bank] {
    return func(ctx context.Context, ids []int64) (map[int64]*Bank, error) {
        return db.BanksByUserIDs(ctx, ids)
    }
}
nexus.LoadField[User, int64, *Bank]("bank", keyFn, NewBankFetcher)

// (c) Inline fetch with trailing fx-injected deps — fx resolves
//     the deps at boot; ctx + keys remain the head of the fn.
nexus.LoadField[User, int64, *Bank](
    "bank",
    func(u User) int64 { return u.ID },
    func(ctx context.Context, ids []int64, db *DB, cache *Cache) (map[int64]*Bank, error) {
        ...
    },
)

Wrong shapes surface as an fx.Error at app start with a message describing the expected signatures.

Parent's SDL name is the Go type's reflect name (User → "User"). Type aliases unwrap to the original (`type User = users.Row` registers against "Row"); use a defined type or rename if that isn't what you want.

func Managed ¶ added in v1.4.0

func Managed[T any](name string, build func(*zap.Logger) (*T, error), resourceFor func(*T) resource.Resource) Option

Managed is the general-purpose declarative binder for any resource manager that doesn't fit the kind-specific Database[T] / Cache[T] / pubsub.Broker[T] (e.g. a custom RabbitMQ/queue manager, an object store client, a third-party SDK wrapper).

Unlike Database[T], the caller constructs the whole *T in build — so T can have arbitrary extra fields, not just an embedded manager — and returns an error to fail boot when the resource is required. The framework then:

• manages lifecycle automatically: on boot it calls Start() if *T has one; on shutdown it calls Stop() (or Close()). Both void and error-returning forms are detected, so db/cache/queue managers (Start()/Stop()) and transport-style handles (Close() error) all work without the caller wiring hooks.

• registers a dashboard resource via resourceFor (pass nil to skip — useful for a managed handle that isn't a topology node).

  type RabbitMQ struct { *rabbitmq.RabbitMQManager cfg *rabbitmq.RabbitMQConfig }

  nexus.Managed("rabbitmq", func(logger *zap.Logger) (*RabbitMQ, error) { cfg := rabbitmq.NewRabbitMQConfig() return &RabbitMQ{rabbitmq.NewRabbitMQManager(cfg, logger), cfg}, nil }, func(r *RabbitMQ) resource.Resource { return resource.NewQueue("rabbitmq", "RabbitMQ broker", map[string]any{"broker": "rabbitmq"}, r.IsConnected) }, )

Handlers inject *RabbitMQ unchanged.

func Module ¶ added in v0.3.0

func Module(name string, opts ...Option) Option

Module groups options under a name. Mirrors fx.Module's logging — the group name appears in startup/shutdown logs and in error messages, which helps when several modules touch the same service or resource. The name is also stamped onto every AsQuery/AsMutation/AsRest registration inside the module so the dashboard's architecture view can group endpoints by module container.

var advertsModule = nexus.Module("adverts",
    nexus.Provide(NewAdvertsService),
    nexus.AsQuery(NewGetAllAdverts),
    nexus.AsMutation(NewCreateAdvert, …),
)

func MustLoadDotenv ¶ added in v0.82.0

func MustLoadDotenv(path ...string) Option

MustLoadDotenv is the strict variant: a missing file fails boot instead of being a no-op. Use it when the .env contents are required (you've intentionally committed a stub for dev and want to catch "forgot to copy it" mistakes before they become silent `${VAR}` lookup failures).

func MustLoadExtensions ¶ added in v1.0.0

func MustLoadExtensions(path ...string) []Option

MustLoadExtensions is the panic-on-error variant matching MustLoadConfig's idiom. Use in main() when an extension block is required to boot.

func Options ¶ added in v0.21.18

func Options(opts ...Option) Option

Options bundles multiple Option values into a single Option. Useful when one logical feature expands into several: a conditional gate that pulls in a frontend mount + a config supply + an extra invoke, for example. Empty input is a no-op.

func Provide ¶ added in v0.3.0

func Provide(fns ...any) Option

Provide registers one or more constructor functions with the dep graph and auto-detects two opt-in extensions:

• Resource providers: any returned value implementing NexusResourceProvider has its resource.Resource list registered with the app at boot. Add UseReporter alongside and OnResourceUse wires automatically — service→resource edges appear on first UsingCtx call without manual plumbing.

• Service wrappers: when the first return is a *T whose struct anonymously embeds *nexus.Service, the constructor's params are scanned for resource providers and other service wrappers. The resulting (resourceDeps, serviceDeps) lists are recorded on the service's registry entry so the dashboard's architecture view draws service→service and service→resource edges at the SERVICE layer with no extra annotation.

Constructors that don't trigger either detector behave like plain fx.Provide — return types enter the graph, params resolve from it. Mixed sets (one service wrapper + one resource manager + one plain helper) work in a single call.

nexus.Provide(
    NewDBManager,        // resource provider — auto-registered
    NewCacheManager,     // ditto
    NewAdvertsService,   // service wrapper — deps recorded
    NewClock,            // plain type — just enters the graph
)

func Raw ¶ added in v0.3.0

func Raw(opt fx.Option) Option

Raw is an escape hatch: accept any fx.Option and route it through nexus. For features nexus hasn't mirrored yet (fx.Decorate, fx.Replace, named values via fx.Annotate with ParamTags, etc.) or one-off integrations. Normal apps never need it.

nexus.Raw(fx.Decorate(wrapLogger))

func ServeFrontend ¶ added in v0.21.16

func ServeFrontend(fsys fs.FS, root string, opts ...FrontendOption) Option

ServeFrontend mounts a built single-page-app bundle from an embedded filesystem. The classic shape:

//go:embed all:web/dist
var webFS embed.FS

nexus.Run(nexus.Config{...},
    nexus.ServeFrontend(webFS, "web/dist"),
    uaa.Module,
    interview.Module,
)

The `root` argument is the directory inside fsys that holds index.html plus the asset subdirectories — typically the same path passed to //go:embed minus the `all:` prefix. Pass "" when fsys is already rooted at the dist directory (e.g. after fs.Sub).

Pass nexus.FrontendAt("/admin") (or any sub-path) to mount the SPA under a sub-path instead of at the deployment root — useful when REST/GraphQL live at /api/* and the frontend should answer at /admin/* on the same listener.

Behavior (under the deployment route prefix when one is set, then the FrontendAt mount path when one is set):

• Files with an extension (foo.js, /assets/main.css, /favicon.ico) are served from the embed.FS directly. Files under /assets/ get an immutable far-future Cache-Control — Vite, Webpack, and esbuild all stamp content hashes into filenames there, so the cached copy can never go stale.
• Anything else is treated as a client-side route and gets index.html with a no-cache header (so an updated bundle is picked up on the next reload, not held for a year).
• REST / GraphQL / WebSocket / dashboard routes are registered before the NoRoute hook fires, so they win on conflict.

App boot fails fast when the FS lacks an index.html so a stale or unbuilt bundle surfaces at start time, not at first request.

func Supply ¶ added in v0.3.0

func Supply(values ...any) Option

Supply puts concrete values into the graph (no constructor). Useful for config structs or pre-built instances created outside the fx graph.

nexus.Supply(nexus.Config{Server: ServerConfig{Addr: ":8080"}})   // rare — Run takes Config directly
nexus.Supply(myAlreadyBuiltClient)          // typical

func UseVolume ¶ added in v0.22.1

func UseVolume(v manifest.Volume) Option

UseVolume produces an Option that registers one Volume.

func WithGraphQL ¶ added in v0.21.28

func WithGraphQL() Option

WithGraphQL turns on GraphQL op generation for AsCRUD. By default AsCRUD only registers REST endpoints; pass this option (and optionally WithoutREST) to opt in to the GraphQL surface.

nexus.AsCRUD[User](resolver, nexus.WithGraphQL())                       // REST + GraphQL
nexus.AsCRUD[User](resolver, nexus.WithGraphQL(), nexus.WithoutREST())  // GraphQL only

func WithoutREST ¶ added in v0.21.28

func WithoutREST() Option

WithoutREST disables REST endpoint generation for AsCRUD. Combine with WithGraphQL() to expose the resource over GraphQL alone. Without WithGraphQL, AsCRUD will return a boot error rather than silently registering nothing.

func Path ¶ added in v0.21.20

func Path(path string) PathOpt

Path sets the module's public URL path. Equivalent to declaring both nexus.RoutePrefix(path) on the module AND service.AtGraphQL(path+"/graphql") on the module's service — expressed once, kept in sync.

var Module = nexus.Module("uaa",
    nexus.DeployAs("uaa-svc"),
    nexus.Path("/oats-uaa"),
    nexus.Provide(NewService),
    nexus.AsRest("POST", "/oauth/token", TokenHandler),
    nexus.AsQuery(NewSearchUsers),
)

Effect: REST endpoints mount under /oats-uaa/* and GraphQL fields belonging to this module mount at /oats-uaa/graphql.

Why bother (vs a deployment-level prefix in the manifest): Path travels with the module — same URL in monolith and split deployments. The SPA's calls to /oats-uaa/graphql work in both shapes without conditional client logic.

Convention: the module name (first arg of nexus.Module) and the *Service name (passed to app.Service in the constructor) must match for the GraphQL path override to apply. Path looks up app.Service(name) by the module's name; if the service uses a different name, declare AtGraphQL explicitly for that service instead.

Leading slash is added if missing; trailing slash is trimmed.

The raw path is stored unchanged; module-side consumers normalize when reading (so "/" → "" for prefix purposes).

func Public ¶ added in v1.14.0

func Public() PublicOption

Public marks an endpoint as exempt from any framework-installed default gate — the explicit opt-out for deny-by-default auth (auth.Authorization.Default). With no default gate configured it's a harmless no-op marker. Works on REST (AsRest / AsRestHandler), GraphQL (AsQuery / AsMutation), and WS (AsWS):

nexus.AsRest("GET", "/health", NewHealth, nexus.Public())

Login endpoints marked nexus.AuthRoute("login") are auto-exempted (you can't require auth to obtain auth), so they need no Public().

func Description ¶ added in v0.3.0

func Description(s string) RestOption

Description sets the human-readable description shown on the dashboard.

func WithRenderer ¶ added in v1.15.0

func WithRenderer(r ResponseRenderer) RestOption

WithRenderer attaches a ResponseRenderer to a single AsRest registration, replacing the default JSON success write. It is a REST-only option (GraphQL and WebSocket returns are encoded by their own transports).

nexus.AsRest("GET", "/users", NewListUsers, nexus.WithRenderer(myRenderer))

Most apps never call this directly — higher-level helpers such as inertia.Page wire the renderer for you.