Skip to content

Modernization: Lara Theme - Upgrade Angular from 20 to 21 & PrimeNG from 17 to 21 #33882

New issue
New issue
Open
Epic
16 of 17 issues completed
#34531
Open
Modernization: Lara Theme - Upgrade Angular from 20 to 21 & PrimeNG from 17 to 21#33882
Epic
16 of 17 issues completed
#34531
Assignees
hmoreras
Labels
Team : Modernization
@hmoreras

Description

@hmoreras
hmoreras
opened on Nov 20, 2025

Upgrade Angular from 20 to 21 & PrimeNG from 17 to 21

Overview

This issue tracks the migration of Angular from 20 to 21 and PrimeNG from 17.18.11 to 21, which includes significant breaking changes that require careful migration planning and execution.

Version Changes

Core Framework

  • Angular: 20.3.16 → 21.1.2
  • @angular/cdk: 20.2.9 → 21.1.2
  • @angular/cli / @angular-devkit/: 20.3.13 → 21.1.2
  • @angular-eslint/: 20.7.0 → ^21.0.0

UI Library

  • PrimeNG: 17.18.11 → ^21.1.1
  • primeicons: 7.0.0 (unchanged)
  • primeflex: 3.3.1 (unchanged)

New Dependencies

  • @primeuix/styles: ^2.0.2 (new — PrimeNG 21 theming)
  • @primeuix/themes: ^2.0.2 (new — PrimeNG 21 theming)
  • tailwindcss: ^4.1.17 (new)
  • tailwindcss-primeui: ^0.6.1 (new)

Tooling

  • @nxext/stencil: 20.1.0 → 21.0.0

Major Breaking Changes

Component Migrations Required

The following components have been deprecated/renamed and need migration:

  1. Calendar → DatePicker

    • All CalendarModule imports and <p-calendar> usage must be migrated to DatePickerModule and <p-datePicker>
    • Found in: dot-edit-content-calendar-field and other date input components

  2. Dropdown → Select

    • All DropdownModule imports and <p-dropdown> usage must be migrated to SelectModule and <p-select>
    • Extensively used throughout the codebase (experiments, content drive, analytics, etc.)

  3. TabView → Tabs

    • All TabViewModule imports and <p-tabView> usage must be migrated to TabsModule and <p-tabs>
    • Found in: experiments reports, edit content forms, and various portlets

  4. Sidebar → Drawer

    • All SidebarModule imports and <p-sidebar> usage must be migrated to DrawerModule and <p-drawer>
    • Found in: block editor sidebar, edit content sidebar, layout properties

  5. Messages → Message

    • All MessagesModule imports and <p-messages> usage must be migrated to MessageModule and <p-message>
    • Found in: EMA shell, analytics dashboard, global message components

  6. Chip → AutoComplete (for multiple selection)

    • Review ChipModule usage - may need to use AutoComplete with multiple enabled
    • Found in: EMA page tools, experiments header

  7. InputSwitch → ToggleSwitch

    • All InputSwitchModule imports must be migrated to ToggleSwitchModule
    • Check Storybook stories and component usage

  8. OverlayPanel → Popover

    • All OverlayPanelModule imports must be migrated to PopoverModule
    • Found in: toolbar overlay components, Storybook stories

  9. pDefer → Angular @defer

    • Replace PrimeNG's pDefer directive with Angular's native @defer control flow
    • Found in: Storybook stories

Additional Considerations

  • Theming: PrimeNG 21 introduces @primeuix/styles and @primeuix/themes — replaces old CSS variable approach
  • Tailwind CSS: Tailwind v4 is now included along with tailwindcss-primeui for PrimeNG integration
  • API Changes: Review primeng/api imports for any deprecated interfaces or services
  • Styling: Verify PrimeFlex 3.3.1 compatibility with PrimeNG 21
  • Module Imports: All module imports remain similar but verify import paths
  • TypeScript Types: Check for any type changes in component props/events

Migration Strategy

Phase 1: Preparation

  • Review PrimeNG 21 migration guide: https://primeng.org/guides/migration
  • Audit all PrimeNG component usage in the codebase
  • Create a comprehensive list of affected files
  • Set up a feature branch for the migration

Phase 2: Dependency Updates

  • Update primeng to version ^21.1.1 in package.json
  • Update Angular to 21.1.2
  • Add @primeuix/styles ^2.0.2 and @primeuix/themes ^2.0.2
  • Add tailwindcss ^4.1.17 and tailwindcss-primeui ^0.6.1
  • Update primeicons if required for PrimeNG 21 compatibility
  • Verify primeflex compatibility
  • Run yarn install and resolve any dependency conflicts

Phase 3: Component Migrations

  • Migrate Calendar → DatePicker
  • Migrate Dropdown → Select
  • Migrate TabView → Tabs
  • Migrate Sidebar → Drawer
  • Migrate Messages → Message
  • Review and migrate Chip usage
  • Migrate InputSwitch → ToggleSwitch
  • Migrate OverlayPanel → Popover
  • Replace pDefer with Angular @defer

Phase 4: Testing

  • Update all component unit tests
  • Update Storybook stories
  • Run E2E tests
  • Manual QA testing of all affected features
  • Visual regression testing

Phase 5: Documentation

  • Update component documentation
  • Update migration notes
  • Update developer guidelines

Affected Areas

Based on codebase analysis, the following areas will be significantly affected:

  • Edit Content Module: Calendar fields, dropdown selectors, tab views
  • Block Editor: Sidebar components, dialogs
  • Experiments Portlet: Tables, dropdowns, tabs, chips
  • Content Drive: Multi-select, tree components
  • Analytics: Dropdowns, calendars, messages
  • EMA Editor: Sidebars, dialogs, messages
  • UI Library: Various shared PrimeNG components
  • Storybook: Multiple PrimeNG component stories

Resources

Notes

  • This is a major version upgrade with breaking changes for both Angular and PrimeNG
  • PrimeNG 21 introduces a new theming system based on @primeuix/themes
  • Tailwind CSS v4 integration replaces PrimeFlex utilities
  • Consider creating a migration script or codemod for repetitive changes
  • Plan for extensive testing across all affected features
  • Coordinate with QA team for comprehensive testing

Sub-issues

Metadata

Metadata

Assignees

Labels

Team : Modernization

Type

Epic

Projects

dotCMS - Product Planning

Status

In Progress

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions