New `withUrlParamsSync` extension for URL-state synchronization

[yannickglt]

I've created a withUrlParamsSync extension for NgRx Signal Store that automatically synchronizes selected state properties with URL parameters (query params or route params). It works bidirectionally: state changes update the URL, and URL changes update the state.

Why?

• Users can share/bookmark URLs with filters, sorting, pagination preserved
• Direct navigation to specific application states
• No need to manually sync state ↔ URL in every component

Example

export const appRoutes: Route[] = [{
  path: 'visibility',
  data: { urlParamsSyncKey: 'todo-list' },
  loadComponent: () => …,
];

…

export const TodoListStore = signalStore(
  { providedIn: 'root' },
  withState(initialState),
  withUrlParamsSync<TodoListState>({
    key: 'todo-list', // Must match route.data['urlParamsSyncKey']
    select: (state) => ({
      'filters.search': state.filters.search,
      sortBy: state.sortBy,
      sortOrder: state.sortOrder,
    }),
    queryParamsKey: {
      'filters.search': 'search',
      sortBy: 'sort_by',
    },
    defaultValues: {
      'filters.search': null,
    },
    syncType: 'queryParams', // or 'routeParameters'
  }),
)

When filters.search changes, the URL updates to ?search=.... When the URL changes (e.g., user navigates back), the state updates automatically.

Features

• ✅ Bidirectional sync (state ↔ URL)
• ✅ Supports query params and route params
• ✅ Nested objects via dot notation (filters.search)
• ✅ Custom serialization/deserialization
• ✅ Default value filtering (keeps URLs clean)
• ✅ Key mapping (state key → URL param name)
• ✅ Only syncs when target route is active

Implementation

The code is production-ready and unit tested. We use if in production for a month.
I think it can be useful to share and your repository (I use on my own) sounds the good place to host it.

If you're interested, I can create a PR with the implementation.

Let me know if you'd like me to proceed and if there are rules to follow 🙂

[rainerhahnekamp]

I think @michael-small is the best one to response because he was already researching/working on something in that field.

[michael-small]

Thank you for this @yannickglt.

We have been discussing an RFC for routing sometime soon, so this comes at a great time. I had a more basic/less featured query param bidirectional sync, as well as a params sync in progress. But like I said, they are lowfi compared to this feature you are proposing.

For reference since I was working on a crude version of something like this, my take on a first draft of a query params syncer.

import { Params } from '@angular/router';
import { signalMethod, signalStore, signalStoreFeature, withHooks, withMethods } from '@ngrx/signals';

// It is not confirmed that we would pull in a dependency, 
// but this is what I have used in prod projects for this feature
import { injectQueryParams } from 'ngxtension/inject-query-params'; 

import { updateState, withDevtools } from '@angular-architects/ngrx-toolkit';
import { withImmutableState } from '@angular-architects/ngrx-toolkit';

type QueryParamsState = {
    id: string;
};

const initialState: QueryParamsState = {
    id: '',
};

export const withDefaultFilters = (p: Params): QueryParamsState => ({
    id p['id'] || '',
});

/**
 * @param filterFn Map default values to query params.
 * 
 * @example 
 * 
    type QueryParamsState = ...;
    const initialState: QueryParamsState = {
       id: '',
        // ...
    };

    // Although we give default `''` values anyways in a store's `initialState`, 
    // these fallback `''` are needed so that the param types are inferrable
    export const withDefaultFilters = (p: Params): QueryParamsState => ({
        id: p['id'] || '',
        // ...
    });

    export const QueryParamsStore = signalStore(
        // ...
        withImmutableState(initialState)
        withQueryParams(withDefaultFilters)
    );
 */
export function withQueryParams<T extends Record<string, string>>(filterFn: (p: Params) => T) {
    return signalStoreFeature(
        withMethods(store => ({
            // The more reactivve thing technically would be to make each computed, but this is convenient/functional
            _setQueryParams: signalMethod<T>(params => {
                updateState(store, 'set query params', { ...params });
            }),
        })),
        withHooks({
            onInit(store) {
                const queryParams = injectQueryParams(params => filterFn(params));
                store._setQueryParams(queryParams);
            },
        })
    );
}

export const QueryParamsStore = signalStore(
    { providedIn: 'root' },
    withDevtools('queryParams'),
    withImmutableState(initialState),
    withQueryParams(withDefaultFilters)
);

I'm thinking that query params + route params support in whatever form would be the bedrock of a routing support, and the basis of an RFC.

Seeing your withUrlParamsSync, I think it looks real promising. But before opening a PR, two things

1. What other maintainers like @rainerhahnekamp think about considering any particular implementation before a formal RFC. I'm really liking the preview of your proposed API, but I'm thinking we probably want to hold off on much further consideration until we can formally RFC a cohesive routing API for the Toolkit.
2. Some particulars about withUrlsParamsSync.
   • What does writing to a param look like? Is it just patching the respective selected piece of state like other patchable signal store state?
   • Does it have any dependencies? My own lofi solution has the bulk of its heavy lifting done via a dependency at the moment, but that is not a guarantee that it would be added without much discussion among us maintainers.
   • Before making a PR, a Stackblitz or some hosted example would probably cover a lot of other questions of ours as well as provide room for anyone to familiarize themselves.

In short, you bring this here at a great time, but this would likely be a contending piece of a greater routing RFC we were going to get to within the coming weeks.

[rainerhahnekamp]

I think it would be good if we take a loot at different implementations and then try to come up with a solution that takes the best ideas.

That what also mean that we should check out the implementation from our buddy @LayZeeDK https://github.com/ngworker/router-component-store/blob/main/packages/router-signal-store/README.md

[LayZeeDK]

Happy to give whatever you need back to NgRx or this repo

[yannickglt]

I love the router signal store btw, didn't know someone migrated it 😍

I created the following stackblitz based on the NgRx signal store demo: https://stackblitz.com/edit/at-ngrx-sig-store-ertcmaek?file=src%2Fwith-url-params-sync.ts

Hopefully it answers your questions and give you a showcase you can play with (don't hesitate to change the syncType).

Thanks :)

[michael-small]

@yannickglt hey, sorry it's been so long. I had not done an RFC before and was overthinking everything, wanting to be a perfectionist. Eventually that turned into being uncertain how to proceed, and being embarrassed to respond after ages. But you put a lot of work into withUrlParamsSync and are sharing this here, so I shouldn't keep putting this off.

I have looked the feature over a few times, but I will do so one more time and take proper notes so I can ask some questions. I'll @ you again with those questions soon, once I have the time. Then that will be good to reference for the greater routing feature(s) RFC story.

[yannickglt]

Hi @michael-small
No worries, I know it can take times to do it well. Don't hesitate for the questions, and btw my proposal implementation is just food for thought (even if we use it in prod at Meikai today). It's OK to start a new implementation from zero if you think it will fit the RFC better.
Cheers

[OlegSuncrown]

Maybe we can have something similar to NgRx Router Store, but for Signal Store.