Developer guide
Build with an AI assistant
The Markdown of every page, prompts that work, and an AGENTS.md for your repository.
An assistant writes a good Light module when it has read the right pages and knows the rules. This site gives it both: every page as Markdown, the whole guide in one file, and a rules file for your repository.
Give your assistant the guide
| What | Where | Use it for |
|---|---|---|
| Copy Markdown | The button under each page title | Paste one page into a chat |
| View as Markdown | The link next to it | Read the page as a model gets it |
| Open | The menu next to them: Open in ChatGPT, Claude, Cursor or Scira AI. A copy of the site on localhost doesn't show it, because those services can't read it | Start a chat that reads this page |
| One page | https://light.magerex.nl/md/developer/<page>.md, for example https://light.magerex.nl/md/developer/recipes/nav-counter.md | Point an agent at the page it needs |
| Every page, listed | https://light.magerex.nl/llms.txt | Let an agent pick the pages itself |
| Every page, in full | https://light.magerex.nl/llms-full.txt | Give a long-context model the whole guide |
The Markdown is the page as written: a code block keeps the path of the file it quotes in its title, and a diagram stays a mermaid block that a model can read. Its links point at the full address of the Markdown they mean, so an assistant can follow them.
Put the rules in your repository
Save these two files in the root of your module's repository. Coding agents such as Claude Code, Cursor and Codex read them before they change anything.
# Working on a Light module
This module extends Light, the simple admin for Mage-OS and Magento Open Source. The Light developer guide is the
authority: https://light.magerex.nl/llms-full.txt holds all of it as Markdown, and
https://light.magerex.nl/md/developer/<page>.md holds one page.The whole file is on this site at /agents/AGENTS.md.
Prompts that work
Each prompt names the pages to read first, the job, and the check to run at the end. Swap in your own module and names.
Read https://light.magerex.nl/md/developer/recipes/nav-counter.md and https://light.magerex.nl/md/developer/ux-guidelines.md first.
In my module Vendor_Returns, add a Light nav item "Returns to handle" under Orders that opens
light/vendorreturns/index, and a counter of the returns with the status "new". Follow the recipe: a class that
implements BadgeSourceInterface, returns null at 0 and uses the tone attention, registered in the BadgePool
argument providers in etc/adminhtml/di.xml, and BadgeCacheInterface::invalidate() wherever the status changes.
Gate every item on Vendor_Returns.
Then run bin/magento mrx:light:doctor --module=Vendor_Returns and fix what it reports.Read https://light.magerex.nl/md/developer/getting-started.md and https://light.magerex.nl/md/developer/case-study-request-an-account.md first.
Write a bridge Vendor_ReviewsLight for the module Vendor_Reviews, which I can't change. Start with
bin/magento mrx:light:app Vendor_ReviewsLight --for=Vendor_Reviews --with=nav,route-map --parent=products.
Keep every call into Vendor_Reviews under Model/Backend/, and add a unit test that fails on any other reference.
Use the module's own ACL resources.
Then tick the "Before you ship" list of the getting started page, and run the doctor on Vendor_ReviewsLight.Read https://light.magerex.nl/md/developer/recipes/form-card.md first.
Add a card "Delivery" with one field, a delivery note of at most 200 characters, to the Light product editor for
my module Vendor_Delivery. Keep the value in a product attribute, set in apply(); save() returns null. Check the
length in validate() and in a browser hook. Put the card in mrx.product.form.main.bottom and give it the ACL
resource Vendor_Delivery::manage.
Then run the doctor, and copy test 4 of tests/playwright/light-proof.spec.ts for a browser test.Read https://light.magerex.nl/md/developer/recipes/settings-page.md and https://light.magerex.nl/md/developer/ux-guidelines.md first.
My module Vendor_Feed has the section vendor_feed in etc/adminhtml/system.xml. Add a Light settings page for it
that shows only general/enabled and general/title in simple mode, with warm labels and notes, and send the stock
section to it. Name each field one by one.
Then run the doctor and fix any schema_field finding.Read https://light.magerex.nl/md/developer/ux-guidelines.md and the "Before you ship" list of https://light.magerex.nl/md/developer/getting-started.md.
Go through my module Vendor_Module and list every place it breaks one of the six rules or misses a box of the list,
with the file and the line. Don't change anything yet.Read https://light.magerex.nl/md/developer/troubleshooting.md first.
Here is the output of bin/magento mrx:light:doctor --module=Vendor_Module --format=json:
<paste the output>
Explain each finding, fix it in the module, and run the doctor again until it reports no errors.Read https://light.magerex.nl/md/developer/upgrading.md, https://light.magerex.nl/md/developer/changelog.md and https://light.magerex.nl/md/developer/versioning.md first.
Move my module Vendor_Module to the newest Light API version the changelog lists. Change the range in
extra.mrx-light-api, in the range guard of registration.php and in any require on mrx/module-light, and replace
every deprecated use the doctor reports with deprecated_use.Check what it wrote
An assistant can be sure of itself and still be wrong. Before you merge its work:
bin/magento mrx:light:doctor --module=<your module>reports no errors,private_apiincluded.- The module's browser test passes, and
tests/playwright/users-and-permissions.spec.tsstill does. - A person reads every label and every Dutch translation: warm copy is Built for Light, rule 6.
Last updated on