Add auto-detection of route param naming

Author: delucis

.changeset/young-cases-matter.md

@@ -0,0 +1,19 @@
+---
+'astro-og-canvas': minor
+---
+
+Adds auto-detection for the route parameter name to `OGImageRoute()`.
+
+**⚠️ BREAKING CHANGE:** The `param` option to `OGImageRoute()` has been removed and your code should be updated to remove it:
+
+```diff
+export const { getStaticPaths, GET } = await OGImageRoute({
+- param: 'slug',
+  pages: {
+    // ...
+  },
+  getImageOptions: () => {/* ... */},
+});
+```
+
+`astro-og-canvas` now detects the `param` value from your image endpoint’s filename automatically.

demo/src/pages/background-test/[path].ts

@@ -4,7 +4,6 @@ const logoPath = './src/astro-docs-logo.png';
 const bgPath = './src/bgPattern.png';
 
 export const { getStaticPaths, GET } = await OGImageRoute({
-  param: 'path',
   pages: {
     'contain.md': {
       bgImage: { path: bgPath, fit: 'contain' },

demo/src/pages/font-test/[path].ts

@@ -2,7 +2,6 @@ import { OGImageRoute } from 'astro-og-canvas';
 import { pages } from './_pages';
 
 export const { getStaticPaths, GET } = await OGImageRoute({
-  param: 'path',
   pages,
   getImageOptions: (_path, page) => ({
     title: page.title,

demo/src/pages/formats/[path].ts

@@ -1,7 +1,6 @@
 import { OGImageRoute, type OGImageOptions } from 'astro-og-canvas';
 
 export const { getStaticPaths, GET } = await OGImageRoute({
-  param: 'path',
   pages: {
     'png.md': {
       title: 'Test image (PNG)',

demo/src/pages/local-font-test/[path].ts

@@ -1,7 +1,6 @@
 import { OGImageRoute } from 'astro-og-canvas';
 
 export const { getStaticPaths, GET } = await OGImageRoute({
-  param: 'path',
   pages: {
     'local.md': {
       title: 'Local fonts',

demo/src/pages/og/[...route].ts

@@ -2,7 +2,6 @@ import type { MarkdownInstance } from 'astro';
 import { OGImageRoute } from 'astro-og-canvas';
 
 export const { getStaticPaths, GET } = await OGImageRoute({
-  param: 'route',
   pages: import.meta.glob<MarkdownInstance<{ title?: string; description?: string }>>(
     '/src/pages/**/*.md',
     { eager: true }

packages/astro-og-canvas/README.md

@@ -14,13 +14,6 @@ npm i astro-og-canvas
 pnpm i canvaskit-wasm
 ```
 
-## Version compatibility
-
-| astro  | astro-og-canvas                                                                               |
-| ------ | --------------------------------------------------------------------------------------------- |
-| `≤2.x` | [`0.1.x`](https://github.com/delucis/astro-og-canvas/blob/astro-og-canvas%400.1.8/README.md)  |
-| `≥3.x` | [`≥0.2.x`](https://github.com/delucis/astro-og-canvas/blob/astro-og-canvas%400.2.0/README.md) |
-
 ## Usage
 
 ### Creating an OpenGraph image endpoint
@@ -35,10 +28,6 @@ pnpm i canvaskit-wasm
    import { OGImageRoute } from 'astro-og-canvas';
 
    export const { getStaticPaths, GET } = await OGImageRoute({
-     // Tell us the name of your dynamic route segment.
-     // In this case it’s `route`, because the file is named `[...route].ts`.
-     param: 'route',
-
      // A collection of pages to generate images for.
      // The keys of this object are used to generate the path for that image.
      // In this example, we generate one image at `/open-graph/example.png`.
@@ -79,10 +68,6 @@ const collectionEntries = await getCollection('my-collection');
 const pages = Object.fromEntries(collectionEntries.map(({ slug, data }) => [slug, data]));
 
 export const { getStaticPaths, GET } = await OGImageRoute({
-  // Tell us the name of your dynamic route segment.
-  // In this case it’s `route`, because the file is named `[...route].ts`.
-  param: 'route',
-
   pages: pages,
 
   getImageOptions: (path, page) => ({
@@ -102,10 +87,6 @@ In the following example, every Markdown file in the project’s `src/pages/` di
 import { OGImageRoute } from 'astro-og-canvas';
 
 export const { getStaticPaths, GET } = await OGImageRoute({
-  // Tell us the name of your dynamic route segment.
-  // In this case it’s `route`, because the file is named `[...route].ts`.
-  param: 'route',
-
   // Pass the glob result to pages
   pages: await import.meta.glob('/src/pages/**/*.md', { eager: true }),
 

packages/astro-og-canvas/src/routing.ts

@@ -1,4 +1,5 @@
 import type { APIRoute, GetStaticPaths } from 'astro';
+import { AstroError } from 'astro/errors';
 import { generateOpenGraphImage } from './generateOpenGraphImage.js';
 import type { OGImageOptions } from './types';
 
@@ -13,7 +14,6 @@ const pathToSlug = (path: string, _page: any, imageOptions: OGImageOptions): str
 
 async function makeGetStaticPaths({
   pages,
-  param,
   getSlug = pathToSlug,
   getImageOptions,
 }: OGImageRouteConfig<any>): Promise<GetStaticPaths> {
@@ -22,14 +22,14 @@ async function makeGetStaticPaths({
       const imageOptions = await getImageOptions(...page);
       const slug = getSlug(...page, imageOptions);
       return { slug, imageOptions };
-    })
+    }),
   );
-  const paths = entries.map(({ slug, imageOptions }) => ({
-    params: { [param]: slug },
-    props: { imageOptions },
-  }));
-  return function getStaticPaths() {
-    return paths;
+  return function getStaticPaths({ routePattern }) {
+    const param = routePatternToParam(routePattern);
+    return entries.map(({ slug, imageOptions }) => ({
+      params: { [param]: slug },
+      props: { imageOptions },
+    }));
   };
 }
 
@@ -51,7 +51,37 @@ export async function OGImageRoute<T>(opts: OGImageRouteConfig<T>): Promise<{
 
 interface OGImageRouteConfig<T extends unknown> {
   pages: { [path: string]: T };
-  param: string;
   getSlug?: (path: string, page: T, imageOptions: OGImageOptions) => string;
   getImageOptions: (path: string, page: T) => OGImageOptions | Promise<OGImageOptions>;
 }
+
+/**
+ * Converts a `routePattern` from Astro's `getStaticPaths()` to a parameter name.
+ * For example, extracts `slug` from both `/og/[slug].png` and `/og/[...slug].png`.
+ */
+function routePatternToParam(routePattern: string): string {
+  const matches = routePattern.matchAll(/\[(?:\.{3})?(?<param>.+?)\]/g);
+  let param: string | undefined;
+  let paramCount = 0;
+  for (const { groups } of matches) {
+    if (groups?.param) {
+      param = groups.param;
+      paramCount++;
+    }
+  }
+  if (!param) {
+    throw new AstroError(
+      `No parameter found in route: \`${routePattern}\``,
+      'Make sure the open graph image file name contains a dynamic route parameter, e.g. `src/pages/og/[...slug].ts`.\n\n' +
+        'See https://docs.astro.build/en/guides/routing/#dynamic-routes for more information on dynamic routes.',
+    );
+  }
+  if (paramCount > 1) {
+    throw new AstroError(
+      `Multiple parameters found in route: \`${routePattern}\``,
+      'Make sure the open graph image file name only contains one dynamic route parameter, e.g. `src/pages/og/[...slug].ts`.\n\n' +
+        'See https://docs.astro.build/en/guides/routing/#dynamic-routes for more information on dynamic routes.',
+    );
+  }
+  return param;
+}

test/astro-og-canvas.ts

@@ -1,6 +1,7 @@
 import assert from 'node:assert';
 import { readFileSync } from 'node:fs';
 import { describe, test } from 'node:test';
+import { type OGImageOptions, OGImageRoute } from '../packages/astro-og-canvas/dist/index.js';
 
 function loadRoute(path: string): string {
   const rel = `../demo/dist/${path}/index.html`.replaceAll(/\/{2,}/g, '/');
@@ -27,3 +28,49 @@ describe('build output', () => {
     assert.notEqual(buff.length, 0);
   });
 });
+
+describe('OGImageRoute', () => {
+  const imageOptions: OGImageOptions = { title: 'Test' };
+  const routeConfig: Parameters<typeof OGImageRoute>[0] = {
+    pages: { example: {} },
+    getImageOptions: () => imageOptions,
+  };
+
+  test('it should create static paths from config', async () => {
+    const { getStaticPaths } = await OGImageRoute(routeConfig);
+    const paths = await getStaticPaths({ routePattern: '/og/[slug].png' } as any);
+    assert.deepStrictEqual(paths, [{ params: { slug: 'example.png' }, props: { imageOptions } }]);
+  });
+
+  test('it should detect param name from routePattern', async () => {
+    const { getStaticPaths } = await OGImageRoute(routeConfig);
+    const [slugPath] = await getStaticPaths({ routePattern: '/og/[slug].png' } as any);
+    assert.equal(slugPath.params.slug, 'example.png');
+    const [routePath] = await getStaticPaths({ routePattern: '/og/[route].png' } as any);
+    assert.equal(routePath.params.route, 'example.png');
+  });
+
+  test('it should detect param name from routePattern with spread', async () => {
+    const { getStaticPaths } = await OGImageRoute(routeConfig);
+    const [slugPath] = await getStaticPaths({ routePattern: '/og/[...slug].png' } as any);
+    assert.equal(slugPath.params.slug, 'example.png');
+    const [routePath] = await getStaticPaths({ routePattern: '/og/[...route].png' } as any);
+    assert.equal(routePath.params.route, 'example.png');
+  });
+
+  test('it should throw if route pattern has no parameter', async () => {
+    const { getStaticPaths } = await OGImageRoute(routeConfig);
+    await assert.rejects(
+      async () => getStaticPaths({ routePattern: '/og/index' } as any),
+      /No parameter found in route: `\/og\/index`/,
+    );
+  });
+
+  test('it should throw if route pattern has multiple parameters', async () => {
+    const { getStaticPaths } = await OGImageRoute(routeConfig);
+    await assert.rejects(
+      async () => getStaticPaths({ routePattern: '/og/[slug]/[id]' } as any),
+      /Multiple parameters found in route: `\/og\/\[slug\]\/\[id\]`/,
+    );
+  });
+});