mobx-url-sync

Synchronizes MobX observables with URL query parameters.

Features

• Type-safe API: Register store properties with strict query parameter names.
• Serialization: Supports primitives (string, number, boolean) by default and allows extension for custom types
• Two-way binding: Observable values are initialized from the URL and uses MobX’s intercept to monitor and sync property changes.
• Clean URLs: Removes query parameters when the value matches the default value.

Installation

Install via npm:

1npm install mobx-url-sync

Example

This examples shows a MobX store holding a counter property which is automatically synchronized with the URL query parameter counter.

1. Create a Counter Store

1// counterStore.ts
2import { makeAutoObservable } from 'mobx'
3import { MobxUrlSync } from 'mobx-url-sync'
4
5// Define allowed query parameter(s) (here, only "counter" is allowed)
6type QueryParams = 'counter'
7
8// Initialize MobxUrlSync (no custom serializers needed for numbers)
9const mobxUrlSync = new MobxUrlSync<QueryParams>()
10
11export class CounterStore {
12  counter: number = 0
13
14  constructor() {
15    makeAutoObservable(this)
16    // Register the counter property to sync with the "counter" query parameter.
17    mobxUrlSync.registerField(this, 'counter', 'counter')
18  }
19
20  increment() {
21    this.counter++
22  }
23
24  decrement() {
25    this.counter--
26  }
27}
28
29export const counterStore = new CounterStore()

After calling counterStore.increment() the URL will change to ?counter=1.

API Reference

Class: MobxUrlSync<QueryParameter extends string>

Constructor

1new MobxUrlSync(defaultSerializers?: Serializers, options?: { throttleDelay?: number })

• defaultSerializers: Custom serializers for complex types.
• options.throttleDelay: Delay (in ms) before updating the URL (default is 500ms).

Method: registerField

1registerField<TStore, K extends keyof TStore>(
2  store: TStore,
3  property: K,
4  queryParam: QueryParameter,
5  config?: {
6    defaultValue?: TStore[K];
7    serialize?: (value: TStore[K]) => string;
8    deserialize?: (value: string) => TStore[K];
9  }
10): void

• store: The MobX store instance.
• property: The property on the store to sync.
• queryParam: A string key from a predefined union of allowed query parameters.
• config (optional): Override the default value or serialization behavior.

Behavior

• On Registration:
  The field is added, and its current value is loaded from the URL if available.

• On Changes:
  When the property changes, the URL is updated (debounced). If the new value matches the default or is null/undefined, the query parameter is removed.

License

MIT