Next.js integration tutorial
Follow a complete App Router setup for Mosaicora Open Graph images, route metadata, and typed JSON-LD render overrides.
What you will build
A Next.js route that publishes a deterministic Mosaicora image URL and optional JSON-LD values that tell the Mosaicora generator exactly what content to render in the Open Graph image.
Step 1
Add the native App Router helpers to the application that publishes your metadata.
Run the installation command from the root of your Next.js project. The package includes the framework-agnostic Mosaicora core as a dependency.
Install with pnpm
pnpm add @mosaicora/plugin-nextjsExpected result
Step 2
Use the same absolute canonical URL for the page, metadata, and Mosaicora image path.
Resolve the canonical URL from trusted application data. Dynamic route query parameters are preserved in deterministic order, while hash fragments are ignored.
Use fallbackHref when a route can be reached through an alternate URL or when your publishing data needs a stable fallback.
Route values
const siteId = "321cac22d2103fb1660c50bd";
const canonicalUrl =
"https://example.com/products/view?sku=123&campaign=launch";Step 3
Generate matching Open Graph and X/Twitter image metadata with createMosaicoraMetadata.
Spread the helper output into the metadata returned by your route. You can add the page title, description, canonical alternate, and other standard Next.js metadata alongside it.
For dynamic routes, resolve the route data inside generateMetadata and pass the final canonical URL to the helper.
Static App Router metadata
import type { Metadata } from "next";
import { createMosaicoraMetadata } from "@mosaicora/plugin-nextjs";
const canonicalUrl = "https://example.com/products/view?sku=123";
export const metadata: Metadata = {
title: "Example product",
alternates: { canonical: canonicalUrl },
...createMosaicoraMetadata({
siteId: "321cac22d2103fb1660c50bd",
canonicalHref: canonicalUrl,
fallbackHref: canonicalUrl,
alt: "Example product social preview",
}),
};Dynamic route metadata
export async function generateMetadata({ params }): Promise<Metadata> {
const { slug } = await params;
const product = await getProduct(slug);
return {
title: product.title,
description: product.description,
...createMosaicoraMetadata({
siteId: "321cac22d2103fb1660c50bd",
canonicalHref: product.canonicalUrl,
fallbackHref: product.canonicalUrl,
alt: product.title,
}),
};
}Expected result
Step 4
Tell the Mosaicora generator which exact page values to render in the image.
MosaicoraOgJsonLd preserves normal Schema.org fields and adds the typed mosaicora:og v3 block. The override is not a replacement for SEO metadata: it gives the image generator precise content such as the title, description, price, and feature list.
Place the component in the page or a route-specific server component so its values describe the same canonical page as the metadata.
Product JSON-LD override
import { MosaicoraOgJsonLd } from "@mosaicora/plugin-nextjs";
export default function ProductJsonLd() {
return (
<MosaicoraOgJsonLd
schemaType="Product"
name="Example product"
description="A polished preview for every product page."
url="https://example.com/products/view?sku=123"
offers={{
"@type": "Offer",
price: "49",
priceCurrency: "USD",
}}
mosaicoraOg={{
schemaVersion: 3,
semanticValues: {
"content.title": "Example product",
"content.description": "A polished product preview.",
"product.price": "$49",
"product.features": ["Fast setup", "Consistent previews"],
},
}}
/>
);
}Step 5
Confirm the final HTML exposes the image URL and render instructions to crawlers.
Deploy or expose the route at its public canonical URL. Inspect the rendered HTML, then run that URL through the Mosaicora Open Graph Checker.
Check that the canonical URL, og:image, twitter:image, image dimensions, alt text, and mosaicora:og semantic values all describe the same page.
Expected result
Reference
The helper creates stable image addresses from the page identity.
Use the high-level Next.js helpers or the re-exported core primitives.
Help
Keep metadata exports in a Server Component route. Do not move metadata generation into a client component or a browser-only effect.
Normalize one absolute canonical URL and reuse it for alternates, canonicalHref, fallbackHref, and the JSON-LD url field.
Inspect the mosaicora:og semanticValues. Add explicit title, description, price, or feature overrides for the values the generator should render exactly.
Join the waitlist and tell us what your publishing workflow needs.