npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

astro-loader-github-releases

v1.4.1

Published

Astro loader for loading GitHub releases from a user's commit history or a list of repositories.

Downloads

714

Readme

astro-loader-github-releases

version jsDocs.io npm downloads showcase

This package provides a GitHub releases loader for Astro. The loader supports two configurable modes, allowing you to load public GitHub releases either from a user's commit history or a list of repositories.

Installation

npm install -D astro-loader-github-releases

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 loader to define a new content collection:

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

const githubReleases = defineCollection({
  loader: githubReleasesLoader({
    loadMode: /* 'userCommit' or 'repoList' */,
    modeConfig: {/* Config options based on `loadMode`. See below. */},
  }),
})

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 `loadMode`. See below. -->
<ul>
  {
    releases.map((release) => (
      <li>
        <a href={release.data.url}>{release.data.repoNameWithOwner} - {release.data.tagName}</a>
      </li>
    ))
  }
</ul>

repoList mode supports rendering 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 releases = await getCollection("githubReleases")
---
<!-- entryReturnType: 'byRepository' -->
{
  releases.map((repo) => (
    <div>
      <p>{repo.data.repo}</p>
      {repo.data.repoReleases.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.

Configuration

The githubReleasesLoader function takes an object with the following options:

| Option (* required) | Type | Description | | ------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------- | | loadMode* | 'userCommit' \| 'repoList' | Specifies the method to fetch GitHub releases (corresponding to different entries' Zod Schema). | | modeConfig* | Record<string, any> | Configures options for the selected loadMode. |

userCommit Mode

The loader uses the GitHub REST API (GET /users/{username}/events/public) to fetch up to 300 events from the past 90 days (with a latency of 30 seconds to 6 hours). If tagNameRegex matches, the commit will be considered a release. This mode is useful for users who want to show their recent release activities. The modeConfig options includes:

| Option (* required) | Type (default) | Description | | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | username* | string | The unique username used to identify a specific GitHub account. | | tagNameRegex | string(default: 'v?(\\d+\\.\\d+\\.\\d+(?:-[\\w.]+)?)(?:\\s\|$)') | Regular expression for matching tag name in commit messages. The first capturing group in the regex will be used as versionNum field. | | keyword | string(default: 'release') | The keyword to filter push events' commit messages for releases. Can be empty, meaning no filtering. | | branches | string[] (default: ['refs/heads/main', 'refs/heads/master', 'refs/heads/latest', 'refs/heads/stable', 'refs/heads/release', 'refs/heads/dev']) | The branches to monitor for push events. Filters out activities from other forks based on these refs. |

repoList Mode

The loader fetches GitHub releases from specified repositories via the GitHub GraphQL API, requiring a GitHub PAT with repo scope for authentication. By default, it retrieves all releases from the listed repositories, ideal for displaying data grouped by repository. The modeConfig options includes:

| Option (* required) | Type (default) | Description | | ------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | repos* | string[] | The repositories from which to load releases, each formatted as 'owner/repo'. | | sinceDate | Date \| string (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. | | githubToken | string (Defaults to the GITHUB_TOKEN environment variable) | 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. |

Schema

The Zod schema for the entries in the loaded collection is defined below.

userCommit Mode

const ReleaseByIdFromUserSchema = z.object({
  id: z.string(),
  url: z.string(),
  tagName: z.string(),
  versionNum: z.string(),
  repoOwner: z.string(),
  repoName: z.string(),
  repoNameWithOwner: z.string(),
  repoUrl: z.string(),
  commitMessage: z.string(),
  commitSha: z.string(),
  commitUrl: z.string(),
  actorLogin: z.string(),
  actorAvatarUrl: z.string(),
  isOrg: z.boolean(),
  orgLogin: z.string().optional(),
  orgAvatarUrl: z.string().optional(),
  createdAt: z.string(),
})

repoList Mode

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

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

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