From 658fc34bc970f54b4be5fa01a4a75db2ed8d8210 Mon Sep 17 00:00:00 2001 From: Daniel Roe Date: Thu, 12 Feb 2026 06:44:34 +0000 Subject: [PATCH] docs: npm comparison/features --- README.md | 76 +++++++++----- docs/content/2.guide/1.features.md | 158 +++++++++++++++++++++++------ 2 files changed, 174 insertions(+), 60 deletions(-) diff --git a/README.md b/README.md index 222ec8c60..bfe41a9f9 100644 --- a/README.md +++ b/README.md @@ -69,34 +69,54 @@ What npmx offers: ### Comparison with npmjs.com -| Feature | npmjs.com | npmx.dev | -| ------------------------------ | :-------: | :------: | -| Package search | ✅ | ✅ | -| Package details & README | ✅ | ✅ | -| Version history | ✅ | ✅ | -| Dependencies list | ✅ | ✅ | -| User profiles | ✅ | ✅ | -| Organization pages | ✅ | ✅ | -| Provenance indicators | ✅ | ✅ | -| Code browser | ✅ | ✅ | -| Dark mode | ❌ | ✅ | -| Outdated dependency warnings | ❌ | ✅ | -| Module format badges (ESM/CJS) | ❌ | ✅ | -| TypeScript types indicator | ✅ | ✅ | -| Install size calculation | ❌ | ✅ | -| JSR cross-reference | ❌ | ✅ | -| Vulnerability warnings | ✅ | ✅ | -| Deprecation notices | ✅ | ✅ | -| Download charts | ✅ | ✅ | -| Playground links | ❌ | ✅ | -| Keyboard navigation | ❌ | ✅ | -| Multi-provider repo support | ❌ | ✅ | -| Version range resolution | ❌ | ✅ | -| Dependents list | ✅ | 🚧 | -| Package admin (access/owners) | ✅ | 🚧 | -| Org/team management | ✅ | 🚧 | -| 2FA/account settings | ✅ | ❌ | -| Claim new package names | ✅ | ✅ | +| Feature | npmjs.com | npmx.dev | +| ------------------------------------------------ | :----------------: | :---------------------------------: | +| **Package browsing** | | | +| Package search | ✅ | ✅ (dual-provider: npm + Algolia) | +| Package details & README | ✅ | ✅ (with TOC, markdown copy) | +| Version history | ✅ (dedicated tab) | ✅ (sidebar, grouped by dist-tag) | +| Dependencies list | ✅ | ✅ (with outdated indicators) | +| Dependents list | ✅ | 🚧 | +| Code browser | ✅ | ✅ (line permalinks, range select) | +| User profiles | ✅ | ✅ | +| Organization pages | ✅ | ✅ | +| Provenance details | ✅ | ✅ (full attestation section) | +| Download charts | ✅ | ✅ (interactive, multi-granularity) | +| Vulnerability warnings | ✅ | ✅ (transitive dep tree) | +| Deprecation notices | ✅ | ✅ | +| TypeScript types indicator | ✅ | ✅ (with @types/\* links) | +| Funding info display | ✅ | 🚧 | +| **Admin features** | | | +| Package access management | ✅ | ✅ (via connector) | +| Maintainer management | ✅ | ✅ (via connector) | +| Org/team management | ✅ | ✅ (via connector) | +| Claim new package names | ✅ | ✅ (via connector) | +| Bulk operations (plan/apply) | ❌ | ✅ | +| Deprecate/undeprecate | ✅ | 🚧 | +| Trusted publishing (OIDC) | ✅ | 🚧 | +| 2FA/account settings | ✅ | ❌ (use npm CLI) | +| **Only on npmx.dev** | | | +| Dark mode + accent colors | ❌ | ✅ | +| 29-locale internationalization | ❌ | ✅ | +| Multi-PM install (npm/pnpm/yarn/bun/deno/vlt) | ❌ | ✅ | +| Auto-generated API docs from types | ❌ | ✅ | +| Package comparison (up to 4) | ❌ | ✅ | +| Module format badges (ESM/CJS/Dual) | ❌ | ✅ | +| Total install size calculation | ❌ | ✅ | +| Outdated dependency warnings | ❌ | ✅ | +| Deprecated dependency tree | ❌ | ✅ | +| Module replacement suggestions | ❌ | ✅ | +| Install scripts security warning | ❌ | ✅ | +| Security downgrade detection | ❌ | ✅ | +| 10 git providers (GitHub, GitLab, Codeberg, ...) | ❌ | ✅ | +| JSR cross-reference | ❌ | ✅ | +| Playground links from README | ❌ | ✅ | +| Version download distribution chart | ❌ | ✅ | +| Custom badge API (20+ types) | ❌ | ✅ | +| Bluesky/ATProto social features | ❌ | ✅ | +| Keyboard shortcuts (/, ., d, c, ?) | ❌ | ✅ | +| Short URLs (/vue, /vue@3.4.0) | ❌ | ✅ | +| OpenSearch browser integration | ❌ | ✅ | 🚧 = coming soon diff --git a/docs/content/2.guide/1.features.md b/docs/content/2.guide/1.features.md index b8449b3af..b472e8981 100644 --- a/docs/content/2.guide/1.features.md +++ b/docs/content/2.guide/1.features.md @@ -5,7 +5,7 @@ navigation: icon: i-lucide-sparkles --- -npmx.dev provides a comprehensive set of features for browsing npm packages. +npmx.dev provides a comprehensive set of features for browsing, analyzing, and administering npm packages. ## Browse packages @@ -13,10 +13,11 @@ npmx.dev provides a comprehensive set of features for browsing npm packages. Each package page displays: -- **README** - Rendered markdown documentation -- **Versions** - Complete version history with release dates -- **Dependencies** - Required packages with version ranges that resolve to actual versions -- **Dependents** - Packages that depend on this one (coming soon) +- **README** - Rendered markdown with table of contents, active section tracking, and copy-as-markdown +- **Description** - With inline markdown rendering +- **Versions** - Complete version history grouped by dist-tags (latest, next, beta, etc.) +- **Dependencies** - Required packages with version range resolution to actual versions, outdated indicators, and vulnerability/deprecation analysis across the full dependency tree +- **Install command** - Multi-package-manager support: npm, pnpm, yarn, bun, deno, and vlt (with JSR support for scoped packages) ### Check package badges @@ -27,49 +28,103 @@ Packages display helpful badges: | ESM / CJS / Dual | Module format support | | TypeScript | Includes type definitions (links to `@types/*` if separate) | | Provenance | Verified build from a known source | +| Engines | Node.js engine compatibility constraints | ### View security information -- **Vulnerability warnings** - Security advisories from the OSV database +- **Vulnerability warnings** - Security advisories from the OSV database, including transitive dependency scanning +- **Deprecated dependency tree** - Shows deprecated packages across the full dependency tree - **Deprecation notices** - Clear warnings for deprecated packages and versions -- **Provenance indicators** - Verified build badges for packages with npm provenance +- **Provenance indicators** - Verified build badges with full attestation details +- **Install scripts warning** - Alerts for packages with lifecycle scripts (postinstall, preinstall, etc.) +- **Security downgrade detection** - Warns when the latest version loses provenance or trusted publishing +- **Module replacement suggestions** - Links to better alternatives for known problematic packages + +### View statistics + +- **Download counts** - Weekly downloads with sparkline charts +- **Download chart** - Interactive full chart with zoom, date range selection, and multiple granularities (daily/weekly/monthly/yearly) +- **Version distribution** - Chart showing download distribution across package versions +- **Install size** - Total size including transitive dependencies +- **Repository stats** - Stars and forks from supported git providers +- **Like counts** - Social engagement via ATProto/Bluesky integration ## Browse source code Press `.` or click the **Code** tab to open the code viewer: -- **File tree** - Navigate the package structure -- **Syntax highlighting** - Language-aware code display -- **Permalinks** - Link to specific lines in files +- **File tree** - Navigate the package structure (sidebar on desktop, drawer on mobile) +- **Syntax highlighting** - Language-aware code display via Shiki +- **Line permalinks** - Link to specific lines (`#L10`) or ranges (`#L10-L20`) +- **Line range selection** - Click + Shift-click for multi-line selection +- **Markdown preview** - Toggle between rendered and source view for `.md` files +- **Raw file access** - Download files via jsDelivr CDN +- **Keyboard shortcut** - Press `.` from any package page -## View statistics +## View auto-generated API documentation -- **Download counts** - Weekly downloads with sparkline charts -- **Install size** - Total size including transitive dependencies -- **Repository stats** - Stars and forks from supported git providers +Press `d` or click the **Docs** tab for auto-generated documentation: -### Supported git providers +- **Type-aware docs** - Generated from published TypeScript types +- **Supports** - Functions, classes, interfaces, type aliases, variables, enums, namespaces +- **Rich display** - Syntax-highlighted signatures, parameters, return types +- **JSDoc rendering** - `@example` blocks, `@deprecated` warnings, `@see` references +- **TOC sidebar** - Navigate long documentation -npmx.dev fetches repository statistics (stars, forks) from these git hosting platforms: +## Compare packages -| Provider | Description | -| ------------------------------------------------------------------------- | ------------------------------------- | -| :icon{name="i-simple-icons-github"} [GitHub](https://github.com) | The most popular git hosting platform | -| :icon{name="i-simple-icons-gitlab"} [GitLab](https://gitlab.com) | Self-hosted instances supported | -| :icon{name="i-simple-icons-bitbucket"} [Bitbucket](https://bitbucket.org) | Atlassian's git hosting service | -| :icon{name="i-simple-icons-codeberg"} [Codeberg](https://codeberg.org) | Free hosting for open source projects | -| :icon{name="i-simple-icons-gitee"} [Gitee](https://gitee.com) | Popular git hosting in China | -| :icon{name="i-simple-icons-sourcehut"} [Sourcehut](https://sr.ht) | Minimalist software forge | -| :icon{name="i-simple-icons-forgejo"} [Forgejo](https://forgejo.org) | Community-driven Gitea fork | -| :icon{name="i-simple-icons-gitea"} [Gitea](https://gitea.com) | Self-hosted git service | -| [Radicle](https://radicle.xyz) | Peer-to-peer code collaboration | -| [Tangled](https://tangled.sh) | Decentralized git hosting | +Navigate to `/compare` or press `c` from a package page: + +- **Side-by-side comparison** - Up to 4 packages at once +- **Facet-based grid** - Compare downloads, size, last updated, and more +- **Download trends overlay** - Overlaid line chart for download history +- **Replacement suggestions** - Module replacement recommendations +- **URL-synced** - Share comparison links (`/compare?packages=a,b,c`) ## Explore users and organizations -- **User profiles** - View any npm user's public packages at `/~username` -- **Organization pages** - Browse org packages at `/@orgname` -- **Search and filter** - Find packages within user/org lists +- **User profiles** - View any npm user's public packages at `/~username`, with filtering, sorting, and total weekly downloads +- **Organization pages** - Browse org packages at `/@orgname` with full search and filtering +- **Admin panels** - When connected via the local connector, manage org members and teams + +## Search and discover + +- **Dual search providers** - Choose between npm registry API and Algolia for faster results +- **Instant results** - Autocomplete suggestions as you type +- **Rich result cards** - Version, description, downloads, date, keywords, deprecation status +- **Sorting** - By popularity, quality, maintenance, or optimal +- **View modes** - Card and table layouts with customizable columns +- **Infinite scroll** - Auto-load additional results as you scroll +- **Keyboard navigation** - Arrow keys to navigate, Enter to select, `/` to focus +- **Package name availability** - Check and claim available package names +- **OpenSearch** - Search directly from the browser address bar + +## Customize your experience + +### Appearance + +- **Theme** - System, light, or dark mode +- **Accent colors** - Multiple color options +- **Background themes** - Various background patterns + +### Display preferences + +- **Relative dates** - Toggle between relative and absolute dates +- **Search provider** - Choose npm or Algolia +- **Language** - 29 locales including RTL (Arabic) with translation coverage tracking +- **Package manager** - Default install command format + +## Administer packages + +Admin features work via a local "connector" CLI that uses your existing npm credentials: + +- **Package access** - Manage read/write permissions +- **Maintainers** - Add/remove package owners +- **Org members** - Add/remove organization members +- **Teams** - Create/destroy teams, manage membership +- **Team access** - Grant/revoke team access to packages +- **Claim packages** - Register new package names +- **Bulk operations** - Queue multiple changes, review the plan, then apply all at once ## Access related resources @@ -89,7 +144,32 @@ Quick access to online development environments detected from package READMEs: | :icon{name="i-simple-icons-jsfiddle"} [JSFiddle](https://jsfiddle.net) | Online editor for web snippets | | :icon{name="i-simple-icons-replit"} [Replit](https://replit.com) | Collaborative browser-based IDE | -### Custom badges +### Supported git providers + +npmx.dev fetches repository statistics (stars, forks) from these git hosting platforms: + +| Provider | Description | +| ------------------------------------------------------------------------- | ------------------------------------- | +| :icon{name="i-simple-icons-github"} [GitHub](https://github.com) | The most popular git hosting platform | +| :icon{name="i-simple-icons-gitlab"} [GitLab](https://gitlab.com) | Self-hosted instances supported | +| :icon{name="i-simple-icons-bitbucket"} [Bitbucket](https://bitbucket.org) | Atlassian's git hosting service | +| :icon{name="i-simple-icons-codeberg"} [Codeberg](https://codeberg.org) | Free hosting for open source projects | +| :icon{name="i-simple-icons-gitee"} [Gitee](https://gitee.com) | Popular git hosting in China | +| :icon{name="i-simple-icons-sourcehut"} [Sourcehut](https://sr.ht) | Minimalist software forge | +| :icon{name="i-simple-icons-forgejo"} [Forgejo](https://forgejo.org) | Community-driven Gitea fork | +| :icon{name="i-simple-icons-gitea"} [Gitea](https://gitea.com) | Self-hosted git service | +| [Radicle](https://radicle.xyz) | Peer-to-peer code collaboration | +| [Tangled](https://tangled.sh) | Decentralized git hosting | + +## Social features + +npmx.dev integrates with the [AT Protocol](https://atproto.com/) (Bluesky) for social features: + +- **Like packages** - Express appreciation for packages you use +- **Bluesky comments** - View discussions about packages from the Bluesky network +- **Social login** - Authenticate with your ATProto identity + +## Custom badges You can add custom npmx badges to your markdown files using the following syntax: @@ -195,3 +275,17 @@ When set to `true`, this parameter replaces the static category label (like "ver | ------------- | -------------------- | ---------------- | | **Version** | `version \| 3.12.0` | `nuxt \| 3.12.0` | | **Downloads** | `downloads/mo \| 2M` | `lodash \| 2M` | + +## Keyboard shortcuts + +| Shortcut | Action | +| ---------- | ---------------------------------------- | +| `/` | Focus search input or navigate to search | +| `?` | Hold to reveal keyboard shortcut hints | +| `.` | Open code viewer from package page | +| `d` | Open docs from package page | +| `c` | Open compare from package page | +| `,` | Navigate to settings | +| `Escape` | Go back from settings | +| Arrow keys | Navigate search results | +| `Enter` | Select highlighted search result |