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
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
- 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.
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
- 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.
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.
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.
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 +.
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.
Interface
One dark palette, one motion library, and a hard 44px target. The UI is quiet so the data is loud.
- 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| decision | alternative | why |
|---|---|---|
| Small manifest shell | Full packument shell | First paint stays small even when the packument is 31 MB. |
| Upstash stale-while-revalidate | Postgres cache | Read-heavy, TTL-shaped data; no schema or migrations for cache entries. |
| Client search while typing | Server render per keystroke | No RSC churn, no aborted server requests, one fetch path. |
| Custom SVG downloads chart | Charting library | Thirty points do not justify a runtime; keyboard and pointer are ours. |
| Native <details> disclosures | Client accordions | Zero JavaScript; works before hydration and in the HTML source. |
| jsDelivr README fallback | Extracting the tarball | One 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.