Upgrade Guide

Upgrade from v0.1.12

GoLazy v0.1.13 adds control-plane probes, native desktop helper commands, the first lazy upgrade workflow, the golazy.dev/lazy CLI vanity module path, and generated-app development-environment cleanup. Existing v0.1.12 applications do not need a large rewrite.

Update the framework requirement:

go get golazy.dev@latest
go mod tidy

Read Install GoLazy for the current install and module setup flow.

Install or update the matching CLI so lazy new selects the latest sample application template:

curl -fsSL https://golazy.dev/install.sh | sh
lazy --version

Read Run With lazy for the development command and Full App for the generated application layout. The new Development guide collects the mise, service, asset-pipeline, Tailwind, and lazy workflow conventions in one place.

Automatic upgrade command

Use lazy upgrade from the application module to apply supported one-step migrations:

lazy upgrade
lazy upgrade --target v0.1.13
lazy upgrade --force v0.1.10

The command reads the current golazy.dev requirement from go.mod. For the v0.1.12 -> v0.1.13 step it updates go.mod, runs go mod tidy, go test ./..., and go vet ./..., and prompts to remove stale Go entries from mise.toml because Go already handles toolchain selection through the module go directive.

For older generated apps, lazy upgrade can also apply the backfilled v0.1.10 -> v0.1.11 and v0.1.11 -> v0.1.12 migrations: it updates recent generated-app mise task layout, moves generated-app services from app/services to top-level services, and rewrites matching Go imports. Use --force <version> to rerun the supported one-step migration that starts at that version, even when go.mod currently records another version.

Use --dry-run to inspect changes before writing them. If a template-owned file appears customized, lazy upgrade prints a diff, writes the proposed file under .golazy/upgrade/conflicts, and stops so you can edit deliberately. Continue with the manual notes below when an app has custom structure or an older unsupported upgrade step.

Mise toolchain cleanup

Generated app mise.toml files should not install Go:

[tools]
node = "24"

If your app still lists go = "1.26.0" under [tools], remove that line. Go already bundles multi-version support through the module go directive and toolchain selection.

Control-plane probes

Generated apps now enable framework-owned probes:

ControlPlane: lazycontrolplane.Config{},

Add that config when your deployment wants built-in GET /livez and GET /readyz endpoints. Use CONTROL_PLANE_ADDR when probes, metrics, or pprof should run on a separate listener. Read Control Plane.

CLI vanity module path

Install or update the CLI through the vanity module path:

go install golazy.dev/lazy@latest

The repository remains github.com/golazy/lazy, but install docs and app-versioned CLI handoff now use golazy.dev/lazy.

Native desktop helper

Use the native helper when you want a desktop window around the current app:

lazy native
lazy native build

This is optional. The normal server-first GoLazy development and deployment flow does not require native desktop support. Read Native Desktop.

Older v0.1.12 changes

If you are upgrading from v0.1.11 or earlier, first read the v0.1.12 upgrade guide for service-layout, asset-upload, S3-compatible storage, app-versioned CLI, and tmux workspace changes.

Versioned guide

Use the v0.1.12 upgrade guide when you need the exact upgrade path from v0.1.11 to v0.1.12.