Astro loader for fetching GitHub Pull Requests, supporting both build-time and runtime retrieval.
npm install astro-loader-github-prs[![version][version-badge]][version-link]
[![jsDocs.io][jsdocs-src]][jsdocs-href]
[![npm downloads][npm-downloads-src]][npm-downloads-href]
[![demo][demo-logo]][demo-link]
This package provides GitHub Pull Request (PR) loaders for Astro projects. It includes:
- githubPrsLoader: Loads PRs at build time using a search query.
- liveGithubPrsLoader: Fetches PRs at runtime on each request — multiple PRs by search query or a single PR by its identifier.
``sh`
npm install astro-loader-github-prs
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:
`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 build-time loader to define a new content collection:
`ts
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:
`astro
---
import { getCollection } from "astro:content"
const prs = await getCollection("githubPrs")
---
{
prs.map(async (pr) => {
const { Content } = await render(pr)
return (
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.
$3
Astro 5.10+ introduces experimental live content collections, which allow data fetching at runtime. To use this feature, enable the experimental
flag as shown below, and use an adapter that supports on-demand rendering.`js title="astro.config.mjs"
// astro.config.mjs
export default {
experimental: {
liveContentCollections: true,
},
};
`In
, import and configure the live loader to define a new live content collection:`ts title="src/live.config.ts"
// src/live.config.ts
import { defineLiveCollection } from 'astro:content';
import { liveGithubPrsLoader } from 'astro-loader-github-prs';const liveGithubPrs = defineLiveCollection({
loader: liveGithubPrsLoader(),
});
export const collections = { liveGithubPrs };
`Query at runtime using
or getLiveEntry():`astro
---
export const prerender = false;
import { getLiveCollection, getLiveEntry } from 'astro:content';// Get PRs
const { entries: prs, error } = await getLiveCollection('liveGithubPrs',{
search: 'repo:withastro/astro',
monthsBack: 3,
maxEntries: 50,
});
// Get individual PR
/* const { entry: pr } = await getLiveEntry('liveGithubPrs', {
// by PR node ID
identifier: 'PR_kwDOFL76Q86uDYLC',
// by url
identifier: 'https://github.com/withastro/astro/pull/12345',
// by object
identifier: { owner: 'withastro', repo: 'astro', number: 12345 },
}); */
---
{
error ? (
{error.message}
) : (
{prs?.map((pr) => (
))}
)
}
`Configuration
$3
| Option (* required) | Type (default) | Description |
| ------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
* | 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. |
| maxEntries | number | Maximum number of pull requests to load.
- Based on GitHub GraphQL search max 1,000 results .
- Returns up to maxEntries, or fewer if fewer exist.
- If monthsBack is set and results exceed maxEntries, only maxEntries are returned. |
| clearStore | boolean (default: false) | Whether to clear the store scoped to the collection before storing newly loaded data. |
| 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. |$3
| Option (* required) | Type (default) | Description |
| ------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
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. |$3
| 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. |
| maxEntries | number | Maximum number of pull requests to load.
- Based on GitHub GraphQL search max 1,000 results .
- Returns up to maxEntries, or fewer if fewer exist.
- If monthsBack is set and results exceed maxEntries, only maxEntries are returned. |$3
| Option (* required) | Type (default) | Description |
| ------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
identifier* | string | The identifier for a pull request, which can be one of the following:
- A PR node ID string: "PR_" + 16 Base64 chars.
- A GitHub PR URL.
- An object with fields: owner, repo, number. |Schema
The collection entries use the following Zod schema:
`ts
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
.union([
z.object({
login: z.string(),
name: z.string().optional(),
url: z.string(),
avatarUrl: z.string(),
}),
z.null(),
])
.optional(),
repository: z.object({
name: z.string(),
nameWithOwner: z.string(),
url: z.string(),
stargazerCount: z.number(),
isInOrganization: z.boolean(),
owner: z.object({
login: z.string(),
name: z.string().optional(),
url: z.string(),
avatarUrl: z.string(),
}),
}),
createdAt: z.string(),
mergedAt: z.union([z.string(), z.null()]).optional(),
})
`Astro uses these schemas to generate TypeScript interfaces for autocompletion and type safety. When customizing the collection schema, keep it compatible with the loader’s built-in Zod schema to avoid errors. To request support for new fields, open an issue.
Live Collections Error Handling
Live loaders may fail due to network, API, or validation errors. Handle these errors in your components. The live loader also returns specific error codes:
-
: Missing required filter options.
- COLLECTION_LOAD_ERROR: Failed to load collection.
- ENTRY_LOAD_ERROR`: Failed to load individual entry.See CHANGELOG.md for the change history of this loader.
If you see any errors or room for improvement, feel free to open an issues or pull request . Thank you in advance for contributing! ❤️
[version-badge]: https://img.shields.io/npm/v/astro-loader-github-prs?label=release&style=flat&colorA=080f12&colorB=f87171
[version-link]: https://www.npmjs.com/package/astro-loader-github-prs
[jsdocs-src]: https://img.shields.io/badge/jsdocs-reference-080f12?style=flat&colorA=080f12&colorB=f87171
[jsdocs-href]: https://www.jsdocs.io/package/astro-loader-github-prs
[npm-downloads-src]: https://img.shields.io/npm/dm/astro-loader-github-prs?style=flat&colorA=080f12&colorB=f87171
[npm-downloads-href]: https://npmjs.com/package/astro-loader-github-prs
[demo-logo]: https://img.shields.io/badge/see-demo-080f12?style=flat&colorA=080f12&colorB=f87171
[demo-link]: https://astro-antfustyle-theme.vercel.app/prs/