SuperAPI AI Directory

sfnext-seo

Coding & development

View repository

Updated 11-17 21:24

About this skill

Storefront Next SEO

In-project references: docs/README-SEO.md, docs/README-AEO-GEO.md, docs/README-MULTI-SITE.md (URL Config), docs/README-MULTI-DOMAIN.md, docs/README-BASE-PATH.md, docs/migrations/seo-url-rules/README.md. Read them for depth; this skill is the task map.

Page metadata: SeoMeta

import { SeoMeta } from '@/components/seo-meta';

<SeoMeta title={t('meta.title', { defaultValue: 'My Page' })} description={t('meta.description', { defaultValue: '...' })} />
<SeoMeta title="Checkout" noIndex />            {/* private/transactional pages */}
<SeoMeta rawTitle title="Store Name" />         {/* no " | Site Name" suffix */}
<SeoMeta title={name} openGraph={{ type: 'product', url: pageUrl, image }} />

Props (verified in src/components/seo-meta/index.tsx): title, rawTitle, description, noIndex, siteName, twitter, openGraph. Open Graph input auto-derives X card tags unless twitter is set. Use noIndex for cart, checkout, account, and other non-public pages. Root-level canonical and hreflang descriptors come from src/utils/seo.ts and src/utils/canonical-url.ts; routes do not add them.

Structured data: JsonLd

import { JsonLd } from '@/components/json-ld';

<JsonLd data={productSchema} id="product-schema" nonce={nonce} />

Pass the CSP nonce so the inline script is allowed. Builders live in src/utils/product-schema.ts, category-schema.ts, schema-url.ts. PDP emits Product; PLP emits CollectionPage + ItemList (see docs/README-AEO-GEO.md).

One URL everywhere

Canonical <link>, og:url and JSON-LD url must agree. In loaders:

import { buildSeoPageUrl } from '@/lib/seo/page-url.server';
import { redirectToCanonicalPath } from '@/lib/seo/canonical-redirect.server';

redirectToCanonicalPath(requestUrl);                 // 301 for trailing slash
const pageUrl = buildSeoPageUrl(context, requestUrl); // origin + canonical path/query

Only allowlisted query params survive in canonicals (CONTENT_PARAMS in src/utils/canonical-url.ts: q, offset, sort, refine, pid by default). Add a param only if it changes main page content, and add a test next to canonical-url.test.ts.

Configurable URLs: url.seoRoutes

// config.server.ts
url: {
  prefix: '/:siteId/:localeId',
  seoRoutes: {
    RefArchGlobal: { product: { prefix: 'p' }, category: { prefix: 'c', mode: 'id-suffix' } },
  },
}

Key rules (full playbook in references/SEO-ROUTES.md):

  • Build-time: changing seoRoutes requires a rebuild and redeploy (restart the dev server locally).
  • Every active site needs an entry, or URL generation throws / the build fails.
  • Business Manager URL settings are the source of truth; seoRoutes is a manual copy that must be kept in sync.
  • Do not rename route files. Routes are already generic; the config maps prefixes.
  • Build links with the semantic builders, never hardcoded /product/... strings:
import { createProductUrl, createCategoryUrl } from '@/route-paths';
import { useSeoUrlContext } from '@/hooks/use-seo-url-context';

const ctx = useSeoUrlContext();
<Link to={createProductUrl({ productId, slug }, ctx)} />

seoFallback.sites in config supplies per-site fallback behavior when a SEO URL cannot be resolved; see docs/README-MULTI-SITE.md.

Multi-domain and base path

  • Origin for canonicals comes from getAppOrigin (honors forwarded host, falls back to EXTERNAL_DOMAIN_NAME). Each custom domain must be attached to the Managed Runtime environment. See references/MULTI-DOMAIN-BASE-PATH.md.
  • Mapping domains to sites uses an X-Site-Id header set by your CDN.
  • A base path (MRT_ENV_BASE_PATH, set from the push config) prefixes asset and route URLs; use getBasePath() rather than hardcoding.

Crawlers

Crawlers receive full HTML rendering; category pages stay crawlable through a ?page=N parameter with rel prev/next links, while the canonical stays the base category URL. Verify with curl and a crawler user agent. Check docs/README-SEO.md "Crawler Rendering and Pagination" before changing streaming behavior.

Related Skills

  • storefront-next:sfnext-routing - route modules and URL patterns
  • storefront-next:sfnext-configuration - config.server.ts and env overrides
  • storefront-next:sfnext-i18n - locales, hreflang inputs
  • storefront-next:sfnext-hybrid-storefronts - URLs owned by another storefront
  • storefront-next:sfnext-security - CSP nonce for JSON-LD
  • storefront-next:sfnext-performance - streaming vs crawler rendering