Skip to main content
The module.json keys and what reads each one

The manifest

The five required keys are name, alias, description, category and providers. module:doctor fails without them.

Admin permissions

Declare them in module.json. Core merges them into the permission map and the admin role editor.
Node keys carry the full path, the routes list does not. module:doctor flags it if you get this wrong.
Without one, the role editor draws no checkbox and only a superadmin can use the page. Existing categories are gateway_settings and addon_module_settings.
Prefix with a verb: "DELETE:/admin/acme-panel/backups/{id}". A node with no routes is fine when your controller checks $user->hasPermission(...) itself.
Keys are stored in each role’s permissions. Renaming one silently removes access.
For a single route you can name the permission inline:

Settings page without React

Extend ModuleSettingsController, return your values and a field list, and core renders the page. It takes the title, logo and back link from module.json. The page uses the Admin Modern theme.
A generated module settings page in Admin Modern
Use url() for update_url and test_url, not route(). route() throws while the module is disabled.
Every field also takes placeholder, help, max_length, full_width, copyable and visible_when (['field' => 'mode', 'equals' => 'live']). For a rich text field you need a custom page, see Admin pages.
Saving submits every tab, not only the visible one.
Two helpers come with the base class:

resolveSecret()

resolveSecret($request, 'api_key', $stored) keeps the saved secret when the password box is posted empty.

flushPaymentGatewayCache()

Gateways must call it after saving, or checkout keeps a stale list for five minutes.
Always ship a Test connection action. It turns a support ticket into a five minute setup.