Migration

v1 to v2

Move from useRouteQuery and Zod schemas to codecs, useQueryState, and useQueryStates.

v2 is a new API. useRouteQuery and its Zod schemas are replaced by codecs that carry their own rules, and writes are batched across the whole app.

What changed

v1v2
useRouteQuery({ key, schema: z.enum([...]), default })useQueryState(key, enumCodec([...], { default }))
useRouteQuery({ schema: { a, b }, default: { a, b } })useQueryStates({ schema: { a: codec({ default }), b: codec({ default }) } })
key as a prefix for object schemasprefix
mode: 'push'historyMode: 'push' in the codec options, or on the group
Zod rules such as z.number().int().min(1)Codec options: numberCodec({ int: true, min: 1 })
A Zod object stored in one keyschemaCodec(z.object({ ... })), with any Standard Schema library
Nested objects flattened as a.b.cOne level per group; use a prefix, or schemaCodec for a nested object
nullable: trueLeave default out: the value can be undefined
enabled, debugRemoved. Bad values are logged in development and listed in client.issues.
Writes from separate calls navigate separatelyEvery write in a tick is one navigation

One value

- import { useRouteQuery } from '@chronicstone/vue-route-query'
- import { z } from 'zod'
+ import { enumCodec, useQueryState } from '@chronicstone/vue-route-query'

- const layout = useRouteQuery({
-   key: 'layout',
-   schema: z.enum(['table', 'grid']),
-   default: 'table',
- })
+ const layout = useQueryState('layout', enumCodec(['table', 'grid'], { default: 'table' }))

An object

- const filters = useRouteQuery({
-   key: 'filters',
-   schema: { search: z.string(), status: z.array(z.string()) },
-   default: { search: '', status: [] },
- })
+ const filters = useQueryStates({
+   prefix: 'filters',
+   schema: {
+     search: stringCodec({ default: '' }),
+     status: arrayCodec(stringCodec(), { default: [] }),
+   },
+ })

Array values change format. v1 wrote them as JSON, ?filters.status=["open","closed"], and arrayCodec writes ?filters.status=open,closed. If old links must keep working, keep the JSON format with a small codec:

const 
jsonListCodec
=
defineCodec
<string[]>({
parse
(
raw
) {
try { const
value
: unknown =
JSON
.
parse
(
raw
)
if (
Array
.
isArray
(
value
)) {
return {
ok
: true,
value
:
value
.
map
(
String
) }
} } catch {} return {
ok
: false,
issue
: {
reason
: 'format',
message
: 'not a JSON list' } }
},
serialize
: (
value
) => (
value
.
length
?
JSON
.
stringify
(
value
) : null),
}) const
status
=
jsonListCodec
({
default
: [] })

Install

npm install @chronicstone/vue-route-query@2

zod is no longer a peer dependency. Keep it only if you use schemaCodec with Zod, or for the rest of your app.

Copyright © 2026 Cyprien Thao. Released under the MIT License.