The Problem

Clients that need turnkey browser‑automation or data‑extraction demos spend weeks building scaffolding, wiring APIs, and styling UI before they can showcase Hyperbrowser’s capabilities. The lack of ready‑made, production‑grade examples forces teams to reinvent common patterns and increases time‑to‑value.

What This Does

hyperbrowser-app-examples is a portfolio of 29 self‑contained Next.js applications that demonstrate end‑to‑end Hyperbrowser workflows. Each folder (e.g., Idea-generator-reddit/, competitor-tracker/, mediresearch/) contains a complete front‑end, API routes, and TypeScript typings.

Key files illustrate the core stack:

  • Idea-generator-reddit/app/lib/hyperbrowser.ts – thin wrapper around Hyperbrowser’s REST client, used by API routes such as app/api/generate/route.ts.
  • competitor-tracker/app/api/crawl/route.ts – receives a URL, invokes the Hyperbrowser client, stores results via lib/db.ts.
  • UI components like Idea-generator-reddit/app/components/sections/HeroSection.tsx showcase Tailwind‑styled, reusable React components.

Across the portfolio the same patterns recur: a Next.js API route calls hyperbrowser.ts, data is optionally persisted with a lightweight DB helper, and the UI consumes the JSON response via React hooks (useIdeaGeneration.ts).

How It Is Wired

Execution for a typical example starts at the Next.js API route. In Idea-generator-reddit/app/api/generate/route.ts the exported POST handler calls hyperbrowser.generateIdea(payload). The generateIdea function lives in app/lib/hyperbrowser.ts, which builds a request using the environment variable HYPERBROWSER_API_KEY and forwards it to the Hyperbrowser service. The response is returned to the route, which then sends JSON back to the client.

On the client side, app/hooks/useIdeaGeneration.ts invokes fetch('/api/generate', …) and updates local state. UI components (IdeaCard.tsx, ProgressBar.tsx) read that state and render results.

The internal import graph shows 421 modules and 135 import edges. The most fan‑in module is competitor-tracker/lib/db.ts (5 inbound imports, 1 outbound), making it a low‑instability hotspot (0.17). Conversely, entry modules such as Idea-generator-reddit/app/components/index.ts have zero inbound imports and ten outbound imports, yielding an instability of 1 – any change there can ripple widely.

A circular import exists between flow-mapper/lib/crawl.ts and flow-mapper/lib/graph.ts. This introduces a load‑time dependency cycle that can complicate refactoring because both modules must be loaded before either can be evaluated.

How To Use It

# Clone the portfolio
git clone https://github.com/moses-y/hyperbrowser-app-examples.git
cd hyperbrowser-app-examples

# Install dependencies for a chosen example
cd Idea-generator-reddit
npm ci          # uses package-lock.json
# Create .env.local (example)
cat <<EOF > .env.local
HYPERBROWSER_API_KEY=your-key-here
EOF

# Run the dev server
npm run dev     # starts Next.js on http://localhost:3000

Each example’s README repeats these steps; missing pieces (e.g., Dockerfile) are not present.

Real‑World Use

A market‑research team could embed competitor-tracker/ into an internal portal. A nightly cron job (implemented as a Next.js API route) calls competitor-tracker/app/api/crawl/route.ts, stores competitor pricing data via lib/db.ts, and the front‑end visualizes trends with the pre‑built Tailwind charts.

Code Health & Issues

  • HIGH – No LICENSE – repository root lacks a license file; redistribution rights are undefined.
  • HIGH – No CI – 426 source files, no .github/workflows or other CI config; builds are never gated.
  • MEDIUM – Dependabot missing – 29 manifest files, no automated dependency updates.
  • MEDIUM – Test coverage – 1 test file for 426 source files (ratio 0.002).
  • LOW – Convention files – missing .editorconfig, .gitattributes, and formatter config.

Measured static analysis also reported 15 high‑severity findings (deep nesting, duplicated blocks, import cycles, oversized files) and 52 medium issues (high branching density, etc.). These are concrete hotspots that should be prioritized before heavy production use.

The Bottom Line

The repo offers a rich catalog of ready‑to‑run Hyperbrowser demos, valuable for fast prototyping and client presentations. However, the lack of licensing, CI, and adequate testing means it is best treated as a reference implementation rather than a production baseline. Teams should audit high‑instability modules and resolve the documented code‑health problems before integrating any example into a critical workflow.