Upgrading Unpoly

New Unpoly releases will occasionally rename or remove an existing function, event or HTML attribute.

To polyfill old APIs, load the file unpoly-migrate.js:

By loading unpoly-migrate.js, calls to most old APIs will be forwarded to the new version. A deprecation notice will be logged to your browser console:

This way you can upgrade Unpoly, revive your application with a few changes, then replace deprecated API calls under green tests.

Tip

We recommend to temporarily load unpoly-migrate.js for every upgrade, even for minor version bumps. Changes handled by unpoly-migrate.js are not considered breaking changes.

Installing the polyfills

unpoly-migrate.js must be loaded after Unpoly, but before your own code. For example:

<script src="unpoly.js"></script>
<script src="unpoly-migrate.js"></script> <!-- mark-line -->
<script src="app.js"></script>

Covered functionality

Removed functions are polyfilled

If a function was removed without replacement, unpoly-migrate.js will provide a polyfill.

E.g. Unpoly no longer supports up.util.times(), but the function is re-added by unpoly-migrate.js.

Renamed functions are aliased

Calls to deprecated functions will be forwarded if there is an equivalent function in the current version.

E.g. up.modal.close() will call up.layer.dismiss().

Renamed options are aliased

Usage of deprecated options will be rewritten if there is an equivalent option in the current version.

E.g. { reveal: false } will be renamed to { scroll: false }.

Renamed packages are aliased

Usage of deprecated pcakages will be rewritten if there is an equivalent packages in the current version.

E.g. up.proxy.config will return up.network.config.

Occasionally a package will be removed

Renamed HTML attributes are aliased

E.g. <a up-close> will translate to <a up-dismiss>

Renamed events are aliased

E.g. up.on('up:proxy:load') will bind to up:request:load.

Note that event aliases are only used when registering listeners with up.on(), but not with the native Element#addEventListener().

Detecting use of deprecated APIs with automated tests

If your app has good test coverage you can configure unpoly-migrate.js to log an error (instead of a warning) whenever a deprecated API is called:

up.migrate.config.logLevel = 'error' // log to the error console
up.log.config.format = false         // log unformatted text for easier extraction

You can now detect which code needs to be upgraded by following test failures.

Tip

Your E2E tests can check if the browser console shows an error using the Selenium API.