chore(shared): replace telemetry postinstall with runtime notice

.changeset/sdk-84-remove-telemetry-postinstall.md

@@ -0,0 +1,9 @@
+---
+'@clerk/shared': patch
+---
+
+Replace the telemetry `postinstall` script with a one-time runtime notice, printed once per process on server runtimes (Node, excluding CI) when the telemetry collector boots against a development instance. Drops the `std-env` dependency.
+
+Removing `postinstall` improves the package's supply-chain posture: `@clerk/shared` no longer executes arbitrary code at install time, aligning with package-manager defaults that increasingly disable install scripts.
+
+Browser-only applications with no server-side Clerk runtime (e.g. a Vite SPA) will not surface an in-band notice. Telemetry behavior and opt-out (`telemetry={false}` or `*_CLERK_TELEMETRY_DISABLED`) are unchanged; disclosure for these setups is provided at https://clerk.com/docs/telemetry.

packages/shared/package.json

@@ -121,8 +121,7 @@
  }
  },
  "files": [
- "dist",
- "scripts"
+ "dist"
  ],
  "scripts": {
  "build": "tsdown",
@@ -131,7 +130,6 @@
  "dev:pub": "pnpm dev -- --env.publish",
  "format": "node ../../scripts/format-package.mjs",
  "format:check": "node ../../scripts/format-package.mjs --check",
- "postinstall": "node ./scripts/postinstall.mjs",
  "lint": "eslint src",
  "lint:attw": "attw --pack . --profile node16",
  "lint:publint": "publint",
@@ -143,8 +141,7 @@
  "@tanstack/query-core": "catalog:repo",
  "dequal": "2.0.3",
  "glob-to-regexp": "0.4.1",
- "js-cookie": "3.0.7",
- "std-env": "^3.9.0"
+ "js-cookie": "3.0.7"
  },
  "devDependencies": {
  "@base-org/account": "catalog:module-manager",

packages/shared/src/__tests__/telemetry.notice.spec.ts

@@ -0,0 +1,114 @@
+/**
+ * @vitest-environment node
+ */
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+
+import { __resetTelemetryNoticeForTests, maybeShowTelemetryNotice } from '../telemetry/notice';
+import { automatedEnvironmentVariables } from '../utils/runtimeEnvironment';
+
+const CI_VARS = automatedEnvironmentVariables;
+
+function clearCIEnv() {
+ for (const name of CI_VARS) {
+ delete process.env[name];
+ }
+}
+
+describe('maybeShowTelemetryNotice', () => {
+ let logSpy: ReturnType<typeof vi.spyOn>;
+ let originalCIEnv: Record<string, string | undefined>;
+
+ beforeEach(() => {
+ originalCIEnv = Object.fromEntries(CI_VARS.map(name => [name, process.env[name]]));
+ clearCIEnv();
+ __resetTelemetryNoticeForTests();
+ logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+ });
+
+ afterEach(() => {
+ logSpy.mockRestore();
+ for (const [name, value] of Object.entries(originalCIEnv)) {
+ if (typeof value === 'string') {
+ process.env[name] = value;
+ } else {
+ delete process.env[name];
+ }
+ }
+ });
+
+ test('prints the disclosure on Node', () => {
+ maybeShowTelemetryNotice();
+
+ expect(logSpy).toHaveBeenCalled();
+ const printed = logSpy.mock.calls.map(call => String(call[0])).join('\n');
+ expect(printed).toMatch(/Clerk collects telemetry/);
+ expect(printed).toMatch(/clerk\.com\/docs\/telemetry/);
+ });
+
+ test('does not print again on subsequent calls in the same process', () => {
+ maybeShowTelemetryNotice();
+ maybeShowTelemetryNotice();
+ maybeShowTelemetryNotice();
+
+ const disclosureCalls = logSpy.mock.calls.filter(call => /Clerk collects telemetry/.test(String(call[0])));
+ expect(disclosureCalls).toHaveLength(1);
+ });
+
+ test('skips entirely when skip:true is passed', () => {
+ maybeShowTelemetryNotice({ skip: true });
+
+ expect(logSpy).not.toHaveBeenCalled();
+ });
+
+ test('skips when a CI env var is set', () => {
+ // eslint-disable-next-line turbo/no-undeclared-env-vars
+ process.env.CI = 'true';
+
+ maybeShowTelemetryNotice();
+
+ expect(logSpy).not.toHaveBeenCalled();
+ });
+
+ test.each(CI_VARS)('skips when %s is set', name => {
+ process.env[name] = '1';
+
+ maybeShowTelemetryNotice();
+
+ expect(logSpy).not.toHaveBeenCalled();
+ });
+
+ test('skips in a browser-like environment', () => {
+ const original = (globalThis as { window?: unknown }).window;
+ (globalThis as { window?: unknown }).window = {};
+
+ try {
+ maybeShowTelemetryNotice();
+ expect(logSpy).not.toHaveBeenCalled();
+ } finally {
+ if (typeof original === 'undefined') {
+ delete (globalThis as { window?: unknown }).window;
+ } else {
+ (globalThis as { window?: unknown }).window = original;
+ }
+ }
+ });
+
+ test('skips in Next.js Edge Runtime', () => {
+ (globalThis as { EdgeRuntime?: string }).EdgeRuntime = 'edge-runtime';
+
+ try {
+ maybeShowTelemetryNotice();
+ expect(logSpy).not.toHaveBeenCalled();
+ } finally {
+ delete (globalThis as { EdgeRuntime?: string }).EdgeRuntime;
+ }
+ });
+
+ test('does not throw if console.log fails', () => {
+ logSpy.mockImplementation(() => {
+ throw new Error('console broken');
+ });
+
+ expect(() => maybeShowTelemetryNotice()).not.toThrow();
+ });
+});

packages/shared/src/telemetry/collector.ts

@@ -20,6 +20,7 @@ import type {
  TelemetryLogEntry,
 } from '../types';
 import { isTruthy } from '../underscore';
+import { maybeShowTelemetryNotice } from './notice';
 import { InMemoryThrottlerCache, LocalStorageThrottlerCache, TelemetryEventThrottler } from './throttler';
 import type { TelemetryCollectorOptions } from './types';
 
@@ -145,6 +146,11 @@ export class TelemetryCollector implements TelemetryCollectorInterface {
  ? new LocalStorageThrottlerCache()
  : new InMemoryThrottlerCache();
  this.#eventThrottler = new TelemetryEventThrottler(cache);
+
+ // Surface the one-time telemetry disclosure at runtime instead of via a postinstall script.
+ // Gated on `isEnabled` so users who opted out (or are not on a development instance) are not
+ // shown a notice for collection that will never happen.
+ maybeShowTelemetryNotice({ skip: !this.isEnabled });
  }
 
  get isEnabled(): boolean {

packages/shared/src/telemetry/notice.ts

@@ -0,0 +1,123 @@
+/**
+ * One-time runtime disclosure that Clerk collects telemetry from development instances.
+ *
+ * Replaces the previous `postinstall` script. Disclosure is intentionally surfaced
+ * only on Node (server-side) so the noise profile matches the original postinstall
+ * (terminal-only, dev-eyes-only). Browser consoles are not used because they are
+ * frequently observed by non-developers (QA, screenshots, demos), and adding another
+ * console warning is a common source of customer complaints.
+ *
+ * Known gap: pure browser-only setups with no server-side Clerk runtime (e.g. a Vite
+ * SPA using `@clerk/clerk-react` or `@clerk/clerk-js` directly, without any Node/Edge
+ * backend that imports `@clerk/shared`) will never hit this code path and therefore
+ * see no in-band disclosure. This is an accepted trade-off: the original postinstall
+ * already fired only once at install time and was easily missed, so the practical
+ * delta is small. Authoritative disclosure for those setups lives in the Clerk
+ * telemetry docs (https://clerk.com/docs/telemetry). Opt-out continues to work the
+ * same way (`telemetry={false}` on `<ClerkProvider>` or the framework-specific
+ * `*_CLERK_TELEMETRY_DISABLED` env var).
+ *
+ * Persistence is in-process via a `globalThis` Symbol, which survives Next.js HMR
+ * module reloads. No filesystem access, no `node:` imports, no dynamic-code APIs, so
+ * the module remains safe to bundle for Edge Runtime, Workers, and any browser path.
+ *
+ * All work is wrapped in try/catch. Failure to display the notice must never affect
+ * the SDK.
+ */
+
+import { isTruthy } from '../underscore';
+import { automatedEnvironmentVariables } from '../utils/runtimeEnvironment';
+
+const PROCESS_FLAG = Symbol.for('@clerk/shared.telemetryNoticeShown');
+
+const NOTICE_LINES = [
+ 'Attention: Clerk collects telemetry data from its SDKs when connected to development instances.',
+ "The data collected is used to inform Clerk's product roadmap.",
+ 'To learn more, including how to opt-out from the telemetry program, visit: https://clerk.com/docs/telemetry.',
+];
+
+function isServerRuntime(): boolean {
+ // Skip in browsers.
+ if (typeof window !== 'undefined') {
+ return false;
+ }
+ // Skip in Next.js Edge Runtime, which exposes a global `EdgeRuntime` marker. We detect via
+ // this marker (rather than checking `process.versions`) because the Edge Runtime build-time
+ // analyzer flags any reachable read of `process.versions` even when it sits behind a guard.
+ if (typeof (globalThis as { EdgeRuntime?: string }).EdgeRuntime !== 'undefined') {
+ return false;
+ }
+ return true;
+}
+
+// Server-only notice: read process.env directly rather than going through
+// getEnvVariable(), which would pull the multi-runtime env resolver into the
+// clerk.browser.js bundle (it ships there via TelemetryCollector). We reuse the
+// shared CI env-var list so the set of detected providers stays in one place.
+function isCI(): boolean {
+ if (typeof process === 'undefined' || !process.env) {
+ return false;
+ }
+ return automatedEnvironmentVariables.some(name => isTruthy(process.env[name]));
+}
+
+function hasSeen(): boolean {
+ return Boolean((globalThis as Record<symbol, unknown>)[PROCESS_FLAG]);
+}
+
+function markSeen(): void {
+ (globalThis as Record<symbol, unknown>)[PROCESS_FLAG] = true;
+}
+
+function printNotice(): void {
+ if (typeof console === 'undefined' || typeof console.log !== 'function') {
+ return;
+ }
+ for (const line of NOTICE_LINES) {
+ console.log(line);
+ }
+ console.log('');
+}
+
+export type MaybeShowTelemetryNoticeOptions = {
+ /**
+ * Skip the notice entirely. Used when the caller has already determined that no
+ * telemetry will be sent (e.g. opt-out, non-development instance), in which case
+ * there is nothing to disclose.
+ */
+ skip?: boolean;
+};
+
+/**
+ * Display the one-time telemetry disclosure on server runtimes if it has not already been
+ * shown in this process. Browser and Edge Runtime callers are silently skipped. Never throws.
+ */
+export function maybeShowTelemetryNotice(options: MaybeShowTelemetryNoticeOptions = {}): void {
+ if (options.skip) {
+ return;
+ }
+ try {
+ if (!isServerRuntime()) {
+ return;
+ }
+ if (isCI()) {
+ return;
+ }
+ if (hasSeen()) {
+ return;
+ }
+ printNotice();
+ markSeen();
+ } catch {
+ // never let disclosure break the SDK
+ }
+}
+
+/**
+ * Test-only: clear the in-process flag so the next call re-runs the gating logic.
+ *
+ * @internal
+ */
+export function __resetTelemetryNoticeForTests(): void {
+ delete (globalThis as Record<symbol, unknown>)[PROCESS_FLAG];
+}

.changeset/sdk-84-remove-telemetry-postinstall.md

@@ -0,0 +1,9 @@
+---
+'@clerk/shared': patch
+---
+
+Replace the telemetry `postinstall` script with a one-time runtime notice, printed once per process on server runtimes (Node, excluding CI) when the telemetry collector boots against a development instance. Drops the `std-env` dependency.
+
+Removing `postinstall` improves the package's supply-chain posture: `@clerk/shared` no longer executes arbitrary code at install time, aligning with package-manager defaults that increasingly disable install scripts.
+
+Browser-only applications with no server-side Clerk runtime (e.g. a Vite SPA) will not surface an in-band notice. Telemetry behavior and opt-out (`telemetry={false}` or `*_CLERK_TELEMETRY_DISABLED`) are unchanged; disclosure for these setups is provided at https://clerk.com/docs/telemetry.

packages/shared/package.json

@@ -121,8 +121,7 @@
  }
  },
  "files": [
- "dist",
- "scripts"
+ "dist"
  ],
  "scripts": {
  "build": "tsdown",
@@ -131,7 +130,6 @@
  "dev:pub": "pnpm dev -- --env.publish",
  "format": "node ../../scripts/format-package.mjs",
  "format:check": "node ../../scripts/format-package.mjs --check",
- "postinstall": "node ./scripts/postinstall.mjs",
  "lint": "eslint src",
  "lint:attw": "attw --pack . --profile node16",
  "lint:publint": "publint",
@@ -143,8 +141,7 @@
  "@tanstack/query-core": "catalog:repo",
  "dequal": "2.0.3",
  "glob-to-regexp": "0.4.1",
- "js-cookie": "3.0.7",
- "std-env": "^3.9.0"
+ "js-cookie": "3.0.7"
  },
  "devDependencies": {
  "@base-org/account": "catalog:module-manager",

packages/shared/src/__tests__/telemetry.notice.spec.ts

@@ -0,0 +1,114 @@
+/**
+ * @vitest-environment node
+ */
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+
+import { __resetTelemetryNoticeForTests, maybeShowTelemetryNotice } from '../telemetry/notice';
+import { automatedEnvironmentVariables } from '../utils/runtimeEnvironment';
+
+const CI_VARS = automatedEnvironmentVariables;
+
+function clearCIEnv() {
+ for (const name of CI_VARS) {
+ delete process.env[name];
+ }
+}
+
+describe('maybeShowTelemetryNotice', () => {
+ let logSpy: ReturnType<typeof vi.spyOn>;
+ let originalCIEnv: Record<string, string | undefined>;
+
+ beforeEach(() => {
+ originalCIEnv = Object.fromEntries(CI_VARS.map(name => [name, process.env[name]]));
+ clearCIEnv();
+ __resetTelemetryNoticeForTests();
+ logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+ });
+
+ afterEach(() => {
+ logSpy.mockRestore();
+ for (const [name, value] of Object.entries(originalCIEnv)) {
+ if (typeof value === 'string') {
+ process.env[name] = value;
+ } else {
+ delete process.env[name];
+ }
+ }
+ });
+
+ test('prints the disclosure on Node', () => {
+ maybeShowTelemetryNotice();
+
+ expect(logSpy).toHaveBeenCalled();
+ const printed = logSpy.mock.calls.map(call => String(call[0])).join('\n');
+ expect(printed).toMatch(/Clerk collects telemetry/);
+ expect(printed).toMatch(/clerk\.com\/docs\/telemetry/);
+ });
+
+ test('does not print again on subsequent calls in the same process', () => {
+ maybeShowTelemetryNotice();
+ maybeShowTelemetryNotice();
+ maybeShowTelemetryNotice();
+
+ const disclosureCalls = logSpy.mock.calls.filter(call => /Clerk collects telemetry/.test(String(call[0])));
+ expect(disclosureCalls).toHaveLength(1);
+ });
+
+ test('skips entirely when skip:true is passed', () => {
+ maybeShowTelemetryNotice({ skip: true });
+
+ expect(logSpy).not.toHaveBeenCalled();
+ });
+
+ test('skips when a CI env var is set', () => {
+ // eslint-disable-next-line turbo/no-undeclared-env-vars
+ process.env.CI = 'true';
+
+ maybeShowTelemetryNotice();
+
+ expect(logSpy).not.toHaveBeenCalled();
+ });
+
+ test.each(CI_VARS)('skips when %s is set', name => {
+ process.env[name] = '1';
+
+ maybeShowTelemetryNotice();
+
+ expect(logSpy).not.toHaveBeenCalled();
+ });
+
+ test('skips in a browser-like environment', () => {
+ const original = (globalThis as { window?: unknown }).window;
+ (globalThis as { window?: unknown }).window = {};
+
+ try {
+ maybeShowTelemetryNotice();
+ expect(logSpy).not.toHaveBeenCalled();
+ } finally {
+ if (typeof original === 'undefined') {
+ delete (globalThis as { window?: unknown }).window;
+ } else {
+ (globalThis as { window?: unknown }).window = original;
+ }
+ }
+ });
+
+ test('skips in Next.js Edge Runtime', () => {
+ (globalThis as { EdgeRuntime?: string }).EdgeRuntime = 'edge-runtime';
+
+ try {
+ maybeShowTelemetryNotice();
+ expect(logSpy).not.toHaveBeenCalled();
+ } finally {
+ delete (globalThis as { EdgeRuntime?: string }).EdgeRuntime;
+ }
+ });
+
+ test('does not throw if console.log fails', () => {
+ logSpy.mockImplementation(() => {
+ throw new Error('console broken');
+ });
+
+ expect(() => maybeShowTelemetryNotice()).not.toThrow();
+ });
+});

packages/shared/src/telemetry/collector.ts

@@ -20,6 +20,7 @@ import type {
  TelemetryLogEntry,
 } from '../types';
 import { isTruthy } from '../underscore';
+import { maybeShowTelemetryNotice } from './notice';
 import { InMemoryThrottlerCache, LocalStorageThrottlerCache, TelemetryEventThrottler } from './throttler';
 import type { TelemetryCollectorOptions } from './types';
 
@@ -145,6 +146,11 @@ export class TelemetryCollector implements TelemetryCollectorInterface {
  ? new LocalStorageThrottlerCache()
  : new InMemoryThrottlerCache();
  this.#eventThrottler = new TelemetryEventThrottler(cache);
+
+ // Surface the one-time telemetry disclosure at runtime instead of via a postinstall script.
+ // Gated on `isEnabled` so users who opted out (or are not on a development instance) are not
+ // shown a notice for collection that will never happen.
+ maybeShowTelemetryNotice({ skip: !this.isEnabled });
  }
 
  get isEnabled(): boolean {

packages/shared/src/telemetry/notice.ts

@@ -0,0 +1,123 @@
+/**
+ * One-time runtime disclosure that Clerk collects telemetry from development instances.
+ *
+ * Replaces the previous `postinstall` script. Disclosure is intentionally surfaced
+ * only on Node (server-side) so the noise profile matches the original postinstall
+ * (terminal-only, dev-eyes-only). Browser consoles are not used because they are
+ * frequently observed by non-developers (QA, screenshots, demos), and adding another
+ * console warning is a common source of customer complaints.
+ *
+ * Known gap: pure browser-only setups with no server-side Clerk runtime (e.g. a Vite
+ * SPA using `@clerk/clerk-react` or `@clerk/clerk-js` directly, without any Node/Edge
+ * backend that imports `@clerk/shared`) will never hit this code path and therefore
+ * see no in-band disclosure. This is an accepted trade-off: the original postinstall
+ * already fired only once at install time and was easily missed, so the practical
+ * delta is small. Authoritative disclosure for those setups lives in the Clerk
+ * telemetry docs (https://clerk.com/docs/telemetry). Opt-out continues to work the
+ * same way (`telemetry={false}` on `<ClerkProvider>` or the framework-specific
+ * `*_CLERK_TELEMETRY_DISABLED` env var).
+ *
+ * Persistence is in-process via a `globalThis` Symbol, which survives Next.js HMR
+ * module reloads. No filesystem access, no `node:` imports, no dynamic-code APIs, so
+ * the module remains safe to bundle for Edge Runtime, Workers, and any browser path.
+ *
+ * All work is wrapped in try/catch. Failure to display the notice must never affect
+ * the SDK.
+ */
+
+import { isTruthy } from '../underscore';
+import { automatedEnvironmentVariables } from '../utils/runtimeEnvironment';
+
+const PROCESS_FLAG = Symbol.for('@clerk/shared.telemetryNoticeShown');
+
+const NOTICE_LINES = [
+ 'Attention: Clerk collects telemetry data from its SDKs when connected to development instances.',
+ "The data collected is used to inform Clerk's product roadmap.",
+ 'To learn more, including how to opt-out from the telemetry program, visit: https://clerk.com/docs/telemetry.',
+];
+
+function isServerRuntime(): boolean {
+ // Skip in browsers.
+ if (typeof window !== 'undefined') {
+ return false;
+ }
+ // Skip in Next.js Edge Runtime, which exposes a global `EdgeRuntime` marker. We detect via
+ // this marker (rather than checking `process.versions`) because the Edge Runtime build-time
+ // analyzer flags any reachable read of `process.versions` even when it sits behind a guard.
+ if (typeof (globalThis as { EdgeRuntime?: string }).EdgeRuntime !== 'undefined') {
+ return false;
+ }
+ return true;
+}
+
+// Server-only notice: read process.env directly rather than going through
+// getEnvVariable(), which would pull the multi-runtime env resolver into the
+// clerk.browser.js bundle (it ships there via TelemetryCollector). We reuse the
+// shared CI env-var list so the set of detected providers stays in one place.
+function isCI(): boolean {
+ if (typeof process === 'undefined' || !process.env) {
+ return false;
+ }
+ return automatedEnvironmentVariables.some(name => isTruthy(process.env[name]));
+}
+
+function hasSeen(): boolean {
+ return Boolean((globalThis as Record<symbol, unknown>)[PROCESS_FLAG]);
+}
+
+function markSeen(): void {
+ (globalThis as Record<symbol, unknown>)[PROCESS_FLAG] = true;
+}
+
+function printNotice(): void {
+ if (typeof console === 'undefined' || typeof console.log !== 'function') {
+ return;
+ }
+ for (const line of NOTICE_LINES) {
+ console.log(line);
+ }
+ console.log('');
+}
+
+export type MaybeShowTelemetryNoticeOptions = {
+ /**
+ * Skip the notice entirely. Used when the caller has already determined that no
+ * telemetry will be sent (e.g. opt-out, non-development instance), in which case
+ * there is nothing to disclose.
+ */
+ skip?: boolean;
+};
+
+/**
+ * Display the one-time telemetry disclosure on server runtimes if it has not already been
+ * shown in this process. Browser and Edge Runtime callers are silently skipped. Never throws.
+ */
+export function maybeShowTelemetryNotice(options: MaybeShowTelemetryNoticeOptions = {}): void {
+ if (options.skip) {
+ return;
+ }
+ try {
+ if (!isServerRuntime()) {
+ return;
+ }
+ if (isCI()) {
+ return;
+ }
+ if (hasSeen()) {
+ return;
+ }
+ printNotice();
+ markSeen();
+ } catch {
+ // never let disclosure break the SDK
+ }
+}
+
+/**
+ * Test-only: clear the in-process flag so the next call re-runs the gating logic.
+ *
+ * @internal
+ */
+export function __resetTelemetryNoticeForTests(): void {
+ delete (globalThis as Record<symbol, unknown>)[PROCESS_FLAG];
+}

.changeset/sdk-84-remove-telemetry-postinstall.md

@@ -0,0 +1,9 @@
+---
+'@clerk/shared': patch
+---
+
+Replace the telemetry `postinstall` script with a one-time runtime notice, printed once per process on server runtimes (Node, excluding CI) when the telemetry collector boots against a development instance. Drops the `std-env` dependency.
+
+Removing `postinstall` improves the package's supply-chain posture: `@clerk/shared` no longer executes arbitrary code at install time, aligning with package-manager defaults that increasingly disable install scripts.
+
+Browser-only applications with no server-side Clerk runtime (e.g. a Vite SPA) will not surface an in-band notice. Telemetry behavior and opt-out (`telemetry={false}` or `*_CLERK_TELEMETRY_DISABLED`) are unchanged; disclosure for these setups is provided at https://clerk.com/docs/telemetry.

packages/shared/package.json

@@ -121,8 +121,7 @@
  }
  },
  "files": [
- "dist",
- "scripts"
+ "dist"
  ],
  "scripts": {
  "build": "tsdown",
@@ -131,7 +130,6 @@
  "dev:pub": "pnpm dev -- --env.publish",
  "format": "node ../../scripts/format-package.mjs",
  "format:check": "node ../../scripts/format-package.mjs --check",
- "postinstall": "node ./scripts/postinstall.mjs",
  "lint": "eslint src",
  "lint:attw": "attw --pack . --profile node16",
  "lint:publint": "publint",
@@ -143,8 +141,7 @@
  "@tanstack/query-core": "catalog:repo",
  "dequal": "2.0.3",
  "glob-to-regexp": "0.4.1",
- "js-cookie": "3.0.7",
- "std-env": "^3.9.0"
+ "js-cookie": "3.0.7"
  },
  "devDependencies": {
  "@base-org/account": "catalog:module-manager",

packages/shared/src/__tests__/telemetry.notice.spec.ts

@@ -0,0 +1,114 @@
+/**
+ * @vitest-environment node
+ */
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+
+import { __resetTelemetryNoticeForTests, maybeShowTelemetryNotice } from '../telemetry/notice';
+import { automatedEnvironmentVariables } from '../utils/runtimeEnvironment';
+
+const CI_VARS = automatedEnvironmentVariables;
+
+function clearCIEnv() {
+ for (const name of CI_VARS) {
+ delete process.env[name];
+ }
+}
+
+describe('maybeShowTelemetryNotice', () => {
+ let logSpy: ReturnType<typeof vi.spyOn>;
+ let originalCIEnv: Record<string, string | undefined>;
+
+ beforeEach(() => {
+ originalCIEnv = Object.fromEntries(CI_VARS.map(name => [name, process.env[name]]));
+ clearCIEnv();
+ __resetTelemetryNoticeForTests();
+ logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+ });
+
+ afterEach(() => {
+ logSpy.mockRestore();
+ for (const [name, value] of Object.entries(originalCIEnv)) {
+ if (typeof value === 'string') {
+ process.env[name] = value;
+ } else {
+ delete process.env[name];
+ }
+ }
+ });
+
+ test('prints the disclosure on Node', () => {
+ maybeShowTelemetryNotice();
+
+ expect(logSpy).toHaveBeenCalled();
+ const printed = logSpy.mock.calls.map(call => String(call[0])).join('\n');
+ expect(printed).toMatch(/Clerk collects telemetry/);
+ expect(printed).toMatch(/clerk\.com\/docs\/telemetry/);
+ });
+
+ test('does not print again on subsequent calls in the same process', () => {
+ maybeShowTelemetryNotice();
+ maybeShowTelemetryNotice();
+ maybeShowTelemetryNotice();
+
+ const disclosureCalls = logSpy.mock.calls.filter(call => /Clerk collects telemetry/.test(String(call[0])));
+ expect(disclosureCalls).toHaveLength(1);
+ });
+
+ test('skips entirely when skip:true is passed', () => {
+ maybeShowTelemetryNotice({ skip: true });
+
+ expect(logSpy).not.toHaveBeenCalled();
+ });
+
+ test('skips when a CI env var is set', () => {
+ // eslint-disable-next-line turbo/no-undeclared-env-vars
+ process.env.CI = 'true';
+
+ maybeShowTelemetryNotice();
+
+ expect(logSpy).not.toHaveBeenCalled();
+ });
+
+ test.each(CI_VARS)('skips when %s is set', name => {
+ process.env[name] = '1';
+
+ maybeShowTelemetryNotice();
+
+ expect(logSpy).not.toHaveBeenCalled();
+ });
+
+ test('skips in a browser-like environment', () => {
+ const original = (globalThis as { window?: unknown }).window;
+ (globalThis as { window?: unknown }).window = {};
+
+ try {
+ maybeShowTelemetryNotice();
+ expect(logSpy).not.toHaveBeenCalled();
+ } finally {
+ if (typeof original === 'undefined') {
+ delete (globalThis as { window?: unknown }).window;
+ } else {
+ (globalThis as { window?: unknown }).window = original;
+ }
+ }
+ });
+
+ test('skips in Next.js Edge Runtime', () => {
+ (globalThis as { EdgeRuntime?: string }).EdgeRuntime = 'edge-runtime';
+
+ try {
+ maybeShowTelemetryNotice();
+ expect(logSpy).not.toHaveBeenCalled();
+ } finally {
+ delete (globalThis as { EdgeRuntime?: string }).EdgeRuntime;
+ }
+ });
+
+ test('does not throw if console.log fails', () => {
+ logSpy.mockImplementation(() => {
+ throw new Error('console broken');
+ });
+
+ expect(() => maybeShowTelemetryNotice()).not.toThrow();
+ });
+});

packages/shared/src/telemetry/collector.ts

@@ -20,6 +20,7 @@ import type {
  TelemetryLogEntry,
 } from '../types';
 import { isTruthy } from '../underscore';
+import { maybeShowTelemetryNotice } from './notice';
 import { InMemoryThrottlerCache, LocalStorageThrottlerCache, TelemetryEventThrottler } from './throttler';
 import type { TelemetryCollectorOptions } from './types';
 
@@ -145,6 +146,11 @@ export class TelemetryCollector implements TelemetryCollectorInterface {
  ? new LocalStorageThrottlerCache()
  : new InMemoryThrottlerCache();
  this.#eventThrottler = new TelemetryEventThrottler(cache);
+
+ // Surface the one-time telemetry disclosure at runtime instead of via a postinstall script.
+ // Gated on `isEnabled` so users who opted out (or are not on a development instance) are not
+ // shown a notice for collection that will never happen.
+ maybeShowTelemetryNotice({ skip: !this.isEnabled });
  }
 
  get isEnabled(): boolean {

packages/shared/src/telemetry/notice.ts

@@ -0,0 +1,123 @@
+/**
+ * One-time runtime disclosure that Clerk collects telemetry from development instances.
+ *
+ * Replaces the previous `postinstall` script. Disclosure is intentionally surfaced
+ * only on Node (server-side) so the noise profile matches the original postinstall
+ * (terminal-only, dev-eyes-only). Browser consoles are not used because they are
+ * frequently observed by non-developers (QA, screenshots, demos), and adding another
+ * console warning is a common source of customer complaints.
+ *
+ * Known gap: pure browser-only setups with no server-side Clerk runtime (e.g. a Vite
+ * SPA using `@clerk/clerk-react` or `@clerk/clerk-js` directly, without any Node/Edge
+ * backend that imports `@clerk/shared`) will never hit this code path and therefore
+ * see no in-band disclosure. This is an accepted trade-off: the original postinstall
+ * already fired only once at install time and was easily missed, so the practical
+ * delta is small. Authoritative disclosure for those setups lives in the Clerk
+ * telemetry docs (https://clerk.com/docs/telemetry). Opt-out continues to work the
+ * same way (`telemetry={false}` on `<ClerkProvider>` or the framework-specific
+ * `*_CLERK_TELEMETRY_DISABLED` env var).
+ *
+ * Persistence is in-process via a `globalThis` Symbol, which survives Next.js HMR
+ * module reloads. No filesystem access, no `node:` imports, no dynamic-code APIs, so
+ * the module remains safe to bundle for Edge Runtime, Workers, and any browser path.
+ *
+ * All work is wrapped in try/catch. Failure to display the notice must never affect
+ * the SDK.
+ */
+
+import { isTruthy } from '../underscore';
+import { automatedEnvironmentVariables } from '../utils/runtimeEnvironment';
+
+const PROCESS_FLAG = Symbol.for('@clerk/shared.telemetryNoticeShown');
+
+const NOTICE_LINES = [
+ 'Attention: Clerk collects telemetry data from its SDKs when connected to development instances.',
+ "The data collected is used to inform Clerk's product roadmap.",
+ 'To learn more, including how to opt-out from the telemetry program, visit: https://clerk.com/docs/telemetry.',
+];
+
+function isServerRuntime(): boolean {
+ // Skip in browsers.
+ if (typeof window !== 'undefined') {
+ return false;
+ }
+ // Skip in Next.js Edge Runtime, which exposes a global `EdgeRuntime` marker. We detect via
+ // this marker (rather than checking `process.versions`) because the Edge Runtime build-time
+ // analyzer flags any reachable read of `process.versions` even when it sits behind a guard.
+ if (typeof (globalThis as { EdgeRuntime?: string }).EdgeRuntime !== 'undefined') {
+ return false;
+ }
+ return true;
+}
+
+// Server-only notice: read process.env directly rather than going through
+// getEnvVariable(), which would pull the multi-runtime env resolver into the
+// clerk.browser.js bundle (it ships there via TelemetryCollector). We reuse the
+// shared CI env-var list so the set of detected providers stays in one place.
+function isCI(): boolean {
+ if (typeof process === 'undefined' || !process.env) {
+ return false;
+ }
+ return automatedEnvironmentVariables.some(name => isTruthy(process.env[name]));
+}
+
+function hasSeen(): boolean {
+ return Boolean((globalThis as Record<symbol, unknown>)[PROCESS_FLAG]);
+}
+
+function markSeen(): void {
+ (globalThis as Record<symbol, unknown>)[PROCESS_FLAG] = true;
+}
+
+function printNotice(): void {
+ if (typeof console === 'undefined' || typeof console.log !== 'function') {
+ return;
+ }
+ for (const line of NOTICE_LINES) {
+ console.log(line);
+ }
+ console.log('');
+}
+
+export type MaybeShowTelemetryNoticeOptions = {
+ /**
+ * Skip the notice entirely. Used when the caller has already determined that no
+ * telemetry will be sent (e.g. opt-out, non-development instance), in which case
+ * there is nothing to disclose.
+ */
+ skip?: boolean;
+};
+
+/**
+ * Display the one-time telemetry disclosure on server runtimes if it has not already been
+ * shown in this process. Browser and Edge Runtime callers are silently skipped. Never throws.
+ */
+export function maybeShowTelemetryNotice(options: MaybeShowTelemetryNoticeOptions = {}): void {
+ if (options.skip) {
+ return;
+ }
+ try {
+ if (!isServerRuntime()) {
+ return;
+ }
+ if (isCI()) {
+ return;
+ }
+ if (hasSeen()) {
+ return;
+ }
+ printNotice();
+ markSeen();
+ } catch {
+ // never let disclosure break the SDK
+ }
+}
+
+/**
+ * Test-only: clear the in-process flag so the next call re-runs the gating logic.
+ *
+ * @internal
+ */
+export function __resetTelemetryNoticeForTests(): void {
+ delete (globalThis as Record<symbol, unknown>)[PROCESS_FLAG];
+}

.changeset/sdk-84-remove-telemetry-postinstall.md

@@ -0,0 +1,9 @@
+---
+'@clerk/shared': patch
+---
+
+Replace the telemetry `postinstall` script with a one-time runtime notice, printed once per process on server runtimes (Node, excluding CI) when the telemetry collector boots against a development instance. Drops the `std-env` dependency.
+
+Removing `postinstall` improves the package's supply-chain posture: `@clerk/shared` no longer executes arbitrary code at install time, aligning with package-manager defaults that increasingly disable install scripts.
+
+Browser-only applications with no server-side Clerk runtime (e.g. a Vite SPA) will not surface an in-band notice. Telemetry behavior and opt-out (`telemetry={false}` or `*_CLERK_TELEMETRY_DISABLED`) are unchanged; disclosure for these setups is provided at https://clerk.com/docs/telemetry.

packages/shared/package.json

@@ -121,8 +121,7 @@
  }
  },
  "files": [
- "dist",
- "scripts"
+ "dist"
  ],
  "scripts": {
  "build": "tsdown",
@@ -131,7 +130,6 @@
  "dev:pub": "pnpm dev -- --env.publish",
  "format": "node ../../scripts/format-package.mjs",
  "format:check": "node ../../scripts/format-package.mjs --check",
- "postinstall": "node ./scripts/postinstall.mjs",
  "lint": "eslint src",
  "lint:attw": "attw --pack . --profile node16",
  "lint:publint": "publint",
@@ -143,8 +141,7 @@
  "@tanstack/query-core": "catalog:repo",
  "dequal": "2.0.3",
  "glob-to-regexp": "0.4.1",
- "js-cookie": "3.0.7",
- "std-env": "^3.9.0"
+ "js-cookie": "3.0.7"
  },
  "devDependencies": {
  "@base-org/account": "catalog:module-manager",

packages/shared/src/__tests__/telemetry.notice.spec.ts

@@ -0,0 +1,114 @@
+/**
+ * @vitest-environment node
+ */
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+
+import { __resetTelemetryNoticeForTests, maybeShowTelemetryNotice } from '../telemetry/notice';
+import { automatedEnvironmentVariables } from '../utils/runtimeEnvironment';
+
+const CI_VARS = automatedEnvironmentVariables;
+
+function clearCIEnv() {
+ for (const name of CI_VARS) {
+ delete process.env[name];
+ }
+}
+
+describe('maybeShowTelemetryNotice', () => {
+ let logSpy: ReturnType<typeof vi.spyOn>;
+ let originalCIEnv: Record<string, string | undefined>;
+
+ beforeEach(() => {
+ originalCIEnv = Object.fromEntries(CI_VARS.map(name => [name, process.env[name]]));
+ clearCIEnv();
+ __resetTelemetryNoticeForTests();
+ logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+ });
+
+ afterEach(() => {
+ logSpy.mockRestore();
+ for (const [name, value] of Object.entries(originalCIEnv)) {
+ if (typeof value === 'string') {
+ process.env[name] = value;
+ } else {
+ delete process.env[name];
+ }
+ }
+ });
+
+ test('prints the disclosure on Node', () => {
+ maybeShowTelemetryNotice();
+
+ expect(logSpy).toHaveBeenCalled();
+ const printed = logSpy.mock.calls.map(call => String(call[0])).join('\n');
+ expect(printed).toMatch(/Clerk collects telemetry/);
+ expect(printed).toMatch(/clerk\.com\/docs\/telemetry/);
+ });
+
+ test('does not print again on subsequent calls in the same process', () => {
+ maybeShowTelemetryNotice();
+ maybeShowTelemetryNotice();
+ maybeShowTelemetryNotice();
+
+ const disclosureCalls = logSpy.mock.calls.filter(call => /Clerk collects telemetry/.test(String(call[0])));
+ expect(disclosureCalls).toHaveLength(1);
+ });
+
+ test('skips entirely when skip:true is passed', () => {
+ maybeShowTelemetryNotice({ skip: true });
+
+ expect(logSpy).not.toHaveBeenCalled();
+ });
+
+ test('skips when a CI env var is set', () => {
+ // eslint-disable-next-line turbo/no-undeclared-env-vars
+ process.env.CI = 'true';
+
+ maybeShowTelemetryNotice();
+
+ expect(logSpy).not.toHaveBeenCalled();
+ });
+
+ test.each(CI_VARS)('skips when %s is set', name => {
+ process.env[name] = '1';
+
+ maybeShowTelemetryNotice();
+
+ expect(logSpy).not.toHaveBeenCalled();
+ });
+
+ test('skips in a browser-like environment', () => {
+ const original = (globalThis as { window?: unknown }).window;
+ (globalThis as { window?: unknown }).window = {};
+
+ try {
+ maybeShowTelemetryNotice();
+ expect(logSpy).not.toHaveBeenCalled();
+ } finally {
+ if (typeof original === 'undefined') {
+ delete (globalThis as { window?: unknown }).window;
+ } else {
+ (globalThis as { window?: unknown }).window = original;
+ }
+ }
+ });
+
+ test('skips in Next.js Edge Runtime', () => {
+ (globalThis as { EdgeRuntime?: string }).EdgeRuntime = 'edge-runtime';
+
+ try {
+ maybeShowTelemetryNotice();
+ expect(logSpy).not.toHaveBeenCalled();
+ } finally {
+ delete (globalThis as { EdgeRuntime?: string }).EdgeRuntime;
+ }
+ });
+
+ test('does not throw if console.log fails', () => {
+ logSpy.mockImplementation(() => {
+ throw new Error('console broken');
+ });
+
+ expect(() => maybeShowTelemetryNotice()).not.toThrow();
+ });
+});

packages/shared/src/telemetry/collector.ts

@@ -20,6 +20,7 @@ import type {
  TelemetryLogEntry,
 } from '../types';
 import { isTruthy } from '../underscore';
+import { maybeShowTelemetryNotice } from './notice';
 import { InMemoryThrottlerCache, LocalStorageThrottlerCache, TelemetryEventThrottler } from './throttler';
 import type { TelemetryCollectorOptions } from './types';
 
@@ -145,6 +146,11 @@ export class TelemetryCollector implements TelemetryCollectorInterface {
  ? new LocalStorageThrottlerCache()
  : new InMemoryThrottlerCache();
  this.#eventThrottler = new TelemetryEventThrottler(cache);
+
+ // Surface the one-time telemetry disclosure at runtime instead of via a postinstall script.
+ // Gated on `isEnabled` so users who opted out (or are not on a development instance) are not
+ // shown a notice for collection that will never happen.
+ maybeShowTelemetryNotice({ skip: !this.isEnabled });
  }
 
  get isEnabled(): boolean {

packages/shared/src/telemetry/notice.ts

@@ -0,0 +1,123 @@
+/**
+ * One-time runtime disclosure that Clerk collects telemetry from development instances.
+ *
+ * Replaces the previous `postinstall` script. Disclosure is intentionally surfaced
+ * only on Node (server-side) so the noise profile matches the original postinstall
+ * (terminal-only, dev-eyes-only). Browser consoles are not used because they are
+ * frequently observed by non-developers (QA, screenshots, demos), and adding another
+ * console warning is a common source of customer complaints.
+ *
+ * Known gap: pure browser-only setups with no server-side Clerk runtime (e.g. a Vite
+ * SPA using `@clerk/clerk-react` or `@clerk/clerk-js` directly, without any Node/Edge
+ * backend that imports `@clerk/shared`) will never hit this code path and therefore
+ * see no in-band disclosure. This is an accepted trade-off: the original postinstall
+ * already fired only once at install time and was easily missed, so the practical
+ * delta is small. Authoritative disclosure for those setups lives in the Clerk
+ * telemetry docs (https://clerk.com/docs/telemetry). Opt-out continues to work the
+ * same way (`telemetry={false}` on `<ClerkProvider>` or the framework-specific
+ * `*_CLERK_TELEMETRY_DISABLED` env var).
+ *
+ * Persistence is in-process via a `globalThis` Symbol, which survives Next.js HMR
+ * module reloads. No filesystem access, no `node:` imports, no dynamic-code APIs, so
+ * the module remains safe to bundle for Edge Runtime, Workers, and any browser path.
+ *
+ * All work is wrapped in try/catch. Failure to display the notice must never affect
+ * the SDK.
+ */
+
+import { isTruthy } from '../underscore';
+import { automatedEnvironmentVariables } from '../utils/runtimeEnvironment';
+
+const PROCESS_FLAG = Symbol.for('@clerk/shared.telemetryNoticeShown');
+
+const NOTICE_LINES = [
+ 'Attention: Clerk collects telemetry data from its SDKs when connected to development instances.',
+ "The data collected is used to inform Clerk's product roadmap.",
+ 'To learn more, including how to opt-out from the telemetry program, visit: https://clerk.com/docs/telemetry.',
+];
+
+function isServerRuntime(): boolean {
+ // Skip in browsers.
+ if (typeof window !== 'undefined') {
+ return false;
+ }
+ // Skip in Next.js Edge Runtime, which exposes a global `EdgeRuntime` marker. We detect via
+ // this marker (rather than checking `process.versions`) because the Edge Runtime build-time
+ // analyzer flags any reachable read of `process.versions` even when it sits behind a guard.
+ if (typeof (globalThis as { EdgeRuntime?: string }).EdgeRuntime !== 'undefined') {
+ return false;
+ }
+ return true;
+}
+
+// Server-only notice: read process.env directly rather than going through
+// getEnvVariable(), which would pull the multi-runtime env resolver into the
+// clerk.browser.js bundle (it ships there via TelemetryCollector). We reuse the
+// shared CI env-var list so the set of detected providers stays in one place.
+function isCI(): boolean {
+ if (typeof process === 'undefined' || !process.env) {
+ return false;
+ }
+ return automatedEnvironmentVariables.some(name => isTruthy(process.env[name]));
+}
+
+function hasSeen(): boolean {
+ return Boolean((globalThis as Record<symbol, unknown>)[PROCESS_FLAG]);
+}
+
+function markSeen(): void {
+ (globalThis as Record<symbol, unknown>)[PROCESS_FLAG] = true;
+}
+
+function printNotice(): void {
+ if (typeof console === 'undefined' || typeof console.log !== 'function') {
+ return;
+ }
+ for (const line of NOTICE_LINES) {
+ console.log(line);
+ }
+ console.log('');
+}
+
+export type MaybeShowTelemetryNoticeOptions = {
+ /**
+ * Skip the notice entirely. Used when the caller has already determined that no
+ * telemetry will be sent (e.g. opt-out, non-development instance), in which case
+ * there is nothing to disclose.
+ */
+ skip?: boolean;
+};
+
+/**
+ * Display the one-time telemetry disclosure on server runtimes if it has not already been
+ * shown in this process. Browser and Edge Runtime callers are silently skipped. Never throws.
+ */
+export function maybeShowTelemetryNotice(options: MaybeShowTelemetryNoticeOptions = {}): void {
+ if (options.skip) {
+ return;
+ }
+ try {
+ if (!isServerRuntime()) {
+ return;
+ }
+ if (isCI()) {
+ return;
+ }
+ if (hasSeen()) {
+ return;
+ }
+ printNotice();
+ markSeen();
+ } catch {
+ // never let disclosure break the SDK
+ }
+}
+
+/**
+ * Test-only: clear the in-process flag so the next call re-runs the gating logic.
+ *
+ * @internal
+ */
+export function __resetTelemetryNoticeForTests(): void {
+ delete (globalThis as Record<symbol, unknown>)[PROCESS_FLAG];
+}

.changeset/sdk-84-remove-telemetry-postinstall.md

@@ -0,0 +1,9 @@
+---
+'@clerk/shared': patch
+---
+
+Replace the telemetry `postinstall` script with a one-time runtime notice, printed once per process on server runtimes (Node, excluding CI) when the telemetry collector boots against a development instance. Drops the `std-env` dependency.
+
+Removing `postinstall` improves the package's supply-chain posture: `@clerk/shared` no longer executes arbitrary code at install time, aligning with package-manager defaults that increasingly disable install scripts.
+
+Browser-only applications with no server-side Clerk runtime (e.g. a Vite SPA) will not surface an in-band notice. Telemetry behavior and opt-out (`telemetry={false}` or `*_CLERK_TELEMETRY_DISABLED`) are unchanged; disclosure for these setups is provided at https://clerk.com/docs/telemetry.

packages/shared/package.json

@@ -121,8 +121,7 @@
  }
  },
  "files": [
- "dist",
- "scripts"
+ "dist"
  ],
  "scripts": {
  "build": "tsdown",
@@ -131,7 +130,6 @@
  "dev:pub": "pnpm dev -- --env.publish",
  "format": "node ../../scripts/format-package.mjs",
  "format:check": "node ../../scripts/format-package.mjs --check",
- "postinstall": "node ./scripts/postinstall.mjs",
  "lint": "eslint src",
  "lint:attw": "attw --pack . --profile node16",
  "lint:publint": "publint",
@@ -143,8 +141,7 @@
  "@tanstack/query-core": "catalog:repo",
  "dequal": "2.0.3",
  "glob-to-regexp": "0.4.1",
- "js-cookie": "3.0.7",
- "std-env": "^3.9.0"
+ "js-cookie": "3.0.7"
  },
  "devDependencies": {
  "@base-org/account": "catalog:module-manager",

packages/shared/src/__tests__/telemetry.notice.spec.ts

@@ -0,0 +1,114 @@
+/**
+ * @vitest-environment node
+ */
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+
+import { __resetTelemetryNoticeForTests, maybeShowTelemetryNotice } from '../telemetry/notice';
+import { automatedEnvironmentVariables } from '../utils/runtimeEnvironment';
+
+const CI_VARS = automatedEnvironmentVariables;
+
+function clearCIEnv() {
+ for (const name of CI_VARS) {
+ delete process.env[name];
+ }
+}
+
+describe('maybeShowTelemetryNotice', () => {
+ let logSpy: ReturnType<typeof vi.spyOn>;
+ let originalCIEnv: Record<string, string | undefined>;
+
+ beforeEach(() => {
+ originalCIEnv = Object.fromEntries(CI_VARS.map(name => [name, process.env[name]]));
+ clearCIEnv();
+ __resetTelemetryNoticeForTests();
+ logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+ });
+
+ afterEach(() => {
+ logSpy.mockRestore();
+ for (const [name, value] of Object.entries(originalCIEnv)) {
+ if (typeof value === 'string') {
+ process.env[name] = value;
+ } else {
+ delete process.env[name];
+ }
+ }
+ });
+
+ test('prints the disclosure on Node', () => {
+ maybeShowTelemetryNotice();
+
+ expect(logSpy).toHaveBeenCalled();
+ const printed = logSpy.mock.calls.map(call => String(call[0])).join('\n');
+ expect(printed).toMatch(/Clerk collects telemetry/);
+ expect(printed).toMatch(/clerk\.com\/docs\/telemetry/);
+ });
+
+ test('does not print again on subsequent calls in the same process', () => {
+ maybeShowTelemetryNotice();
+ maybeShowTelemetryNotice();
+ maybeShowTelemetryNotice();
+
+ const disclosureCalls = logSpy.mock.calls.filter(call => /Clerk collects telemetry/.test(String(call[0])));
+ expect(disclosureCalls).toHaveLength(1);
+ });
+
+ test('skips entirely when skip:true is passed', () => {
+ maybeShowTelemetryNotice({ skip: true });
+
+ expect(logSpy).not.toHaveBeenCalled();
+ });
+
+ test('skips when a CI env var is set', () => {
+ // eslint-disable-next-line turbo/no-undeclared-env-vars
+ process.env.CI = 'true';
+
+ maybeShowTelemetryNotice();
+
+ expect(logSpy).not.toHaveBeenCalled();
+ });
+
+ test.each(CI_VARS)('skips when %s is set', name => {
+ process.env[name] = '1';
+
+ maybeShowTelemetryNotice();
+
+ expect(logSpy).not.toHaveBeenCalled();
+ });
+
+ test('skips in a browser-like environment', () => {
+ const original = (globalThis as { window?: unknown }).window;
+ (globalThis as { window?: unknown }).window = {};
+
+ try {
+ maybeShowTelemetryNotice();
+ expect(logSpy).not.toHaveBeenCalled();
+ } finally {
+ if (typeof original === 'undefined') {
+ delete (globalThis as { window?: unknown }).window;
+ } else {
+ (globalThis as { window?: unknown }).window = original;
+ }
+ }
+ });
+
+ test('skips in Next.js Edge Runtime', () => {
+ (globalThis as { EdgeRuntime?: string }).EdgeRuntime = 'edge-runtime';
+
+ try {
+ maybeShowTelemetryNotice();
+ expect(logSpy).not.toHaveBeenCalled();
+ } finally {
+ delete (globalThis as { EdgeRuntime?: string }).EdgeRuntime;
+ }
+ });
+
+ test('does not throw if console.log fails', () => {
+ logSpy.mockImplementation(() => {
+ throw new Error('console broken');
+ });
+
+ expect(() => maybeShowTelemetryNotice()).not.toThrow();
+ });
+});

packages/shared/src/telemetry/collector.ts

@@ -20,6 +20,7 @@ import type {
  TelemetryLogEntry,
 } from '../types';
 import { isTruthy } from '../underscore';
+import { maybeShowTelemetryNotice } from './notice';
 import { InMemoryThrottlerCache, LocalStorageThrottlerCache, TelemetryEventThrottler } from './throttler';
 import type { TelemetryCollectorOptions } from './types';
 
@@ -145,6 +146,11 @@ export class TelemetryCollector implements TelemetryCollectorInterface {
  ? new LocalStorageThrottlerCache()
  : new InMemoryThrottlerCache();
  this.#eventThrottler = new TelemetryEventThrottler(cache);
+
+ // Surface the one-time telemetry disclosure at runtime instead of via a postinstall script.
+ // Gated on `isEnabled` so users who opted out (or are not on a development instance) are not
+ // shown a notice for collection that will never happen.
+ maybeShowTelemetryNotice({ skip: !this.isEnabled });
  }
 
  get isEnabled(): boolean {

packages/shared/src/telemetry/notice.ts

@@ -0,0 +1,123 @@
+/**
+ * One-time runtime disclosure that Clerk collects telemetry from development instances.
+ *
+ * Replaces the previous `postinstall` script. Disclosure is intentionally surfaced
+ * only on Node (server-side) so the noise profile matches the original postinstall
+ * (terminal-only, dev-eyes-only). Browser consoles are not used because they are
+ * frequently observed by non-developers (QA, screenshots, demos), and adding another
+ * console warning is a common source of customer complaints.
+ *
+ * Known gap: pure browser-only setups with no server-side Clerk runtime (e.g. a Vite
+ * SPA using `@clerk/clerk-react` or `@clerk/clerk-js` directly, without any Node/Edge
+ * backend that imports `@clerk/shared`) will never hit this code path and therefore
+ * see no in-band disclosure. This is an accepted trade-off: the original postinstall
+ * already fired only once at install time and was easily missed, so the practical
+ * delta is small. Authoritative disclosure for those setups lives in the Clerk
+ * telemetry docs (https://clerk.com/docs/telemetry). Opt-out continues to work the
+ * same way (`telemetry={false}` on `<ClerkProvider>` or the framework-specific
+ * `*_CLERK_TELEMETRY_DISABLED` env var).
+ *
+ * Persistence is in-process via a `globalThis` Symbol, which survives Next.js HMR
+ * module reloads. No filesystem access, no `node:` imports, no dynamic-code APIs, so
+ * the module remains safe to bundle for Edge Runtime, Workers, and any browser path.
+ *
+ * All work is wrapped in try/catch. Failure to display the notice must never affect
+ * the SDK.
+ */
+
+import { isTruthy } from '../underscore';
+import { automatedEnvironmentVariables } from '../utils/runtimeEnvironment';
+
+const PROCESS_FLAG = Symbol.for('@clerk/shared.telemetryNoticeShown');
+
+const NOTICE_LINES = [
+ 'Attention: Clerk collects telemetry data from its SDKs when connected to development instances.',
+ "The data collected is used to inform Clerk's product roadmap.",
+ 'To learn more, including how to opt-out from the telemetry program, visit: https://clerk.com/docs/telemetry.',
+];
+
+function isServerRuntime(): boolean {
+ // Skip in browsers.
+ if (typeof window !== 'undefined') {
+ return false;
+ }
+ // Skip in Next.js Edge Runtime, which exposes a global `EdgeRuntime` marker. We detect via
+ // this marker (rather than checking `process.versions`) because the Edge Runtime build-time
+ // analyzer flags any reachable read of `process.versions` even when it sits behind a guard.
+ if (typeof (globalThis as { EdgeRuntime?: string }).EdgeRuntime !== 'undefined') {
+ return false;
+ }
+ return true;
+}
+
+// Server-only notice: read process.env directly rather than going through
+// getEnvVariable(), which would pull the multi-runtime env resolver into the
+// clerk.browser.js bundle (it ships there via TelemetryCollector). We reuse the
+// shared CI env-var list so the set of detected providers stays in one place.
+function isCI(): boolean {
+ if (typeof process === 'undefined' || !process.env) {
+ return false;
+ }
+ return automatedEnvironmentVariables.some(name => isTruthy(process.env[name]));
+}
+
+function hasSeen(): boolean {
+ return Boolean((globalThis as Record<symbol, unknown>)[PROCESS_FLAG]);
+}
+
+function markSeen(): void {
+ (globalThis as Record<symbol, unknown>)[PROCESS_FLAG] = true;
+}
+
+function printNotice(): void {
+ if (typeof console === 'undefined' || typeof console.log !== 'function') {
+ return;
+ }
+ for (const line of NOTICE_LINES) {
+ console.log(line);
+ }
+ console.log('');
+}
+
+export type MaybeShowTelemetryNoticeOptions = {
+ /**
+ * Skip the notice entirely. Used when the caller has already determined that no
+ * telemetry will be sent (e.g. opt-out, non-development instance), in which case
+ * there is nothing to disclose.
+ */
+ skip?: boolean;
+};
+
+/**
+ * Display the one-time telemetry disclosure on server runtimes if it has not already been
+ * shown in this process. Browser and Edge Runtime callers are silently skipped. Never throws.
+ */
+export function maybeShowTelemetryNotice(options: MaybeShowTelemetryNoticeOptions = {}): void {
+ if (options.skip) {
+ return;
+ }
+ try {
+ if (!isServerRuntime()) {
+ return;
+ }
+ if (isCI()) {
+ return;
+ }
+ if (hasSeen()) {
+ return;
+ }
+ printNotice();
+ markSeen();
+ } catch {
+ // never let disclosure break the SDK
+ }
+}
+
+/**
+ * Test-only: clear the in-process flag so the next call re-runs the gating logic.
+ *
+ * @internal
+ */
+export function __resetTelemetryNoticeForTests(): void {
+ delete (globalThis as Record<symbol, unknown>)[PROCESS_FLAG];
+}

.changeset/sdk-84-remove-telemetry-postinstall.md

@@ -0,0 +1,9 @@
+---
+'@clerk/shared': patch
+---
+
+Replace the telemetry `postinstall` script with a one-time runtime notice, printed once per process on server runtimes (Node, excluding CI) when the telemetry collector boots against a development instance. Drops the `std-env` dependency.
+
+Removing `postinstall` improves the package's supply-chain posture: `@clerk/shared` no longer executes arbitrary code at install time, aligning with package-manager defaults that increasingly disable install scripts.
+
+Browser-only applications with no server-side Clerk runtime (e.g. a Vite SPA) will not surface an in-band notice. Telemetry behavior and opt-out (`telemetry={false}` or `*_CLERK_TELEMETRY_DISABLED`) are unchanged; disclosure for these setups is provided at https://clerk.com/docs/telemetry.

packages/shared/package.json

@@ -121,8 +121,7 @@
  }
  },
  "files": [
- "dist",
- "scripts"
+ "dist"
  ],
  "scripts": {
  "build": "tsdown",
@@ -131,7 +130,6 @@
  "dev:pub": "pnpm dev -- --env.publish",
  "format": "node ../../scripts/format-package.mjs",
  "format:check": "node ../../scripts/format-package.mjs --check",
- "postinstall": "node ./scripts/postinstall.mjs",
  "lint": "eslint src",
  "lint:attw": "attw --pack . --profile node16",
  "lint:publint": "publint",
@@ -143,8 +141,7 @@
  "@tanstack/query-core": "catalog:repo",
  "dequal": "2.0.3",
  "glob-to-regexp": "0.4.1",
- "js-cookie": "3.0.7",
- "std-env": "^3.9.0"
+ "js-cookie": "3.0.7"
  },
  "devDependencies": {
  "@base-org/account": "catalog:module-manager",

packages/shared/src/__tests__/telemetry.notice.spec.ts

@@ -0,0 +1,114 @@
+/**
+ * @vitest-environment node
+ */
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+
+import { __resetTelemetryNoticeForTests, maybeShowTelemetryNotice } from '../telemetry/notice';
+import { automatedEnvironmentVariables } from '../utils/runtimeEnvironment';
+
+const CI_VARS = automatedEnvironmentVariables;
+
+function clearCIEnv() {
+ for (const name of CI_VARS) {
+ delete process.env[name];
+ }
+}
+
+describe('maybeShowTelemetryNotice', () => {
+ let logSpy: ReturnType<typeof vi.spyOn>;
+ let originalCIEnv: Record<string, string | undefined>;
+
+ beforeEach(() => {
+ originalCIEnv = Object.fromEntries(CI_VARS.map(name => [name, process.env[name]]));
+ clearCIEnv();
+ __resetTelemetryNoticeForTests();
+ logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+ });
+
+ afterEach(() => {
+ logSpy.mockRestore();
+ for (const [name, value] of Object.entries(originalCIEnv)) {
+ if (typeof value === 'string') {
+ process.env[name] = value;
+ } else {
+ delete process.env[name];
+ }
+ }
+ });
+
+ test('prints the disclosure on Node', () => {
+ maybeShowTelemetryNotice();
+
+ expect(logSpy).toHaveBeenCalled();
+ const printed = logSpy.mock.calls.map(call => String(call[0])).join('\n');
+ expect(printed).toMatch(/Clerk collects telemetry/);
+ expect(printed).toMatch(/clerk\.com\/docs\/telemetry/);
+ });
+
+ test('does not print again on subsequent calls in the same process', () => {
+ maybeShowTelemetryNotice();
+ maybeShowTelemetryNotice();
+ maybeShowTelemetryNotice();
+
+ const disclosureCalls = logSpy.mock.calls.filter(call => /Clerk collects telemetry/.test(String(call[0])));
+ expect(disclosureCalls).toHaveLength(1);
+ });
+
+ test('skips entirely when skip:true is passed', () => {
+ maybeShowTelemetryNotice({ skip: true });
+
+ expect(logSpy).not.toHaveBeenCalled();
+ });
+
+ test('skips when a CI env var is set', () => {
+ // eslint-disable-next-line turbo/no-undeclared-env-vars
+ process.env.CI = 'true';
+
+ maybeShowTelemetryNotice();
+
+ expect(logSpy).not.toHaveBeenCalled();
+ });
+
+ test.each(CI_VARS)('skips when %s is set', name => {
+ process.env[name] = '1';
+
+ maybeShowTelemetryNotice();
+
+ expect(logSpy).not.toHaveBeenCalled();
+ });
+
+ test('skips in a browser-like environment', () => {
+ const original = (globalThis as { window?: unknown }).window;
+ (globalThis as { window?: unknown }).window = {};
+
+ try {
+ maybeShowTelemetryNotice();
+ expect(logSpy).not.toHaveBeenCalled();
+ } finally {
+ if (typeof original === 'undefined') {
+ delete (globalThis as { window?: unknown }).window;
+ } else {
+ (globalThis as { window?: unknown }).window = original;
+ }
+ }
+ });
+
+ test('skips in Next.js Edge Runtime', () => {
+ (globalThis as { EdgeRuntime?: string }).EdgeRuntime = 'edge-runtime';
+
+ try {
+ maybeShowTelemetryNotice();
+ expect(logSpy).not.toHaveBeenCalled();
+ } finally {
+ delete (globalThis as { EdgeRuntime?: string }).EdgeRuntime;
+ }
+ });
+
+ test('does not throw if console.log fails', () => {
+ logSpy.mockImplementation(() => {
+ throw new Error('console broken');
+ });
+
+ expect(() => maybeShowTelemetryNotice()).not.toThrow();
+ });
+});

packages/shared/src/telemetry/collector.ts

@@ -20,6 +20,7 @@ import type {
  TelemetryLogEntry,
 } from '../types';
 import { isTruthy } from '../underscore';
+import { maybeShowTelemetryNotice } from './notice';
 import { InMemoryThrottlerCache, LocalStorageThrottlerCache, TelemetryEventThrottler } from './throttler';
 import type { TelemetryCollectorOptions } from './types';
 
@@ -145,6 +146,11 @@ export class TelemetryCollector implements TelemetryCollectorInterface {
  ? new LocalStorageThrottlerCache()
  : new InMemoryThrottlerCache();
  this.#eventThrottler = new TelemetryEventThrottler(cache);
+
+ // Surface the one-time telemetry disclosure at runtime instead of via a postinstall script.
+ // Gated on `isEnabled` so users who opted out (or are not on a development instance) are not
+ // shown a notice for collection that will never happen.
+ maybeShowTelemetryNotice({ skip: !this.isEnabled });
  }
 
  get isEnabled(): boolean {

packages/shared/src/telemetry/notice.ts

@@ -0,0 +1,123 @@
+/**
+ * One-time runtime disclosure that Clerk collects telemetry from development instances.
+ *
+ * Replaces the previous `postinstall` script. Disclosure is intentionally surfaced
+ * only on Node (server-side) so the noise profile matches the original postinstall
+ * (terminal-only, dev-eyes-only). Browser consoles are not used because they are
+ * frequently observed by non-developers (QA, screenshots, demos), and adding another
+ * console warning is a common source of customer complaints.
+ *
+ * Known gap: pure browser-only setups with no server-side Clerk runtime (e.g. a Vite
+ * SPA using `@clerk/clerk-react` or `@clerk/clerk-js` directly, without any Node/Edge
+ * backend that imports `@clerk/shared`) will never hit this code path and therefore
+ * see no in-band disclosure. This is an accepted trade-off: the original postinstall
+ * already fired only once at install time and was easily missed, so the practical
+ * delta is small. Authoritative disclosure for those setups lives in the Clerk
+ * telemetry docs (https://clerk.com/docs/telemetry). Opt-out continues to work the
+ * same way (`telemetry={false}` on `<ClerkProvider>` or the framework-specific
+ * `*_CLERK_TELEMETRY_DISABLED` env var).
+ *
+ * Persistence is in-process via a `globalThis` Symbol, which survives Next.js HMR
+ * module reloads. No filesystem access, no `node:` imports, no dynamic-code APIs, so
+ * the module remains safe to bundle for Edge Runtime, Workers, and any browser path.
+ *
+ * All work is wrapped in try/catch. Failure to display the notice must never affect
+ * the SDK.
+ */
+
+import { isTruthy } from '../underscore';
+import { automatedEnvironmentVariables } from '../utils/runtimeEnvironment';
+
+const PROCESS_FLAG = Symbol.for('@clerk/shared.telemetryNoticeShown');
+
+const NOTICE_LINES = [
+ 'Attention: Clerk collects telemetry data from its SDKs when connected to development instances.',
+ "The data collected is used to inform Clerk's product roadmap.",
+ 'To learn more, including how to opt-out from the telemetry program, visit: https://clerk.com/docs/telemetry.',
+];
+
+function isServerRuntime(): boolean {
+ // Skip in browsers.
+ if (typeof window !== 'undefined') {
+ return false;
+ }
+ // Skip in Next.js Edge Runtime, which exposes a global `EdgeRuntime` marker. We detect via
+ // this marker (rather than checking `process.versions`) because the Edge Runtime build-time
+ // analyzer flags any reachable read of `process.versions` even when it sits behind a guard.
+ if (typeof (globalThis as { EdgeRuntime?: string }).EdgeRuntime !== 'undefined') {
+ return false;
+ }
+ return true;
+}
+
+// Server-only notice: read process.env directly rather than going through
+// getEnvVariable(), which would pull the multi-runtime env resolver into the
+// clerk.browser.js bundle (it ships there via TelemetryCollector). We reuse the
+// shared CI env-var list so the set of detected providers stays in one place.
+function isCI(): boolean {
+ if (typeof process === 'undefined' || !process.env) {
+ return false;
+ }
+ return automatedEnvironmentVariables.some(name => isTruthy(process.env[name]));
+}
+
+function hasSeen(): boolean {
+ return Boolean((globalThis as Record<symbol, unknown>)[PROCESS_FLAG]);
+}
+
+function markSeen(): void {
+ (globalThis as Record<symbol, unknown>)[PROCESS_FLAG] = true;
+}
+
+function printNotice(): void {
+ if (typeof console === 'undefined' || typeof console.log !== 'function') {
+ return;
+ }
+ for (const line of NOTICE_LINES) {
+ console.log(line);
+ }
+ console.log('');
+}
+
+export type MaybeShowTelemetryNoticeOptions = {
+ /**
+ * Skip the notice entirely. Used when the caller has already determined that no
+ * telemetry will be sent (e.g. opt-out, non-development instance), in which case
+ * there is nothing to disclose.
+ */
+ skip?: boolean;
+};
+
+/**
+ * Display the one-time telemetry disclosure on server runtimes if it has not already been
+ * shown in this process. Browser and Edge Runtime callers are silently skipped. Never throws.
+ */
+export function maybeShowTelemetryNotice(options: MaybeShowTelemetryNoticeOptions = {}): void {
+ if (options.skip) {
+ return;
+ }
+ try {
+ if (!isServerRuntime()) {
+ return;
+ }
+ if (isCI()) {
+ return;
+ }
+ if (hasSeen()) {
+ return;
+ }
+ printNotice();
+ markSeen();
+ } catch {
+ // never let disclosure break the SDK
+ }
+}
+
+/**
+ * Test-only: clear the in-process flag so the next call re-runs the gating logic.
+ *
+ * @internal
+ */
+export function __resetTelemetryNoticeForTests(): void {
+ delete (globalThis as Record<symbol, unknown>)[PROCESS_FLAG];
+}

.changeset/sdk-84-remove-telemetry-postinstall.md

@@ -0,0 +1,9 @@
+---
+'@clerk/shared': patch
+---
+
+Replace the telemetry `postinstall` script with a one-time runtime notice, printed once per process on server runtimes (Node, excluding CI) when the telemetry collector boots against a development instance. Drops the `std-env` dependency.
+
+Removing `postinstall` improves the package's supply-chain posture: `@clerk/shared` no longer executes arbitrary code at install time, aligning with package-manager defaults that increasingly disable install scripts.
+
+Browser-only applications with no server-side Clerk runtime (e.g. a Vite SPA) will not surface an in-band notice. Telemetry behavior and opt-out (`telemetry={false}` or `*_CLERK_TELEMETRY_DISABLED`) are unchanged; disclosure for these setups is provided at https://clerk.com/docs/telemetry.

packages/shared/package.json

@@ -121,8 +121,7 @@
  }
  },
  "files": [
- "dist",
- "scripts"
+ "dist"
  ],
  "scripts": {
  "build": "tsdown",
@@ -131,7 +130,6 @@
  "dev:pub": "pnpm dev -- --env.publish",
  "format": "node ../../scripts/format-package.mjs",
  "format:check": "node ../../scripts/format-package.mjs --check",
- "postinstall": "node ./scripts/postinstall.mjs",
  "lint": "eslint src",
  "lint:attw": "attw --pack . --profile node16",
  "lint:publint": "publint",
@@ -143,8 +141,7 @@
  "@tanstack/query-core": "catalog:repo",
  "dequal": "2.0.3",
  "glob-to-regexp": "0.4.1",
- "js-cookie": "3.0.7",
- "std-env": "^3.9.0"
+ "js-cookie": "3.0.7"
  },
  "devDependencies": {
  "@base-org/account": "catalog:module-manager",

packages/shared/src/__tests__/telemetry.notice.spec.ts

@@ -0,0 +1,114 @@
+/**
+ * @vitest-environment node
+ */
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+
+import { __resetTelemetryNoticeForTests, maybeShowTelemetryNotice } from '../telemetry/notice';
+import { automatedEnvironmentVariables } from '../utils/runtimeEnvironment';
+
+const CI_VARS = automatedEnvironmentVariables;
+
+function clearCIEnv() {
+ for (const name of CI_VARS) {
+ delete process.env[name];
+ }
+}
+
+describe('maybeShowTelemetryNotice', () => {
+ let logSpy: ReturnType<typeof vi.spyOn>;
+ let originalCIEnv: Record<string, string | undefined>;
+
+ beforeEach(() => {
+ originalCIEnv = Object.fromEntries(CI_VARS.map(name => [name, process.env[name]]));
+ clearCIEnv();
+ __resetTelemetryNoticeForTests();
+ logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+ });
+
+ afterEach(() => {
+ logSpy.mockRestore();
+ for (const [name, value] of Object.entries(originalCIEnv)) {
+ if (typeof value === 'string') {
+ process.env[name] = value;
+ } else {
+ delete process.env[name];
+ }
+ }
+ });
+
+ test('prints the disclosure on Node', () => {
+ maybeShowTelemetryNotice();
+
+ expect(logSpy).toHaveBeenCalled();
+ const printed = logSpy.mock.calls.map(call => String(call[0])).join('\n');
+ expect(printed).toMatch(/Clerk collects telemetry/);
+ expect(printed).toMatch(/clerk\.com\/docs\/telemetry/);
+ });
+
+ test('does not print again on subsequent calls in the same process', () => {
+ maybeShowTelemetryNotice();
+ maybeShowTelemetryNotice();
+ maybeShowTelemetryNotice();
+
+ const disclosureCalls = logSpy.mock.calls.filter(call => /Clerk collects telemetry/.test(String(call[0])));
+ expect(disclosureCalls).toHaveLength(1);
+ });
+
+ test('skips entirely when skip:true is passed', () => {
+ maybeShowTelemetryNotice({ skip: true });
+
+ expect(logSpy).not.toHaveBeenCalled();
+ });
+
+ test('skips when a CI env var is set', () => {
+ // eslint-disable-next-line turbo/no-undeclared-env-vars
+ process.env.CI = 'true';
+
+ maybeShowTelemetryNotice();
+
+ expect(logSpy).not.toHaveBeenCalled();
+ });
+
+ test.each(CI_VARS)('skips when %s is set', name => {
+ process.env[name] = '1';
+
+ maybeShowTelemetryNotice();
+
+ expect(logSpy).not.toHaveBeenCalled();
+ });
+
+ test('skips in a browser-like environment', () => {
+ const original = (globalThis as { window?: unknown }).window;
+ (globalThis as { window?: unknown }).window = {};
+
+ try {
+ maybeShowTelemetryNotice();
+ expect(logSpy).not.toHaveBeenCalled();
+ } finally {
+ if (typeof original === 'undefined') {
+ delete (globalThis as { window?: unknown }).window;
+ } else {
+ (globalThis as { window?: unknown }).window = original;
+ }
+ }
+ });
+
+ test('skips in Next.js Edge Runtime', () => {
+ (globalThis as { EdgeRuntime?: string }).EdgeRuntime = 'edge-runtime';
+
+ try {
+ maybeShowTelemetryNotice();
+ expect(logSpy).not.toHaveBeenCalled();
+ } finally {
+ delete (globalThis as { EdgeRuntime?: string }).EdgeRuntime;
+ }
+ });
+
+ test('does not throw if console.log fails', () => {
+ logSpy.mockImplementation(() => {
+ throw new Error('console broken');
+ });
+
+ expect(() => maybeShowTelemetryNotice()).not.toThrow();
+ });
+});

packages/shared/src/telemetry/collector.ts

@@ -20,6 +20,7 @@ import type {
  TelemetryLogEntry,
 } from '../types';
 import { isTruthy } from '../underscore';
+import { maybeShowTelemetryNotice } from './notice';
 import { InMemoryThrottlerCache, LocalStorageThrottlerCache, TelemetryEventThrottler } from './throttler';
 import type { TelemetryCollectorOptions } from './types';
 
@@ -145,6 +146,11 @@ export class TelemetryCollector implements TelemetryCollectorInterface {
  ? new LocalStorageThrottlerCache()
  : new InMemoryThrottlerCache();
  this.#eventThrottler = new TelemetryEventThrottler(cache);
+
+ // Surface the one-time telemetry disclosure at runtime instead of via a postinstall script.
+ // Gated on `isEnabled` so users who opted out (or are not on a development instance) are not
+ // shown a notice for collection that will never happen.
+ maybeShowTelemetryNotice({ skip: !this.isEnabled });
  }
 
  get isEnabled(): boolean {

packages/shared/src/telemetry/notice.ts

@@ -0,0 +1,123 @@
+/**
+ * One-time runtime disclosure that Clerk collects telemetry from development instances.
+ *
+ * Replaces the previous `postinstall` script. Disclosure is intentionally surfaced
+ * only on Node (server-side) so the noise profile matches the original postinstall
+ * (terminal-only, dev-eyes-only). Browser consoles are not used because they are
+ * frequently observed by non-developers (QA, screenshots, demos), and adding another
+ * console warning is a common source of customer complaints.
+ *
+ * Known gap: pure browser-only setups with no server-side Clerk runtime (e.g. a Vite
+ * SPA using `@clerk/clerk-react` or `@clerk/clerk-js` directly, without any Node/Edge
+ * backend that imports `@clerk/shared`) will never hit this code path and therefore
+ * see no in-band disclosure. This is an accepted trade-off: the original postinstall
+ * already fired only once at install time and was easily missed, so the practical
+ * delta is small. Authoritative disclosure for those setups lives in the Clerk
+ * telemetry docs (https://clerk.com/docs/telemetry). Opt-out continues to work the
+ * same way (`telemetry={false}` on `<ClerkProvider>` or the framework-specific
+ * `*_CLERK_TELEMETRY_DISABLED` env var).
+ *
+ * Persistence is in-process via a `globalThis` Symbol, which survives Next.js HMR
+ * module reloads. No filesystem access, no `node:` imports, no dynamic-code APIs, so
+ * the module remains safe to bundle for Edge Runtime, Workers, and any browser path.
+ *
+ * All work is wrapped in try/catch. Failure to display the notice must never affect
+ * the SDK.
+ */
+
+import { isTruthy } from '../underscore';
+import { automatedEnvironmentVariables } from '../utils/runtimeEnvironment';
+
+const PROCESS_FLAG = Symbol.for('@clerk/shared.telemetryNoticeShown');
+
+const NOTICE_LINES = [
+ 'Attention: Clerk collects telemetry data from its SDKs when connected to development instances.',
+ "The data collected is used to inform Clerk's product roadmap.",
+ 'To learn more, including how to opt-out from the telemetry program, visit: https://clerk.com/docs/telemetry.',
+];
+
+function isServerRuntime(): boolean {
+ // Skip in browsers.
+ if (typeof window !== 'undefined') {
+ return false;
+ }
+ // Skip in Next.js Edge Runtime, which exposes a global `EdgeRuntime` marker. We detect via
+ // this marker (rather than checking `process.versions`) because the Edge Runtime build-time
+ // analyzer flags any reachable read of `process.versions` even when it sits behind a guard.
+ if (typeof (globalThis as { EdgeRuntime?: string }).EdgeRuntime !== 'undefined') {
+ return false;
+ }
+ return true;
+}
+
+// Server-only notice: read process.env directly rather than going through
+// getEnvVariable(), which would pull the multi-runtime env resolver into the
+// clerk.browser.js bundle (it ships there via TelemetryCollector). We reuse the
+// shared CI env-var list so the set of detected providers stays in one place.
+function isCI(): boolean {
+ if (typeof process === 'undefined' || !process.env) {
+ return false;
+ }
+ return automatedEnvironmentVariables.some(name => isTruthy(process.env[name]));
+}
+
+function hasSeen(): boolean {
+ return Boolean((globalThis as Record<symbol, unknown>)[PROCESS_FLAG]);
+}
+
+function markSeen(): void {
+ (globalThis as Record<symbol, unknown>)[PROCESS_FLAG] = true;
+}
+
+function printNotice(): void {
+ if (typeof console === 'undefined' || typeof console.log !== 'function') {
+ return;
+ }
+ for (const line of NOTICE_LINES) {
+ console.log(line);
+ }
+ console.log('');
+}
+
+export type MaybeShowTelemetryNoticeOptions = {
+ /**
+ * Skip the notice entirely. Used when the caller has already determined that no
+ * telemetry will be sent (e.g. opt-out, non-development instance), in which case
+ * there is nothing to disclose.
+ */
+ skip?: boolean;
+};
+
+/**
+ * Display the one-time telemetry disclosure on server runtimes if it has not already been
+ * shown in this process. Browser and Edge Runtime callers are silently skipped. Never throws.
+ */
+export function maybeShowTelemetryNotice(options: MaybeShowTelemetryNoticeOptions = {}): void {
+ if (options.skip) {
+ return;
+ }
+ try {
+ if (!isServerRuntime()) {
+ return;
+ }
+ if (isCI()) {
+ return;
+ }
+ if (hasSeen()) {
+ return;
+ }
+ printNotice();
+ markSeen();
+ } catch {
+ // never let disclosure break the SDK
+ }
+}
+
+/**
+ * Test-only: clear the in-process flag so the next call re-runs the gating logic.
+ *
+ * @internal
+ */
+export function __resetTelemetryNoticeForTests(): void {
+ delete (globalThis as Record<symbol, unknown>)[PROCESS_FLAG];
+}