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 🤩

[ValentinBossi]

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

this is (when i understand you @CrazyJoker correctly) - see here https://ngrx.io/guide/eslint-plugin/rules/no-multiple-actions-in-effects - not recommended.

[ValentinBossi]

could when(event) and on(event) being both when(event)? or both on(event)? in ngrx store it was on() and ofType().

[BaronVonPerko]

I have mixed feelings about this. This is a great implementation of a redux approach to signal store, but I agree with @ducin, this takes away from the simplicity of what signal-store gives us.

Signals in general is a big step towards simplicity (computed is easier than dealing with rxjs pipes), and signal-store is already a great tool for organizing state with signals.

With the reactivity we get from signals, I guess the question is, do we really need these events?

[ducin]

do we really need these events?

💯. Or, slightly rephrased:

Do we need to put redux-alike impl. everywhere? (given that it is already implemented in so many places)

[e-oz]

Events are really needed sometimes, but they have a cost. Similar to effect(), they should be avoided, but they can sometimes be useful if used with care.
I recommend adding some guidelines to the documentation and JSDoc.

• Code that reacts to events should only change internal state, not something global or shared. For example, when an API service clears its cached requests because a global event declared the data is stale, that's a good use of events. When multiple services/components try to change URL params or trigger a redirect because of some event, that's a bad use of events.
• It becomes more difficult to trace the chain of calls. You cannot “click-through” methods in your IDE to see what causes a side effect. You need smart IDEs that can find event usages, and even then, you only see a list of usages, which might not clearly indicate what you're looking for.
• Events and listeners are fragile - when you refactor an event, you can't see direct consequences (as mentioned in the previous point). Over time and as the codebase grows, it becomes easier (or safer) to create a new event that “almost” duplicates an existing one. As you can see, this doesn't improve the overall code quality. Because of this, only global events should exist, and direct method calls should be preferred to internal events.
• Even within one store, if an event triggers mutations in different methods, it can create chaos, weird bugs, and unexpected behavior. Ideally, there should only be one listener per event in a store.

This is a list of reasons why I believe events should be avoided when possible and direct calls should be preferred.
However, there are examples of good event usage, and some cases can benefit noticeably from them.

[LcsGa]

I would definitely need it but I would never dispatch anything from the outside but instead, from within a feature that would trigger an effect on the parent like:
Both a pagination feature with infinite scroll and a category of product in a product store

• if the category changes the page is reset to the first one + it loads the x first products of that category
• if the page changes it loads x next products of the current category
• it loads the x first products (all categories) on init

Would that be a valid use case or am I missing something (pretty new to stores tbh)?

I tried with an effect in the onInit hook but it went into an infinite loop even though the only dependency there was the selectedCategory

EDIT: I could actually use the dispatcher outside of a store/feature in very specific/rare cases but would clearly avoid it as much as possible

[e-oz]

@LcsGa ,
I would use the URL as the source of truth here. When the category is changed: router.navigate(.., { queryParams: { category, page: 0 }, queryParamsHandling: 'merge' }).

The same applies to pagination.

Then, in the component that displays the items, I would use inputs bound to query params, so they would change on navigation and load items using those params.

But I might have misunderstood your case.

[LcsGa]

Yep, that could be a way of handling this but it doesn't fit my use case:

• On top of the page I have a select for categories
• the rest of the same page is a grid with potentially infinite products, loading with an infinite scroll => when I reach the bottom of the page, I load the x next products of the selecte category

[e-oz]

@LcsGa component with the grid will not be destroyed/reloaded if you navigate to the same route.
Having one source of truth (URL in this case) and letting users save/share their state of browsing using the URL is very valuable.

There are other ways, of course:

• Convert the store that keeps information about the selected category into a global store (providedIn: root), inject it into the products grid component, and watch some observable/signal;
• Use events.

[LcsGa]

Yes I completely agree with you but unfortunately I can't do that due to my pagination, as it's made rn. If I had a paginator, I'd do that right away (even though in my case + the router solution, I could simply use an expand) + it's maybe not the best example I gave but my purpose here is to stick with ngrx, to see if what I have in mind would be a good way to use events (I mean, if we didn't have the router option)

[yjaaidi]

🤯 this would make the SignalStore the most versatile state management ever.

I would emphasize that:

• it's an opt-in
• it should improve integration with devtools
• it enables the "shared event" pattern where one event can be handled by different stores/slices instead of creating interdependencies or manual indirection

what a team! 💪

[davdev82]

Really awesome and simple implementation. I would definitely like to give it a try. I like the last bit about scaling up where everything is so neat and concise.