Verified Production Fix
[gitlab-org/gitlab] Add npm package version badge support for project README
GL-gitlab-org/gitlab#592614 • Mar 08, 2026
### ROOT CAUSE
The GitLab Package Registry currently lacks a public badge/link endpoint for npm packages, which prevents users from displaying package version badges in their project READMEs. Additionally, there is no documentation on how to create badges for npm packages published to GitLab, and there is no straightforward way to reference or link to published packages in the README.
### CODE FIX
To address this issue, we can implement a solution that provides a public badge URL or package link for npm packages in the GitLab Package Registry. Here is a proposed fix:
1. **Create a Public Badge Endpoint**:
- Add a new endpoint to the GitLab API that returns a badge image showing the latest npm package version.
- Example endpoint: `https://gitlab.com/api/v4/projects/:id/packages/npm/:package_name/badge`
2. **Update Documentation**:
- Provide documentation on how to use the new badge endpoint in the README of the project.
- Include examples of how to display the badge in Markdown format.
3. **Enhance Package Registry UI**:
- Add a "Copy badge markdown" or "Copy package link" option in the Package Registry UI to make it easier for users to include badges in their READMEs.
Here is a sample implementation of the badge endpoint in Ruby on Rails:
ruby
# config/routes.rb
Rails.application.routes.draw do
namespace :api do
namespace :v4 do
resources :projects, only: [] do
resources :packages, only: [] do
member do
get 'npm/:package_name/badge', to: 'packages#npm_badge'
end
end
end
end
end
end
# app/controllers/api/v4/packages_controller.rb
module Api
module V4
class PackagesController < ApplicationController
def npm_badge
project = Project.find(params[:id])
package_name = params[:package_name]
# Fetch the latest version of the npm package
latest_version = project.packages.where(name: package_name).order(version: :desc).first
if latest_version
# Generate the badge image URL
badge_url = "https://img.shields.io/npm/v/#{package_name}.svg"
render plain: badge_url, content_type: 'text/plain'
else
render plain: 'Package not found', status: :not_found
end
end
end
end
end
This implementation provides a public badge URL for npm packages in the GitLab Package Registry. Users can then include this badge in their project READMEs using Markdown format. Additionally, the documentation should include examples of how to display the badge in Markdown format, such as:
markdown
[](https://gitlab.com/user/project/-/packages/npm/@scope/package)
By implementing this solution, users will be able to easily display package version badges in their project READMEs, similar to what is available on npm.js and GitHub.
Deploy with Vultr
Use this fix in production instantly. Claim your high-performance developer credit.
Get Started with Vultr →
digital