---
name: nuxt-integration
description: Using Pinia with Nuxt - auto-imports, SSR, and best practices
---

# Nuxt Integration

Pinia works seamlessly with Nuxt 3/4, handling SSR, serialization, and XSS protection automatically.

## Installation

```bash
npx nuxi@latest module add pinia
```

This installs both `@pinia/nuxt` and `pinia`. If `pinia` isn't installed, add it manually.

> **npm users:** If you get `ERESOLVE unable to resolve dependency tree`, add to `package.json`:
>
> ```json
> "overrides": { "vue": "latest" }
> ```

## Configuration

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

## Auto Imports

These are automatically available:

- `usePinia()` - get pinia instance
- `defineStore()` - define stores
- `storeToRefs()` - extract reactive refs
- `acceptHMRUpdate()` - HMR support

**All stores in `app/stores/` (Nuxt 4) or `stores/` are auto-imported.**

### Custom Store Directories

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@pinia/nuxt'],
  pinia: {
    storesDirs: ['./stores/**', './custom-folder/stores/**'],
  },
});
```

## Fetching Data in Pages

Use `callOnce()` for SSR-friendly data fetching:

```vue
<script setup>
const store = useStore();

// Run once, data persists across navigations
await callOnce('user', () => store.fetchUser());
</script>
```

### Refetch on Navigation

```vue
<script setup>
const store = useStore();

// Refetch on every navigation (like useFetch)
await callOnce('user', () => store.fetchUser(), { mode: 'navigation' });
</script>
```

## Using Stores Outside Components

In navigation guards, middlewares, or other stores, pass the `pinia` instance:

```ts
// middleware/auth.ts
export default defineNuxtRouteMiddleware((to) => {
  const nuxtApp = useNuxtApp();
  const store = useStore(nuxtApp.$pinia);

  if (to.meta.requiresAuth && !store.isLoggedIn) {
    return navigateTo('/login');
  }
});
```

Most of the time, you don't need this - just use stores in components or other injection-aware contexts.

## Pinia Plugins with Nuxt

Create a Nuxt plugin:

```ts
// plugins/myPiniaPlugin.ts
import { PiniaPluginContext } from 'pinia';

function MyPiniaPlugin({ store }: PiniaPluginContext) {
  store.$subscribe((mutation) => {
    console.log(`[🍍 ${mutation.storeId}]: ${mutation.type}`);
  });
  return { creationTime: new Date() };
}

export default defineNuxtPlugin(({ $pinia }) => {
  $pinia.use(MyPiniaPlugin);
});
```

<!--
Source references:
- https://pinia.vuejs.org/ssr/nuxt.html
-->
