feat: adding gh changelog/releases to npmx

[WilcoSp]

This pr will add the possibility to view the changelog.md & releases from a package's github repo within npmx.
This will make it easier to see the changelogs while not needing to leave npmx and allowing quicker access.

This pr is the first pr of #501

Preview here, this will automatically update

Acknowledgements

While I was making this PR antfu also made this pr #1368 and here my comment from his pr

Also @ShroXd is currently working on adding changelogs to the version history page that was merged with #2025, we've both agreed to first independently work on our PRs and later after both are merged and we've received feedback & irl use we'll collaborate on the interaction between the two

Translations

Thanks @WarningImHack3r for translating the text for changelog to French

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
npmx.dev	Ready	Preview, Comment	Mar 31, 2026 9:22am

2 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
docs.npmx.dev	Ignored	Preview	Mar 31, 2026 9:22am
npmx-lunaria	Ignored		Mar 31, 2026 9:22am

[github-actions]

Lunaria Status Overview

🌕 This pull request will trigger status changes.

Learn more

By default, every PR changing files present in the Lunaria configuration's files property will be considered and trigger status changes accordingly.

You can change this by adding one of the keywords present in the ignoreKeywords property in your Lunaria configuration file in the PR's title (ignoring all files) or by including a tracker directive in the merged commit's description.

Tracked Files

File	Note
i18n/locales/en.json	Source changed, localizations will be marked as outdated.
i18n/locales/fr-FR.json	Localization changed, will be marked as complete. 🔄️
i18n/locales/kn-IN.json	Localization changed, will be marked as complete. 🔄️
i18n/locales/tr-TR.json	Localization changed, will be marked as complete. 🔄️

Warnings reference

Icon	Description
🔄️	The source for this localization has been updated since the creation of this pull request, make sure all changes in the source have been applied.

[codecov]

Codecov Report

❌ Patch coverage is 66.66667% with 17 lines in your changes missing coverage. Please review.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
app/components/Package/Header.vue	46.15%	5 Missing and 2 partials ⚠️
app/utils/router.ts	0.00%	3 Missing and 2 partials ⚠️
app/components/Changelog/Card.vue	78.57%	3 Missing ⚠️
app/pages/settings.vue	0.00%	1 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

[alexdln]

the only issue I'm facing is that some packages have both releases and changelog.md in use (oxfmt), but some like msw only have a changelog.md to refer to releases, how can I best detect whether I can fallback to changelog.md and when not?

This is what I was wondering about in previous comments. Maybe we shouldn't support files, but only display what's in releases. In the case of files, an additional question is whether we should load a file from a specific version (and which hash is that?). And another big question is, maybe we should only show the changelog for the current version (incl. show tab only if there is block for this specific version)...

I left another small comment. About other details, I think we can continue to improve iteratively - it seems we also could refactor the Markdown renderer and reuse it more with the main page

In general lgtm, thanks 🤍
Would like to wait for a bit for a second eye

[WilcoSp]

@alexdln

This is what I was wondering about in previous comments. Maybe we shouldn't support files, but only display what's in releases.

I don't think it's a good idea to only support the releases. by removing changelog.md file support it'll make this changelog feature incomplete.

In the case of files, an additional question is whether we should load a file from a specific version (and which hash is that?).

This will make serving the changelog overcomplicated and might result in a worse experience.

maybe we should only show the changelog for the current version (incl. show tab only if there is block for this specific version)...

For a specific version @ShroXd is currently working on making it possible to have changelogs at the versions's page
https://discord.com/channels/1464542801676206113/1464926468751753269/1481214467181117534.

Also maybe this will helps for the context of how I've implemented the changelogs for npmx.
When I update dependencies in the projects I work on I want to view the changelogs for the versions between I've currently and the latest released.
For example with Vue I've currently 3.5.20, when I want to update versions 3.5.21, 3.6.0 & 3.6.1 have been released in that order, I want to than be able to read the changelogs for 3.5.21, 3.6.0 & 3.6.1 not just 3.6.1

it seems we also could refactor the Markdown renderer and reuse it more with the main page

For markdown rendering refactor I want to save for a separate smaller pr that's easier to review & merge (tbh I also don't want to deal with bigger merge conflicts rn)

I think we can continue to improve iteratively

That was always the plan, at #501 there is a roadmap for what is planned.

[alexdln]

I don't think it's a good idea to only support the releases. by removing changelog.md file support it'll make this changelog feature incomplete.

This will make serving the changelog overcomplicated and might result in a worse experience.

It's just a few more specific cases. And as the result bunch of new questions:

1. There could be weird cases (like this one). In the case of the readme, we had an additional layer in the form of a provider, but here we take everything from GitHub - does this increase the risks? (probably not, but maybe we missed something because we hadn't worked with rendering direct information before. Like what if there would be really huge file? Maybe we should implement size limit because otherwise it can just block our server. What else?)
2. Should the user see the changelog tab on specific version if there's probably no release for this version there (like in canary channels or in old ones)?
3. What if this version existed, but in a previous version of the branch (like vite) (it was the main reason of the idea to show specific release)
4. Is there a reason to support different paths - looks like it can be cached and reused for all versions?

[WilcoSp]

In the case of the readme, we had an additional layer in the form of a provider, but here we take everything from GitHub

yes, atm we're completely relying on ungh.cc & their use of the github api. using github api directly isn't possible because of their stricter rate limits. so atm idk a good solution with also the fact there are plans to support other git providers

Like what if there would be really huge file? Maybe we should implement size limit because otherwise it can just block our server. What else?)

at least in this pr there is no size limit. a solution could be to split a changelog.md file up into chunks. but idk if that is a good solution. giving "changelog.md is too big" isn't a very good option because that could be annoying.

There could be weird cases (like this one)
Should the user see the changelog tab on specific version if there's probably no release for this version there (like in canary channels or in old ones)?

I do think it's better to still give the changelogs instead of not giving them, even if the specific version doesn't have them. sometimes no information is still useful information

What if this version existed, but in a previous version of the branch (like vite) (it was the main reason of the idea to show specific release)

for this we currently don't have anyway to support when the changelog is on a alpha/beta branch because everyone does this differently. maybe the npmx.changelog field for package.json can in the future include information for this.

Is there a reason to support different paths - looks like it can be cached and reused for all versions?

path is in the ChangelogInfo type because of monorepos like Vue and Pinia having the changelog.md in a nested directory.
the reason for per version being fetched is that sometimes people move to a different git provider (pinia-plugin-persistedstate 4.5.0 - > 4.6.0) or move to a different repo (vue 2->3).

idk whether it's possible but in case ungh.cc is unable to return any info when trying to detect releases/changelog.md we could if possible look up in the case for a previous versions and server that.

[WarningImHack3r]

A few nitpicks:

• is it possible to defer the loading of the changelog contents? It currently blocks the whole page loading, a skeleton would be a nice addition imo
• I think we should remove the title anchoring for releases’ content, it clutters visually the UI and is pointless 99% of the time as anchors for "Minor changes" (or patch/major) are identical across all releases
• Similarly, the TOC per release is not necessary
• missing a bit of top padding at the top of the raw rendered changelogs :D

Other than that, nice work! Can’t wait to see how the feature set will turn out when all the features are done!

[gameroman]

One thing I am not a fan of is autoscroll when switching from main tab to changelog tab

Looks like it's triggered due to automatic addition of hash to URL

[gameroman]

Otherwise this looks really great, I like it

/package-changelog/tsdown

[WilcoSp]

@gameroman

One thing I am not a fan of is autoscroll when switching from main tab to changelog tab

Looks like it's triggered due to automatic addition of hash to URL

I had added it to bring to the requested version or at least as close as possible.
But what might be a good solution is to make it an opt out setting at the settings page.
I'll also remove the auto scrolling when no requested version is in the url (currently goes to latest)

@WarningImHack3r

is it possible to defer the loading of the changelog contents? It currently blocks the whole page loading, a skeleton would be a nice addition imo

ehm, skeletons loaders are already being used with <suspense>, I'll change the useFetch to useLazyFetch at the releases/changelog components maybe that'll help

I think we should remove the title anchoring for releases’ content, it clutters visually the UI and is pointless 99% of the time as anchors for "Minor changes" (or patch/major) are identical across all releases

In the package readme they also have it that every header is anchored, that is why it's also with changelogs.
The reason why changelog has the icons always visible is because at least Vue has already a link in the version headers, so the icon had to become standalone to the right for consistency.
recently they did change for readme that with H4-H6 that the icon is to the left and invisible so long not focussed/hovering. For changelog I can change the behavior to also only be visible when focussed/hovering.

Similarly, the TOC per release is not necessary

For small releases it's not needed, but for very long ones (nuxt/tsdown) it's still handy to have and the toc is always generated no matter how small, there is only a requirement that at least 2 toc items are needed to show the toc atm.

missing a bit of top padding at the top of the raw rendered changelogs :D

I'll add a pt-2 to the <article> element for the changelog to add some padding

atm I've also work so either after work or tomorrow I'll make the changes.

[WilcoSp]

@WarningImHack3r & @gameroman I've just committed the changes that I talked about in my prev msg.

I've also fixed that hash was being applied to the url when switching to main & the cards for releases are now lazy with "hydrate-on-interaction", this makes initial rendering faster.

[WarningImHack3r]

Another set of QA feedback (:D):

• The anchor icon that's now on hover for releases' body is only visible when hovering on it, which can be surprising when you don't expect it. I think it should be visible when hovering over the whole title it's anchored to.
• Tag navigation is a bit buggy
  • Some selections are misplaced (here, link from above in the PR)
  • Some others do nothing (navigating from the latest (default) Vite to any other version requires a refresh to work)
  • Some others crash (try navigating here to 0.21.0-beta.5 with the dropdown), and pressing the back button breaks the X-axis layout

On another note, here are the promised French localizations:

{
    // ...
    "enable_changelog_autoscroll": "Scroller automatiquement à la version voulue",
    "enable_changelog_autoscroll_description": "Scroller automatiquement à — ou près — de la version voulue dans la page des changements"
    // ...
    "changelog": "changements"
    // ...
    "changelog": {
    "pre_release": "Pré-version",
    "draft": "Brouillon",
    "no_logs": "Désolé, ce paquet ne publie pas de changements ou le format de ses changements n'est pas pris en charge.",
    "error": {
      "p1": "Désolé, les changements de {package} n'ont pas pu être chargés",
      "p2": "Veuillez réessayer plus tard ou {viewon}" // i couldn't find what `viewon` is
    },
    "rate_limit_ungh": "Désolé, la limite de requêtes à l'API GitHub a été atteinte, réessayez plus tard"
  }
}

[WilcoSp]

I've committed some changes that should improve changelogs.

• when changing versions, the resolving of version & changelog happens in the background by using useLazyFetch's previous result that it gives automatically. after resolving then the automatic scrolling happens, this also reduces a flash of the skeleton loader which caused the crashes earlier.
• when the package couldn't be resolve the "package couldn't be found" msg will be displayed which is copied from /package/....
• added msg "The requested version is not available." when manually entering a version nr that isn't on npm (@WarningImHack3r if you want you can translate this to French)

@WarningImHack3r the issues you had found should have be fixed now.

[WarningImHack3r]

Awesome work!!
Here is the translated new entry:

    "version_unavailable": "La version demandée n'est pas disponible."

It's the only one that changed as far as I can see.
There is also a moved block in the french translation, idk if it's intentional

LGTM otherwise!