jeffersongoncalves/laravel-npm-readme

A Laravel package that fetches an npm package's README from the registry document, renders the markdown and caches the resulting HTML. The default renderer strips raw HTML; provide your own renderer callable (and sanitize) to keep it. Rendered HTML is untrusted — sanitize it before display.

v1.0.0 2026-06-21 23:22 UTC

Requires

• php: ^8.2
• guzzlehttp/guzzle: ^7.8
• illuminate/contracts: ^11.0|^12.0|^13.0
• illuminate/http: ^11.0|^12.0|^13.0
• illuminate/support: ^11.0|^12.0|^13.0
• league/commonmark: ^2.8.2
• spatie/laravel-package-tools: ^1.14

Requires (Dev)

• larastan/larastan: ^3.0
• laravel/pint: ^1.0
• orchestra/testbench: ^9.0|^10.0|^11.0
• pestphp/pest: ^3.7.4|^4.0
• pestphp/pest-plugin-laravel: ^3.0|^4.0

MIT

• Jefferson Gonçalves

• laravel
• jeffersongoncalves
• laravel-npm-readme

README

Laravel npm Readme

Fetch an npm package's README straight from the registry document, render the markdown and cache the resulting HTML. The npm registry ships the README markdown inline in the package document, so there is no extra request beyond the registry call.

This is the npm sibling of jeffersongoncalves/laravel-github-readme.

Installation

composer require jeffersongoncalves/laravel-npm-readme

Optionally publish the config:

php artisan vendor:publish --tag="npm-readme-config"

Usage

use JeffersonGoncalves\NpmReadme\NpmReadme;

$html = NpmReadme::fetchHtml('https://www.npmjs.com/package/laravel-echo');
// or a scoped package:
$html = NpmReadme::fetchHtml('https://www.npmjs.com/package/@tailwindcss/vite');

fetchHtml() returns the rendered HTML, or null when the URL isn't an npm package, the registry has no document, or the package ships no README. Results are cached on the default cache store (npm_readme:{package}) for config('npm-readme.cache_minutes').

NpmReadme::packageFromUrl($url) is also public if you only need the package identifier.

Security

The rendered HTML is untrusted (third-party package READMEs). The default renderer therefore strips raw HTML (html_input = strip), so an embedded <script> cannot become stored XSS.

If you need raw HTML kept, provide your own renderer callable in config/npm-readme.php — the output is then unsafe and you must sanitize it before display, e.g. with jeffersongoncalves/laravel-html-sanitizer:

// config/npm-readme.php
'renderer' => [\App\Support\Markdown::class, 'render'],

Configuration

Key	Default	Description
cache_minutes	60	Minutes the rendered HTML is cached per package.
registry_url	https://registry.npmjs.org	npm registry base URL.
timeout	8	Registry request timeout in seconds.
user_agent	laravel-npm-readme	User-Agent header for the registry request.
renderer	null	Optional callable(string $markdown): string. When null, an internal CommonMark renderer (GFM + heading permalinks, raw HTML stripped) is used.

Testing

composer test

License

The MIT License (MIT). Please see License File for more information.