RFC: Add `events` plugin to `@ngrx/signals`

[markostanimirovic]

Which @ngrx/* package(s) are relevant/related to the feature request?

signals

Information

This RFC proposes adding the events plugin to the @ngrx/signals package to enable event-based state management with NgRx SignalStore.

Key Principles

• Combines proven patterns from Flux, NgRx Store, and RxJS.
• Seamlessly integrates with existing SignalStore features.
• Extends Flux architecture with powerful customization options.
• Unifies local and global state management with a single approach.

Prototype

The prototype of the @ngrx/signals/events plugin with a demo application is available at the following link: https://github.com/markostanimirovic/ngrx-signals-events-prototype

Walkthrough

Defining Events

Event creators are defined using the eventGroup function:

// users.events.ts

import { emptyProps, eventGroup, props } from '@ngrx/signals/events';

export const usersPageEvents = eventGroup({
  source: 'Users Page',
  events: {
    opened: emptyProps(),
    refreshed: emptyProps(),
  },
});

export const usersApiEvents = eventGroup({
  source: 'Users API',
  events: {
    usersLoadedSuccess: props<{ users: User[] }>(),
    usersLoadedFailure: props<{ error: string }>(),
  },
});

Performing State Changes

The reducer is added to the SignalStore using the withReducer feature. Case reducers are defined using the when function:

// users.store.ts

import { when, withReducer } from '@ngrx/signals/events';

export const UsersStore = signalStore(
  { providedIn: 'root' },
  withEntities<User>(),
  withRequestStatus(),
  withReducer(
    when(usersPageEvents.opened, usersPageEvents.refreshed, setPending),
    when(usersApiEvents.usersLoadedSuccess, ({ users }) => [
      setAllEntities(users),
      setFulfilled(),
    ]),
    when(usersApiEvents.usersLoadedError, ({ error }) => setError(error)),
  ),
);

Performing Side Effects

Side effects are added to the SignalStore using the withEffects feature:

// users.store.ts

import { Events, withEffects } from '@ngrx/signals/events';

export const UsersStore = signalStore(
  /* ... */
  withEffects(
    (
      _,
      events = inject(Events),
      usersService = inject(UsersService),
    ) => ({
      loadUsers$: events
        .on(usersPageEvents.opened, usersPageEvents.refreshed)
        .pipe(
          exhaustMap(() =>
            usersService.getAll().pipe(
              mapResponse({
                next: (users) => usersApiEvents.usersLoadedSuccess({ users }),
                error: (error: { message: string }) =>
                  usersApiEvents.usersLoadedError({ error: error.message }),
              }),
            ),
          ),
        ),
      logError$: events
        .on(usersApiEvents.usersLoadedError)
        .pipe(tap(({ error }) => console.log(error))),
    }),
  ),
);

Dispatched events can be listened to using the Events service.
If an effect returns a new event, it will be dispatched automatically.

Reading State

State and computed signals are accessed via store instance:

// users.component.ts

@Component({
  selector: 'app-users',
  standalone: true,
  template: `
    <h1>Users</h1>

    @if (usersStore.isPending()) {
      <p>Loading...</p>
    }

    <ul>
      @for (user of usersStore.entities(); track user.id) {
        <li>{{ user.name }}</li>
      }
    </ul>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class UsersComponent {
  readonly usersStore = inject(UsersStore);
}

Dispatching Events

Events are dispatched using the Dispatcher service:

// users.component.ts

import { Dispatcher } from '@ngrx/signals/events';

@Component({
  /* ... */
  template: `
    <h1>Users</h1>

    <button (click)="onRefresh()">Refresh</button>

    <!-- ... -->
  `,
})
export class UsersComponent implements OnInit {
  readonly usersStore = inject(UsersStore);
  readonly dispatcher = inject(Dispatcher);

  ngOnInit() {
    this.dispatcher.dispatch(usersPageEvents.opened());
  }

  onRefresh(): void {
    this.dispatcher.dispatch(usersPageEvents.refreshed());
  }
}

It's also possible to define self-dispatching events using the injectDispatch function:

// users.component.ts

import { injectDispatch } from '@ngrx/signals/events';

@Component({
  /* ... */
  template: `
    <h1>Users</h1>

    <button (click)="dispatch.refreshed()">Refresh</button>

    <!-- ... -->
  `,
})
export class UsersComponent implements OnInit {
  readonly usersStore = inject(UsersStore);
  readonly dispatch = injectDispatch(usersPageEvents);

  ngOnInit() {
    this.dispatch.opened();
  }
}

Scaling Up

The reducer can be moved to a separate file using the custom SignalStore feature:

// users.reducer.ts

export function withUsersReducer() {
  return signalStoreFeature(
    { state: type<EntityState<User> & RequestStatusState>() },
    withReducer(
      when(usersPageEvents.opened, usersPageEvents.refreshed, setPending),
      when(usersApiEvents.usersLoadedSuccess, ({ users }) => [
        setAllEntities(users),
        setFulfilled(),
      ]),
      when(usersApiEvents.usersLoadedError, ({ error }) => setError(error)),
    ),
  );
}

The same can be done for effects:

// users.effects.ts

export function withUsersEffects() {
  return signalStoreFeature(
    withEffects(
      (
        _,
        events = inject(Events),
        usersService = inject(UsersService),
      ) => ({
        loadUsers$: events
          .on(usersPageEvents.opened, usersPageEvents.refreshed)
          .pipe(
            exhaustMap(() =>
              usersService.getAll().pipe(
                mapResponse({
                  next: (users) => usersApiEvents.usersLoadedSuccess({ users }),
                  error: (error: { message: string }) =>
                    usersApiEvents.usersLoadedError({ error: error.message }),
                }),
              ),
            ),
          ),
        logError$: events
          .on(usersApiEvents.usersLoadedError)
          .pipe(tap(({ error }) => console.log(error))),
      }),
    ),
  );
}

The final SignalStore implementation will look like this:

// users.store.ts

export const UsersStore = signalStore(
  { providedIn: 'root' },
  withEntities<User>(),
  withRequestStatus(),
  withUsersReducer(),
  withUsersEffects(),
);

Describe any alternatives/workarounds you're currently using

No response

I would be willing to submit a PR to fix this issue

• Yes
• No

[rainerhahnekamp]

Well, I don't see ANY reason why this shouldn't land. 💯👍

[mauriziocescon]

Very nice! 👏🏿

I wonder: any specific reason why there isn't a withEventGroup or similar? I guess it would be nice to have everything together (withEventGroup, withReducer, withEffects) whenever it makes sense.

[pawel-twardziak]

Hurray! 🚀 Redux-like state handling is the missing part - at least for us and our project 💯

[e-oz]

Is it something like global actions? I mean, actions that any store can intercept.

[dmorosinotto]

Great work @markostanimirovic as @rainerhahnekamp stated just ship it 😉👍
Only one simple question about naming: with “self-dispatching” events using injectDispath you mean a “strong-typed” dispatcher!?🤔
Because in the example I saw only “manual” callling dispatch.specificEvent(…) don’t understand the self-dispatching meaning, or I miss something?! 🧐

[gabrielguerrero]

@markostanimirovic looks fantastic

[ducin]

Damn it, so I'll be the one "against" 😉

The main selling point behind NGRX-SS for me is its simplicity. The core (withState, withComputed, withMethods) is basically getting native angular stuff - but organizing it and making composable. Simple + composable + thin layer over native APIs -> win.

Nobody enforces to use a "plugin". But if majority of the community walked in redux style direction, I'd see it as a step backwards in terms of simplicity. Redux style includes significant tradeoffs and it does make sense to be used - but not in all scenarios. From my personal experience, I've seen redux far many more times abused than used properly. Hope that doesn't happen to NGRX signal store.

[CrazyJoker]

Looks great! What about returning multiple events in an effect, similar to using mergeMap or concatMap in @ngrx effects? Is this possible?

[mikezks]

Great work as always, @markostanimirovic.

This is exactly what we need and turns the Signal Store into a perfect state management solution, where devs may start lean and add the event-based API if needed later.

Very nice! 👏🏿

I wonder: any specific reason why there isn't a withEventGroup or similar? I guess it would be nice to have everything together (withEventGroup, withReducer, withEffects) whenever it makes sense.

Defining Events as with-Feature inside a Signal Store definition would not be a good idea as it leads to coupling of a single Signal Store instance to dispatch Events, which need to have a global nature in Redux-like patterns.

Great work @markostanimirovic as @rainerhahnekamp stated just ship it 😉👍 Only one simple question about naming: with “self-dispatching” events using injectDispath you mean a “strong-typed” dispatcher!?🤔 Because in the example I saw only “manual” callling dispatch.specificEvent(…) don’t understand the self-dispatching meaning, or I miss something?! 🧐

Self-dispatching means, that you do not need to call dispatch to pass in an Event, but just execute a method, pass in a payload if needed and the dispatching works automatically behind the covers.

Is it something like global actions? I mean, actions that any store can intercept.

Yes, exactly that.

[ValentinBossi]

@rainerhahnekamp and @markostanimirovic so so goooood🔥❤️
This was the missing part in signal store:
"Unifies local and global state management with a single approach."

Having back a global event bus is so important🛠️

New people will use anyway signals in angular cause of angular docs and so will choose first the non redux way. so no worries about going in the wrong direction as those with redux needs would stay at ngrx store. this plugin just helps going in the right direction!

[marcindz88]

I think it's also a nice idea, if someone wants to inject a store that has both dispatch and get-data functionality, then its possible to define:

export const injectUserStore = () => ({ ...inject(UserStore), ...injectDispatch(userEvents) });

Maybe it would be nice to include some store-feature that merges action dispatcher into store or util / docs about it

e.g.

export const injectStoreWithDispatch = <
  T extends Type<StateSource<any>>,
  EventGroup extends Record<string, EventCreator | EventWithPropsCreator>,
>(
  store: T,
  events: EventGroup
): Prettify<InjectDispatchResult<EventGroup> & InstanceType<T>> => ({
  ...inject<InstanceType<T>>(store),
  ...injectDispatch(events),
});

[hudzenko]

Just discovered this feature at ng poland conf. This seems to be a game changer for our team for migration from global store to signal store. Waiting to be landed 🔥

[marcindz88]

Hi @markostanimirovic I think we should already consider a possibility to connect redux dev-tools.

I have a working hacky solution here, that could be used as an inspiration, but with the ability to change @ngrx internal packages, it would be possible to easily create a fully functional and quality solution.

[timdeschryver]

I like that events can be created outside of the store 🤩