astro-loader-github-prs

This package provides a GitHub PRs loader for Astro, fetching pull requests via a GitHub search query for use in Astro projects.

Installation

npm install -D astro-loader-github-prs

Usage

To use the Astro loader, ensure Astro version ^4.14.0 || ^5.0.0-beta.0. For ^4.14.0, enable the experimental content layer in astro.config.ts:

export default defineConfig({
  experimental: {
    contentLayer: true,
  },
});

In src/content/config.ts, import and configure the GitHub PRs loader to define a new content collection:

import { defineCollection } from "astro:content";
import { githubPrsLoader } from "astro-loader-github-prs";

const githubPrs = defineCollection({
  loader: githubPrsLoader({
    search: 'author:username created:>=2024-10-01',
  }),
});

export const collections = { githubPrs };

Query the content collection like any other Astro content collection to render the loaded GitHub PRs:

---
import { getCollection } from "astro:content";

const prs = await getCollection("githubPrs");
---

<ul>
  {
    prs.map((pr) => (
      <li>
        <a href={pr.data.url}>{pr.data.title} - {pr.data.repository.nameWithOwner}</a>
      </li>
    ))
  }
</ul>

To update the data, trigger a site rebuild, as the loader fetches data only at build time.

Configuration

The loader fetches PRs via the GitHub GraphQL API with a search string, requiring a repo-scoped PAT, and returns up to 1,000 results. Options include:

| Option (* required) | Type (defaults) | Description | | ------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | search* | string | The search string for querying pull requests on GitHub. This string will be concatenated with type:pr to form the complete search query. See how to search pull requests. For examples:'author:xxx created:>=2024-01-01': matches prs written by xxx that were created after 2024.'author:xxx -user:xxx': matches prs written by xxx, but not to their own repositories. | | githubToken | string (defaults: 'import.meta.env.GITHUB_TOKEN') | A GitHub PAT with at least repo scope permissions. Defaults to the GITHUB_TOKEN environment variable. If configured here, keep confidential and avoid public exposure. See how to create one and configure env vars in an Astro project. |

Schema

The Zod schema for the loaded collection entries is defined as follows:

const GithubPrSchema = z.object({
  id: z.string(),
  url: z.string(),
  title: z.string(),
  titleHTML: z.string(),
  number: z.number(),
  state: z.enum(['CLOSED', 'MERGED', 'OPEN']),
  isDraft: z.boolean(),
  body: z.string(),
  bodyHTML: z.string(),
  bodyText: z.string(),
  author: z.object({
    login: z.string(),
    url: z.string(),
    avatarUrl: z.string(),
  }),
  repository: z.object({
    name: z.string(),
    nameWithOwner: z.string(),
    url: z.string(),
    stargazerCount: z.number(),
    isInOrganization: z.boolean(),
    owner: z.object({
      login: z.string(),
      url: z.string(),
      avatarUrl: z.string(),
    }),
  }),
  createdAt: z.string(),
  mergedAt: z.string(),
})

Astro automatically applies this schema to generate TypeScript interfaces, providing full support for autocompletion and type-checking when querying the collection.

If you need to customize the collection schema, ensure it remains compatible with the built-in Zod schema to avoid errors. For additional fields you'd like to fetch, feel free to open an issue.