// Use when upgrading Backpex to a newer version, handling breaking changes, or migrating code after a version bump. Also use when the user asks about what changed between versions.
Use when scaffolding a new Backpex LiveResource, setting up admin CRUD views, or configuring adapter_config, fields, filters, and routing for a resource.
Use when creating custom Backpex field types, implementing the Backpex.Field behaviour, or adding fields to a LiveResource's fields/0 callback.
Use when adding a filter to a Backpex LiveResource, creating a filter module, or the user asks about filtering data in Backpex index views.
Use when creating custom Backpex item actions, adding action buttons to table rows or the show page, or modifying the default edit/delete/show actions.
Use when creating Backpex resource actions for global operations like bulk exports, invitations, imports, or any action that applies to the resource as a whole rather than individual items.
| name | upgrade |
| description | Use when upgrading Backpex to a newer version, handling breaking changes, or migrating code after a version bump. Also use when the user asks about what changed between versions. |
You are an expert at upgrading Backpex versions. When the user wants to upgrade, follow this process:
mix.exsCheck mix.exs for the Backpex dependency:
{:backpex, "~> 0.17.0"}
All upgrade guides are at guides/upgrading/ in the Backpex repository (also available on HexDocs). Read these files directly to get the exact migration steps:
| Version | File |
|---|---|
| 0.18 | guides/upgrading/v0.18.md |
| 0.17 | guides/upgrading/v0.17.md |
| 0.16 | guides/upgrading/v0.16.md |
| 0.15 | guides/upgrading/v0.15.md |
| 0.14 | guides/upgrading/v0.14.md |
| 0.13 | guides/upgrading/v0.13.md |
| 0.12 | guides/upgrading/v0.12.md |
| 0.11 | guides/upgrading/v0.11.md |
| 0.10 | guides/upgrading/v0.10.md |
| 0.9 | guides/upgrading/v0.9.md |
| 0.8 | guides/upgrading/v0.8.md |
| 0.7 | guides/upgrading/v0.7.md |
| 0.6 | guides/upgrading/v0.6.md |
| 0.5 | guides/upgrading/v0.5.md |
| 0.3 | guides/upgrading/v0.3.md |
| 0.2 | guides/upgrading/v0.2.md |
Read ALL upgrade guides between current and target version. For example, upgrading from 0.15 to 0.18 requires reading v0.16, v0.17, and v0.18 guides.
Bump the dependency in mix.exs:
{:backpex, "~> 0.18.0"}
Run mix deps.get to fetch the new version.
Apply breaking changes from each guide in order. Common categories:
Compile and fix warnings: mix compile --warnings-as-errors
Run tests to catch regressions.
# Before (option)
use Backpex.LiveResource, layout: {MyAppWeb.Layouts, :admin}
# After (callback)
use Backpex.LiveResource, ...
@impl Backpex.LiveResource
def layout(_assigns), do: {MyAppWeb.Layouts, :admin}
Read the upgrade guide for the default value and implement it in affected modules.
Search your codebase for the old callback name and update all implementations.
Check if your code directly uses the removed module/function and replace with the suggested alternative.
Each Backpex release may add new translatable strings. After upgrading:
Copy the updated Gettext template from the Backpex dependency into your application:
cp deps/backpex/priv/gettext/backpex.pot priv/gettext/backpex.pot
Alternatively, download it from GitHub at https://github.com/naymspace/backpex/blob/<VERSION>/priv/gettext/backpex.pot (replace <VERSION> with your target version tag).
Remove elixir-autogen comments from the copied .pot file. The Backpex source file contains #, elixir-autogen, elixir-format comment lines. If left in place, running mix gettext.extract --merge will delete all Backpex translations from your PO files (Gettext treats autogen entries as auto-generated and removes those not found in your source code). Strip them:
sed -i '' 's/#, elixir-autogen, elixir-format/#, elixir-format/g' priv/gettext/backpex.pot
Merge the new strings into your existing PO files:
mix gettext.merge priv/gettext
Translate any new msgid entries in your priv/gettext/<locale>/LC_MESSAGES/backpex.po files.
The .pot file on the develop branch may contain unreleased translations. Always use the version tag that matches your Backpex version.