chore(shared,ui): Add telemetry event for flow steps

[LauraBeatris]

Description

This PR adds a new telemetry event to track when a flow step gets mounted, so we can leverage it on multi step flows such as self-serve SSO.

We want to leverage those events to later query the average time between when the user lands on the first step and actually ends up activating the connection.

Checklist

• pnpm test runs as expected.
• pnpm build runs as expected.
• (If applicable) JSDoc comments have been added or updated for any package exports
• (If applicable) Documentation has been updated

Type of change

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

Summary by CodeRabbit

• New Features
  • Added a generic flow-step telemetry event builder to support multi-step funnel measurement.
  • Extended self-serve SSO telemetry to record events when key steps mount and when SSO activation completes, including timestamps and relevant connection and organization identifiers.
• Chores
  • Improved end-to-end observability across the SSO flow lifecycle with broader telemetry coverage.

[changeset-bot]

🦋 Changeset detected

Latest commit: 56719d3

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 23 packages

Name	Type
@clerk/shared	Patch
@clerk/ui	Patch
@clerk/astro	Patch
@clerk/backend	Patch
@clerk/chrome-extension	Patch
@clerk/clerk-js	Patch
@clerk/electron	Patch
@clerk/expo-passkeys	Patch
@clerk/expo	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/headless	Patch
@clerk/hono	Patch
@clerk/localizations	Patch
@clerk/msw	Patch
@clerk/nextjs	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/react	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	Patch
@clerk/vue	Patch
@clerk/swingset	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jun 23, 2026 7:17pm
swingset	Ready	Preview, Comment	Jun 23, 2026 7:17pm

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds a new eventFlowStepMounted telemetry event builder in the shared telemetry package and integrates it into two ConfigureSSO step components: ActivateStep emits the event after a successful connection activation, and OrganizationDomainsStep emits it once on mount via a useRef-guarded useEffect.

Changes

Flow Step Telemetry

Layer / File(s)	Summary
eventFlowStepMounted helper and export packages/shared/src/telemetry/events/flow-step.ts, packages/shared/src/telemetry/events/index.ts, .changeset/gold-ends-throw.md	Defines the FLOW_STEP_MOUNTED event name constant, default sampling rate, EventFlowStepMounted payload type, and the eventFlowStepMounted builder function. Re-exports it from the telemetry events barrel and updates the release notes/patch metadata.
Telemetry recording in ActivateStep and OrganizationDomainsStep packages/ui/src/components/ConfigureSSO/steps/ActivateStep.tsx, packages/ui/src/components/ConfigureSSO/steps/OrganizationDomainsStep.tsx	ActivateStep calls useClerk and useOrganization and emits eventFlowStepMounted('configureSSO', 'activate', ...) after successful activation. OrganizationDomainsStep adds useEffect and useRef to emit the event once on mount for the verify-domain step, guarded by a ref to prevent duplicate records.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• clerk/javascript#8882: Modifies the self-serve SSO ActivateStep, which overlaps with the activation-path telemetry added here.
• clerk/javascript#8866: Both PRs modify the OrganizationDomainsStep component, with the main PR adding telemetry on mount and the retrieved PR adding domain-deletion flows.

Suggested reviewers

• iagodahlem

Poem

🐇 Hop, hop, a step took flight,
Tiny events now glow at night.
flow-step.ts hums, the funnel sings,
Two SSO steps got telemetry wings.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: adding a telemetry event for tracking flow steps across the shared and ui packages.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands.}

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@8951

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@8951

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@8951

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@8951

@clerk/electron

npm i https://pkg.pr.new/@clerk/electron@8951

@clerk/electron-passkeys

npm i https://pkg.pr.new/@clerk/electron-passkeys@8951

@clerk/eslint-plugin

npm i https://pkg.pr.new/@clerk/eslint-plugin@8951

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@8951

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@8951

@clerk/express

npm i https://pkg.pr.new/@clerk/express@8951

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@8951

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@8951

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@8951

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@8951

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@8951

@clerk/react

npm i https://pkg.pr.new/@clerk/react@8951

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@8951

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@8951

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@8951

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@8951

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@8951

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@8951

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@8951

commit: 56719d3

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/shared/src/telemetry/events/flow-step.ts`:
- Around line 34-38: The spread of payload in the telemetry event payload object
allows external data to override the core flow-step fields (flow, step, and
timestamp). Reorder the properties in the payload object so that the spread of
payload comes first, followed by the explicit core fields (flow, step, and
timestamp) so that these critical telemetry fields take precedence and cannot be
overridden by any data in the payload parameter.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Repository UI (inherited)

Review profile: CHILL

Plan: Pro

Run ID: b8bab827-d791-4454-80d8-9457d04e4a9c

📥 Commits

Reviewing files that changed from the base of the PR and between dd51fe4 and 8377b13.

📒 Files selected for processing (4)

• packages/shared/src/telemetry/events/flow-step.ts
• packages/shared/src/telemetry/events/index.ts
• packages/ui/src/components/ConfigureSSO/steps/ActivateStep.tsx
• packages/ui/src/components/ConfigureSSO/steps/OrganizationDomainsStep.tsx

[github-actions]

API Changes Report

Generated by Break Check on 2026-06-23T19:19:09.028Z

Summary

Metric	Count
Packages analyzed	19
Packages with changes	1
🔴 Breaking changes	0
🟡 Non-breaking changes	0
🟢 Additions	1

---

@clerk/shared

Current version: 4.20.0
Recommended bump: MINOR → 4.21.0

Subpath ./telemetry

🟢 Additions (1)

Added: eventFlowStepMounted

+ declare function eventFlowStepMounted(flow: string, step: string, metadata?: TelemetryEventRaw['payload'], eventSamplingRate?: number): TelemetryEventRaw<EventFlowStepMounted>;

Added function eventFlowStepMounted

---

Report generated by Break Check

_{Last ran on 56719d3.}