Skip to content
HTMX UI
Esc

    Type to search pages and sections.
    GitHub npm
    Get started

    Project

    Upgrading

    Move a project to a newer htmx-ui with one command: htmx-ui-upgrade rewrites what changed and lists what it couldn't.

    View .md

    Before 1.0, a minor release can rename a class or change a component's markup; every one is listed under Breaking changes in the changelog. htmx-ui-upgrade makes those edits for you. Run it in your project, with your work committed: 

    bunx htmx-ui-upgrade@latest

    Then install the new versions and build the site. Always run @latest: each release of htmx-ui ships an htmx-ui-upgrade of the same version that knows every migration up to it, so a project several releases behind upgrades in one go.

    What it does#

    1. Reads the version your code is on from package.json (htmx-ui, else htmx-ui-engine, else a plugin). --from sets it instead.
    2. Runs each release's migration after that version, oldest first, over your templates, scripts, stylesheets and htmx-ui.config.*: renamed classes and attributes in class="…" values, selectors and strings; markup that changed shape; classes that became required; removed functions; renamed config keys.
    3. Sets htmx-ui, htmx-ui-engine and the plugins in package.json to the new version.
    4. Prints what it changed, file by file, and every place it left for you as file:line: markup it doesn't recognise, classes with no one-to-one replacement, old names in prose or comments.
    text 
    Upgrading 0.2.0 → 0.3.0 (htmx-ui ^0.2.0)
Migrations: 0.3.0

Changed 3 files:
  layouts/docs.html
    .code-tab → .tabs-trigger
    .dialog-close gets .btn .btn-ghost .btn-icon .btn-sm (2)
  app.ts
    initCode() call removed (initComponents() runs the clipboard)
  package.json
    htmx-ui ^0.2.0 → ^0.3.0

Check by hand (1):
  partials/chat.html:14  .message-typing is gone: use loader("typing") (/docs/components/loader)

    It never touches node_modules, dist, build, lib, archive (frozen docs versions) or dot-directories, and it refuses to run on a git working tree with uncommitted changes, so the upgrade is one diff to review, or undo.

    Options#

    OptionDescription
    [directory]The project to upgrade. Default: the current directory.
    --from <version>The version the code is written for. Default: read from package.json.
    --to <version>Upgrade to this version. Default: the newest this release knows.
    --dry-runShow what would change and write nothing.
    --forceRun even though there are uncommitted changes.
    --listList every migration and what it does.
     
    bunx htmx-ui-upgrade@latest ./my-site --dry-run
bunx htmx-ui-upgrade@latest --from 0.1.0 --to 0.2.0