Nuxt Sanity

https://sanity.nuxtjs.org/
Admin
Nuxt Sanity is a module that provides the easiest way to integrate Sanity with Nuxt, offering a...
Tokens:3,771
Snippets:32
Trust Score:9.9
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install Sanity Integration Module

Source: https://sanity.nuxtjs.org/getting-started/installation

This command installs the Sanity integration module for NuxtJS using the nuxi CLI. It is the first step in setting up Sanity with your Nuxt project.

```bash
npx nuxi@latest module add sanity

```

--------------------------------

### Install @sanity/client for NuxtJS

Source: https://sanity.nuxtjs.org/getting-started/live-content

Installs the necessary Sanity client package for your NuxtJS project. This is a prerequisite for interacting with the Sanity API and enabling live content features.

```bash
pnpm add @sanity/client

```

--------------------------------

### Install @sanity/client for NuxtJS

Source: https://sanity.nuxtjs.org/getting-started/visual-editing

Installs the `@sanity/client` package, which is required for enabling visual editing features in your Nuxt application. This package is essential for interacting with the Sanity API.

```pnpm
pnpm install @sanity/client
```

```npm
npm install @sanity/client --save
```

--------------------------------

### GROQ Helper for Syntax Highlighting and ESLint Rules

Source: https://sanity.nuxtjs.org/helpers/groq

This helper function assists with GROQ syntax highlighting and ESLint rules within the project. It is globally available via auto-imports in both server routes and the Vue app. Ensure the VSCode extension is installed for full functionality.

```javascript
<script>
// In VS Code this will be highlighted
const query = groq`*[_type == "article"][0].title`
</script>

```

--------------------------------

### Configure Sanity Project ID in Nuxt

Source: https://sanity.nuxtjs.org/getting-started/installation

This configuration example demonstrates how to set the Sanity projectId directly within the Nuxt configuration file (`nuxt.config.ts`). Alternatively, configuration can be provided via a separate `sanity.config.ts` file.

```typescript
export default defineNuxtConfig({
  modules: ['@nuxtjs/sanity'],
  sanity: {
    projectId: 'myProject'
  }
})

```

--------------------------------

### Using Global $urlFor Helper (Vue)

Source: https://sanity.nuxtjs.org/helpers/images

Example of using the globally provided `$urlFor` helper within a Vue template to dynamically generate an image source URL from a movie object's image property, applying size transformations.

```html
<template>
  <img
    :src="$urlFor(movie.image).size(426).url()"
    :alt="movie.title"
    height="426"
    width="426"
    loading="lazy"
  />
</template>

```

--------------------------------

### Enable Sanity Module in Nuxt Configuration

Source: https://sanity.nuxtjs.org/getting-started/installation

This code snippet shows how to enable the installed Sanity module within your Nuxt application's configuration file (`nuxt.config.ts`). It adds '@nuxtjs/sanity' to the modules array.

```typescript
export default defineNuxtConfig({
  modules: ['@nuxtjs/sanity']
})

```

--------------------------------

### Configure Custom Components for SanityContent (Vue)

Source: https://sanity.nuxtjs.org/helpers/portable-text

This example shows how to customize the rendering of portable text by providing a 'components' object to the <SanityContent> component. It illustrates defining custom components for different block types (lazyRegisteredComponent, importedComponent, dynamicComponent) and mark types (internalLink). Custom components receive their data via props.value, requiring destructuring.

```vue
<template>
  <SanityContent :value="content" :components="components" />
</template>

<script setup>
import { defineAsyncComponent, h, resolveComponent } from 'vue'
import CustomBlockComponent from '~/components/CustomBlockComponent.vue'

const components = {
  types: {
    // This is how to access a component registered by "@nuxt/components"
    lazyRegisteredComponent: props => h(resolveComponent('LazyCustomSerializer'), {
      ...props.value,
    }),
    // A directly imported component
    importedComponent: props => h(CustomBlockComponent, {
      ...props.value,
    }),
    // Example of a more complex async component
    dynamicComponent: props => h(defineAsyncComponent({
      loadingComponent: () => 'Loading...',
      loader: () => import('~/other/component.vue'),
    }), {
      ...props.value,
    }),
  },
  marks: {
    // Custom marks handling
    internalLink: props => h('a', { href: props.value.href }, props.text)
  }
}
</script>

```

--------------------------------

### Configure NuxtJS for Live Content

Source: https://sanity.nuxtjs.org/getting-started/live-content

Enables and configures the live content feature within your NuxtJS application's configuration file. It requires project ID, dataset, API version, and tokens for live content.

```typescript
// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxtjs/sanity'],
  sanity: {
    projectId: '<your-project-id>',
    dataset: '<your-dataset>',
    apiVersion: '2021-03-25',
    liveContent: {
      browserToken: process.env.NUXT_SANITY_LIVE_BROWSER_TOKEN,
      serverToken: process.env.NUXT_SANITY_LIVE_SERVER_TOKEN,
    },
  },
})

```

--------------------------------

### Perform GROQ Queries with sanity.fetch

Source: https://sanity.nuxtjs.org/getting-started/usage

Use the `fetch` method exposed by the Sanity client obtained via `useSanity` to perform GROQ queries. It returns a Promise and can be typed for specific return structures.

```javascript
<script setup>
const query = groq`{ "articles": *[_type == "article"] }`
const sanity = useSanity()
const { data } = await useAsyncData('articles', () => sanity.fetch(query))
</script>

```

```typescript
<script setup lang="ts">
const query = groq`{ "articles": *[_type == "article"] }`
const sanity = useSanity()
// By default it returns a `Promise<unknown>`,
// but you can customise the type of the return.
const { data } = await useAsyncData('articles', () => sanity.fetch<{ articles: Article[] }>(query))
</script>

```

--------------------------------

### Configure Image URL Builder with Sanity Config

Source: https://sanity.nuxtjs.org/getting-started/usage

Shows how to access the Sanity module's configuration to initialize '@sanity/image-url' builder, enabling image transformations and URL generation for Sanity images.

```javascript
plugins/sanity.ts
```javascript
import imageUrlBuilder from '@sanity/image-url'
export default defineNuxtPlugin(() => {
  const sanity = useSanity()
  const builder = imageUrlBuilder(sanity.config)

  function urlFor(source) {
    return builder.image(source)
  }

  return {
    provide: { urlFor }
  }
})
```
```

--------------------------------

### Configure Visual Editing in NuxtJS Sanity Module

Source: https://sanity.nuxtjs.org/getting-started/visual-editing

Sets up visual editing for the NuxtJS Sanity module by configuring the `sanity.visualEditing` key in `nuxt.config.ts`. This includes specifying the `token` for server-side queries and the `studioUrl` for the Sanity Studio.

```typescript
export default defineNuxtConfig({
  modules: ['@nuxtjs/sanity'],
  sanity: {
    // ... Sanity config
    visualEditing: {
      token: process.env.NUXT_SANITY_VISUAL_EDITING_TOKEN,
      studioUrl: process.env.NUXT_SANITY_VISUAL_EDITING_STUDIO_URL,
    }
  },
})
```

--------------------------------

### Advanced SanityContent Props Configuration (Vue)

Source: https://sanity.nuxtjs.org/helpers/portable-text

This snippet demonstrates advanced configuration for the <SanityContent> component, including passing custom components, defining a handler for missing components, and setting list nesting mode. The 'handleMissingComponent' function logs a warning when a component cannot be found.

```vue
<template>
  <SanityContent 
    :value="content" 
    :components="components"
    :onMissingComponent="handleMissingComponent" 
    :listNestingMode="'html'" 
  />
</template>

<script setup>
const handleMissingComponent = (message, options) => {
  console.warn(`Missing component: ${options.type} (${options.nodeType})`)
}
</script>

```

--------------------------------

### Runtime Configuration for @nuxtjs/sanity

Source: https://sanity.nuxtjs.org/getting-started/configuration

Sets up runtime configuration for the `@nuxtjs/sanity` module, allowing sensitive information like API tokens to be managed via environment variables. The `token` is configured under the `runtimeConfig.sanity` key.

```typescript
export default defineNuxtConfig({
  modules: ['@nuxtjs/sanity'],
  runtimeConfig: {
    sanity: {
      token: process.env.NUXT_SANITY_TOKEN,
    },
  },
  sanity: {
    projectId: 'myProject',
  },
})
```

--------------------------------

### Query Live Content with useSanityQuery in NuxtJS

Source: https://sanity.nuxtjs.org/getting-started/live-content

Demonstrates how to fetch data from Sanity and automatically receive live updates using the `useSanityQuery` composable in a NuxtJS Vue component. The `data` ref updates in real-time.

```vue
<script setup lang="ts">
const { data, refresh, pending, error } = useSanityQuery(
  '*[_type == "post"] | order(_createdAt desc)'
)
</script>

<template>
  <div v-if="data">
    <div v-for="post in data" :key="post._id">
      <h2>{{ post.title }}</h2>
      <p>{{ post.body }}</p>
    </div>
  </div>
</template>

```

--------------------------------

### Configuring Additional Sanity Clients in Nuxt

Source: https://sanity.nuxtjs.org/getting-started/configuration

Demonstrates how to configure multiple Sanity clients within the Nuxt configuration. The `additionalClients` object allows defining named clients with their own `projectId` and other options, which merge with the default client's configuration.

```typescript
export default defineNuxtConfig({
  modules: ['@nuxtjs/sanity'],
  sanity: {
    additionalClients: {
      another: {
        projectId: 'anotherproject',
      },
    },
  },
})
```

--------------------------------

### Sanity Image URL Builder Plugin (JavaScript)

Source: https://sanity.nuxtjs.org/helpers/images

A Nuxt.js plugin for setting up the `@sanity/image-url` package. It creates a global `$urlFor` helper function that uses the Sanity client configuration to build image URLs with specified transformations.

```javascript
import imageUrlBuilder from '@sanity/image-url'

export default defineNuxtPlugin(() => {
  const builder = imageUrlBuilder(useSanity().config)
  function urlFor(source) {
    return builder.image(source).auto('format')
  }
  return {
    provide: { urlFor }
  }
})

```

--------------------------------

### Access Additional Sanity Clients

Source: https://sanity.nuxtjs.org/getting-started/usage

Illustrates how to access and use additional Sanity clients configured within the module by providing a client name to the `useSanity` composable.

```typescript
plugins/fetch.ts
```typescript
export default defineNuxtPlugin(() => {
  const otherSanityHelper = useSanity('other')
  otherSanityHelper.fetch('*[type == "article"][0]')
})
```
```

--------------------------------

### SanityImage Component Usage (Vue)

Source: https://sanity.nuxtjs.org/helpers/images

Demonstrates the basic usage of the global `<SanityImage>` component in a Vue template to render an image with auto-formatting. It takes an `asset-id` and transformation props.

```html
<template>
  <SanityImage
    asset-id="image-G3i4emG6B8JnTmGoN0UjgAp8-300x450-jpg"
    auto="format"
  />
</template>

```

--------------------------------

### SanityImage Renderless Component Usage (Vue)

Source: https://sanity.nuxtjs.org/helpers/images

Shows how to use the `<SanityImage>` component in a renderless manner within a Vue template, utilizing a scoped slot to gain full control over the image rendering with generated URLs.

```html
<template>
  <SanityImage
    asset-id="image-G3i4emG6B8JnTmGoN0UjgAp8-300x450-jpg"
    auto="format"
  >
    <template #default="{ src }">
      <img :src="src" />
    </template>
  </SanityImage>
</template>

```

--------------------------------

### Access Sanity Client with useSanity (Nuxt & Nitro)

Source: https://sanity.nuxtjs.org/getting-started/usage

The useSanity composable provides a Sanity helper/client accessible globally in Nuxt 3 applications and Nitro server routes. It allows for custom data fetching patterns and direct client access.

```javascript
const sanity = useSanity()

// Access the underlying client
const client = sanity.client

// Subscribe to updates
const observable = sanity.client.listen('*[_type == "article"][0].title')
observable.subscribe(event => {
  // Do something
})

```

--------------------------------

### Default Sanity Configuration (sanity.config.ts)

Source: https://sanity.nuxtjs.org/getting-started/configuration

Defines the default Sanity project configuration using `defineConfig`. It specifies the `projectId` and `dataset`. This file is typically located at `~/cms/sanity.config.ts`.

```typescript
import { defineConfig } from 'sanity'

export default defineConfig({
  projectId: '<sample-project-id>',
  dataset: 'production',
  // rest of your configuration
})
```

--------------------------------

### Fetch Sanity Data with useSanityQuery (Nuxt 3)

Source: https://sanity.nuxtjs.org/getting-started/usage

Use useSanityQuery to automatically fetch data from Sanity using GROQ queries. It wraps Nuxt 3's useAsyncData and automatically refetches when ref/computed parameters change. Supports explicit typing of the query result.

```javascript
const query = groq`*[_type == "post" && topic == $topic][0..10]`
const { data, refresh } = useSanityQuery(query, { topic: 'News' })

```

```typescript
// data will be typed as Ref<Post | null>
const query = groq`*[_type == "post" && topic == $topic][0..10]`
const { data, refresh } = useSanityQuery<Post>(query, { topic: 'News' })

```

--------------------------------

### Fetch Sanity Data with useLazySanityQuery (Nuxt Bridge)

Source: https://sanity.nuxtjs.org/getting-started/usage

useLazySanityQuery is an equivalent to useSanityQuery for Nuxt Bridge. It uses useLazyAsyncData under the hood, preventing blocking of client-side navigation. The API is identical to useSanityQuery.

```javascript
const query = groq`*[_type == "post" && topic == $topic][0..10]`
const { data, pending, refresh } = useLazySanityQuery(query, { topic: 'News' })

```

--------------------------------

### Create Sanity Data Attribute for Visual Editing

Source: https://sanity.nuxtjs.org/helpers/groq

When visual editing is enabled in Sanity, this helper function allows manual mapping of component content to its source. It is essential for correctly linking your frontend components to their corresponding Sanity content.

--------------------------------

### Manually Control Live Mode with useSanityLiveMode in NuxtJS

Source: https://sanity.nuxtjs.org/getting-started/live-content

Shows how to manually enable or disable live mode in a NuxtJS application using the `useSanityLiveMode` composable. This is an advanced feature for specific use cases where automatic control is not desired.

```vue
<script setup>
const disable = useSanityLiveMode()
// Call disable() to turn off live mode if needed
</script>

```

--------------------------------

### Nuxt Configuration for @nuxtjs/sanity

Source: https://sanity.nuxtjs.org/getting-started/configuration

Configures the `@nuxtjs/sanity` module within the `nuxt.config.ts` file. It allows specifying `projectId` and `apiVersion` directly. The module is added to the `modules` array.

```typescript
export default defineNuxtConfig({
  modules: ['@nuxtjs/sanity'],
  sanity: {
    projectId: 'myProject',
    apiVersion: '2021-10-18'
  },
})
```

--------------------------------

### SanityFile Component for File URLs (Vue.js)

Source: https://sanity.nuxtjs.org/helpers/files

A Vue.js functional component that generates valid file URLs based on Sanity asset IDs. It supports optional download attributes for direct file downloads, allowing custom filenames. Dependencies include Vue.js and Sanity asset management.

```vue
<template>
  <SanityFile asset-id="file-41773b5c55bc5414ab7554a75eefddf8e2e14524-txt" download="myfile.txt">
    <template #default="{ src }">
      <a :href="src">Click here to read this text file</a>
    </template>
  </SanityFile>
</template>
```

--------------------------------

### Map Component Content to Source with createSanityDataAttribute

Source: https://sanity.nuxtjs.org/helpers/visual-editing

The `createSanityDataAttribute` helper function is used to manually map content within a Vue component to its source in Sanity when visual editing is enabled. It is auto-imported and available globally. This function takes an object with `id`, `type`, and `path` properties to define the mapping.

```html
<template>
  <h1 :data-sanity="createSanityDataAttribute({
    id: 'the-godfather',
    type: 'movie',
    path: 'title',
  })">The Godfather</h1>
</template>

```

--------------------------------

### Render Portable Text with SanityContent Component (Vue)

Source: https://sanity.nuxtjs.org/helpers/portable-text

This snippet demonstrates the basic usage of the <SanityContent> component in a Vue template to render portable text content. It assumes the 'content' data property is available and contains the portable text value. The component directly processes the 'value' prop.

```vue
<template>
  <SanityContent :value="content" />
</template>

```

--------------------------------

### Securely Set Sanity Token in Nuxt Plugin

Source: https://sanity.nuxtjs.org/getting-started/usage

Demonstrates how to securely set the Sanity client token within a Nuxt plugin, typically for server-side requests where the token might be extracted from the request object.

```typescript
plugins/sanity.server.ts
```typescript
export default defineNuxtPlugin((nuxtApp) => {
  const sanity = useSanity()
  const token = getTokenFromReq(nuxtApp.ssrContext.req)
  sanity.setToken(token)
})
```
```
Tokens:
Raw