Upgrade Guide

Upgrade from v0.1.14

GoLazy v0.1.15 replaces app context initializers with dependency initializers and changes lazyapp.Config.SEO to a context-aware function. Existing v0.1.14 applications should use lazy upgrade so the source rewrite is applied consistently.

Install or update the matching CLI:

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

Run the application migration:

lazy upgrade

lazy upgrade applies the framework module update with the Go command, using the release's go.mod manifest. It also applies any mise.toml tool manifest for the release: new tools are added, changed tool versions are updated, and obsolete tool or task entries are commented with a reason instead of removed silently.

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.

Dependency initializer migration

lazyapp.Config.Context is replaced by lazyapp.Config.Dependencies. The initializer now receives a framework-owned *lazydeps.Scope:

func Dependencies(deps *lazydeps.Scope) error {
    _, err := lazydeps.Service(deps, "posts", func(ctx context.Context) (
        context.Context,
        *postservice.Service,
        error,
        context.CancelFunc,
    ) {
        posts, err := postservice.New()
        if err != nil {
            return ctx, nil, fmt.Errorf(
                "initialize posts service: %w",
                err,
            ), nil
        }

        return postservice.WithContext(ctx, posts), posts, nil, nil
    })
    return err
}

lazy upgrade migrates v0.1.14 apps by renaming init/context.go to init/dependencies.go, changing Context to Dependencies, and rewriting the lazyapp.Config field. Review the result when the old initializer had custom control flow, then run go test ./....

Read Application Startup and Dependencies And Services.

CLI setup behavior

lazy new now checks https://golazy.dev/lazy.version before cloning a remote template. If a newer CLI is available, update first or pass --skip-update-check deliberately:

lazy new github.com/user/my_app
lazy new --version v0.1.13 github.com/user/old_app
lazy new --skip-update-check github.com/user/offline_app

Generated apps validate with the current go on PATH. Non-Go app-managed tool subprocesses, such as the package-manager work inside lazy js and lazy tailwind, still run through mise exec so tools installed by the app's mise.toml are available without opening a new shell.

lazy new also initializes a fresh Git repository and commits the generated checkout with a command-local GoLazy identity after validation succeeds.

SEO metadata

lazyapp.Config.SEO is now a function that receives the dependency-initialized app context. Put that function in init/seo.go:

func SEO(ctx context.Context) []lazyseo.Option {
    return []lazyseo.Option{
        lazyseo.SiteName("GoLazy"),
        lazyseo.Description("A GoLazy application."),
        lazyseo.Language("en"),
        lazyseo.TwitterCardType("summary"),
    }
}

Wire it from init/app.go:

SEO: SEO,

lazy upgrade moves simple inline SEO: []lazyseo.Option{...} config into init/seo.go automatically. Review the result when the old SEO defaults used custom helper functions or imports.

Apps that set social metadata can also include image alt text, image dimensions, and published timestamps:

c.SEOImageAlt("Hello post social preview")
c.PublishedTime(post.PublishedAt)
c.OpenGraph(lazyseo.OpenGraph{
    Image: "/posts/hello-og.png",
    ImageAlt: "Hello post social preview",
    ImageWidth: 1200,
    ImageHeight: 630,
})

Metadata can read matching optional model methods such as ImageAlt() string and PublishedTime() time.Time. Read SEO And Sitemaps.

lazy upgrade

lazy upgrade now uses compact progress output for migration steps and keeps interactive conflict diffs or prompts in deliberate terminal takeovers. It updates go.mod through go get from a versioned manifest instead of writing the module file directly. Automated migrations include the older generated-app paths through v0.1.13 and the v0.1.14 -> v0.1.15 dependency initializer and SEO initializer rewrites. The v0.1.13 -> v0.1.14 update remains a manual module update.

Template-owned files are checked with SHA-256 hashes from the bundled sample-app manifest. New files are created directly. Files that still match the previous sample-app version are replaced or removed directly. If a file has local changes, lazy upgrade asks before installing the new version with a dated backup such as init/app.go-2026-06-25, deleting a removed file with a backup, or keeping a removed file that may still cause issues.

mise.toml tool changes are handled as dependencies, not as a full-file replacement. Required tools are added or version-updated, while tools that are no longer needed stay in the file as comments explaining why they are obsolete.

If you are upgrading from v0.1.12 or earlier, first read the v0.1.13 upgrade guide for control-plane probes, native desktop helper commands, the CLI vanity module path, and the first lazy upgrade migrations.