@od-oneapp/seo 2026.1.1301

package/src/examples/nextjs-15-features.tsx

@@ -0,0 +1,383 @@
+/**
+ * @fileoverview Next.js 15 SEO Features Comprehensive Example
+ * @module @repo/seo/examples/nextjs-15-features
+ *
+ * This example demonstrates all the enhanced Next.js 15 SEO features
+ * provided by the @repo/seo package, including:
+ *
+ * - Optimized JsonLd components with Script strategy
+ * - Streaming-compatible structured data
+ * - Metadata templates for common patterns
+ * - Dynamic viewport configuration
+ * - Multi-language sitemap generation
+ * - Preview mode metadata handling
+ * - Edge-compatible metadata generation
+ *
+ * @example
+ * // Import the features you need
+ * import { OptimizedJsonLd, metadataTemplates } from '@repo/seo/client/next';
+ * import { generateMetadataAsync, generateI18nSitemap } from '@repo/seo/server/next';
+ */
+
+// ============================================
+// CLIENT-SIDE EXAMPLES (client-next.tsx)
+// ============================================
+
+// ============================================
+// SERVER-SIDE EXAMPLES (server-next.ts)
+// ============================================
+import { type Metadata } from 'next';
+
+import { type Product, type WithContext } from 'schema-dts';
+
+import { OptimizedJsonLd, StreamingJsonLd, useOpenGraphPreview } from '../client-next';
+import {
+  generateI18nSitemap,
+  generateMetadataAsync,
+  generateMetadataEdge,
+  generatePreviewMetadata,
+  generateViewport,
+  metadataTemplates,
+  SEOManager,
+  viewportPresets,
+} from '../server-next';
+
+/**
+ * Example: Optimized JsonLd with Next.js Script component
+ * This provides better performance by controlling when the script loads
+ */
+export function ProductPageWithOptimizedSEO({ product }: { product: any }) {
+  const structuredData: WithContext<Product> = {
+    '@context': 'https://schema.org',
+    '@type': 'Product',
+    name: product.name,
+    description: product.description,
+    image: product.images,
+    offers: {
+      '@type': 'Offer',
+      price: product.price,
+      priceCurrency: product.currency,
+      availability: product.inStock
+        ? 'https://schema.org/InStock'
+        : 'https://schema.org/OutOfStock',
+    },
+  };
+
+  return (
+    <>
+      <OptimizedJsonLd data={structuredData} id="product-data" strategy="afterInteractive" />
+
+      <OptimizedJsonLd
+        data={structuredData}
+        id="critical-product-data"
+        strategy="beforeInteractive"
+      />
+    </>
+  );
+}
+
+/**
+ * Example: Streaming JsonLd for React Server Components
+ * Perfect for async data that needs SEO optimization
+ */
+export function StreamingProductPage({ productId }: { productId: string }) {
+  // This could be a fetch from your database
+  const productPromise = (async () => {
+    const res = await fetch(`/api/products/${productId}`);
+    const product = await res.json();
+    return {
+      '@context': 'https://schema.org',
+      '@type': 'Product',
+      name: product.name,
+      description: product.description,
+    } as WithContext<Product>;
+  })();
+
+  const fallbackData: WithContext<Product> = {
+    '@context': 'https://schema.org',
+    '@type': 'Product',
+    name: 'Loading...',
+    description: 'Product information is loading',
+  };
+
+  return (
+    <StreamingJsonLd dataPromise={productPromise} fallback={fallbackData} id="streaming-product" />
+  );
+}
+
+/**
+ * Example: Dynamic Open Graph Preview Hook
+ * Useful for content editors or preview modes
+ */
+export function ContentEditor() {
+  const { preview, updatePreview, generatePreviewHtml } = useOpenGraphPreview({
+    title: 'My Article',
+    description: 'Article description',
+    image: '/images/article-hero.jpg',
+    url: 'https://example.com/article',
+  });
+
+  return (
+    <div>
+      <h2>SEO Preview</h2>
+      <input
+        placeholder="Title"
+        value={preview.title}
+        onChange={(e: any) => updatePreview({ title: e.target.value })}
+      />
+      <textarea
+        placeholder="Description"
+        value={preview.description}
+        onChange={(e: any) => updatePreview({ description: e.target.value })}
+      />
+      <div>
+        <h3>Generated Meta Tags:</h3>
+        <pre>{generatePreviewHtml}</pre>
+      </div>
+    </div>
+  );
+}
+
+/**
+ * Example: Using metadata templates for a product page
+ */
+export async function generateMetadata({ params }: { params: { id: string } }) {
+  const product = await getProduct(params.id);
+
+  return metadataTemplates.product({
+    name: product.name,
+    description: product.description,
+    price: product.price,
+    currency: 'USD',
+    image: product.image,
+    availability: product.inStock ? 'InStock' : 'OutOfStock',
+    brand: product.brand,
+  });
+}
+
+/**
+ * Example: Article metadata with author and publishing info
+ */
+export function ArticleMetadata({ article }: { article: any }): Metadata {
+  return metadataTemplates.article({
+    title: article.title,
+    description: article.excerpt,
+    author: article.author.name,
+    publishedTime: new Date(article.publishedAt),
+    modifiedTime: article.updatedAt ? new Date(article.updatedAt) : undefined,
+    image: article.featuredImage,
+    tags: article.tags,
+    section: article.category,
+  });
+}
+
+/**
+ * Example: User profile metadata
+ */
+export function ProfileMetadata({ user }: { user: any }): Metadata {
+  return metadataTemplates.profile({
+    name: user.displayName,
+    bio: user.bio,
+    image: user.avatar,
+    username: user.username,
+    firstName: user.firstName,
+    lastName: user.lastName,
+  });
+}
+
+/**
+ * Example: Dynamic viewport based on user agent
+ */
+export function generateDynamicViewport(request: any) {
+  const userAgent = request.headers.get('user-agent') ?? '';
+  return generateViewport(userAgent);
+}
+
+/**
+ * Example: Using viewport presets
+ */
+export const viewportExamples = {
+  // Default responsive viewport
+  default: viewportPresets.default,
+
+  // Mobile app that shouldn't zoom
+  mobileApp: viewportPresets.mobileOptimized,
+
+  // Content-heavy tablet site
+  tablet: viewportPresets.tablet,
+
+  // Desktop-first application
+  desktop: viewportPresets.desktop,
+};
+
+/**
+ * Example: Multi-language sitemap generation
+ */
+export async function generateMultiLangSitemap() {
+  const products = await getProducts();
+  const locales = ['en', 'es', 'fr', 'de'];
+  const baseUrl = 'https://example.com';
+
+  const routes = products.map((product: any) => ({
+    url: `${baseUrl}/products/${product.slug}`,
+    lastModified: product.updatedAt,
+    changeFrequency: 'daily' as const,
+    priority: 0.8,
+  }));
+
+  return generateI18nSitemap(routes, locales, 'en');
+}
+
+/**
+ * Example: Preview mode metadata
+ */
+export function DraftPageMetadata({ isDraft, page }: { isDraft: boolean; page: any }) {
+  const baseMetadata: Metadata = {
+    title: page.title,
+    description: page.description,
+  };
+
+  return generatePreviewMetadata(isDraft, baseMetadata, {
+    draftIndicator: '🚧 DRAFT',
+    noIndexDrafts: true,
+  });
+}
+
+/**
+ * Example: Async metadata generation with Next.js 15 patterns
+ */
+export async function ProductPageMetadata(props: {
+  params: Promise<{ id: string }>;
+  searchParams: Promise<{ variant?: string }>;
+}) {
+  return generateMetadataAsync({
+    params: props.params as Promise<Record<string, string>>,
+    searchParams: props.searchParams as Promise<Record<string, string | string[] | undefined>>,
+    generator: async (params, searchParams: any) => {
+      const product = await getProduct(params.id ?? '');
+      const { variant } = searchParams;
+
+      return {
+        title: variant ? `${product.name} - ${variant as string}` : product.name,
+        description: product.description,
+      };
+    },
+  });
+}
+
+/**
+ * Example: Edge-compatible metadata generation
+ */
+export async function EdgeMetadata(request: any) {
+  // This runs on the edge runtime
+  const url = new URL(request.url);
+  const slug = url.pathname.split('/').pop();
+
+  return generateMetadataEdge(request, {
+    title: `Edge Page - ${slug}`,
+    description: 'This metadata was generated on the edge',
+    image: '/images/edge-og.jpg',
+  });
+}
+
+/**
+ * Example: Using SEOManager for consistent configuration
+ */
+const seoManager = new SEOManager({
+  applicationName: 'My E-commerce Store',
+  author: {
+    name: 'John Doe',
+    url: 'https://johndoe.com',
+  },
+  keywords: ['ecommerce', 'shopping', 'online store'],
+  locale: 'en_US',
+  publisher: 'My Company',
+  themeColor: '#0070f3',
+  twitterHandle: '@mystore',
+});
+
+/**
+ * Example: Generate error page metadata
+ */
+export function ErrorPageMetadata(statusCode: number) {
+  return seoManager.createErrorMetadata(statusCode);
+}
+
+/**
+ * Example: Generate metadata with SEOManager
+ */
+export function PageWithSEOManager({ page }: { page: any }) {
+  return seoManager.createMetadata({
+    title: page.title,
+    description: page.description,
+    image: page.image,
+    keywords: page.tags,
+    article:
+      page.type === 'article'
+        ? {
+            publishedTime: page.publishedAt,
+            modifiedTime: page.updatedAt,
+            authors: [page.author],
+            tags: page.tags,
+          }
+        : undefined,
+  });
+}
+
+// ============================================
+// HELPER FUNCTIONS (for examples)
+// ============================================
+
+async function getProduct(id: string) {
+  // Mock implementation
+  return {
+    id,
+    name: 'Example Product',
+    description: 'A great product',
+    price: 99.99,
+    currency: 'USD',
+    image: '/images/product.jpg',
+    inStock: true,
+    brand: 'Example Brand',
+
+    slug: 'example-product',
+    updatedAt: new Date(),
+  };
+}
+
+async function getProducts() {
+  // Mock implementation
+  return [
+    { slug: 'product-1', updatedAt: new Date() },
+    { slug: 'product-2', updatedAt: new Date() },
+  ];
+}
+
+/**
+ * Example: Complete page with all SEO features
+ */
+export default async function ComprehensiveSEOExample() {
+  const product = await getProduct('123');
+
+  // Generate metadata
+  const metadata = metadataTemplates.product({
+    name: product.name,
+    description: product.description,
+    price: product.price,
+    currency: product.currency,
+    image: product.image,
+    availability: 'InStock',
+  });
+
+  // Return complete page setup
+  return {
+    metadata,
+    viewport: viewportPresets.default,
+    structuredData: {
+      '@context': 'https://schema.org',
+      '@type': 'Product',
+      name: product.name,
+      description: product.description,
+    },
+  };
+}

package/src/examples/nextjs-15-integration.ts

@@ -0,0 +1,241 @@
+/**
+ * @fileoverview Next.js 15 + next-sitemap Integration Example
+ * @module @repo/seo/examples/nextjs-15-integration
+ *
+ * This example demonstrates how to integrate Next.js 15's native sitemap
+ * functionality with next-sitemap for the best of both worlds.
+ *
+ * Benefits of this approach:
+ * - Use Next.js 15's app directory for dynamic sitemaps
+ * - Use next-sitemap for static generation and advanced features
+ * - Automatic sitemap index generation for large sites
+ * - Unified robots.txt generation
+ *
+ * Prerequisites:
+ * - Next.js 15.0.0 or later
+ * - next-sitemap 4.0.0 or later (optional)
+ * - @repo/seo package
+ *
+ * @example
+ * // 1. Create app directory sitemaps for dynamic content
+ * // 2. Use next-sitemap for static pages and sitemap index
+ * // 3. Combine both in robots.txt
+ */
+
+// ============================================
+// STEP 1: App Directory Dynamic Sitemaps
+// ============================================
+
+// ============================================
+// STEP 5: Helper for Hybrid Approach
+// ============================================
+import { type MetadataRoute } from 'next';
+
+// app/sitemaps/products/sitemap.ts
+import { logError } from '@repo/shared/logs';
+
+import {
+  convertToNextSitemap,
+  createIntegratedSitemapConfig,
+  generateSitemapObject,
+  type DynamicSitemapRoute,
+} from '../server-next';
+
+/**
+ * Dynamic product sitemap using Next.js 15 native support
+ * This will be available at /sitemaps/products/sitemap.xml
+ */
+export async function generateProductSitemap(): Promise<MetadataRoute.Sitemap> {
+  const baseUrl = process.env.NEXT_PUBLIC_URL ?? 'https://example.com';
+
+  // Fetch your products
+  const products = (await fetch(`${baseUrl}/api/products`).then(res => res.json())) as Array<{
+    slug: string;
+    updatedAt: string;
+    name: string;
+    images?: Array<{ url: string; alt: string }>;
+  }>;
+
+  const routes: DynamicSitemapRoute[] = products.map(product => ({
+    url: `${baseUrl}/products/${product.slug}`,
+    lastModified: new Date(product.updatedAt),
+    changeFrequency: 'daily',
+    priority: 0.8,
+    // Next.js 15 supports images in sitemaps!
+    images: product.images?.map(img => ({
+      url: img.url,
+      title: img.alt,
+      caption: product.name,
+    })),
+  }));
+
+  return generateSitemapObject(routes);
+}
+
+// app/sitemaps/blog/sitemap.ts
+/**
+ * Dynamic blog sitemap
+ * This will be available at /sitemaps/blog/sitemap.xml
+ */
+export async function generateBlogSitemap(): Promise<MetadataRoute.Sitemap> {
+  const baseUrl = process.env.NEXT_PUBLIC_URL ?? 'https://example.com';
+
+  const posts = (await fetch(`${baseUrl}/api/posts`).then(res => res.json())) as Array<{
+    slug: string;
+    publishedAt: string;
+  }>;
+
+  const routes: DynamicSitemapRoute[] = posts.map(post => ({
+    url: `${baseUrl}/blog/${post.slug}`,
+    lastModified: new Date(post.publishedAt),
+    changeFrequency: 'weekly',
+    priority: 0.6,
+  }));
+
+  return generateSitemapObject(routes);
+}
+
+const config = createIntegratedSitemapConfig({
+  siteUrl: process.env.SITE_URL ?? 'https://example.com',
+  generateRobotsTxt: true,
+
+  // Tell next-sitemap about your app directory sitemaps
+  appDirSitemaps: ['/sitemaps/products/sitemap.xml', '/sitemaps/blog/sitemap.xml'],
+
+  // Handle static pages with next-sitemap
+  exclude: [
+    '/api/*',
+    '/admin/*',
+    // Exclude dynamic routes handled by app directory
+    '/products/*',
+    '/blog/*',
+  ],
+
+  // Merge additional static routes
+
+  additionalPaths: async (_config: unknown) => {
+    return [
+      { loc: '/', changefreq: 'daily', priority: 1 },
+      { loc: '/about', changefreq: 'monthly', priority: 0.8 },
+      { loc: '/contact', changefreq: 'monthly', priority: 0.7 },
+    ];
+  },
+
+  // Advanced: Transform function for static pages (must be synchronous)
+  transform: (_config: unknown, path: string) => {
+    // Custom logic for specific paths
+    if (path === '/') {
+      return {
+        loc: path,
+        changefreq: 'daily',
+        priority: 1,
+        lastmod: new Date().toISOString(),
+      };
+    }
+
+    return {
+      loc: path,
+      changefreq: 'monthly',
+      priority: 0.5,
+      lastmod: new Date().toISOString(),
+    };
+  },
+});
+
+export default config;
+
+// ============================================
+// STEP 3: Unified Robots.txt
+// ============================================
+
+// app/robots.ts
+/**
+ * Unified robots.txt that references all sitemaps
+ * Both from next-sitemap and app directory
+ */
+export function robots(): MetadataRoute.Robots {
+  const baseUrl = process.env.NEXT_PUBLIC_URL ?? 'https://example.com';
+
+  return {
+    rules: [
+      {
+        userAgent: '*',
+        allow: '/',
+        disallow: ['/api/', '/admin/', '/private/'],
+      },
+      {
+        userAgent: 'Googlebot',
+        allow: '/',
+      },
+    ],
+    // Reference all sitemaps
+    sitemap: [
+      `${baseUrl}/sitemap.xml`, // Main sitemap from next-sitemap
+      `${baseUrl}/sitemap-0.xml`, // Additional sitemaps from next-sitemap
+      `${baseUrl}/sitemaps/products/sitemap.xml`, // App directory sitemap
+      `${baseUrl}/sitemaps/blog/sitemap.xml`, // App directory sitemap
+    ],
+  };
+}
+
+// ============================================
+// STEP 4: Sitemap Index (Optional)
+// ============================================
+
+// app/sitemap.ts
+/**
+ * Main sitemap index that combines all sitemaps
+ * This creates a sitemap index for very large sites
+ */
+export function sitemap(): MetadataRoute.Sitemap {
+  const baseUrl = process.env.NEXT_PUBLIC_URL ?? 'https://example.com';
+
+  // Return sitemap index entries
+  return [
+    {
+      url: `${baseUrl}/sitemap-static.xml`,
+      lastModified: new Date(),
+    },
+    {
+      url: `${baseUrl}/sitemaps/products/sitemap.xml`,
+      lastModified: new Date(),
+    },
+    {
+      url: `${baseUrl}/sitemaps/blog/sitemap.xml`,
+      lastModified: new Date(),
+    },
+  ];
+}
+
+/**
+ * Utility to fetch and merge sitemaps from different sources
+ */
+export async function mergeSitemaps(sources: string[]): Promise<MetadataRoute.Sitemap> {
+  const allRoutes: MetadataRoute.Sitemap = [];
+
+  for (const source of sources) {
+    try {
+      const response = await fetch(source);
+      const data = (await response.json()) as MetadataRoute.Sitemap;
+      allRoutes.push(...data);
+    } catch (error: unknown) {
+      logError(`Failed to fetch sitemap from ${source}`, { error, source });
+    }
+  }
+
+  return allRoutes;
+}
+
+/**
+ * Convert between Next.js and next-sitemap formats
+ */
+export function convertSitemapFormats(
+  nextjsSitemap: Array<{
+    url: string;
+    lastModified?: Date;
+    changeFrequency?: string;
+    priority?: number;
+  }>,
+) {
+  return convertToNextSitemap(nextjsSitemap);
+}

package/src/index.ts

@@ -0,0 +1,87 @@
+/**
+ * @fileoverview Main SEO Package Index
+ *
+ * Re-exports commonly used SEO functionality from various modules.
+ * This provides a convenient single import point for basic SEO needs.
+ *
+ * Features:
+ * - Structured data (JSON-LD) generation
+ * - Next.js metadata utilities
+ * - SEO validation utilities
+ * - i18n-enhanced metadata
+ *
+ * @module @repo/seo
+ *
+ * @example Basic usage with structured data
+ * ```tsx
+ * import { JsonLd, structuredData } from '@repo/seo';
+ *
+ * const article = structuredData.article({
+ *   headline: 'Getting Started',
+ *   author: 'John Doe',
+ *   datePublished: '2024-01-01'
+ * });
+ *
+ * export default function Page() {
+ *   return <JsonLd data={article} />;
+ * }
+ * ```
+ *
+ * @example With validation
+ * ```ts
+ * import { validateSchemaOrg, structuredData } from '@repo/seo';
+ *
+ * const org = structuredData.organization({
+ *   name: 'Acme Corp',
+ *   url: 'https://acme.com'
+ * });
+ *
+ * if (validateSchemaOrg(org)) {
+ *   // Data is valid
+ * }
+ * ```
+ *
+ * @example Next.js metadata
+ * ```ts
+ * import { createMetadata } from '@repo/seo';
+ *
+ * export const metadata = createMetadata({
+ *   title: 'Page Title',
+ *   description: 'Page description',
+ *   image: '/og-image.png'
+ * });
+ * ```
+ */
+
+// Re-export client-side components
+export { JsonLd } from './client';
+
+// Re-export server-side utilities
+export { createStructuredData, structuredData } from './server';
+
+// Re-export structured data utilities
+export {
+  JsonLd as StructuredDataJsonLd,
+  createStructuredData as createStructuredDataUtil,
+  structuredData as structuredDataHelpers,
+} from './components/structured-data';
+
+// Re-export metadata utilities
+export { createMetadata } from './utils/metadata';
+
+// Re-export validation utilities (for convenience)
+export {
+  validateImages,
+  validateImagesDetailed,
+  validateMetadata,
+  validateOpenGraph,
+  validateSchemaOrg,
+  validateSchemaOrgDetailed,
+  validateUrl,
+  validateUrls,
+  validateUrlsDetailed,
+} from './utils/validation';
+
+// Re-export types
+export type { StructuredDataType, Thing, WithContext } from './server';
+export type { ValidationResult } from './utils/validation';