@servicetitan/query-params-mobx

MobX-native synchronization between observable store state and the URL query string — a nuqs analog for MobX. Declare typed query params with parser builders; the library keeps location.search and your observables in sync in both directions.

Usage & API documentation lives in the Frontend Community docs, published at docs.st.dev (source: packages/docs/docs/query-params-mobx). Setup, parsers, options, and testing helpers are all documented there.

This README is for contributors to the package.

Source layout

src/
  adapters/    history / browser / in-memory adapters (the source of truth for the query string)
  client/      QueryParamsClient + shared-client singleton (one adapter subscription, batched writes)
  entities/    QueryParam (single key) and QueryParams (multiple keys, atomic writes)
  parsers/     parser builders + option types (vendored from nuqs — see "Vendored code" below)
  react-ioc/   store decorator, deferred params, and caller-owned client provider helper
  react-router/ local-client hooks, the location-driven canonicalize hook, and the
                compatibility QueryParamsHistoryProvider bridge
  test/        memoryAdapter / flushQueryParamWrites helpers for consumers' tests

The package ships four entry points (see exports in package.json): the root, ./react-ioc, ./react-router, and ./test.

The shared client follows nuqs collision semantics: multiple independently bundled consumers may subscribe to one key, same-tick writes are last-writer-wins, and URL changes fan out to all subscribers. Each subscriber parses the serialized URL value with its own parser.

Developing

Install dependencies from the repo root (this is a Lerna monorepo):

npm install

Building

# from the repo root — builds every package (includes type-checking)
npm run build

# build just this package
npm run build --scope @servicetitan/query-params-mobx

Testing

Tests are colocated under src/**/__tests__.

# from the repo root — runs the full test suite
npm test

# run a single test file
npm test -- packages/query-params-mobx/src/entities/__tests__/query-param.test.ts

Linting

npm run lint

Vendored code

src/parsers/ contains code copied from nuqs (parser builders, option types, and url-encoding.ts). The original MIT LICENSE is preserved alongside it at src/parsers/LICENSE. When syncing upstream changes, keep that attribution intact.