Add unstable sitemap abstraction (#2478)

* Add a sitemap abstraction

.changeset/slow-keys-fold.md

@@ -0,0 +1,7 @@
+---
+'@shopify/hydrogen': patch
+---
+
+Introduce a new abstraction for generating sitemap index and child sitemaps.
+
+See the [sitemap example](https://github.com/Shopify/hydrogen/tree/main/examples/sitemap) for how to use it and read the [docs](https://shopify.dev/docs/api/hydrogen/utilities/getSitemapIndex) for more information.

examples/sitemap/app/routes/[sitemap.xml].tsx

@@ -1,5 +1,5 @@
 import type {LoaderFunctionArgs} from '@shopify/remix-oxygen';
-import {getSitemapIndex} from 'app/lib/sitemap';
+import {unstable__getSitemapIndex as getSitemapIndex} from '@shopify/hydrogen';
 
 export async function loader({
   request,

examples/sitemap/app/routes/sitemap.$type.$page[.xml].tsx

@@ -1,5 +1,5 @@
 import type {LoaderFunctionArgs} from '@shopify/remix-oxygen';
-import {getSitemap} from 'app/lib/sitemap';
+import {unstable__getSitemap as getSitemap} from '@shopify/hydrogen';
 
 export async function loader({
   request,

packages/hydrogen/src/index.ts

@@ -169,3 +169,8 @@ export {
   createHydrogenContext,
   type HydrogenContext,
 } from './createHydrogenContext';
+
+export {
+  getSitemapIndex as unstable__getSitemapIndex,
+  getSitemap as unstable__getSitemap,
+} from './sitemap/sitemap';

packages/hydrogen/src/sitemap/getSitemap.doc.ts

@@ -0,0 +1,43 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'getSitemap',
+  category: 'utilities',
+  isVisualComponent: false,
+  related: [
+    {
+      name: 'getSitemapIndex',
+      type: 'utilities',
+      url: '/api/hydrogen/utilities/getSitemapIndex',
+    },
+  ],
+  description: `> Caution:\n> This component is in an unstable pre-release state and may have breaking changes in a future release.\n\nGenerate a sitemap for a specific resource type. Returns a standard Response object.`,
+  type: 'utility',
+  defaultExample: {
+    description: 'I am the default example',
+    codeblock: {
+      tabs: [
+        {
+          title: 'JavaScript',
+          code: './getSitemap.example.jsx',
+          language: 'js',
+        },
+        {
+          title: 'TypeScript',
+          code: './getSitemap.example.tsx',
+          language: 'ts',
+        },
+      ],
+      title: 'Example code',
+    },
+  },
+  definitions: [
+    {
+      title: 'getSitemap',
+      type: 'GetSitemapGeneratedType',
+      description: '',
+    },
+  ],
+};
+
+export default data;

packages/hydrogen/src/sitemap/getSitemap.example.jsx

@@ -0,0 +1,21 @@
+import {unstable__getSitemap as getSitemap} from '@shopify/hydrogen';
+
+export async function loader({request, params, context: {storefront}}) {
+  const response = await getSitemap({
+    storefront,
+    request,
+    params,
+    // The locales to include in the sitemap
+    locales: ['EN-US', 'EN-CA', 'FR-CA'],
+    // A function to generate a link for a given resource
+    getLink: ({type, baseUrl, handle, locale}) => {
+      if (!locale) return `${baseUrl}/${type}/${handle}`;
+      return `${baseUrl}/${locale}/${type}/${handle}`;
+    },
+  });
+
+  // Set any custom headers on the sitemap response
+  response.headers.set('Cache-Control', `max-age=${60 * 60 * 24}`);
+
+  return response;
+}

packages/hydrogen/src/sitemap/getSitemap.example.tsx

@@ -0,0 +1,26 @@
+import type {LoaderFunctionArgs} from '@shopify/remix-oxygen';
+import {unstable__getSitemap as getSitemap} from '@shopify/hydrogen';
+
+export async function loader({
+  request,
+  params,
+  context: {storefront},
+}: LoaderFunctionArgs) {
+  const response = await getSitemap({
+    storefront,
+    request,
+    params,
+    // The locales to include in the sitemap
+    locales: ['EN-US', 'EN-CA', 'FR-CA'],
+    // A function to generate a link for a given resource
+    getLink: ({type, baseUrl, handle, locale}) => {
+      if (!locale) return `${baseUrl}/${type}/${handle}`;
+      return `${baseUrl}/${locale}/${type}/${handle}`;
+    },
+  });
+
+  // Set any custom headers on the sitemap response
+  response.headers.set('Cache-Control', `max-age=${60 * 60 * 24}`);
+
+  return response;
+}

packages/hydrogen/src/sitemap/getSitemapIndex.doc.ts

@@ -0,0 +1,43 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'getSitemapIndex',
+  category: 'utilities',
+  isVisualComponent: false,
+  related: [
+    {
+      name: 'getSitemap',
+      type: 'utilities',
+      url: '/api/hydrogen/utilities/getSitemap',
+    },
+  ],
+  description: `> Caution:\n> This component is in an unstable pre-release state and may have breaking changes in a future release.\n\nGenerate a sitemap index that links to separate child sitemaps for different resource types. Returns a standard Response object.`,
+  type: 'utility',
+  defaultExample: {
+    description: 'I am the default example',
+    codeblock: {
+      tabs: [
+        {
+          title: 'JavaScript',
+          code: './getSitemapIndex.example.jsx',
+          language: 'js',
+        },
+        {
+          title: 'TypeScript',
+          code: './getSitemapIndex.example.tsx',
+          language: 'ts',
+        },
+      ],
+      title: 'Example code',
+    },
+  },
+  definitions: [
+    {
+      title: 'getSitemapIndex',
+      type: 'GetSitemapIndexGeneratedType',
+      description: '',
+    },
+  ],
+};
+
+export default data;

packages/hydrogen/src/sitemap/getSitemapIndex.example.jsx

@@ -0,0 +1,21 @@
+import {unstable__getSitemapIndex as getSitemapIndex} from '@shopify/hydrogen';
+
+export async function loader({request, context: {storefront}}) {
+  const response = await getSitemapIndex({
+    storefront,
+    request,
+    types: [
+      'products',
+      'pages',
+      'collections',
+      'metaObjects',
+      'articles',
+      'blogs',
+    ],
+  });
+
+  // Set any custom headers on the sitemap response
+  response.headers.set('Cache-Control', `max-age=${60 * 60 * 24}`);
+
+  return response;
+}

packages/hydrogen/src/sitemap/getSitemapIndex.example.tsx

@@ -0,0 +1,25 @@
+import type {LoaderFunctionArgs} from '@shopify/remix-oxygen';
+import {unstable__getSitemapIndex as getSitemapIndex} from '@shopify/hydrogen';
+
+export async function loader({
+  request,
+  context: {storefront},
+}: LoaderFunctionArgs) {
+  const response = await getSitemapIndex({
+    storefront,
+    request,
+    types: [
+      'products',
+      'pages',
+      'collections',
+      'metaObjects',
+      'articles',
+      'blogs',
+    ],
+  });
+
+  // Set any custom headers on the sitemap response
+  response.headers.set('Cache-Control', `max-age=${60 * 60 * 24}`);
+
+  return response;
+}