nuxt-jsonld

library2.2.1jsnpmunverified

nuxt-jsonld is a specialized Nuxt.js module designed to streamline the integration and management of JSON-LD (Linked Data) within Vue components, primarily for SEO purposes. Currently at version 2.2.1, it provides a developer-friendly API for embedding structured data directly into Nuxt 3 applications. The module maintains an active release cadence, with the latest update in June 2025, focusing on bug fixes and compatibility. Key differentiators include its `useJsonld` composable for Composition API, enabling both static and reactive JSON-LD generation, as well as support for the Options API. It addresses the complexities of server-side rendering (SSR) and static site generation (SSG) for structured data, ensuring proper SEO indexing, unlike manual `useHead` implementations that might require more boilerplate and careful handling of reactivity and deduplication. It also provides explicit handling for Nuxt 2 users via its v1 documentation.

web-framework serialization

npm install nuxt-jsonld

github ↗package ↗

INSTALL

IMPORT

SIG · NUXT-JSONLD

nuxt-jsonld

web-frameworkjavascriptv2.2.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

module registration

✓ export default defineNuxtConfig({ modules: ['nuxt-jsonld'] });

✗ export default { buildModules: ['nuxt-jsonld'] };

For Nuxt 3, modules are registered in `modules` array. `buildModules` was primarily for Nuxt 2.

useJsonld

✓ useJsonld({ '@context': 'https://schema.org', '@type': 'Thing', name: 'My Static Item' });

✗ import { useJsonld } from 'nuxt-jsonld';

The `useJsonld` composable is auto-imported in Nuxt 3, so explicit import is often not required. If needed, import from '#jsonld'.

useJsonld (reactive)

✓ const someData = ref('Initial'); useJsonld(() => ({ '@context': 'https://schema.org', '@type': 'Product', name: `Reactive Product: ${someData.value}` }));

✗ useJsonld({ // ... name: `Reactive Product: ${someData.value}` }); // Object won't react

For reactive JSON-LD, pass a function that returns the JSON-LD object. This ensures reactivity when dependencies change.

This quickstart demonstrates how to set up `nuxt-jsonld` in `nuxt.config.ts` and use the `useJsonld` composable within a Vue component to define both static and reactive JSON-LD structured data.

export default defineNuxtConfig({ modules: ['nuxt-jsonld'], // Optional: Disable Options API mixin if not used // jsonld: { // disableOptionsAPI: true // } });  <template> <div> <h1>My Page with Structured Data</h1> <p>This content is augmented with JSON-LD for SEO.</p> <button @click="updateProductRating">Update Rating</button> </div> </template> <script lang="ts" setup> import { ref } from 'vue'; // useJsonld is auto-imported by Nuxt const productRating = ref(4.5); // Static JSON-LD for the page useJsonld({ '@context': 'https://schema.org', '@type': 'WebPage', 'name': 'Homepage with JSON-LD', 'description': 'A comprehensive page featuring structured data for SEO.' }); // Reactive JSON-LD for a product, updated dynamically const updateProductRating = () => { productRating.value = Math.min(5.0, productRating.value + 0.1); }; useJsonld(() => ({ '@context': 'https://schema.org', '@type': 'Product', 'name': 'Awesome Widget Pro', 'image': 'https://example.com/widget-pro.jpg', 'description': 'The best widget for all your needs.', 'brand': { '@type': 'Brand', 'name': 'WidgetCo' }, 'aggregateRating': { '@type': 'AggregateRating', 'ratingValue': productRating.value.toFixed(1), 'reviewCount': '120' }, 'offers': { '@type': 'Offer', 'priceCurrency': 'USD', 'price': '99.99', 'itemCondition': 'https://schema.org/NewCondition', 'availability': 'https://schema.org/InStock' } })); </script>

Debug

Known issues

breakingWhen migrating from `nuxt-jsonld` v1 (for Nuxt 2) to v2 (for Nuxt 3), the API for defining JSON-LD changes significantly. V2 primarily uses the Composition API's `useJsonld` composable, replacing the Nuxt 2 `head()` method or Options API mixin.

fix

Refer to the v2 documentation for updated usage with `useJsonld` in `<script setup>` or the Options API `jsonld()` method. Ensure `nuxt-jsonld` is added to the `modules` array in `nuxt.config.ts`.

affects: >=2.0.0

breakingThe `children` prop for `script` tags, typically used for injecting content, was changed to `innerHTML` in version 2.1.1 due to updates in underlying meta management. Direct usage of `children` for JSON-LD scripts will no longer work.

fix

Update any manual `script` tag injections or similar patterns to use `innerHTML` instead of `children` for embedding JSON-LD content.

affects: >=2.1.1

gotchaVersion 2.2.0 changed how Vue types are augmented, specifically from `@vue/runtime-core` to `vue`. While often transparent, this could potentially cause TypeScript errors in projects with complex type augmentations or specific tooling setups.

fix

If encountering type-related issues after upgrading, ensure your TypeScript configuration aligns with `vue` module augmentations. You might need to adjust or remove custom type declarations that conflict.

affects: >=2.2.0

gotchaThe module added a `tagPosition` parameter in v2.1.0, allowing JSON-LD script tags to be placed at different positions (e.g., `head`, `bodyOpen`, `bodyClose`). The default position is `head`. Incorrect positioning might affect how search engines parse the structured data in specific scenarios.

fix

If you have specific requirements for JSON-LD script placement, use the `tagPosition` option with `useJsonld`. For example: `useJsonld(data, { tagPosition: 'bodyClose' })`.

affects: >=2.1.0

Errors

Common errors & fixes

Property 'children' does not exist on type 'HeadEntry'.

Attempting to use `children` property for script tag content after `nuxt-jsonld` v2.1.1, which expects `innerHTML`.

fix

Change `children: JSON.stringify(jsonLd)` to `innerHTML: JSON.stringify(jsonLd)`.

Duplicate JSON-LD meta tags are being generated, impacting SEO or page performance.

Older versions of `nuxt-jsonld` (pre-v1.5.7) had a bug that could lead to duplicate meta tag generation, especially in complex page structures or during SSR.

fix

Ensure you are using `nuxt-jsonld` version 1.5.7 or higher. If the issue persists, review your component structure for accidental multiple `useJsonld` calls or conflicts with other meta management libraries.

JSON-LD data is not present in the HTML source code on server-side rendered (SSR) pages or during static site generation (SSG).

Early versions of `nuxt-jsonld` (pre-v1.5.4) had issues generating JSON-LD correctly during SSR, particularly when used with Nuxt Bridge.

fix

Upgrade `nuxt-jsonld` to version 1.5.4 or newer to resolve SSR generation issues. Verify that your JSON-LD data is reactive if it depends on asynchronous data, by passing a function to `useJsonld`.

Upgrade

Version history

2.2.1latest on npm

Audit

Dependencies

nuxtrequiredCore framework dependency as it is a Nuxt module.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/ymmooot/nuxt-jsonld ↗

packagehttps://www.npmjs.com/package/nuxt-jsonld ↗