---
title: "Compatibility"
space: "Commera"
url: "https://docs.bwh.tech/commera/plugin-reference/compatibility"
updated: "2026-10-09"
---

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.

```python
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 "<app> does not support this Commera" |
| 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.

```python
# 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.

:::note[Using ERPNext fields]

Your plugin can read ERPNext's own fields, such as **Delivered by Supplier (Drop Ship)** on an Item. The prefix rule applies only to fields that your plugin adds.

:::

## 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.

## Next steps

- [Dashboard entries](/commera/plugin-reference/dashboard-entries)
- [SDK](/commera/plugin-reference/sdk)
- [Gotchas](/commera/plugin-reference/gotchas)