feat(expo): add native component theming via Expo config plugin#8243
feat(expo): add native component theming via Expo config plugin#8243chriscanin wants to merge 11 commits intomainfrom
Conversation
Adds support for customizing native Clerk UI components (sign-in, sign-up,
user profile) on both iOS and Android via a JSON theme configuration file
referenced in the Expo plugin config:
["@clerk/expo", { "theme": "./clerk-theme.json" }]
The JSON schema supports:
- colors: 15 semantic color tokens (primary, background, danger, etc.)
- darkColors: dark mode color overrides (iOS uses @Environment colorScheme,
Android uses ClerkTheme.darkColors)
- fonts: fontFamily string or per-style overrides (iOS only)
- design: borderRadius
Plugin changes:
- Reads and validates the JSON at prebuild time
- iOS: Embeds theme in Info.plist; removes UIUserInterfaceStyle when
darkColors is present to enable system dark mode
- Android: Copies JSON to app assets directory
Native changes:
- iOS: Parses theme from Info.plist, builds light/dark ClerkTheme objects,
applies via .environment(\.clerkTheme) with colorScheme switching
- Android: Parses theme from assets JSON, sets Clerk.customTheme
- Both: AuthView now uses Clerk.customTheme instead of null
🦋 Changeset detectedLatest commit: 257de36 The changes in this PR will be included in the next version bump. This PR includes changesets to release 1 package
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 |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
…erkDesign signature Two fixes needed to make the Android theme actually take effect: 1. Call loadThemeFromAssets() AFTER Clerk.initialize() instead of before. Clerk.initialize() accepts a `theme` parameter that defaults to null and assigns it to Clerk.customTheme on every call, which was wiping out the theme we just loaded. 2. Use the real ClerkDesign(borderRadius: Dp) constructor signature. The previous code passed nonexistent fontFamily and nullable borderRadius parameters that don't compile against clerk-android-ui.
|
Note Reviews pausedIt 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 Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughAdds native theming support for Clerk in the Expo integration. Introduces an Expo config plugin Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes 🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@packages/expo/app.plugin.js`:
- Line 621: HEX_COLOR_REGEX currently allows 3-character hex colors but iOS
colorFromHex only supports 6- and 8-character forms, causing valid-looking
inputs to return nil; update HEX_COLOR_REGEX to remove the 3-char alternative so
it only matches 6- or 8-digit hex (e.g., change
/^#([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$/ to a pattern that omits the
{3} branch), and run/update any tests or callers that assume 3-char acceptance;
alternatively, if you prefer to keep 3-char support, implement expansion logic
in the native colorFromHex parser to expand 3-char shorthand to 6-char before
parsing.
🪄 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), Organization UI (inherited)
Review profile: CHILL
Plan: Pro
Run ID: 4526911d-c482-4634-a181-3952e94714b2
📒 Files selected for processing (5)
packages/expo/android/src/main/java/expo/modules/clerk/ClerkAuthActivity.ktpackages/expo/android/src/main/java/expo/modules/clerk/ClerkAuthExpoView.ktpackages/expo/android/src/main/java/expo/modules/clerk/ClerkExpoModule.ktpackages/expo/app.plugin.jspackages/expo/ios/ClerkViewFactory.swift
@clerk/agent-toolkit
@clerk/astro
@clerk/backend
@clerk/chrome-extension
@clerk/clerk-js
@clerk/dev-cli
@clerk/expo
@clerk/expo-passkeys
@clerk/express
@clerk/fastify
@clerk/hono
@clerk/localizations
@clerk/nextjs
@clerk/nuxt
@clerk/react
@clerk/react-router
@clerk/shared
@clerk/tanstack-react-start
@clerk/testing
@clerk/ui
@clerk/upgrade
@clerk/vue
commit: |
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b5af733345
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
packages/expo/app.plugin.js
Outdated
| 'shadow', | ||
| ]; | ||
|
|
||
| const HEX_COLOR_REGEX = /^#([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$/; |
There was a problem hiding this comment.
Disallow 3-digit hex colors in theme validation
The plugin accepts #RGB values via HEX_COLOR_REGEX, but both native parsers only handle 6- or 8-digit hex (parseHexColor on Android and colorFromHex on iOS branch only on lengths 6/8). That means a theme like {"colors":{"primary":"#fff"}} passes prebuild validation and is then silently ignored at runtime, so users think their theme is applied when it is not.
Useful? React with 👍 / 👎.
| return try { | ||
| when (cleaned.length) { | ||
| 6 -> Color(android.graphics.Color.parseColor("#FF$cleaned")) | ||
| 8 -> Color(android.graphics.Color.parseColor("#$cleaned")) |
There was a problem hiding this comment.
Normalize 8-digit hex ordering before Android parseColor
The Android parser forwards 8-digit values directly to android.graphics.Color.parseColor, which interprets them as #AARRGGBB, while iOS parses 8-digit values as RRGGBBAA in colorFromHex. As a result, the same darkColors/colors token can render with different RGB/alpha on each platform, so cross-platform theming is incorrect whenever 8-digit hex values are used.
Useful? React with 👍 / 👎.
…igit hex ordering - Remove 3-digit hex (#RGB) from the prebuild validation regex. Both native parsers only handle 6- or 8-digit hex, so 3-digit values would pass validation but be silently ignored at runtime. - Convert RRGGBBAA to AARRGGBB on Android before passing to parseColor. iOS already parses 8-digit hex as RRGGBBAA, so without this conversion the same color token could render differently on each platform.
packages/expo/app.plugin.js
Outdated
| if (themeJson.darkColors) { | ||
| delete modConfig.modResults.UIUserInterfaceStyle; | ||
| console.log('✅ Removed UIUserInterfaceStyle to enable system dark mode'); | ||
| } |
There was a problem hiding this comment.
Something codex's local review spotted on this:
darkColors changes the whole app's appearance policy
When darkColors is present, this deletes UIUserInterfaceStyle from Info.plist. That is an app-wide setting, not a Clerk-only one, so any app intentionally pinned to Light or Dark will silently switch back to system-controlled appearance just to theme Clerk screens.
There was a problem hiding this comment.
Oh hmmmm I didnt consider this when doing the dark mode / light mode switch. I will look into solutions. Good callout.
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@packages/expo/app.plugin.js`:
- Around line 623-648: validateThemeJson currently allows non-object shapes for
theme.colors, theme.darkColors, and theme.design because validateColors returns
early for non-objects; change the validation to be strict: in validateColors
throw an Error when colors is present but not an object (use typeof === 'object'
&& colors !== null && !Array.isArray(colors)), and for theme.design require it
to be an object when present (throw if design is not an object or is an
array/null); keep existing checks for VALID_COLOR_KEYS and HEX_COLOR_REGEX and
the design.fontFamily/design.borderRadius type checks, but ensure the initial
presence checks for theme.colors, theme.darkColors, and theme.design validate
object shape and error out instead of silently returning.
🪄 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), Organization UI (inherited)
Review profile: CHILL
Plan: Pro
Run ID: 493cfb37-0ed2-4699-940b-50852d4c2e76
📒 Files selected for processing (2)
packages/expo/android/src/main/java/expo/modules/clerk/ClerkExpoModule.ktpackages/expo/app.plugin.js
🚧 Files skipped from review as they are similar to previous changes (1)
- packages/expo/android/src/main/java/expo/modules/clerk/ClerkExpoModule.kt
The plugin was deleting UIUserInterfaceStyle from Info.plist whenever the theme JSON included darkColors, overriding the developer's app-wide userInterfaceStyle setting from app.json. This broke apps that intentionally pin to light or dark mode. The plugin now only embeds the theme data. Dark mode switching is controlled by the developer via Expo's existing userInterfaceStyle config.
There was a problem hiding this comment.
🧹 Nitpick comments (1)
packages/expo/app.plugin.js (1)
650-692: Consider adding tests for the theming plugin.The
withClerkThemefunction andvalidateThemeJsonhelper introduce non-trivial validation and file-writing logic. Unit tests covering valid/invalid theme JSON inputs and the expected outputs (Info.plist mutation, assets file creation) would help prevent regressions.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/expo/app.plugin.js` around lines 650 - 692, Add unit tests for withClerkTheme and validateThemeJson: write Jest tests that (1) mock fs to simulate missing theme file and assert withClerkTheme returns unchanged config and logs a warning, (2) mock fs.readFileSync to return invalid JSON and assert withClerkTheme throws a parse error, (3) provide a valid theme JSON and assert validateThemeJson accepts it, withInfoPlist is invoked and the modResults.ClerkTheme equals the parsed object, and (4) for Android, mock fs.mkdirSync and fs.writeFileSync and assert withDangerousMod writes clerk_theme.json to the computed assetsDir with JSON.stringify(themeJson, null, 2) + '\n'; use jest mocks for fs and spy on console/logging where needed to verify messages.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@packages/expo/app.plugin.js`:
- Around line 650-692: Add unit tests for withClerkTheme and validateThemeJson:
write Jest tests that (1) mock fs to simulate missing theme file and assert
withClerkTheme returns unchanged config and logs a warning, (2) mock
fs.readFileSync to return invalid JSON and assert withClerkTheme throws a parse
error, (3) provide a valid theme JSON and assert validateThemeJson accepts it,
withInfoPlist is invoked and the modResults.ClerkTheme equals the parsed object,
and (4) for Android, mock fs.mkdirSync and fs.writeFileSync and assert
withDangerousMod writes clerk_theme.json to the computed assetsDir with
JSON.stringify(themeJson, null, 2) + '\n'; use jest mocks for fs and spy on
console/logging where needed to verify messages.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository YAML (base), Organization UI (inherited)
Review profile: CHILL
Plan: Pro
Run ID: 064f9f8d-947b-431b-962b-8755f9d83844
📒 Files selected for processing (2)
.changeset/expo-native-component-theming.mdpackages/expo/app.plugin.js
✅ Files skipped from review due to trivial changes (1)
- .changeset/expo-native-component-theming.md
- Use ClerkTheme init with non-optional params (nil-coalesce to .default) - Reorder arguments: fonts before design to match ClerkTheme.init signature - Mark register() and loadThemes() as @mainactor (ClerkTheme is @mainactor) - Construct Colors via init instead of mutating after creation, so derived tokens (primaryPressed, border opacity, etc.) are calculated correctly
- validateThemeJson now throws when colors, darkColors, or design is present but not a plain object (string, array, number all rejected). - null values are treated as absent (not an error). - Add vitest tests covering valid themes, shape validation, hex format rejection (3-digit, no hash), unknown key warnings, and design field types.
Add isPlainObject guard at the top of validateThemeJson to reject null, arrays, and non-object values that would crash or silently pass validation. Remove stale JSDoc comment about UIUserInterfaceStyle removal which no longer matches the implementation. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
manovotny
left a comment
There was a problem hiding this comment.
Nice work! I wouldn't normally peek into the JS PR, but I was here reviewing the docs for this anyway.
A few things I pushed direct fixes for (578ac31):
- Removed stale JSDoc comment on
withClerkThemethat still referenced removingUIUserInterfaceStylewhendarkColorsis present. That behavior was removed in 3c703ef and the changeset correctly says otherwise. - Added top-level
isPlainObject(theme)validation invalidateThemeJson. Without it, a theme JSON file containingnullcrashes with a TypeError, and non-object values like"hello"silently pass validation. Added test cases fornull,string, andarray.
Let me know if those are incorrect and I can fix/adjust or revert.
I left comment for the other things that caught my eye.
Small note on the PR description: it lists fonts as a top-level schema key, but the actual schema (and the changeset) puts fontFamily under design. Might be worth updating the description to match: design.fontFamily and design.borderRadius.
|
|
||
| // The plugin is plain CJS — load the validation function by evaluating | ||
| // just the relevant pieces. We re-declare the constants and function | ||
| // exactly as they appear in app.plugin.js so the test stays in sync. |
There was a problem hiding this comment.
This test copies validateThemeJson, VALID_COLOR_KEYS, HEX_COLOR_REGEX, and isPlainObject from app.plugin.js instead of importing the real code. If the plugin's validation changes (eg. a new color key is added, the regex is tightened), these tests will still pass against the stale copy.
Could the validator be exported from app.plugin.js (eg. module.exports.validateThemeJson = validateThemeJson) so the test require()s the real implementation? That way drift between the two isn't possible.
Understand if there's an Expo plugin packaging constraint that prevents this. Just want to flag the possible maintenance risk.
| private static var clerkConfigured = false | ||
|
|
||
| /// Parsed light and dark themes from Info.plist "ClerkTheme" dictionary. | ||
| var lightTheme: ClerkTheme? |
There was a problem hiding this comment.
The template file at ios/templates/ClerkViewFactory.swift hasn't been updated with the theme changes.
The config plugin copies from this file (ios/ClerkViewFactory.swift), so theming works, but the template is now significantly diverged (no lightTheme/darkTheme properties, no loadThemes(), no @MainActor register(), no wrapper view theme params).
Is the template still needed? The plugin references ios/ClerkViewFactory.swift directly (line 266 of app.plugin.js). If the template serves another purpose, maybe it should be synced.
| Clerk.initialize(reactApplicationContext, pubKey) | ||
| // Must be set AFTER Clerk.initialize() because initialize() | ||
| // resets customTheme to its `theme` parameter (default null). | ||
| loadThemeFromAssets() |
There was a problem hiding this comment.
loadThemeFromAssets() is only called here in ClerkExpoModule. But ClerkViewFactory.configure() and ClerkUserProfileActivity.onCreate() also call Clerk.initialize() without loading the theme.
If Clerk is ever initialized through those paths first, Clerk.customTheme stays null and theming silently doesn't apply.
In normal Expo flow ClerkExpoModule initializes first, so this probably never triggers, but would it be worth either:
- Moving
loadThemeFromAssets()into a shared companion called after everyClerk.initialize(), or - Adding a comment documenting that
ClerkExpoModuleis the only supported init path and theme loading is intentionally centralized here?
| }; | ||
|
|
||
| /** | ||
| * Apply a custom theme to Clerk native components (iOS + Android). |
There was a problem hiding this comment.
The plugin writes ClerkTheme to Info.plist, and clerk_theme.json to Android assets, but never cleans them up.
If a project had a theme and later removes the theme prop, incremental prebuilds (expo prebuild without --clean) keep using the old embedded theme.
Maybe we could look into:
- Actively removing
ClerkThemefrom Info.plist and deletingclerk_theme.jsonwhenthemeis absent, or - Documenting that
expo prebuild --cleanis required after removingtheme
There was a problem hiding this comment.
Hi @manovotny , good callout. I think that removing the theme when doing a prebuild if the theme is not present would be a good option. If the theme is removed, and is not present in the plugin, I can add a step that removes these themes from the json and plist and sets things back to default.
Documenting the expo prebuild --clean as a necessary step after removal may be a bit confusing, I think the automatic removal on prebuild would be best as part of the plugin. And the --clean as a backup.
- Export validation internals via _testing so tests import the real implementation instead of a stale copy. - Add comment documenting that theme loading is centralized in ClerkExpoModule (other init paths guard with !isInitialized).
The plugin copies from ios/ClerkViewFactory.swift directly (app.plugin.js line 266). The template at ios/templates/ was from an earlier iteration and is no longer referenced by anything.
Adds support for customizing native Clerk UI components (sign-in, sign-up, user profile) on both iOS and Android via a JSON theme configuration file referenced in the Expo plugin config:
["@clerk/expo", { "theme": "./clerk-theme.json" }]
The JSON schema supports:
Plugin changes:
The plugin does not modify
UIUserInterfaceStyle. Dark mode switching is controlled by the developer via Expo'suserInterfaceStylesetting inapp.json.Native changes:
Checklist
pnpm testruns as expected.pnpm buildruns as expected.Type of change