Custom helper functions from integration for getStaticPaths()

[openscript]

Summary

getStaticPaths() provides a helper function called paginate. I propose making it possible for integrations to provide additional functions like paginate.

Background & Motivation

With getStaticPaths(), the props and params are crafted for each page. Out of the box, Astro already provides a paginate function to handle pagination. This is convenient, as not every project needs to implement this relatively complex requirement from scratch.

However, projects often have other needs beyond pagination — for example, internationalization or grouping logic.

A common use case is internationalization, where translated pages need to be generated based on a content collection. Today, a typical approach is to provide a custom function called from within getStaticPaths():

export const getStaticPaths = async () => {
  const routePattern = "[...locale]/[files]/[slug]";
  const collection = await getCollection("files");

  return i18nPropsAndParams(collection, {
    defaultLocale: C.DEFAULT_LOCALE,
    segmentTranslations: C.SEGMENT_TRANSLATIONS,
    routePattern,
  });
};

The downside of this approach is that such helper functions don't have access to the same context or capabilities as the built-in paginate function. This limits their utility.

That’s why I propose making it possible for integrations to provide custom utilities—similar to paginate—which can be used within getStaticPaths() and have access to the same context.

Goals

• Make getStaticPaths() extensible from integrations
• Reduce repetition in getStaticPaths() implementations
• Improve reusability of common logic within getStaticPaths()
• Enable better testability for reusable getStaticPaths() logic

Example

// my-i18n-integration.ts
import type { AstroIntegration } from 'astro';

export default function i18nIntegration(): AstroIntegration {
  return {
    name: 'my-i18n',
    hooks: {
      'astro:config:setup': ({ injectGetStaticPathsHelper }) => {
        injectGetStaticPathsHelper({
          name: 'i18n',
          handler: ({ collection, context }) => { // config => Astro Context
            // Example i18n helper
            return collection.flatMap((entry) => {
              return context.config.locales.map((locale) => ({
                params: { locale, slug: entry.slug },
                props: { entry, locale },
              }));
            });
          },
        });
      },
    },
  };
}

export const getStaticPaths = async ({ helpers, paginate }) => {
  const collection = await getCollection('docs');

  return helpers.i18n({
    collection,
  });
};