feat: throw when a store is used outside of a Nuxt-aware context.

[pguilbert]

Context

The Pinia documentation states the following:

Make sure all of your useStore() calls appear before any await. Otherwise, this could lead to using the wrong Pinia instance in SSR apps: pinia.vuejs.org/cookbook/composing-stores.html#Shared-Actions

We recently discovered that we had cross-request pollution caused by bad use of Pinia stores after an await in Nuxt. With a large codebase, it was tough to track down every instance of the issue. So, we ended up creating a custom version of defineStore, similar to the one in this PR, to help prevent developers from misusing Pinia stores.

I think it would be useful if this could be implemented directly in the Pinia Nuxt module.

Description of the changes

The Nuxt Pinia module does the following for each request:

// Create the instance for this request
const pinia = createPinia()
// Store the instance within the Nuxt context (mainly for serialization after)
nuxtApp.vueApp.use(pinia)
// Set the Pinia global instance (that will be used by Pinia and is subject to cross-request pollution)
setActivePinia(pinia)

The module also provides a helper usePinia() that retrieves the Pinia instance from the Nuxt context and not from the Pinia global variable. Conveniently, this helper will throw an error if used after an await (outside of a Nuxt-aware context)!

This PR ensures that on the server we always use usePinia() to get the current Pinia instance. By doing so useStore will systematically throw if used after an await on the server (similarly to the useNuxtApp composable)

Breaking change

Server-side, using a store outside a Nuxt-aware context will now result in an error. Previously, it would continue without error, but sometimes, the wrong Pinia instance was used.

Error in dev:

[nuxt] A composable that requires access to the Nuxt instance was called outside of a plugin, Nuxt hook, Nuxt middleware, or Vue setup function

Error in prod:

[nuxt] instance unavailable

Summary by CodeRabbit

• New Features

  • Stores now work reliably in server-side rendering environments with improved context awareness and error handling
  • Enhanced error messages when stores are accessed outside the proper Nuxt context

• Documentation

  • Added example demonstrating store usage patterns in server-side rendering scenarios

• Tests

  • Added test coverage for store behavior across various server-side rendering contexts

[netlify]

✅ Deploy Preview for pinia-playground canceled.

Name	Link
🔨 Latest commit	5cf66cf
🔍 Latest deploy log	https://app.netlify.com/sites/pinia-playground/deploys/6814c644d2bf3400081cf1b7

[netlify]

✅ Deploy Preview for pinia-official canceled.

Name	Link
🔨 Latest commit	fd75a3d
🔍 Latest deploy log	https://app.netlify.com/projects/pinia-official/deploys/6909d71e26d371000805f232

[posva]

Thanks for the PR! Do you have a reproduction of the problem where correctly using the useStore() composable returned by defineStore() doesn't work?

[pguilbert]

Thanks for the PR! Do you have a reproduction of the problem where correctly using the useStore() composable returned by defineStore() doesn't work?

"correctly" no. The purpose of this PR is to ease the detection of incorrect usage. In the current version bad usage of a store after a await will work without warning in low-traffic environments. But, in cases of simultaneous requests, there is a possibility that pinia uses the pinia instance from another request.

I can provide a reproduction if needed, but this is already a documented case:

Make sure all of your useStore() calls appear before any await. Otherwise, this could lead to using the wrong Pinia instance in SSR apps: pinia.vuejs.org/cookbook/composing-stores.html#Shared-Actions

For context: We recently found out that we had cross-request pollution caused by bad use of Pinia in Nuxt. With our large codebase, it was tough to track down every instance of the issue. So, we ended up creating a custom version of defineStore, similar to this one, to help prevent developers from misusing Pinia stores.

(I'll update the PR description with those infos.)

[posva]

Thanks for the great description of the problem! I agree it's a nice addition

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@pinia/nuxt@2857

npm i https://pkg.pr.new/pinia@2857

npm i https://pkg.pr.new/@pinia/testing@2857

commit: 05d6bf7

[codecov]

Codecov Report

Attention: Patch coverage is 0% with 13 lines in your changes missing coverage. Please review.

Project coverage is 87.96%. Comparing base (2071db2) to head (2a0c9ed).

Files with missing lines	Patch %	Lines
packages/nuxt/src/runtime/composables.ts	0.00%	13 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##               v2    #2857      +/-   ##
==========================================
- Coverage   88.75%   87.96%   -0.79%     
==========================================
  Files          19       19              
  Lines        1449     1462      +13     
  Branches      226      226              
==========================================
  Hits         1286     1286              
- Misses        162      175      +13     
  Partials        1        1              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[pguilbert]

Thanks for the great description of the problem! I agree it's a nice addition

Nice! I'll complete the typing and refine the test to move this PR out of draft.

[pguilbert]

@posva what do you think of this version? Could we merge this? 🙏

[posva]

Let's make the error dev only, it shouldn't affect the final bundle. This should be possible by using process.env.NODE_ENV === 'production' ? _defineStore : ... or a similar guard

[pguilbert]

Sorry it took so long; it's done now!

[iPrytz]

Thanks for this @pguilbert ! I think this is a great addition to Pinia. Is this planned to merge any time soon? 😊 @posva

[coderabbitai]

📝 Walkthrough

Walkthrough

Implements SSR-safe store handling by wrapping defineStore to defer store creation to server contexts, adds global __TEST__ TypeScript declaration, includes a playground page demonstrating async store usage patterns, and adds corresponding error handling test cases.

Changes

Cohort / File(s)	Summary
TypeScript Configuration packages/nuxt/tsconfig.json	Added ./global.d.ts to the include array to register global TypeScript declarations.
Global Type Declarations packages/nuxt/global.d.ts	Declared global __TEST__ boolean constant for test environment identification.
Runtime Store Composables packages/nuxt/src/runtime/composables.ts	Enhanced defineStore with SSR-aware wrapper that proxies store instantiation via usePinia() in non-production environments. Updated usePinia return type to Pinia | undefined.
Test Suite packages/nuxt/test/nuxt.spec.ts	Added server-side test case validating error handling when accessing /usage-after-await without Nuxt context.
Playground Demo packages/nuxt/playground/pages/usage-after-await.vue	Created new Vue SFC demonstrating async useFancyCounter composition with error hook registration and server status handling.

Sequence Diagram(s)

sequenceDiagram
    participant Client
    participant Server
    participant defineStore as SSR defineStore
    participant Pinia
    
    alt Non-Production/Test Environment
        Client->>Server: Request store instance
        Server->>defineStore: useStore() called
        defineStore->>defineStore: Check if server context
        defineStore->>Pinia: Defer to usePinia()
        Pinia-->>defineStore: Return Pinia instance
        defineStore->>defineStore: Proxy store creation
        defineStore-->>Server: Return store via wrapper
    else Production Environment
        Client->>defineStore: useStore() called
        defineStore->>Pinia: Direct _defineStore call
        Pinia-->>defineStore: Return store
        defineStore-->>Client: Return store instance
    end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

• packages/nuxt/src/runtime/composables.ts requires careful attention to the SSR-aware wrapper logic, conditional compilation based on environment, and metadata preservation ($id, _pinia properties).
• packages/nuxt/playground/pages/usage-after-await.vue demonstrates the intended usage pattern but interaction with error hooks and async store initialization should be verified.
• Cross-file consistency between the new global declaration, test assertions, and playground usage should be validated.

Poem

🐰 A store that knows when to defer,
Through server realms it gently sways,
With __TEST__ flags to help confer,
And error hooks that light the ways!
SSR safety springs to life,
No more context strife! ✨

🚥 Pre-merge checks | ✅ 2

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: adding an error when a store is used outside Nuxt-aware context.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[posva]

Any way to get rid of this? I don't think we should need this

[posva]

This condition can be probably be moved up so we simply return _defineStore too