feat(js,ui): mount and render the directory sync setup flow

[kalafut]

Description

Part 3 of 5 of the self-serve Directory Sync stack. Stacked on jim/dir-sync-2-hooks; the changeset lands in the final PR and the stack will be squashed on merge.

• @clerk/clerk-js: __internal_mountConfigureDirectorySync with guards mirroring ConfigureSSO's (orgs enabled, active org, self-serve directory sync feature).
• @clerk/ui: ConfigureDirectorySync wizard over the organization's enterprise connection and directory (show-once token held in wizard session state, read-only attribute mapping from the directory, test step polls provisioned users), plus a Directory Sync section on the Security page. Google-provider connections are directed to the Dashboard.

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:

🤖 Generated with Claude Code

https://claude.ai/code/session_01RYZSEgDLvdeKhFgnxFzPeP

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview	Aug 28, 2026 10:48pm
swingset	Ready	Preview	Aug 28, 2026 10:48pm

[changeset-bot]

⚠️ No Changeset found

Latest commit: f598bc7

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/electron

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

@clerk/electron-passkeys

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

@clerk/eslint-plugin

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

@clerk/expo

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

@clerk/expo-google-signin

npm i https://pkg.pr.new/@clerk/expo-google-signin@9592

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: f598bc7

[github-actions]

API Changes Report

Generated by Break Check on 2026-08-28T22:50:44.433Z

Summary

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

🤖 This report was reviewed by claude-sonnet-4-6.

---

@clerk/clerk-js

Current version: 6.30.2
Recommended bump: MINOR → 6.31.0

Subpath .

🟢 Additions (2)

Added: Clerk.__internal_mountConfigureDirectorySync

+ __internal_mountConfigureDirectorySync: (node: HTMLDivElement, props?: ConfigureSSOProps) => void;

Added property Clerk.__internal_mountConfigureDirectorySync

Added: Clerk.__internal_unmountConfigureDirectorySync

+ __internal_unmountConfigureDirectorySync: (node: HTMLDivElement) => void;

Added property Clerk.__internal_unmountConfigureDirectorySync

Subpath ./no-rhc

🟢 Additions (2)

Added: Clerk.__internal_mountConfigureDirectorySync

+ __internal_mountConfigureDirectorySync: (node: HTMLDivElement, props?: ConfigureSSOProps) => void;

Added property Clerk.__internal_mountConfigureDirectorySync

Added: Clerk.__internal_unmountConfigureDirectorySync

+ __internal_unmountConfigureDirectorySync: (node: HTMLDivElement) => void;

Added property Clerk.__internal_unmountConfigureDirectorySync

---

@clerk/shared

Current version: 4.30.2
Recommended bump: MINOR → 4.31.0

Subpath ./internal/clerk-js/componentGuards

🟢 Additions (1)

Added: disabledSelfServeDirectorySyncFeature

+ disabledSelfServeDirectorySyncFeature: ComponentGuard

Added variable disabledSelfServeDirectorySyncFeature

Subpath ./internal/clerk-js/warnings

🟡 Non-breaking Changes (1)

Modified: warnings

// ... 7 unchanged lines elided ...
    cannotRenderSignInComponentWhenSessionExists: string;
    cannotRenderSignInComponentWhenTaskExists: string;
    cannotRenderComponentWhenUserDoesNotExist: string;
-   createCannotRenderComponentWhenOrgDoesNotExist: (componentName: "OrganizationProfile" | "InviteMembers" | "ConfigureSSO") => string;
+   createCannotRenderComponentWhenOrgDoesNotExist: (componentName: "OrganizationProfile" | "InviteMembers" | "ConfigureSSO" | "ConfigureDirectorySync") => string;
    createCannotRenderComponentWhenPermissionIsMissing: (componentName: "InviteMembers", permission: string) => string;
-   cannotRenderAnyOrganizationComponent: (componentName: "OrganizationProfile" | "InviteMembers" | "OrganizationSwitcher" | "OrganizationList" | "CreateOrganization" | "TaskChooseOrganization" | "ConfigureSSO") => string;
+   cannotRenderAnyOrganizationComponent: (componentName: "OrganizationProfile" | "InviteMembers" | "OrganizationSwitcher" | "OrganizationList" | "CreateOrganization" | "TaskChooseOrganization" | "ConfigureSSO" | "ConfigureDirectorySync") => string;
    cannotRenderAnyBillingComponent: (componentName: "PricingTable" | "Checkout" | "PlanDetails") => string;
    cannotOpenUserProfile: string;
    cannotOpenCheckout: string;
    cannotOpenSignInOrSignUp: string;
    cannotRenderAPIKeysComponent: string;
    cannotRenderAPIKeysComponentForOrgWhenUnauthorized: string;
    cannotRenderAPIKeysComponentForUserWhenDisabled: string;
    cannotRenderAPIKeysComponentForOrgWhenDisabled: string;
    cannotRenderOAuthConsentComponentWhenUserDoesNotExist: string;
    cannotRenderConfigureSSOComponentWhenUserDoesNotExist: string;
    cannotRenderConfigureSSOComponentWhenDisabled: string;
+   cannotRenderConfigureDirectorySyncComponentWhenDisabled: string;
    cannotRenderConfigureSSOComponentWhenEmailAddressDisabled: string;
  }

Static analyzer: Breaking change in variable warnings: Type changed: {proxyUrlAsFunctionNotSupported:string;domainAsFunctionNotSupported:string;cannotRenderComponentWhenSessionExists:strin… → {proxyUrlAsFunctionNotSupported:string;domainAsFunctionNotSupported:string;cannotRenderComponentWhenSessionExists:strin…

🤖 AI review (reclassified as non-breaking) (90%): The only changes are: (1) adding "ConfigureDirectorySync" to the union parameter of createCannotRenderComponentWhenOrgDoesNotExist and cannotRenderAnyOrganizationComponent — widening a function parameter's union is non-breaking for callers (input contravariance), and (2) adding a new required property cannotRenderConfigureDirectorySyncComponentWhenDisabled: string — since warnings is an internally-constructed object (an output/value, not a type consumers must implement or construct), adding a property to it does not break existing consumers who only read it.

Subpath ./types

🟡 Non-breaking Changes (3)

Modified: __internal_AttemptToEnableEnvironmentSettingParams

  type __internal_AttemptToEnableEnvironmentSettingParams = {
    for: 'organizations';
-   caller: 'OrganizationSwitcher' | 'OrganizationProfile' | 'InviteMembers' | 'OrganizationList' | 'CreateOrganization' | 'TaskChooseOrganization' | 'ConfigureSSO' | 'useOrganizationList' | 'useOrganization';
+   caller: 'OrganizationSwitcher' | 'OrganizationProfile' | 'InviteMembers' | 'OrganizationList' | 'CreateOrganization' | 'TaskChooseOrganization' | 'ConfigureSSO' | 'ConfigureDirectorySync' | 'useOrganizationList' | 'useOrganization';
    onClose?: () => void;
  };

Static analyzer: Breaking change in type alias __internal_AttemptToEnableEnvironmentSettingParams: Type changed: {for:'organizations';caller:'ConfigureSSO'|'CreateOrganization'|'InviteMembers'|'OrganizationList'|'OrganizationProfile… → {for:'organizations';caller:'ConfigureDirectorySync'|'ConfigureSSO'|'CreateOrganization'|'InviteMembers'|'OrganizationL…

🤖 AI review (reclassified as non-breaking) (90%): The caller union was widened by adding 'ConfigureDirectorySync'; this is an input parameter type, so broadening the union of accepted values is non-breaking for callers who pass existing string literals (their code still compiles) — no existing valid caller value was removed.

Modified: __internal_LocalizationResource

// ... 1108 unchanged lines elided ...
          tooltip__noRole: LocalizationValue;
          tooltipLabel: LocalizationValue;
        };
+       directorySyncSection: {
+         title: LocalizationValue;
+         badge__unconfigured: LocalizationValue;
+         badge__active: LocalizationValue;
+         badge__inactive: LocalizationValue;
+         description: LocalizationValue;
+         primaryButton__startConfiguration: LocalizationValue;
+         menuAction__edit: LocalizationValue;
+         menuAction__activate: LocalizationValue;
+         menuAction__deactivate: LocalizationValue;
+         menuAction__remove: LocalizationValue;
+         removeDialog: {
+           title: LocalizationValue;
+           subtitle: LocalizationValue;
+           confirmButton: LocalizationValue;
+         };
+       };
      };
      membersPage: {
        detailsTitle__emptyRow: LocalizationValue;
// ... 963 unchanged lines elided ...

Static analyzer: Breaking change in type alias __internal_LocalizationResource: Type changed: {locale:string;maintenanceMode:import("@clerk/shared").LocalizationValue;roles:{[r:string]:import("@clerk/shared").Loca… → {locale:string;maintenanceMode:import("@clerk/shared").LocalizationValue;roles:{[r:string]:import("@clerk/shared").Loca…

🤖 AI review (reclassified as non-breaking) (85%): __internal_LocalizationResource is used as the basis for LocalizationResource via DeepPartial<DeepLocalizationWithoutObjects<...>>, meaning consumers read/extend it as an output/extension type; the elided diff adds new optional-by-partial-wrapping localization keys, which is non-breaking for consumers who only supply a subset.

Modified: ProfileSectionId

- type ProfileSectionId = 'profile' | 'username' | 'emailAddresses' | 'phoneNumbers' | 'connectedAccounts' | 'enterpriseAccounts' | 'web3Wallets' | 'password' | 'passkeys' | 'mfa' | 'danger' | 'activeDevices' | 'organizationProfile' | 'organizationDanger' | 'organizationDomains' | 'manageVerifiedDomains' | 'subscriptionsList' | 'paymentMethods' | 'sso' | 'ssoStatus' | 'enableSso' | 'ssoDomain' | 'ssoConfiguration' | 'configureAgain' | 'resetSso' | 'testSsoUrl' | 'testResults' | 'accountCredits';
+ type ProfileSectionId = 'profile' | 'username' | 'emailAddresses' | 'phoneNumbers' | 'connectedAccounts' | 'enterpriseAccounts' | 'web3Wallets' | 'password' | 'passkeys' | 'mfa' | 'danger' | 'activeDevices' | 'organizationProfile' | 'organizationDanger' | 'organizationDomains' | 'manageVerifiedDomains' | 'subscriptionsList' | 'paymentMethods' | 'sso' | 'directorySync' | 'ssoStatus' | 'enableSso' | 'ssoDomain' | 'ssoConfiguration' | 'configureAgain' | 'resetSso' | 'testSsoUrl' | 'testResults' | 'accountCredits';

Static analyzer: Breaking change in type alias ProfileSectionId: Type changed: 'accountCredits'|'activeDevices'|'configureAgain'|'connectedAccounts'|'danger'|'emailAddresses'|'enableSso'|'enterprise… → 'accountCredits'|'activeDevices'|'configureAgain'|'connectedAccounts'|'danger'|'directorySync'|'emailAddresses'|'enable…

🤖 AI review (reclassified as non-breaking) (90%): ProfileSectionId is a union that had 'directorySync' added; it feeds into MenuId which is used internally. Adding a new member to a string union is non-breaking for consumers who switch/compare on known values and never need to exhaustively cover all members.

---

Report generated by Break Check

_{Last ran on f598bc7.}