fix(ui): import createTheme types relatively for deterministic declarations by alexcarpenter · Pull Request #10040 · clerk/javascript

alexcarpenter · 2026-10-02T18:28:53Z

Description

createTheme.ts imported its appearance types through the package's own @clerk/ui/internal specifier. That resolves through package.json exports to dist/internal/index.d.ts, so tsdown emitted different declarations depending on whether dist/ existed at build time:

empty dist/: import { ... } from "@clerk/ui/internal"
existing dist/ (clean: false): import { ... } from "../dist/internal/appearance.js", an invalid path from inside dist/themes/

Break Check builds its main baseline and the PR head under different conditions, so every PR touching packages/ui/** was reported as a breaking change to createTheme in ./themes/experimental (e.g. #10015 (comment)).

Importing the types relatively makes the emitted declarations identical in both cases. Published types are unaffected.

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

…ations

vercel · 2026-10-02T18:28:56Z

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

Project	Deployment	Actions	Updated
clerk-js-sandbox	Ready	Preview	Oct 2, 2026 6:32pm UTC
swingset	Ready	Preview	Oct 2, 2026 6:32pm UTC

changeset-bot · 2026-10-02T18:29:00Z

🦋 Changeset detected

Latest commit: f5a9463

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

coderabbitai · 2026-10-02T18:29:26Z

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

🧰 Additional context used

📚 Code guidelines (1)

.cursor/rules/typescript.mdc — auto-discovered

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: Team

Run ID: f886f804-9d08-4c93-a958-179d6398a016

📥 Commits

Reviewing files that changed from the base of the PR and between dee649c and f5a9463.

📒 Files selected for processing (2)

.changeset/stable-createtheme-type-imports.md
packages/ui/src/themes/createTheme.ts

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

clerk/clerk_go (manual)
clerk/dashboard (manual)
clerk/accounts (manual)
clerk/backoffice (manual)
clerk/clerk (manual)
clerk/clerk-docs (manual)
clerk/cloudflare-workers (manual)
clerk/clerk-ios (auto-detected)
clerk/clerk-android (auto-detected)
clerk/cli (auto-detected)

Included review availability: This review used your included allowance. 7 included reviews remain after this review. Your included PR review attempts over the past 7 days set your current allowance at 8 reviews per hour.

📝 Walkthrough

Walkthrough

The BaseTheme, Elements, and Theme type import in createTheme.ts now uses ../internal/appearance instead of @clerk/ui/internal. The changeset file contains empty frontmatter and no description.

Priority: ⬇️ Low

Estimated code review effort: 1 (Trivial) | ~3 minutes

Merge Risk: ⚪ Minimal · up to f5a94

The theme declaration import now uses a stable relative path, and its target is included in the published output. The empty changeset does not disrupt release workflows, so no actionable merge risk remains.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: using relative imports for createTheme types to produce deterministic declarations.
Description check	✅ Passed	The description directly explains the declaration-generation issue, the relative-import fix, and the expected build impact.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 1…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.

_{Comment @coderabbitai help to get the list of available commands.}

pkg-pr-new · 2026-10-02T18:31:55Z

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/electron

npm i https://pkg.pr.new/@clerk/electron@10040

@clerk/electron-passkeys

npm i https://pkg.pr.new/@clerk/electron-passkeys@10040

@clerk/eslint-plugin

npm i https://pkg.pr.new/@clerk/eslint-plugin@10040

@clerk/expo

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

@clerk/expo-biometrics

npm i https://pkg.pr.new/@clerk/expo-biometrics@10040

@clerk/expo-google-signin

npm i https://pkg.pr.new/@clerk/expo-google-signin@10040

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/mosaic

npm i https://pkg.pr.new/@clerk/mosaic@10040

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: f5a9463

github-actions · 2026-10-02T18:33:04Z

API Changes Report

Generated by Break Check on 2026-10-02T18:33:01.939Z

Summary

Metric	Count
Packages analyzed	19
Packages with changes	1
🔴 Breaking changes	0
🟡 Non-breaking changes	1
🟢 Additions	0

🤖 This report was reviewed by claude-sonnet-4-6.

@clerk/ui

Current version: 1.38.1
Recommended bump: MINOR → 1.39.0

Subpath `./themes/experimental`

🟡 Non-breaking Changes (1)

Modified: `createTheme`

// ... 4 unchanged lines elided ...
      theme: InternalTheme;
    }) => Elements);
    theme?: (BaseTheme | BaseTheme[]) | undefined;
-   options?: import("@clerk/ui/internal").Options | undefined;
-   variables?: import("@clerk/ui/internal").Variables | undefined;
-   captcha?: import("@clerk/ui/internal").CaptchaAppearanceOptions | undefined;
+   options?: Options | undefined;
+   variables?: Variables | undefined;
+   captcha?: CaptchaAppearanceOptions | undefined;
    cssLayerName?: string | undefined;
  }

Static analyzer: Breaking change in function createTheme: Return type changed: {__type:"prebuilt_appearance";name?:string;elements?:!unknown|((params:{theme:import("@clerk/ui").~InternalTheme;})=>!unknown);theme?:(!unknown|!unknown[])|undefined;options?:import("@clerk/ui/internal").Options|undefined;variables?:import("@clerk/ui/internal").Variables|undefined;captcha?:import("@clerk/ui/internal").CaptchaAppearanceOptions|undefined;cssLayerName?:string|undefined;} → {__type:"prebuilt_appearance";name?:string;elements?:((params:{theme:import("@clerk/ui").~InternalTheme;})=>import("@clerk/ui").~Elements)|import("@clerk/ui").~Elements;theme?:(import("@clerk/ui").~BaseTheme|import("@clerk/ui").~BaseTheme[])|undefined;options?:import("@clerk/ui").~Options|undefined;variables?:import("@clerk/ui").~Variables|undefined;captcha?:import("@clerk/ui").~CaptchaAppearanceOptions|undefined;cssLayerName?:string|undefined;}

🤖 AI review (reclassified as non-breaking) (85%): The before/after snippets show structurally identical return types; the only difference is that options, variables, and captcha changed their module specifier from @clerk/ui/internal to @clerk/ui. Per rule 12, @clerk/ui/internal has referenceResolutions verdict unknown (package not found), so we cannot confirm the old specifier was resolvable. Per rule 13, when a non-resolvable specifier is replaced by a public entry-point specifier, the change is a repair rather than a break. The new specifier (@clerk/ui) is the package's main entry point and is fully resolvable, so the change improves consumer type resolution and is non-breaking.

Report generated by Break Check

_{Last ran on f5a9463.}

fix(ui): import createTheme types relatively for deterministic declar…

f5a9463

…ations

github-actions Bot added the ui label Oct 2, 2026

vercel Bot deployed to Preview – clerk-js-sandbox October 2, 2026 18:29 View deployment

vercel Bot deployed to Preview – swingset October 2, 2026 18:32 View deployment

alexcarpenter requested a review from wobsoriano October 2, 2026 20:41

wobsoriano approved these changes Oct 2, 2026

View reviewed changes

Navigation Menu

fix(ui): import createTheme types relatively for deterministic declarations - #10040

fix(ui): import createTheme types relatively for deterministic declarations#10040
alexcarpenter wants to merge 1 commit into
mainfrom
carp/fix-createtheme-self-import

alexcarpenter commented Oct 2, 2026

Uh oh!

vercel Bot commented Oct 2, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented Oct 2, 2026

Uh oh!

coderabbitai Bot commented Oct 2, 2026 •

edited

Loading

Walkthrough

Uh oh!

pkg-pr-new Bot commented Oct 2, 2026

Uh oh!

github-actions Bot commented Oct 2, 2026

Uh oh!

This branch was successfully deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

alexcarpenter commented Oct 2, 2026

Description

Checklist

Type of change

Uh oh!

vercel Bot commented Oct 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot Bot commented Oct 2, 2026

🦋 Changeset detected

Uh oh!

coderabbitai Bot commented Oct 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Uh oh!

pkg-pr-new Bot commented Oct 2, 2026

Uh oh!

github-actions Bot commented Oct 2, 2026

API Changes Report

Summary

@clerk/ui

Subpath ./themes/experimental

🟡 Non-breaking Changes (1)

Modified: createTheme

Uh oh!

This branch was successfully deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

vercel Bot commented Oct 2, 2026 •

edited

Loading

coderabbitai Bot commented Oct 2, 2026 •

edited

Loading

Subpath `./themes/experimental`

Modified: `createTheme`