Migration from CUBA Platform

Update packages

Open the root directory of the front module.

Remove cuba packages:

npm uninstall @cuba-platform/react-core @cuba-platform/react-ui @cuba-platform/rest

Update third-party dependencies.

npm install @ant-design/icons@^4.0.0 antd@^4.12.3 mobx@^6.1.8 mobx-react@^7.1.0 moment@^2.25.3 react@^17.0.1 react-dom@^17.0.1 react-input-mask@^2.0.4 react-intl@^5.3.0 react-router-dom@^5.2.0

Install Jmix packages:

npm install @haulmont/jmix-react-core@^0.9.0 @haulmont/jmix-react-ui@^0.9.0 @haulmont/jmix-rest@^0.9.0

Change environment

Open package.json and add a proxy server to http://localhost:8080/:

{
  ...
  "proxy": "http://localhost:8080/",
  ...
}

Open src/config.ts and remove CUBA_APP_URL constant and add JMIX_REST_URL constant this way:

// Before:
export const CUBA_APP_URL = process.env.REACT_APP_CUBA_URL ?? "/app/rest/";

// After:
export const JMIX_REST_URL = process.env.REACT_APP_JMIX_REST_URL ?? "/rest/";

Сhange environment variables.

Open .env.development.local and .env.production.local and rename varaibles in both files this way:

PUBLIC_URL=/front/
REACT_APP_JMIX_REST_URL=/rest/
REACT_APP_REST_CLIENT_ID=client
REACT_APP_REST_CLIENT_SECRET=secret

Generate TypeScript SDK

Open the root directory of the front module.

Remove cuba generator package.

npm uninstall @cuba-platform/front-generator

Install Jmix generator package.

npm install --save-dev @haulmont/jmix-front-generator@^0.9.0

Open package.json and rewrite update-model script:

// Before:
{
  "scripts": {
    ...
    "update-model": "gen-cuba-front sdk:all --dest src/cuba"
    ...
  }
}

// After:
{
  "scripts": {
    ...
    "update-model": "gen-jmix-front sdk:all --dest src/jmix"
    ...
  }
}

Remove src/cuba/ directory.

Generate new Jmix model classes (the project must be open in Jmix Studio for this to work):

npm run update-model
If this fails with an error indicating that a connection to Studio cannot be established, go to Jmix Plugin Settings and ensure that "Enable integration with frontend generator" checkbox is ticked.

Rename imports from src/cuba/ to src/jmix/ everywhere in the project.

// Before:
import {...} "../cuba/.."

// After:
import {...} "../jmix/.."

Changes in src/index.tsx

Add this import for fix mobx Observer batching warning:

After:
import 'mobx-react-lite/batchingForReactDom';

Change Jmix REST initialization.

Import JMIX_REST_URL constant from src/config.ts. Remove cubaREST initialization. After that add jmixREST initialization this way:

// Before:
import { CUBA_APP_URL, REST_CLIENT_ID, REST_CLIENT_SECRET } from "./config";
// After:
import { JMIX_REST_URL, REST_CLIENT_ID, REST_CLIENT_SECRET } from "./config";

// Before:
export const cubaREST = initializeApp({
  name: {project name},
  apiUrl: CUBA_APP_URL,
  restClientId: REST_CLIENT_ID,
  restClientSecret: REST_CLIENT_SECRET,
  storage: window.localStorage,
  defaultLocale: "en"
});

// After:
export const jmixREST = initializeApp({
  name: {project name},
  apiUrl: JMIX_REST_URL,
  restClientId: REST_CLIENT_ID,
  restClientSecret: REST_CLIENT_SECRET,
  storage: window.localStorage,
  defaultLocale: "en"
});

Replace CubaAppProvider with JmixAppProvider.

// Before:
ReactDOM.render(
  <CubaAppProvider cubaREST={cubaREST}>
    ...
  </CubaAppProvider>,
  document.getElementById("root") as HTMLElement
);

// After:
ReactDOM.render(
  <JmixAppProvider jmixREST={jmixREST}>
    ...
  </JmixAppProvider>,
  document.getElementById("root") as HTMLElement
);

Rename imports / types / functions, fix breaking changes

Run application for TypeScript hints.

npm run start

Replace the following code in all generated editors:

// Before
  useReaction(
    () => mainStore.security.isDataLoaded,
    (isDataLoaded, permsReaction) => {

// After
  useReaction(
    () => mainStore.security.isDataLoaded,
    (isDataLoaded, _prev, permsReaction) => {

Replace the following code in LanguageSwitcher.tsx:

// Before
defaultValue={getMainStore().locale}

// After
defaultValue={getMainStore().locale ?? undefined}

Replace all imports of CUBA packages to the corresponding Jmix packages. Rename the types / functions everywhere in the project.

Imports:

  • @cuba-platform/react-core → @haulmont/jmix-react-core

  • @cuba-platform/react-ui → @haulmont/jmix-react-ui

  • @cuba-platform/rest → @haulmont/jmix-rest

Types / functions:

  • CubaAppProvider → JmixAppProvider

  • CubaApp → JmixRestConnection

  • CubaRestError → JmixRestError

  • loginMapCubaRestErrorToIntlId → loginMapJmixRestErrorToIntlId

// Before:
import { CubaAppProvider } from "@cuba-platform/react-core";
import { CubaApp } from "@cuba-platform/rest";
import { ... } from "@cuba-platform/react-ui";

// After:
import { JmixAppProvider } from "@haulmont/jmix-react-core";
import { JmixRestConnection } from "@haulmont/jmix-rest";
import { ... } from "@haulmont/jmix-react-ui";

Change i18n messages

In all i18n message files (en.json, etc.) replace management.editor.success key-value pair with two key-value pairs management.editor.created and management.editor.updated.

Troubleshooting

If you have "Module not found" error upon running the application, try the following:

  • delete node_modules folder

  • delete package-lock.json

  • run npm install