🕵️‍♂️ Sherlock

Check social media accounts usernames

A serverless username search tool powered by Cloudflare Workers and Containers. Search for a username across hundreds of social media platforms instantly.

Tech Stack

• Frontend: Hono with JSX
• Runtime: Cloudflare Workers
• Backend: Python Flask in Cloudflare Containers
• Validation: Zod schemas
• Styling: TailwindCSS
• Code Quality: Vite Plus with Oxlint and Oxfmt

Getting Started

Prerequisites

• pnpm 12.9.1
• Node.js 24.21.0 LTS (.node-version) or newer
• Docker running locally for Container development
• Cloudflare account with Workers and Container access

Installation

# Install dependencies
pnpm install

# Generate TypeScript types
pnpm cf-typegen

Cloudflare configuration lives in cloudflare.config.ts; Vite handles development and builds. Generated Worker types live in .cloudflare/types/ and are ignored by Git.

Development

# Start local development server
pnpm dev

Open the local URL printed by the development server to access the application.

Deployment

# Sign in to Cloudflare
pnpm exec cf auth login

# Build and validate without uploading
pnpm build
pnpm deploy --dry-run

# Deploy to Cloudflare Workers
pnpm deploy

Worker Previews

# Deploy a Preview for the current Git branch
pnpm preview

# Or provide a Preview name
pnpm preview my-feature

Preview configuration includes the Sherlock Container and Durable Object export, ready for Preview Container support in cf. Current cf releases reject Durable Object managed Containers in Previews, so pnpm preview is blocked until that support arrives. The username cache currently uses the production KV namespace.

Usage

Web Interface

Navigate to the deployed URL and enter a username to search.

API

Search for a username programmatically:

curl https://sherlock.nuro.dev/your_username_here \
  -H "Accept: application/json"

Response format:

{
  "data": {
    "GitHub": {
      "status": "found",
      "url": "https://github.com/username"
    },
    "Twitter": {
      "status": "found",
      "url": "https://twitter.com/username"
    }
  },
  "error": null
}

Code Quality

# Format code
pnpm format

# Lint and auto-fix
pnpm lint

# Check without fixing
pnpm check

# Check TypeScript
pnpm typecheck

License

See LICENSE file for details.

Acknowledgments

💙 Powered by sherlock-project/sherlock