npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

react-hardcover-shelf

v0.1.0

Published

A React widget for displaying a Hardcover bookshelf

Readme

react-hardcover-shelf

This React component allows you to display a Hardcover bookshelf in a React application, powered by the official Hardcover GraphQL API.

Demo

Preview

Example image

Installation

pnpm install react-hardcover-shelf

(or with a package manager of your choice)

Usage

Create a scoped API key from your Hardcover account (Account → API), then pass it to the component:

import React from "react";
import HardcoverShelf from "react-hardcover-shelf";

export default function App() {
  return <HardcoverShelf apiKey="YOUR_API_KEY" userId="kylekarpack" />;
}

When no userId is supplied, the shelf of the API key's owner is displayed. userId accepts either a numeric user ID or a username.

API key scopes

Hardcover lets you pick exactly which scopes an API key grants. read:library:public is the only scope the widget needs for the default usage of displaying the shelf of the API key's owner:

Generate a scoped API key →

| Scope | What it grants | | --------------------- | --------------------------------------------------------------- | | read:library:public | Your public shelf entries (the books the widget displays) | | read:me:content | Your public profile (id, username, name, avatar) | | read:catalog | Hardcover's public book catalog (covers, authors, descriptions) |

The additional scopes (read:me:content and read:catalog) are only necessary if you want to view someone else's public bookshelves, i.e. when passing the userId prop with another Hardcover user. The link below pre-selects everything:

Generate an API key for public shelves →

With these scopes, an exposed key cannot modify your library, cannot read private or followers-only entries, and cannot see your email. Do not select any write scopes.

Security note: a scoped key kept in the browser is still visible to visitors and usable for rate-limit-burning reads. That is fine for personal sites and blogs. If you need stronger isolation, you can run a small proxy that attaches the Authorization header server-side and pass its URL via the apiUrl option instead.

Customization

| Option | Type | Description | Default | | -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | | apiKey | string | An API key from a Hardcover account's settings page; a "Bearer" prefix is optional. Required unless apiUrl is provided. See API key scopes for the recommended read-only scopes. | - | | apiUrl | string | An alternative endpoint to send queries to; useful for proxies that keep the API key server-side | Hardcover API | | userId | string | The Hardcover user ID or username whose shelf to fetch | The owner of the API key | | shelf | string | The shelf from which to fetch books ("read", "currently-reading", or "to-read") | read | | sort | string | The field by which to sort the results returned (title, author, rating, avg_rating, date_read, date_added, or pages) | date_read | | order | string | The direction in which to sort the results ("a" for ascending or "d" for descending) | d | | limit | number | The maximum number of books to be returned | 10 | | width | number | Minimum width allowed for each book | 100 | | search | string | Filter fetched books by title and author | "" | | groupBy | string | Group books by a field (e.g. "year") | - | | displayOptions | object | Options for hiding book details, background images, and grid spacing | - | | filter | function | A filter function to include only some of the fetched books | - |

Development

This project uses Vite+.

  • pnpm dev to run the demo page dev server
  • pnpm storybook to launch storybook for testing
  • pnpm test to run the test suite
  • pnpm check to format-check, lint, and type-check everything

Contribution

Please feel free to open issues or pull requests and I will review as promptly as I am able.