Repository navigation
Discussion: changelogs button #501
Description
Activity
Very cool idea!
I've implemented changelog before and what I landed on was (assuming we want to render the changelog, not just link to it)
- Check the tarball for the CHANGELOG.md file
- Check the repo for the CHANGELOG.md file
- Pull from GitHub releases
I'm also looking to re-implement this on the work in progress api, but with better checks for the changelog file since we can process the whole tarball like yarn/algolia does here (although there are even more options I can think of).
con: if adopted by npm they could bring breaking changes like with what css nesting did in sass/scss.
The entire registry is full of inconsistencies so I think we'd be ok!
Have an "npmx" object field and then in there have "changelogs" field (example: {"npmx": {"changelogs": "https://example.pkg/changes"}})
If we could do it without this that'd be cool, especially if it encourages more people to ship a changelog file with their package
I wasn't planning to display the changelogs in npmx but to link to them.
but it could be an idea to display the changelog.md or/releases(if there are api's available) within npmx at a new route, for example(/package-)changelogor(/package-)changes. thepackage-prefix depends if other routes are being changed or not.If we could do it without this that'd be cool
It's totally optional and for near 99% of all packages on npm the default will work fine, it's only for those few that host the changelogs somewhere else or where they may have switched between Changelog.md <-> /releases
especially if it encourages more people to ship a changelog file with their package
I rather not encourage including the changelog.md as it does add to the install size and except for npmx it doesn't help developers much when included
The entire registry is full of inconsistencies so I think we'd be ok!
true
yessss that would be a really nice feature. another alternative npm frontend does it like this: https://npm.willow.sh/package/swarpc@0.19.0/changelog
seems like it renders the CHANGELOG.md file and/or (maybe?) reads from the github releases' notes as a fallback
i changed my !npm bang to this frontend instead of npmx for that reason but tbh npmx seems to be developing really fast so ill switch to it i think!
I've checked npm.willow.sh and they uses both readme.md & for github's /releases page with giving the readme.md the propriety.
I was thinking if we display the changelogs in npmx I check best would be to check for both and then check the last update date (not time) and pick which one is last updated, if both have the same date then readme.md gets the priority.
Also with pinia I've noticed that they have "Please refer to CHANGELOG.md for details", should we check for this and then display the referred changelog.md or should we keep it simple and only display the releases from github?
just writing down my two cents
i believe using a package's
CHANGELOG.mdfile should be prioritized for various reasons.as @WilcoSp said in the previous comment some release tabs only point to a changelog file (e.g. pinia, vite)
monorepos that use GH releases will also use them in different ways - some might have one entry listing every package that changed in that release, some will have separate releases for each package in the monorepo (the way Changesets does it)
if the changelog is read from a
CHANGELOG.mdfile included in the package tarball it is also immutable (i think?), for better or for worsenot all (or many?) packages include a changelog file in the tarball of course, so agree with @ghostdevv about the prio order
- tarball
CHANGELOG.md,RELEASES.md, etc. - soruce code
CHANGELOG.md,RELEASES.md, etc. - source forge releases
it would also be nice to be able to search for specific version numbers as doing that with GH releases currently is a major pain :)
- tarball
it would also be nice to be able to search for specific version numbers as doing that with GH releases currently is a major pain :)
We could even split up the changelog file into per-version changes and attach them to each version.
Renovate does this and it's really cool, when you get a upgrade PR for a package it shows the release notes, but only for the versions between the latest and the one you currently have
I searched a bit in their source code, I think the splitting logic is here: https://github.com/renovatebot/renovate/blob/179abe488afe8030b213130578e62791af35efcd/lib/workers/repository/update/pr/changelog/release-notes.ts#L349
I think that it boils down to splitting by heading that have the version in their text (if we had a strict, standardized way to format changelogs it'd be nice but the closest to that is https://keepachangelog.com and it's not that strict and not that popular too, unfortunately)
obviously, for github releases the splitting up part is trivial since each tag has its own release notes
also, seems like there's nuggets of useful information, as Renovate has been parsing changelogs for a pretty wide range of packages for a while:
/** * Determine how long to cache release notes based on when the version was released. * * It's not uncommon for release notes to be updated shortly after the release itself, * so only cache for about an hour when the release is less than a week old. Otherwise, * cache for days. */
(in the same file)
Reacted by Vincent Taverna and EliI'll be splitting up all the additions into multiple PRs, this is spread the workload and also allow basic functionality be available sooner compared to everything in 1 big PR
I think these will be the PRs
- button, page & basic viewers (these will cover most people)
- the changelog button at package page (thanks Vinny for how it should look and for whether it should be shown)
- a changelog page where basic data is fetched to determine which of the 2 below viewer components should be used.
- a basic changelog.md viewer component (at least github but if easily done also others) (if possible with links to each version header)
- a basic gh releases viewer component
- most of the other repositories services (if needed this can be spread across multiple PRs for each service)
- if not in PR1, then here changelog.md for the others services
- the releases api from the other services where possible.
- filters for releases
- support for monorepos where each package gets their own changelog
- support to select 1 to multiple versions (if possible even groups of versions, for example only 2.x.x)
- more advanced changelog.md where versions can be split by version headings
those numbered will be made in order, those without are more free in which other they're made after the ordered ones
Also the PRs above aren't final and could have things added to them or even new PRs could be added to the list
Also for the releases APIs can best be made into adapters which so that in components it's easier to request changelogs
Reacted by Vincent Taverna and Gwenn Le BihanReacted by Gwenn Le Bihan- button, page & basic viewers (these will cover most people)
Sounds like a great plan!
the changelog button at package page
I've seen some folks concerned about this section of the package page being too cluttered with buttons, we may want to discuss an alternative UX for it, I just wanted to see if adding it next to
issuesfelt right in my PoC.I am also wondering whether one of those PRs would include whether or not to display the button, or if all packages would display changelog buttons of some kind. Then clicking the button when no changelog was available would say something along the lines of "This package doesn't have a changelog, request the maintainer add one." or something like that. It certainly allows us to reduce the load on analysis (
server/api/registry/analysis/[...pkg].get.ts) which is nice.a basic changelog.md viewer component
What if instead of a dedicated changelog viewer component we added "Preview" markdown functionality to the existing codebase file viewer. Then with that in place we would be able to load the existing file viewer for any file, whether its CHANGELOG.md, HISTORY.md, etc. We could embed the Table of Contents (the component I just shipped for the README on the package page) in the preview to make it easier to jump around the changes in the file.
I think that might be handy for other features on npmx in the future too
14 remaining items
- modified the milestones: release: crystal chronicle, Up Next, release: dexterous dredge
on May 11, 2026 Currently publishing a monorepo using https://bumpy.varlock.dev (similar to changesets). This setup means GH has a separate release for each package at each version. Currently all of these releases (for all packages) are showing on npmx changelog tab - see https://npmx.dev/package-changelog/varlock for an example.
I definitely would expect the CHANGELOG.md file within a specific package folder to be prioritized over release info (using package.json repository url and directory to find the package root in git).
Reacted by Philippe SerhalRandom sidenote - when browsing other data in npmx, linking to changelogs could be cool. For example I'm looking at the bundle size graph, and I see a huge spike with a warning of a big increase. Linking tot the related changelog there feels very natural as it would (hopefully) explain what happened.
Reacted by Philippe Serhal, Eli and Wilcoyes for now monorepos npmx will show all releases from every package, I do eventually want to have pattern matching to allow filtering and have the closest match always available. But I'll first work on adding support for other git providers
for the dependency graph I'll look at how it works and maybe add it or ping the creator for their opinion on how it could be added, but for sure a nice suggestion.
would using the changelog.md files not be preferable to relying on releases? This would also be more portable for different git providers.
not every package has a 'changelog.md' on github and only use releases (for example Nuxt), also with monorepos it happens a lot that package B depends on package A, by using releases it's possible to see them together instead of needing to see them separate.
lastly because releases has it's content already split into versions, when more filtering options are added releases will be easier to filter than 'changelog.md' which might receive the filtering features later or not because it needs to be split into version chunks.I've added an table to the first message with how the current (in development) support is for each git provider.
Gitee & Radicle are currently not on it because those need to be developed, I'm currently researching Gitee for how to implement it to npmx's changelog.
Radicle I did look at but currently not possible because I can't get a raw changelog.mdReacted by Felix SchneiderI've updated the support table with also pushin.eu included.
I've also done some research into how the support is for the commit shorthand for commits that are in a different repo than the npm package's own repo. most use
@as the separator between owner/repo & the commit sha. except for tangled, bitbucket, sourcehut & gitee.do you all think I should still add support for bitbucket, sourcehut & gitee to use
owner/repo@1a2b3c4or have it disabled for those?
for tangled I'll add the support like what I've done already with issue, pr, commit & accountalso for Radicle I've added a post on their forum/chat to ask for help to also add support for Radicle, here is a link to it (link)
also for now my planning for the package changelog will be:
- add support for shorthands that reference issues/PRs/commits that is external of the package's git repo.
- make it possible for forgejo, codeberg & gitea to use
!for referencing a pr. - begin with making of the docs for package changelog, it'll have information about how npmx resolves the changelog of a package & the markdown support, mostly the shorthands support
afterwards I'll begin with other features for package changelog like the tag filtering & infinite scroll (depends on unjs/ungh#171)
Reacted by João Ferreira
in this issue we discuss, come up with ideas, give feedback & contribute to adding & evolving changelogs to npmx.
below is a roadmap and below that there is the original starting message of this discussion.
roadmaps in PRs (updated September 9th 2026)
1.5 ✅ some refactoring which isn't possible in a big branch (#2717 )
filters for releases
package@version)support for infinite scrolling for releases
more advanced features for changelog.md
add npmx.changelog fields for package.json that can't be covered by the PRs above, this will be a separate issue when the time comes
those numbered will be made in order, those without are more free in which order they're made after the ordered ones
Also the PRs above aren't final and could be changed till the moment it's merged.
You're free to share your ideas and make your own PRs even if they're not in the roadmap.
PRs can also be merged to my or someone else's fork first and to then together create a bigger PR to npmx
packages to test with
api docs
Current (in development) support for each git provider
This table display the current support for each git provider, ☑️ means that it's implemented but unstable
* Currently with Radicle it's not possible to fetch the raw changelog file.
** Currently with Pushin.eu it's not possible to fetch the raw changelog file, also npmx doesn't support pushin in general (#3303)
commit seperator repo@commit
example:
npmx-dev/vscode-npmx@dee1eb4b@: github, gitlab, codeberg, forgejo, giteatangled doesn't have shorthands, so
@will be usedbitbucket & source hut is unknown
gitee doesn't support referencing to other repo's
original message
I'll would like to make a "changelogs" button for at the package page to allow for quicker checking newer versions of earlier installed packages.
But I do think it's best to discus first how we should get the link for the changelogs.
Atm I'm thinking of the following default behaviour:
{repository}/releasesor equivalent page and is being used have the link go to it.But some may host their changelogs somewhere else, for this it may be handy to have a way in the package.json to specify where the changelogs are located.
For example Ag grid host their changelog somewhere else and vuetify has their changelogs both at github & their own website.
I was thinking of 2 ways to have this in package.json
{"changelogs": "https://example.pkg/changes"}){"npmx": {"changelogs": "https://example.pkg/changes"}})Hopefully discussion brings a lot of ideas & feadback.
Also why not link to specific release changelog: