Simple Analytics Managed Component

Documentation

Managed Components docs are published at https://managedcomponents.dev .

Find out more about Managed Components here for inspiration and motivation details.

🚀 Quickstart local dev environment

1. Make sure you're running node version >=18.
2. Install dependencies with pnpm i
3. Run unit test watcher with pnpm run test:dev

🧪 Local component preview (WebCM)

Use the bundled Web Components Manager to exercise the component against either a local fixture or a live site.

pnpm run dev:webcm

By default, WebCM reads webcm.config.ts for permissions, settings, and proxy target. Tweak the settings block to match the properties you expect inside Zaraz (for example, set the hostname, autoCollect, or collectDnt flags). To proxy a live site or pass ad-hoc settings from the command line:

# Proxy https://example.com while injecting the local component
pnpm run dev:webcm:proxy

# Override the target/settings on the fly
pnpm run dev:webcm -- https://your-site.com --settings_hostname=your-site.com --settings_collectDnt=true

WebCM will expose the proxied site on the host/port defined in the config (defaults to http://localhost:1337).

⚙️ Tool Settings

Settings are used to configure the tool in a Component Manager config file

Example Setting boolean

exampleSetting can be the pixelID or any other essential/optional setting like the option to anonymize IPs, send ecommerce events etc.

🧱 Fields Description

Fields are properties that can/must be sent with certain events

Human Readable Field Name type required

field_id give it a short description and send to a more detailed reference Find more about how to create your own Managed Component.

☁️ Deploy as a Cloudflare Worker

1. Authenticate with your Cloudflare account (interactive browser login):

   pnpm run cf:login

2. Build and deploy the managed component as a Worker:

   pnpm run cf:deploy

   This script runs the local bundle and then invokes managed-component-to-cloudflare-worker with the compiled file in dist/index.js. Before the first deploy, edit wrangler.toml and replace YOUR_ACCOUNT_ID with the Cloudflare account that should own the Worker. The script publishes the Worker as custom-mc-simple-analytics.

3. (Optional) Publish directly with Wrangler if you prefer:

   pnpm run cf:publish

   Wrangler will execute the pnpm run bundle command declared in wrangler.toml before pushing the Worker.

🔌 Add it to Zaraz

In the Cloudflare dashboard navigate to Zaraz → Tools configuration → Add new tool → Custom Managed Component, pick custom-mc-simple-analytics, assign the same permissions you configured locally, and populate the settings. Afterwards wire the component up to your triggers and actions (pageview, event, custom events, etc.).

🧭 Preview & debug safely

Enable Zaraz Preview & Publish. Then, inside the site’s DevTools console, run:

zaraz.preview('<YOUR_DEBUG_KEY>');

Preview mode limits the rollout to sessions with the debug key and exposes detailed telemetry in the browser console. Combine it with Zaraz’ Debug mode or the network panel to inspect emitted events before publishing changes to production traffic.

🔁 CI/CD (optional)

For automated deployments you can connect the Worker in the Cloudflare dashboard to your Git repo (Workers Builds) or add a GitHub Action that runs pnpm run bundle followed by wrangler publish. See Cloudflare Workers CI/CD docs and the Wrangler Action marketplace listing for ready-to-use templates.

📝 License

Licensed under the Apache License.