@od-oneapp/seo 2026.1.1301

package/README.md

@@ -0,0 +1,586 @@
+# @repo/seo
+
+Enterprise-grade SEO utilities for Next.js applications with comprehensive metadata generation, structured data, and
+sitemap support.
+
+## Status
+
+- **Build**: ✅ TypeScript source package (no build step required)
+- **Tests**: ✅ 19 test files with comprehensive coverage
+- **Type Safety**: ✅ Strict TypeScript with schema-dts integration
+
+## Installation
+
+```bash
+pnpm add @repo/seo
+```
+
+## Quick Start
+
+### Next.js 15 Metadata (App Router)
+
+```typescript
+// app/layout.tsx
+import { createMetadata } from "@repo/seo/server/next";
+
+export const metadata = createMetadata({
+  title: "Home",
+  description: "Welcome to our application",
+  image: "/og-image.png",
+  applicationName: "My App",
+  author: { name: "Your Name", url: "https://example.com" },
+  publisher: "Your Company",
+  twitterHandle: "@yourhandle"
+});
+```
+
+### Structured Data (JSON-LD)
+
+```typescript
+// app/products/[id]/page.tsx
+import { JsonLd } from "@repo/seo/client/next";
+import { structuredData } from "@repo/seo/server/next";
+
+export default function ProductPage({ product }) {
+  const productSchema = structuredData.product({
+    name: product.title,
+    description: product.description,
+    image: product.image,
+    offers: {
+      price: product.price.toString(),
+      priceCurrency: "USD",
+      availability: "https://schema.org/InStock",
+    },
+    brand: product.brand,
+  });
+
+  return (
+    <>
+      <JsonLd data={productSchema} />
+      {/* Your product content */}
+    </>
+  );
+}
+```
+
+### Dynamic Sitemap
+
+```typescript
+// app/sitemap.ts
+import { generateSitemapObject } from "@repo/seo/server/next";
+import { getBaseUrl } from "@repo/seo/env";
+
+export default async function sitemap() {
+  const products = await getAllProducts();
+  const baseUrl = getBaseUrl({ required: true });
+
+  return generateSitemapObject([
+    {
+      url: baseUrl,
+      changeFrequency: "daily",
+      priority: 1,
+      lastModified: new Date()
+    },
+    ...products.map((product) => ({
+      url: `${baseUrl}/products/${product.slug}`,
+      lastModified: product.updatedAt,
+      changeFrequency: "weekly" as const,
+      priority: 0.8,
+      images: [{ url: product.image, title: product.title }]
+    }))
+  ]);
+}
+```
+
+## Package Exports
+
+This package uses the modern exports field for precise imports:
+
+- **`@repo/seo`** - Main entry point (convenience re-exports)
+- **`@repo/seo/client`** - Client-side components (generic)
+- **`@repo/seo/server`** - Server-side utilities (generic)
+- **`@repo/seo/client/next`** - Next.js client components
+- **`@repo/seo/server/next`** - Next.js server utilities
+- **`@repo/seo/structured-data`** - Structured data components
+
+## Core Features
+
+### 1. Next.js 15 Integration
+
+Full support for Next.js 15 App Router metadata API:
+
+```typescript
+import { SEOManager } from "@repo/seo/server/next";
+
+const seoManager = new SEOManager({
+  applicationName: "My App",
+  author: { name: "Author Name", url: "https://author.com" },
+  publisher: "Publisher Name",
+  twitterHandle: "@handle",
+  keywords: ["keyword1", "keyword2"],
+  locale: "en_US",
+  themeColor: "#000000"
+});
+
+// Generate metadata for any page
+export async function generateMetadata({ params }) {
+  return seoManager.createMetadata({
+    title: "Page Title",
+    description: "Page description",
+    image: "/image.png",
+    keywords: ["page-specific", "keywords"],
+    canonical: "https://example.com/canonical-url"
+  });
+}
+
+// Error pages
+export const metadata = seoManager.createErrorMetadata(404);
+```
+
+### 2. Metadata Templates
+
+Pre-built templates for common page types:
+
+```typescript
+import { metadataTemplates } from "@repo/seo/server/next";
+
+// Product page
+export const metadata = metadataTemplates.product({
+  name: "Product Name",
+  description: "Product description",
+  price: 99.99,
+  currency: "USD",
+  image: "/product.png",
+  availability: "InStock",
+  brand: "Brand Name"
+});
+
+// Article/blog post
+export const metadata = metadataTemplates.article({
+  title: "Article Title",
+  description: "Article description",
+  author: "Author Name",
+  publishedTime: new Date("2024-01-01"),
+  modifiedTime: new Date("2024-01-15"),
+  image: "/article.png",
+  tags: ["tag1", "tag2"],
+  section: "Technology"
+});
+
+// User profile
+export const metadata = metadataTemplates.profile({
+  name: "User Name",
+  bio: "User biography",
+  image: "/avatar.png",
+  username: "username",
+  firstName: "First",
+  lastName: "Last"
+});
+```
+
+### 3. Structured Data Builders
+
+Type-safe Schema.org structured data generation:
+
+```typescript
+import { structuredData } from "@repo/seo/server/next";
+import { JsonLd } from "@repo/seo/client/next";
+
+// Article schema
+const articleSchema = structuredData.article({
+  headline: "Article Title",
+  author: { name: "Author Name", url: "https://author.com" },
+  datePublished: "2024-01-01",
+  dateModified: "2024-01-15",
+  image: ["/article.png"],
+  publisher: { name: "Publisher", logo: "/logo.png" },
+});
+
+// Organization schema
+const orgSchema = structuredData.organization({
+  name: "Company Name",
+  url: "https://company.com",
+  logo: "/logo.png",
+  description: "Company description",
+  sameAs: ["https://twitter.com/company", "https://linkedin.com/company"],
+  contactPoint: {
+    contactType: "Customer Service",
+    telephone: "+1-555-1234",
+    areaServed: "US",
+    availableLanguage: ["English"],
+  },
+});
+
+// FAQ schema
+const faqSchema = structuredData.faq([
+  { question: "What is this?", answer: "This is the answer." },
+  { question: "How do I use it?", answer: "Follow the instructions." },
+]);
+
+// Breadcrumbs
+const breadcrumbsSchema = structuredData.breadcrumbs([
+  { name: "Home", url: "https://example.com" },
+  { name: "Category", url: "https://example.com/category" },
+  { name: "Product", url: "https://example.com/category/product" },
+]);
+
+// Render in component
+<JsonLd data={[articleSchema, orgSchema, breadcrumbsSchema]} />;
+```
+
+### 4. Internationalization (i18n)
+
+Multi-language SEO with hreflang support:
+
+```typescript
+import { generateI18nSitemap } from "@repo/seo/server/next";
+
+const routes = [
+  { url: "https://example.com", priority: 1, changeFrequency: "daily" as const },
+  { url: "https://example.com/about", priority: 0.8, changeFrequency: "monthly" as const }
+];
+
+const locales = ["en", "es", "fr", "de"];
+const sitemap = generateI18nSitemap(routes, locales, "en");
+
+// Generates:
+// https://example.com
+// https://example.com/es
+// https://example.com/fr
+// https://example.com/de
+// https://example.com/about
+// https://example.com/es/about
+// ... etc
+```
+
+### 5. Viewport Configuration
+
+Device-specific viewport presets:
+
+```typescript
+import { viewportPresets, generateViewport } from "@repo/seo/server/next";
+
+// Static viewport
+export const viewport = viewportPresets.default; // Responsive
+export const viewport = viewportPresets.mobileOptimized; // Mobile (no zoom)
+export const viewport = viewportPresets.tablet; // Tablet
+export const viewport = viewportPresets.desktop; // Desktop
+
+// Dynamic viewport based on user agent
+export function generateViewport() {
+  const userAgent = headers().get("user-agent") || "";
+  return generateViewport(userAgent);
+}
+```
+
+### 6. Advanced Features
+
+#### Preview Mode Metadata
+
+```typescript
+import { generatePreviewMetadata } from "@repo/seo/server/next";
+
+const isDraft = true;
+const baseMetadata = createMetadata({ title: "My Post", description: "..." });
+
+const metadata = generatePreviewMetadata(isDraft, baseMetadata, {
+  draftIndicator: "[DRAFT]",
+  noIndexDrafts: true
+});
+```
+
+#### Edge Runtime Support
+
+```typescript
+import { generateMetadataEdge } from "@repo/seo/server/next";
+
+export const runtime = "edge";
+
+export async function GET(request: Request) {
+  const metadata = await generateMetadataEdge(request, {
+    title: "Edge Page",
+    description: "Generated on the edge",
+    image: "/edge-og.png"
+  });
+
+  return NextResponse.json(metadata);
+}
+```
+
+#### Streaming JSON-LD
+
+```typescript
+import { StreamingJsonLd } from "@repo/seo/client/next";
+
+export default function Page() {
+  const dataPromise = fetch("/api/product-schema").then((r) => r.json());
+
+  return (
+    <StreamingJsonLd
+      dataPromise={dataPromise}
+      fallback={{ "@context": "https://schema.org", "@type": "Product" }}
+    />
+  );
+}
+```
+
+## Environment Configuration
+
+The package uses `@t3-oss/env-core` for type-safe environment validation:
+
+```bash
+# Required environment variables (at least one)
+NEXT_PUBLIC_URL=https://example.com
+SITE_URL=https://example.com
+VERCEL_PROJECT_PRODUCTION_URL=example.com
+
+# Optional
+NODE_ENV=production
+VERCEL_ENV=production
+```
+
+```typescript
+import { env, getProtocol, getBaseUrl, isProduction } from "@repo/seo/env";
+
+// Access validated environment variables
+const protocol = getProtocol(); // 'https' in production
+const baseUrl = getBaseUrl(); // Falls back to env vars
+const isProd = isProduction(); // true if NODE_ENV === 'production'
+```
+
+## Validation Utilities
+
+```typescript
+import {
+  validateMetadata,
+  validateOpenGraph,
+  validateSchemaOrg,
+  validateUrls,
+  validateImages
+} from "@repo/seo/validation";
+
+// Validate metadata has required fields
+const missing = validateMetadata({ title: "My Page" }); // ['description']
+
+// Validate Open Graph data
+const isValid = validateOpenGraph({ title: "Title", description: "Desc" }); // true
+
+// Validate Schema.org structured data
+const isValidSchema = validateSchemaOrg({
+  "@context": "https://schema.org",
+  "@type": "Article"
+}); // true
+
+// Validate URLs
+const validUrls = validateUrls(["https://example.com", "invalid"]); // false
+
+// Validate image URLs
+const validImages = validateImages(["https://example.com/image.jpg", "https://example.com/logo.png"]); // true
+```
+
+## Security Considerations
+
+### XSS Prevention
+
+The package includes built-in XSS protection:
+
+```typescript
+// ✅ SAFE: JSON.stringify escapes content
+<JsonLd data={structuredData.article({ headline: userInput })} />
+
+// ✅ SAFE: useOpenGraphPreview escapes HTML
+const { generatePreviewHtml } = useOpenGraphPreview({
+  title: userInput, // Automatically escaped
+  description: userInput,
+});
+
+// ✅ SAFE: URL validation prevents malicious URLs
+createMetadata({
+  image: userProvidedUrl, // Validated before use
+});
+```
+
+### Environment Variables
+
+- Never expose server-side environment variables to the client
+- Use `NEXT_PUBLIC_` prefix only for public URLs
+- Environment validation runs on package import
+
+## Best Practices
+
+### 1. Use SEOManager for Consistency
+
+```typescript
+// ✅ Recommended: Centralized configuration
+const seoManager = new SEOManager({ ...config });
+export const metadata = seoManager.createMetadata({ ...pageData });
+
+// ❌ Avoid: Inconsistent metadata across pages
+export const metadata = createMetadata({ ...everythingEachTime });
+```
+
+### 2. Combine Metadata with Structured Data
+
+```typescript
+export const metadata = metadataTemplates.article({ ...articleData });
+
+export default function ArticlePage() {
+  const schema = structuredData.article({ ...articleData });
+  return <><JsonLd data={schema} />{/* content */}</>;
+}
+```
+
+### 3. Validate URLs Before Use
+
+```typescript
+import { validateUrls } from "@repo/seo/utils/validation";
+
+const imageUrl = getUserUploadedImage();
+if (!validateUrls([imageUrl])) {
+  // Use fallback image
+  imageUrl = "/default-og-image.png";
+}
+```
+
+### 4. Use TypeScript for Type Safety
+
+```typescript
+import type { Metadata, SEOConfig } from "@repo/seo/server/next";
+
+const config: SEOConfig = {
+  applicationName: "My App",
+  author: { name: "Name", url: "https://example.com" },
+  publisher: "Publisher",
+  twitterHandle: "@handle"
+};
+```
+
+## Testing
+
+```bash
+pnpm test          # Run all tests
+pnpm test:watch    # Watch mode
+pnpm test:coverage # Coverage report
+pnpm test:ui       # Interactive UI
+```
+
+## API Reference
+
+### Server Utilities (Next.js)
+
+- `createMetadata(options)` - Simple metadata generation
+- `SEOManager` - Centralized SEO configuration
+- `metadataTemplates` - Pre-built templates (product, article, profile)
+- `structuredData` - Schema.org builders (article, product, organization, FAQ, breadcrumbs, website)
+- `generateSitemapObject(routes)` - Dynamic sitemap generation
+- `generateI18nSitemap(routes, locales)` - Multi-language sitemaps
+- `viewportPresets` - Device-specific viewport configs
+- `generateViewport(userAgent)` - Dynamic viewport selection
+- `generatePreviewMetadata(isDraft, metadata)` - Draft/preview handling
+- `generateMetadataEdge(request, options)` - Edge runtime support
+- `createSitemapConfig(config)` - next-sitemap integration
+
+### Client Components
+
+- `<JsonLd data={...} />` - Render JSON-LD structured data
+- `<OptimizedJsonLd data={...} strategy="..." />` - Performance-optimized JSON-LD
+- `<StreamingJsonLd dataPromise={...} />` - Async data loading
+- `useOpenGraphPreview(metadata)` - Dynamic OG preview generation
+
+### Validation
+
+- `validateMetadata(metadata)` - Check required fields
+- `validateOpenGraph(og)` - Validate OG data
+- `validateSchemaOrg(schema)` - Validate structured data
+- `validateUrls(urls)` - URL format validation
+- `validateImages(images)` - Image URL validation
+
+## Migration Guide
+
+### From next-seo
+
+```typescript
+// Before (next-seo)
+import { NextSeo } from 'next-seo';
+
+export default function Page() {
+  return <NextSeo title="..." description="..." openGraph={{ ... }} />;
+}
+
+// After (@repo/seo)
+import { createMetadata } from '@repo/seo/server/next';
+
+export const metadata = createMetadata({
+  title: "...",
+  description: "...",
+  image: "...",
+});
+
+export default function Page() {
+  return <>{/* content */}</>;
+}
+```
+
+### From Manual Metadata
+
+```typescript
+// Before
+export const metadata = {
+  title: "...",
+  description: "...",
+  openGraph: {
+    /* manual configuration */
+  },
+  twitter: {
+    /* manual configuration */
+  }
+};
+
+// After
+import { SEOManager } from "@repo/seo/server/next";
+
+const seo = new SEOManager({ ...appConfig });
+export const metadata = seo.createMetadata({ title: "...", description: "..." });
+```
+
+## Troubleshooting
+
+### Metadata not appearing
+
+1. Check that `metadataBase` is set correctly
+2. Verify environment variables are configured
+3. Ensure metadata is exported from page/layout
+
+### Structured data not validating
+
+1. Use Google's Rich Results Test
+2. Validate against Schema.org schemas
+3. Check console for validation errors
+
+### Type errors
+
+1. Update `@types/react` to latest version
+2. Ensure `next` version is 15.0.0+
+3. Check TypeScript is 5.0+
+
+## Related Packages
+
+- `@repo/utils` - Shared utilities (cn, formatters, validators)
+- `@repo/types` - TypeScript type utilities
+
+## Contributing
+
+See the main monorepo [CONTRIBUTING.md](../../../CONTRIBUTING.md) for guidelines.
+
+## License
+
+MIT - See [LICENSE](../../../LICENSE) for details.
+
+## 📚 Comprehensive Documentation
+
+For detailed documentation, see:
+
+- **[Audit Reports](../../apps/docs/content/docs/audits/seo/)** - Comprehensive audits, fixes, and security reviews
+- **[Technical Guides](../../apps/docs/content/docs/packages/seo/)** - Implementation guides and best practices
+
+All comprehensive documentation has been centralized in the docs app.

package/dist/client-next.d.mts

@@ -0,0 +1,46 @@
+import { Thing, Thing as Thing$1, WithContext, WithContext as WithContext$1 } from "schema-dts";
+import * as react_jsx_runtime0 from "react/jsx-runtime";
+export * from "schema-dts";
+
+//#region src/client-next.d.ts
+interface JsonLdProps {
+  data: WithContext$1<Thing$1> | WithContext$1<Thing$1>[];
+  id?: string;
+  strategy?: 'afterInteractive' | 'lazyOnload' | 'beforeInteractive' | 'worker';
+}
+declare function JsonLd({
+  data,
+  id
+}: JsonLdProps): react_jsx_runtime0.JSX.Element;
+declare function OptimizedJsonLd({
+  data,
+  id
+}: JsonLdProps): react_jsx_runtime0.JSX.Element;
+interface StreamingJsonLdProps {
+  dataPromise: Promise<WithContext$1<Thing$1> | WithContext$1<Thing$1>[]>;
+  id?: string;
+  fallback?: WithContext$1<Thing$1>;
+}
+declare function StreamingJsonLd({
+  dataPromise,
+  id,
+  fallback
+}: StreamingJsonLdProps): react_jsx_runtime0.JSX.Element;
+declare function useOpenGraphPreview(metadata: {
+  title: string;
+  description: string;
+  image?: string;
+  url?: string;
+}): {
+  preview: {
+    title: string;
+    description: string;
+    image?: string;
+    url?: string;
+  };
+  updatePreview: (updates: Partial<typeof metadata>) => void;
+  generatePreviewHtml: string;
+};
+//#endregion
+export { JsonLd, OptimizedJsonLd, StreamingJsonLd, type Thing, type WithContext, useOpenGraphPreview };
+//# sourceMappingURL=client-next.d.mts.map

package/dist/client-next.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-next.d.mts","names":[],"sources":["../src/client-next.tsx"],"mappings":";;;;;UAeU,WAAA;EACR,IAAA,EAAM,aAAA,CAAY,OAAA,IAAS,aAAA,CAAY,OAAA;EACvC,EAAA;EACA,QAAA;AAAA;AAAA,iBAIc,MAAA,CAAA;EAAS,IAAA;EAAM;AAAA,GAAM,WAAA,GAAW,kBAAA,CAAA,GAAA,CAAA,OAAA;AAAA,iBAoBhC,eAAA,CAAA;EAAkB,IAAA;EAAM;AAAA,GAAM,WAAA,GAAW,kBAAA,CAAA,GAAA,CAAA,OAAA;AAAA,UAqB/C,oBAAA;EACR,WAAA,EAAa,OAAA,CAAQ,aAAA,CAAY,OAAA,IAAS,aAAA,CAAY,OAAA;EACtD,EAAA;EACA,QAAA,GAAW,aAAA,CAAY,OAAA;AAAA;AAAA,iBAGT,eAAA,CAAA;EAAkB,WAAA;EAAa,EAAA;EAAI;AAAA,GAAY,oBAAA,GAAoB,kBAAA,CAAA,GAAA,CAAA,OAAA;AAAA,iBAkCnE,mBAAA,CAAoB,QAAA;EAClC,KAAA;EACA,WAAA;EACA,KAAA;EACA,GAAA;AAAA;;;;;;;2BAIkD,OAAA,QAAe,QAAA"}