Run With lazy

Start the app

Run lazy from the application module:

lazy

The command reads go.mod, selects ./cmd/<module-name> or ./cmd/app, builds a temporary lazydev binary, starts it on an internal loopback address, and proxies the public address.

lazydev builds read views and public files from the local filesystem. By default, lazy passes app/views and app/public into the build with -ldflags; use --viewpath or --publicpath to override those roots for nonstandard app layouts.

Development assets are served by logical path. Helpers such as asset_path return /styles.css instead of /styles-<hash>.css, and GoLazy does not add asset cache headers in development.

When view files change, lazy asks the running lazydev app to rebuild its view cache through the dev control-plane endpoint under /_golazy/, then reloads the browser. The app process is not rebuilt for view-only edits. Public file edits also avoid an app rebuild; lazy reloads the browser because public assets are read from disk on demand in development.

Before building, lazy runs go mod tidy only when Go workspace mode is inactive. If GOWORK or go env GOWORK points at an active workspace, lazy skips tidy and builds with the workspace as-is.

Proxy startup, generated-asset work, builds, and app starts are shown as compact progress tasks. Successful task output stays hidden, failed task output is printed, and the application process still writes directly to the terminal.

Open a tmux workspace

Apps can opt into a tmux development workspace with lazy.toml:

services = ["postgres", "s3"]

[tmux]
session = "my-app"

[[runners]]
name = "tailwind"
command = "lazy tailwind --watch"

[[programs]]
name = "editor"
command = "nvim"
window = "workspace"

When lazy.toml is present, the default lazy command opens tmux through mise. Service panes run mise run <service>:start, runner panes run their configured commands, the app pane runs the normal GoLazy development loop, and the command-center pane runs:

lazy command-center

Define service lifecycle actions as mise tasks named {service}:{action}. {service}:start is required and should run the service in the foreground so SIGINT stops it. Optional actions include kill, dump FILE, load FILE, create, and migrate.

Match the app version

App-bound lazy commands use the CLI version that matches the app's golazy.dev requirement in go.mod. If the directly invoked binary is a different version, it looks for the matching binary under the user cache:

golazy/lazy/builds/<version>/lazy

If that binary is missing, lazy installs it with go install and then re-runs the same command with the matching version. lazy --version and lazy new always use the binary you invoked directly.

Set LAZY_MULTIVERSION=off when testing a local CLI binary against an app that intentionally requires another framework version:

LAZY_MULTIVERSION=off lazy js

Choose the public address

Use ADDR or PORT when the default 127.0.0.1:3000 is not what you want:

ADDR=127.0.0.1:4000 lazy
PORT=4000 lazy

A numeric value is treated as a port. A full host:port value is used as the listen address.

Let lazy rebuild

When source files change, lazy rebuilds and restarts the app after a successful build. Apps with js.toml also run the JavaScript pipeline before the initial build and after relevant JavaScript changes:

app/js/app.js
app/js/controllers/hello_controller.js
js.toml
package.json
package-lock.json

Tailwind still runs through lazy tailwind, usually in a separate watch process during UI work:

lazy tailwind --watch

The lazy server watches the generated public CSS and reloads pages after the application rebuilds.

Press Ctrl-C to stop the development loop. lazy forwards an interrupt to the running app, waits briefly for it to clean up, then exits. If the app exits cleanly or because of an interrupt, lazy exits too instead of leaving the watcher running.

Build directly when needed

Production builds stay ordinary Go builds:

lazy js
lazy tailwind
go build -o .tmp/build/app ./cmd/app

Use Generated Assets Before Build for the build-time asset checklist.