Skip to content

CLI ​

bash
go install github.com/paulmanoni/nexus/cmd/nexus/v2@latest

Or pin it in the project's go.mod as a tool, and run it with go tool nexus …:

bash
go get -tool github.com/paulmanoni/nexus/cmd/nexus/v2@latest

nexus new <dir> ​

Scaffolds a runnable app with a nexus.toml.

Flag
--frontend vue|reactAdd a Vite project under web/
--inertia [--ssr]Inertia (Vue) pages, with optional server-side rendering
--db, --cache, --authWire a database, a cache and auth
--module <path>Set the Go module path
--yesTake the defaults without prompting

nexus init [dir] ​

Adds a Vite frontend (web/) to an existing project and updates main.go to embed and serve it.

Flag
--frontend vue|reactRequired
--forceAdd the project files to an existing web/, keeping index.html and src/. Replaced config files are saved as <file>.orig.

nexus dev [dir] ​

Builds and runs the app, rebuilds on save, and runs the frontend's Vite beside it. See The dev loop.

Flag
--addr host:portOverride the listen address
--openOpen a browser once the app answers
--frontend <dir>Frontend directory (relative to the working directory)
--distKeep web/dist rebuilt with vite build in the background
--debugKeep DWARF debug info (for delve)
--no-embed-stubEmbed the real frontend bundle in the dev binary
--view-filesWrite the compiled views (*_templ.go, view_gen.go, view_imports_gen.go) to disk, for an editor on plain gopls; by default they are compiled in memory
--verboseShow all of Vite's output
--log-format, --log-pattern, --raw-logsLog formatting
--tuiTerminal UI

nexus build [pkg] ​

Installs frontend dependencies if needed, runs vite build (and the SSR build when src/ssr.ts exists), then runs go build, embedding web/dist.

Flag
-o, --out <path>Where to write the binary
--frontend <dir>Frontend directory

nexus client ​

Writes the client SDK to disk, for vendoring.

bash
nexus client --out ./web/sdk                                  # client.js + vue.js
nexus client --out ./web/sdk --url http://localhost:8080      # plus manifest + types
nexus client --out ./web/sdk --manifest ./manifest.json       # offline
nexus client --out ./web/sdk --tsconfig ./web/tsconfig.json   # merge path mappings

nexus generate ​

Command
nexus generate handlers [./...]Write the registrations for //nexus: decorators. --check is a CI drift gate.
nexus generate frontendGenerate a typed TypeScript source tree from a manifest. --check is a drift gate.
nexus generate views [dir]Compile the .templ views to Go on disk (*_templ.go, view_gen.go, view_imports_gen.go) for a plain go build; nexus dev and nexus build compile them in memory. Prints the compiler's warnings. --check is a drift gate.

nexus migrate v2 [dir] ​

Rewrites a nexus v1 project for v2, in place. Re-running it is a no-op, and --dry-run lists every change without writing. What it can't rewrite gets a // TODO(nexus v2): … comment naming the replacement. Step by step: Migrating to v2.

RuleRewrites
importsGo and templ import paths: github.com/paulmanoni/nexus[/p] → …/nexus/v2[/p] (view included); the separate modules — cmd/nexus, di/fxcontainer, extension/cache/redis, extension/jobs/jobsamqp, extension/jobs/jobsredis, httpx/ginrouter — take /v2 on their own path. Only import specs change.
symbolsMoved and renamed names, on selectors of a nexus import (aliases followed, shadowing locals left alone): nexus.Config → config.Runtime, nexus.ServerConfig → config.Server, nexus.Get → config.Get, nexus.MustLoadConfig → config.MustLoad and every other config name, nexus.Cache → resource.Cache, graph.FieldMiddleware/FieldResolveFn/ResolveParams → gql.Middleware/Resolver/Field, PreserveDev/IsDev/… → the dev package, NewNotifier/Notifier/Bus → the notify package, ServeFrontend → Frontend, ClientIPFromCtx → ClientIP, AsRestHandler → AsRest, nexus.UseVolume → nexus.DeclareVolume, auth.Describe → auth.InspectExtractor. The target package is imported (as nexusconfig when config is taken in the file) and an import left unused is dropped. MustLoadDotenv(), LoadDotenvIfPresent() and WithClientIP are dropped from their option list with a TODO. nexus migrate v2 --help lists the whole table.
errorsnexus.NewErrors() → nexus.Invalid(), nexus.Errors → nexus.Error, nexus.ErrForbidden → nexus.Forbidden, the boot option nexus.Error(err) → nexus.FailBoot(err); a TODO on each MapCRUDError.
tagsThe retired uri:"x" struct tag becomes path:"x" in Go files that import nexus.
go.modrequire/replace lines for those modules move to the new paths at v2.0.0; a …/nexus/view requirement is dropped. Run go mod tidy afterwards.
annotations//@x and // @x nexus annotations in .go and .templ files become //nexus:x directives; other tools' @-annotations are left alone.
nexus.tomlKeys in the wrong table (a top-level environment, an addr under [runtime]) move to the one table the strict check pins them to. Typos and undeclared sections are left for nexus config check.
assemblyA TODO on Middleware.Global (→ nexus.Middleware), AsCRUD (→ nexus.Resource), and nexus.Invoke of Ensure*/Migrate*/Seed*/Backfill* functions (→ nexus.Setup).
op namesv1 dropped a New prefix from op names; AsQuery/AsMutation/AsSubscription registrations of NewXxx handlers get nexus.Op("xxx") and NewXxx functions annotated //nexus:query/mutation/subscription get //nexus:use nexus.Op("xxx"), so GraphQL field names don't move.
fieldsmiddleware.Middleware{Gin: …} literals become {HTTP: …}.
spreadsnexus.MustLoadExtensions()... loses its spread (it returns one Option).
sectionsEvery top-level nexus.toml section nothing declares is declared free-form, config.Section[map[string]any]("name"), in main.go and in each package that reads it, with a TODO to give it a struct.

Changed .go files are gofmt'ed. vendor, node_modules, testdata and hidden directories are skipped.

nexus config ​

Command
nexus config check [path]Validate a nexus.toml with the boot rules — unknown keys, misplaced keys, undeclared sections — and exit 1 on a problem. --json for CI. Reads the app's config.Section declarations from its source.
nexus config schemaPrint the JSON schema for nexus.toml (--framework: nexus's tables only).
nexus auth check [path]Validate nexus.toml's [auth] table as boot does and print the effective setup: schemes in order, default gate, pages and areas, endpoints, session/throttle/password rules. Exit 1 on a problem.

Tooling ​

Command
nexus lspA language server for editors: proxies gopls and opens the generated Go (compiled views, //nexus: registrations) as editor buffers, and marks what keeps a live page from tracking its changes as warnings. See views.
nexus test [packages] / nexus vet [packages]go test / go vet through the same overlay nexus build uses, so no generated file is needed on disk.
nexus doctorCheck the project: Go against go.mod, the module on nexus v2, nexus.toml, Node / the package manager / Vite, the Tailwind CLI, generated view files, and live pages that can't track their changes. nexus doctor - audits a deployment manifest on stdin.
nexus add ui <component>...Vendor view/ui components into the app (--dir, default ./ui).
nexus release <version>Release a multi-module repository: CHANGELOG and tree checks, tags in dependency order, push, CLI install check. Prints the plan; --yes runs it.

nexus docs [topic] ​

Prints the built-in quick reference for a topic. nexus docs --list lists the topics, and --web opens this site.

Other commands ​

Command
nexus pki ...Generate mTLS certificates for the peer mesh
nexus versionPrint the CLI version

Released under the MIT License.