Upgrade Guide

Upgrading Angular: legacy → current

Move from primus-angular-ui-legacy (Angular 16–20) to primus-angular-ui (Angular 21+).

Step 1 — Upgrade Angular

npx @angular/cli@latest update @angular/core@latest @angular/cli@latest

Follow the Angular update guide for your specific version jump (e.g. 20 → 21).

Step 2 — Swap the package

npm uninstall primus-angular-ui-legacy
npm install  primus-angular-ui

@primus/ui-core stays the same — no change needed there.

Step 3 — Update imports

// Before
import { PrimusUiModule } from 'primus-angular-ui-legacy';
import { PrimusAuthService } from 'primus-angular-ui-legacy';

// After
import { PrimusUiModule } from 'primus-angular-ui';
import { PrimusAuthService } from 'primus-angular-ui';

Run a global find-and-replace: primus-angular-ui-legacy → primus-angular-ui.

Step 4 — Migrate to Standalone (recommended)

If your project uses NgModule, you can migrate to Standalone incrementally. The Primus package supports both — no forced migration.

To keep NgModule — nothing changes:

// app.module.ts — works exactly the same
import { PrimusUiModule } from 'primus-angular-ui';

@NgModule({
  imports: [PrimusUiModule.forRoot({ apiBaseUrl: '...' })]
})
export class AppModule {}

To switch to Standalone — update main.ts:

// main.ts
import { bootstrapApplication } from '@angular/platform-browser';
import { providePrimus, providePrimusTheme } from 'primus-angular-ui';
import { AppComponent } from './app/app.component';

bootstrapApplication(AppComponent, {
  providers: [
    providePrimus({ apiBaseUrl: 'https://api.yourdomain.com' }),
    providePrimusTheme({ defaultTheme: 'dark' }),
  ],
});

Step 5 — Remove CUSTOM_ELEMENTS_SCHEMA (if you had it)

Angular 21 no longer requires CUSTOM_ELEMENTS_SCHEMA for Primus Web Component wrappers. Remove it if present:

// Remove this if it was added for Angular 16 compatibility
schemas: [CUSTOM_ELEMENTS_SCHEMA],

Step 6 — Replace legacy-only components

If you used any legacy-only components, replace them:

Legacy component	Replacement
primus-metric-card	primus-stats-card
primus-progress-ring	<meter> from @primus/ui-core

<!-- Before -->
<primus-metric-card [value]="revenue" label="Revenue" delta="+12%"></primus-metric-card>

<!-- After -->
<primus-stats-card [value]="revenue" label="Revenue" delta="+12%" trend="up"></primus-stats-card>

---

Version history — breaking changes

v0.4.0 → v0.5.0

No breaking changes.

Additions:

• primus-rbac-admin (Angular 17+)
• PrimusPasswordInput, PrimusInputGroup
• Toast/Tooltip/Skeleton/Spinner/Accordion/Dropdown/Tabs added to @primus/ui-core JS bundle

v0.3.0 → v0.4.0

No breaking changes.

Additions:

• Banking and Insurance component suites
• primus-date-range-picker

v0.2.0 → v0.3.0

Breaking: PrimusLayout slot names changed.

<!-- Before v0.3.0 -->
<primus-layout>
  <ng-template primusNavSlot>...</ng-template>
  <ng-template primusContentSlot>...</ng-template>
</primus-layout>

<!-- After v0.3.0 -->
<primus-layout>
  <primus-sidebar [items]="navItems"></primus-sidebar>
  <primus-header title="My App"></primus-header>
  <!-- Content goes directly inside layout -->
  <div>Page content</div>
</primus-layout>

v0.1.0 → v0.2.0

Breaking: PrimusButton variant prop values changed.

<!-- Before v0.2.0 -->
<primus-button type="primary">Save</primus-button>
<primus-button type="secondary">Cancel</primus-button>

<!-- After v0.2.0 -->
<primus-button>Save</primus-button>
<primus-button variant="secondary">Cancel</primus-button>

Breaking: PrimusInput value binding changed from [(ngModel)] only to also support formControlName:

<!-- Before — template-driven only -->
<primus-input [(ngModel)]="email"></primus-input>

<!-- After — both supported -->
<primus-input [(ngModel)]="email"></primus-input>
<primus-input formControlName="email"></primus-input>

---

React — version history

v0.4.0 → v0.5.0

No breaking changes. All new components are additive.

v0.3.0 → v0.4.0

No breaking changes.

v0.2.0 → v0.3.0

Breaking: PrimusThemeProvider is now required at the root.

// Before
import { PrimusLogin } from 'primus-react-ui';
// Just used components directly

// After
import { PrimusThemeProvider, PrimusUiCoreBridge } from 'primus-react-ui';

function App() {
  return (
    <PrimusThemeProvider defaultTheme="dark">
      <PrimusUiCoreBridge />
      {/* your app */}
    </PrimusThemeProvider>
  );
}

v0.1.0 → v0.2.0

Breaking: Button variant prop renamed.

// Before
<Button variant="primary">Save</Button>
<Button variant="secondary">Cancel</Button>

// After
<PrimusButton>Save</PrimusButton>
<PrimusButton variant="secondary">Cancel</PrimusButton>

All component names prefixed with Primus for clarity (e.g. Login → PrimusLogin, DataTable → PrimusDataTable).

---

Checklist

Use this before deploying an upgrade:

• npm install completed with no peer dependency errors
• import paths updated (find-replace done)
• App builds without TypeScript errors (ng build --aot / tsc)
• Legacy-only components replaced
• Auth flow tested (sign in, sign out, token refresh)
• Theme toggle tested (light ↔ dark)
• Key user journeys tested (login → dashboard → form → submit)
• Parity test passing: node packages/docs/parity-test.js