Skip to content

Commit 658fc34

Browse files
danielroedanielroe
committed
docs: npm comparison/features
1 parent 391a327 commit 658fc34

2 files changed

Lines changed: 174 additions & 60 deletions

File tree

‎README.md‎

Lines changed: 48 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -69,34 +69,54 @@ What npmx offers:
6969

7070
### Comparison with npmjs.com
7171

72-
| Feature | npmjs.com | npmx.dev |
73-
| ------------------------------ | :-------: | :------: |
74-
| Package search | ✅ | ✅ |
75-
| Package details & README | ✅ | ✅ |
76-
| Version history | ✅ | ✅ |
77-
| Dependencies list | ✅ | ✅ |
78-
| User profiles | ✅ | ✅ |
79-
| Organization pages | ✅ | ✅ |
80-
| Provenance indicators | ✅ | ✅ |
81-
| Code browser | ✅ | ✅ |
82-
| Dark mode | ❌ | ✅ |
83-
| Outdated dependency warnings | ❌ | ✅ |
84-
| Module format badges (ESM/CJS) | ❌ | ✅ |
85-
| TypeScript types indicator | ✅ | ✅ |
86-
| Install size calculation | ❌ | ✅ |
87-
| JSR cross-reference | ❌ | ✅ |
88-
| Vulnerability warnings | ✅ | ✅ |
89-
| Deprecation notices | ✅ | ✅ |
90-
| Download charts | ✅ | ✅ |
91-
| Playground links | ❌ | ✅ |
92-
| Keyboard navigation | ❌ | ✅ |
93-
| Multi-provider repo support | ❌ | ✅ |
94-
| Version range resolution | ❌ | ✅ |
95-
| Dependents list | ✅ | 🚧 |
96-
| Package admin (access/owners) | ✅ | 🚧 |
97-
| Org/team management | ✅ | 🚧 |
98-
| 2FA/account settings | ✅ | ❌ |
99-
| Claim new package names | ✅ | ✅ |
72+
| Feature | npmjs.com | npmx.dev |
73+
| ------------------------------------------------ | :----------------: | :---------------------------------: |
74+
| **Package browsing** | | |
75+
| Package search | ✅ | ✅ (dual-provider: npm + Algolia) |
76+
| Package details & README | ✅ | ✅ (with TOC, markdown copy) |
77+
| Version history | ✅ (dedicated tab) | ✅ (sidebar, grouped by dist-tag) |
78+
| Dependencies list | ✅ | ✅ (with outdated indicators) |
79+
| Dependents list | ✅ | 🚧 |
80+
| Code browser | ✅ | ✅ (line permalinks, range select) |
81+
| User profiles | ✅ | ✅ |
82+
| Organization pages | ✅ | ✅ |
83+
| Provenance details | ✅ | ✅ (full attestation section) |
84+
| Download charts | ✅ | ✅ (interactive, multi-granularity) |
85+
| Vulnerability warnings | ✅ | ✅ (transitive dep tree) |
86+
| Deprecation notices | ✅ | ✅ |
87+
| TypeScript types indicator | ✅ | ✅ (with @types/\* links) |
88+
| Funding info display | ✅ | 🚧 |
89+
| **Admin features** | | |
90+
| Package access management | ✅ | ✅ (via connector) |
91+
| Maintainer management | ✅ | ✅ (via connector) |
92+
| Org/team management | ✅ | ✅ (via connector) |
93+
| Claim new package names | ✅ | ✅ (via connector) |
94+
| Bulk operations (plan/apply) | ❌ | ✅ |
95+
| Deprecate/undeprecate | ✅ | 🚧 |
96+
| Trusted publishing (OIDC) | ✅ | 🚧 |
97+
| 2FA/account settings | ✅ | ❌ (use npm CLI) |
98+
| **Only on npmx.dev** | | |
99+
| Dark mode + accent colors | ❌ | ✅ |
100+
| 29-locale internationalization | ❌ | ✅ |
101+
| Multi-PM install (npm/pnpm/yarn/bun/deno/vlt) | ❌ | ✅ |
102+
| Auto-generated API docs from types | ❌ | ✅ |
103+
| Package comparison (up to 4) | ❌ | ✅ |
104+
| Module format badges (ESM/CJS/Dual) | ❌ | ✅ |
105+
| Total install size calculation | ❌ | ✅ |
106+
| Outdated dependency warnings | ❌ | ✅ |
107+
| Deprecated dependency tree | ❌ | ✅ |
108+
| Module replacement suggestions | ❌ | ✅ |
109+
| Install scripts security warning | ❌ | ✅ |
110+
| Security downgrade detection | ❌ | ✅ |
111+
| 10 git providers (GitHub, GitLab, Codeberg, ...) | ❌ | ✅ |
112+
| JSR cross-reference | ❌ | ✅ |
113+
| Playground links from README | ❌ | ✅ |
114+
| Version download distribution chart | ❌ | ✅ |
115+
| Custom badge API (20+ types) | ❌ | ✅ |
116+
| Bluesky/ATProto social features | ❌ | ✅ |
117+
| Keyboard shortcuts (/, ., d, c, ?) | ❌ | ✅ |
118+
| Short URLs (/vue, /vue@3.4.0) | ❌ | ✅ |
119+
| OpenSearch browser integration | ❌ | ✅ |
100120

101121
🚧 = coming soon
102122

‎docs/content/2.guide/1.features.md‎

Lines changed: 126 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -5,18 +5,19 @@ navigation:
55
icon: i-lucide-sparkles
66
---
77

8-
npmx.dev provides a comprehensive set of features for browsing npm packages.
8+
npmx.dev provides a comprehensive set of features for browsing, analyzing, and administering npm packages.
99

1010
## Browse packages
1111

1212
### View package details
1313

1414
Each package page displays:
1515

16-
- **README** - Rendered markdown documentation
17-
- **Versions** - Complete version history with release dates
18-
- **Dependencies** - Required packages with version ranges that resolve to actual versions
19-
- **Dependents** - Packages that depend on this one (coming soon)
16+
- **README** - Rendered markdown with table of contents, active section tracking, and copy-as-markdown
17+
- **Description** - With inline markdown rendering
18+
- **Versions** - Complete version history grouped by dist-tags (latest, next, beta, etc.)
19+
- **Dependencies** - Required packages with version range resolution to actual versions, outdated indicators, and vulnerability/deprecation analysis across the full dependency tree
20+
- **Install command** - Multi-package-manager support: npm, pnpm, yarn, bun, deno, and vlt (with JSR support for scoped packages)
2021

2122
### Check package badges
2223

@@ -27,49 +28,103 @@ Packages display helpful badges:
2728
| ESM / CJS / Dual | Module format support |
2829
| TypeScript | Includes type definitions (links to `@types/*` if separate) |
2930
| Provenance | Verified build from a known source |
31+
| Engines | Node.js engine compatibility constraints |
3032

3133
### View security information
3234

33-
- **Vulnerability warnings** - Security advisories from the OSV database
35+
- **Vulnerability warnings** - Security advisories from the OSV database, including transitive dependency scanning
36+
- **Deprecated dependency tree** - Shows deprecated packages across the full dependency tree
3437
- **Deprecation notices** - Clear warnings for deprecated packages and versions
35-
- **Provenance indicators** - Verified build badges for packages with npm provenance
38+
- **Provenance indicators** - Verified build badges with full attestation details
39+
- **Install scripts warning** - Alerts for packages with lifecycle scripts (postinstall, preinstall, etc.)
40+
- **Security downgrade detection** - Warns when the latest version loses provenance or trusted publishing
41+
- **Module replacement suggestions** - Links to better alternatives for known problematic packages
42+
43+
### View statistics
44+
45+
- **Download counts** - Weekly downloads with sparkline charts
46+
- **Download chart** - Interactive full chart with zoom, date range selection, and multiple granularities (daily/weekly/monthly/yearly)
47+
- **Version distribution** - Chart showing download distribution across package versions
48+
- **Install size** - Total size including transitive dependencies
49+
- **Repository stats** - Stars and forks from supported git providers
50+
- **Like counts** - Social engagement via ATProto/Bluesky integration
3651

3752
## Browse source code
3853

3954
Press `.` or click the **Code** tab to open the code viewer:
4055

41-
- **File tree** - Navigate the package structure
42-
- **Syntax highlighting** - Language-aware code display
43-
- **Permalinks** - Link to specific lines in files
56+
- **File tree** - Navigate the package structure (sidebar on desktop, drawer on mobile)
57+
- **Syntax highlighting** - Language-aware code display via Shiki
58+
- **Line permalinks** - Link to specific lines (`#L10`) or ranges (`#L10-L20`)
59+
- **Line range selection** - Click + Shift-click for multi-line selection
60+
- **Markdown preview** - Toggle between rendered and source view for `.md` files
61+
- **Raw file access** - Download files via jsDelivr CDN
62+
- **Keyboard shortcut** - Press `.` from any package page
4463

45-
## View statistics
64+
## View auto-generated API documentation
4665

47-
- **Download counts** - Weekly downloads with sparkline charts
48-
- **Install size** - Total size including transitive dependencies
49-
- **Repository stats** - Stars and forks from supported git providers
66+
Press `d` or click the **Docs** tab for auto-generated documentation:
5067

51-
### Supported git providers
68+
- **Type-aware docs** - Generated from published TypeScript types
69+
- **Supports** - Functions, classes, interfaces, type aliases, variables, enums, namespaces
70+
- **Rich display** - Syntax-highlighted signatures, parameters, return types
71+
- **JSDoc rendering** - `@example` blocks, `@deprecated` warnings, `@see` references
72+
- **TOC sidebar** - Navigate long documentation
5273

53-
npmx.dev fetches repository statistics (stars, forks) from these git hosting platforms:
74+
## Compare packages
5475

55-
| Provider | Description |
56-
| ------------------------------------------------------------------------- | ------------------------------------- |
57-
| :icon{name="i-simple-icons-github"} [GitHub](https://github.com) | The most popular git hosting platform |
58-
| :icon{name="i-simple-icons-gitlab"} [GitLab](https://gitlab.com) | Self-hosted instances supported |
59-
| :icon{name="i-simple-icons-bitbucket"} [Bitbucket](https://bitbucket.org) | Atlassian's git hosting service |
60-
| :icon{name="i-simple-icons-codeberg"} [Codeberg](https://codeberg.org) | Free hosting for open source projects |
61-
| :icon{name="i-simple-icons-gitee"} [Gitee](https://gitee.com) | Popular git hosting in China |
62-
| :icon{name="i-simple-icons-sourcehut"} [Sourcehut](https://sr.ht) | Minimalist software forge |
63-
| :icon{name="i-simple-icons-forgejo"} [Forgejo](https://forgejo.org) | Community-driven Gitea fork |
64-
| :icon{name="i-simple-icons-gitea"} [Gitea](https://gitea.com) | Self-hosted git service |
65-
| [Radicle](https://radicle.xyz) | Peer-to-peer code collaboration |
66-
| [Tangled](https://tangled.sh) | Decentralized git hosting |
76+
Navigate to `/compare` or press `c` from a package page:
77+
78+
- **Side-by-side comparison** - Up to 4 packages at once
79+
- **Facet-based grid** - Compare downloads, size, last updated, and more
80+
- **Download trends overlay** - Overlaid line chart for download history
81+
- **Replacement suggestions** - Module replacement recommendations
82+
- **URL-synced** - Share comparison links (`/compare?packages=a,b,c`)
6783

6884
## Explore users and organizations
6985

70-
- **User profiles** - View any npm user's public packages at `/~username`
71-
- **Organization pages** - Browse org packages at `/@orgname`
72-
- **Search and filter** - Find packages within user/org lists
86+
- **User profiles** - View any npm user's public packages at `/~username`, with filtering, sorting, and total weekly downloads
87+
- **Organization pages** - Browse org packages at `/@orgname` with full search and filtering
88+
- **Admin panels** - When connected via the local connector, manage org members and teams
89+
90+
## Search and discover
91+
92+
- **Dual search providers** - Choose between npm registry API and Algolia for faster results
93+
- **Instant results** - Autocomplete suggestions as you type
94+
- **Rich result cards** - Version, description, downloads, date, keywords, deprecation status
95+
- **Sorting** - By popularity, quality, maintenance, or optimal
96+
- **View modes** - Card and table layouts with customizable columns
97+
- **Infinite scroll** - Auto-load additional results as you scroll
98+
- **Keyboard navigation** - Arrow keys to navigate, Enter to select, `/` to focus
99+
- **Package name availability** - Check and claim available package names
100+
- **OpenSearch** - Search directly from the browser address bar
101+
102+
## Customize your experience
103+
104+
### Appearance
105+
106+
- **Theme** - System, light, or dark mode
107+
- **Accent colors** - Multiple color options
108+
- **Background themes** - Various background patterns
109+
110+
### Display preferences
111+
112+
- **Relative dates** - Toggle between relative and absolute dates
113+
- **Search provider** - Choose npm or Algolia
114+
- **Language** - 29 locales including RTL (Arabic) with translation coverage tracking
115+
- **Package manager** - Default install command format
116+
117+
## Administer packages
118+
119+
Admin features work via a local "connector" CLI that uses your existing npm credentials:
120+
121+
- **Package access** - Manage read/write permissions
122+
- **Maintainers** - Add/remove package owners
123+
- **Org members** - Add/remove organization members
124+
- **Teams** - Create/destroy teams, manage membership
125+
- **Team access** - Grant/revoke team access to packages
126+
- **Claim packages** - Register new package names
127+
- **Bulk operations** - Queue multiple changes, review the plan, then apply all at once
73128

74129
## Access related resources
75130

@@ -89,7 +144,32 @@ Quick access to online development environments detected from package READMEs:
89144
| :icon{name="i-simple-icons-jsfiddle"} [JSFiddle](https://jsfiddle.net) | Online editor for web snippets |
90145
| :icon{name="i-simple-icons-replit"} [Replit](https://replit.com) | Collaborative browser-based IDE |
91146

92-
### Custom badges
147+
### Supported git providers
148+
149+
npmx.dev fetches repository statistics (stars, forks) from these git hosting platforms:
150+
151+
| Provider | Description |
152+
| ------------------------------------------------------------------------- | ------------------------------------- |
153+
| :icon{name="i-simple-icons-github"} [GitHub](https://github.com) | The most popular git hosting platform |
154+
| :icon{name="i-simple-icons-gitlab"} [GitLab](https://gitlab.com) | Self-hosted instances supported |
155+
| :icon{name="i-simple-icons-bitbucket"} [Bitbucket](https://bitbucket.org) | Atlassian's git hosting service |
156+
| :icon{name="i-simple-icons-codeberg"} [Codeberg](https://codeberg.org) | Free hosting for open source projects |
157+
| :icon{name="i-simple-icons-gitee"} [Gitee](https://gitee.com) | Popular git hosting in China |
158+
| :icon{name="i-simple-icons-sourcehut"} [Sourcehut](https://sr.ht) | Minimalist software forge |
159+
| :icon{name="i-simple-icons-forgejo"} [Forgejo](https://forgejo.org) | Community-driven Gitea fork |
160+
| :icon{name="i-simple-icons-gitea"} [Gitea](https://gitea.com) | Self-hosted git service |
161+
| [Radicle](https://radicle.xyz) | Peer-to-peer code collaboration |
162+
| [Tangled](https://tangled.sh) | Decentralized git hosting |
163+
164+
## Social features
165+
166+
npmx.dev integrates with the [AT Protocol](https://atproto.com/) (Bluesky) for social features:
167+
168+
- **Like packages** - Express appreciation for packages you use
169+
- **Bluesky comments** - View discussions about packages from the Bluesky network
170+
- **Social login** - Authenticate with your ATProto identity
171+
172+
## Custom badges
93173

94174
You can add custom npmx badges to your markdown files using the following syntax:
95175

@@ -195,3 +275,17 @@ When set to `true`, this parameter replaces the static category label (like "ver
195275
| ------------- | -------------------- | ---------------- |
196276
| **Version** | `version \| 3.12.0` | `nuxt \| 3.12.0` |
197277
| **Downloads** | `downloads/mo \| 2M` | `lodash \| 2M` |
278+
279+
## Keyboard shortcuts
280+
281+
| Shortcut | Action |
282+
| ---------- | ---------------------------------------- |
283+
| `/` | Focus search input or navigate to search |
284+
| `?` | Hold to reveal keyboard shortcut hints |
285+
| `.` | Open code viewer from package page |
286+
| `d` | Open docs from package page |
287+
| `c` | Open compare from package page |
288+
| `,` | Navigate to settings |
289+
| `Escape` | Go back from settings |
290+
| Arrow keys | Navigate search results |
291+
| `Enter` | Select highlighted search result |

0 commit comments

Comments
 (0)