fix: exclude internal Clerk classes from structural CSS detection

[brkalow]

Description

Fixes false positives in the structural CSS warning where Clerk's own internal classes (generated by Emotion with .cl-internal-* selectors) were triggering warnings on fresh installs without any custom CSS.

Only user-authored customization targeting Clerk's public APIs should trigger the warning. Internal classes are implementation details and shouldn't be flagged. If users explicitly reference .cl-internal-* in their appearance.elements configuration, that's still warned about since it's a stability risk.

Type of change

• 🐛 Bug fix

Summary by CodeRabbit

• Tests

  • Added comprehensive test coverage to verify that internal CSS class patterns (including those in nested and combined selectors) are correctly handled and excluded from analysis.

• Bug Fixes

  • Enhanced stylesheet detection mechanism to properly filter out internal Clerk-generated classes, reducing false positive customization warnings.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Mar 20, 2026 6:20pm

[changeset-bot]

⚠️ No Changeset found

Latest commit: 73c2f22

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/agent-toolkit

npm i https://pkg.pr.new/@clerk/agent-toolkit@8142

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/dev-cli

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 73c2f22

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

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

Review profile: ASSERTIVE

Plan: Pro

Run ID: 5961223c-e893-4705-99ed-08966effc701

📥 Commits

Reviewing files that changed from the base of the PR and between ad782ff and 73c2f22.

📒 Files selected for processing (4)

• packages/ui/src/utils/__tests__/detectClerkStylesheetUsage.test.ts
• packages/ui/src/utils/__tests__/warnAboutCustomizationWithoutPinning.test.ts
• packages/ui/src/utils/cssPatterns.ts
• packages/ui/src/utils/detectClerkStylesheetUsage.ts

---

📝 Walkthrough

Walkthrough

The changes introduce handling for internal Clerk-generated classes (.cl-internal-* prefix). A new regex pattern CLERK_INTERNAL_CLASS_RE was added to match these internal classes. The stylesheet usage detection logic was updated to strip these internal class patterns from selectors before analyzing them. Test coverage was added to verify that selectors containing only internal classes don't trigger customization warnings, and that nested selectors with internal classes are handled correctly.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: excluding internal Clerk classes from structural CSS detection, which directly corresponds to the code modifications across all files.

_{✏️ 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.}

Tip

You can get early access to new features in CodeRabbit.

Enable the early_access setting to enable early access features such as new models, tools, and more.