Миграция на QPalette 7.0

Новая версия QPalette использует версию Angular 17 и PrimeNG 17. Остальные зависимости также обновлены до последних совместимых версий.

Подготовьте окружение

Для перевода продукта на новую версию Q.Palette потребуются:

• NodeJS версии 20.11.1 или выше.
• NPM версии 10.2.4 или выше (входит в NodeJS 20.x).

Обновите NodeJS и NPM

• Установите nvm (для Windows (opens in a new tab), для MacOS/Linux (opens in a new tab)) для удобного переключениям между разными средами NodeJS. Это также позволит сохранить текущую установленную версию NodeJS.

• Установите NodeJS выбранной вами версии с помощью nvm (чтобы в дальнейшем можно было к ней легко вернуться при необходимости), например:

  nvm install 20.11.1 # для примера, укажите вашу текущую версию

• Установите NodeJS версии 20.11.1 и переключитесь на неё с помощью nvm:

  nvm install 20.11.1
  nvm use 20.11.1

• Убедитесь, что установлены корректные версии NodeJS и NPM:

  node -v # v20.11.1 (или выше)
  npm -v # 10.2.4 (или выше)

• После установки окружений все ранее установленные “глобальные” зависимости перестанут работать, необходимо установить их заново (для всех версий NodeJS, установленных через nvm). В частности, потребуется Angular CLI, установите его командой:

  npm install -g @angular/cli@17

Для пользователей MacOS/Linux

Обратите внимание, что команда nvm use <version> по умолчанию действует только внутри того терминала, в котором выполняется эта команда. Каждый новый открытый терминал будет активировать первую установленную версию. Чтобы задать версию по умолчанию для каждого нового терминала, можно воспользоваться командой:

nvm alias default 20.11.1 # будет использоваться 20.11.1

Для пользователей Windows

Обратите внимание, что команда nvm use <version> повлияет на все консоли, открытые в данный момент и которые будут открыты в дальнейшем.

Для пользователей Windows 7

Последняя поддерживаемая Windows 7 версия NodeJS - 13.13. Если нет возможности обновить Windows до последних версий, есть 2 варианта:

• Использовать виртуальную машину или докер-образ (opens in a new tab) с новой версией NodeJS.
• Воспользоваться обходным решением, описанным на странице GitHub (opens in a new tab), однако гарантировать корректную работу такой конфигурации нельзя.

Выполните миграцию проекта

Установите внутренний репозиторий NPM

Добавьте в корень проекта файл .npmrc со следующим содержимым:

registry=https://registry.npmjs.org
@diasoft:registry=http://repolib-main.diasoft.ru:8081/repository/npm-public-and-diasoft

Это временное решение на период миграции гарантирует, что пакеты @diasoft/* будут ставиться из внутреннего репозитория компании, а все остальные - из публичного.

Подготовьте терминал

Перед тем, как выполнять команды, приведенные в данной инструкции, сделайте следующее:

• откройте терминал;
• перейдите в корень проекта (где находится файл package.json);
• убедитесь, что используется нужная версия NodeJS:

nvm use 20.11.1 # Now using node v20.11.1 (npm v10.2.4)

• очистите кэш NPM:

npm cache clean --force

Обновите зависимости

Замените версию библиотек QPalette на 7.3.9 или выше см. какая версия актуальна на данный момент:

"@diasoft/qpalette-auth": "7.3.9",
"@diasoft/qpalette-core": "7.3.9",
"@diasoft/qpalette-dashboard": "7.3.9",
"@diasoft/qpalette-file-viewer": "7.3.9",
"@diasoft/qpalette-form-addons": "7.3.9",
"@diasoft/qpalette-form-flow": "7.3.9",
"@diasoft/qpalette-permissions": "7.3.9",
"@diasoft/qpalette-prime": "7.3.9",
"@diasoft/qpalette-table-addons": "7.3.9",
"@diasoft/qpalette-ui-grid": "7.3.9",
"@diasoft/qpalette-updater": "7.3.9",
"@diasoft/qpalette-urls": "7.3.9",
"@diasoft/qpalette-urls-addons": "7.3.9",
"@diasoft/qpalette-visual": "7.3.9",

Обновите Angular. Сейчас система стабильно работает на версииях пакетов 17.3.7. На всякий случай можете свериться с package.json нашей документации (opens in a new tab):

ng update @angular/core@16 @angular/cli@16 --force --allow-dirty
ng update @angular/core@17 @angular/cli@17 --force --allow-dirty
ng update @angular/cdk@16 --force --allow-dirty
ng update @angular/cdk@17 --force --allow-dirty

Запустите ng update без указания пакетов:

ng update

Посмотрите, какие зависимости еще требуют обновления и обновите их:

ng update <package1> <package2> --force --allow-dirty

Запустите ng update без параметров. Если все пакеты обновлены - команда выведет сообщение:

We analyzed your package.json and everything seems to be in order. Good work!

В результате выполнения команд ng update в вашем коде могут появиться изменения - не забудьте их закоммитить:

git commit "Применение миграций"

Установите npm-check-updates (opens in a new tab) и запустите его:

ncu -u

Установите зависимости:

npm i

Если есть конфликты - установите совместимые версии, указанные в ошибках NPM.

Проверьте, что зависимости есть во внутреннем репозитории

После того как все зависимости установлены и мы убедились, что все работает, нужно:

1. Удалить package-lock.json и node_modules.

2. Почистить кэш npm: npm cache clean --force.

3. Заменить в .npmrc адрес репозитория:

   registry=http://repolib-main.diasoft.ru:8081/repository/npm-public-and-diasoft

4. Сделать npm i и закоммитить полученный package-lock.json.

В этом случае NPM должен поставить только те версии, которые есть во внутреннем репозитории.

Если NPM сообщит, что каких-то версий зависимостей не хватает, то нужно выполнить следующие действия:

1. Прислать package.json на почту iilich@diasoft.ru с просьбой загрузить пакеты, либо дать доступ к средству загрузки в Nexus.
2. После загрузки пакетов в Nexus запустить npm i еще раз и закоммитить полученный package-lock.json.

Проверьте сборку

Запустите сборку и проверьте корректность работы приложения.

Исправьте Jenkinsfile

Пропишите в Jenkinsfile параметр:

pipelineParameters.put("pbcui_nvm_node_version", "18")
pipelineParameters.put("pbcui_repository_rootapp_branch", "master")

Если вы остаетесь на 6-й версии QPalette, исправьте параметр pbcui_repository_rootapp_branch:

pipelineParameters.put("pbcui_repository_rootapp_branch", "sup/6.0")

Исправьте Dockerfile-pbcui.txt

Пропишите базовый образ:

FROM registry-new.diasoft.ru/release/qpalette:24100914

Дополнительно

Проверьте инструкции по миграции Angular

Зайдите в руководство по миграции Angular (opens in a new tab), выберите в поле From v. текущую версию (для версии QPalette 6.x это 15.0), в поле To v. версию 17.0 и убедитесь, что выполнены все инструкции, помимо тех, что были выполнены ранее.

Большая часть изменений выполняется апдейтером автоматически.

Обратите внимание на критичные изменения, помеченные как “breaking changes” и сделайте необходимые правки в своем продукте, если требуется.

Исправьте ошибки Typescript

В новой версии произошла миграция на Typescript 5.2.2. Если после миграции появляются ошибки, связанные с несоответствием типов, сделайте следующее:

1. Установите strict в файле tsconfig.json в значение false.
2. Если ошибки все равно возникают - исправьте их.

Однако помните, что рекомендацию из п. 1 стоит рассматривать лишь как временную.

Ошибки компилятора могут говорить о неправильно подобранных интерфейсах, логических ошибках и угрозах безопасности, что может привести к серьезным проблемам в будущем.

Проверьте зависимости CommonJS и AMD

При сборке могут выводиться предупреждения типа:

<library> depends on <dependency>. CommonJS or AMD dependencies can cause optimization bailouts

Это говорит о том, что библиотека <library> зависит от библиотеки <dependency>, которая собрана в формате CommonJS или AMD, что будет замедлять сборку и увеличивать размер бандла.

Чтобы избавиться от предупреждений - добавьте указанные зависимости в поле architect.build.options.allowedCommonJsDependencies конфигурации продукта в angular.json:

"allowedCommonJsDependencies": [
  "<dependency>"
	...
],

Breaking Changes

Параметр bundleUrl метода QEventsService.openNewTab() может вызывать проблемы

Ранее при открытии страниц библиотечного продукта через openNewTab() необходимо было указывать bundleUrl бандла библиотечного продукта.

import { QEventsService } from '@diasoft/qpalette-visual';
import {Component} from "@angular/core";
 
@Component({
// ...
})
export class GetPropertiesComponent {
    constructor(private readonly eventsService: QEventsService) {
      this.eventsService.openNewTab({
        caption: 'Название вкладки',
        url: '/interface/service/component/route?query=param', // страница продукта, в который подключается библиотечный продукт
        bundleUrl: '/api/some/route/to/bundle/main.js' // бандл библиотечного продукта, вызовет проблемы
      });
    }
}

В новых версиях bundleUrl в таком случае сломает открытие страницы. Необходимо убрать bundleUrl, а в продукте-потребителе сделать страницу с адресом, который был передан в качестве url. На этой странице подключить бандл библиотечного продукта уже с указанием этого bundleUrl:

<q-web-component
  [endpoint]='endpoint'
  bundleUrl='/api/some/route/to/bundle/main.js'
></q-web-component>

endpoint = {
    service: 'service',
    component: 'component',
    route: 'route?query=param',
    caption: 'Название вкладки',
    properties: {
      // Здесь можно передать какие-то параметры, необходимые для инициализации библиотечного PBC
    }
};

Deprecations

См. актуальные способы работы с передаваемыми данными веб-компонентов в анонсе версии 7.3.9.

Изменения в Angular и PrimeNG

Angular

Проверьте руководство по миграции Angular (opens in a new tab) на предмет изменений, включая breaking changes.

PrimeNG

Изменения см. тут (opens in a new tab).

Breaking changes, известные на текущий момент:

• Компонент p-badge больше не имеет значения small для свойства size. Для задания значения small используйте [size]="null” или не указывайте [size] вообще.
• Компонент p-virtualScroller больше не имеет свойства rows, количество строк рассчитывается автоматически по высоте родительского контейнера, получить текущее значение можно в event.rows события onLazyLoad.

Если есть проблемы с загрузкой бандлов

Убедитесь, что нет дублей QWebComponentModule.forRoot() (см. BREAKING CHANGES в анонсах 7.3.5 и 7.3.11).

Убедитесь, что в главном компоненте вашего продукта (который наследует QWebComponent) в случае наличия хуков Angular вызван дочерний метод с помощью super (см. BREAKING CHANGES в анонсе 7.3.6).

Если проблема сохраняется – воспользуйтесь функцией логирования (см. анонсы выпусков 7.3.8 и 7.3.10).