tessl/npm-gatsby-plugin-sitemap

Gatsby plugin that automatically creates XML sitemaps for your site during the production build process

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Gatsby Plugin Hooks

Name: tessl/npm-gatsby-plugin-sitemap
Author: tessl

Implementation of Gatsby's plugin lifecycle hooks for sitemap generation and HTML head integration.

Capabilities

onPostBuild Hook

Main plugin hook that generates sitemap files during the production build process.

/**
 * Gatsby onPostBuild hook - generates sitemap files after all pages are built
 * @param context - Gatsby build context
 * @param context.graphql - Function to execute GraphQL queries
 * @param context.reporter - Gatsby reporter for logging
 * @param context.basePath - Base path for the site
 * @param context.pathPrefix - Path prefix for the site
 * @param options - Plugin configuration options
 * @returns Promise that resolves when sitemap generation is complete
 */
exports.onPostBuild = async (
  { graphql, reporter, basePath, pathPrefix },
  {
    output,
    entryLimit,
    query,
    excludes,
    resolveSiteUrl,
    resolvePagePath,
    resolvePages,
    filterPages,
    serialize,
  }
) => Promise<void>;

Hook Process:

Executes the configured GraphQL query
Resolves the site URL using resolveSiteUrl
Extracts pages using resolvePages
Filters pages based on excludes and filterPages
Serializes pages using serialize
Generates sitemap files using the sitemap library

Error Handling: The hook throws errors and uses reporter.panic for:

GraphQL query execution failures
Site URL resolution failures
Page resolution failures
Non-array results from resolvePages
Page serialization failures

Usage Example:

// This hook is automatically called by Gatsby - no direct usage required
// Configuration is done through gatsby-config.js plugin options

onRenderBody Hook

Adds sitemap link element to HTML head when createLinkInHead option is enabled.

/**
 * Gatsby onRenderBody hook - adds sitemap link to HTML head
 * @param context - Gatsby SSR context
 * @param context.setHeadComponents - Function to add elements to HTML head
 * @param pluginOptions - Plugin configuration options
 * @param pluginOptions.output - Output directory for sitemaps
 * @param pluginOptions.createLinkInHead - Whether to create the link element
 */
exports.onRenderBody = ({ setHeadComponents }, { output, createLinkInHead }) => void;

Generated HTML:

<link
  rel="sitemap"
  type="application/xml"
  href="/sitemap-index.xml"
/>

Usage Example:

// Automatically creates link element when createLinkInHead: true
{
  resolve: 'gatsby-plugin-sitemap',
  options: {
    createLinkInHead: true, // Default: true
    output: '/custom-path', // Affects link href
  }
}

pluginOptionsSchema

Joi validation schema for plugin options that ensures proper configuration.

/**
 * Joi schema for validating plugin options
 * @param joi - Joi validation library instance
 * @returns Joi schema object for plugin options validation
 */
exports.pluginOptionsSchema = ({ Joi }) => JoiSchema;

Validation Rules:

output: String, defaults to /
createLinkInHead: Boolean, defaults to true
entryLimit: Number, defaults to 45000
query: String (must be valid GraphQL), has complex default query
excludes: Array of any type, defaults to []
resolveSiteUrl: Function, defaults to internal resolveSiteUrl
resolvePagePath: Function, defaults to internal resolvePagePath
resolvePages: Function, defaults to internal resolvePages
filterPages: Function, defaults to internal defaultFilterPages
serialize: Function, defaults to internal serialize

GraphQL Query Validation: The schema includes external validation for the query option that parses the GraphQL to ensure it's syntactically valid.

Usage Example:

// Schema is automatically used by Gatsby for option validation
// Validation errors will be thrown during build if options are invalid

// This would cause a validation error:
{
  resolve: 'gatsby-plugin-sitemap',
  options: {
    entryLimit: 'invalid', // Should be number
    query: 'invalid graphql', // Should be valid GraphQL
  }
}

Hook Integration

// Complete hook exports from gatsby-node.js
exports.pluginOptionsSchema = pluginOptionsSchema;
exports.onPostBuild = async (context, options) => {
  // Sitemap generation logic
};

// Complete hook exports from gatsby-ssr.js
exports.onRenderBody = ({ setHeadComponents }, pluginOptions) => {
  // HTML head link injection logic
};

Generated Files

The hooks generate the following files in the public directory:

sitemap-index.xml: Main sitemap index file pointing to individual sitemaps
sitemap-0.xml, sitemap-1.xml, etc.: Individual sitemap files (one per entryLimit entries)
HTML head link: <link rel="sitemap"> element (when createLinkInHead is true)

Dependencies Used by Hooks

// External dependencies used in hook implementations
import { simpleSitemapAndIndex } from 'sitemap'; // XML sitemap generation
import { withPrefix, withAssetPrefix } from 'gatsby'; // Path prefixing
import { posix } from 'path'; // Path utilities