Skip to content

engineering

Fast is a design decision.

npmsearch renders a small manifest first, streams the heavy parts, and caches every slow upstream. No request waterfalls, no 31 MB first paint. This page is the map.

31 MB

packument kept off first paint

100 ms

search debounce

1,000

results, virtualized

30 days

download history

01

The shell

The first paint never waits for the README. The shell is built from a single small manifest plus downloads.

request

browser

RSC shell

next.js

/pkg/latest

+ downloads, parallel

streamed

README · analytics · history

Heavy sections suspend independently; the shell never blocks on the full packument.
  • The latest manifest is a few kilobytes, not a 31 MB document.
  • Metadata and downloads fetch in parallel; no waterfall.
  • Skeletons reserve the final boxes, so streamed sections do not shift the layout.
02

The cache

Stale data is served immediately. Refresh happens after the response, not during it.

request

route or API

Upstash

versioned key

serve

fresh / stale

after()

one refresh

search60s / 1h
package5m / 24h
analytics1h / 24h
readme1d / 7d
  • Fresh and hard TTLs; stale entries still render.
  • One in-flight refresh per key, deduped with after().
  • Cache failures are fail-open: the page falls back to upstream.
03

Search

The input is the source of truth. Typing updates the URL without re-rendering the server page.

keystroke

input

100 ms

leading + trailing

/api/search

abort previous

virtual rows

1,000 cap

  • AbortController cancels the previous request.
  • history.replaceState keeps the URL shareable without RSC churn.
  • A 60-second client cache serves repeat queries instantly.
04

README

Registry first. If it is empty, fetch the published README, then sanitize and highlight on the server.

registry

readme field

jsDelivr

fallback

sanitize

rehype schema

Shiki

server only

TOC + copy

reader tools

  • Scripts, iframes and event handlers never reach the DOM.
  • Relative images and links resolve against the GitHub repository.
  • Common grammars are preloaded; rare ones are lazy.
05

Analytics

Install size and outdated dependencies are estimates computed from registry manifests, with hard bounds.

direct deps

latest manifests

bounded BFS

depth 3 · 60 pkgs · 2s

size + status

ESM · CJS · types

  • 8 concurrent requests; time and package budgets stop fan-out.
  • A dependency is outdated when the latest release leaves its range.
  • Estimates are labelled; truncated results end with a +.
06

Routes

The canonical route is long-form. The short routes are aliases, including scoped and pinned versions.

/package/axios

canonical

/axios

short alias

/axios@1.21.1

pinned

  • Scoped names work: /@types/node and /@types/node@22.
  • Reserved top-level paths are rejected before the registry.
  • The home page stays static; only package pages are dynamic.
07

Interface

One dark palette, one motion library, and a hard 44px target. The UI is quiet so the data is loud.

downloadsCJStypesopen sourceactions
  • Motion is limited to opacity and transform; no layout animation.
  • Reduced motion is respected globally; focus rings are never removed.
  • Token changes live in app/globals.css — no Tailwind config.

stack

Small, sharp tools.

No CSS-in-JS, no component library, no chart runtime. The boring parts stay boring.

  • Next.js

    framework

  • React

    UI

  • TypeScript

    types

  • Tailwind CSS

    styling

  • Upstash Redis

    cache

  • Vercel

    hosting

  • pnpm

    packages

  • Playwright

    e2e

  • Vitest

    unit

  • Shiki

    highlighting

Tradeoffs

not every default
decisionalternativewhy
Small manifest shellFull packument shellFirst paint stays small even when the packument is 31 MB.
Upstash stale-while-revalidatePostgres cacheRead-heavy, TTL-shaped data; no schema or migrations for cache entries.
Client search while typingServer render per keystrokeNo RSC churn, no aborted server requests, one fetch path.
Custom SVG downloads chartCharting libraryThirty points do not justify a runtime; keyboard and pointer are ours.
Native <details> disclosuresClient accordionsZero JavaScript; works before hydration and in the HTML source.
jsDelivr README fallbackExtracting the tarballOne small request instead of a tar parser and a multi-megabyte download.

open source

Built in the open.

If you care about fast interfaces and honest registry data, there is room. Start with an issue, a test, or a small performance win.