/clerk-swift

Custom Flow Reference (ClerkKit)

Use this file only when flow type is custom.

Purpose

Implement native iOS auth with ClerkKit primitives while keeping flow and layout very close to ClerkKitUI AuthView by default.

Source-Driven Requirements

Use installed package source from Xcode DerivedData:

• ~/Library/Developer/Xcode/DerivedData/.../SourcePackages/checkouts/clerk-ios

Source priority rules for custom flow:

• Primary source: installed ClerkKitUI source for auth UI behavior and gating parity.
• Secondary source: installed ClerkKit source for core auth/network/config behavior.
• Fallback only: example apps (local or GitHub) when behavior is unclear from library source.

For custom flows, treat ClerkKitUI AuthView as a strict parity target for:

• step progression/sequencing
• field visibility and hidden-state rules per step
• branching between factors/strategies
• screen structure and layout composition per step
• view hierarchy and section ordering per step

Required Patterns

1. Package products

• If clerk-ios is not installed, add it using the latest available release with an up-to-next-major package requirement.
• Do not pin an exact package version unless the developer explicitly requests version pinning.
• Add ClerkKit by default.
• Add ClerkKitUI only if the developer explicitly asks for mixed prebuilt/custom composition.

2. Quickstart prerequisite audit

• Find the iOS quickstart URL in the installed clerk-ios package README, append .md, then visit and read that markdown URL.
• Build a checklist from the visited markdown quickstart and verify the current project completed all required setup.
• If required setup is missing, add it before finishing custom auth implementation.
• Always add any missing Associated Domains entries and any other capabilities required by the quickstart.
• Explicitly apply quickstart step Add associated domain capability (https://clerk.com/docs/ios/getting-started/quickstart#add-associated-domain-capability); ensure webcredentials:{YOUR_FRONTEND_API_URL} exists when missing.

3. Environment inspection + normalization

• Inspect installed ClerkKitUI source first to identify which Environment fields and semantics drive flow behavior.
• Build an agent-internal Environment field map from that source inspection.
• Make a direct HTTP call to /v1/environment only after the Environment field map is defined.
• Derive from the response using that ClerkKitUI-aligned field map (agent-internal only):
  • normalized ClerkKitUI-style capability matrix
  • required-field matrix
• Drive custom-flow implementation decisions from these matrices.
• Do not serialize or add these matrices as source artifacts in the app codebase.

4. Combined-entry default

• Keep a combined sign-in-or-sign-up entry by default.
• Do not add a local sign-in/sign-up mode switcher unless explicitly requested.

5. AuthView progression parity

• Follow ClerkKitUI AuthView progression logic for advancing/regressing steps.
• Show/hide inputs exactly according to the active step requirements instead of static form layouts.
• Keep factor/strategy branching aligned with how AuthView gates transitions.
• Keep screen layout and component structure very close to AuthView defaults unless the developer explicitly requests a different UX.
• Keep view hierarchy and section ordering close to AuthView on each step; do not redesign the information architecture unless explicitly requested.
• Break the custom flow into multiple step screens/states similar to AuthView; do not try to gather all signup/signin requirements in one view.
• If proposed custom layout materially deviates from AuthView, stop and ask for explicit developer approval before implementing.

6. Multi-file organization and separation of concerns

• Break custom auth flow into focused files/modules instead of one large screen file.
• Separate UI step views, flow/state orchestration, and Clerk/network integration responsibilities.
• Keep per-file responsibilities narrow and composable so new factors/steps can be added without rewriting a monolithic view.

7. Capability-matrix-driven implementation

• Drive custom flow behavior from normalized ClerkKitUI-style capability mapping.
• Do not rely on one-off raw environment checks.
• Apply matrix outcomes to runtime flow logic only; do not add matrix models/constants/files to the project.
• Ensure custom logic uses the same environment-field gates and interpretations that ClerkKitUI uses.

8. Required-field coverage

• Implement all required fields from required-field matrix.
• Do not ship flow with missing required fields.

9. Apple sign-in policy

• Implement Apple via native Clerk Apple path.
• If Apple capability is required for this app and missing, add it.
• Do not implement Apple through generic social-provider OAuth handling.

10. Source parity

• Follow installed ClerkKitUI and ClerkKit source patterns for sequencing, factor handling, and verification steps.
• When unsure about custom-flow implementation details, sequencing, gating, or Environment usage/semantics, stop guessing and reference installed ClerkKitUI implementation behavior.
• Resolve ambiguity by mirroring ClerkKitUI behavior unless the developer explicitly asks for a different approach.

Verification Checklist

1. Quickstart prerequisites are complete

• Quickstart link was sourced from installed clerk-ios package README, .md was appended, and the markdown page was visited/read.
• Required project setup from quickstart is present.
• Any missing quickstart-required Associated Domains/capabilities were added, not just reported.
• Quickstart Add associated domain capability step was applied, including webcredentials:{YOUR_FRONTEND_API_URL}.

2. No unrequested mode switcher

• No local toggle/segmented control/tabs for sign-in vs sign-up unless explicitly requested.

3. Environment call completed

• Installed ClerkKitUI Environment field usage was inspected before calling /v1/environment.
• Direct /v1/environment call succeeded after field-map inspection.

4. AuthView flow parity

• Step transitions follow AuthView progression rules.
• Inputs shown at each step match AuthView step-level visibility behavior.
• Step layouts and component grouping are materially close to AuthView; do not introduce major layout redesign unless explicitly requested.
• View hierarchy/section ordering remain close to AuthView across steps unless explicitly requested otherwise.
• Flow is split across multiple steps like AuthView; required data is not collected in one monolithic screen.
• When implementation ambiguity appears, final behavior matches installed ClerkKitUI rather than an inferred/custom interpretation.

5. Flow organization quality

• Custom flow code is split into multiple focused files/modules (not a single monolithic auth view file).
• UI, state/flow orchestration, and integration logic are separated with clear boundaries.

6. Matrices created and used

• Capability matrix and required-field matrix exist and drive the implementation.
• Matrix artifacts are not written into project source files.
• Environment fields used for gating/requirements match the set and semantics used by installed ClerkKitUI.

7. Required fields covered

• Required-field matrix has full coverage in custom UI.

8. Capability-map parity

• Feature availability and branching use normalized capability map.

9. Apple path correctness

• Apple flow uses native path, not generic provider OAuth path.

10. No unrequested prebuilt dependency

• ClerkKitUI is not added unless explicitly needed.