Add public repository metrics to website hero

Author: mojeebdev

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to StackBrief are documented here.
 
+## Unreleased
+
+### Added
+
+- The product website hero now displays public, source-linked GitHub stars and npm downloads since StackBrief launched. Metrics refresh hourly, remain token-free, and disappear individually rather than making the page fail when a provider is unavailable.
+
 ## 1.1.2 — 2026-07-18
 
 ### Changed

apps/web/README.md

@@ -9,6 +9,12 @@ The website uses two complementary pieces of product language:
 
 The first names the product; the second describes the developer outcome. Do not merge or replace either without a deliberate product decision.
 
+## Public metrics
+
+The hero can show two public, source-linked credibility signals: GitHub stars and npm downloads since StackBrief launched on 2026-07-12. They are fetched server-side and cached for one hour, so the page never exposes a token or depends on client-side requests. If either public API is unavailable or rate-limited, that one metric is omitted; the homepage still renders normally.
+
+The npm label deliberately says **downloads since launch**. npm's download endpoint reports a requested date range, so StackBrief does not present it as an ambiguous all-time total.
+
 ## Development
 
 ```bash

apps/web/app/globals.css

@@ -2,17 +2,70 @@ import { BrandMark } from "../components/brand-mark";
 import { CopyButton } from "../components/copy-button";
 import { FieldMap } from "../components/field-map";
 import { OriginArtwork } from "../components/origin-artwork";
+import {
+  getRepositoryMetrics,
+  type RepositoryMetrics,
+} from "../lib/repository-metrics";
 
 const GITHUB = "https://github.com/mojeebdev/stackbrief";
 const NPM = "https://www.npmjs.com/package/@blindspotlab/stackbrief";
 const ORIGIN_POST = "https://x.com/MojeebMotion/status/2078447946782163291?s=20";
 const FOUNDER_X = "https://x.com/MojeebMotion";
 
+// Next requires route-segment values to be statically analyzable literals.
+export const revalidate = 3600;
+
 function ExternalArrow() {
   return <span aria-hidden="true">↗</span>;
 }
 
-export default function HomePage() {
+function formatCount(value: number): string {
+  return new Intl.NumberFormat("en-US").format(value);
+}
+
+function HeroMetrics({ metrics }: { metrics: RepositoryMetrics }) {
+  const hasMetrics =
+    metrics.githubStars !== undefined ||
+    metrics.npmDownloadsSinceLaunch !== undefined;
+
+  if (!hasMetrics) return null;
+
+  return (
+    <div className="hero-metrics" aria-label="Public StackBrief repository metrics">
+      <div className="hero-metric-list">
+        {metrics.githubStars !== undefined ? (
+          <a
+            className="hero-metric"
+            href={GITHUB}
+            target="_blank"
+            rel="noreferrer"
+            aria-label={`${formatCount(metrics.githubStars)} GitHub stars. View the StackBrief repository.`}
+          >
+            <strong>{formatCount(metrics.githubStars)}</strong>
+            <span>GitHub stars</span>
+          </a>
+        ) : null}
+        {metrics.npmDownloadsSinceLaunch !== undefined ? (
+          <a
+            className="hero-metric"
+            href={NPM}
+            target="_blank"
+            rel="noreferrer"
+            aria-label={`${formatCount(metrics.npmDownloadsSinceLaunch)} npm downloads since StackBrief launched. View the package.`}
+          >
+            <strong>{formatCount(metrics.npmDownloadsSinceLaunch)}</strong>
+            <span>npm downloads since launch</span>
+          </a>
+        ) : null}
+      </div>
+      <p>Public repository metrics · refreshed hourly</p>
+    </div>
+  );
+}
+
+export default async function HomePage() {
+  const metrics = await getRepositoryMetrics();
+
   return (
     <>
       <a className="skip-link" href="#main">Skip to content</a>
@@ -38,6 +91,7 @@ export default function HomePage() {
                 <a className="button button-primary" href="#install">Start with the CLI <span aria-hidden="true">↓</span></a>
                 <a className="text-link" href={GITHUB} target="_blank" rel="noreferrer">Read the repository <ExternalArrow /></a>
               </div>
+              <HeroMetrics metrics={metrics} />
               <div className="hero-proof" aria-label="StackBrief principles"><span>Offline analysis</span><i /><span>Source-cited</span><i /><span>Agent-neutral</span></div>
             </div>
             <FieldMap />

apps/web/app/page.tsx

@@ -0,0 +1,78 @@
+const GITHUB_REPOSITORY = "mojeebdev/stackbrief";
+const NPM_PACKAGE = "@blindspotlab/stackbrief";
+const PACKAGE_LAUNCH_DATE = "2026-07-12";
+
+export const REPOSITORY_METRICS_REVALIDATE_SECONDS = 60 * 60;
+
+export interface RepositoryMetrics {
+  githubStars?: number;
+  npmDownloadsSinceLaunch?: number;
+}
+
+interface GitHubRepositoryResponse {
+  stargazers_count?: unknown;
+}
+
+interface NpmDownloadsResponse {
+  downloads?: unknown;
+}
+
+function asCount(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0
+    ? Math.floor(value)
+    : undefined;
+}
+
+function currentUtcDate(): string {
+  return new Date().toISOString().slice(0, 10);
+}
+
+async function fetchJson<T>(url: string, headers?: HeadersInit): Promise<T | undefined> {
+  try {
+    const response = await fetch(url, {
+      headers,
+      next: { revalidate: REPOSITORY_METRICS_REVALIDATE_SECONDS },
+    });
+
+    if (!response.ok) return undefined;
+
+    return (await response.json()) as T;
+  } catch {
+    return undefined;
+  }
+}
+
+async function fetchGitHubStars(): Promise<number | undefined> {
+  const repository = await fetchJson<GitHubRepositoryResponse>(
+    `https://api.github.com/repos/${GITHUB_REPOSITORY}`,
+    {
+      Accept: "application/vnd.github+json",
+      "X-GitHub-Api-Version": "2022-11-28",
+    },
+  );
+
+  return asCount(repository?.stargazers_count);
+}
+
+async function fetchNpmDownloadsSinceLaunch(): Promise<number | undefined> {
+  const range = `${PACKAGE_LAUNCH_DATE}:${currentUtcDate()}`;
+  const packageName = encodeURIComponent(NPM_PACKAGE);
+  const downloads = await fetchJson<NpmDownloadsResponse>(
+    `https://api.npmjs.org/downloads/point/${range}/${packageName}`,
+  );
+
+  return asCount(downloads?.downloads);
+}
+
+/**
+ * Public signals only. A missing provider result intentionally does not make the
+ * homepage fail: the available metric can still be rendered on its own.
+ */
+export async function getRepositoryMetrics(): Promise<RepositoryMetrics> {
+  const [githubStars, npmDownloadsSinceLaunch] = await Promise.all([
+    fetchGitHubStars(),
+    fetchNpmDownloadsSinceLaunch(),
+  ]);
+
+  return { githubStars, npmDownloadsSinceLaunch };
+}

apps/web/lib/repository-metrics.ts

@@ -1,6 +1,6 @@
 {
   "name": "@blindspotlab/stackbrief-web",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "private": true,
   "scripts": {
     "dev": "next dev",