.webp)
These rules keep your plugin working across Commera releases and next to other plugins.
Declare the API version
Add the Commera API versions that your plugin supports to hooks.py. bench commera init adds it for you.
required_apps = ["commera"]
commera_api_version = [1]
Your commera_api_version |
What Commera does |
|---|---|
Holds the current version (1) |
Calls your hooks |
| Does not hold it | Skips every hook of your plugin, prints a message at migrate, and writes an Error Log titled " |
| Missing | Calls your hooks, and prints a warning at migrate |
Read the current version from commera.sdk.API_VERSION.
Dashboard entries carry their own version. The build puts the plugin API version in the manifest and on the first line of each module. Commera refuses a module from a different version and shows the reason in place of the entry. Rebuild your plugin after you upgrade Commera.
Handler paths
Commera finds the plugin that owns a handler from the first part of its dotted path. Every handler, condition and method must start with your app's module name.
# The app is my_app.
commera_events = {"order_paid": ["my_app.orders.on_order_paid"]}
A condition or method path outside your plugin fails the build. An action method must also be whitelisted with @frappe.whitelist().
Restart after a hooks change
Frappe caches hooks.py. After you add or change a hook, run bench --site <site> clear-cache and restart the bench, or Commera keeps calling the old handlers. On a development bench, stop bench start and run it again. On a production bench, run bench restart.
Custom Field names
Start every Custom Field that your plugin adds with your app name and an underscore, for example my_app_status. Commera checks this on Sales Order, Quotation, Sales Invoice, Item and Customer.
| Where | What happens with a field without the prefix |
|---|---|
bench migrate |
Commera prints the fields and writes an Error Log titled "Commera plugins added unprefixed Custom Fields" |
get_order(extra_fields=...) |
Throws frappe.ValidationError |
set_cart_fields(...) |
Throws frappe.ValidationError |
get_cart() |
Leaves the field out of plugin_fields |
Commera counts a field as yours when it starts with the name of an installed app that has a commera_ hook. Ship the fields as fixtures or create them in after_install, with the module set to your app's module.
Build kit and Vue versions
bench commera init adds these development dependencies to your package.json:
| Package | Version |
|---|---|
@commera/plugin-kit |
link:../commera/packages/plugin-kit (the kit inside your Commera) |
vue |
^3.5.15 |
vite |
^5.4.11 |
@vitejs/plugin-vue |
^5.2.1 |
It copies the vue, vite and @vitejs/plugin-vue versions from your Commera's dashboard. You do not add frappe-ui: the dashboard supplies it, at ^1.0.0-beta.55. Keep vue on the same minor version as the dashboard. Your plugin compiles its templates with its own vue, but they run on the dashboard's copy. The build does not bundle vue, frappe-ui, frappe-ui/list, frappe-ui/charts or @commera/admin: the dashboard supplies them.
Commit yarn.lock. Bench installs with yarn install --frozen-lockfile.
Uninstall
After your plugin is uninstalled, the next delivery job for it marks all its Queued and Running deliveries as Failed. A new event or the scheduled job that starts due deliveries starts that job. Your Custom Fields stay on the DocTypes unless your plugin removes them.