dev

package
v0.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 14, 2026 License: MIT Imports: 22 Imported by: 0

Documentation

Overview

Package dev holds the development loop, S15.

`avero dev` runs a proxy in front of the application. The proxy serves the reload channel at /_avero/reload, and it adds the reload client to an HTML answer. The application therefore carries no development code, and a production build holds none of it.

A change to a CSS file rebuilds the stylesheet and sends the new address to the browser. The page swaps the link element, so no process restarts and no page reloads. See DX-2.

A change to a Go file or to a templ file rebuilds the binary and starts it again. The proxy holds the request until the new process answers, so the browser keeps its page and its scroll position. See DX-3.

Index

Constants

View Source
const (
	// ReloadPath is the address of the reload channel.
	ReloadPath = "/_avero/reload"
	// HealthPath is the address that the proxy polls after a restart.
	HealthPath = "/healthz"
	// StartTimeout bounds the wait for a child that starts.
	StartTimeout = 30 * time.Second
	// RequestWait bounds the wait of one request during a restart.
	RequestWait = 10 * time.Second
	// EnvDevelopment is the environment that carries the loop.
	EnvDevelopment = "development"
)

The defaults of the loop.

View Source
const Debounce = 20 * time.Millisecond

Debounce is the time that the watcher waits after a change, so one save of an editor gives one rebuild.

Variables

View Source
var TemplCommand = []string{"go", "tool", "templ", "generate", "--watch"}

TemplCommand is the tool that watches the templ files. Avero wraps it and writes no generator and no watcher of its own. See the SDD, S15.

The application carries the tool in its go.mod, so `go tool templ` runs the version that the application pins and a person installs nothing.

Functions

func Client

func Client() []byte

Client returns the reload client. `avero dev` adds it to an HTML answer.

func Group

func Group(cmd *exec.Cmd)

Group puts a command in a process group of its own.

`go tool templ` starts the tool as a child of its own, so a kill of the command leaves the tool behind. The tool then holds the output of the loop, and the loop never ends. A kill of the group ends both.

func HasTempl

func HasTempl(dir string) bool

HasTempl reports a tree that holds a templ file.

func KillGroup

func KillGroup(cmd *exec.Cmd)

KillGroup ends a command and every process that it started.

Types

type Config

type Config struct {
	// Dir is the root of the application.
	Dir string
	// Port is the port that the browser reads.
	Port int
	// ChildPort is the port of the application. A zero value takes a free
	// port.
	ChildPort int
	// Env states the environment. The loop runs in development only.
	Env string
	// Out receives the log of the loop and the output of the application.
	Out io.Writer
	// BuildCSS rebuilds the stylesheet and returns its address. A nil value
	// builds with the asset pipeline of the project.
	BuildCSS func(ctx context.Context) (string, error)
	// BuildScript rebuilds the bundle of the front end. A nil value builds
	// with the asset pipeline of the project.
	BuildScript func(ctx context.Context) error
	// BuildGo rebuilds the binary of the application. A nil value runs the
	// Go tool.
	BuildGo func(ctx context.Context) error
	// Start starts the application and returns the process. A nil value runs
	// the binary that BuildGo wrote.
	Start func(ctx context.Context, port int) (Process, error)
	// FrontEnd runs the development server of the front end, such as Vite. A
	// nil value runs none, and the loop then owns the assets itself.
	FrontEnd []string
	// FrontEndDir is the directory of that command, relative to Dir. The
	// watcher skips it, because the development server of the front end
	// watches it.
	FrontEndDir string
	// AssetDir holds the built assets. The proxy serves them from the disk,
	// because the binary of the application carries the copy of the last
	// build. A CSS change therefore reaches the browser with no restart.
	// See DX-2.
	AssetDir string
	// AssetBase is the URL prefix of the assets. An empty value is
	// /assets/.
	AssetBase string
}

Config states one development loop.

type ExitAware

type ExitAware interface {
	// Exited returns a channel that carries the end of the process.
	Exited() <-chan error
}

ExitAware is the optional contract of a process that reports its own end. The loop states the fault at once instead of waiting for the health endpoint. See DX-7.

type Process

type Process interface {
	// Stop ends the process and waits for it.
	Stop() error
}

Process is one running application. The loop stops it and starts it again.

func StartTempl

func StartTempl(ctx context.Context, dir string, out interface{ Write([]byte) (int, error) }) (Process, error)

StartTempl runs `templ generate --watch` in the tree.

The tool writes the Go file of each templ file. The loop then sees the Go file change and rebuilds, so the two steps compose and Avero writes no generator of its own.

A tree with no templ file starts nothing. A tree that holds one and finds no templ binary returns a fault that states the repair.

type Server

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

Server is the development loop. It watches the tree, rebuilds and proxies.

func New

func New(cfg Config) (*Server, error)

New builds the loop.

func (*Server) Addr

func (s *Server) Addr() string

Addr returns the address that the browser reads.

func (*Server) Changed

func (s *Server) Changed(ctx context.Context, files []string) error

Changed answers one change of the tree. A test calls it with no watcher.

func (*Server) Clients

func (s *Server) Clients() int

Clients returns the number of browsers that listen on the reload channel.

func (*Server) Handler

func (s *Server) Handler() http.Handler

Handler returns the handler of the proxy. A test drives it with no listener.

func (*Server) Run

func (s *Server) Run(ctx context.Context) error

Run starts the application, watches the tree and serves the proxy. It returns when the caller cancels the context.

func (*Server) Sweep

func (s *Server) Sweep(since time.Time) []string

Sweep returns the source files of the tree that changed after a time. The loop calls it after each rebuild, and a test reads it.

func (*Server) Watch

func (s *Server) Watch(ctx context.Context) ([]string, error)

Watch returns the source files of the first change of the tree. A test reads it. The loop runs the same watcher.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL