-
Notifications
You must be signed in to change notification settings - Fork 426
feat(ui): Add warning for structural CSS customization without version pinning #7590
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Conversation
🦋 Changeset detectedLatest commit: bd8aa87 The changes in this PR will be included in the next version bump. This PR includes changesets to release 20 packages
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.
|
6a73890 to
bb6f356
Compare
|
!snapshot |
|
Hey @brkalow - the snapshot version command generated the following package versions:
Tip: Use the snippet copy button below to quickly install the required packages. npm i @clerk/agent-toolkit@0.2.9-snapshot.v20260114034743 --save-exact
npm i @clerk/astro@3.0.0-snapshot.v20260114034743 --save-exact
npm i @clerk/backend@3.0.0-snapshot.v20260114034743 --save-exact
npm i @clerk/chrome-extension@3.0.0-snapshot.v20260114034743 --save-exact
npm i @clerk/clerk-js@6.0.0-snapshot.v20260114034743 --save-exact
npm i @clerk/dev-cli@1.0.0-snapshot.v20260114034743 --save-exact
npm i @clerk/expo@3.0.0-snapshot.v20260114034743 --save-exact
npm i @clerk/expo-passkeys@1.0.0-snapshot.v20260114034743 --save-exact
npm i @clerk/express@2.0.0-snapshot.v20260114034743 --save-exact
npm i @clerk/fastify@2.6.9-snapshot.v20260114034743 --save-exact
npm i @clerk/localizations@4.0.0-snapshot.v20260114034743 --save-exact
npm i @clerk/msw@0.0.1-snapshot.v20260114034743 --save-exact
npm i @clerk/nextjs@7.0.0-snapshot.v20260114034743 --save-exact
npm i @clerk/nuxt@2.0.0-snapshot.v20260114034743 --save-exact
npm i @clerk/react@6.0.0-snapshot.v20260114034743 --save-exact
npm i @clerk/react-router@3.0.0-snapshot.v20260114034743 --save-exact
npm i @clerk/shared@4.0.0-snapshot.v20260114034743 --save-exact
npm i @clerk/tanstack-react-start@1.0.0-snapshot.v20260114034743 --save-exact
npm i @clerk/testing@2.0.0-snapshot.v20260114034743 --save-exact
npm i @clerk/ui@1.0.0-snapshot.v20260114034743 --save-exact
npm i @clerk/upgrade@2.0.0-snapshot.v20260114034743 --save-exact
npm i @clerk/vue@2.0.0-snapshot.v20260114034743 --save-exact |
bb6f356 to
4d6d160
Compare
4d6d160 to
00e9b52
Compare
…n pinning Add a development-mode console warning when users customize Clerk components using structural CSS patterns that may rely on internal DOM structure: - Detects appearance.elements with combinators (>, +, ~), positional pseudo-selectors (:nth-child, etc.), :has(), or multiple .cl- classes - Detects external CSS stylesheets targeting .cl- classes structurally - Only runs in development mode, deferred via setTimeout to avoid blocking - Uses hasChecked guard to prevent rescanning on component remount The warning guides users to pin their @clerk/ui version to avoid breakages when internal DOM structure changes between versions. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
00e9b52 to
cd7e426
Compare
|
!snapshot |
|
Hey @brkalow - the snapshot version command generated the following package versions:
Tip: Use the snippet copy button below to quickly install the required packages. npm i @clerk/agent-toolkit@0.2.9-snapshot.v20260114212940 --save-exact
npm i @clerk/astro@3.0.0-snapshot.v20260114212940 --save-exact
npm i @clerk/backend@3.0.0-snapshot.v20260114212940 --save-exact
npm i @clerk/chrome-extension@3.0.0-snapshot.v20260114212940 --save-exact
npm i @clerk/clerk-js@6.0.0-snapshot.v20260114212940 --save-exact
npm i @clerk/dev-cli@1.0.0-snapshot.v20260114212940 --save-exact
npm i @clerk/expo@3.0.0-snapshot.v20260114212940 --save-exact
npm i @clerk/expo-passkeys@1.0.0-snapshot.v20260114212940 --save-exact
npm i @clerk/express@2.0.0-snapshot.v20260114212940 --save-exact
npm i @clerk/fastify@2.6.9-snapshot.v20260114212940 --save-exact
npm i @clerk/localizations@4.0.0-snapshot.v20260114212940 --save-exact
npm i @clerk/msw@0.0.1-snapshot.v20260114212940 --save-exact
npm i @clerk/nextjs@7.0.0-snapshot.v20260114212940 --save-exact
npm i @clerk/nuxt@2.0.0-snapshot.v20260114212940 --save-exact
npm i @clerk/react@6.0.0-snapshot.v20260114212940 --save-exact
npm i @clerk/react-router@3.0.0-snapshot.v20260114212940 --save-exact
npm i @clerk/shared@4.0.0-snapshot.v20260114212940 --save-exact
npm i @clerk/tanstack-react-start@1.0.0-snapshot.v20260114212940 --save-exact
npm i @clerk/testing@2.0.0-snapshot.v20260114212940 --save-exact
npm i @clerk/ui@1.0.0-snapshot.v20260114212940 --save-exact
npm i @clerk/upgrade@2.0.0-snapshot.v20260114212940 --save-exact
npm i @clerk/vue@2.0.0-snapshot.v20260114212940 --save-exact |
…pinning options.clerkUiCtor is always set when loading from CDN (via window.__internal_ClerkUiCtor), so the warning would never show. The correct check is options.ui, which is only set when the user explicitly imports @clerk/ui and passes it to ClerkProvider. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
|
!snapshot |
|
Hey @brkalow - the snapshot version command generated the following package versions:
Tip: Use the snippet copy button below to quickly install the required packages. npm i @clerk/agent-toolkit@0.2.9-snapshot.v20260115035526 --save-exact
npm i @clerk/astro@3.0.0-snapshot.v20260115035526 --save-exact
npm i @clerk/backend@3.0.0-snapshot.v20260115035526 --save-exact
npm i @clerk/chrome-extension@3.0.0-snapshot.v20260115035526 --save-exact
npm i @clerk/clerk-js@6.0.0-snapshot.v20260115035526 --save-exact
npm i @clerk/dev-cli@1.0.0-snapshot.v20260115035526 --save-exact
npm i @clerk/expo@3.0.0-snapshot.v20260115035526 --save-exact
npm i @clerk/expo-passkeys@1.0.0-snapshot.v20260115035526 --save-exact
npm i @clerk/express@2.0.0-snapshot.v20260115035526 --save-exact
npm i @clerk/fastify@2.6.9-snapshot.v20260115035526 --save-exact
npm i @clerk/localizations@4.0.0-snapshot.v20260115035526 --save-exact
npm i @clerk/msw@0.0.1-snapshot.v20260115035526 --save-exact
npm i @clerk/nextjs@7.0.0-snapshot.v20260115035526 --save-exact
npm i @clerk/nuxt@2.0.0-snapshot.v20260115035526 --save-exact
npm i @clerk/react@6.0.0-snapshot.v20260115035526 --save-exact
npm i @clerk/react-router@3.0.0-snapshot.v20260115035526 --save-exact
npm i @clerk/shared@4.0.0-snapshot.v20260115035526 --save-exact
npm i @clerk/tanstack-react-start@1.0.0-snapshot.v20260115035526 --save-exact
npm i @clerk/testing@2.0.0-snapshot.v20260115035526 --save-exact
npm i @clerk/ui@1.0.0-snapshot.v20260115035526 --save-exact
npm i @clerk/upgrade@2.0.0-snapshot.v20260115035526 --save-exact
npm i @clerk/vue@2.0.0-snapshot.v20260115035526 --save-exact |
|
!snapshot |
|
Hey @brkalow - the snapshot version command generated the following package versions:
Tip: Use the snippet copy button below to quickly install the required packages. npm i @clerk/agent-toolkit@0.2.9-snapshot.v20260120164554 --save-exact
npm i @clerk/astro@3.0.0-snapshot.v20260120164554 --save-exact
npm i @clerk/backend@3.0.0-snapshot.v20260120164554 --save-exact
npm i @clerk/chrome-extension@3.0.0-snapshot.v20260120164554 --save-exact
npm i @clerk/clerk-js@6.0.0-snapshot.v20260120164554 --save-exact
npm i @clerk/dev-cli@1.0.0-snapshot.v20260120164554 --save-exact
npm i @clerk/expo@3.0.0-snapshot.v20260120164554 --save-exact
npm i @clerk/expo-passkeys@1.0.0-snapshot.v20260120164554 --save-exact
npm i @clerk/express@2.0.0-snapshot.v20260120164554 --save-exact
npm i @clerk/fastify@2.6.9-snapshot.v20260120164554 --save-exact
npm i @clerk/localizations@4.0.0-snapshot.v20260120164554 --save-exact
npm i @clerk/msw@0.0.1-snapshot.v20260120164554 --save-exact
npm i @clerk/nextjs@7.0.0-snapshot.v20260120164554 --save-exact
npm i @clerk/nuxt@2.0.0-snapshot.v20260120164554 --save-exact
npm i @clerk/react@6.0.0-snapshot.v20260120164554 --save-exact
npm i @clerk/react-router@3.0.0-snapshot.v20260120164554 --save-exact
npm i @clerk/shared@4.0.0-snapshot.v20260120164554 --save-exact
npm i @clerk/tanstack-react-start@1.0.0-snapshot.v20260120164554 --save-exact
npm i @clerk/testing@2.0.0-snapshot.v20260120164554 --save-exact
npm i @clerk/ui@1.0.0-snapshot.v20260120164554 --save-exact
npm i @clerk/upgrade@2.0.0-snapshot.v20260120164554 --save-exact
npm i @clerk/vue@2.0.0-snapshot.v20260120164554 --save-exact |
…ion-without-pinning # Conflicts: # packages/ui/vitest.config.mts
packages/ui/src/Components.tsx
Outdated
| // Defer warning check to avoid blocking component mount | ||
| // Only check in development mode (based on publishable key, not NODE_ENV) | ||
| if (getClerk().instanceType === 'development') { | ||
| setTimeout(() => warnAboutCustomizationWithoutPinning(options), 0); |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
probably prefer requestIdleCallback instead, this just waits for microtasks
📝 WalkthroughWalkthroughAdds a development-mode warning when projects customize Clerk components using structural CSS patterns without pinning the clerk/ui version. Introduces a changeset, new exported regex constants for detecting structural selectors, an exported detectStructuralClerkCss() scanner for document stylesheets, and an exported warnAboutCustomizationWithoutPinning(options?) utility. Integrates a deferred call to the warning from component mount in development builds. Adds comprehensive unit tests for stylesheet detection and the warning logic. No existing public API signatures were removed. 🚥 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. Comment |
- Add [CLERK_W001] error code for searchability - Show specific patterns found (e.g., elements.card "& > div", CSS ".cl-card > div") - Truncate to first 3 patterns with "(+N more)" indicator - Use requestIdleCallback for non-blocking warning check Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@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/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: |
The warning is only used in the UI package, so it doesn't need to live in shared/warnings.ts. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Summary
appearance.elements(CSS-in-JS) and external stylesheets targeting.cl-classes@clerk/uiversion to avoid breakagesDetection Criteria
Structural patterns that trigger the warning:
>,+,~) with.cl-classes.cl-classes:nth-child,:first-child, etc.):has()selector.cl-classes in a single selector.cl-class (e.g.,div.cl-button)Safe patterns that do NOT trigger the warning:
.cl-class styling (e.g.,.cl-button { color: red }):hover,:focus::before,::afterappearance.elementsPerformance Considerations
setTimeoutto avoid blocking component mounthasCheckedguard to prevent rescanning on remountappearance.elements(skips stylesheet scan)Test plan
detectStructuralClerkCss()- 16 testswarnAboutCustomizationWithoutPinning()- 18 tests🤖 Generated with Claude Code
Summary by CodeRabbit
New Features
Tests
Chores
✏️ Tip: You can customize this high-level summary in your review settings.