Skip to content

Find a component

Loading the directory…

↑ ↓ to select · Enter to open · Esc to closeBrowse all →
Contributor login

Convalytics

Bijection component for server-side analytics tracking with Convalytics

Bijection source
git clone https://github.com/bijectionhq/convalytics.git
cd convalytics
git checkout 7ac95d6ab3baf4454fe065345fd2e0fc958abc4d

Bijection 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.

Available to evaluate

Review the source and its dependencies before adopting this package. Source availability does not establish npm publication or runtime qualification.

Getting started

  1. Get the source at the revision above and read its package documentation.
  2. Check the required Bijection SDK version, dependencies, and external service credentials.
  3. Follow the package setup instructions and the guide to using components.
  4. 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.

agent-prompt.md
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)

OptionTypeRequiredDescription
writeKeystringYesYour Convalytics project write key
ingestUrlstringNoOverride ingest endpoint (for local dev)

analytics.track(ctx, event)

FieldTypeRequiredDescription
namestringYesEvent name (e.g. "user_signed_up")
userIdstringYesStable user identifier
userEmailstringNoUser email — shown in dashboard instead of raw ID
userNamestringNoUser display name — shown in dashboard
sessionIdstringNoSession ID (auto-generated if omitted)
timestampnumberNoUnix ms timestamp (defaults to Date.now())
propsRecord<string, string | number | boolean>NoAdditional 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

Keywords