chore(ui): Layer architecture for configure steps per IdP and protocol

[LauraBeatris]

Description

Introduces new architecture for adding configuration steps per IdP and protocol, making it more flexible to add Microsoft Entra + Google Workspace for SAML, and later OpenID connect.

Now, each protocol has it's folder within the provider types, and each provider should have it's inner steps created within a module, which allows for flexibility when composing the UI.

How to add a new SAML provider

1. Update the ProviderType union
2. Once the union gets updated, then it'll require to update the step mapper within ConfigureStep/index.tsx
3. Implement the steps component for that identity provider according to it's instructions

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:

[changeset-bot]

🦋 Changeset detected

Latest commit: 8be9b23

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

This PR includes changesets to release 20 packages

Name	Type
@clerk/localizations	Patch
@clerk/shared	Patch
@clerk/ui	Patch
@clerk/react	Patch
@clerk/astro	Patch
@clerk/backend	Patch
@clerk/chrome-extension	Patch
@clerk/clerk-js	Patch
@clerk/expo-passkeys	Patch
@clerk/expo	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/hono	Patch
@clerk/msw	Patch
@clerk/nextjs	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	Patch
@clerk/vue	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	May 28, 2026 2:48pm

[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

This PR refactors the ConfigureSSO SAML wizard architecture into provider-specific, step-based flows and updates localization and types accordingly. It adds shared UI components AttributeMappingTable and IdentityProviderMetadataForm, implements SamlOktaConfigureSteps and SamlCustomConfigureSteps composed of create-app, attribute-mapping, assign-users, and identity-provider-metadata steps, introduces a provider-dispatching ConfigureStep entry, and extracts a shared InnerStepCounter used by VerifyDomainStep.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• clerk/javascript#8553: Implements segmented metadata URL vs manual IdP metadata flow and related localization keys used here.
• clerk/javascript#8535: Earlier Okta Configure step UI and localization work that this PR refactors into the step-based hierarchy.
• clerk/javascript#8586: Overlaps changes to SAML attribute-mapping UI and localization keys.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main architectural change: introducing a layered architecture for configure steps organized by IdP and protocol.
Description check	✅ Passed	The description clearly explains the architectural refactoring, provides context on use cases, and includes implementation guidance for adding new providers.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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 and usage tips.}

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/dev-cli

npm i https://pkg.pr.new/@clerk/dev-cli@8651

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 8be9b23

[coderabbitai]

🧹 Nitpick comments (1)

packages/shared/src/types/localization.ts (1)

1403-1573: ⚡ Quick win

Add a type-level regression check for the new localization schema.

This rewires a large public key surface, but no coverage was updated in the supplied diff. A compile-time fixture asserting the default SSO localization resource still satisfies this configureSSO.configureStep shape would catch missing or renamed keys early.

As per coding guidelines, "If there are no tests added or modified as part of the PR, please suggest that tests be added to cover the changes."

🤖 Prompt for 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.

In `@packages/shared/src/types/localization.ts` around lines 1403 - 1573, Add a
compile-time regression check that imports the default SSO/localization resource
and asserts it still satisfies the configureSSO.configureStep shape: create a
TypeScript-only test (no runtime assertions) that imports the type for
configureSSO.configureStep and the default localization object and then do a
type-level assertion (e.g., const _check: typeof
defaultLocalization.configureSSO.configureStep = {} as typeof
configureSSO.configureStep or using the TS 4.9 `satisfies` operator) so the
build fails if any keys are missing/renamed; ensure the test references
configureSSO.configureStep and the default SSO localization export and is added
to the test suite/CI.

🤖 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.

Nitpick comments:
In `@packages/shared/src/types/localization.ts`:
- Around line 1403-1573: Add a compile-time regression check that imports the
default SSO/localization resource and asserts it still satisfies the
configureSSO.configureStep shape: create a TypeScript-only test (no runtime
assertions) that imports the type for configureSSO.configureStep and the default
localization object and then do a type-level assertion (e.g., const _check:
typeof defaultLocalization.configureSSO.configureStep = {} as typeof
configureSSO.configureStep or using the TS 4.9 `satisfies` operator) so the
build fails if any keys are missing/renamed; ensure the test references
configureSSO.configureStep and the default SSO localization export and is added
to the test suite/CI.

---

ℹ️ Review info

⚙️ Run configuration

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

Review profile: CHILL

Plan: Pro

Run ID: 23bb4169-5d71-4bc6-bc43-572d98d5cf04

📥 Commits

Reviewing files that changed from the base of the PR and between df44a2a and c43e632.

📒 Files selected for processing (11)

• packages/localizations/src/en-US.ts
• packages/shared/src/types/localization.ts
• packages/ui/src/components/ConfigureSSO/elements/Wizard/InnerStepCounter.tsx
• packages/ui/src/components/ConfigureSSO/steps/ConfigureStep.tsx
• packages/ui/src/components/ConfigureSSO/steps/ConfigureStep/index.tsx
• packages/ui/src/components/ConfigureSSO/steps/ConfigureStep/saml/SamlCustomConfigureSteps.tsx
• packages/ui/src/components/ConfigureSSO/steps/ConfigureStep/saml/SamlOktaConfigureSteps.tsx
• packages/ui/src/components/ConfigureSSO/steps/ConfigureStep/saml/shared/AttributeMappingTable.tsx
• packages/ui/src/components/ConfigureSSO/steps/ConfigureStep/saml/shared/IdentityProviderMetadataForm.tsx
• packages/ui/src/components/ConfigureSSO/steps/VerifyDomainStep.tsx
• packages/ui/src/components/ConfigureSSO/steps/configureStepTranslations.ts

💤 Files with no reviewable changes (2)

• packages/ui/src/components/ConfigureSSO/steps/configureStepTranslations.ts
• packages/ui/src/components/ConfigureSSO/steps/ConfigureStep.tsx

✅ Files skipped from review due to trivial changes (1)

• packages/ui/src/components/ConfigureSSO/elements/Wizard/InnerStepCounter.tsx

🚧 Files skipped from review as they are similar to previous changes (7)

• packages/ui/src/components/ConfigureSSO/steps/VerifyDomainStep.tsx
• packages/ui/src/components/ConfigureSSO/steps/ConfigureStep/index.tsx
• packages/ui/src/components/ConfigureSSO/steps/ConfigureStep/saml/SamlCustomConfigureSteps.tsx
• packages/ui/src/components/ConfigureSSO/steps/ConfigureStep/saml/shared/AttributeMappingTable.tsx
• packages/ui/src/components/ConfigureSSO/steps/ConfigureStep/saml/SamlOktaConfigureSteps.tsx
• packages/ui/src/components/ConfigureSSO/steps/ConfigureStep/saml/shared/IdentityProviderMetadataForm.tsx
• packages/localizations/src/en-US.ts

[github-actions]

API Changes Report

Generated by snapi on 2026-05-28T14:50:45.228Z

Summary

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

Warning
1 breaking change(s) detected - Major version bump required

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

---

@clerk/shared

Current version: 4.14.0
Recommended bump: MAJOR → 5.0.0

Subpath ./types

🔴 Breaking Changes (1)

Changed: __internal_LocalizationResource

Diff (before: 1712 lines, after: 1680 lines). Click to expand.

// ... 1307 unchanged lines elided ...
        };
      };
      configureStep: {
-       attributeMapping: {
-         title: LocalizationValue;
-         paragraph: LocalizationValue;
-         columns: {
-           attribute: LocalizationValue;
-           claimName: LocalizationValue;
-           claimValue: LocalizationValue;
-         };
-         badges: {
-           required: LocalizationValue;
-           optional: LocalizationValue;
-         };
-         rows: {
-           email: {
-             attribute: LocalizationValue;
-             claim: LocalizationValue;
-           };
-           firstName: {
-             attribute: LocalizationValue;
-             claim: LocalizationValue;
-           };
-           lastName: {
-             attribute: LocalizationValue;
-             claim: LocalizationValue;
-           };
-         };
-       };
-       samlOkta: {
-         headerTitle: LocalizationValue;
-         attributeMapping: {
// ... 157 more lines elided ...
-         metadataUrl: {
-           headerSubtitle: LocalizationValue;
-           label: LocalizationValue;
-           placeholder: LocalizationValue;
-           description: LocalizationValue;
-         };
-         modes: {
-           ariaLabel: LocalizationValue;
-           metadataUrl: LocalizationValue;
-           manual: LocalizationValue;
-         };
-         submitSamlConfig: {
-           title: LocalizationValue;
-         };
-         manual: {
-           description: LocalizationValue;
-           signOnUrl: {
-             label: LocalizationValue;
-             placeholder: LocalizationValue;
-           };
-           issuer: {
-             label: LocalizationValue;
-             placeholder: LocalizationValue;
-           };
-           signingCertificate: {
-             label: LocalizationValue;
-             uploadFile: LocalizationValue;
-             replaceFile: LocalizationValue;
-             removeFile: LocalizationValue;
-             fileUploaded: LocalizationValue;
+       attributeMappingTable: {
+         badges: {
+           required: LocalizationValue;
+           optional: LocalizationValue;
+         };
+       };
+       samlOkta: {
+         mainHeaderTitle: LocalizationValue;
+         createAppStep: {
+           headerSubtitle: LocalizationValue;
+           createAppInstructions: {
+             title: LocalizationValue;
+             step1: LocalizationValue;
+             step2: LocalizationValue;
+             step3: LocalizationValue;
+             step4: LocalizationValue;
+             step5: LocalizationValue;
+           };
+           serviceProviderInstructions: {
+             title: LocalizationValue;
+             paragraph1: LocalizationValue;
+             paragraph2: LocalizationValue;
+             serviceProviderFields: {
+               acsUrl: {
+                 label: LocalizationValue;
+               };
+               spEntityId: {
+                 label: LocalizationValue;
+               };
+             };
// ... 125 more lines elided ...
+         identityProviderMetadataStep: {
+           headerSubtitle: LocalizationValue;
+           modes: {
+             title: LocalizationValue;
+             ariaLabel: LocalizationValue;
+             metadataUrl: LocalizationValue;
+             manual: LocalizationValue;
+           };
+           metadataUrl: {
+             label: LocalizationValue;
+             placeholder: LocalizationValue;
+             description: LocalizationValue;
+           };
+           manual: {
+             description: LocalizationValue;
+             signOnUrl: {
+               label: LocalizationValue;
+               placeholder: LocalizationValue;
+             };
+             issuer: {
+               label: LocalizationValue;
+               placeholder: LocalizationValue;
+             };
+             signingCertificate: {
+               label: LocalizationValue;
+               uploadFile: LocalizationValue;
+               replaceFile: LocalizationValue;
+               removeFile: LocalizationValue;
+               fileUploaded: LocalizationValue;
+             };
            };
          };
        };
// ... 182 unchanged lines elided ...

Static analyzer: Breaking change in type alias __internal_LocalizationResource: Type changed: {locale:string;maintenanceMode:LocalizationValue;roles:{[r:string]:LocalizationValue;};socialButtonsBlockButton:Localiz… → {locale:string;maintenanceMode:LocalizationValue;roles:{[r:string]:LocalizationValue;};socialButtonsBlockButton:Localiz…

🤖 AI review (confirmed) (85%): The configureStep subtree within __internal_LocalizationResource was significantly restructured: the baseline had flat properties like attributeMapping, samlOkta.headerTitle, samlOkta.attributeMapping, samlOkta.spFields, samlOkta.createApp, etc., while the current version reorganized them into step-based sub-objects (attributeMappingTable, samlOkta.mainHeaderTitle, samlOkta.createAppStep, samlOkta.attributeMappingStep, samlOkta.assignUsersStep, samlOkta.identityProviderMetadataStep, and similarly for samlCustom). Consumers providing custom localization objects implementing this type would fail to compile against the new shape.

Migration: Update any custom localization objects that implement __internal_LocalizationResource.configureSSO.configureStep to use the new step-based structure (e.g., samlOkta.createAppStep, samlOkta.attributeMappingStep, samlOkta.identityProviderMetadataStep) instead of the old flat structure.

---

Report generated by snapi