feat: add explicit Makeswift SEO metadata support

Author: jorgemoya

.changeset/wild-bears-open.md

@@ -0,0 +1,82 @@
+---
+"@bigcommerce/catalyst-makeswift": patch
+---
+
+Add explicit Makeswift SEO metadata support to public-facing pages. When configured in Makeswift, the SEO title and description will take priority over the default values from BigCommerce or static translations.
+
+The following pages now support Makeswift SEO metadata:
+
+- Home page (`/`)
+- Catch-all page (`/[...rest]`)
+- Product page (`/product/[slug]`)
+- Brand page (`/brand/[slug]`)
+- Category page (`/category/[slug]`)
+- Blog list page (`/blog`)
+- Blog post page (`/blog/[blogId]`)
+- Search page (`/search`)
+- Cart page (`/cart`)
+- Compare page (`/compare`)
+- Gift certificates page (`/gift-certificates`)
+- Gift certificates balance page (`/gift-certificates/balance`)
+- Contact webpage (`/webpages/[id]/contact`)
+- Normal webpage (`/webpages/[id]/normal`)
+
+## Migration steps
+
+### Step 1: Add `getPageMetadata` function
+
+Add the `getPageMetadata` function to `core/lib/makeswift/client.ts`:
+
+```diff
++ export async function getPageMetadata({ path, locale }: { path: string; locale: string }) {
++   const snapshot = await getPageSnapshot({ path, locale });
++
++   if (snapshot == null) {
++     return null;
++   }
++
++   const { meta } = snapshot.document;
++
++   return {
++     ...(meta.title && { title: meta.title }),
++     ...(meta.description && { description: meta.description }),
++   };
++ }
+```
+
+Export the function from `core/lib/makeswift/index.ts`:
+
+```diff
+  export { Page } from './page';
+- export { client } from './client';
++ export { client, getPageMetadata } from './client';
+```
+
+### Step 2: Update page metadata
+
+Each page's `generateMetadata` function has been updated to fetch Makeswift metadata and use it as the primary source, falling back to existing values. Here's an example using the cart page:
+
+Update `core/app/[locale]/(default)/cart/page.tsx`:
+
+```diff
+  import { getPreferredCurrencyCode } from '~/lib/currency';
++ import { getPageMetadata } from '~/lib/makeswift';
+  import { Slot } from '~/lib/makeswift/slot';
+```
+
+```diff
+  export async function generateMetadata({ params }: Props): Promise<Metadata> {
+    const { locale } = await params;
+
+    const t = await getTranslations({ locale, namespace: 'Cart' });
++   const makeswiftMetadata = await getPageMetadata({ path: '/cart', locale });
+
+    return {
+-     title: t('title'),
++     title: makeswiftMetadata?.title || t('title'),
++     description: makeswiftMetadata?.description || undefined,
+    };
+  }
+```
+
+Apply the same pattern to the other pages listed above, using the appropriate path for each page (e.g., `/blog`, `/search`, `/compare`, etc.).

core/app/[locale]/(default)/(faceted)/brand/[slug]/page-data.ts

@@ -9,6 +9,7 @@ const BrandPageQuery = graphql(`
     site {
       brand(entityId: $entityId) {
         name
+        path
         seo {
           pageTitle
           metaDescription

core/app/[locale]/(default)/(faceted)/brand/[slug]/page.tsx

@@ -13,6 +13,7 @@ import { facetsTransformer } from '~/data-transformers/facets-transformer';
 import { pageInfoTransformer } from '~/data-transformers/page-info-transformer';
 import { productCardTransformer } from '~/data-transformers/product-card-transformer';
 import { getPreferredCurrencyCode } from '~/lib/currency';
+import { getPageMetadata } from '~/lib/makeswift';
 
 import { MAX_COMPARE_LIMIT } from '../../../compare/page-data';
 import { getCompareProducts as getCompareProductsData } from '../../fetch-compare-products';
@@ -67,7 +68,7 @@ interface Props {
 }
 
 export async function generateMetadata(props: Props): Promise<Metadata> {
-  const { slug } = await props.params;
+  const { slug, locale } = await props.params;
   const customerAccessToken = await getSessionCustomerAccessToken();
 
   const brandId = Number(slug);
@@ -78,11 +79,13 @@ export async function generateMetadata(props: Props): Promise<Metadata> {
     return notFound();
   }
 
+  const makeswiftMetadata = await getPageMetadata({ path: brand.path, locale });
+
   const { pageTitle, metaDescription, metaKeywords } = brand.seo;
 
   return {
-    title: pageTitle || brand.name,
-    description: metaDescription,
+    title: makeswiftMetadata?.title || pageTitle || brand.name,
+    description: makeswiftMetadata?.description || metaDescription,
     keywords: metaKeywords ? metaKeywords.split(',') : null,
   };
 }

core/app/[locale]/(default)/(faceted)/category/[slug]/page-data.ts

@@ -12,6 +12,7 @@ const CategoryPageQuery = graphql(
         category(entityId: $entityId) {
           entityId
           name
+          path
           ...BreadcrumbsFragment
           seo {
             pageTitle

core/app/[locale]/(default)/(faceted)/category/[slug]/page.tsx

@@ -14,6 +14,7 @@ import { facetsTransformer } from '~/data-transformers/facets-transformer';
 import { pageInfoTransformer } from '~/data-transformers/page-info-transformer';
 import { productCardTransformer } from '~/data-transformers/product-card-transformer';
 import { getPreferredCurrencyCode } from '~/lib/currency';
+import { getPageMetadata } from '~/lib/makeswift';
 import { Slot } from '~/lib/makeswift/slot';
 
 import { MAX_COMPARE_LIMIT } from '../../../compare/page-data';
@@ -70,7 +71,7 @@ interface Props {
 }
 
 export async function generateMetadata(props: Props): Promise<Metadata> {
-  const { slug } = await props.params;
+  const { slug, locale } = await props.params;
   const customerAccessToken = await getSessionCustomerAccessToken();
 
   const categoryId = Number(slug);
@@ -81,11 +82,13 @@ export async function generateMetadata(props: Props): Promise<Metadata> {
     return notFound();
   }
 
+  const makeswiftMetadata = await getPageMetadata({ path: category.path, locale });
+
   const { pageTitle, metaDescription, metaKeywords } = category.seo;
 
   return {
-    title: pageTitle || category.name,
-    description: metaDescription,
+    title: makeswiftMetadata?.title || pageTitle || category.name,
+    description: makeswiftMetadata?.description || metaDescription,
     keywords: metaKeywords ? metaKeywords.split(',') : null,
   };
 }

core/app/[locale]/(default)/(faceted)/search/page.tsx

@@ -12,6 +12,7 @@ import { facetsTransformer } from '~/data-transformers/facets-transformer';
 import { pageInfoTransformer } from '~/data-transformers/page-info-transformer';
 import { productCardTransformer } from '~/data-transformers/product-card-transformer';
 import { getPreferredCurrencyCode } from '~/lib/currency';
+import { getPageMetadata } from '~/lib/makeswift';
 
 import { MAX_COMPARE_LIMIT } from '../../compare/page-data';
 import { getCompareProducts as getCompareProductsData } from '../fetch-compare-products';
@@ -63,9 +64,11 @@ export async function generateMetadata({ params }: Props): Promise<Metadata> {
   const { locale } = await params;
 
   const t = await getTranslations({ locale, namespace: 'Faceted.Search' });
+  const makeswiftMetadata = await getPageMetadata({ path: '/search', locale });
 
   return {
-    title: t('title'),
+    title: makeswiftMetadata?.title || t('title'),
+    description: makeswiftMetadata?.description || undefined,
   };
 }
 

core/app/[locale]/(default)/[...rest]/page.tsx

@@ -1,11 +1,25 @@
+import { Metadata } from 'next';
+
 import { defaultLocale, locales } from '~/i18n/locales';
-import { client, Page } from '~/lib/makeswift';
+import { client, getPageMetadata, Page } from '~/lib/makeswift';
 
 interface PageParams {
   locale: string;
   rest: string[];
 }
 
+export async function generateMetadata({
+  params,
+}: {
+  params: Promise<PageParams>;
+}): Promise<Metadata> {
+  const { rest, locale } = await params;
+  const path = `/${rest.join('/')}`;
+  const metadata = await getPageMetadata({ path, locale });
+
+  return metadata ?? {};
+}
+
 export async function generateStaticParams(): Promise<PageParams[]> {
   const pages = await client.getPages().toArray();
 

core/app/[locale]/(default)/blog/[blogId]/page-data.ts

@@ -15,6 +15,7 @@ const BlogPageQuery = graphql(`
             author
             htmlBody
             name
+            path
             publishedDate {
               utc
             }

core/app/[locale]/(default)/blog/[blogId]/page.tsx

@@ -5,6 +5,7 @@ import { cache } from 'react';
 
 import { BlogPostContent, BlogPostContentBlogPost } from '@/vibes/soul/sections/blog-post-content';
 import { Breadcrumb } from '@/vibes/soul/sections/breadcrumbs';
+import { getPageMetadata } from '~/lib/makeswift';
 
 import { getBlogPageData } from './page-data';
 
@@ -18,7 +19,7 @@ interface Props {
 }
 
 export async function generateMetadata({ params }: Props): Promise<Metadata> {
-  const { blogId } = await params;
+  const { blogId, locale } = await params;
 
   const variables = cachedBlogPageDataVariables(blogId);
 
@@ -29,11 +30,12 @@ export async function generateMetadata({ params }: Props): Promise<Metadata> {
     return {};
   }
 
+  const makeswiftMetadata = await getPageMetadata({ path: blogPost.path, locale });
   const { pageTitle, metaDescription, metaKeywords } = blogPost.seo;
 
   return {
-    title: pageTitle || blogPost.name,
-    description: metaDescription,
+    title: makeswiftMetadata?.title || pageTitle || blogPost.name,
+    description: makeswiftMetadata?.description || metaDescription,
     keywords: metaKeywords ? metaKeywords.split(',') : null,
   };
 }

core/app/[locale]/(default)/blog/page.tsx

@@ -7,6 +7,7 @@ import { createSearchParamsCache, parseAsInteger, parseAsString } from 'nuqs/ser
 import { Streamable } from '@/vibes/soul/lib/streamable';
 import { FeaturedBlogPostList } from '@/vibes/soul/sections/featured-blog-post-list';
 import { defaultPageInfo, pageInfoTransformer } from '~/data-transformers/page-info-transformer';
+import { getPageMetadata } from '~/lib/makeswift';
 
 import { getBlog, getBlogPosts } from './page-data';
 
@@ -29,13 +30,15 @@ export async function generateMetadata({ params }: Props): Promise<Metadata> {
 
   const t = await getTranslations({ locale, namespace: 'Blog' });
   const blog = await getBlog();
+  const makeswiftMetadata = await getPageMetadata({ path: '/blog', locale });
 
   return {
-    title: blog?.name ?? t('title'),
+    title: makeswiftMetadata?.title || blog?.name || t('title'),
     description:
-      blog?.description && blog.description.length > 150
+      makeswiftMetadata?.description ||
+      (blog?.description && blog.description.length > 150
         ? `${blog.description.substring(0, 150)}...`
-        : blog?.description,
+        : blog?.description),
   };
 }