astro-loader-github-prs

This package provides a GitHub PRs loader for Astro, fetching pull requests with a 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. For ^4.14.0, enable the experimental content layer in astro.config.ts:

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

In src/content/config.ts (for ^4.14.0) or src/content.config.ts (for ^5.0.0), 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")
---

{
  prs.map(async (pr) => {
    const { Content } = await render(pr)
    return (
      <div>
        <a href={pr.data.url}>
          {pr.data.repository.nameWithOwner} - #{pr.data.number}
        </a>
        <p set:html={pr.data.titleHTML} />
        <Content />
        {/* <div set:html={pr.data.bodyHTML}></div> */}
      </div>
    )
  })
}

To update the data, trigger a site rebuild (e.g., using a third-party cron job service), 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 (default)	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.
monthsBack	number	The number of recent months to load pull requests, including the current month. The loader automatically converts this to a date for the 'created' qualifier in the search query. If the 'created' qualifier is defined in search option, it will override this value.
githubToken	string (Defaults to the GITHUB_TOKEN environment variable)	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.
clearStore	boolean (default: false)	Whether to clear the store scoped to the collection before storing newly loaded data.

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 these schemas to generate TypeScript interfaces, enabling autocompletion and type-checking for collection queries. If you customize the collection schema, ensure compatibility with the loader's built-in Zod schema to prevent errors. For additional fields, consider opening an issue.

Changelog

See CHANGELOG.md for the change history of this loader.

Contribution

If you see any errors or room for improvement, feel free to open an issues or pull request . Thank you in advance for contributing! ❤️