Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 48 additions & 28 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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, /[email protected]) | ❌ | ✅ |
| OpenSearch browser integration | ❌ | ✅ |

🚧 = coming soon

Expand Down
158 changes: 126 additions & 32 deletions docs/content/2.guide/1.features.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,18 +5,19 @@ 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

### View package details

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

Expand All @@ -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

Expand All @@ -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 |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Hyphenate compound adjective.

“open source projects” should be “open‑source projects” when used as a compound adjective.

✏️ Proposed tweak
-| :icon{name="i-simple-icons-codeberg"} [Codeberg](https://codeberg.org)    | Free hosting for open source projects |
+| :icon{name="i-simple-icons-codeberg"} [Codeberg](https://codeberg.org)    | Free hosting for open‑source projects |
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
| :icon{name="i-simple-icons-codeberg"} [Codeberg](https://codeberg.org) | Free hosting for open source projects |
| :icon{name="i-simple-icons-codeberg"} [Codeberg](https://codeberg.org) | Free hosting for open-source projects |
🧰 Tools
🪛 LanguageTool

[uncategorized] ~156-~156: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ...s://codeberg.org) | Free hosting for open source projects | | :icon{name="i-simple-icons...

(EN_COMPOUND_ADJECTIVE_INTERNAL)

| :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:

Expand Down Expand Up @@ -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 |
Loading