devserver

Documentation

Overview

Package devserver implements viteless.Host backed by nexus's existing frontend machinery — the SFC compiler, the esbuild single-file transform, and the nexus.lock/.nexus-cache resolver. It is the seam that lets `nexus dev` serve the SPA unbundled (one module per URL, one Vue instance, real state-preserving HMR) instead of bundling, while `nexus build` keeps using the bundler unchanged.

The Host plugs three operations into viteless:

• LoadModule — bytes for a served URL: user source under Root, or a cached dependency blob under DepPrefix.
• Transform — one file → browser JS: .vue via the SFC compiler (+ an HMR accept footer), .ts/.tsx/.jsx/.json via esbuild's single-file Transform, .js/.mjs passthrough.
• ResolveImport — a specifier → the URL the browser should fetch: relative/alias imports stay in the source tree; bare and registry-internal imports go through the shared resolver and are served from the cache under DepPrefix.

Index

• Constants
• type Alias
• type Config
• type Host
  • func New(cfg Config) *Host
  • func (h *Host) LoadModule(urlPath string) ([]byte, string, bool)
  • func (h *Host) ResolveImport(spec string, kind viteless.SpecKind, importerURL string) string
  • func (h *Host) Transform(urlPath string, src []byte) ([]byte, error)

Constants

const PrebundlePrefix = "/@pre/"

PrebundlePrefix is the URL namespace pre-bundled package entries are served under (distinct from DepPrefix's per-module blobs).

Types

type Alias

type Alias struct {
	Prefix string // import prefix (wildcard) or full specifier (exact)
	Dir    string // target dir (wildcard) or target file (exact)
	Exact  bool   // true → whole-specifier → single file mapping
}

Alias maps an import specifier to a filesystem target, mirroring a tsconfig "paths" entry. Two shapes:

• Wildcard: Prefix "@/", Dir "<root>/src", Exact=false — from "@/*": ["./src/*"]. The text after Prefix is joined onto Dir.
• Exact: Prefix "nexus-client", Dir "<root>/src/sdk/client.js", Exact=true — from "nexus-client": ["src/sdk/client.js"]. The whole specifier maps to that one file.

The target is expected to live under Root so it can be served.

type Config

type Config struct {
	// Root is the directory served as the dev origin: index.html lives
	// here and a URL path "/x/y" maps to <Root>/x/y. Required.
	Root string

	// IndexHTML is an optional absolute path to the SPA shell when it
	// doesn't live under Root. The nexus layout keeps source under
	// islands.src/ (= Root) but the shell index.html under islands/ (the
	// build-output dir); without this the dev server has no index to serve
	// and the SPA can't boot. The entry <script> in it is rewritten to the
	// real source entry on serve (its checked-in /main.js points at the
	// production bundle, which doesn't exist in unbundled dev).
	IndexHTML string

	// Resolver carries the lockfile + store + on-demand/dev-rewrite hooks
	// the shared resolver uses to turn bare specs into cached blob URLs.
	Resolver resolver.Options

	// Compiler compiles .vue SFCs. nil disables Vue (a .vue request then
	// surfaces a transform error / overlay).
	Compiler vue.SFCCompiler

	// Aliases are tsconfig-style path aliases resolved against the source
	// tree before the dependency resolver is consulted.
	Aliases []Alias

	// Env carries import.meta.env.<NAME> substitutions (the VITE_* vars
	// from .env files). Inlined as esbuild Defines during Transform so a
	// real app's `import.meta.env.VITE_API` reads the value at dev time.
	Env map[string]string

	// Mode is the dev mode injected as import.meta.env.MODE alongside the
	// DEV/PROD booleans. Typically "development".
	Mode string

	// DepPrefix is the URL namespace cached dependency blobs are served
	// under. Defaults to "/@dep/".
	DepPrefix string

	// Prebundle enables dependency pre-bundling: each npm package is
	// esbuild-bundled into one file on first request (intra-package
	// siblings inlined, cross-package imports kept external + shared), so
	// the browser fetches one file per dep instead of hundreds. Off by
	// default — a pure perf layer over the per-module path, which stays
	// the fallback for any package that fails to bundle.
	Prebundle bool
}

Config configures a Host.

type Host

type Host struct {
	// contains filtered or unexported fields
}

Host implements viteless.Host.

func New

func New(cfg Config) *Host

New builds a Host from cfg.

func (*Host) LoadModule

func (h *Host) LoadModule(urlPath string) ([]byte, string, bool)

LoadModule returns the source bytes + kind for a served URL path.

func (*Host) ResolveImport

func (h *Host) ResolveImport(spec string, kind viteless.SpecKind, importerURL string) string

ResolveImport maps an import specifier to the URL the browser should fetch. importerURL is the served path of the importing module.

func (*Host) Transform

func (h *Host) Transform(urlPath string, src []byte) ([]byte, error)

Transform compiles one source file to browser JS. viteless only calls this for "js"-kind modules; dispatch is by extension.