@clerk/mosaic 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Clerk, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,108 @@
+<p align="center">
+  <a href="https://clerk.com?utm_source=github&utm_medium=clerk_mosaic" target="_blank" rel="noopener noreferrer">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://images.clerk.com/static/logo-dark-mode-400x400.png">
+      <img src="https://images.clerk.com/static/logo-light-mode-400x400.png" height="64">
+    </picture>
+  </a>
+  <br />
+  <h1 align="center">@clerk/mosaic</h1>
+</p>
+
+<div align="center">
+
+[![Clerk documentation](https://img.shields.io/badge/documentation-clerk-green.svg)](https://clerk.com/docs?utm_source=github&utm_medium=clerk_mosaic)
+[![Follow on X](https://img.shields.io/twitter/follow/clerk?style=social)](https://x.com/intent/follow?screen_name=clerk)
+
+[Changelog](https://github.com/clerk/javascript/blob/main/packages/mosaic/CHANGELOG.md)
+·
+[Report a Bug](https://github.com/clerk/javascript/issues/new?assignees=&labels=needs-triage&projects=&template=BUG_REPORT.yml)
+·
+[Request a Feature](https://feedback.clerk.com/roadmap)
+·
+[Get help](https://clerk.com/contact/support?utm_source=github&utm_medium=clerk_mosaic)
+
+</div>
+
+## Getting started
+
+`@clerk/mosaic` provides Clerk's experimental next-generation React components.
+
+This package lets you preview and provide feedback on Clerk's next generation of components.
+
+When stable, components will move to be exported through the regular packages.
+
+> :construction: We reserve the right to make breaking changes in minors, please pin your version.
+
+### Prerequisites
+
+- Node.js `>=20.9.0` or later
+- A supported React-based Clerk SDK that renders a `ClerkProvider`
+  - `@clerk/react` version 6 or later
+  - `@clerk/nextjs` version 7 or later
+  - Other React-based Clerk SDKs may also work, but are currently untested
+- React 18 or 19
+
+### Installation
+
+```shell
+
+npm install --save-exact @clerk/mosaic
+pnpm add --save-exact @clerk/mosaic
+yarn add --exact @clerk/mosaic
+```
+
+## Usage
+
+Import the stylesheet and render Mosaic components beneath the SDK `ClerkProvider`:
+
+```tsx
+import { ClerkProvider } from '@clerk/react';
+import { UserButton } from '@clerk/mosaic';
+import '@clerk/mosaic/styles.css';
+
+export function App({ children }) {
+  return (
+    <ClerkProvider publishableKey={process.env.CLERK_PUBLISHABLE_KEY}>
+      <UserButton />
+      {children}
+    </ClerkProvider>
+  );
+}
+```
+
+If you want to use custom CSS to theme the components, instead import the stylesheet into a cascade layer:
+
+```css
+@import '@clerk/mosaic/styles.css' layer(components);
+```
+
+This ensures your unlayered custom CSS takes priority. Expect more documentation on custom theming soon.
+
+## Troubleshooting
+
+### A Clerk hook says it can only be used within `<ClerkProvider />`
+
+Mosaic and your Clerk framework SDK must resolve the same copy of `@clerk/shared`. If `<ClerkProvider />` is present but you still see this error, deduplicate your dependencies:
+
+```shell
+npm dedupe
+pnpm dedupe
+yarn dedupe @clerk/shared
+```
+
+Check the installed versions:
+
+```shell
+npm ls @clerk/shared
+pnpm why @clerk/shared
+yarn why @clerk/shared
+```
+
+If multiple versions remain, the supported ranges are likely incompatible. Update Mosaic and your Clerk framework SDK to the latest versions, then deduplicate again.
+
+## License
+
+This project is licensed under the **MIT license**.
+
+See [LICENSE](https://github.com/clerk/javascript/blob/main/packages/mosaic/LICENSE) for more information.

package/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "@clerk/mosaic",
+  "version": "0.0.1",
+  "description": "Clerk Mosaic UI components",
+  "keywords": [
+    "clerk",
+    "auth",
+    "authentication",
+    "react",
+    "mosaic",
+    "ui"
+  ],
+  "homepage": "https://clerk.com/",
+  "bugs": {
+    "url": "https://github.com/clerk/javascript/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/clerk/javascript.git",
+    "directory": "packages/mosaic"
+  },
+  "license": "MIT",
+  "author": "Clerk",
+  "sideEffects": [
+    "./dist/styles.css"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./styles.css": {
+      "types": "./styles.css.d.ts",
+      "default": "./dist/styles.css"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "styles.css.d.ts"
+  ],
+  "dependencies": {
+    "@clerk/shared": "^4.33.0"
+  },
+  "devDependencies": {
+    "@floating-ui/react": "0.27.20",
+    "@stylexjs/eslint-plugin": "0.19.0",
+    "@stylexjs/rollup-plugin": "0.19.0",
+    "@stylexjs/stylex": "0.19.0",
+    "@stylexjs/unplugin": "0.19.0",
+    "@types/react": "18.3.28",
+    "@types/react-dom": "18.3.7",
+    "bundlewatch": "^0.4.2",
+    "react": "18.3.1",
+    "react-dom": "18.3.1",
+    "tsdown": "0.22.2",
+    "@clerk/headless": "^0.0.34"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ~19.0.3 || ~19.1.4 || ~19.2.3 || ~19.3.0-0",
+    "react-dom": "^18.0.0 || ~19.0.3 || ~19.1.4 || ~19.2.3 || ~19.3.0-0"
+  },
+  "engines": {
+    "node": ">=20.9.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "pnpm build:js && pnpm build:css && pnpm check:bundle && pnpm typecheck",
+    "build:css": "tsdown --config tsdown.css.config.mts",
+    "build:js": "tsdown --config tsdown.config.mts",
+    "bundlewatch": "FORCE_COLOR=1 bundlewatch --config bundlewatch.config.json",
+    "check:bundle": "node ./scripts/check-bundle.mjs",
+    "clean": "rimraf ./dist ./dist-css",
+    "dev": "tsdown --config tsdown.config.mts --watch",
+    "format": "node ../../scripts/format-package.mjs",
+    "format:check": "node ../../scripts/format-package.mjs --check",
+    "lint": "eslint src",
+    "lint:attw": "attw --pack . --exclude-entrypoints styles.css --profile esm-only",
+    "lint:publint": "publint",
+    "test": "vitest run",
+    "test:ci": "vitest run --maxWorkers=70%",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/styles.css.d.ts

@@ -0,0 +1 @@
+export {};