feat: sitemap implementation (#166)

* feature: add sitemap services, utils and parsers. add sitemap path to nextJS.

* refactor: update test cases

* refactor: update the function names, fix static sitemap generation

* refactor: revert logger test case fixes

* fix: NODE_ENV type

* feat: add time bases revalidation

* feat: keep time based revalidation to 0 so sitemaps are generated dynamically always

* refactor: remove duplicated deps, rename sitemap.config to sitemapConfig, explicitly mentioning exporting members from script

* chore: add link to sitemap() docblock

* refactor: config keys.

* refactor: replace @link annotation with @see

* refactor: replace export { generateSitemap } with function

* refactor: rename sitemap_index.xml to sitemap.xml, move SitemapDataFromXML from types package to types.ts

* refactor: remove types from @return and @param

* refactor: rename sitemap.xml to sitemap_index.xml because paths are conflicting

* refactor: rename sitemap_index.xml to wp-sitemap.xml

* doc: add sitemap.md doc and update config-api.md doc

* chore: add unit tests for the next sitemap module

* chore: update test cases for sitemap generation, wrap getSitemapPaths in try/catch block

* chore: npm run format

* chore: cleanup

* chore: npm run format

* chore: update docs

* docs: modify doc to make it more accurate

* docs: clarify `SitemapConfig.customPaths`

* fix: deep merge issue with sitemap

* doc: add link to the MetadataRoute.SiteMap interface

* chore: update docs format

* fix: test cases

* refactor: remove if-else-if ladder

---------

Co-authored-by: Dovid Levine <david@axepress.dev>

Author: SH4LIN

README.md

@@ -61,6 +61,8 @@ SnapWP provides several plugins, packages, and libraries that can be used indivi
 -   [Template Rendering System](docs/template-rendering.md)
 -   [Handling HTTP Status Codes](docs/http-status-codes.md)
 -   [Resolving CORS Issues](docs/cors.md)
+-   [Handling Sitemap Generation](docs/sitemap.md)
+-   [Using the Query Engine](docs/query-engine.md)
 
 ## Development & Contributing
 

docs/config-api.md

@@ -69,6 +69,7 @@ Here are the available configuration options:
 | `blockDefinitions` | `BlockDefinitions`       | [blocks](../packages/blocks/src/blocks/index.ts)                           | Block definitions for the editor.<br />[Learn more](./overloading-wp-behavior.md#overloading-blocks)                                            |
 | `parserOptions`    | `HTMLReactParserOptions` | [defaultOptions](../packages/next/src/react-parser/options.tsx)            | The default options for the `html-react-parser` library.<br />[Learn more](./overloading-wp-behavior.md#2-pass-customparseroptions-to-overload) |
 | `query`            | `QueryEngine`            | [ApolloClientEngine](../packages/plugin-apollo-client/src/engine/index.ts) | Configuration for the GraphQL query engine.<br />See below for more details on how to customize it.[Learn more](./query-engine.md)              |
+| `sitemap`          | `SitemapConfig`          | undefined                                                                  | Configuration for the sitemap plugin.<br />[Learn more](./sitemap.md)                                                                           |
 
 Config values are available via their respective keys in the `getConfig()` function.
 
@@ -139,6 +140,16 @@ export default config;
 
 This configuration allows you to replace the default engine with your custom engine. For more information about creating a custom query engine, see [Creating a Custom Query Engine](./query-engine.md#creating-a-custom-query-engine).
 
+### `sitemap` Configuration
+
+Sitemap behavior is controllable vis the `sitemap` configuration object. The following are the available options:
+
+| **Property**     | **Type**                        | **Default Value** | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| ---------------- | ------------------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `indexUri`       | `string`                        | `/wp-sitemap.xml` | The URI of the WordPress index sitemap.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `ignorePatterns` | `string[]`                      | `undefined`       | An array of regex patterns used to exclude specific URLs from the sitemap.<br /><br />**Important:** These patterns are matched against the WordPress URLs of each post or page — not your frontend (e.g., Next.js) URLs. For example, if your WordPress site is hosted at `https://example.com` and a post URL is `https://example.com/blog/my-post`, a pattern like `/\/blog\//` or `/my-post$/` will work, while `/localhost:3000/blog/my-post/` will not.                                                                                                                                                                                                                                         |
+| `customPaths`    | `Record<string, SitemapData[]>` | `undefined`       | Arrays of SitemapData, keyed to their sub-sitemap names. This allows you to add custom or overload WordPress-generated sub-sitemaps.<br /> <br />The keys should match the sub-sitemap names as defined in the WordPress sitemap index. For example, if the WordPress sub-sitemap URL you are overriding is `http://mysite.local/wp-sitemap-posts-page-1.xml`, the key should be `wp-sitemap-posts-page-1`.<br /> <br />The `SitemapData` is a subset of [NextJS's MetadataRoute.SiteMap](https://github.com/vercel/next.js/blob/47eda30f1ab5ff8fc97802643125b4ce19cac14e/packages/next/src/lib/metadata/types/metadata-interface.ts#L687). The `images` and `videos` properties are _not_ supported. |
+
 ## Integration with `next.config.ts`
 
 SnapWP extends the Next.js configuration using the `withSnapWP` function to configure certain settings automatically based on your Config API, such as using the WordPress URL for [`images.remotePatterns`](https://nextjs.org/docs/app/api-reference/components/image#remotepatterns).

docs/sitemap.md

@@ -0,0 +1,69 @@
+# Sitemap
+
+By default, SnapWP uses WordPress's built-in sitemap as the source of truth for generating sitemaps. The sitemap is built using data fetched directly from your WordPress backend and updates automatically.
+
+## Index Sitemap
+
+In the example Next.js starter app, the main sitemap is available at `/wp-sitemap.xml`, just like WordPress default.
+
+### How to Change the Index Sitemap Path in Next.js
+
+If you'd like to change the path (e.g., to `/sitemap_index.xml`), follow these steps:
+
+1. Create a directory in `app/` named `sitemap_index.xml`.
+2. Inside it, create a file named `route.ts`.
+3. Add the following logic:
+
+```ts
+// route.ts
+
+import { NextResponse } from 'next/server';
+import { generateIndexSitemap } from '@snapwp/next';
+
+export async function GET(): Promise< NextResponse > {
+	const sitemaps = await generateIndexSitemap();
+
+	const xml = buildXmlFromSitemaps( sitemaps ); // Build <sitemapindex> XML from list
+
+	return new NextResponse( xml, {
+		headers: {
+			'Content-Type': 'application/xml',
+		},
+	} );
+}
+```
+
+> [!Note]
+> The function `generateIndexSitemap()` returns an array of sitemap objects. You can map over them to build the final XML structure.
+
+## Sub-sitemaps
+
+SnapWP supports automatic generation of sub-sitemaps (for posts, pages, custom post types, etc.) using the `app/sitemap.ts` file.
+
+### File: `app/sitemap.ts`
+
+```ts
+// app/sitemap.ts
+
+import type { MetadataRoute } from 'next';
+import { getSitemapPaths, generateSubSitemaps } from '@snapwp/next';
+
+// This function returns an array of sitemap IDs from WordPress
+export const generateSitemaps = async () => {
+	return await getSitemapPaths();
+};
+
+// This function generates the XML for each sitemap based on the ID
+export default async function sitemap( { id }: { id: string } ) {
+	return await generateSubSitemaps( id );
+}
+
+// Always render fresh sitemap content
+export const revalidate = 0;
+```
+
+### What Each Function Does
+
+-   **`getSitemapPaths()`** → Fetches all available sitemap IDs (e.g., `wp-sitemap-posts-post-1`, `wp-sitemap-pages-page-1`) from the WordPress sitemap index.
+-   **`generateSubSitemaps(id)`** → Generates the XML content for the specified sitemap ID by fetching the sub-sitemap and mapping the URLs.
+-   **`revalidate = 0`** → Disables static caching to ensure the sitemap is always generated fresh on every request.

examples/nextjs/starter/src/app/sitemap.ts

@@ -0,0 +1,37 @@
+import type { MetadataRoute } from 'next';
+import { getSitemapPaths, generateSubSitemaps } from '@snapwp/next';
+
+/**
+ * Returns Sitemap IDs to be dynamically generated.
+ *
+ * https://nextjs.org/docs/app/api-reference/file-conventions/metadata/sitemap#generating-multiple-sitemaps
+ *
+ * @return An array of Sitemap IDs.
+ */
+export const generateSitemaps = async (): Promise<
+	Array< { id: string } >
+> => {
+	return await getSitemapPaths();
+};
+
+/**
+ * Generate a sitemap for a specific path.
+ *
+ * @see https://nextjs.org/docs/app/api-reference/file-conventions/metadata/sitemap
+ *
+ * @param root0 - The object containing the sitemap ID.
+ * @param root0.id - The ID of the sitemap to generate.
+ *
+ * @return The generated sitemap.
+ */
+export default async function sitemap( {
+	id,
+}: {
+	id: string;
+} ): Promise< MetadataRoute.Sitemap > {
+	return await generateSubSitemaps( id );
+}
+
+// @todo: This will be replaced with on-demand revalidation using revalidateTag or revalidatePath once webhooks are implemented.
+// Keeping revalidation to 0 to render it dynamically always.
+export const revalidate = 0;

examples/nextjs/starter/src/app/wp-sitemap.xml/route.ts

@@ -0,0 +1,30 @@
+import { NextResponse } from 'next/server';
+import { generateIndexSitemap } from '@snapwp/next';
+
+/**
+ * Generate a sitemap index for all sitemaps.
+ *
+ * @return The generated sitemap index.
+ */
+export async function GET(): Promise< NextResponse > {
+	const sitemaps = await generateIndexSitemap();
+
+	const xml = `<?xml version="1.0" encoding="UTF-8"?>
+		<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+			${ sitemaps
+				.map(
+					( sitemap ) => `
+						<sitemap>
+							<loc>${ sitemap.url }</loc>
+						</sitemap>
+					`
+				)
+				.join( '' ) }
+		</sitemapindex>`;
+
+	return new NextResponse( xml, {
+		headers: {
+			'Content-Type': 'application/xml',
+		},
+	} );
+}

package-lock.json

@@ -3,7 +3,11 @@
 import { Logger } from '@/logger';
 import { generateGraphqlUrl, isValidUrl } from '@/utils';
 
-import type { BlockDefinitions, QueryEngine } from '@snapwp/types';
+import type {
+	BlockDefinitions,
+	QueryEngine,
+	SitemapConfig,
+} from '@snapwp/types';
 import type { HTMLReactParserOptions } from 'html-react-parser';
 
 export interface SnapWPEnv {
@@ -46,6 +50,10 @@ export interface SnapWPConfig {
 	 * html-react-parser overload options
 	 */
 	parserOptions?: HTMLReactParserOptions;
+	/**
+	 * Sitemap configuration.
+	 */
+	sitemap?: SitemapConfig;
 	/**
 	 * Query Engine
 	 */
@@ -79,6 +87,9 @@ const defaultConfig: Partial< SnapWPEnv & SnapWPConfig > = {
 	graphqlEndpoint: 'index.php?graphql',
 	restUrlPrefix: '/wp-json',
 	uploadsDirectory: '/wp-content/uploads',
+	sitemap: {
+		indexUri: '/wp-sitemap.xml',
+	},
 };
 
 /**
@@ -138,6 +149,30 @@ class SnapWPConfigManager {
 			type: 'object',
 			required: false,
 		},
+		sitemap: {
+			type: 'object',
+			required: false,
+			/**
+			 * Validate the sitemap configuration.
+			 *
+			 * @param {SitemapConfig} value The sitemap configuration to validate.
+			 *
+			 * @throws {Error} If the value is invalid.
+			 */
+			validate( value ) {
+				if ( value && typeof value !== 'object' ) {
+					throw new Error( '`sitemap` should be an object.' );
+				}
+
+				if (
+					value &&
+					value.indexUri &&
+					typeof value.indexUri !== 'string'
+				) {
+					throw new Error( '`sitemap.indexUri` should be a string.' );
+				}
+			},
+		},
 		query: {
 			type: 'object',
 			required: true,
@@ -254,7 +289,10 @@ class SnapWPConfigManager {
 			( key: keyof T ) => {
 				if ( cfg[ key ] === undefined ) {
 					delete cfg[ key ];
-				} else if (
+					return;
+				}
+
+				if (
 					// @todo this should probably be moved into the schema as a sanitize callback.
 					( key === 'wpHomeUrl' ||
 						key === 'frontendUrl' ||
@@ -266,6 +304,15 @@ class SnapWPConfigManager {
 					cfg[ key ] = ( value.endsWith( '/' )
 						? value.slice( 0, -1 )
 						: value ) as unknown as T[ keyof T ];
+
+					return;
+				}
+
+				if ( key === 'sitemap' ) {
+					cfg[ key ] = {
+						...defaultConfig.sitemap,
+						...( cfg[ key ] as SitemapConfig ),
+					} as unknown as T[ keyof T ];
 				}
 			}
 		);

packages/core/src/config/snapwp-config-manager.ts

@@ -3,6 +3,7 @@ import {
 	getConfig,
 	getGraphqlUrl,
 	setConfig,
+	type SnapWPConfig,
 	type SnapWPEnv,
 } from '@/config/snapwp-config-manager';
 import { Logger } from '@/logger';
@@ -29,12 +30,15 @@ describe( 'SnapWPConfigManager functions', () => {
 		restUrlPrefix: '/env-wp-json',
 	};
 
-	const defaultConfig: Partial< SnapWPEnv > = {
+	const defaultConfig: Partial< SnapWPEnv & SnapWPConfig > = {
 		corsProxyPrefix:
 			process.env.NODE_ENV === 'development' ? '/proxy' : undefined,
 		graphqlEndpoint: 'index.php?graphql',
 		uploadsDirectory: '/wp-content/uploads',
 		restUrlPrefix: '/wp-json',
+		sitemap: {
+			indexUri: '/wp-sitemap.xml',
+		},
 	};
 
 	beforeEach( () => {

packages/core/src/config/tests/snapwp-config-manager.test.tsx

@@ -0,0 +1,9 @@
+global.__snapWPConfig = {};
+
+global.__envConfig = {
+	frontendUrl: 'https://example.com',
+	wpHomeUrl: 'https://wp.example.com',
+};
+
+process.env.NEXT_PUBLIC_FRONTEND_URL = global.__envConfig.frontendUrl;
+process.env.NEXT_PUBLIC_WP_HOME_URL = global.__envConfig.wpHomeUrl;

packages/next/jest.setup.js

@@ -56,7 +56,8 @@
 		"html-react-parser": "^5.1.12",
 		"modify-source-webpack-plugin": "^4.1.0",
 		"sanitize-html": "^2.15.0",
-		"zod": "^3.24.2"
+		"zod": "^3.24.2",
+		"fast-xml-parser": "^5.2.1"
 	},
 	"devDependencies": {
 		"@snapwp/types": "*",