Skip to main content

Migration 17.0.0

IMA.js brings few major breaking changes, notably in the renaming of all packages. We've tried to make this process as easy as possible through the provided jscodeshift transform scripts. For more information read below.


The ima- packages (even plugins) has been renamed to @ima/ scoped packages and ima core package has been renamed to @ima/core. The core package is now bundled with rollup, so you can no longer import a file from specific path (i.e. import GenericError from 'ima/error/GenericError'), but you can import it directly from @ima/core (i.e. import { GenericError } from '@ima/core').

All of this can be done automatically for a whole project using following jscodeshift script.

npx jscodeshift -t node_modules/@ima/core/transform/import-v17.js --extensions jsx,js --ignore-config=.gitignore ./

Also replace paths which contain ima to @ima/core in package.json (setupFiles in jest) and server.js.

Following packages have been renamed.

ima-gulp-task-loader -> @ima/gulp-task-loader
ima-gulp-tasks -> @ima/gulp-tasks
ima-helpers -> @ima/helpers
ima-server -> @ima/server

Following packages have been removed.


And as a replacement, following package has been created.


Also all plugins have been renamed from ima-plugin-* to @ima/plugin-*.

Context API

IMA.js v17 no longer uses prop-types in contextTypes of React components. Instead, you should use PageContext from @ima/core. Also, prop-types has been removed from IMA.js dependencies, so if you need it for some reason, make sure it is installed as a project dependency.


This is original IMA.js v16 code.

import PropTypes from 'prop-types';

export default class MyComponent extends AbstractComponent {
static get contextTypes() {
return {
$Utils: PropTypes.object,
urlParams: PropTypes.object

This should be the new IMA.js v17 code.

import { PageContext } from '@ima/core';

export default class MyComponent extends AbstractComponent {
static get contextType() {
return PageContext;

All of this can be done automatically for a whole project using following jscodeshift script.

npx jscodeshift -t node_modules/@ima/core/transform/context-api-v17.js --extensions jsx,js --ignore-config=.gitignore ./

Utils Registration

There is a new way of defining component utils. You can no longer define oc.constant('$Utils', {...}) in app/conf/bind.js, you have to use oc.get(ComponentUtils).register({...}) instead. Also, following component utils are predefined by default, so you don't have to define them yourself.

$CssClasses: '$CssClasses',
$Dictionary: Dictionary,
$Dispatcher: Dispatcher,
$EventBus: EventBus,
$Helper: '$Helper',
$Http: HttpAgent,
$PageStateManager: PageStateManager,
$Router: Router,
$Settings: '$Settings',
$Window: Window


Following definition of utils is no longer supported.

oc.constant('$Utils', {
$MyCustomHelper: oc.get(MyCustomHelper),

And must be replaced with following.

$MyCustomHelper: MyCustomHelper,

IMA.js bundle for client/server

IMA.js v17 comes bundled for server and client side. This means smaller bundle for clients. To benefit from this, you should update vendors in your app/build.js as following.

let vendors = {
- common: ['@ima/core'],
+ common: [],

- server: [],
+ server: [{ '@ima/core': '@ima/core/dist/ima.server.cjs.js' }],

- client: [],
+ client: [{ '@ima/core': '@ima/core/dist/ima.client.cjs.js' }],

test: []

Language Key in Config

Config key language (mostly used in app/config/*.js boot methods) has been renamed to $Language. You can search whole project for config.language and replace it with config.$Language, but most likely, it will be used only in app/config/settings.js.

Hot Reload

Hot Reload has been rewritten and published as ima plugin. Old hot reloading will no longer work. You should delete app/assets/js/hot.reload.js from your project, then install the plugin via npm install --save-dev @ima/plugin-websocket @ima/plugin-hot-reload and add following lines to your app/build.js.

// You can add this somewhere below the vendors variable initialization
if (
process.env.NODE_ENV === 'dev' ||
process.env.NODE_ENV === 'development' ||
process.env.NODE_ENV === undefined
) {

IMA.js Plugins

All IMA.js plugins need to be updated to the latest version. Older versions won't work.