Upgrading

Retest your tier-2 changesCopy Anchor Link

A minor release keeps every tier-1 promise (Versioning), but it may change what tier 2 relies on: the values of core items you changed or removed, core block names and arguments, templates you override, CSS on mrx-* classes and RequireJS mixins. After every minor:

1. Read "Changed defaults" in Changelog.
2. Run bin/magento mrx:light:doctor --module=<your module>: override_order, override_gate, deprecated_use and private_api point at what moved.
3. Run your browser tests.

From an internal build to the 0.1.0 betaCopy Anchor Link

The rename. Every name of Light changed before the 0.1.0 beta. Replace them in your code, XML, layout and composer.json:

MageRex_DemoData, MageRex_Branding, the child theme MageRex/studio and magerex:demo:seed keep their names.

Ranges. Declare ^0.1 in extra.mrx-light-api, in the range guard of registration.php, and in a require on mrx/module-light.

Hyvä code moved. The Hyvä storefront code of Content and Settings moved to Mrx_ContentHyva and Mrx_SettingsHyva. A module that overrode it follows it there (Hyvä code in a -hyva module).

Nav counters. BadgeProviderInterface and the BadgePool argument badges still work. Move to BadgeSourceInterface and the argument providers: your count then merges with other modules' counts on the same item, gets a tone and a spoken label, and comes from the cache (A nav item with a counter). Mrx\Light\Api\Navigation\BadgeProviderInterface is not deprecated.

Deprecated. The tags read since 0.1.0, removed in 2.0.0 (Versioning), so each still works until 2.0.0:

Countries. Core no longer assumes a Dutch shop. Nothing here is deprecated: the old names are gone, so change them in your code, layout and tests:

The patches ChargeDutchVatOnEveryOrder and UseEnglishTaxClassNames are gone. They repaired data of older internal builds, and their patch_list rows are harmless.

Packs. Everything Dutch and everything Mollie left core and sits in modules of its own (Changelog). Nothing is deprecated, so change what names the old places:

Copy and languages. The English source is US English, and an installed language package overrides a module CSV. Nothing is deprecated:

Page drafts. Core's page drafts in Mrx_Content stay. A Dutch shop gets the pack's copies through same-key file items in page_templates, so nothing that names a core draft changes.

Dutch shops. Install magerex/distribution-nl, or core and the packs from the same release. A Dutch shop that runs core without Mrx_CountryNl has no Dutch VAT setup, no KvK check, no PostNL and no Dutch legal page drafts, and bin/magento mrx:light:doctor warns with country_pack. A pack and core are tested together, so keep them on the same release.

Tier 2 in the Dutch pack. Mrx_CountryNl relies on tier-2 surfaces of core: the block arguments of mrx.settings.taxes.oss, mrx.settings.payments and mrx.settings.payments.providers.none, the tracking_url of four carriers and the file of five page drafts (Changelog, Changed defaults). The pack is retested with every core minor. Retest a module of yours that relies on the same surfaces the same way.

The store default theme comes from the brand. Without a saved default, a shop gets Baken with MageRex_Branding, mage-os on Mage-OS without it, and Classic on Magento Open Source. A default an admin saved stays.

ui-kit section 17 moved here. The extension API that ui-kit.md section 17 described is this guide now. Section 17 keeps one line per old subsection, pointing at its new page.

Emails and documents (Mrx_Documents)Copy Anchor Link

Mrx_Documents draws the header and footer of every customer email and prints Light's PDFs (Your module's email and document). What an upgrading shop and a module developer must do:

Install.

• magerex/distribution-nl installs mrx/module-documents. Mrx_Orders and Mrx_Returns require it now, so a shop that runs core alone gets it too. Enable the module and run setup:upgrade; it creates the table mrx_documents_invoice_mailed.
• Run setup:static-content:deploy, or the shop keeps sending the old email CSS.
• The first PDF fills the font cache in var/mrx_documents/fonts. The PHP-FPM user must own that folder, so don't print the first PDF from a root shell.
• In production mode delete generated/ after you enable the module, then run setup:di:compile. It builds the interceptors that Light's plugins need. Without them the mails keep the stock header and the stock PDFs.

Emails. The look comes from the brand kit and the format (Your module's email and document):

• The email template mrx_settings_email_header is gone, and design/email/header_template has no Light default any more. Light maps the stock header and footer ids to its own, so "Header (Default)" in Content > Design > Configuration means Light's header, and "Load Default Template" > Header in Marketing > Email Templates loads Light's header, with or without a theme. A store that still names mrx_settings_email_header fails its mails with "Email template is not defined"; the doctor reports it as email_shell_config. Set Header Template back to the default. A header someone saved in Marketing > Email Templates still wins and gets Light's footer.
• In developer mode delete generated/metadata/staticcache/*.php, generated/code/Magento/Email/Model/Template/Interceptor.php and generated/code/Magento/Email/Model/Template/Css/Processor/Interceptor.php where they exist, or the cached interceptors skip MapShellIds and SwapCssTokens: mails then keep the stock header or show raw __MRX_ tokens. Production runs setup:di:compile, which rebuilds both.
• sales_email/order/template, sales_email/invoice/template and sales_email/shipment/template, with their guest_template, point at Light's own bodies. A shop that picked its own template for one of them in Marketing > Email Templates keeps it, because a numeric value wins over the default, until someone saves texts for that email in Settings > Customer emails, which sets the scope back to the standard template.
• Settings > Customer emails no longer creates email templates. It saves the texts as config rows under mrx_settings/email_texts/ and puts them into the mail when it renders.
• The emails pool and the placeholders argument of Mrx\Settings\Model\CustomerEmails\Placeholders are global now. Move your module's items from etc/adminhtml/di.xml to etc/di.xml: in the admin area they still show in Customer emails, but the saved texts and your placeholders reach only mails sent from the admin, not the order confirmation from checkout or a mail sent by cron. The doctor reports wrong_area for an emails item until you move it.
• Every mail goes out with a plain-text part next to its HTML.

PDFs. Invoices, credit memos and packing slips are Light's. Every stock getPdf() caller now gets them in the brand kit and format, rendered with dompdf (Your module's document); "Magento classic" gives back the stock PDFs:

• A plugin or preference on the drawing code of Magento\Sales\Model\Order\Pdf (insertOrder(), _drawItem(), insertTotals(), a pdf.xml item renderer for invoices, credit memos or shipments) no longer runs, and no error says so. That includes plugins on Magento\Sales\Model\Order\Pdf\Shipment and on the Items\Shipment renderers, which used to print the packing slip. Run the doctor: pdf_inner_plugin lists each one. Move it into an item_lines line or a document type. The pdf.xml total models still run as before.
• The accountant ZIP holds PDFs up to 300 documents, not 1000; above that it holds the CSV files only. A month over 100 documents is split into numbered files (invoices-2026-09-1.pdf, -2.pdf), and a file with documents of two store views lists one store's documents, then the other's.
• In developer mode delete generated/code/Magento/Sales/Model/Order/Pdf/Invoice/Interceptor.php, Creditmemo/Interceptor.php and Shipment/Interceptor.php where they exist, or the cached interceptors keep printing the stock PDFs.
• The paper is always A4, whatever the store's locale.
• The packing slip has no browser page any more. light/orders/packingslips answers the orders list's check in JSON, so a link of yours to light/orders/packingslips?ids=12 now points at light/documents/download?type=packing_slip&ids=12, and one with ?shipment=5 at light/documents/download?type=packing_slip_shipment&ids=5. Mrx\Orders\ViewModel\PackingSlips and Mrx_Orders::order/packing-slips.phtml are gone.

Mail.

• One setting, mrx_documents/invoice/send_with ("Send the invoice PDF with" on Settings > Emails & documents), decides which email carries the invoice PDF: the shipping confirmation (the default), "Payment received", or no email (PDFs on customer emails). The refund email carries the credit memo PDF and follows the same setting. A shop whose invoices go out through another module or a bookkeeping tool picks "No email".
• All six sales senders carry the PDF: InvoiceSender and Invoice\Sender\EmailSender, ShipmentSender and Shipment\Sender\EmailSender, CreditmemoSender and Creditmemo\Sender\EmailSender; OrderSender does when the owner attaches the order confirmation. Every caller gets them: the admin, the checkout, cron and payment modules. A module of yours that sets senderBuilderFactory on one of these senders replaces Light's builder, or Light replaces yours, depending on the load order.
• "Mark as paid" still sends no email. "Email invoice" in the order's More actions does.
• "Print invoice" and "Print refund" on the storefront serve the PDF, unless Magento classic is on. What your module adds to the stock print page, through the print handle of sales_order_printinvoice and sales_order_printcreditmemo or their guest twins, no longer shows; add it to the document with a document_sections item instead.
• In developer mode delete generated/metadata/staticcache/*_compiled_plugins.php and the interceptors of the four storefront print controllers under generated/code/Magento/Sales/Controller/Order and Guest where they exist.
• Settings > Users no longer returns a password when it adds a user: the password key of the light/settings/usercreate answer is gone. The new user gets an invite by email, and invite_link holds the link only when that mail failed.
• The approval mail of a return carries the return slip (The return slip on the approval mail). A theme that overrides customer_new.html keeps the blocks {{depend mrx_awaits_review}} and {{depend mrx_approved}}, or the mail of an approved return still promises a review. Returns replaces MageOS RMA's SenderInterface with its own through a preference; a preference of yours on that interface wins or loses depending on the load order.

Magento classic. Stores > Configuration > Sales > Emails and documents (Light) > Advanced holds the switch; "Open in advanced view" on Settings > Emails & documents leads there. On, it gives back the stock header, footer and email styles, the stock order, invoice and shipment bodies, and the stock PDFs. Light's own mails (returns, messages, shipping updates) keep their layout without the Light styles. The shop sends no PDF on an email and no return slip, and the storefront print page comes back.

From 0.1.0 to 0.1.1Copy Anchor Link

Returns is optional. magerex/distribution-nl and magerex/light-demo-data no longer require mrx/module-returns. On composer update, a shop that got Returns only through the distribution loses mrx/module-returns and mage-os/module-rma. Decide before you update, because Composer removes the code while Magento's cache still lists both modules: every bin/magento command, setup:upgrade and cache:flush included, then fails with Class "MageOS\RMA\Console\Command\CleanupCommand" does not exist until you clear the cache storage by hand (var/cache, or the Redis or Valkey cache database).

To keep returns, require the package yourself before you update:

composer require mrx/module-returns:^0.1

To drop them, dump the database and disable both modules before you update:

bin/magento module:disable Mrx_Returns MageOS_RMA
composer update 'mrx/*' 'magerex/*' -w
bin/magento setup:upgrade

The rma_* tables and the returns in them stay: Magento drops a module's tables only when setup:upgrade runs while the module is disabled and its code is still installed. Run nothing else between the disable and the update, or that setup:upgrade drops them.

A shop without Returns runs Light as before: the Returns nav item, its settings card, its order actions and its role area are absent. A module of yours that names a Mrx\Returns class or the MageOS_RMA ACL resources requires mrx/module-returns in its own composer.json.

From 0.1.1 to 0.1.2Copy Anchor Link

Nothing changes for your code. Light's roles are saved once more. Every role Light makes holds the user's own second factor from 0.1.2, and the first setup:upgrade on 0.1.2 or later gives it to each role that holds Mrx_Light::light without full access and lacks it (the Staff and Shipping staff presets also get screens their areas miss). Light stores such a role through Magento's Rules::saveRel(), once: later runs find the second factor and leave the role alone. saveRel() writes the role again from the ACL tree of that moment, so a resource of a module that is disabled during that setup:upgrade is gone from the role and doesn't come back when the module is enabled again. Dump the database first, run the update with your modules enabled, and check the roles named in var/log/system.log ("Light: roles ... got the screens"). A role saved later in Magento's own role editor with Light ticked gets the second factor on that save (0.4.3 and later).

From 0.1.2 to 0.1.3Copy Anchor Link

Nothing changes for your code: the API surface is the same as in 0.1.0.

Preset roles are reset. Light 0.1.0 to 0.1.2 gave a Staff or Shipping staff role made through Settings > Users > Add user every resource of the admin, user and role management included, so a Staff user could make themselves Owner. The first setup:upgrade on 0.1.3 (the data patch RepairPresetRoles, once) resets a role only when it carries that leak: it is named Staff or Shipping staff, holds Light (Mrx_Light::light, which every role Light makes holds) and holds both user management and role management (Magento_User::acl_users and Magento_User::acl_roles, which no Light area gives). Such a role is set back to exactly what its preset gives, and each reset is logged with the resources it took away (var/log/system.log, "Light: role ... was reset to it"). In such a role Light can't tell a leaked resource from one a merchant gave it on purpose in Magento's own role editor, so both go, and so do areas added to it in Light's role editor: check the logged roles after the update and give them back what they should have, in Settings > Users or the advanced view. Every other role stays as it is: a preset role that only holds what Light's areas give, a role named Staff that a merchant made in Magento's own editor without Light or without user and role management, Owner and every role with full access. One case the repair can't tell apart: Light 0.1.0 to 0.1.2 gave Mrx_Light::light to any role named Staff or Shipping staff on every setup:upgrade, also to one a merchant made in Magento's own role editor. If such a role also has user and role management on purpose, it carries the same signature and is reset too, so it loses those grants; the log names it. Give them back in the advanced view, or rename the role first if you know it is yours. A leaked preset role that was renamed later isn't found by its name; check roles you renamed from Staff or Shipping staff yourself, and take user and role management away from any that still has them (Users and permissions).

Role completion only touches Light's roles. Light's role completion (setup:upgrade, every time) treated any role named Staff or Shipping staff as its preset in 0.1.0 to 0.1.2: it gave such a role, also one Light never made, the screens of every area the role touched and the resources every Light role gets, the user's own second factor and its parents included. From 0.1.3 it completes a preset role only when the role also holds Mrx_Light::light, which every role Light makes holds; a role without it keeps exactly what it has, whatever its name. A preset role from which someone removed Light in the advanced view is left alone too; saving it in Light's role editor gives it back. What the 0.1.x completion already gave a role of your own stays: check a role of your own called Staff or Shipping staff and take away what you don't want it to have.

When 0.1.3 is the first Light you install on an existing store, none of this applies: a role of the store that happens to be named Staff or Shipping staff holds no Mrx_Light::light, so it is neither reset nor completed.

From 0.1.3 to 0.1.4Copy Anchor Link

Nothing changes for your code: the API surface is the same as in 0.1.0. Run setup:upgrade after composer update 'mrx/*' 'magerex/*' -w; 0.1.4 adds no tables, columns or data patches. -w updates the Light packages and the packages they need, and leaves the packages your shop requires itself, such as its own payment plugin, at their locked versions. Use -W only when Composer says a package your shop requires is in the way, and check what it changed before you deploy (Updating).

Reservations stay with the owner. Light's Products area no longer gives "Clean balanced reservations" and "Mass Delete Reservations" (MageOS_InventoryReservationsGrid::clean and ::delete): cleaning or deleting reservations changes what every product can sell. On 0.1.4 a role that already holds them keeps them. The next release takes them from the Staff and Shipping staff roles Light made on its first setup:upgrade, and saving such a role in Light's role editor takes them away too (From 0.1.4 to 0.1.5). Take them away in the advanced view from any other role that shouldn't have them (Users and permissions).

Switching Multi-Source Inventory on later. Light works with MSI on and one source. A store that turns MSI on after running with it off gets its source quantities from the legacy stock, which open orders already lowered. Magento's inventory:reservation:create-compensations then subtracts those orders a second time. Keep the compensations, since shipping, cancelling or refunding needs them, and raise each affected source quantity by the order's unshipped quantity.

Rate tables are optional. mrx/module-shipping-matrixrate is new and not part of a distribution. To add it:

composer require 'mrx/module-shipping-matrixrate:^0.1'
bin/magento module:enable WebShopApps_MatrixRate Mrx_ShippingMatrixrate
bin/magento setup:upgrade
bin/magento cache:flush

The package brings webshopapps/module-matrixrate with it. setup:upgrade would enable both modules on its own; module:enable names them, so you see what you switch on (Rate tables, an add-on).

From 0.1.4 to 0.1.5Copy Anchor Link

Nothing in the API surface changes, but two settings behaviours and the preset roles do. Check your module for them.

A channel value stays the channel's own. ScopedConfigWriterInterface::save($values, $websiteId) keeps a website value that equals the all-channels value; before, it removed it. If your module wrote the all-channels value for a website to make that website follow all channels again, write null for those paths instead. A value equal to what the website reads now is still not written, so saving a whole form leaves untouched fields following all channels as before (Saving per scope).

A removed channel is refused. A settings page that saves through light/settings/save/page/<code> no longer receives a request whose channel names a channel that doesn't exist: the controller answers 422 first. A page that read such a request as "All channels" on purpose gets that case no more.

Preset roles lose what their areas exclude. 0.1.4 took "Clean balanced reservations" and "Mass Delete Reservations" (MageOS_InventoryReservationsGrid::clean and ::delete) out of the Products area, but a Staff or Shipping staff role made before kept them. The first setup:upgrade on this release (the data patch RemoveExcludedFromPresetRoles, once) takes from each preset role Light made (named Staff or Shipping staff and holding Mrx_Light::light, never one with full access) what the exclude lists of its areas leave out, with the resources below them, unless another of its areas gives them. It logs each role and what it took (var/log/system.log, "Light: role ... held resources its areas leave to the owner"). The reservation screens are the known case; a preset role with the Settings area that holds sign-in security, API access, the activity log or developer settings loses those too. Everything else in the role stays, and so do a role of another name, one without Mrx_Light::light and every role with full access. Saving a preset role in Light's role editor now does the same, also for an exclude your module adds to an area later; a role of another name keeps what it has outside its areas. Give a preset role such a screen back in the advanced view if it should have it: the patch runs once, and later setup:upgrade runs only add. Saving that role in Light's role editor takes the screen away again, since every save of a preset role drops what its areas exclude; to keep the screen, edit the role only in the advanced view, or make it a role of your own under another name.

From 0.1.x to 0.2.0Copy Anchor Link

0.2.0 adds locations and pickup at a location (Changelog). Nothing of 0.1.x was removed from the API surface, but a 0.x minor never matches the range of the one before it.

Ranges. Move every range from ^0.1 to ^0.2: extra.mrx-light-api in composer.json, the range guard in registration.php (satisfies('^0.2')) and a require on mrx/module-light or any other mrx/module-*. A module left on ^0.1 is hidden by the compatibility gate, and its range guard stops it from loading (Versioning).

Setup. Run setup:upgrade right after composer update. Until then the admin is unusable: Light's Home fails with "Cannot instantiate interface Mrx\Locations\Api\LocationsInterface", because Mrx_Locations is new and still off. setup:upgrade enables it and creates mrx_location, mrx_location_stock and mrx_order_pickup. mrx/module-locations comes in through Catalog, Orders and Home; on a shop without Magento's inventory modules it is enabled and does nothing.

Internal classes that changed. None of these carried @api, so they were never part of the contract. A plugin or a preference of yours on them needs a look:

Reading stock after the switch. Once a shop has a second location, cataloginventory_stock_item.qty follows only Magento's default source, which the switch sets to 0. Code that read the legacy quantity as "on hand" reads MSI's source items or the salable quantity instead (Locations and pickup).

Words. The picklist's storage column is "Bin" now (pick_locations items keep working). A CSV row of yours for "Location" in nl_NL or de_DE loses to the row Mrx_Locations puts in prefer_phrases.

A VAT basis nobody stored is no OSS choice. OssInterface::isUsed() and EuVat::getMode() read a shop that never stored tax/calculation/based_on (Magento's default is the delivery address) and has no OSS rules as home VAT. A module that called isUsed() to decide whether to add OSS rates now gets false on such a shop. Saving Settings > Taxes stores the basis at all channels, so from then on the storefront charges home VAT on orders abroad instead of 0% where no rate existed.

Hyvä footer block renamed. Mrx_ContentHyva now uses the block name mrx.content.footer.menu on Hyvä too (it was mrx.content.footer.menu.hyva), and Mrx_SettingsHyva renders the legal page links in the Hyvä footer. A Hyvä theme that moved or removed mrx.content.footer.menu.hyva in its own layout uses the new name.

From 0.2.x to 0.3.0Copy Anchor Link

0.3.0 adds two core routes, light/notifications/dismisstasks and light/settings/legalpagevisibility, and a few additive keys (Changelog). Nothing of 0.2.x was removed or changed in the API surface, but a 0.x minor never matches the range of the one before it.

Ranges. Move every range from ^0.2 to ^0.3: extra.mrx-light-api in composer.json, the range guard in registration.php (satisfies('^0.3')) and a require on mrx/module-light or any other mrx/module-* or magerex/* package. A module left on ^0.2 is hidden by the compatibility gate, and its range guard stops it from loading (Versioning).

Composer. composer update stays inside ^0.2, so move the ranges with a require. Put the shop's own mrx/* requires in the same command, so Composer resolves them together:

composer require 'magerex/distribution-nl:^0.3' 'mrx/module-returns:^0.3' -w
bin/magento setup:upgrade
bin/magento cache:flush

Leave out the packages the shop doesn't require, and use magerex/distribution-nl-hyva on a Hyvä shop.

Run setup:upgrade right after composer. Between the two the admin is unusable: Composer has put 0.3.0 code next to the database and the generated classes of 0.2.x, and setup:upgrade brings them in line. In production mode, run setup:di:compile and setup:static-content:deploy after it.

Payment providers. A pack that implements Mrx\Settings\Api\ChannelPaymentProviderStateInterface (new in 0.3.0) needs Settings 0.3.x, so its range moves with the rest. A provider that implements only PaymentProviderStateInterface keeps working: Settings asks it isOffered(), whatever channel is being saved.

From 0.3.x to 0.4.0Copy Anchor Link

0.4.0 adds one layout container, mrx.home.top on Home (Changelog). Nothing of 0.3.x was removed or changed in the API surface, but a 0.x minor never matches the range of the one before it.

Ranges. Move every range from ^0.3 to ^0.4: extra.mrx-light-api in composer.json, the range guard in registration.php (satisfies('^0.4')) and a require on mrx/module-light or any other mrx/module-* or magerex/* package. A module left on ^0.3 is hidden by the compatibility gate, and its range guard stops it from loading (Versioning).

Composer. composer update stays inside ^0.3, so move the ranges with a require. Put the shop's own mrx/* and magerex/* requires in the same command, so Composer resolves them together:

composer require 'magerex/distribution-nl:^0.4' 'mrx/module-returns:^0.4' -w
bin/magento setup:upgrade
bin/magento cache:flush

Leave out the packages the shop doesn't require, and use magerex/distribution-nl-hyva on a Hyvä shop. A shop with magerex/module-flex-bridge or mrx/module-shipping-matrixrate adds them to the same require at ^0.4.

Run setup:upgrade right after composer. Between the two the admin is unusable: Composer has put 0.4.0 code next to the database and the generated classes of 0.3.x, and setup:upgrade brings them in line. In production mode, run setup:di:compile and setup:static-content:deploy after it.

A banner on Home. A module whose card in mrx.home.widgets is a way into its own screen, or a notice that must not be missed, can move it to mrx.home.top, full width above the figures (Home to-dos, setup steps and widgets). Nothing moves by itself: a block in mrx.home.widgets stays in the side column.

From 0.4.8 to 0.4.9Copy Anchor Link

0.4.9 changes no API, but magerex/distribution-nl (and with it magerex/distribution-nl-hyva) no longer installs magerex/light-branding: Light from a metapackage is white-label, and the MageRex brand is an add-on (The MageRex brand).

Keep the brand. A shop that had the brand only through the metapackage requires it itself, in the same command as the update:

composer require 'magerex/distribution-nl:^0.4' 'magerex/light-branding:^0.4' -w
bin/magento setup:upgrade
bin/magento cache:flush

Without it, composer update removes the package, setup:upgrade drops MageRex_Branding from app/etc/config.php, and the admin shows the platform's own logo and default theme. The brand keeps no data, so nothing else changes: a theme an admin picked or a store default someone saved stays. A module of your own that requires magerex/light-branding keeps it installed.

From the 0.1.0 beta to 1.0.0Copy Anchor Link

1.0.0 follows the testing phase of the beta. At that release:

Ranges. Move every range from ^0.y to ^1.0, in extra.mrx-light-api, in the range guard of registration.php, and in a require on mrx/module-light. A caret on 0.x never matches 1.0.0, so a module left on ^0.1 is hidden.

No range is out of range. From the 1.0.0 release a module that contributes to Light without extra.mrx-light-api counts as out of range, and the doctor's api_undeclared is an error. During the beta it is a warning, so add the range now (Versioning).