RFC: Standalone NgRx APIs

[markostanimirovic]

Standalone Angular

Standalone Angular APIs are introduced in version 14. They make Angular modules optional. Check Angular repo for more info 👉
angular/angular#43784, angular/angular#45554

Angular Modules from NgRx packages

Angular modules are not just used to declare components or provide services. They are also used to configure various application and library functionalities. For example, we use the EffectsModule.forRoot method to provide Actions observable at the root level of an Angular application, initialize the effects runner, and register root effects. Therefore, importing root modules from other NgRx packages will configure their functionalities and/or provide services:

@NgModule({
  imports: [
    // provide `Store` at the root level
    // register initial reducers
    // initialize runtime checks mechanism
    StoreModule.forRoot({ router: routerReducer, auth: authReducer }),
    // connect NgRx Store with Angular Router
    RouterStoreConnectingModule.forRoot(),
    // connect NgRx Store with Redux Devtools extension
    StoreDevtoolsModule.instrument(),
    // provide `Actions` at the root level
    // initialize the effects runner
    // register root effects
    EffectsModule.forRoot([RouterEffects, AuthEffects]),
  ],
})
export class AppModule {}

Also, NgRx exposes APIs to register additional reducers and effects in feature modules:

@NgModule({
  imports: [
    // register feature reducer
    StoreModule.forFeature('musicians', musiciansReducer),
    // register feature effects
    EffectsModule.forFeature([MusiciansApiEffects]),
  ],
})
export class MusiciansModule {}

Using NgRx Modules with Standalone Angular APIs

Root Angular modules from NgRx packages can be configured at the application level using the importProvidersFrom function from @angular/core in the following way:

// main.ts
bootstrapApplication(AppComponent, {
  providers: importProvidersFrom(
    RouterModule.forRoot(appRoutes),

    // configure NgRx modules
    StoreModule.forRoot({ router: routerReducer, auth: AuthReducer }),
    RouterStoreConnectingModule.forRoot(),
    StoreDevtoolsModule.instrument(),
    EffectsModule.forRoot([RouterEffects, AuthEffects]),
  ),
});

The feature reducer and effects can be registered lazily in the route configuration for a specific feature:

// musicians.routes.ts
export const musiciansRoutes: Route[] = [
  {
    path: '',
    children: [
      {
        path: '',
        component: MusicianListComponent,
        title: 'Musician List'
      },
      {
        path: ':id',
        component: MusicianDetailsComponent,
        title: 'Musician Details',
        canActivate: [MusicianExistsGuard],
      },
    ],
    providers: importProvidersFrom(
      // register reducer and effects for musicians feature
      StoreModule.forFeature('musicians', musiciansReducer),
      EffectsModule.forFeature([MusiciansApiEffects]),
    ),
  },
];

Standalone NgRx APIs

We can provide a better developer experience in Standalone Angular applications by creating functions to configure NgRx packages. For example, instead of StoreModule.forRoot we can create a function named configureStore or provideStore. The same principle can be applied for other NgRx packages. Their usage would look like this:

bootstrapApplication(AppComponent, {
  providers: [
    // alternative to `StoreModule.forRoot`
    configureStore({ router: routerReducer, auth: AuthReducer }), // or `provideStore`
    // alternative to `RouterStoreConnectingModule.forRoot`
    configureRouterStore(),
    // alternative to `StoreDevtoolsModule.instrument`
    configureStoreDevtools(),
    // alternative to `EffectsModule.forRoot`
    configureEffects([RouterEffects, AuthEffects]), // or `runEffects`
  ),
});

Feature effects and reducers would be also registered by using functions instead of NgModules:

export const musiciansRoutes: Route[] = [
  {
    path: '',
    children: [
      {
        path: '',
        component: MusicianListComponent,
        title: 'Musicians'
      },
      {
        path: ':id',
        component: MusicianDetailsComponent,
        title: 'Musician Details',
        canActivate: [MusicianExistsGuard],
      },
    ],
    providers: [
      // alternative to `StoreModule.forFeature`
      registerStoreFeature(musiciansFeature),
      // alternative to `EffectsModule.feature`
      registerFeatureEffects([MusiciansApiEffects]),
    ],
  },
];

Playground

The playground project is available here

[e-oz]

About the functions - that's an amazing idea!

My humble opinion: since they are supposed to be used inside the "providers", it would be logical and intuitive to call "provideStore", "provideEffects", "provideSomethingElse" - this way you obviously create a collection of providers.

[kbrilla]

Angular itself is also going with 'provide*' naming schema

[Lonli-Lokli]

What's the actual difference except for naming and static mark?

[brandonroberts]

I'd rather use provideStore(config) and runEffects([ApiEffects, MoreEffects]) as the function names also. Also if possible I think it's worth exploring not just wrapping the existing ModuleWithProviders, but using the new ENVIRONMENT_INITIALIZER token along with the providers directly. That way we aren't just still using NgModules underneath.

It's a good question to ask though whether we should just wrap existing APIs for now.

For reference, we used to have EffectsModule.run([effects]), which is where runEffects came from - https://github.com/ngrx/effects/blob/master/docs/intro.md

[LayZeeDK]

How about initializeEffects or registerEffects?

[eskwisit]

[e-oz]

Factories are doing something.

[e-oz]

In case of class names - yes.

[e-oz]

LoL, you are writing things like "ok if you don't get my point", "ok to don't know", and still trying to blame my tone? It was funny 😄

[jrista]

Things are usually named by nouns:

StoreProvider (a provider for stores)

Behaviors that do something are usually named by verbs:

provideStore (a function that creates a provider for stores)

The functions being proposed are behaviors, not things, that create things.... Hence, the verbNoun approach is appropriate. The functions are behaviors, not just things, that are then providing the thing that is ACTUALLY the provider. IMO, a better name would be buildStoreProvider or configureStoreProvider, since the "provider" (a token potentially attached to some configuration) is the thing that Angular's injector uses to look up injectable dependencies. The function doing the work of CREATING or CONFIGURING the provider is what we are talking about here.

[yjaaidi]

Concerning the naming, I am more in favor of naming anything that returns providers provideXXX this will help with auto-completion.
I want to type something like providers: [provide...] and let the IDE come to the rescue.

[yjaaidi]

We recently had a discussion with @brandonroberts about where should we lift the state/effects initialization: bootstrap? router? somewhere else?

Here are the tradeoffs:

at Bootstrap

boostrapApplication(MyApp, {providers: [provideEffects(...)]})

This is a quite nice place and it’s clearly the highest common point… now, the problem is that it requires eager loading all states/effects (so no lazy loading) and this doesn’t scale as the main bundle will keep getting larger and larger.

at Router level

Router allows lazy loading but is it the highest common point after the bootstrap? Not really. In fact, a state will mostly be used by components under some shared route but quickly while the app grows, one might want to reuse the component under another route or anywhere else in the app and that’s when things get tricky. As we broke the locality principle, we have to think about checking out the route providers and move the state/effects to somewhere higher… which will end up being the bootstrap… and thus the clutter in the main bundle.
In addition to this, we can mention the challenge of debugging the state/effects provided in the routing. Someone tries to use a component outside the route and they observe the following surprising behavior “if I navigate to the feature route first, then I move to the other route, the component works, but when I land directly on this route, the action doesn’t change the state” (because the effect wasn’t loaded).

TL;DR

Providing state at bootstrap clutters the bundle and providing state at router level doesn’t scale either as one has to keep thinking about which state should be provided

Concrete example

An app with an UnreadEmailComponent and a bunch of other components used in /emails. Email state/effects are provided at the route level. Months/years later, someone wants to lazy load and dynamically inject UnreadEmailComponent in a dialog or something like that when the user clicks somewhere in the landing page.
If they visit /emails first, it’s going to work but before navigating to /emails the effects/state are not initialized. First, they end up with a bug, then they need to be quite familiar with Ngrx and injectors to understand what’s happening and that’s when they decide to move the state/effects to bootstrap which is annoying because we end up eager loading state/effects while the components that need them are lazy-loaded.

Alternatives

Components should be able to tell that they are part of a "feature" and that the feature's state/effects should be initialized when the first component of this feature is loaded.

@Component({})
class RecipeSearchCmp {
 store = injectRecipeStore();
}

function injectRecipeStore() {
  const store = inject(Store);
  store.addFeature(recipeReducers);
  store.addEffects([...]);
  return store;
}

We can think of more composable functions of course (e.g. provideStore({features:...})).

This also kind of breaks Ngrx indirection but it helps make sure that a feature's or a library's components will never be used without having the state/effects loaded.
In this case, RecipeSearchCmp will always work properly, no matter where and how you load it.

[e-oz]

Components should be able to tell that they are part of a "feature"

This thing I love to hear :) It's a great idea. Will work well in tests, also, I think.

[faileon]

Is there currently any solution for this problem?

[sebastianblesgen]

I'm facing the same issue.
I have split my store in slices. Let say

• featureA used in /featureA/** routes (providing reducer/effect at router level)
• featureB use in /featureB/** routes

Now if I want a

• /stats route with a component that show featureA and/or featureB I need to make sure I also provide reducer and effect.

IMHO we should be able to abstract (have a facade) the store and therefore provide a way to inject whatever is required to be able to use the feature (the facade).

Example:

@Injectable({
  providedIn: 'root',
})
export class FeatureAService {

  field$: Observable<Field[]> = this.store.select(selectFeatureAField);

  constructor(private store: Store<State>) {
    // Check here that a depedenccy (token?) is missing
  }

  loadFields() {
    this.store.dispatch(loadFields());
  }


  static forChild(){
    return [
      makeEnvironmentProviders([{provide: FeatureAService}]),
      provideEffects([FeatureAEffects]),
      provideState(featureAKey, reducer),
    ]
  }
}

Not sure it's the best way, still thinking about it

To still use a unique instance of the service:

...
  static forChild() {
    return [
      makeEnvironmentProviders([{provide: SourceService, useFactory: this.getInstanceFactory, deps: [Store<State>]}]),
      provideEffects([SourceEffects]),
      provideState(sourcesFeatureKey, reducer),
    ]
  }

  private static getInstanceFactory(store: Store<State>) {
    if (!this.instance) {
      this.instance = new SourceService(store);
    }
    return this.instance;
  }

[Niclassg]

Are there currently any generators for creating a standalone component with an ngrx component store attached? I'm having trouble doing this manually and there doesn't seem to be much traction on this topic

[xianshenglu]

I think componentStore can handle this question?