🌐 Favicon

automagically grab the favicon of a url

📖 Usage

add this to your html:

<img loading="lazy" src="https://favicon.jaw.dev?url=<url>" />

Note

the first request will be slow, but the subsequent requests will be cached.

How it works

1. First Request (Cache Miss):

   • Extracts the domain from the provided URL
   • Attempts to fetch favicon from multiple common locations in parallel:
     • /favicon.ico, /favicon.png, /favicon.svg
     • Apple touch icons
     • Web app manifest icons
   • Returns the first successful match (within 1.5 second timeout)
   • Optimizes images by resizing to 16x16 if needed
   • Stores the favicon in SQLite database with 24-hour expiration
   • Returns the favicon with X-Favicon-Source: fetched header

2. Subsequent Requests (Cache Hit):

   • Checks database for cached favicon
   • If found and not expired, returns immediately
   • Response includes ETag for browser caching
   • Returns with X-Favicon-Source: cached header
   • Much faster than initial fetch (~3µs vs 500ms+)

3. Fallback:

   • If no favicon found after timeout, returns a default favicon
   • Response includes X-Favicon-Source: default header

API Endpoints

GET /

Fetches the favicon for a given URL.

Parameters:

• url (required): The URL to fetch the favicon for

Example:

https://favicon.jaw.dev?url=github.com

GET /domains

Lists all cached favicons in the database.

Parameters:

• format (optional): Response format
  • Default: HTML table view
  • json: Returns JSON array

HTML Response:

Returns an HTML table with the following columns:

• id: Database ID
• domain: Cached domain
• data: Favicon preview with size in bytes
• content_type: MIME type of the favicon
• created_at: Timestamp when cached

JSON Response:

curl https://favicon.jaw.dev/domains?format=json

Returns JSON array:

[
  {
    "id": 1,
    "domain": "github.com",
    "data_size": 5430,
    "content_type": "image/png",
    "created_at": "2025-10-15 04:55:40"
  }
]

GET /healthz

Health check endpoint. Returns ok if the service is healthy.

📑 Docs

• See DEVELOPMENT for development guide.
• See CONTRIBUTION for contribution guide.

📜 License

Distributed under the MIT License © wajeht. See LICENSE for more information.