nuxt-jsonld

If you want to prevent a JSON-LD tag from being rendered under certain conditions (e.g., when data is missing), simply return null from your useJsonld call.

<script lang="ts" setup>
useJsonld(() => {
  if (!props.product) {
    return null;
  }
  return {
    '@context': 'https://schema.org',
    '@type': 'Product',
    name: props.product.name,
  };
});
</script>

nuxt-jsonld is a Nuxt module designed to manage JSON-LD structured data directly within Vue components. It is compatible with both Nuxt 3 and Nuxt 4.

If you are using Nuxt 2, please refer to the legacy documentation at https://github.com/ymmooot/nuxt-jsonld/blob/v1/README.md.

You can install nuxt-jsonld using the Nuxt CLI, which automatically registers the module in your nuxt.config.ts:

$ npx nuxi module add nuxt-jsonld

Alternatively, you can install it manually using your preferred package manager and add it to the modules array in nuxt.config.ts:

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['nuxt-jsonld'],
});

Since the Options API jsonld method is implemented using a global mixin, you can disable it in your nuxt.config.ts if you only intend to use the Composition API. This is useful for reducing overhead if the feature is unused.

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['nuxt-jsonld'],
  'nuxt-jsonld': { disableOptionsAPI: true },
});

// Or using the array syntax:
export default defineNuxtConfig({
  modules: [['nuxt-jsonld', { disableOptionsAPI: true }]],
});

In the Options API, you can define a jsonld() method in your Vue component. This method should return the structured data object. This feature is implemented via a global mixin.

<script lang="ts">
import type { WithContext, BreadcrumbList } from 'schema-dts';

export default defineComponent({
  data() {
    return {
      breadcrumbs: [
        { url: 'https://example.com', text: 'top page' },
      ],
    };
  },
  jsonld(): WithContext<BreadcrumbList> {
    return {
      '@context': 'https://schema.org',
      '@type': 'BreadcrumbList',
      itemListElement: this.breadcrumbs.map((item, index) => ({
        '@type': 'ListItem',
        position: index + 1,
        item: {
          '@id': item.url,
          name: item.text,
        },
      })),
    };
  },
});
</script>

The nuxt-jsonld module can be configured in your nuxt.config.ts using the nuxt-jsonld key. The primary configuration option is disableOptionsAPI.

If disableOptionsAPI is set to true, the module will not register the plugin that enables the Options API usage (e.g., using jsonld as a component option).

export interface ModuleOptions {
  disableOptionsAPI: boolean;
}

// Example usage in nuxt.config.ts:
export default defineNuxtConfig({
  modules: ['nuxt-jsonld'],
  nuxtJsonld: {
    disableOptionsAPI: true
  }
});

The useJsonld composable accepts an optional options object of type UseJsonldOptions. This object allows you to pass configuration directly to the underlying useHead call. Currently, it supports the tagPosition option from @unhead/vue.

import { useJsonld } from 'nuxt-jsonld';

useJsonld(myJsonData, {
  tagPosition: 'bodyToEnd'
});

The useJsonld composable allows you to inject JSON-LD structured data into your Vue components. It automatically handles the creation of a <script type="application/ld+json"> tag using @unhead/vue.

You can pass either a static JSON object or a function that returns a JSON object. Using a function allows the JSON-LD to be reactive, updating whenever the function's internal dependencies change.

import { useJsonld } from 'nuxt-jsonld';

// Using a static object
useJsonld({
  '@context': 'https://schema.org',
  '@type': 'WebSite',
  'name': 'My Site'
});

// Using a function for reactivity
useJsonld(() => ({
  '@context': 'https://schema.org',
  '@type': 'Product',
  'name': props.productName
}));

By default, nuxt-jsonld allows you to provide JSON-LD data directly as a component option named jsonld. This is enabled unless disableOptionsAPI is set to true in your module configuration.

Note: This feature extends the ComponentCustomOptions interface in Vue.

<script>
export default {
  jsonld: {
    '@context': 'https://schema.org',
    '@type': 'Article',
    // ... other properties
  }
}
</script>

The module automatically provides the useJsonld composable, which can be imported and used within your Vue components to manage JSON-LD data.

// useJsonld is auto-imported by the module
const { setJsonld } = useJsonld();

setJsonld({
  '@context': 'https://schema.org',
  '@type': 'WebPage',
  // ... other properties
});