Vite frontend
A nexus frontend is an ordinary npm-managed Vite project under web/. It can use any framework, Vite plugin or npm library. nexus build runs the Vite build and embeds web/dist in the Go binary, so you still deploy one file, and the server needs no Node.js.
Create one
nexus new my-app --frontend vue # or react
nexus new my-app --inertia [--ssr] # server-driven Inertia pages (Vue)
nexus init --frontend vue # add web/ to an existing projectThen run go mod tidy && nexus dev. The first run installs dependencies.
Layout
web/
package.json vite, the framework plugin, typescript
package-lock.json commit it (or pnpm / yarn / bun's lockfile)
vite.config.ts plugins: [vue(), nexus()]
tsconfig.json
index.html the entry HTML (also the Inertia page shell)
sdk/ commit it: the Vite plugin and the typed client SDK
src/
main.ts
App.vue
dist/ build output, embedded in the binary
index.html a committed stub, so the first go build compilesnode_modules/ and dist/* (except the stub) are gitignored.
Wiring
import "embed"
//go:embed all:web/dist
var webFS embed.FS
func main() {
nexus.Boot(nexus.Frontend(webFS, "web/dist"), usersModule)
}nexus.Frontend works with single-page apps:
- A path without an extension falls back to
index.html. - REST, GraphQL and WebSocket routes win on conflict.
nexus.FrontendAt("/admin")mounts the app under a sub-path.- It provides
*nexus.Documentinto DI: the page shell — the builtindex.htmlin production, Vite's live one undernexus dev. Middleware and renderers take it as a parameter (doc.Get(ctx)) instead of reading the embed, which would be stale in dev.
Caching follows the build. A file is served immutable only when the Vite manifest lists it and its name carries a content hash. Everything else, including index.html, is revalidated with an ETag.
In production, boot fails fast if the bundle has neither index.html nor a Vite manifest. In development, an unbuilt bundle serves a placeholder page.
Development: one origin
The Vite plugin connects the two processes:
// web/vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import nexus from './sdk/nexus-vite-plugin.js'
export default defineConfig({
plugins: [vue(), nexus()],
})While vite dev runs, the plugin writes a small hot file (web/dist/.vite/nexus-hot.json) with the dev server's real address, and removes it on exit. The Go app reads that file, and pages it serves load their modules from Vite with full HMR.
You always open the app's own origin (http://localhost:8080). There is no proxy block to maintain and no second URL. nexus dev runs Vite for you. Running npm run dev and go run . in two terminals works the same way.
The hot file is followed only under nexus dev or with environment = "development", and only while its dev server is alive. A file left behind by a killed Vite is ignored.
Production build
nexus build -o my-app- Installs dependencies if
node_modules/.bin/viteis missing. It uses the project's own package manager (frompackageManageror the lockfile), frozen to the lockfile. - Refreshes
web/sdk/nexus-vite-plugin.*. - Runs
vite build, withbuild.manifestforced on. - Runs
vite build --ssr src/ssr.tstoo, when that file exists. - Runs
go build, which embedsweb/dist.
A directory without a package.json is served as-is and never built. That fits a hand-written or prebuilt dist.
Which directory
nexus dev and nexus build pick the frontend directory in this order:
- the
--frontend <dir>flag - the
NEXUS_FRONTEND_DIRenvironment variable - the directory named in
main.go'snexus.Frontendcall web/, when it has apackage.json
Values from nexus.toml
[env] values reach frontend code as import.meta.env.<dotted.key>. See the [env] bridge.