Counterscale is a simple web analytics tracker and dashboard that you self-host on Cloudflare.
It's designed to be easy to deploy and maintain, and should cost you near-zero to operate – even at high levels of traffic (Cloudflare's free tier could hypothetically support up to 100k hits/day).
NOTE: Counterscale is currently in very early development and shouldn't be used in any actual production setting. We welcome people trying it and giving feedback/contributing, but heads up this project is still super early.
If you don't have one already, create a Cloudflare account here and verify your email address.
- Go to your Cloudflare dashboard and, if you do not already have one, set up a Cloudflare Workers subdomain
- Enable Cloudflare Analytics Engine beta for your account (screenshot)
- If this is your first time using Workers, you have to create a Worker before you can enable the Analytics Engine. Navigate to Workers & Pages > Overview, click the "Create Worker" button (screenshot) to create a "Hello World" worker (it doesn't matter what you name this Worker as you can delete it later).
- Create a Cloudflare API token. This token needs
Account.Account Analytics
permissions at a minimum (screenshot).- WARNING: Keep this window open or copy your API token somewhere safe (e.g. a password manager), because if you close this window you will not be able to access this API token again and have to start over.
- Download the latest Counterscale release (or clone the repository) and extract the source files to a folder.
- With your terminal, navigate to the folder containing the source files.
- Run
npm install
- Run
npx wrangler pages project create counterscale
and create a new Pages project.- You will be prompted to enter the "production branch name". Just use the default provided (e.g. "main" or "production").
- NOTE: If this is your first time invoking
wrangler
on the terminal, you will be prompted to sign into your Cloudflare account.
- Run
npx wrangler pages secret put CF_BEARER_TOKEN
→ when prompted, paste the API token you created - Run
npx wrangler pages secret put CF_ACCOUNT_ID
→ when prompted, paste your Cloudflare Account ID- Find your account ID by visiting Workers and Pages > Overview. It is displayed on the right hand side of the screen.
- Run
npm run deploy
– this will do several things:- Create a new Analytics Engine dataset, called
metricsDataset
- Deploy the site and give you the deployment URL.
- Create a new Analytics Engine dataset, called
- The site should now be deployed. Visit
https://{subdomain-emitted-from-npm-run-deploy}.pages.dev
.- NOTE: It may take take a few minutes before the subdomain becomes live.
When Counterscale is deployed, it makes tracker.js
available at the URL you deployed to:
https://{subdomain-emitted-from-npm-run-deploy}.pages.dev/tracker.js
To start tracking website traffic on your web property, copy/paste the following snippet into your website HTML:
<script>
(function () {
window.counterscale = {
q: [["set", "siteId", "your-unique-site-id"], ["trackPageview"]],
};
})();
</script>
<script
id="counterscale-script"
src="https://{subdomain-emitted-from-npm-run-deploy}.pages.dev/tracker.js"
defer
></script>
Be sure to replace your-unique-site-id
with a unique string/slug representing your web property. Use a unique site ID for each property you place the tracking script on.
If the website is not immediately available (e.g. "Secure Connection Failed"), it could be because Cloudflare has not yet activated your subdomain (yoursubdomain.workers.dev). This process can take a minute; you can check in on the progress by visiting the newly created worker in your Cloudflare dashboard (Workers & Pages → counterscale).
The deployment URL can always be changed to go behind a custom domain you own. More here.
To get started, in the project root, copy .dev.vars.example
to .dev.vars
.
Open .dev.vars
and enter the same values for CF_BEARER_TOKEN
and CF_ACCOUNT_ID
you used earlier.
Counterscale is built on Remix and Cloudflare Workers. In development, you have two options:
npm run dev
→ This runs the Vite development server in Node.js. This server will automatically rebuild files when you change them, but it does not best reflect Cloudflare's serverless platform.npm run preview
→ This runs Cloudflare's Miniflare server with a build of the Remix files. This closer matches the deployment environment, but does not (yet) automatically rebuild your app.
There is only one "database": the Cloudflare Analytics Engine dataset, which is communicated entirely over HTTP using Cloudflare's API.
Right now there is no local "test" database. This means in local development:
- Writes will no-op (no hits will be recorded)
- Reads will be read from the production Analaytics Engine dataset (local development shows production data)
Cloudflare Analytics Engine uses sampling to make high volume data ingestion/querying affordable at scale (this is similar to most other analytics tools, see Google Analytics on Sampling). You can find out more how sampling works with CF AE here.
Counterscale development is 100% volunteer-driven. If you use and like this software and want to see it improve, we encourage you to contribute with Issues or Pull Requests.
The primary goal of Counterscale is to be super easy to self-host and maintain. It should be "set up once and forget".
To achieve that:
- There should be no application state outside of CF Analytics Engine
- e.g. no additional relational database like MySQL, PostgreSQL, etc.
- That means no
users
table, nosites
table, etc. - This also means retention will be limited by what CF Analytics Engine provides. While it could be possible to stand up a "hit counter" for long-lived data (e.g. years), that would mean another database, which we will not pursue.
- We prioritize backwards compatibility
- New
metricsDataset
columns can be added, but old columns cannot be removed or renamed (they can however, be "forgotten"). - That also means it's okay if a feature only works during a period where the data is active.
- New