-
Notifications
You must be signed in to change notification settings - Fork 453
chore(shared): replace telemetry postinstall with runtime notice #8549
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
jacekradko
merged 9 commits into
main
from
jacek/sdk-84-remove-telemetry-postinstall-notice
Jun 3, 2026
Merged
Changes from all commits
Commits
Show all changes
9 commits
Select commit
Hold shift + click to select a range
0158426
chore(shared): replace telemetry postinstall with runtime notice
jacekradko b121f97
fix(shared): evade bundler static analysis for node: imports
jacekradko d148c8c
fix(shared): drop fs persistence and new Function from telemetry notice
jacekradko b3d0fd5
refactor(shared): scope telemetry notice to server-side only
jacekradko c2cce4e
fix(shared): detect server runtime without reading process.versions
jacekradko 48c8ef9
fix(shared): add curly braces to satisfy eslint curly rule
jacekradko 77e2db7
update changeset
jacekradko 4dd535a
docs(shared): document SPA disclosure trade-off and supply-chain rati…
jacekradko 7034b14
refactor(shared): reuse shared CI env-var list in telemetry notice
jacekradko File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file was deleted.
Oops, something went wrong.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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(); | ||
| }); | ||
| }); |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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]; | ||
| } | ||
Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.