Run & review this pull request in StackBlitz Codeflow.

Walkthrough

The changes refactor Nuxt's state management system by introducing a new internal metadata storage mechanism (_state on the Nuxt app instance) to track per-key state and default functions. The useState composable is updated to accept a UseStateOptions<T> type for initialization and returns a computed reference that proxies to this internal storage. The clearNuxtState function gains an optional reset parameter and delegates per-key clearing logic to a new clearNuxtStateByKey helper, which handles both payload removal and state reset to initial or undefined values. Comprehensive test coverage has been added to validate state lifecycle, reset semantics, and payload synchronisation.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

The changes introduce new initialisation logic and internal state storage mechanisms in state.ts with modified public API signatures. Whilst the structural changes are localised to a single primary file and the logic is reasonably focused, the interplay between metadata storage, hydration, and reset behaviour requires careful reasoning. The addition of a new helper function and the introduction of the _state field in nuxt.ts add moderate complexity. The test additions are largely homogeneous patterns testing reset and removal scenarios, which reduces overall review effort. The heterogeneous nature of the logic changes (new storage pattern, computed reference behaviour, reset semantics) necessitates separate reasoning for key sections.

Pre-merge checks and finishing touches

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

CodSpeed Performance Report

Merging #33527 will not alter performance

_{Comparing Harm-Nullix:reset-to-init-useState (e7b2a3b) with main (b7ed1d3)¹}

Summary

✅ 10 untouched

Open in StackBlitz

npm i https://pkg.pr.new/@nuxt/kit@33527

npm i https://pkg.pr.new/nuxt@33527

npm i https://pkg.pr.new/@nuxt/rspack-builder@33527

npm i https://pkg.pr.new/@nuxt/schema@33527

npm i https://pkg.pr.new/@nuxt/vite-builder@33527

npm i https://pkg.pr.new/@nuxt/webpack-builder@33527

commit: e7b2a3b

Quick example addition:

<script setup lang="ts">
import { useState } from '#app'

const stateWithoutKeyAndInit = useState<number | undefined>()
const stateWithKeyWithoutInit = useState<number | undefined>('WithKeyWithoutInit')
const stateWithoutKeyWithInit = useState<any>(() => ({
  spamm: 'eggs',
  green: 'ham',
  value: 1,
}))
const stateWithKeyWithInit = useState<any>('WithKeyWithInit', () => ({
  spamm: 'eggs',
  green: 'ham',
  value: 1,
}))

const resetState = (keys?: string | string[]) => {
  clearNuxtState(keys)
}
const reload = () => window.location.reload()

const state1 = useState('key', () => ref({
  test: 1,
}))
const state2 = useState('key', () => ref({
  test: 2,
}))
console.debug('state1.value :: ', state1.value.test)
console.debug('state2.value :: ', state2.value.test)
state1.value.test = 3
</script>

<template>
  <!-- Edit this file to play around with Nuxt but never commit changes! -->
  <div>
    Nuxt Playground

    <button @click="resetState()">
      Reset state
    </button>
    <button @click="reloadNuxtApp()">
      reload nuxt app
    </button>
    <button @click="reload()">
      reload window
    </button>
  </div>
  <div>
    <ul>
      <li>
        stateWithoutKeyAndInit :: {{ stateWithoutKeyAndInit }}
        <button @click="stateWithoutKeyAndInit = stateWithoutKeyAndInit ? stateWithoutKeyAndInit + 1 :1 ">
          set state
        </button>
      </li>
      <li>
        stateWithKeyWithoutInit :: {{ stateWithKeyWithoutInit }}
        <button @click="stateWithKeyWithoutInit = stateWithKeyWithoutInit ? stateWithKeyWithoutInit + 1 :1 ">
          set state
        </button>
      </li>
      <li>
        stateWithoutKeyWithInit :: {{ stateWithoutKeyWithInit }} <button @click="stateWithoutKeyWithInit.value += 1">
          set state
        </button>
      </li>
      <li>
        stateWithKeyWithInit :: {{ stateWithKeyWithInit }} <button @click="stateWithKeyWithInit.value += 1">
          set state
        </button>
      </li>
    </ul>

    {{ state1 }}. -- <br><br><br>
    {{ state2 }}
  </div>
</template>

<style scoped>

</style>

I think that it can be really confusing for users and quite hard to debug if there's multiple useState that retuns differents default values

I agree,
That is how states currently work right?
If you use a key twice, the second useState will just return the current payload of the first useState.

E.g. asyncData has the same logic: When you use asyncData with a default value, and the same key is used based on the url, you will get a other default value (or the current transformed value) from the other component that makes the same call, and not your own default.

You can tackle this by creating a composable around your useState as recommended that would be in charge of this specific key.

I think it is a valid point about data storage and the keys that are being used, I've come across this myself while useing UseFetch with autokeys, but I also think that topic is too brought to pick up in such a change as this, wouldn't you agree?

So what is next?
I am a bit lost in what to do with this now.
I feel like I made a clear case to at least discus.

• I am not certain of how the PR flow goes (beyond the defaults)

Yes that's just how it currently works with useAsyncData.
I think we can move on with this PR. I'll trigger a discussion with the team but this is probably the best solution.