Odoo JavaScript to OWL Migration

Legacy JavaScript patterns were gradually deprecated starting Odoo 15, and from Odoo 17 onward OWL is the required framework. This guide covers migrating odoo.define and web.Widget code.

The problem

Legacy JavaScript patterns such as odoo.define(), web.Widget, and web.AbstractField were deprecated starting Odoo 15. From Odoo 17+, components built on them must be rewritten as OWL components.

Why it matters

Frontend code that depends on removed legacy classes will not load. Broken widgets degrade form, list, and kanban views, and the failures often appear only in the browser console rather than at install time.

Common symptoms

JavaScript console errors about undefined modules
Widgets not loading on form or list views
Broken kanban views and custom buttons
Form widget failures with no server-side error

Example risk

A widget defined with the legacy module system needs to be rewritten as an OWL component:

odoo.define('my_module.MyWidget', function (require) {
    var Widget = require('web.Widget');
    return Widget.extend({
        // legacy widget body
    });
});

The OWL equivalent uses an ES module with @odoo-module, a class extending Component, and registration in the appropriate registry.

How to audit it

Search JavaScript files for odoo.define, web.Widget, web.AbstractField, and Class.extend patterns.
Check for legacy qweb template usage tied to those widgets.
Verify asset bundle declarations in __manifest__.py.

How Odoo Doctor helps

The Migration Audit detects legacy JavaScript patterns and flags them for OWL migration with file and line references. See the legacy odoo.define and legacy web.Widget findings for details.

Manual testing needed

Install on a clean target database and open every view that uses a custom widget. Watch the browser console and confirm each OWL component renders, reacts to data changes, and handles user actions.

Find legacy JavaScript to migrate

Scan your module for odoo.define and web.Widget usage before upgrading.

Run Migration Audit

Frequently asked questions

When did OWL become required in Odoo?

OWL was introduced in Odoo 15 alongside legacy widgets. From Odoo 17 onward OWL is the required frontend framework and most legacy web.Widget components no longer load.

Can odoo.define and OWL modules coexist?

During Odoo 15 and 16 they can coexist while you migrate. The modern module is declared with @odoo-module and uses ES module imports instead of the require callback used by odoo.define.

What happens to my QWeb templates?

Legacy QWeb templates tied to web.Widget need to be reworked as OWL component templates. The template syntax is similar but the binding model and lifecycle differ, so each template should be tested.

Does the audit rewrite my JavaScript to OWL?

No. The Migration Audit detects legacy JavaScript patterns and flags them for OWL migration with file and line references. The rewrite and testing are done by you.

Related guides