---
title: "Upgrading"
description: "Move a project to a newer htmx-ui with one command: htmx-ui-upgrade rewrites what changed and lists what it couldn't."
url: "https://susonwaiba.github.io/htmx-ui/docs/upgrading"
section: "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.

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](https://susonwaiba.github.io/htmx-ui/docs/changelog). `htmx-ui-upgrade` makes those edits for you. Run it in your project, with your work committed:

```bash bun
bunx htmx-ui-upgrade@latest
```

```bash npm
npx htmx-ui-upgrade@latest
```

```bash pnpm
pnpm dlx htmx-ui-upgrade@latest
```

```bash yarn
yarn dlx 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](https://susonwaiba.github.io/htmx-ui/docs/plugins/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

| Option | Description |
| --- | --- |
| [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-run | Show what would change and write nothing. |
| --force | Run even though there are uncommitted changes. |
| --list | List every migration and what it does. |

```bash bun
bunx htmx-ui-upgrade@latest ./my-site --dry-run
bunx htmx-ui-upgrade@latest --from 0.1.0 --to 0.2.0
```

```bash npm
npx htmx-ui-upgrade@latest ./my-site --dry-run
npx htmx-ui-upgrade@latest --from 0.1.0 --to 0.2.0
```

```bash pnpm
pnpm dlx htmx-ui-upgrade@latest ./my-site --dry-run
pnpm dlx htmx-ui-upgrade@latest --from 0.1.0 --to 0.2.0
```

```bash yarn
yarn dlx htmx-ui-upgrade@latest ./my-site --dry-run
yarn dlx htmx-ui-upgrade@latest --from 0.1.0 --to 0.2.0
```