queryRef() - URL-persisted ref() for Nuxt

Features

• Drop-in support instead of ref()
• Supports all common types (string, number, boolean, Arrays, Objects)
• Coherently typed for good DX

Quick Setup

Install the module to your Nuxt application with one command:

npx nuxi module add nuxt-queryref

That's it! You can now use queryRef in your Nuxt app ✨

Usage

Use queryRef() just like you would use a normal ref()

const variable = queryRef(<key>, <value>)

It takes two Parameters:

• <key>: The key for the URL Query Param
• <value>: The actual value, just like you would use with ref()

Following types are supported for <value>:

• string
• number
• boolean
• Object
• Array (of each of the above)

Examples

const name = queryRef('name', 'Lukas')

// With generic type (optional, default is based on <value>)
const name = queryRef<string>('name', 'Lukas')

// With Object and custom type
const name = queryRef<{ firstName: string }>('name', { firstName: 'Lukas' })

Use-cases

There are multiple scenarios where URL-persisting makes sense:

• In general: making URLs shareable or look the same on reload
• Persisting filters or sorting for sharing
• Persisting selected tabs or popups
• Persisting selected image (-index) for e.g. a slider

Under the Hood

Some insights:

• queryRef() uses a regular ref() under the hood, but adds the according loader and watcher to sync with the URL - therefore you can use your local variable exactly like a regular ref (e.g. setting like variable.value = 'foobar')
• The value is loaded on page load via useRoute(), which ensures that the value will already be loaded during SSR and no flickering will occur
• If the provided value is an array, the type will be inferred by the first item of the value. Therefore mixed-type arrays are currently not supported (or will lead to problems)

Contribution

# Install dependencies
npm install

# Generate type stubs
npm run dev:prepare

# Develop with the playground
npm run dev

# Build the playground
npm run dev:build

# Run ESLint
npm run lint

# Run Vitest
npm run test
npm run test:watch

# Release new version
npm run release