fix(ui): Improve structural CSS warning message format, warn for appearance usage on components by brkalow · Pull Request #7628 · clerk/javascript

brkalow · 2026-01-20T23:10:16Z

Description

Improve the warning message for structural CSS detection based on feedback.
Trigger detection on appearance objects passed directly to components

BEFORE

🔒 Clerk:
[CLERK_W001] Structural CSS detected

Found: 
  -
  -

May break on updates. Pin your version:
  npm install @clerk/ui && import { ui } from '@clerk/ui'
  <ClerkProvider ui={ui} />

https://clerk.com/docs/customization/versioning
(This notice only appears in development)

AFTER

Clerk: Structural CSS detected that may break on updates.

Found:
  -
  -

These selectors depend on the internal DOM structure of Clerk's components, which may change when Clerk deploys component updates.
To prevent breaking changes, install @clerk/ui and pass it to ClerkProvider:

  import { ui } from '@clerk/ui'
  <ClerkProvider ui={ui}>

Learn more: https://clerk.com/docs/reference/components/versioning
(code=structural_css_pin_clerk_ui)

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

Summary by CodeRabbit

New Features
- Development-only warnings now surface when structural CSS customizations are detected without UI pinning, including condensed, bulleted pattern listings for component-level appearance.
Tests
- Added tests for development vs production, pinned vs unpinned UI, missing provider context, idle-timing behavior, and new warning formatting.
Chores
- Minor changelog entry and bundle size thresholds adjusted.

- Clearer title and explanation - Package manager agnostic install instructions - Use (code=structural_css_pin_clerk_ui) error code format Co-Authored-By: Claude Opus 4.5 <[email protected]>

Previously, the structural CSS warning only triggered when ClerkProvider mounted. This adds checking when individual components mount with their own appearance prop (e.g., <SignIn appearance={...} />). - Add warnAboutComponentAppearance() for checking component-level appearance - Add useWarnAboutCustomizationWithoutPinning hook called from AppearanceProvider - Hook gracefully handles missing context (e.g., in tests) - Only runs in development mode Co-Authored-By: Claude Opus 4.5 <[email protected]>

changeset-bot · 2026-01-20T23:10:20Z

🦋 Changeset detected

Latest commit: fb6cb15

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

This PR includes changesets to release 0 packages

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

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 · 2026-01-20T23:10:21Z

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Feb 3, 2026 2:29pm

pkg-pr-new · 2026-01-20T23:13:41Z

Open in StackBlitz

@clerk/agent-toolkit

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

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/dev-cli

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: fb6cb15

coderabbitai · 2026-01-20T23:13:49Z

📝 Walkthrough

Walkthrough

Introduces a development-only structural CSS warning flow: adds hook useWarnAboutCustomizationWithoutPinning and calls it from the Appearance provider with appearance to run a deferred check. The hook reads Clerk and Options contexts, stabilizes appearance, defers work via requestIdleCallback with a fallback, skips in production or when contexts are absent, and cleans up on unmount. Adds warnAboutComponentAppearance(appearance, uiPinned) to collect and format up to five detected element patterns as bullet points and emit a one-time warning. Tests cover the hook and utility behavior.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately captures the two main changes: improving the structural CSS warning message format and adding appearance-level component warnings.
Docstring Coverage	✅ Passed	Docstring coverage is 83.33% which is sufficient. The required threshold is 80.00%.

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

Co-Authored-By: Claude Opus 4.5 <[email protected]>

…owser.js - ui.browser.js: 34KB -> 34.5KB - ui.legacy.browser.js: 72KB -> 73KB Co-Authored-By: Claude Opus 4.5 <[email protected]>

alexcarpenter · 2026-01-26T18:17:32Z

!snapshot

clerk-cookie · 2026-01-26T18:20:48Z

Hey @alexcarpenter - the snapshot version command generated the following package versions:

Package	Version
@clerk/agent-toolkit	0.2.9-snapshot.v20260126181919
@clerk/astro	3.0.0-snapshot.v20260126181919
@clerk/backend	3.0.0-snapshot.v20260126181919
@clerk/chrome-extension	3.0.0-snapshot.v20260126181919
@clerk/clerk-js	6.0.0-snapshot.v20260126181919
@clerk/dev-cli	1.0.0-snapshot.v20260126181919
@clerk/expo	3.0.0-snapshot.v20260126181919
@clerk/expo-passkeys	1.0.0-snapshot.v20260126181919
@clerk/express	2.0.0-snapshot.v20260126181919
@clerk/fastify	2.6.9-snapshot.v20260126181919
@clerk/localizations	4.0.0-snapshot.v20260126181919
@clerk/msw	0.0.1-snapshot.v20260126181919
@clerk/nextjs	7.0.0-snapshot.v20260126181919
@clerk/nuxt	2.0.0-snapshot.v20260126181919
@clerk/react	6.0.0-snapshot.v20260126181919
@clerk/react-router	3.0.0-snapshot.v20260126181919
@clerk/shared	4.0.0-snapshot.v20260126181919
@clerk/tanstack-react-start	1.0.0-snapshot.v20260126181919
@clerk/testing	2.0.0-snapshot.v20260126181919
@clerk/ui	1.0.0-snapshot.v20260126181919
@clerk/upgrade	2.0.0-snapshot.v20260126181919
@clerk/vue	2.0.0-snapshot.v20260126181919

Tip: Use the snippet copy button below to quickly install the required packages.
@clerk/agent-toolkit

npm i @clerk/[email protected] --save-exact

@clerk/astro

npm i @clerk/[email protected] --save-exact

@clerk/backend

npm i @clerk/[email protected] --save-exact

@clerk/chrome-extension

npm i @clerk/[email protected] --save-exact

@clerk/clerk-js

npm i @clerk/[email protected] --save-exact

@clerk/dev-cli

npm i @clerk/[email protected] --save-exact

@clerk/expo

npm i @clerk/[email protected] --save-exact

@clerk/expo-passkeys

npm i @clerk/[email protected] --save-exact

@clerk/express

npm i @clerk/[email protected] --save-exact

@clerk/fastify

npm i @clerk/[email protected] --save-exact

@clerk/localizations

npm i @clerk/[email protected] --save-exact

@clerk/msw

npm i @clerk/[email protected] --save-exact

@clerk/nextjs

npm i @clerk/[email protected] --save-exact

@clerk/nuxt

npm i @clerk/[email protected] --save-exact

@clerk/react

npm i @clerk/[email protected] --save-exact

@clerk/react-router

npm i @clerk/[email protected] --save-exact

@clerk/shared

npm i @clerk/[email protected] --save-exact

@clerk/tanstack-react-start

npm i @clerk/[email protected] --save-exact

@clerk/testing

npm i @clerk/[email protected] --save-exact

@clerk/ui

npm i @clerk/[email protected] --save-exact

@clerk/upgrade

npm i @clerk/[email protected] --save-exact

@clerk/vue

npm i @clerk/[email protected] --save-exact

alexcarpenter

outside of the perf review shared in slack, tested in dashboard and working 👍🏼

nikosdouvlis

Nice improvement to the DX here

nikosdouvlis · 2026-01-27T15:23:40Z

packages/ui/src/hooks/useWarnAboutCustomizationWithoutPinning.ts

+    });
+
+    return () => {
+      if (typeof cancelIdleCallback === 'function' && typeof handle === 'number') {


When requestIdleCallback isn't available, we fall back to setTimeout but the cleanup still calls cancelIdleCallback. Probably fine since the 0ms timeout fires immediately anyway, just wanted to flag it

…utPinning - Use useDeepEqualMemo to stabilize appearance reference, preventing effect re-runs when consumers pass inline objects - Fix cleanup function to properly handle setTimeout fallback when requestIdleCallback is unavailable (Safari < 16.4, Node) - Extract inline regexes to module-level constants to avoid repeated compilation Co-Authored-By: Claude Opus 4.5 <[email protected]>

brkalow and others added 3 commits January 20, 2026 13:49

fix(ui): Improve structural CSS warning message format

50eb8dc

- Clearer title and explanation - Package manager agnostic install instructions - Use (code=structural_css_pin_clerk_ui) error code format Co-Authored-By: Claude Opus 4.5 <[email protected]>

improve warning message

bd9d3fa

brkalow requested review from dstaley and jacekradko January 20, 2026 23:10

github-actions bot added the core-3 label Jan 20, 2026

chore: Add empty changeset

3dd0d17

Co-Authored-By: Claude Opus 4.5 <[email protected]>

vercel bot deployed to Preview January 21, 2026 05:01 View deployment

chore(ui): Bump bundlewatch limits for ui.browser.js and ui.legacy.br…

9f7563c

…owser.js - ui.browser.js: 34KB -> 34.5KB - ui.legacy.browser.js: 72KB -> 73KB Co-Authored-By: Claude Opus 4.5 <[email protected]>

vercel bot deployed to Preview January 21, 2026 17:04 View deployment

alexcarpenter approved these changes Jan 26, 2026

View reviewed changes

nikosdouvlis approved these changes Jan 27, 2026

View reviewed changes

vercel bot deployed to Preview February 2, 2026 20:39 View deployment

Merge branch 'main' into bryce/warn-customization-without-pinning-2

79fcdc3

brkalow enabled auto-merge (squash) February 2, 2026 20:47

vercel bot deployed to Preview February 2, 2026 20:47 View deployment

brkalow disabled auto-merge February 2, 2026 21:04

brkalow enabled auto-merge (squash) February 2, 2026 21:04

Merge branch 'main' into bryce/warn-customization-without-pinning-2

8418a0c

vercel bot deployed to Preview February 3, 2026 02:47 View deployment

Merge branch 'main' into bryce/warn-customization-without-pinning-2

fb6cb15

vercel bot deployed to Preview February 3, 2026 14:29 View deployment

brkalow merged commit c73aa48 into main Feb 3, 2026
38 checks passed

brkalow deleted the bryce/warn-customization-without-pinning-2 branch February 3, 2026 14:37

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix(ui): Improve structural CSS warning message format, warn for appearance usage on components#7628

fix(ui): Improve structural CSS warning message format, warn for appearance usage on components#7628
brkalow merged 9 commits intomainfrom
bryce/warn-customization-without-pinning-2

brkalow commented Jan 20, 2026 •

edited by coderabbitai bot

Loading

Uh oh!

changeset-bot bot commented Jan 20, 2026 •

edited

Loading

Uh oh!

vercel bot commented Jan 20, 2026 •

edited

Loading

Uh oh!

pkg-pr-new bot commented Jan 20, 2026 •

edited

Loading

Uh oh!

coderabbitai bot commented Jan 20, 2026 •

edited

Loading

Walkthrough

Uh oh!

alexcarpenter commented Jan 26, 2026

Uh oh!

clerk-cookie commented Jan 26, 2026

Uh oh!

alexcarpenter left a comment

Uh oh!

nikosdouvlis left a comment

Uh oh!

nikosdouvlis Jan 27, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Conversation

brkalow commented Jan 20, 2026 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Type of change

Summary by CodeRabbit

Uh oh!

changeset-bot bot commented Jan 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

vercel bot commented Jan 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pkg-pr-new bot commented Jan 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai bot commented Jan 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Uh oh!

alexcarpenter commented Jan 26, 2026

Uh oh!

clerk-cookie commented Jan 26, 2026

Uh oh!

alexcarpenter left a comment

Choose a reason for hiding this comment

Uh oh!

nikosdouvlis left a comment

Choose a reason for hiding this comment

Uh oh!

nikosdouvlis Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

brkalow commented Jan 20, 2026 •

edited by coderabbitai bot

Loading

changeset-bot bot commented Jan 20, 2026 •

edited

Loading

vercel bot commented Jan 20, 2026 •

edited

Loading

pkg-pr-new bot commented Jan 20, 2026 •

edited

Loading

coderabbitai bot commented Jan 20, 2026 •

edited

Loading