It all came from the need to use state that lives in the URL or in storage inside my code, in a way that's both reactive and type-safe. I had used plenty of different solutions for that before. One of them read and wrote storage through a proxy, which let me step in between and handle parsing and serializing right there in the proxy.

Using it looked roughly like this:

import { SESSION_STORAGE_KEYS } from '@/utils/storage'
import { createStorageManager } from '@/utils/storageManagerFactory'

const sessionStorageManager = createStorageManager(sessionStorage, SESSION_STORAGE_KEYS, {
  prefix: 'foo:',
  placeholderData: {
    lastSessionExpiredShown: false,
  },
})

// If not set, returns the placeholder
console.log(sessionStorageManager.lastSessionExpiredShown) // false

// Set a value
sessionStorageManager.lastSessionExpiredShown = true

// Delete a value
delete sessionStorageManager.lastSessionExpiredShown

// Clear all managed keys
sessionStorageManager.clear()

And here's roughly one of the solutions I came up with for the route:

import { computed } from 'vue'
import { useRoute, useRouter } from 'vue-router'

const route = useRoute()
const router = useRouter()

const showLabels = computed({
  get: () => {
    const current = route.query.show_labels
    if (current === undefined) return true
    return current === 'true'
  },
  set: val => {
    router.replace({ query: { ...route.query, show_labels: String(val) } })
  },
})

That's just an example for a single boolean. When several params had to change at once, I used other approaches as well.

Then VueUse came along, and I tried using its composables in my projects. That wasn't enough either, because there were cases where I had to read and write some of this state outside an effect scope. Bit by bit, that's how qpick came about first. Its goal was quite simple. There's state in the route, and I want to read and write it type-safely.

I modeled the approach on nuqs. If you haven't heard of it, I highly recommend taking a look. Anyway, back to our topic.

After using the package for a while, I noticed some problems, and I also wanted the same solution for storage state. Route state, for example, had a race condition where two params written in the same tick could wipe each other out.

Before writing usewagen, I spent some time thinking about the API, because qpick already has a parser system inside it, and I wanted the route and storage composables to share that same parser system. My first idea was to publish them as separate packages and combine them, with a core package and adapter packages for Vue, React and so on. That would have worked for storage, but getting it to work for the router would have been tough. Besides, nuqs is already popular in the React ecosystem, and for good reason.

Another thing I wanted was for the parsers in a project to be collected automatically, so they could be used in composables just by their name. At first I had packages like @aioli/core, @aioli/vue-route and @aioli/vue-storage in mind. What's aioli, you ask? A burger sauce, actually 😄. I hadn't put much thought into the name back then. Clearly I was hungry.

The problem was that both adapter packages depended on core and re-exported its parsers, so parseAsBoolean, for example, could be imported from both the router and the storage package. And since both packages depended on core, their versions had to be kept in sync, otherwise core couldn't be deduped and the app could end up with two copies of it. On top of that, I wanted to write a Vite plugin that collects the parsers and makes them available across the project. And of course, the utility functions for creating custom parsers come from core as well.

Thinking about all of this, I decided to publish it as a single package. I can't really tell yet whether it will find its place in the community anyway, so I started building it to solve my own problem. It's still split on the inside. The parsers come from usewagen, while the composables and the Vite plugin live under usewagen/router, usewagen/storage and usewagen/vite. vue-router and vite are optional peer dependencies, so you only install what you use.

The goal is actually very simple. There's state in the route or in storage, I want to read and write it type-safely, and I want it to be reactive at the same time. That's exactly where the name came from. Wagen apparently means wagon in German, something to carry your state around in. At first I tried to name it just wagen, but npm's name policy put the brakes on that, so I went with usewagen.

Soo, how do you use usewagen?

It's very simple. Let's look at an example:

const route = useRoute()
const router = useRouter()

const page = ref(Number(route.query.page ?? 1))

watch(page, value => router.replace({ query: { ...route.query, page: String(value) } }))
watch(
  () => route.query.page,
  value => (page.value = Number(value ?? 1)),
)

With usewagen, the same logic can be written like this:

import { parseAsInteger } from 'usewagen'
import { useRouteState } from 'usewagen/router'

const page = useRouteState({ key: 'page', parser: parseAsInteger.withDefault(1) })

Custom parsers can be written like this:

import { defineParser } from 'usewagen'

export const parseAsSlug = defineParser<string>({
  parse: raw => (/^[a-z0-9-]+$/.test(raw) ? raw : null),
})

And used directly like this:

const slug = useRouteState({ key: 'slug', parser: parseAsSlug })

To use them by name, they need to be registered first. This is where the Vite plugin comes in. It collects the parsers in a folder and serves them from a virtual module that you hand to createWagen.

import { usewagen } from 'usewagen/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [usewagen({ dirs: 'src/parsers' })],
})

import { createWagen } from 'usewagen'
import { parsers } from 'virtual:usewagen/parsers'
import { createApp } from 'vue'

import App from './App.vue'

const wagen = createWagen({ parsers })

createApp(App).use(wagen).mount('#app')

After that, the name is enough:

// by name
const slug = useRouteState({ key: 'slug', parser: { name: 'parseAsSlug' } })

// with a default value (parseAsSort being another parser in src/parsers)
const sort = useRouteState({ key: 'sort', parser: { name: 'parseAsSort', defaultValue: 'asc' } })

You can also create as many scoped storages as you like:

import { createLocalStorage, createMemoryStorage, createSessionStorage } from 'usewagen/storage'

const local = createLocalStorage({ prefix: 'app:' })
const memory = createMemoryStorage()

Maybe you need a storage for tests? Here it is! createMemoryStorage keeps everything in a Map, and you can hand it to a single state or to createWagen for the whole app. And if you need a store of your own, createStorage takes four functions and gives you the same API:

import { createStorage } from 'usewagen/storage'

const store = new Map<string, string>()

const shared = createStorage('shared', {
  getItem: key => store.get(key) ?? null,
  setItem: (key, value) => void store.set(key, value),
  removeItem: key => void store.delete(key),
  keys: () => [...store.keys()],
  prefix: 'app:',
})

And that's how usewagen was born. If I'm honest, it's less an invention than a reunion of every solution I'd tried before, rethought and finally heading in the same direction.

It's about a five-minute conversation that changed how qpick works.

The Conversation

I'd been wanting to get feedback on qpick from Eduardo (the author and maintainer of vue-router and pinia). He pulled up the docs, read through them for a few minutes, and pointed at something I'd completely overlooked: idempotency.

I'd spent so much time thinking about reactivity that I missed something equally fundamental to a URL parser library. When you parse a value from the URL and serialize it back, you should get the same string. Always. And if you parse that string again, you should get the same value. No matter how many times you repeat the cycle.

What the Spec Says

If you look at the URL Standard's goals, idempotency is stated explicitly:

Ensure the combination of parser, serializer, and API guarantee idempotence. For example, a non-failure result of a parse-then-serialize operation will not change with any further parse-then-serialize operations applied to it. Similarly, manipulating a non-failure result through the API will not change from applying any number of serialize-then-parse operations to it.

A simple way to think about this: a function is idempotent when applying it twice gives the same result as applying it once.

f(f(x)) = f(x)

For a URL parser, the equivalent guarantee is:

parse(serialize(parse(str))) === parse(str)

No matter how many round-trips you do, the value stabilizes after the first successful parse.

Removing eq

The first thing I did was remove the eq function from the parser config:

export type ParserConfig<T> = {
  parse: (value: string) => T | null
  serialize: (value: T) => string
  eq?: (a: T, b: T) => boolean 
}

The eq function existed for one reason: deciding whether a parameter should be cleared from the URL (i.e., whether the current value equals the default). But once you enforce idempotent serialization, you don't need a separate equality function. Two values are "equal" for URL purposes if and only if they serialize to the same string:

function shouldClear<T>(parser: Parser<T>, value: T, clearOnDefault: boolean): boolean {
  // ...
  const eq = parser.eq ?? ((a: T, b: T) => a === b) 
  return eq(value, def) 
  return parser.serialize(value) === parser.serialize(def) 
}

This is simpler and more correct. If your serializer is idempotent, comparing serialized output is the canonical way to check equality. No custom eq needed.

The New API

I also renamed createParser to defineParser to align with Vue ecosystem conventions (defineComponent, defineStore, defineEmits...). Small change, but it makes the API feel more at home in a Vue project.

Here's what a custom parser looks like in alpha-2:

type HexColor = number // 0x000000–0xFFFFFF

const parseAsHexColor = defineParser<HexColor>({
  parse(v) {
    const parsedValue = Number.parseInt(v, 16)
    if (Number.isNaN(parsedValue)) {
      return null
    }
    return parsedValue
  },
  serialize: v => v.toString(16).padStart(6, '0'),
})
// ?color=ff5733 → 16734003

No eq to define. The only contract you need to uphold is that parse and serialize are inverses of each other, so that round-tripping always produces stable results.

Why Conferences Still Matter

This change came from a five-minute hallway conversation. I could have stared at the code for weeks and not seen it, because I was too close to it, thinking in terms of reactivity and Vue internals instead of stepping back to ask "what guarantees should a URL parser provide?"

That's what events like MadVue give you. A different set of eyes, a different frame of reference, and access to people who've been thinking about these problems longer than you have. Oh, and apparently we were the first Turkish attendees in MadVue's history. 😅

You can find all the alpha-2 changes on GitHub. If you're using qpick, I'd love to hear how the new API feels.

So you do the responsible thing: you start syncing state with route.query. You write a watcher. Then another one. Then you realize route.query.page is a string and your pagination logic just did "2" + 1 = "21". You add parseInt. A fallback. Another watcher for the back button. Forty lines later, you have a working page parameter and you haven't even started on sort.

To be fair, the title is intentionally dramatic. URL is not where all app state should live: it only carries strings, and browsers/servers impose practical URL length limits. So the right target is shareable, navigable UI state (like filters, sorting, pagination), not large or sensitive data.

I got tired of writing that code. So I wrote qpick

What's in a Name?

The name comes from q (query) and pick, as in cherry-picking the exact parameters you need from the URL. I wanted something short enough that you wouldn't resent typing it in every import statement, and honest enough that you'd know what it does before reading a single line of documentation. You pick query params, you get reactive state.

So What Does It Actually Do?

qpick gives you a single composable, useRouteState, that turns URL parameters into writable, type-safe, reactive refs. If you've ever used ref() in Vue, you already know how to use qpick. The only difference is that the source of truth lives in the address bar instead of component memory.

import { parseAsInteger, useRouteState } from 'qpick'

const page = useRouteState({ key: 'page', parser: parseAsInteger.default(1) }) 
// page.value is a number. Always. Never null, never "2", never undefined.
// Setting page.value = 3 navigates to ?page=3.
// Hitting the back button sets it back. Reactively.

That's not pseudocode, it's the actual API. No setup ceremony beyond what you already have with vue-router, no plugin registration required.

Why I Built This

I went looking for something like this in the Vue ecosystem and came up mostly empty. The React world has nuqs, which nails this problem with a clean, composable-driven approach. Vue had router utilities, state management libraries that could optionally sync with the URL, but nothing that treated URL parameters as first-class reactive primitives with the same ergonomics you'd expect from a plain ref().

I wanted something that feels like writing normal Vue code, with an API that looks and behaves like JavaScript you already know. parseAsInteger, parseAsFloat, parseAsBoolean... if you've used parseInt or parseFloat before, the naming and mental model are immediately familiar. Declare what you need from the URL, get a ref back, wire it up with v-model, and move on with your day.

Parsers, or: How to Stop Worrying About Strings

The thing that makes all of this work is the parser system. URLs only speak strings, but your app thinks in numbers, booleans, arrays, dates, and union types. Parsers handle the translation in both directions, and they carry their types with them:

const search = useRouteState({ key: 'q' })
// string | null

const page = useRouteState({ key: 'page', parser: parseAsInteger.default(1) })
// number, parsed, typed, guaranteed non-null

const sort = useRouteState({
  key: 'sort',
  parser: parseAsStringLiteral(['price', 'name', 'rating']).default('price'),
})
// 'price' | 'name' | 'rating', narrowed at the type level

Every parser has a .default() method that does two things at once: it guarantees a non-null type so you can stop writing page ?? 1 everywhere, and it keeps the URL clean by stripping the parameter when the value matches the default. A page in its default state gets a clean URL, no ?page=1&sort=price&inStock=true clutter.

qpick ships with parsers for the common cases like parseAsFloat, parseAsBoolean, parseAsDate, parseAsArrayOf, and parseAsJson, but the one I find myself reaching for constantly is parseAsStringLiteral. It gives you runtime validation and TypeScript type narrowing from a single declaration. If someone manually types ?sort=banana into the address bar, the value quietly falls back to the default instead of propagating nonsense through your app.

When the built-ins don't cover your case, createParser lets you bring your own types:

const parseAsPriceRange = createParser<{ min: number; max: number }>({
  parse(value) {
    const [min, max] = value.split('-').map(Number)
    return Number.isNaN(min) || Number.isNaN(max) ? null : { min, max }
  },
  serialize(value) {
    return `${value.min}-${value.max}`
  },
  eq(a, b) {
    return a.min === b.min && a.max === b.max
  },
})

// ?price=50-200 → { min: 50, max: 200 }

Same pattern, same guarantees, your own domain types.

More Than One Parameter

Most pages you'll work on have several URL parameters that need to stay in sync. qpick handles this by accepting an array of configs and returning an object of refs:

const filters = useRouteState([
  { key: 'q', parser: parseAsString.default('') },
  { key: 'page', parser: parseAsInteger.default(1) },
  { key: 'sort', parser: parseAsStringLiteral(['price', 'name', 'rating']).default('price') },
  { key: 'categories', parser: parseAsArrayOf(parseAsString).default([]) },
])

Each key becomes a reactive ref: filters.q.value, filters.page.value, and so on. But here's the part that matters. When your user types a new search query, you probably want to reset to page 1. If you set filters.q.value and filters.page.value separately, that's two router navigations, two history entries, and a flash of intermediate state that nobody asked for. So instead:

filters.set({ q: 'headphones', page: 1 })

One navigation. One history entry. No intermediate flicker. There's also filters.reset() to restore everything to defaults, and filters.toObject() when you need a plain object for an API call:

watch(
  () => filters.toObject(),
  params => {
    fetchProducts(params)
  },
)

Configs That Travel Between Components

If you've used TanStack Query, the pattern here might feel familiar. TanStack Query encourages you to define query options in a shared file so that any component can reference the same query without duplicating configuration. qpick borrows that idea for URL state: define your configs once, import them wherever you need them, and let the shared source of truth (in this case, the URL) keep everything in sync.

export const searchState = routeStateOptions({
  key: 'search',
  parser: parseAsString.default(''),
  urlKey: 'q',
})

export const pageState = routeStateOptions({
  key: 'page',
  parser: parseAsInteger.default(1),
})

Now ProductList.vue and ProductPagination.vue can both import pageState, call useRouteState(pageState), and they stay in sync automatically. Not through a store or provide/inject or an event bus, but because they both read from and write to the same URL. Change the page in one component, the other one reacts. That's just how refs work when they share a source of truth.

The Small Things That Add Up

Beyond the core API, there are a few design decisions that ended up mattering more than I expected in daily use.

urlKey remapping lets your code use filters.search.value while the URL shows ?q=.... You get developer-friendly names in your components and user-friendly (or API-friendly) names in the address bar, without any disconnect between the two.

Path parameters work too. If your route is /products/:id, you can use { key: 'id', parser: parseAsInteger } and qpick reads from route.params automatically. You can mix path and query params in the same useRouteState call, each with its own parser and default.

History mode is configurable per parameter. A search input should probably use replace since nobody wants 50 history entries from typing a word. A page change should use push because you want the back button to work. When you batch-update with set(), qpick resolves conflicts with a simple rule: push wins over replace, because losing a history entry is worse than gaining an extra one.

And the plugin is entirely optional. If you have vue-router, useRouteState works out of the box. The plugin only exists for cases where you want to override the global defaults.

Give It a Spin

pnpm add qpick

The whole thing is one composable, a set of parsers, and a README that should get you running in a few minutes. If you've ever caught yourself manually syncing route.query with a ref and thought "there has to be a better way", I'd love for you to give it a try.