Self-host

The Emojisense API is open source (MIT). You can run it on your own Cloudflare account, with your own Workers AI calls and your own database.

What you run

The API is one Cloudflare Worker, packages/worker. It serves the data packs as static files, keeps the emoji vectors in its own bundle, embeds queries with Workers AI, caches answers in each data center and stores keys and usage in D1. There are no containers, load balancers or vector databases to run.

You call the embedding model on your own account, under the model’s license. Model weights are never part of the repository.

Requirements

• Node.js 24 and pnpm 9.
• A Cloudflare account with Workers AI. For production traffic, use Workers Paid ($5 a month).
• wrangler login on the machine that embeds the emoji and deploys the Worker.

Steps

1. Build the data packs

   This joins Emojibase, Unicode CLDR and the alias files into the locale packs.

   Terminal

   git clone https://github.com/emojisense/emojisense.git emojisense
   cd emojisense
   pnpm install
   pnpm data:build

2. Embed the emoji on your account

   This sends the emoji descriptions to Workers AI in batches and writes the vector file. Queries and emoji must use the same model at the same size, so keep your choice. bge-m3 at 1,024 dimensions is the production model.

   Terminal

   npx wrangler login
   pnpm --filter @emojisense/data embed -- --models bge-m3 --dims 1024

3. Copy the packs and vectors into the Worker

   Terminal

   pnpm --filter @emojisense/worker sync -- --model bge-m3 --dims 1024

4. Create the database

   D1 holds apps, keys and monthly usage. The schema is in packages/platform/migrations.

   Terminal

   cd packages/worker
   npx wrangler d1 create emojisense        # copy the database_id into wrangler.jsonc
   npx wrangler d1 migrations apply DB --remote

5. Configure

   Edit packages/worker/wrangler.jsonc before the first deploy:

   • name: the Worker name, which is also its workers.dev subdomain.
   • vars.DEV_KEYS: keys that need no database row, as key or key:plan, comma-separated. They allow any origin.
   • ratelimits: requests per minute for keyed and anonymous callers.

6. Deploy

   Terminal

   pnpm --filter @emojisense/worker deploy

7. Point your apps at it

   TypeScript

   const sense = useEmojisense({
     packBaseUrl: "https://emojisense-api.<your-subdomain>.workers.dev/v1/pack/0.1.0",
     endpoint: "https://emojisense-api.<your-subdomain>.workers.dev",
   });

Keys and usage

The dashboard, apps/dashboard, issues keys, binds them to origins and shows usage per month. It is a second Worker that uses the same D1 database. Its README explains the GitHub sign-in setup.

Try it without a Cloudflare account

Workers AI has no local emulator. The offline mode starts the Worker with an empty vector file, so it answers with dictionary results only and marks them "degraded": true. The development keys pk_demo and sk_live_local work without a database row.

pnpm --filter @emojisense/worker sync -- --placeholder
pnpm --filter @emojisense/worker db:migrate
pnpm --filter @emojisense/worker dev:offline   # http://localhost:8788