Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/dvlkit/nuxe/llms.txt

Use this file to discover all available pages before exploring further.

Nuxe provides useState — a composable that creates reactive refs backed by the application payload. State set on the server is automatically serialized into window.__NUXE__ and restored on the client, making it available across components without a separate state management library. Every call with the same key returns the exact same Ref, so components always stay in sync.

​
useState

​
Signature

useState<T>(key: string, init?: () => T): Ref<T>
​
key
string
required
A unique string identifier for this piece of state. The same key always returns the same Ref within an application instance.
​
init
() => T
Optional factory function called once to create the initial value when the key is first registered. Subsequent calls with the same key ignore init and return the existing ref.

​
Example

The recommended pattern is to wrap useState in a dedicated composable so the key string is co-located with its consumers: 
// composables/use-counter.ts
export const useCounter = () => useState('counter', () => 0)

<!-- pages/state.vue -->
<script setup lang="ts">
const count = useCounter()

function increment() {
  count.value++
}
</script>

<template>
  <button @click="increment">{{ count }}</button>
</template>
Any component that calls useCounter() receives the same underlying ref. Updating count.value in one component immediately reflects in all others.

​
SSR and hydration

During server-side rendering, useState stores its value in the server payload under the given key. When the HTML reaches the browser, Nuxe deserializes the payload from window.__NUXE__ and populates the state registry before Vue mounts. The client never starts with a blank slate — the exact server value is available synchronously on first render, preventing hydration mismatches.
1

Server render

useState('counter', () => 0) is called; the initial value 0 is stored in the server payload.
2

HTML is sent

The serialized payload is inlined into the HTML as window.__NUXE__ = { state: { counter: 0 } }.
3

Client hydration

Before Vue mounts, Nuxe reads window.__NUXE__ and restores each state key into its Ref. Components mount with count.value === 0 without re-running the init factory.

​
Error conditions

useState throws in three situations:
  • Key is not a non-empty string — throws TypeError: [nuxe] [useState] key must be a non-empty string.
  • init is provided but is not a function — throws Error: [nuxe] [useState] init must be a function.
  • Called outside a Nuxe context — throws Error: [nuxe] useState() must be called inside a Nuxe plugin or setup function, or inside a runWithContext that has provided an app via provideNuxeApp().
useState must be called inside a Nuxe plugin, a Vue setup function, or a runWithContext block that has provided an app via provideNuxeApp(). Calling it at the module level (outside any context) throws. Similarly, passing a non-string or empty string as key, or a non-function as init, throws immediately.

​
createNuxeState

createNuxeState is a utility for building an initial state object outside of a component. It converts plain values into Refs and is useful for seeding state in plugins or server middleware. 
import { createNuxeState } from '@dvlkit/nuxe'

const state = createNuxeState({
  counter: 0,
  user: { name: 'Guest' },
})
// state.counter === Ref<number>(0)
// state.user    === Ref<{ name: string }>({ name: 'Guest' })
If a value is already a Ref, it is kept as-is.

​
clearNuxeState

clearNuxeState removes entries from the state registry. It is useful in tests, after logout flows, or whenever you need to reset a slice of shared state.

​
Signatures

clearNuxeState()

​
Examples

// Reset a single counter after a user action
function reset() {
  clearNuxeState('counter')
}

// Sign out — remove all user-scoped state at once
function signOut() {
  clearNuxeState(key => key.startsWith('user'))
}

// Tear everything down in a test's afterEach hook
afterEach(() => {
  clearNuxeState()
})
Wrap useState in a named composable (e.g. useCounter) rather than calling it with a raw string in every component. This keeps the key string co-located with the state definition and makes global search-and-replace safe if you need to rename a key.

Build docs developers (and LLMs) love

Get started for freeTalk to us