//nexus: decorators
As an alternative to listing every handler in a nexus.Module(...), you can annotate handlers with //nexus: comments and let nexus generate the registrations. The result is the same AsRest/AsQuery/Provide options you would write by hand, so both styles can be mixed.
package users
import "github.com/paulmanoni/nexus/v2"
//nexus:provide
func NewUserService(app *nexus.App) *UserService {
return &UserService{app.Service("users")}
}
type GetUserArgs struct {
ID string `path:"id"`
}
//nexus:rest GET /users/:id
func NewGetUser(s *UserService, p nexus.Params[GetUserArgs]) (*User, error) { ... }
//nexus:mutation
//nexus:auth Requires users:write
func NewCreateUser(s *UserService, p nexus.Params[CreateUserArgs]) (*User, error) { ... }main needs no handler list:
func main() { nexus.Boot() }Each annotated package becomes a dashboard module named after the package. The main package is named app.
Annotations
One primary annotation per function, plus optional modifiers:
| Annotation | Registers |
|---|---|
//nexus:provide | A constructor (nexus.Provide) |
//nexus:rest <METHOD> <PATH> | A REST endpoint |
//nexus:query / //nexus:mutation / //nexus:subscription | A GraphQL field |
//nexus:ws <PATH> <TYPE> | A WebSocket message handler |
//nexus:worker <NAME> | A background worker |
//nexus:job [queue] [timeout=D] [retry=N] [unique=D] [name=X] | A background job (jobs.Define on a method, jobs.DefineFunc on a function) |
//nexus:page <METHOD> <PATH> [Component] | An Inertia page (inertia.Page; on a controller method the component defaults to <Folder>/<Method>) |
//nexus:controller <prefix> [trailing-slash] | On a type: a controller whose annotated methods are its actions |
//nexus:live [<path>] | On a type: a live view (view.Live) routed at <path>, gated by the type's //nexus:auth / //nexus:use; with no path, registered to be embedded only |
//nexus:auth Required / //nexus:auth Requires PERM… / //nexus:auth Public | Modifier: an auth gate (bare tokens; legacy Requires("X") also accepted) |
//nexus:session Required | Modifier: flow-continuity gate — 428 unless the request arrived with an established session |
//nexus:use <expr> | Modifier: per-op middleware |
//nexus:module <name> / //nexus:path <prefix> / //nexus:routeprefix <prefix> | Package doc comment: name the module group, prefix its routes (nexus.Path/nexus.RoutePrefix) |
//nexus:<pkg>.<Func> args… | A custom decorator from an extension, for example //nexus:inertia.Page GET /users Users/Index |
A custom decorator becomes pkg.Func(args…, fn). The codegen resolves the pkg import by looking, in order, at:
- the annotated file's imports
- the other files in the same package
- a
[decorators.imports]hint innexus.toml - the module's import graph — where your own module's packages outrank dependencies:
//nexus:use utils.Wrap(...)means the project'sutilseven when three dependencies ship a package by that name, with no import and no hint. Only a tie inside the module, or between foreign packages with no local candidate, asks you to disambiguate.
Package selectors inside //nexus:use (and type-level //nexus:use) expressions resolve through the same cascade, so the annotated file needs no import — not even a blank one — for the packages its expressions name. The import lands only in the generated file. An identifier that names a top-level declaration of the annotated package (cfg.Timeout) is recognised as a value and skipped outright — it never reaches the module graph, and no shadowing import is synthesized for it; anything else the cascade cannot place is left alone.
Errors are strict and positioned
Every mistake fails at the annotation with a file:line your editor can jump to — never as a compile error inside the invisible generated file:
- An unknown keyword is an error — the
nexus:namespace belongs to nexus, so there is nothing to coexist with. A typo (//nexus:quer,//nexus:Rest,//nexus:mutations) gets a did-you-mean suggestion. - The v1 spelling (
//@rest, or gofmt's// @rest) is rejected with itsfile:lineand a pointer tonexus migrate v2, which rewrites it. Other tools'@-annotations (swag's// @Summary, for one) are left alone. // nexus:rest(with a space) is not a Go directive — gofmt and go/doc treat it as prose — so it is rejected too; write//nexus:rest.//nexus:restvalidates the HTTP method (and normalises case, so//nexus:rest get /usersregisters asGET) and requires the path to start with/.//nexus:wschecks its path the same way.//nexus:query///nexus:mutation///nexus:subscription///nexus:providereject stray arguments — the op name derives from the function; override it with//nexus:use nexus.Op("name").//nexus:authand//nexus:useexpressions are parse-checked at the annotation.- Known extension decorators are validated too:
//nexus:inertia.Pagetakes bare tokens (//nexus:inertia.Page get,post /login Login— quoting optional, verbs case-normalised) and rejects a wrong arg count, a non-HTTP verb, or a bad path at the annotation.
Auth and session gates
The //nexus:auth modifier reads naturally — bare tokens, capability case-insensitive:
//nexus:auth Required // auth.Required()
//nexus:auth Requires ADMIN HR // auth.Requires("ADMIN", "HR")
//nexus:auth Public // nexus.Public() — the deny-by-default opt-out//nexus:session Required attaches session.Required(), the flow-continuity gate: 428 Precondition Required unless the request arrived with an established session. See Sessions.
Package-level directives
A package's registration group is configured on the package doc comment:
// Package billing handles invoicing.
//
//nexus:module billing
//nexus:path /billing
package billing//nexus:module <name>names the generatednexus.Module(default: the package name).//nexus:path <prefix>prefixes the module's REST and GraphQL routes (nexus.Path).//nexus:routeprefix <prefix>is the REST-only variant (nexus.RoutePrefix).
Scope is enforced both ways: a package directive on a function — or a function directive on the package doc — is a positioned error, and two files declaring conflicting values error naming both locations.
Controllers
Methods can be annotated too, and the generated code calls them as method expressions such as (*UsersController).Show, with the receiver supplied by DI. Without //nexus:controller, a type's annotated actions go to the nexus.Controller or nexus.Resource your code declares for it. Your code keeps the module, path and gates, and the annotations bring the routes (annotated actions, declared in Go). Put //nexus:controller <prefix> on the type to declare the whole controller with annotations:
//nexus:controller /users trailing-slash
//nexus:auth Required
type UsersController struct{ users *UserService }
//nexus:page GET /
func (c *UsersController) Index(ctx context.Context) (IndexProps, error)
//nexus:page GET /:id/view Admin/UserDetail
//nexus:auth Requires view_user
func (c *UsersController) Show(ctx context.Context, id int64) (ShowProps, error)
//nexus:mutation
func (c *UsersController) SaveUser(ctx context.Context, in SaveUser) (*User, error)- Type-level modifiers are shared.
//nexus:auth,//nexus:sessionand//nexus:useon the type apply to every action. - Paths are relative to the prefix.
/or""is the prefix itself.trailing-slashregisters each route at both/xand/x/. - An action may map to several routes with more than one
//nexus:pageor//nexus:restline. A plain function still registers exactly once. - Actions take
//nexus:page,//nexus:rest,//nexus:queryand//nexus:mutation.//nexus:inertia.Pageon an action reads as//nexus:page. - The controller is its own router, so an action can't take
//nexus:on. - The constructor still needs
//nexus:provide(or any other provider). - Directives may sit anywhere in the doc comment. gofmt moves
//nexus:lines below the prose; every line is read.
Routers (FastAPI-style)
For grouping beyond one-module-per-package, declare routers: named groups with stacking prefixes, shared gates, and cross-package membership.
// Package api.
//
//nexus:router v1 /api/v1
//nexus:router billing /billing parent=v1 auth=Requires(ADMIN)
package apiThe name is optional when the router is the package — the same default //nexus:module uses. //nexus:router <prefix> names the router after the package, and every op in that package joins it automatically:
// Package billing.
//
//nexus:router /billing parent=v1
package billing
//nexus:rest GET /invoices
func NewListInvoices(...) (...) // joins "billing" — no //nexus:on needed(One package-named router per package; it replaces //nexus:module///nexus:path there, and mixing them is an error. //nexus:on <other> on an op still wins.)
For cross-package routers, declare with an explicit name; any handler in any package then joins with //nexus:on:
//nexus:rest GET /invoices
//nexus:on billing
func NewListInvoices(...) (...) // serves /api/v1/billing/invoices, ADMIN-gated- Prefixes stack through
parent=; sharedauth=gates apply to every member op (parents' gates first), ahead of the op's own options. - Each router is its own dashboard module; ops without
//nexus:onstay on the package module as before. - Strictness as usual: an unknown router name in
//nexus:onerrors with a did-you-mean over the declared names, conflicting re-declarations name both locations, unknown parents and parent cycles are positioned errors.
The same model is available as plain Go — nexus.NewRouter(name, prefix, shared...), .Rest/.Query/.Mutation/.WS/.Worker/.Provide, and .Include(child); pass only the root router to Boot. See Modules & services.
How the wiring is generated
nexus devandnexus buildgenerate the registrations on the fly and pass them togo buildas an overlay. Nothing is written to your source tree.nexus generate handlers ./...writes anexus_handlers_gen.goper package, plus an import aggregator in the main package. Commit these files when you need a barego build,go testorgo installwithout the CLI, or when static tools such as gopls and linters should see the registrations.nexus generate handlers --checkfails when the committed files are out of date. Use it as a CI drift gate.
Testing annotated modules in isolation
nexus generate handlers (the eject path) is what makes annotated registrations visible to a bare go test — but the registry they drain from is process-global, so a test binary whose files link several annotated packages hands every package's registrations to every boot. An InProcess boot of one module then fails on the other packages' missing providers.
Scope the boot instead:
app, stop, err := nexus.InProcess(config.Runtime{},
nexus.DecoratedModules("adverts"), // only adverts' //nexus: registrations
adverts.Module,
/* the module's own deps */)Only drained modules named in the list participate (decorated modules are named after their package; main registers as "app"). nexus.DecoratedModules() with no names drops every decorated registration — a boot fully isolated from annotations. A linked framework package's own plumbing — the view runtime's /_view/*.js, the component kit's assets — registers with nexus.RegisterBuiltinOptions and is never dropped, so live pages work in a scoped boot.