astro-loader-github-releases

This package provides GitHub releases loaders for Astro projects. It includes:

• githubReleasesLoader – Loads releases from a list of repositories at build time.
• liveGithubReleasesLoader – Fetches releases at runtime on each request — releases from a list of repositories or a single release by its identifier.

Installation

npm install astro-loader-github-releases

Usage

To use the Astro loader, ensure Astro version >=4.14.0. For ^4.14.0, enable the experimental content layer in astro.config.ts:

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

githubReleasesLoader (Build-time Collection)

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:

import { defineCollection } from "astro:content"
import { githubReleasesLoader } from "astro-loader-github-releases"

const githubReleases = defineCollection({
  loader: githubReleasesLoader({
    repos: ['withastro/astro'],
  }),
})

export const collections = { githubReleases }

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

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

const releases = await getCollection("githubReleases")
---
<!-- Entries' Zod Schema varies by `entryReturnType`. -->
<ul>
  {
    releases.map((release) => (
      <li>
        <a href={release.data.url}>{release.data.repoNameWithOwner} - {release.data.tagName}</a>
      </li>
    ))
  }
</ul>

Support rendering of release content:

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

const releases = await getCollection("githubReleases")
---
<!-- entryReturnType: 'byRelease' -->
{
  releases.map(async (release) => {
    const { Content } = await render(release)
    return <Content />
  })
}

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

const repos = await getCollection("githubReleases")
---
<!-- entryReturnType: 'byRepository' -->
{
  repos.map((repo) => (
    <div>
      <p>{repo.data.repo}</p>
      {repo.data.releases.map((release) => {
        return <section set:html={release.descriptionHTML} />
      })}
    </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.

liveGithubReleasesLoader (Live Collection)

To use live content collections, ensure Astro version >=5.10.0 and use an adapter that supports on-demand rendering with astro:env/server runtime support. For ^5.10.0, enable the experimental liveContentCollections flag in astro.config.ts:

export default {
  experimental: {
    liveContentCollections: true,
  },
};

Starting in 6.0.0, this feature is no longer experimental. In src/live.config.ts, import and configure the live loader to define a new live content collection:

import { defineLiveCollection } from 'astro:content';
import { liveGithubReleasesLoader } from 'astro-loader-github-releases/live';

const liveGithubReleases = defineLiveCollection({
  loader: liveGithubReleasesLoader(),
});

export const collections = { liveGithubReleases };

Query at runtime using getLiveCollection() or getLiveEntry():

---
export const prerender = false;
import { getLiveCollection, getLiveEntry } from 'astro:content';

// Get releases
const { entries: releases, error } = await getLiveCollection('liveGithubReleases', {
  repos: ['withastro/astro'],
});

// Get individual release
/* const { entry: release } = await getLiveEntry('liveGithubReleases', {
  // by release node ID
  identifier: 'RE_kwDOFL76Q84O4ieR',

  // by url
  identifier: 'https://github.com/withastro/astro/releases/tag/[email protected]',

  // by object
  identifier: { owner: 'withastro', repo: 'astro', tag: '[email protected]' },
}); */
---

{
  error ? (
    <p>{error.message}</p>
  ) : (
    <div>
      {releases?.map((release) => (
        <div>
          <a href={release.data.url}>{release.data.repoNameWithOwner} - {release.data.tagName}</a>
          {/* Optional `<Content />` from `await render(release)` */}
        </div>
      ))}
    </div>
  )
}

Configuration

githubReleasesLoader Options

| Option (* required) | Type (default) | Description | | ------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | repos* | string[] | The repositories from which to load releases, each formatted as 'owner/repo'. | | sinceDate | Date \| string \| number (If sinceDate and monthsBack are unspecified, load all) | The date from which to start loading releases. See supported date string formats here. For example:"2024-11-01T00:00:00.000Z""2024-11-01""01/11/24" | | monthsBack | number (If sinceDate and monthsBack are unspecified, load all) | The number of recent months to load releases, including the current month. If both monthsBack and sinceDate are specified, the more recent date will be used. | | entryReturnType | 'byRelease' \| 'byRepository' (default: 'byRepository') | Determines whether entries are returned per repository or per individual release item. This option influences the entries' Zod Schema. | | clearStore | boolean (default: false) | Whether to clear the store scoped to the collection before storing newly loaded data. | | githubToken | string (Defaults to GITHUB_TOKEN via import.meta.env) | A GitHub PAT with at least repo scope permissions. If configured here, keep confidential and avoid public exposure. See how to create one and configure env vars in an Astro project. |

liveGithubReleasesLoader Options

| Option | Type (default) | Description | | ------------------------------------------------------------------------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | githubToken | string (Defaults to GITHUB_TOKEN via getSecret()) | A GitHub PAT with at least repo scope permissions. If configured here, keep confidential and avoid public exposure. See how to create one and configure env vars in an Astro project. |

liveGithubReleasesLoader Collection Filters

| Option (* required) | Type (default) | Description | | ------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | repos* | string[] | The repositories from which to load releases, each formatted as 'owner/repo'. | | sinceDate | Date \| string | The date from which to start loading releases. If both monthsBack and sinceDate are specified, the more recent date will be used. | | monthsBack | number | The number of recent months to load releases, including the current month. If both monthsBack and sinceDate are specified, the more recent date will be used. | | entryReturnType | 'byRelease' \| 'byRepository' (default: 'byRepository') | Determines whether entries are returned per repository or per individual release item. This option influences the entries' Zod Schema. |

liveGithubReleasesLoader Entry Filters

| Option (* required) | Type (default) | Description | | ------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | identifier* | string | The identifier for a release, which can be one of the following:- A release node ID string: "RE_" + 16 Base64 chars.- A GitHub release URL.- An object with fields: owner, repo, tagName. |

Schema

The collection entries use the following Zod schema:

// entryReturnType: 'byRelease'
const ReleaseByIdFromReposSchema = z.object({
  id: z.string(),
  url: z.string(),
  name: z.string().optional(),
  tagName: z.string(),
  versionNum: z.string().optional(),
  description: z.string().optional(),
  descriptionHTML: z.string().optional(),
  isDraft: z.boolean(),
  isLatest: z.boolean(),
  isPrerelease: z.boolean(),
  repoOwner: z.string(),
  repoName: z.string(),
  repoNameWithOwner: z.string(),
  repoUrl: z.string(),
  repoStargazerCount: z.number(),
  repoIsInOrganization: z.boolean(),
  createdAt: z.string(),
  publishedAt: z.string().optional(),
})

// entryReturnType: 'byRepository'
const ReleaseByRepoFromReposSchema = z.object({
  repo: z.string(),
  releases: z.array(ReleaseByIdFromReposSchema),
})

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:

• INVALID_FILTER: Missing required filter options.
• COLLECTION_LOAD_ERROR: Failed to load collection.
• ENTRY_LOAD_ERROR: Failed to load individual entry.
• MISSING_TOKEN: No GitHub token provided.

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! ❤️