Migration 18.0.0
IMA.js brings few major breaking changes. For more information read below.
Update requirements
IMA.js v18 requires node >= 18, npm >= 8 and react 18.
Moved from gulp to webpack
You can remove gulp things. There is new @ima/cli plugin for helping with webpack. From now, you have to import everything you want to be present in your bundle (that's how webpack works).
Change scripts in package.json
There is new @ima/cli used in scripts instead of gulp.
Example:
...
"scripts": {
"test": "jest",
"lint": "eslint './**/*.{js,jsx,ts,tsx}'",
"dev": "ima dev",
"build": "NODE_ENV=production ima build",
"start": "NODE_ENV=production node server/server.js"
},
...
Remove "main": "build/server.js"
from package.json
too. (Server is not anymore in build/server.js.)
Update settings.js
Remove scripts and esScripts from $Page.$Render (IMA process this things now by manifest and contentVariables).
Remove gulp specific things
Dependencies:
- @ima/gulp-task-loader
- @ima/gulp-tasks
Files:
- gulpfile.js
- gulpConfig.js
Removed build.js, optionally add ima.config.js file to root
- look at ima.config.js
- definition of languages moved from
build.js
toima.config.js
- definition of less file pathes is not needed - see section Styles below
Moved from babel to swc
You can remove @babel dependencies (except for eslint specific).
Add @swc/jest
devDependency for tests.
New React-page-renderer
- React-page-renderer moved to new package @ima/react-page-renderer
- npm
- Yarn
- pnpm
npm i @ima/react-page-renderer
yarn add @ima/react-page-renderer
pnpm add @ima/react-page-renderer
You can use codemod
npx @cns/web-plugins-codemods
-> ima18: react page renderer importsUpdate DocumentView - use AbstractPureComponent from @ima/react-page-renderer instead of AbstractDocumentView
Update EventBus
You have to add target as the second argument for EventBus fire, listen/unlisten.
Update DocumentView
Rewrite your DocumentView similar like in create-ima-app.
Update Server
You have to add dependency to error-to-json
on your own. It was removed from @ima/server.
Replace
let errorToJSON = require('error-to-json');
by
const errorToJSON = require('error-to-json').default;
Split server.js -> server.js and app.js
This change is optionally, but we use it in our create-ima-app.
Server changes
Remove:
'use strict';
require('@ima/core/polyfill/imaLoader.js');
require('@ima/core/polyfill/imaRunner.js');
Replace this part:
let imaServer = require('@ima/server');
let clientApp = imaServer.clientApp;
let urlParser = imaServer.urlParser;
let environment = imaServer.environment;
let logger = imaServer.logger;
let cache = imaServer.cache;
by
const imaServer = require('@ima/server')();
const { serverApp, urlParser, environment, logger, cache, memStaticProxy } =
imaServer;
require('@ima/react-page-renderer/hook/server')(imaServer);
Replace clientApp.requestHandler by serverApp.requestHandlerMiddleware.
Remove staticErrorPage and replace errorHandler function by
function renderError(error, req, res, next) {
serverApp
.errorHandlerMiddleware(error, req, res, next)
.then(response => {
logger.error(response.error);
})
.catch(next);
}
Move environment.js file
- File
app/environment.js
was moved to location/server/config/environment.js
There was removed test env.
Templates
- 400, 500, spa templates are in
server/template
(look at create-ima-app)
Update DocumentView
You can remove getAsyncScripts method and body content replace with: (You have to add $Page.$Render.masterElementId property to settings.js)
<div
id={this.utils.$Settings.$Page.$Render.masterElementId}
dangerouslySetInnerHTML={{ __html: this.props.page }}
/>
{'#{revivalCache}'}
{'#{revivalSettings}'}
{'#{runner}'}
Instead of app css loading use:
{'#{styles}'}
Assets => app/public
Everything from folder app/public is moved to build folder into static folder.
Styles
- Remove files mark as
FAKE FILE FOR GULP LESS
- Move less files from
assets/less
toapp/less
- You have to move definition of less files pathes from build.js to "imports" - you have two options:
- import less files per component
- import root less file e.g. in main.js and use glob pattern to import other less files similar like it was in build.js
- app/less/globals.less - this file is prepending to every less file so that you can import here variables, mixins, etc.
- strictMaths is enabled
Tests
Add @swc/jest
dependency.
Add identity-obj-proxy
for css/less in jest.
Replace enzyme-adapter-react-16
with @cfaester/enzyme-adapter-react-18
.
Other changes
- Prepared for typescript
Deleted packages
You can remove following packages:
- @ima/react-hooks - functionality moved to @ima/react-page-renderer
- @ima/plugin-less-constants moved to @ima/cli-plugin-less-constants
- @ima/plugin-hot-reload
- @ima/plugin-websocket
- @ima/gulp-task-loader
- @ima/gulp-tasks
IMA.js Plugins
All IMA.js plugins need to be updated to the latest version. Older versions won't work.