NgRx Setup

This page walks through setting up NgRx in a OneCX Angular application: installing the packages, the general steps to build a feature store, and wiring OneCX platform state into the store with @onecx/ngrx-integration-interface.

This page covers Angular only. There is currently no equivalent state-management pattern documented for React applications in OneCX.

For what NgRx is and when to use it, see NgRx. For the conventions OneCX applications follow, see NgRx Guidelines.

Installation

Install the NgRx packages plus the three OneCX libraries:

npm install @ngrx/store @ngrx/effects @ngrx/entity @ngrx/router-store @ngrx/component-store @ngrx/store-devtools
npm install @onecx/ngrx-integration-interface @onecx/ngrx-accelerator @onecx/ngrx-linter-rules

The three @onecx/ngrx- packages are released as part of the same OneCX portal release train as the other @onecx/ libraries, so keep them on a matching version.

Getting started

High-level steps:

  1. Define actions for user intents and async outcomes.

  2. Create feature state, initial state, and reducers.

  3. Add selectors to expose view models from state.

  4. Implement effects to handle HTTP calls, routing, and other side effects.

  5. Wire up the feature with provideState/provideEffects (standalone) or feature modules.

  6. Use the Redux DevTools for debugging (StoreDevtoolsModule or provideStoreDevtools).

Wiring OneCX platform state into the store

Library: @onecx/ngrx-integration-interface

@onecx/ngrx-integration-interface bridges OneCX platform state — location, permissions, configuration, app config, current MFE, page, theme, and workspace — into the NgRx store as a single onecx feature slice. You provide a reducer and opt into the platform pieces you need by registering one or more store-connector providers.

Register the onecx slice with its reducer and add the connectors you want to the providers of your application module. The module is bootstrapped with bootstrapModule() from @onecx/angular-webcomponents, as described in Module Approach:

src/app/app.module.ts
import { NgModule } from '@angular/core';
import { StoreModule } from '@ngrx/store';
import {
  oneCxReducer,
  providePermissionsStoreConnector,
  provideConfigurationStoreConnector,
  provideCurrentThemeStoreConnector,
  provideAppConfigStoreConnector,
} from '@onecx/ngrx-integration-interface';

@NgModule({
  imports: [
    // feature key is "onecx"
    StoreModule.forRoot({ onecx: oneCxReducer }),
  ],
  providers: [
    // opt into the platform state you consume
    providePermissionsStoreConnector(),
    provideConfigurationStoreConnector(),
    provideCurrentThemeStoreConnector(),
    provideAppConfigStoreConnector(),
  ],
})
export class AppModule {}
src/bootstrap.ts
import { bootstrapModule } from '@onecx/angular-webcomponents';
import { environment } from './environments/environment';
import { AppModule } from './app/app.module';

bootstrapModule(AppModule, 'microfrontend', environment.production);

A Remote Component has no application module. It is bootstrapped with bootstrapRemoteComponent() from @onecx/angular-webcomponents, as described in Component Approach, so pass the store and the connectors in its providers array instead:

src/app/remotes/example/example.component.bootstrap.ts
import { provideStore } from '@ngrx/store';
import { bootstrapRemoteComponent } from '@onecx/angular-webcomponents';
import { oneCxReducer, providePermissionsStoreConnector } from '@onecx/ngrx-integration-interface';
import { environment } from '../../../environments/environment';
import { ExampleComponent } from './example.component';

bootstrapRemoteComponent(ExampleComponent, 'example-remote-component', environment.production, [
  // other Remote Component providers
  provideStore({ onecx: oneCxReducer }),
  providePermissionsStoreConnector(),
]);

Each connector subscribes to the matching OneCX platform service and dispatches into the store, so you can read platform state with selectors instead of reaching for a service directly. Read it back with the generated selectors:

src/app/shared/onecx.selectors.ts
import { createOneCxSelector, getOneCxSelectors, OneCxState } from '@onecx/ngrx-integration-interface';

// root state of the application; the "onecx" key matches the StoreModule.forRoot registration
interface AppState {
  onecx: OneCxState;
}

export const { selectPermissions, selectConfig, selectCurrentTheme, selectAppConfig } =
  getOneCxSelectors(createOneCxSelector<AppState>());

Use the matching select…​ for each slice you registered. Selectors for slices that are not registered simply resolve to undefined until that connector is added.

The full list of available store-connector providers and the onecx slice state shape is documented with the library.

For the other OneCX NgRx libraries, @onecx/ngrx-accelerator and @onecx/ngrx-linter-rules, see OneCX utilities in the guidelines.

  • NgRx — what NgRx is, when to use it, and an index of the NgRx pages.

  • NgRx Guidelines — the conventions OneCX applications follow and the OneCX utility libraries.

  • State Management — why OneCX Angular applications use NgRx.