Deploy

If you want your own counter service under a custom domain, deploy Tally API to Cloudflare Pages. The project uses Pages Functions for the API and Cloudflare D1 for persistence, so there is no separate database to provision outside your Cloudflare account.

Prerequisites

• A Cloudflare account
• A JavaScript runtime, such as Bun or Node.js

The examples below use Bun because that is what I use personally. If you are only adapting the deployment flow, you can replace the package-manager commands with npm, pnpm, or yarn equivalents.

If Wrangler is not authenticated yet, run bunx wrangler login before you create the D1 database or deploy the site.

Deploy to Cloudflare Pages

1. Clone the repository and install dependencies:

git clone https://github.com/xueelf/tally-api.git
cd tally-api
bun install

2. Create a D1 database:

bunx wrangler d1 create tally-api

3. Copy the returned database_id into d1_databases in wrangler.json:

"d1_databases": [
  {
    "binding": "DB",
    "database_name": "tally-api",
    "database_id": "<your database id>"
  }
]

Replace the placeholder with the real database ID. Without it, local development and deployment will fail. If your database already exists, bunx wrangler d1 list prints its ID instead.

4. Apply the schema to the remote database:

bunx wrangler d1 migrations apply DB --remote

Migrations live in migrations/ and are tracked in the d1_migrations table, so this command only applies what is still pending.

5. Generate worker type definitions:

bun run types

6. Build the docs site:

bun run docs:build

7. Deploy to Cloudflare Pages:

bunx wrangler pages deploy

Wrangler uses the pages_build_output_dir setting from wrangler.json, so the static docs and the API routes under functions are deployed together.

Migrating an Existing KV Deployment

Counters that still live in KV can be copied into D1 with scripts/migrate-kv-to-d1.ts. It overwrites rather than adds, so re-running it never double counts. The script talks to the Cloudflare REST API, so export a token with Workers KV Storage: Read and D1: Edit permissions first:

export CLOUDFLARE_API_TOKEN=<api token>
bun run db:migrate            # add --dry-run to preview without writing

It uses the KV namespace and D1 database IDs from wrangler.json by default; set KV_NAMESPACE_ID, D1_DATABASE_ID, or CLOUDFLARE_ACCOUNT_ID to override them.

Once the counters are migrated and verified, you can delete the now-unused kv_namespaces block from wrangler.json and remove the KV namespace from your Cloudflare account.

Local Development

bun run db:migrate:local
bun run dev

db:migrate:local applies the migrations to the local SQLite database that wrangler pages dev uses, and dev builds the docs, generates types, and starts wrangler pages dev ./dist. Once it is running, open http://localhost:8788 to test the docs site and API locally.

Notes

If all you want is your own counter service, the steps above are enough. After that, you can switch the domain, adjust the copy, or pick a different theme if needed.

For route rules, response formats, and error handling, see API Reference.