Migrate from PrimeNG

Moving a PrimeNG v21 application to Optimus UI.

Overview #

Optimus UI is the open-source MIT licensed continuation of PrimeNG (now closed-source), rebranded due to trademark restrictions. Optimus UI v1 targets Angular 21 and is fully API-compatible with PrimeNG v21, so migrating is a rename rather than a rewrite. From v1 onward, Optimus UI evolves independently and future versions will diverge from PrimeNG, so v1 is the smoothest point to switch.

Component selectors keep the p- prefix and icon classes keep the pi- prefix, so your templates are not affected by the migration.

Prerequisites #

Your project must be on PrimeNG v21 before migrating, as Optimus UI v1 mirrors the PrimeNG v21 API. If you are on an older version, update PrimeNG first by following its v21 migration guide.

ng update primeng@21

The migration schematic verifies this requirement and aborts when PrimeNG is missing or older than v21. The check can be bypassed with the --force flag, for example in workspaces where the dependency is declared in a non-standard location.

Automated Migration #

The recommended way to migrate is the migrate-from-primeng schematic. Install @openng/optimus-ui first so the Angular CLI can resolve it, then run the schematic: packages are swapped, imports are rewritten and dependencies are installed.

npm install @openng/optimus-ui
ng generate @openng/optimus-ui:migrate-from-primeng

Note that ng add does not run the migration. It only sets up Optimus UI in a fresh project and makes no changes when primeng is detected. The schematic can be re-run at any time, for example after pulling in unmigrated code, and accepts a couple of flags. --skip-install skips the package install task and --force bypasses the PrimeNG v21 version check.

ng generate @openng/optimus-ui:migrate-from-primeng --skip-install
ng generate @openng/optimus-ui:migrate-from-primeng --force

After rewriting, the schematic scans the workspace and prints a report of any remaining primeng, primeicons or @primeuix references it could not migrate automatically, with file and line numbers. Review these manually using the tables in the manual migration section below.

Files your .gitignore excludes are left alone, so coverage reports and build output are neither rewritten nor reported. The report itself is printed before the CLI lists the files it created and updated — that list only covers what the migration changed for you, so scroll back up to the warnings before you build.

What the Schematic Does #

The schematic performs the following steps across the whole workspace, skipping build output and dependency folders.

Swaps the PrimeNG package family for the Optimus UI equivalents in every package.json.
Rewrites import specifiers and renamed identifiers, such as providePrimeNG, in all .ts and .mts source files.
Updates asset references, such as the PrimeIcons stylesheet, in stylesheets and in angular.json / project.json.
Prints a report of leftover references that require manual review.
Schedules a package install, unless --skip-install is set.

Manual Migration #

If you prefer to migrate by hand, or need to finish references the schematic reported as leftovers, apply the renames below. Start by replacing the packages.

# Using npm
npm uninstall primeng primeicons @primeuix/themes
npm install @openng/optimus-ui @openng/optimus-ui-themes @openng/icons

# Using pnpm
pnpm remove primeng primeicons @primeuix/themes
pnpm add @openng/optimus-ui @openng/optimus-ui-themes @openng/icons

Packages

Replace the packages in package.json and in every import path. Subpath imports keep their suffix, for example primeng/button becomes @openng/optimus-ui/button.

PrimeNG	Optimus UI
primeng	@openng/optimus-ui
primeicons	@openng/icons
@primeuix/themes	@openng/optimus-ui-themes
@primeuix/styled	@openng/optimus-ui-styled
@primeuix/styles	@openng/optimus-ui-styles
@primeuix/utils	@openng/optimus-ui-utils
@primeuix/motion	@openng/optimus-ui-motion

Identifiers

Rename the following exported identifiers. The PrimeIcons constants class still compiles through a deprecated alias, however OpenngIcons is the current API.

PrimeNG	Optimus UI
providePrimeNG	provideOptimus
PrimeNG	Optimus
PrimeNGConfigType	OptimusConfigType
PrimeIcons	OpenngIcons

Assets

The PrimeIcons stylesheet moved along with the package rename. Update references in global stylesheets and in the styles arrays of angular.json or project.json from primeicons/primeicons.css to @openng/icons/openng-icons.css.

Example

A typical app.config.ts and component before the migration.

import { ApplicationConfig } from '@angular/core';
import { providePrimeNG } from 'primeng/config';
import Aura from '@primeuix/themes/aura';

export const appConfig: ApplicationConfig = {
    providers: [
        providePrimeNG({
            theme: {
                preset: Aura
            }
        })
    ]
};

// component
import { ButtonModule } from 'primeng/button';

The same code after the migration.

import { ApplicationConfig } from '@angular/core';
import { provideOptimus } from '@openng/optimus-ui/config';
import Aura from '@openng/optimus-ui-themes/aura';

export const appConfig: ApplicationConfig = {
    providers: [
        provideOptimus({
            theme: {
                preset: Aura
            }
        })
    ]
};

// component
import { ButtonModule } from '@openng/optimus-ui/button';

Verify #

Build the application and run your test suite to confirm the migration. Searching the project for the old package names is a quick way to find anything left behind. The schematic scans for the same pattern when it prints its leftover report.

ng build

grep -riEn "primeng|primeicons|@primeuix" src/