← Back to Dashboard
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
[![npm version](https://img.shields.io/npm/v/@scope/package)](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 →