# Setup

::note
`@nuxtjs/strapi`

 is a 

**client**

 for a Strapi backend. It connects your Nuxt app to a Strapi server that you run and host separately. It does not install, run, or bundle Strapi itself. If you don't have a Strapi server yet, follow the 

[Strapi quick start](https://docs.strapi.io/dev-docs/quick-start){rel=""nofollow""}

 first, then point the 

[`url`](https://strapi.nuxtjs.org/#url)

 option at it.
::

## Installation

Add `@nuxtjs/strapi` module to your project:

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

This will add the module to the `modules` section of your `nuxt.config.ts`. You can then configure it:

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

## Options

Defaults:

```ts
{
  url: process.env.STRAPI_URL || 'http://localhost:1337',
  token: process.env.STRAPI_TOKEN || undefined,
  prefix: '/api',
  admin: '/admin',
  version: 'v5',
  cookie: {},
  cookieName: 'strapi_jwt'
}
```

If you want to override any options on runtime, you may use [Nuxt runtime-config](https://nuxt.com/docs/getting-started/configuration#environment-variables-and-private-tokens){rel=""nofollow""}:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  // Example of separate client/server URLs
  runtimeConfig: {
    strapi: {
      url: 'http://localhost:1337'
    },
    public: {
      strapi: {
        url: 'http://localhost:1337'
      }
    }
  }
})
```

### `url`

URL of the Strapi server.

Environment variable `STRAPI_URL` can be used to override `url`.

### `admin`

Specify admin prefix used by your Strapi.

### `prefix`

Prefix of the Strapi server. Not for version `v3`.

> Learn how to change the default [API prefix](https://docs.strapi.io/developer-docs/latest/setup-deployment-guides/configurations/optional/api.html){rel=""nofollow""} in your Strapi server.

### `version`

Version of the Strapi server. Can only be `v5`/`v4`/`v3`.

### `cookie`

Cookie options of the Strapi token cookie.

> All cookie options can be found in the [Nuxt documentation](https://nuxt.com/docs/api/composables/use-cookie#options){rel=""nofollow""}

### `cookieName`

Cookie name of the Strapi token cookie

### `auth.populate` :u-badge{.align-middle.rounded-full label="v1.5.0+" variant="subtle"} :u-badge{.align-middle.rounded-full label="Strapi v4.2.2+" variant="subtle"}

Configure the `populate` query param of the `/users/me` route.

> Learn more on [Populating documentation](https://docs.strapi.io/developer-docs/latest/developer-resources/database-apis-reference/entity-service/populate.html#advanced-populating){rel=""nofollow""}.

### `auth.fields` :u-badge{.align-middle.rounded-full label="v1.7.0+" variant="subtle"} :u-badge{.align-middle.rounded-full label="Strapi v4.2.2+" variant="subtle"}

Configure the `fields` query param of the `/users/me` route.

> Learn more on [Field Selection documentation](https://docs.strapi.io/developer-docs/latest/developer-resources/database-apis-reference/rest/populating-fields.html#field-selection){rel=""nofollow""}.

### `devtools` :u-badge{.align-middle.rounded-full label="v1.9.0+" variant="subtle"}

Embed the Strapi admin to the [Nuxt Devtools](https://devtools.nuxtjs.org){rel=""nofollow""}, read more in the [Devtools section](https://strapi.nuxtjs.org/devtools).

## Continuous releases

Nuxt Strapi uses [pkg.pr.new](https://github.com/stackblitz-labs/pkg.pr.new){rel=""nofollow""} for continuous preview releases, providing developers with instant access to the latest features and bug fixes without waiting for official releases.

Automatic preview releases are created for all commits and PRs to the `main` branch. Use them by replacing your package version with the specific commit hash or PR number.

```diff [package.json]
{
  "dependencies": {
-   "@nuxtjs/strapi": "^2.1.1",
+   "@nuxtjs/strapi": "https://pkg.pr.new/@nuxtjs/strapi@95260d0",
  }
}
```

::note
**pkg.pr.new**

 will automatically comment on PRs with the installation URL, making it easy to test changes.
::


# Usage

> This module exposes composables that are [auto-imported](https://nuxt.com/docs/guide/directory-structure/composables){rel=""nofollow""} by Nuxt.

## `useStrapi`

Depending on which version you have in your [options](https://strapi.nuxtjs.org/setup#options), you will be using either the v5 (default), v4 or v3 client.

::tip
All examples below are demonstrated with the default v5 `useStrapi()`. :br

:br

Note that v3/v4 expose similar methods with different options. Check out specific types for [v5](https://github.com/nuxt-modules/strapi/blob/main/src/runtime/types/v5.ts){rel=""nofollow""}, [v4](https://github.com/nuxt-modules/strapi/blob/main/src/runtime/types/v4.ts){rel=""nofollow""} or [v3](https://github.com/nuxt-modules/strapi/blob/main/src/runtime/types/v3.ts){rel=""nofollow""}.
::

> Learn how to handle Strapi errors globally by using [nuxt hooks](https://strapi.nuxtjs.org/advanced#errors-handling).

::warning
All examples below are demonstrated with http calls in script setup. However, to handle SSR properly you may want to use 

[useAsyncData](https://strapi.nuxtjs.org/advanced#async-data)

.
::

When using the composable, you can pass in a default data model for all methods.

```ts
const { findOne } = useStrapi<Course>()

// typed to Course
findOne('courses', '123')
```

If you prefer not to use a default data type and want to override the default, you can pass the data model on individual methods as well.

```ts
const { findOne } = useStrapi<Course>()

// typed to SpecialCourse
findOne<SpecialCourse>('courses', '123')
```

### `find`

Get a list of documents. Returns entries matching the query filters (see [parameters](https://docs.strapi.io/cms/api/rest/parameters){rel="&#x22;nofollow&#x22;"} documentation).

- **Arguments:**
  - contentType: `string`
  - params?: [`Strapi5RequestParams`](https://github.com/nuxt-modules/strapi/blob/main/src/runtime/types/v5.ts){rel="&#x22;nofollow&#x22;"}
  - fetchOptions?: [`FetchOptions`](https://github.com/unjs/ofetch/blob/main/src/types.ts#L34){rel="&#x22;nofollow&#x22;"}
- **Returns:** `Promise<Strapi5ResponseMany<T>>`

```vue
<script setup lang="ts">
import type { Restaurant } from '~/types'

const { find } = useStrapi()

const response = await find<Restaurant>('restaurants')
</script>
```

> Check out the Strapi [Get documents](https://docs.strapi.io/cms/api/rest#get-documents){rel="&#x22;nofollow&#x22;"} REST API endpoint.

### `findOne`

Returns a document by `documentId`.

- **Arguments:**
  - contentType: `string`
  - documentId: `string`
  - params?: [`Strapi5RequestParams`](https://github.com/nuxt-modules/strapi/blob/main/src/runtime/types/v5.ts){rel="&#x22;nofollow&#x22;"} (without `filters`)
  - fetchOptions?: [`FetchOptions`](https://github.com/unjs/ofetch/blob/main/src/types.ts#L34){rel="&#x22;nofollow&#x22;"}
- **Returns:** `Promise<Strapi5ResponseSingle<T>>`

```vue
<script setup lang="ts">
import type { Restaurant } from '~/types'

const route = useRoute()
const { findOne } = useStrapi()

const response = await findOne<Restaurant>('restaurants', route.params.id)
</script>
```

> Check out the Strapi [Get a document](https://docs.strapi.io/cms/api/rest#get-a-document){rel="&#x22;nofollow&#x22;"} REST API endpoint.

### `create`

Creates a document and returns its value.

- **Arguments:**
  - contentType: `string`
  - data: `Partial<T>`
  - params?: [`Strapi5RequestParams`](https://github.com/nuxt-modules/strapi/blob/main/src/runtime/types/v5.ts){rel="&#x22;nofollow&#x22;"} (without `filters`)
- **Returns:** `Promise<Strapi5ResponseSingle<T>>`

```vue
<script setup lang="ts">
import type { Restaurant } from '~/types'

const { create } = useStrapi()

const onSubmit = async () => {
  await create<Restaurant>('restaurants', { name: 'My restaurant' })
}
</script>
```

> Check out the Strapi [Create a document](https://docs.strapi.io/cms/api/rest#create-a-document){rel="&#x22;nofollow&#x22;"} REST API endpoint.

### `update`

Partially updates a document by `documentId` and returns its value. Fields that aren't sent in the query are not changed in the database. Send a `null` value if you want to clear them.

- **Arguments:**
  - contentType: `string`
  - documentId: `string`
  - data?: `Partial<T>`
  - params?: [`Strapi5RequestParams`](https://github.com/nuxt-modules/strapi/blob/main/src/runtime/types/v5.ts){rel="&#x22;nofollow&#x22;"} (without `filters`)
- **Returns:** `Promise<Strapi5ResponseSingle<T>>`

```vue
<script setup lang="ts">
import type { Restaurant } from '~/types'

const route = useRoute()
const { update } = useStrapi()

const onSubmit = async () => {
  await update<Restaurant>('restaurants', route.params.id, { name: 'My updated restaurant' })
}
</script>
```

> Check out the Strapi [Update a document](https://docs.strapi.io/cms/api/rest#update-a-document){rel="&#x22;nofollow&#x22;"} REST API endpoint.

### `delete`

Deletes a document by `documentId`. Returns no content (204).

- **Arguments:**
  - contentType: `string`
  - documentId?: `string`
  - params?: `{ locale?: StrapiLocale }`
- **Returns:** `Promise<void>`

```vue
<script setup lang="ts">
const route = useRoute()
const { delete: _delete } = useStrapi()

const onSubmit = async () => {
  await _delete('restaurants', route.params.id)
}
</script>
```

::tip
Pass 

`locale`

 to delete a specific locale version: 

`_delete('restaurants', id, { locale: 'fr' })`
::

> Check out the Strapi [Delete a document](https://docs.strapi.io/cms/api/rest#delete-a-document){rel="&#x22;nofollow&#x22;"} REST API endpoint.

### `count`

Returns the count of entries matching the query filters. You can read more about parameters [here](https://docs-v3.strapi.io/developer-docs/latest/developer-resources/content-api/content-api.html#api-parameters){rel="&#x22;nofollow&#x22;"}.

::warning
Available only for 

`v3`

 as Strapi v4 can do the same thing with the 

[Pagination queries](https://docs.strapi.io/developer-docs/latest/developer-resources/database-apis-reference/rest-api.html#pagination){rel=""nofollow""}

 of the 

`find`

 method.
::

- **Arguments:**
  - contentType: `string`
  - params?: [`Strapi3RequestParams`](https://github.com/nuxt-modules/strapi/blob/main/src/runtime/types/v3.ts#L9){rel="&#x22;nofollow&#x22;"}
- **Returns:** `Promise<number>`

```vue
<script setup lang="ts">
const { count } = useStrapi()

const total = await count('restaurants')
</script>
```

> Check out the Strapi v3 [Count entries](https://docs-v3.strapi.io/developer-docs/latest/developer-resources/content-api/content-api.html#count-entries){rel="&#x22;nofollow&#x22;"} REST API endpoint.

## `useStrapiGraphQL`

This composable is an alias of `useStrapiClient` that sets the `url` to `/graphql` and `method` to `POST`. You can use this method to send an authenticated GraphQL query to your API. See [Use Imported GraphQL](https://strapi.nuxtjs.org/advanced#use-imported-graphql) to use Option 2 below.

- **Arguments:**
  - query: `string|DocumentNode`
  - variables (optional): [`StrapiGraphqlVariables`](https://github.com/nuxt-modules/strapi/blob/main/src/runtime/types/index.ts#L570){rel="&#x22;nofollow&#x22;"}
- **Returns:** `Promise<T>`

```vue
<script setup lang="ts">
const route = useRoute()
const graphql = useStrapiGraphQL()

// Option 1: use inline query
const restaurant = await graphql(`
  query {
    restaurant(documentId: "${route.params.id}") {
      documentId
      name
    }
  }
`)

// Option 2: use imported query
const restaurant = await graphql(query, { id: route.params.id })
</script>
```

## `useStrapiClient`

This composable is a wrapper around [Nuxt `$fetch` helper](https://nuxt.com/docs/api/utils/dollarfetch){rel="&#x22;nofollow&#x22;"} that uses [`ofetch`](https://github.com/unjs/ofetch){rel="&#x22;nofollow&#x22;"} under the hood. You can use this method to reach custom strapi endpoints not available in the `useStrapi` composable.

- **Arguments:**
  - url: `string`
  - fetchOptions?: [`FetchOptions`](https://github.com/unjs/ofetch/blob/main/src/types.ts#L34){rel="&#x22;nofollow&#x22;"}
- **Returns:** `Promise<T>`

```vue
<script setup lang="ts">
import type { Restaurant } from '~/types'

const client = useStrapiClient()

const restaurant = await client<Restaurant>('/restaurants', { method: 'POST', body: { name: 'My restaurant' } })
</script>
```

## `useStrapiUrl`

This composable is an helper to get the strapi url endpoint. It is used internally to reach the api in the `useStrapiClient` composable.

```vue
<script setup>
const url = useStrapiUrl()
</script>
```

## `useStrapiVersion`

This composable is an helper to get version defined in options. It is used internally to compute the `useStrapiUrl` composable.

```vue
<script setup>
const version = useStrapiVersion()
</script>
```

## `useStrapiMedia`

This composable is a helper to get the full URL for media. Strapi endpoints return media URLs as relative paths (e.g. `/uploads/image.png`) on self-hosted instances, or absolute URLs on Strapi Cloud. This composable handles both cases automatically.

```vue
<script setup>
const imageUrl = useStrapiMedia('/uploads/image.png')
</script>
```


# Authentication

> This module exposes composables that are [auto-imported](https://nuxt.com/docs/guide/directory-structure/composables){rel="&#x22;nofollow&#x22;"} by Nuxt.

## Configuration

When using `@nuxtjs/strapi` for authentication, the user jwt token will be stored in a cookie (`strapi_jwt` by default). By using the default cookie configuration, the expiration will be set to `Session`, which means the cookie will disappear when the browser is closed, and users will have to log in everytime.

If you want your cookie to stay longer, we recommend using the configuration below (expiration is set to 14 days, feel free to change it):

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  strapi: {
    cookie: {
      path: '/',
      maxAge: 14 * 24 * 60 * 60,
      secure: process.env.NODE_ENV === 'production',
      sameSite: true
    }
  }
})
```

## `useStrapiUser`

Once logged in, you can access your user everywhere:

```ts
const user = useStrapiUser()
```

> Learn how to protect your routes by writing your own [auth middleware composable](https://strapi.nuxtjs.org/advanced#auth-middleware).

## `useStrapiToken`

This composable is an helper to get the jwt token. It is used internally to get the `strapi_jwt` cookie. If the latter does not exist, this uses the config variable `token`

```ts
const token = useStrapiToken()
```

## `useStrapiAuth`

This composable exposes all the methods available in the Strapi [Users & Permissions plugin](https://docs.strapi.io/developer-docs/latest/plugins/users-permissions.html){rel="&#x22;nofollow&#x22;"}.

::tip
On 

`login`

, 

`register`

, 

`resetPassword`

 and 

`authenticateProvider`

 methods, the user is populated through the 

[`fetchUser`](https://strapi.nuxtjs.org/auth#fetchuser)

 method.
::

### `login`

Submit the user's identifier and password credentials for authentication. Sets [`user`](https://strapi.nuxtjs.org/auth#usestrapiuser) and [`token`](https://strapi.nuxtjs.org/auth#usestrapitoken).

- **Arguments:**
  - data: [`StrapiAuthenticationData`](https://github.com/nuxt-modules/strapi/blob/main/src/runtime/types/index.ts#L538){rel="&#x22;nofollow&#x22;"}
- **Returns:** [`Promise<StrapiAuthenticationResponse>`](https://github.com/nuxt-modules/strapi/blob/main/src/runtime/types/index.ts#L533){rel="&#x22;nofollow&#x22;"}

```vue [pages/login.vue]
<script setup lang="ts">
const { login } = useStrapiAuth()
const router = useRouter()

const onSubmit = async () => {
  try {
    await login({ identifier: '', password: '' })

    router.push('/authenticated-page')
  } catch (e) {}
}
</script>
```

> Check out the Strapi [Login](https://docs.strapi.io/developer-docs/latest/plugins/users-permissions.html#login){rel="&#x22;nofollow&#x22;"} documentation.

### `logout`

Unset [`user`](https://strapi.nuxtjs.org/auth#usestrapiuser) and [`token`](https://strapi.nuxtjs.org/auth#usestrapitoken).

```vue
<script setup lang="ts">
const { logout } = useStrapiAuth()
const router = useRouter()

const onClick = () => {
  logout()

  router.push('/')
}
</script>
```

### `register`

Creates a new user in the database with a default role as `Authenticated`.

Custom user fields, if added to the content type, e.g. `phoneNumber`, can be added to the payload as well.

- **Arguments:**
  - data: [`StrapiRegistrationData`](https://github.com/nuxt-modules/strapi/blob/main/src/runtime/types/index.ts#L543){rel="&#x22;nofollow&#x22;"}
- **Returns:** [`Promise<StrapiAuthenticationResponse>`](https://github.com/nuxt-modules/strapi/blob/main/src/runtime/types/index.ts#L533){rel="&#x22;nofollow&#x22;"}

```vue [pages/register.vue]
<script setup lang="ts">
const { register } = useStrapiAuth()
const router = useRouter()

const onSubmit = async () => {
  try {
    await register({ username: '', email: '', password: '', phoneNumber: '' })

    router.push('/authenticated-page')
  } catch (e) {}
}
</script>
```

> Check out the Strapi [Registration](https://docs.strapi.io/developer-docs/latest/plugins/users-permissions.html#registration){rel="&#x22;nofollow&#x22;"} documentation.

### `forgotPassword`

This action sends an email to a user with the link to your own reset password page. The link will be enriched with the url param code that is needed for the [`resetPassword`](https://strapi.nuxtjs.org/auth#resetpassword).

- **Arguments:**
  - data: [`StrapiForgotPasswordData`](https://github.com/nuxt-modules/strapi/blob/main/src/runtime/types/index.ts#L550){rel="&#x22;nofollow&#x22;"}
- **Returns:** `Promise<void>`

```vue [pages/forgot.vue]
<script setup lang="ts">
const { forgotPassword } = useStrapiAuth()
const router = useRouter()

const onSubmit = async () => {
  try {
    await forgotPassword({ email: '' })

    router.push('/')
  } catch (e) {}
}
</script>
```

> Check out the Strapi [Forgot & Reset flow](https://docs.strapi.io/developer-docs/latest/plugins/users-permissions.html#reset-password){rel="&#x22;nofollow&#x22;"} documentation.

### `resetPassword`

This action will update the user password. Sets [`user`](https://strapi.nuxtjs.org/auth#usestrapiuser) and [`token`](https://strapi.nuxtjs.org/auth#usestrapitoken).

- **Arguments:**
  - data: [`StrapiResetPasswordData`](https://github.com/nuxt-modules/strapi/blob/main/src/runtime/types/index.ts#L554){rel="&#x22;nofollow&#x22;"}
- **Returns:** [`Promise<StrapiAuthenticationResponse>`](https://github.com/nuxt-modules/strapi/blob/main/src/runtime/types/index.ts#L533){rel="&#x22;nofollow&#x22;"}

```vue [pages/reset.vue]
<script setup lang="ts">
const { resetPassword } = useStrapiAuth()
const router = useRouter()

const onSubmit = async () => {
  try {
    await resetPassword({ code: '', password: '', passwordConfirmation: '' })

    router.push('/authenticated-page')
  } catch (e) {}
}
</script>
```

> Check out the Strapi [Forgot & Reset flow](https://docs.strapi.io/developer-docs/latest/plugins/users-permissions.html#reset-password){rel="&#x22;nofollow&#x22;"} documentation.

### `changePassword`

You can also update an authenticated user password through the `/change-password` API endpoint:

- **Arguments:**
  - data: [`StrapiChangePasswordData`](https://github.com/nuxt-modules/strapi/blob/main/src/runtime/types/index.ts#L560){rel="&#x22;nofollow&#x22;"}
- **Returns:** `Promise<void>`

```vue
<script setup lang="ts">
const { changePassword } = useStrapiAuth()

const onSubmit = async () => {
  try {
    await changePassword({ currentPassword: '', password: '', passwordConfirmation: '' })

    $toast.success('Password changed!')
  } catch (e) {}
}
</script>
```

> Check out the Strapi [Change password flow](https://docs.strapi.io/developer-docs/latest/plugins/users-permissions.html#reset-password){rel="&#x22;nofollow&#x22;"} documentation.

### `sendEmailConfirmation`

This action will re-send the confirmation sent after [`registration`](https://strapi.nuxtjs.org/auth#register).

- **Arguments:**
  - data: [`StrapiEmailConfirmationData`](https://github.com/nuxt-modules/strapi/blob/main/src/runtime/types/index.ts#L566){rel="&#x22;nofollow&#x22;"}
- **Returns:** `Promise<void>`

```vue
<script setup lang="ts">
const { sendEmailConfirmation } = useStrapiAuth()

const onSubmit = async () => {
  try {
    await sendEmailConfirmation({ email: '' })

    alert('Success!')
  } catch (e) {}
}
</script>
```

> Check out the Strapi [Email validation](https://docs.strapi.io/developer-docs/latest/plugins/users-permissions.html#email-validation){rel="&#x22;nofollow&#x22;"} documentation.

### `getProviderAuthenticationUrl`

Return the correct URL to authenticate with provider.

- **Arguments:**
  - provider: [`StrapiAuthProvider`](https://github.com/nuxt-modules/strapi/blob/main/src/runtime/types/index.ts#L505){rel="&#x22;nofollow&#x22;"}
- **Returns:** `string`

```vue [pages/login.vue]
<script setup lang="ts">
const { getProviderAuthenticationUrl } = useStrapiAuth()

const onClick = () => {
  window.location.href = getProviderAuthenticationUrl('github')
}
</script>
```

### `authenticateProvider`

Authenticate user with external provider. Sets [`user`](https://strapi.nuxtjs.org/auth#usestrapiuser) and [`token`](https://strapi.nuxtjs.org/auth#usestrapitoken).

- **Arguments:**
  - provider: [`StrapiAuthProvider`](https://github.com/nuxt-modules/strapi/blob/main/src/runtime/types/index.ts#L505){rel="&#x22;nofollow&#x22;"}
  - access\_token: `string`
- **Returns:** [`Promise<StrapiAuthenticationResponse>`](https://github.com/nuxt-modules/strapi/blob/main/src/runtime/types/index.ts#L533){rel="&#x22;nofollow&#x22;"}

```vue [pages/auth/[provider\\]/callback.vue]
<script setup lang="ts">
const { authenticateProvider } = useStrapiAuth()
const route = useRoute()

await authenticateProvider('github', route.query.access_token)
</script>
```

### `fetchUser`

Fetch `me` user from `/users/me` route if a [`token`](https://strapi.nuxtjs.org/auth#usestrapitoken) exists in the cookies then sets [`user`](https://strapi.nuxtjs.org/auth#usestrapiuser).

::tip
This method is called on the server-side only and the data are hydrated client-side so the HTTP call happens only once. This method is called by default on init through a 

[Nuxt plugin](https://nuxt.com/docs/guide/directory-structure/plugins){rel=""nofollow""}

, so you don't have to.
::

```vue
<script setup lang="ts">
const { fetchUser } = useStrapiAuth()

const user = await fetchUser()
</script>
```

> Learn how to populate relations in [`/users/me` route](https://strapi.nuxtjs.org/setup#authpopulate).


# Advanced

## Async data

To take full advantage of server-side rendering, you can use Nuxt [useAsyncData](https://nuxt.com/docs/getting-started/data-fetching){rel="&#x22;nofollow&#x22;"} composable:

```vue
<script setup lang="ts">
import type { Restaurant } from '~/types'

const route = useRoute()
const { findOne } = useStrapi()

const { data, pending, refresh, error } = await useAsyncData(
  'restaurant',
  () => findOne<Restaurant>('restaurants', route.params.id)
)
</script>
```

## Server-Specific Configuration

You can apply configuration based on whether a request is processed on the browser or server by using Nuxt [runtimeConfig](https://nuxt.com/docs/getting-started/configuration#environment-variables-and-private-tokens){rel="&#x22;nofollow&#x22;"}. Options provided directly over `runtimeConfig` field will override options provided in the `strapi` field of Nuxt configuration.

```ts
export default defineNuxtConfig({
  // ...
  runtimeConfig: {
    strapi: { // nuxt/strapi options available server-side
      url: 'http://example-strapi-instance:1337'
    },
    public: {
      strapi: { // nuxt/strapi options available client-side
        url: 'https://strapi.example.com'
      }
    }
  },
  // nuxt/strapi options available on both client and server
  strapi: {
    prefix: '/api'
  }
  // ...
})
```

## Auth middleware

You can protect your authenticated routes by creating a [custom middleware](https://nuxt.com/docs/guide/directory-structure/middleware){rel="&#x22;nofollow&#x22;"} in your project, here is an example:

```ts [middleware/auth.ts]
export default defineNuxtRouteMiddleware((to, _from) => {
  const user = useStrapiUser()
  if (!user.value) {
    useCookie('redirect', { path: '/' }).value = to.fullPath
    return navigateTo('/login')
  }
})
```

Don't forget to reference your middleware in your page with:

```ts [pages/my-page.vue]
definePageMeta({
  middleware: 'auth'
})
```

## Errors handling

You can use the nuxt `strapi:error` hook to display a toast for example (the following example assumes that a `$toast` plugin has been injected).

Here are examples for both `v5`/`v4` and `v3` as the signature between both versions is different.

> Learn how to change the version in the [options](https://strapi.nuxtjs.org/setup#options).

### `v5`/`v4`

```ts [plugins/strapi.client.ts]
import type { Strapi5Error } from '@nuxtjs/strapi'

export default defineNuxtPlugin((nuxt) => {
  nuxt.hook('strapi:error' as any, (e: Strapi5Error) => {
    nuxt.$toast.error({ title: e.error.name, description: e.error.message })
  })
})
```

> Check out the [Strapi5Error](https://github.com/nuxt-modules/strapi/blob/main/src/runtime/types/v5.ts#L3){rel="&#x22;nofollow&#x22;"} or [Strapi4Error](https://github.com/nuxt-modules/strapi/blob/main/src/runtime/types/v4.ts#L3){rel="&#x22;nofollow&#x22;"} type.

### `v3`

```ts [plugins/strapi.client.ts]
import type { Strapi3Error } from '@nuxtjs/strapi'

export default defineNuxtPlugin((nuxt) => {
  nuxt.hook('strapi:error' as any, (e: Strapi3Error) => {
    let description
    if (Array.isArray(e.message)) {
      description = e.message[0].messages[0].message
    } else if (typeof e.message === 'object' && e.message !== null) {
      description = e.message.message
    } else {
      description = e.message
    }

    nuxt.$toast.error({ title: e.error, description })
  })
})
```

> Check out the [Strapi3Error](https://github.com/nuxt-modules/strapi/blob/main/src/runtime/types/v3.ts#L3){rel="&#x22;nofollow&#x22;"} type.

## Override Strapi `/users/me` route

::tip
Since 

[v1.5.0](https://github.com/nuxt-modules/strapi/releases/tag/v1.5.0){rel=""nofollow""}

 and Strapi 

[v4.2.2](https://github.com/strapi/strapi/releases/tag/v4.2.2){rel=""nofollow""}

, you can use the 

[`auth.populate`](https://strapi.nuxtjs.org/setup#authpopulate)

 option to populate data from 

`/users/me`

 route.
::

By default, when calling `/users/me` route, Strapi only returns the user populated with the role. Strapi `User.me` controller from the `users-permissions` plugin returns the `ctx.state.user` populated by the `fetchAuthenticated` method.

Here is how to override this method for both Strapi v3 and v4 by adding our own custom relation, in this example `restaurants`:

### `v5`/`v4`

```js [src/index.js]
module.exports = {
  register ({ strapi }) {
    strapi.service('plugin::users-permissions.user').fetchAuthenticatedUser = (id) => {
      return strapi
        .query('plugin::users-permissions.user')
        .findOne({ where: { id }, populate: ['role', 'restaurants'] })
    }
  }
}
```

> Note that in Strapi v4/v5, you must enable the `restaurants.find` permission in your admin for the Authenticated role to have the data populated.

### `v3`

```js [extensions/users-permissions/services/User.js]
module.exports = {
  fetchAuthenticatedUser(id) {
    return strapi.query('user', 'users-permissions').findOne({ id }, ['role', 'restaurants'])
  }
}
```

## File upload

On `create` and `update` routes, thanks to the [Upload plugin](https://docs.strapi.io/developer-docs/latest/plugins/upload.html#upload-files-related-to-an-entry){rel="&#x22;nofollow&#x22;"} Strapi lets you upload files related to an entry. To do so, you'll have to send a `FormData`.

Here is an example on how to upload an `avatar` file while creating a new entry in `restaurants`:

```vue
<script setup lang="ts">
import type { Restaurant } from '~/types'

const avatar = ref(null)
const form = reactive({ ... })

const client = useStrapiClient()

async function onSubmit () {
  try {
    const formData = new FormData()
    formData.append('files.avatar', avatar)
    formData.append('data', JSON.stringify(form))

    const { data } = await client<Restaurant>(`/restaurants`, {
      method: 'POST',
      body: formData
    })
  } catch (e) { }
}
</script>
```

> Note that you have to use the `client` because `create` and `update` methods sends the [body inside `data`](https://github.com/nuxt-modules/strapi/blob/main/src/runtime/composables/useStrapi4.ts#L64){rel="&#x22;nofollow&#x22;"}.

## Use Imported GraphQL

You can use an imported GraphQL query with the [useStrapiGraphQL composable](https://strapi.nuxtjs.org/usage#usestrapigraphql). To process imported GraphQL, you'll need to provide plugin for processing. An example setup with [@rollup/plugin-graphql](https://www.npmjs.com/package/@rollup/plugin-graphql){rel="&#x22;nofollow&#x22;"} is shown below:

```ts [nuxt.config.ts]
import gql from "@rollup/plugin-graphql"

export default defineNuxtConfig({
    // ...
    vite: {
        plugins: [ gql() ]
    }
})
```

You can now import a query like so:

> Arguments on an imported GraphQL file [must be defined on the query](https://graphql.org/graphql-js/passing-arguments/){rel="&#x22;nofollow&#x22;"} to be passed from the client.

```vue
<script setup lang="ts">
import query from "./query/example-query.gql"
const route = useRoute()
const graphql = useStrapiGraphQL()

const restaurant = await graphql(query, { id: route.params.id })
</script>
```

If importing a GraphQL query from TypeScript, you may encounter an error: "Cannot find module './query/example-query.gql' or its corresponding type declarations". You can resolve this error by creating a type declaration file within your project with the following contents:

```ts [globals.d.ts]
declare module '*.gql' {
    import { DocumentNode } from 'graphql'
    const Schema: DocumentNode
    export = Schema
}
```


# Nuxt Devtools

![Strapi in Nuxt Devtools](https://user-images.githubusercontent.com/904724/222923164-f4f13177-7582-4581-a88e-0256c0789c9d.png)

## Setup :u-badge{.align-middle.rounded-full label="v1.9.0+" variant="subtle"}

Strapi uses [helmet](https://helmetjs.github.io/){rel="&#x22;nofollow&#x22;"} as [security middleware](https://github.com/strapi/strapi/blob/main/packages/core/strapi/lib/middlewares/security.js){rel="&#x22;nofollow&#x22;"}.

By default, it sets the `Content Security Policy` directive to `frame-ancestors 'self'`. Making it impossible to embed the admin on localhost.

To enable the embedding of Strapi Admin, open the `config/middlewares.js` file in your Strapi project and update the `strapi::security` middleware:

```diff [config/middlewares.js]
module.exports = [
  'strapi::errors',
- 'strapi::security',
+ {
+   name: 'strapi::security',
+   config: {
+     contentSecurityPolicy: {
+       directives: {
+         frameAncestors: ['http://localhost:*', 'self']
+       }
+     }
+   }
+ },
  'strapi::cors',
  'strapi::poweredBy',
  'strapi::logger',
  'strapi::query',
  'strapi::body',
  'strapi::session',
  'strapi::favicon',
  'strapi::public'
]
```

Restart your Strapi server and it should be ready to be embedded in the devtools.

Open your `nuxt.config.ts` and set the `devtools` option to `true`:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  strapi: {
    devtools: true
  }
})
```

::tip
You should now see your Strapi Admin right into your Nuxt project by opening the devtools ✨
::


# Strapi integration for Nuxt

::u-page-hero
---
links:
  - label: Get started
    to: /setup
    trailingIcon: i-lucide-arrow-right
  - label: Star on GitHub
    to: https://github.com/nuxt-modules/strapi
    target: _blank
    icon: i-simple-icons-github
    color: neutral
    variant: subtle
orientation: horizontal
---
```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxtjs/strapi'],
  strapi: {
    version: 'v5',
    prefix: '/api'
  }
})
```

#title
Nuxt [Strapi]{.text-primary}

#description
Nuxt module for first class integration with the Strapi CMS.
::

::u-page-section
#title
Shipped with many features.

#features
  :::u-page-feature
  ---
  icon: i-simple-icons-nuxtdotjs
  ---
  #title{unwrap="p"}
  Nuxt Ready

  #description{unwrap="p"}
  Leverage our auto-imported [composables](https://strapi.nuxtjs.org/usage) and our [devtools](https://strapi.nuxtjs.org/devtools) integration.
  :::

  :::u-page-feature
  ---
  icon: i-simple-icons-strapi
  ---
  #title{unwrap="p"}
  Strapi v5/v4/v3

  #description{unwrap="p"}
  Works with the different versions of Strapi.
  :::

  :::u-page-feature
  ---
  icon: i-lucide-lock
  ---
  #title{unwrap="p"}
  Authentication

  #description{unwrap="p"}
  Leverage [`useStrapiUser`](https://strapi.nuxtjs.org/auth) composable to bring auth to your app.
  :::

  :::u-page-feature
  ---
  icon: i-lucide-server-cog
  ---
  #title{unwrap="p"}
  RESTful

  #description{unwrap="p"}
  Interact with all the HTTP methods to your Strapi API.
  :::

  :::u-page-feature
  ---
  icon: i-lucide-bug
  ---
  #title{unwrap="p"}
  Error Handling

  #description{unwrap="p"}
  Handle errors with our [hooks](https://strapi.nuxtjs.org/advanced#errors-handling) to provide a great UX.
  :::

  :::u-page-feature
  ---
  icon: i-simple-icons-typescript
  ---
  #title{unwrap="p"}
  TypeScript Support

  #description{unwrap="p"}
  Our composables support types augmentation.
  :::
::