caramel

The open-source and privacy-first alternative to Honey. Caramel The Trusted Alternative To Honey For Finding Coupons

Automatically checked · GitHub checked 2026-11-13

Overview

App Checks Extension Checks Discord

Caramel - Trusted Coupon Finder

Caramel is the open‑source, privacy‑first alternative to Honey.
It automatically tests codes at checkout, never sells your data, and never overwrites creators’ affiliate links. Today Caramel already supports more than 4,000 stores. You can find even more information at https://grabcaramel.com.

caramel-banner

See it work: about 10% off a real Corsair order

A live checkout on corsair.com for a niche part, the Corsair Type-4 Debossed PATA power cable. Caramel pops up at checkout, tries the store's codes one by one and keeps the best: LOCHVANESS takes the item from $99.95 to $90.00 (CA$9.95 saved, about 10%). The shopper's personal details are blurred.

Caramel finding and applying the code LOCHVANESS on a Corsair checkout, taking the item from $99.95 to $90.00

Watch the full-quality video (MP4)

Why choose Caramel?

  • 100% open source – every release is on GitHub for public audit

  • Privacy first – the extension asks only for the permissions it needs to find the store you're on, read the checkout page and apply codes (tabs, storage, sign-in) – no ads, no third‑party trackers

  • Real‑time savings meter – see exactly how much each code saved as it is tested

  • Creator‑friendly – Caramel keeps existing affiliate links intact so influencers get the credit they deserve

  • Community‑powered – join our Discord, file issues, or open PRs to make Caramel even sweeter

  • Discord

Browser support

  • Chrome / Edge (Manifest V3)
  • Firefox (AMO)
  • Safari for macOS and iOS – converted from the Chromium build and re‑skinned automatically during CI
Chrome Web Store badge Download on the App Store badge Firefox Add‑ons badge Edge Add‑ons badge

Getting Started

Prerequisites: Docker with Compose v2 (the one command that runs the app), plus Node.js 22+ and pnpm 9 (this repo's packageManager field — corepack enable picks it up) for installing deps, the escape hatches, and the test suites.

  1. Install dependencies (repo root):

    pnpm install
    
  2. Create your env file:

    cp apps/caramel-app/.env.example apps/caramel-app/.env
    

    Then fill it in using the secrets table below — most values are already correct or optional.

  3. Run it — one command builds the image and boots the whole stack:

    pnpm dev
    

    pnpm dev is docker compose up --build: it builds the web image, boots Postgres 18.4 + web, runs prisma migrate deploy automatically inside the container (creating and seeding the app-owned coupon catalog), and serves the app + API at http://localhost:28000. Local and CI run this same docker-compose.yml in prod-mode builds — and it is the deployment unit production migrates onto (cutover gated, human-run) — so what you run locally is what ships, which means hot reload is deliberately traded away (ratified 2026-07-09). When you want framework hot reload or to run one package on the host, bring up Postgres alone (docker compose up postgres -d) and use an escape hatch:

    pnpm dev:next        # web app on the host (Next.js dev server, :28000, hot reload)
    pnpm dev:extension   # the browser extension in a web-ext Chromium instance
    

    Coupon routes return 200 locally: the app owns its coupon catalog, created and seeded in the local Postgres by prisma migrate deploy when the stack boots. In production the external pipeline keeps it fresh by pushing to POST /api/ingest/catalog (see docs/INGEST.md); the old externally-owned-DB "degraded mode" is retired (see docs/LOCAL-DEV.md).

  4. Run the tests:

    pnpm test                             # unit — real vitest, both packages (~300 tests)
    pnpm --filter caramel-app test:e2e    # Playwright — needs Postgres up + migrations (docs/LOCAL-DEV.md)
    pnpm --filter caramel-app eval        # cart-classifier AI eval — needs OPENROUTER_API_KEY, see apps/caramel-app/evals/README.md
    

Secrets — where each .env.example value comes from

apps/caramel-app/.env is gitignored and never committed — copy .env.example (step 2) and fill it in per this table.

DATABASE_URL — provided by local compose, but verify the value:

postgresql://caramel:caramel_password@localhost:28005/caramel?schema=public

This matches what .env.example ships — the compose Postgres creates exactly this caramel role (see docker-compose.yml).

COUPONS_DATABASE_URL — optional, bridge-sync only (leave unset locally):

The app serves its own coupon catalog from DATABASE_URL, so this is unset in local dev — the app never reads it at boot. It is consumed only by the migration-period bridge:sync job (pnpm --filter caramel-app bridge:sync), which reads the still-live external, Python-owned caramel_coupons Postgres (strictly read-only) and replays it into the app catalog through the same ingest engine as POST /api/ingest/catalog. It ships commented out in .env.example — uncomment it only when running that bridge against a reachable external DB (set-but-empty fails fast at boot by design). See docs/LOCAL-DEV.md and docs/INGEST.md.

Generate locally (any random string) — at least one of the first two is required:

VariableNotes
JWT_SECRET
BETTER_AUTH_SECRET
EXTENSION_OAUTH_STATE_SECRETOnly needed to test extension OAuth locally

Local defaults — already correct in .env.example, no action needed:

VariableShipped value
BETTER_AUTH_URLhttp://localhost:28000
NEXT_PUBLIC_BASE_URLhttp://localhost:28000
BCRYPT_SALT_ROUNDS10
ALLOWED_ORIGINSblank (same-origin + extensions only)
SENDLY_FROM_EMAIL / SENDLY_FROM_NAME[email protected] / Caramel
OPENROUTER_MODELanthropic/claude-haiku-4.5

(NODE_ENV is deliberately absent from .env.example: it is framework-managed — Next.js sets it per command and env files cannot override it.)

Local-optional — leave blank unless you need the specific feature:

VariableUnlocks
CHROME_EXTENSION_ORIGIN / FIREFOX_EXTENSION_ORIGIN / SAFARI_EXTENSION_ORIGINExtension OAuth from a locally-loaded unpacked extension
COUPONS_ADMIN_SECRETPOST /api/coupons/expire (server-to-server)
INGEST_API_KEYPOST /api/ingest/catalog — the coupons pipeline supplier push (server-to-server)
UPKUMA_HEALTH_SECRETGET /api/health/db — any value works, it just has to match
API_ENCRYPTION_ENABLED / NEXT_PUBLIC_API_ENCRYPTION_ENABLEDResponse encryption — the two flags must agree

Human-only — external provider dashboards, optional for a basic boot:

VariableNeeded for
GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRETGoogle sign-in
APPLE_CLIENT_ID / APPLE_TEAM_ID / APPLE_KEY_ID / APPLE_PRIVATE_KEY / APPLE_REDIRECT_URIApple sign-in (the app signs its own client secret from the .p8 key) — see docs/APPLE_OAUTH_LOCAL_TESTING.md
SENDLY_API_KEYOutgoing email via Sendly (signup verification, etc.); key scopes emails:send + emails:read
OPENROUTER_API_KEYThe cart classifier (/api/classify-cart) and pnpm eval
NEXT_PUBLIC_SENTRY_DSNError/APM reporting (no-op locally without it)
NEXT_PUBLIC_GOOGLE_ANALYTICS_IDAnalytics

Repo layout at a glance

  • apps/caramel-app — Next.js web app + API (grabcaramel.com)
  • apps/caramel-extension — browser extension (Chrome/Edge/Firefox/Safari)
  • docker-compose.yml + Dockerfile — one-root-compose (web + Postgres); pnpm dev runs it
  • RUNBOOK.md — deploys, health checks, rollback, on-call

Full directory purposes: see Project layout below. Local infra detail: docs/LOCAL-DEV.md. Deploys/ops: RUNBOOK.md.

Project layout

PathPurpose
apps/caramel-appWeb app + API for grabcaramel.com — Next.js, Prisma (auth DB), Better Auth
apps/caramel-extensionBrowser extension source (Chrome/Edge/Firefox/Safari — no in-repo Xcode project; release CI packages Safari from the WXT build at .output/chrome-mv3 via safari-web-extension-converter, see below)
docker-compose.yml / DockerfileOne-root-compose: web + Postgres — the graph pnpm dev builds and runs — and the deployment unit production migrates onto

Safari Extension Icons

The Safari Web Extension Converter (xcrun safari-web-extension-converter) automatically converts Chrome extension icons to Safari app icons, but it often adds white padding around them. .github/workflows/scripts/generate-safari-icons.sh and update-safari-icons.sh fix that: they generate and apply properly formatted Safari icons from a single source icon (apps/caramel-extension/icons/original.png).

Both scripts run only inside release-extension.yml's Safari publish job (macOS runner; needs ImageMagick + the Xcode project that job's own xcrun step generates) — there's no standalone local entry point. Read the workflow file if you need to reproduce a step by hand.

CI/CD

The project uses GitHub Actions for CI/CD. The workflow is defined in .github/workflows/.

For deploys, health checks, rollback, and known failure modes, see RUNBOOK.md.

License

See LICENSE file for details.