The complete open source platform to run your entire marketplace. Storefront, vendor panel, admin console, and integrations in one enterprise-grade platform you own.
TypeScript b2b-marketplacecomposable-commerceecommerceenterpriseheadless-commercemarketplacemedusamedusajsmulti-vendortypescript
feat(cli): add telemetry transparency — persistent config, notice, and docs (#795)
Jakub Sieradzki8d426b940f33
diff --git a/apps/docs/v2/telemetry.mdx b/apps/docs/v2/telemetry.mdxnew file mode 100644index 000000000..afdaace34--- /dev/null+++ b/apps/docs/v2/telemetry.mdx@@ -0,0 +1,67 @@+---+title: "Telemetry"+description: "Learn about the anonymous usage data collected by the Mercur CLI"+---++## Overview++The Mercur CLI collects **anonymous usage data** to help us understand how the CLI is used and improve the developer experience. This data is collected by default but can be easily disabled.++## What We Collect++When you run CLI commands (`create`, `init`, `add`, `registry:build`), the following data is sent:++| Data | Description |+|------|-------------|+| Event type | Which command was run and its outcome |+| Node.js version | Your Node.js runtime version |+| Node environment | The `NODE_ENV` value |+| Mercur version | Version of `@mercurjs/core` in your project |+| Medusa version | Version of `@medusajs/framework` in your project |+| Package manager | npm, yarn, pnpm, or bun |+| Project structure | Whether `src/` directory is used, alias prefix |+| System info | OS, platform, architecture, CPU model/speed/count, RAM |+| Environment | Whether running in WSL, Docker, or a TTY |+| Deployment vendor | Detected hosting platform (Railway, Fly.io, Heroku, etc.) |+| Project ID | SHA-256 hash (base64) of your git remote URL — **not the URL itself** |+| Project config | Contents of your `blocks.json` configuration |+| Email | **Only** if you voluntarily provided it during `mercurjs create` |++## What We Do NOT Collect++- Source code or file contents+- File names or directory structure+- Git history or commit messages+- Personal data (beyond the optional email above)++## How to Opt Out++### Using the CLI++```bash+mercurjs telemetry --disable+```++### Using an environment variable++```bash+export MERCUR_DISABLE_TELEMETRY=true+```++This is useful for CI/CD environments or shared configurations.++### Check current status++```bash+mercurjs telemetry+```++## Where Data Goes++Telemetry events are sent to `https://telemetry.mercurjs.com`. The data is used exclusively by the Mercur team to prioritize features and fix issues.++## Re-enabling Telemetry++```bash+mercurjs telemetry --enable+```diff --git a/packages/cli/src/commands/add.ts b/packages/cli/src/commands/add.tsindex ab46f090e..77260345f 100644--- a/packages/cli/src/commands/add.ts+++ b/packages/cli/src/commands/add.ts@@ -11,7 +11,7 @@ import { highlighter } from "../utils/highlighter";import { logger } from "../utils/logger";import { runInit } from "./init";import { handleError } from "../utils/handle-error";-import { sendTelemetryEvent } from "../telemetry";+import { sendTelemetryEvent, showTelemetryNoticeIfNeeded } from "../telemetry";export const addOptionsSchema = z.object({blocks: z.array(z.string()).optional(),@@ -35,6 +35,7 @@ export const add = new Command().option("-s, --silent", "mute output.", false).action(async (items, opts) => {try {+ showTelemetryNoticeIfNeeded();const options = addOptionsSchema.parse({blocks: items,cwd: path.resolve(opts.cwd),diff --git a/packages/cli/src/commands/create.ts b/packages/cli/src/commands/create.tsindex 3547262d3..c3ac92e83 100644--- a/packages/cli/src/commands/create.ts+++ b/packages/cli/src/commands/create.ts@@ -4,7 +4,7 @@ import { pipeline } from "node:stream/promises";import path from "path";import { clearRegistryContext } from "@/src/registry/context";-import { sendTelemetryEvent, setTelemetryEmail } from "@/src/telemetry";+import { sendTelemetryEvent, setTelemetryEmail, showTelemetryNoticeIfNeeded } from "@/src/telemetry";import { setupDatabase, type SetupDatabaseResult } from "@/src/utils/create-db";import { getPackageManager } from "@/src/utils/get-package-manager";import { handleError } from "@/src/utils/handle-error";@@ -56,6 +56,7 @@ export const create = new Command().action(async (name, opts) => {try {validateNodeVersion();+ showTelemetryNoticeIfNeeded();let projectName = name;if (!projectName) {@@ -383,7 +384,7 @@ ${header("Documentation:")}}function feedbackOutro(): string {- return `${kleur.bgCyan(kleur.black(" Have feedback? "))} Visit us on ${createTerminalLink("GitHub", "https://github.com/mercurjs/mercur")}.`;+ return `${kleur.bgCyan(kleur.black(" Have feedback? "))} Visit us on ${createTerminalLink("GitHub", "https://github.com/mercurjs/mercur")}.\n${kleur.bgMagenta(kleur.black(" Join the community! "))} Chat with us on ${createTerminalLink("Discord", "https://discord.gg/hnZBzc4NJU")}.`;}function createTerminalLink(text: string, url: string) {diff --git a/packages/cli/src/commands/init.ts b/packages/cli/src/commands/init.tsindex 283a10349..0cff83892 100644--- a/packages/cli/src/commands/init.ts+++ b/packages/cli/src/commands/init.ts@@ -12,7 +12,7 @@ import { handleError } from "../utils/handle-error";import { highlighter } from "../utils/highlighter";import { logger } from "../utils/logger";import { spinner } from "../utils/spinner";-import { sendTelemetryEvent } from "../telemetry";+import { sendTelemetryEvent, showTelemetryNoticeIfNeeded } from "../telemetry";export const initOptionsSchema = z.object({cwd: z.string(),@@ -34,6 +34,7 @@ export const init = new Command().option("-s, --silent", "mute output.", false).action(async (opts) => {try {+ showTelemetryNoticeIfNeeded();const options = initOptionsSchema.parse({cwd: path.resolve(opts.cwd),...opts,diff --git a/packages/cli/src/commands/registry-build.ts b/packages/cli/src/commands/registry-build.tsindex ea9baf9f0..3466c9c52 100644--- a/packages/cli/src/commands/registry-build.ts+++ b/packages/cli/src/commands/registry-build.ts@@ -13,7 +13,7 @@ import { spinner } from "@/src/utils/spinner";import { Command } from "commander";import { z } from "zod";import { REGISTRY_ITEM_SCHEMA_URL } from "../registry";-import { sendTelemetryEvent } from "../telemetry";+import { sendTelemetryEvent, showTelemetryNoticeIfNeeded } from "../telemetry";export const buildOptionsSchema = z.object({cwd: z.string(),@@ -48,6 +48,7 @@ export const registryBuild = new Command()async function buildRegistry(opts: z.infer<typeof buildOptionsSchema>) {try {+ showTelemetryNoticeIfNeeded();const options = buildOptionsSchema.parse(opts);const [{ errors, resolvePaths, config }, projectInfo] = await Promise.all([diff --git a/packages/cli/src/commands/telemetry.ts b/packages/cli/src/commands/telemetry.tsindex ba193ee69..57e0124dc 100644--- a/packages/cli/src/commands/telemetry.ts+++ b/packages/cli/src/commands/telemetry.ts@@ -1,4 +1,5 @@-import { toggleTelemetry } from "@/src/telemetry";+import { toggleTelemetry, TELEMETRY_DOCS_URL } from "@/src/telemetry";+import { configStore } from "@/src/telemetry/store";import { handleError } from "@/src/utils/handle-error";import { logger } from "@/src/utils/logger";import { Command } from "commander";@@ -6,19 +7,43 @@ import { Command } from "commander";export const telemetry = new Command().name("telemetry").description(- "enable or disable the collection of anonymous usage data. If no option is provided, the command enables the collection of anonymous usage data."+ "manage the collection of anonymous usage data")- .option("--enable", "enable telemetry (default)")+ .option("--enable", "enable telemetry").option("--disable", "disable telemetry").action(async (opts) => {try {- const enabled = !opts.disable;+ if (opts.enable && opts.disable) {+ logger.error("Cannot use --enable and --disable together.");+ return;+ }++ // No flags — show current status+ if (!opts.enable && !opts.disable) {+ const configEnabled = configStore.get("telemetry_enabled");+ const envDisabled = process.env.MERCUR_DISABLE_TELEMETRY === 'true';+ const enabled = configEnabled && !envDisabled;+ const status = enabled ? "enabled" : "disabled";+ logger.log(`Telemetry is currently ${status}.`);+ if (envDisabled && configEnabled) {+ logger.log(`(Disabled via MERCUR_DISABLE_TELEMETRY environment variable)`);+ }+ logger.log(+ enabled+ ? `Run "mercurjs telemetry --disable" to opt out.`+ : `Run "mercurjs telemetry --enable" to opt in.`+ );+ logger.log(`Learn more: ${TELEMETRY_DOCS_URL}`);+ return;+ }++ const enabled = !!opts.enable;toggleTelemetry(enabled);if (enabled) {- logger.success("Telemetry enabled.");+ logger.success(`Telemetry enabled. Learn more: ${TELEMETRY_DOCS_URL}`);} else {- logger.success("Telemetry disabled.");+ logger.success("Telemetry disabled. No data will be collected.");}} catch (error) {handleError(error);diff --git a/packages/cli/src/telemetry/index.ts b/packages/cli/src/telemetry/index.tsindex 878e6656a..96a294905 100644--- a/packages/cli/src/telemetry/index.ts+++ b/packages/cli/src/telemetry/index.ts@@ -5,6 +5,7 @@ import { detectSystemInfo } from "./detect-system-info";import { getPackageManager } from "../utils/get-package-manager";import { hashToBase64 } from "./hash";import { getProjectInfo, type PackageJson } from "../utils/get-project-info";+import { highlighter } from "../utils/highlighter";const TELEMETRY_URL = process.env.MERCUR_TELEMETRY_PROXY_URL || 'https://telemetry.mercurjs.com/api/v1/events'@@ -22,6 +23,31 @@ export const toggleTelemetry = (enabled: boolean) => {configStore.set("telemetry_enabled", enabled)}+export const TELEMETRY_DOCS_URL = 'https://docs.mercurjs.com/v2/telemetry'++export const showTelemetryNoticeIfNeeded = () => {+ if (configStore.get("notice_shown")) {+ return;+ }++ configStore.set("notice_shown", true);++ if (process.env.MERCUR_DISABLE_TELEMETRY === 'true') {+ return;+ }++ console.error(+ [+ "",+ "Mercur collects anonymous usage data to improve the CLI experience.",+ `You can disable this at any time by running: ${highlighter.info("mercurjs telemetry --disable")}`,+ `Or by setting ${highlighter.info("MERCUR_DISABLE_TELEMETRY=true")}`,+ `Learn more: ${highlighter.info(TELEMETRY_DOCS_URL)}`,+ "",+ ].join("\n")+ );+}+const isTelemetryEnabled = () => {return configStore.get("telemetry_enabled") && process.env.MERCUR_DISABLE_TELEMETRY !== 'true'}diff --git a/packages/cli/src/telemetry/store.ts b/packages/cli/src/telemetry/store.tsindex 44e966982..6b6fca13b 100644--- a/packages/cli/src/telemetry/store.ts+++ b/packages/cli/src/telemetry/store.ts@@ -1,55 +1,57 @@-import os from "os";+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";+import { homedir } from "os";import { join } from "path";-interface TelemetryConfig {- "telemetry_enabled": boolean;- "telemetry_email": string | null;+ telemetry_enabled: boolean;+ telemetry_email: string | null;+ notice_shown: boolean;}-class ConfigStore {- private config: TelemetryConfig;- public path: string = join(os.tmpdir(), "mercur");+const CONFIG_DIR = join(homedir(), ".mercur");+const CONFIG_PATH = join(CONFIG_DIR, "config.json");- constructor() {- this.config = this.createBaseConfig();- }-- private createBaseConfig(): TelemetryConfig {- return {- "telemetry_enabled": true,- "telemetry_email": null,- };- }+const DEFAULTS: TelemetryConfig = {+ telemetry_enabled: true,+ telemetry_email: null,+ notice_shown: false,+};+class ConfigStore {get<K extends keyof TelemetryConfig>(key: K): TelemetryConfig[K] {- return this.config[key];+ const config = this.read();+ return config[key];}set<K extends keyof TelemetryConfig>(key: K, value: TelemetryConfig[K]): void {- this.config[key] = value;- }-- all(): TelemetryConfig {- return this.config;- }-- size(): number {- return Object.keys(this.config).length;- }-- has(key: keyof TelemetryConfig): boolean {- return key in this.config && this.config[key] !== undefined;- }-- del(key: keyof TelemetryConfig): void {- delete this.config[key];- }-- clear(): void {- this.config = this.createBaseConfig();+ const config = this.read();+ config[key] = value;+ this.write(config);+ }++ private read(): TelemetryConfig {+ try {+ if (!existsSync(CONFIG_PATH)) {+ return { ...DEFAULTS };+ }+ const raw = readFileSync(CONFIG_PATH, "utf-8");+ const parsed = JSON.parse(raw);+ return { ...DEFAULTS, ...parsed };+ } catch {+ return { ...DEFAULTS };+ }+ }++ private write(config: TelemetryConfig): void {+ try {+ mkdirSync(CONFIG_DIR, { recursive: true });+ writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2) + "\n", {+ mode: 0o600,+ });+ } catch {+ // Silently fail — telemetry config is non-critical+ }}}export const configStore = new ConfigStore();-