# SEO and Metadata Differences with PWA Kit

PWA Kit uses react-helmet to manage meta tags, with developers manually adding Helmet components to each page. Storefront Next provides a comprehensive SEO system built around the `SeoMeta` component, with built-in support for hreflang alternates, canonical URLs, Open Graph, Twitter Cards, and robots control. Both support dynamic metadata, but Storefront Next offers a more complete, production-ready SEO implementation out of the box.

## Key Differences

| Aspect          | PWA Kit                    | Storefront Next                    |
| --------------- | -------------------------- | ---------------------------------- |
| Library         | react-helmet               | Built-in React component (SeoMeta) |
| Pattern         | Manual Helmet in each page | SeoMeta component                  |
| Dynamic Meta    | Implemented via Helmet     | Implemented via SeoMeta            |
| Hreflang        | Not documented             | Automatic locale alternates        |
| Canonical URLs  | Not documented             | With query param normalization     |
| Robots Control  | Manual via Helmet          | Built-in `noIndex` prop            |
| Social Tags     | Manual via Helmet          | Open Graph + Twitter Card support  |
| API Integration | Consumes `pageMetaTags`    | Uses SeoMeta with dynamic props    |

## Head Management Approach

PWA Kit:

```javascript
// Per-page Helmet usage
import { Helmet } from "react-helmet";

export default function ProductDetail() {
  return (
    <>
      <Helmet>
        <title>{product.pageTitle}</title>
        <meta name="description" content={product.pageDescription} />
      </Helmet>
      {/* page content */}
    </>
  );
}
```

Storefront Next:

```typescript
// SeoMeta component usage
import { SeoMeta } from "@/components/seo-meta";

export default function ProductDetail() {
  return (
    <>
      <SeoMeta
        title={product.pageTitle}
        description={product.pageDescription}
        openGraph={{
          type: "product",
          url: canonicalUrl,
          image: product.imageUrl,
        }}
      />
      {/* page content */}
    </>
  );
}
```

## API Meta Tag Consumption

PWA Kit consumes the Commerce API's `pageMetaTags` array directly:

```javascript
// PWA Kit: Renders each meta tag from API via Helmet
import { Helmet } from "react-helmet";

<Helmet>
  <title>{product.pageTitle}</title>
  <meta name="description" content={product.pageDescription} />
  {product.pageMetaTags?.map(({ id, value }) => (
    <meta name={id} content={value} key={id} />
  ))}
</Helmet>;
```

Storefront Next uses the `SeoMeta` component with explicit props rather than consuming `pageMetaTags` directly:

```typescript
// Storefront Next: Uses SeoMeta component
import { SeoMeta } from "@/components/seo-meta";

<SeoMeta
  title={product.pageTitle}
  description={product.pageDescription}
  openGraph={{
    type: "product",
    url: canonicalUrl,
    image: product.imageUrl,
  }}
  twitter={{ cardType: "summary_large_image" }}
/>;
```

If you need to consume `pageMetaTags` in Storefront Next, you can map them to the `SeoMeta` props or render them as additional meta tags.

## Key Similarities

1. **Dynamic metadata**: Both support dynamic page titles and meta descriptions.
2. **SSR support**: Both render meta tags server-side for SEO.
3. **Component-based**: Both use React components to manage meta tags.
4. **No structured data**: Neither implements JSON-LD by default (can be added manually).

## Storefront Next Advantages

1. **Hreflang alternates**: Automatically generates locale-specific alternate links with x-default support.
2. **Canonical URLs**: Built-in canonical URL generation with query parameter normalization and allowlist.
3. **Social tags**: Built-in Open Graph and Twitter Card support via `SeoMeta` props.
4. **Robots control**: Simple `noIndex` prop for controlling search engine indexing.
5. **Centralized SEO utils**: SEO logic consolidated in `src/utils/seo.ts` and `src/utils/canonical-url.ts`.
6. **Title modes**: Support for suffixed (default), raw, and fallback title rendering.

## Storefront Next Hreflang Implementation

Storefront Next automatically generates hreflang tags for all supported locales:

```html
<!-- Automatically generated in <head> -->
<link rel="canonical" href="https://www.example.com/global/en-GB/product/123" />
<link rel="alternate" hreflang="en-GB" href="https://www.example.com/global/en-GB/product/123" />
<link rel="alternate" hreflang="fr-FR" href="https://www.example.com/global/fr-FR/product/123" />
<link
  rel="alternate"
  hreflang="x-default"
  href="https://www.example.com/global/en-GB/product/123"
/>
```

PWA Kit does not provide built-in hreflang support. You would need to implement this manually using react-helmet.

## Canonical URL Management

Storefront Next includes sophisticated canonical URL handling with query parameter normalization:

**Allowed parameters** (kept in canonical URL):

- `q` - search query
- `offset` - pagination
- `sort` - sort order
- `refine` - filters
- `pid` - product variant ID

**Removed parameters**: All tracking params, analytics IDs, and non-content parameters are stripped.

PWA Kit does not provide built-in canonical URL management. You would need to implement this manually.

## Storefront Conversion Considerations

When migrating from PWA Kit to Storefront Next:

1. Replace react-helmet with SeoMeta

   - Remove `react-helmet` imports and `<Helmet>` components.
   - Replace with `<SeoMeta>` component from `@/components/seo-meta`.
   - Convert inline meta tags to `SeoMeta` props.

2. Leverage Built-in SEO Features

   - Hreflang alternates are already configured in `src/utils/seo.ts`.
   - Canonical URLs are automatically generated via `src/utils/canonical-url.ts`.
   - Add `openGraph` and `twitter` props to `SeoMeta` for social sharing.

3. Add noIndex for Protected Pages

   - Use `<SeoMeta noIndex />` for account, checkout, and order pages.
   - This prevents search engines from indexing private content.

4. Configure Query Parameters

   - Update `CONTENT_PARAMS` in `src/utils/canonical-url.ts` if you add custom query params that affect page content.

5. Optional: Add Structured Data

   - Consider adding JSON-LD for products, categories, and breadcrumbs.
   - Render `<script type="application/ld+json">` tags within route components.

6. Test Multi-Locale Sites
   - Verify hreflang links are generated correctly for all locales.
   - Confirm canonical URLs strip locale prefixes appropriately.