Convalytics
Bijection component for server-side analytics tracking with Convalytics
git clone https://github.com/bijectionhq/convalytics.git
cd convalytics
git checkout 7ac95d6ab3baf4454fe065345fd2e0fc958abc4dBijection repository access is required. Request access.
Description
Bijection component for server-side analytics tracking with Convalytics
Explore the package README for API concepts, configuration, and examples. Check the Bijection source for adaptation-specific setup.
Review the source and its dependencies before adopting this package. Source availability does not establish npm publication or runtime qualification.
Getting started
- Get the source at the revision above and read its package documentation.
- Check the required Bijection SDK version, dependencies, and external service credentials.
- Follow the package setup instructions and the guide to using components.
- Exercise the component in your deployment according to your project’s verification rules.
Open source
Maintained source: bijectionhq/convalytics. Based on Dan-Cleary/convalytics-convex-component. License: MIT. Consult the repository for license terms, notices, and contributor attribution.
From the upstream publisher
Convex component for server-side analytics tracking with Convalytics
Explore the demo ↗Upstream overview
From the upstream package documentation.
Convalytics provides server-side analytics for Convex applications, allowing you to track product events reliably from mutations and actions. Unlike client-side tracking, server-side events bypass ad blockers and aren't lost on page unloads. It includes web analytics capabilities and provides a unified dashboard for both server events and browser page views.
Use cases
From the upstream package documentation.
- Track user lifecycle events like signups, upgrades, and feature adoption from your Convex mutations
- Monitor payment and subscription events from webhook handlers in Convex actions
- Analyze user behavior patterns without worrying about ad blockers or dropped events
- Get reliable analytics data for business metrics and product decisions
- Combine server-side product events with traditional web analytics in one dashboard
How it works
From the upstream package documentation.
The component integrates as a Convex component that you register in convex.config.ts and configure with a write key from the Convalytics dashboard. You create an analytics singleton that wraps the component with your credentials.
To track events, call analytics.track() from your mutations or actions, passing the Convex context and event data including name, userId, and optional properties. Events are delivered asynchronously and failures are logged without affecting your application flow.
For web analytics, you add a script tag to your HTML that points to your Convex deployment URL. The CLI tool npx convalytics init can automate the entire setup process, creating projects, installing dependencies, and configuring your environment variables.
Upstream package FAQ
Does the Convalytics Component affect Convex function performance?
No, the Convalytics Component delivers events asynchronously and never throws errors. Analytics failures are logged but never propagate to your mutations or actions, ensuring your core application logic remains unaffected.
Can I track events from both Convex mutations and actions?
Yes, the Convalytics Component works in both mutations and actions. Use analytics.track(ctx, event) in mutations for database operations and in httpActions for webhook processing or external API calls.
How do I set up the write key for the Convalytics Component?
Set your write key as a Convex environment variable using npx convex env set CONVALYTICS_WRITE_KEY your_key. Get your write key from the Convalytics dashboard or use npx convalytics init to auto-generate one.
What data can I include with tracked events?
The Convalytics Component accepts event name, userId, optional userEmail, userName, sessionId, timestamp, and custom properties. Properties support strings, numbers, and booleans for flexible event metadata.
Does the component include client-side web analytics?
The Convalytics Component handles server-side tracking only. For complete analytics, pair it with the Convalytics browser script for page views and client-side events in the same dashboard.
Use with agents and CLI
Give your coding agent the component’s source identity and setup guidance.
Help me integrate Convalytics with Bijection.
Read: https://bijection.com/components/convalytics/SKILL.md
Check SDK compatibility and dependency availability.
Follow this project's execution and verification rules.Upstream README.md
View repository ↗Documentation from Dan-Cleary/convalytics-convex-component, recorded October 23, 2026. APIs and setup may differ in the Bijection adaptation.
convalytics-dev
Server-side analytics for Convex apps. Track events reliably from mutations and actions — server-side events aren't affected by ad blockers and are never dropped on page unload.
Pairs with the Convalytics browser script for full-stack analytics: web traffic + server-side product events in one dashboard.
Install
npm install convalytics-dev
Setup
1. Register the component
Add to convex/convex.config.ts (create it if it doesn't exist):
import { defineApp } from "convex/server";
import analytics from "convalytics-dev/convex.config";
const app = defineApp();
app.use(analytics);
export default app;
2. Create an analytics singleton
Create convex/analytics.ts:
import { components } from "./_generated/api";
import { Convalytics } from "convalytics-dev";
export const analytics = new Convalytics(components.convalytics, {
writeKey: process.env.CONVALYTICS_WRITE_KEY!,
});
3. Set your write key
Add to your Convex environment variables (via the Convex dashboard or CLI):
npx convex env set CONVALYTICS_WRITE_KEY your_write_key_here
Get your write key from the Convalytics dashboard.
Usage
Track events from mutations
import { mutation } from "./_generated/server";
import { v } from "convex/values";
import { analytics } from "./analytics";
export const createUser = mutation({
args: { name: v.string(), email: v.string(), plan: v.string() },
handler: async (ctx, args) => {
const userId = await ctx.db.insert("users", args);
await analytics.track(ctx, {
name: "user_signed_up",
userId: String(userId),
props: { plan: args.plan },
});
return userId;
},
});
Track events from actions
import { httpAction } from "./_generated/server";
import { analytics } from "./analytics";
export const stripeWebhook = httpAction(async (ctx, req) => {
const event = await req.json();
if (event.type === "invoice.payment_succeeded") {
await analytics.track(ctx, {
name: "subscription_renewed",
userId: event.data.object.customer,
props: { amount: event.data.object.amount_paid },
});
}
return new Response(null, { status: 200 });
});
API
new Convalytics(component, options)
| Option | Type | Required | Description |
|---|---|---|---|
writeKey | string | Yes | Your Convalytics project write key |
ingestUrl | string | No | Override ingest endpoint (for local dev) |
analytics.track(ctx, event)
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Event name (e.g. "user_signed_up") |
userId | string | Yes | Stable user identifier |
userEmail | string | No | User email — shown in dashboard instead of raw ID |
userName | string | No | User display name — shown in dashboard |
sessionId | string | No | Session ID (auto-generated if omitted) |
timestamp | number | No | Unix ms timestamp (defaults to Date.now()) |
props | Record<string, string | number | boolean> | No | Additional properties |
Events are delivered asynchronously and never throw — analytics failures are logged but never propagate to the caller.
Web analytics
For browser page view tracking, add to your <head>:
<script defer src="https://YOUR_CONVEX_SITE_URL/script.js?key=YOUR_WRITE_KEY"></script>
Your Convex site URL is shown in the Convalytics dashboard after claiming your project, or use the CLI (below) to insert it automatically.
Quick setup via CLI
npx convalytics init
Auto-provisions a project, installs the package, patches convex.config.ts, creates convex/analytics.ts, sets env vars, and inserts the script tag. No write key required — one is created for you. Pass an existing key to reuse a project:
npx convalytics init YOUR_WRITE_KEY
Verify the pipeline:
npx convalytics verify YOUR_WRITE_KEY