Nuxt State Management

Nuxt State Management

Share reactive state across components with SSR-safe useState and Pinia store hydration

When to Use

• You need state that persists across navigation without re-fetching (user session, cart, theme)
• You are seeing hydration mismatch errors caused by state divergence between server and client
• You want to use Pinia stores in a Nuxt SSR context with proper server-to-client serialization
• You need to share state between unrelated components without prop-drilling

Instructions

useState — built-in SSR-safe state:

1. Use useState instead of ref for any state that must be consistent between server and client renders. useState is keyed: the same key always returns the same reactive reference:

// composables/useCounter.ts
export const useCounter = () => useState<number>('counter', () => 0);

<!-- pages/index.vue -->
<script setup>
  const counter = useCounter();
</script>
<template>
  <button @click="counter++">{{ counter }}</button>
</template>

2. The second argument to useState is an initializer factory — it runs only once on the server and is never called again on the client (state is transferred via payload):

const user = useState<User | null>('current-user', () => null);

3. Always provide a unique, descriptive key to avoid collisions across different composables:

// Prefer namespaced keys for large apps
const cartItems = useState<CartItem[]>('cart:items', () => []);
const cartTotal = useState<number>('cart:total', () => 0);

4. Reset state on the server-per-request boundary using clearNuxtState — useful for user-specific data:

// plugins/reset-state.ts
export default defineNuxtPlugin(() => {
  addRouteMiddleware(() => {
    clearNuxtState(['cart:items', 'cart:total']);
  });
});

Pinia — structured stores:

5. Install @pinia/nuxt and add it to modules in nuxt.config.ts:

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@pinia/nuxt'],
});

6. Define stores using defineStore — they are auto-imported when placed in stores/ (with imports.dirs configured):

// stores/useAuthStore.ts
export const useAuthStore = defineStore('auth', () => {
  const user = ref<User | null>(null);
  const isAuthenticated = computed(() => !!user.value);

  async function login(credentials: Credentials) {
    user.value = await $fetch('/api/auth/login', { method: 'POST', body: credentials });
  }

  function logout() {
    user.value = null;
  }

  return { user, isAuthenticated, login, logout };
});

7. Hydrate Pinia stores server-side using useAsyncData within the store or in the page:

// Hydrate in page
const authStore = useAuthStore();
await useAsyncData('auth', () => authStore.fetchCurrentUser());

8. Use pinia.state.value in server plugins to initialize store state from server-side sources:

// plugins/init-state.server.ts
export default defineNuxtPlugin(async (nuxtApp) => {
  const authStore = useAuthStore(nuxtApp.$pinia);
  const sessionUser = await getSessionUser(useRequestEvent());
  authStore.user = sessionUser;
});

Details

Why ref causes hydration mismatches:

A plain ref in a composable creates a new reactive instance per component call. During SSR, the server renders with its own instance; on the client, a fresh ref initializes to the default value — causing a mismatch. useState solves this by storing state in Nuxt's SSR payload and rehydrating from it on the client.

useState vs. Pinia:

Concern	useState	Pinia
Simple scalar/object state	Best fit	Overkill
Complex logic, actions, getters	Awkward	Best fit
DevTools time-travel	No	Yes
Plugin ecosystem	None	Rich
SSR safety	Built-in	Requires setup

Serialization requirements:

State transferred via the SSR payload must be JSON-serializable. Do not store class instances, functions, or circular references in useState or Pinia stores. Use plain objects and primitives.

Pinia store persistence (client-only):

Use pinia-plugin-persistedstate for localStorage sync. Mark it client-only to avoid SSR issues:

// plugins/pinia-persist.client.ts
import piniaPluginPersistedstate from 'pinia-plugin-persistedstate';
export default defineNuxtPlugin(({ $pinia }) => {
  $pinia.use(piniaPluginPersistedstate);
});

Avoiding state pollution between requests:

In SSR, all requests share the same module scope. Never use module-level ref or reactive for per-user state — it leaks between requests. Always use useState (keyed per request) or Pinia (reset via $reset() in server middleware).

Source

https://nuxt.com/docs/getting-started/state-management

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.