Discussion: changelogs button

@person

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)

✅ button, page & basic viewers (these will cover most people) (feat: adding gh changelog/releases to npmx #1233 (ready for review & merge))
- changelog button at button page
- /package-changes/ page
- a basic changelog.md viewer component with toc
- basic releases viewer component
- automatic scrolling to the as close as possible to the requested version with date+version (fallback to date)
- check whether the changelog.md from the latest release is in the repository directory specified in the npm package or the root of the package

1.5 ✅ some refactoring which isn't possible in a big branch (#2717 )

refactor the markdown renderer to better share code with the readme renderer

most of the other repositories services (if needed this can be spread across multiple PRs for each service) (feat: changelog - formatted links, more git providers & copy markdown #2983, preview)
- add support for other git service provider documented here for releases
- add support for other git service providers documented here for changelog.md
- add support for for automatic links to pull/merge requests (#pr), issues (#issue) and users (@person)
  - parse from plain text to a link
  - parse from link to git provider style for the issue/pr/user
- have a button to the changelogs page in the package dependencies
- at the package page have buttons next to selectable package versions (similar to feat: link to releases #1368)

filters for releases
- support for filtering for specific packages within releases (does need heading to be package@version)
- support for filtering to specific version range (for example 3.5.x or 3.x.x)
support for infinite scrolling for releases
- ^ (feat: adding pagination for releases unjs/ungh#171)
more advanced features for changelog.md
- split the versions by heading (semver regex)
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
- add possibility for self hosted repositories give information how their repository platform
  - allow to give information how each url is formatted
  - allow giving info that the git platform is a self hosted version of gitlab, gitea, forgejo etc
- allow giving where the changelog.md is located in repository (for if it's a very specific)
- allow to give a website url where the changelog can be found if not hosted on any git provider (self hosted)

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

vue (github changelog with redirect from releases)
nuxt (github releases)
gitlab/ui (gitlab releases)
pinia-plugin-persistedstate (codeberg changelog.md)
prosemirror-search (self hosted forgejo changelog.md)
package-json-editor (codeberg releases)
papaparse (switched from releases to changelog.md)
vue-codemirror6 (also switched from releases to changelog.md)

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

	changelog.md	releases	formats issue links	formats pr links	links to commits	links to accounts	formats compare links
github	✅	✅	✅	✅	✅	✅	✅
codeberg/forgejo	✅	✅	✅	✅	✅	✅	✅
gitlab	✅	✅	✅	✅	✅	✅	✅
tangled	✅	n/a	☑️ (temporary default till tangled develops their shorthands)	☑️ (same as issue)	✅	✅	✅
gitea	✅	✅	✅	✅	✅	✅	✅
bitbucket	✅	n\a	❌ (uses jira)	✅	✅	❌	❌ (differently formatted)
source hut	✅	❌ (seems to not be used anymore)	✅	n/a	✅	✅ (with ~ instead of @)	❌
Gitee	✅	✅	✅	✅	✅	✅	✅
Radicle*	❌	n/a	❌	❌	❌	❌	❌
Pushin.eu**	❌	❌	❌	❌	❌	❌	❌

* 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, gitea

tangled doesn't have shorthands, so @ will be used
bitbucket & 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:

For repository services that have a {repository}/releasesor equivalent page and is being used have the link go to it.
If ^ isn't used/supported then and there is a /changelogs.md file then link to it instead

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

Have a "changelogs" field in the root of the package.json (example: {"changelogs": "https://example.pkg/changes"})
- pro: can easier be used by other websites
- pro: has a (slight) chance of being adopted by npm
- con: if adopted by npm they could bring breaking changes like with what css nesting did in sass/scss.
Have an "npmx" object field and then in there have "changelogs" field (example: {"npmx": {"changelogs": "https://example.pkg/changes"}})

pro: allows for better control of the definition of the changelogs field even if npm adopts it.
pro: with the npmx object field other features could also be added in the future.
con: other website may not use this as they may see it outside of their control

Hopefully discussion brings a lot of ideas & feadback.

Also why not link to specific release changelog:

in case their are versions between the installed version & latest version it will make the in between versions easier to read/reach.

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-)changelog or (/package-)changes. the package- 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?

@WilcoSp

just writing down my two cents

i believe using a package's CHANGELOG.md file 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.md file included in the package tarball it is also immutable (i think?), for better or for worse

not 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 :)

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)

To feed the discussion, I put together a proof of concept here

@gwennlbh

@gwennlbh the caching optimization is intriguing, curious how we might do that optimally. Currently in my poc I just piggyback off the analysis in server/api/registry/analysis/[...pkg].get.ts

I'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

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 issues felt 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

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).

Random 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.

yes 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.md

I'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@1a2b3c4 or have it disabled for those?
for tangled I'll add the support like what I've done already with issue, pr, commit & account

also 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)

Navigation Menu

Repository navigation

Discussion: changelogs button #501

roadmaps in PRs (updated September 9th 2026)

packages to test with

api docs

Current (in development) support for each git provider

commit seperator repo@commit

original message

14 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Discussion: changelogs button #501

Description

roadmaps in PRs (updated September 9th 2026)

packages to test with

api docs

Current (in development) support for each git provider

commit seperator repo@commit

original message

Activity

serhalp commented on Jan 31, 2026

ghostdevv commented on Jan 31, 2026

WilcoSp commented on Feb 1, 2026

gwennlbh commented on Feb 1, 2026

WilcoSp commented on Feb 1, 2026

beeequeue commented on Feb 2, 2026

gwennlbh commented on Feb 2, 2026

vinnymac commented on Feb 2, 2026

vinnymac commented on Feb 2, 2026

WilcoSp commented on Feb 3, 2026

vinnymac commented on Feb 3, 2026

14 remaining items

theoephraim commented on May 26, 2026

theoephraim commented on May 26, 2026

WilcoSp commented on May 26, 2026

theoephraim commented on May 26, 2026

WilcoSp commented on May 27, 2026

WilcoSp commented on Sep 9, 2026

WilcoSp commented on Oct 9, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions