Feature Request: Help with URL state migrations

[tordans]

Tanner Linsley who is advocating for storing the application state in the URL hinted (Example) a few times that he has a migration concept that allows to update old URL configs to a new structure with a migration concept.

I wonder, how a library like next-usequerystate could help with this kind of migrations.

I am have some very basic code that …

• will make sure a previous parser format will still work https://github.com/FixMyBerlin/atlas-app/blob/develop/src/app/regionen/%5BregionSlug%5D/_hooks/useQueryState/useConfigParamParser/customParseStringify.ts
• will make sure the app initializes with a valid config but also preserve all values that are still possibile to preserve https://github.com/FixMyBerlin/atlas-app/blob/develop/src/app/regionen/%5BregionSlug%5D/_components/mapStateConfig/initializeMapRegionConfig.ts

However, both are not great and not really migrations, just preventing the worst invalid states…

---

Maybe this is something for the roadmap?

[tordans]

While looking into #404 I thought of possible ways to support this idea of migrations.

But first…

UseCase

Whenever we have a complex URL (like an object)

• that URL can break, so a broken object is received by the hook
• that URL can hold an outdated object, which is not supported anymore by the app

In both cases, I want to rescue as much information as possible from the object and update the URL with a new, valid object.

Example

In my case, the object holds which UI elements are active and how they are configure. However, the UI elements can chance. I need to remove/ignore parts of the URL object. Or the UI configuration options can change, which means I need to update the object as well.

Current issue

Right now, I have no way to access the current URL param inside the withDefaults setting.

Possible solution A: Add a callback to withDefaults

  const configParamParser = createParser({
    parse: (query: string) => customParse(query) as ThemeConfig[],
    serialize: (value: ThemeConfig[]) => customStringify(value),
  })
    .withOptions({ history: 'push' })
    .withDefault((urlConfigFromFirstPageLoad) => {
      const freshConfig = createMapRegionConfig(region.themes)
      // This is my migration step.
      // It should only happen once when the hook is used first.
      // It takes the unknown param and performs cleanup and migration tasks.
      // To then return a propperly formatted config…
      const initializedConfig = initializeMapRegionConfig({
        freshConfig,
        urlConfig: urlConfigFromFirstPageLoad,
      })
      return initializedConfig
    })

Possible solution B: Add a withTransforamtion option

Inspired by ZOD.transform (https://github.com/colinhacks/zod#transform).
In this case, the withDefault would become more like a Promise.prototype.catch(), which is only called then the transform throws (or something)

  const freshConfig = createMapRegionConfig(region.themes)
  const configParamParser = createParser({
    parse: (query: string) => customParse(query) as ThemeConfig[],
    serialize: (value: ThemeConfig[]) => customStringify(value),
  })
    .withOptions({ history: 'push' })
    .withTransformation((urlConfigFromFirstPageLoad) => {
      const initializedConfig = initializeMapRegionConfig({
        freshConfig,
        urlConfig: urlConfigFromFirstPageLoad,
      })
      return initializedConfig
    })
    .withDefaults(freshConfig)

[tordans]

I found a work around for the possibly invalid param by expanding my customParser:

FixMyBerlin/atlas-app@c796eb1

This does guard the application against undefined states where the initial URL is invalid. However, it also causes weird state effects.

1. Open page with broken config-param
2. App fixes the config-param and renders fine but does not fix the URL
3. Only once the user triggers a setConfig, the fixed URL is populated

[tordans]

To close this of, I found a solution that I like with the help of @franky47. The working version can be found at https://github.com/FixMyBerlin/atlas-app

In short…

• The URL state migration is done in the NextJS middleware https://github.com/FixMyBerlin/atlas-app/blob/develop/src/middleware.ts
• As such, the app only ever receives a migrated URL, so my nuqs code does not need to handle old URLs

Two things about the middleware…

• The URLs are escaped, which is why somewhere in the app I re-initialize them with nuqs so they look nice again
• There is a bug in DEV when using custom hostnames which requires a workaround like https://github.com/FixMyBerlin/atlas-app/blob/develop/src/app/regionen/%5BregionSlug%5D/_components/DevMiddlewareHostnameWorkaround.tsx

[franky47]

The URLs are escaped, which is why somewhere in the app I re-initialize them with nuqs so they look nice again

Check out the serializer helper, it might be useful for this case.

A hack I should probably add to the docs is to forego specifying parsers, and pass it the whole querystring as a base to be reformatted:

import { createSerializer } from 'nuqs'

const serialize = createSerializer({})
serialize(new URLSearchParams(location.search), {})