Merge branch 'main' into alexcarpenter/social-buttons-layout-mobile

Author: alexcarpenter

.changeset/great-cobras-give.md

@@ -1,18 +1,21 @@
 ---
-description: 
-globs: 
+description:
+globs:
 alwaysApply: true
 ---
+
 Monorepo Architecture and Structure
 
 Repository Overview
+
 - This is the official Clerk JavaScript SDK monorepo containing all Clerk authentication packages
 - Clerk provides streamlined user experiences for sign up, sign in, and profile management
 - All packages are published under the @clerk namespace on npm
 - Uses pnpm as the package manager with Turbo for build orchestration
 - Supports multiple JavaScript frameworks and environments
 
 Core Package Categories
+
 - **Core SDK**: `@clerk/clerk-js` - Core browser SDK with UI components
 - **Framework Integrations**: Next.js, React, Vue, Astro, Nuxt, Remix, Express, Fastify
 - **Platform Support**: Expo (React Native), Chrome Extension
@@ -23,6 +26,7 @@ Core Package Categories
 - **Specialized**: `@clerk/agent-toolkit` - AI agent integration tools
 
 Directory Structure
+
 - `packages/` - All publishable packages
 - `integration/` - End-to-end tests and integration templates
 - `playground/` - Development and testing applications
@@ -31,6 +35,7 @@ Directory Structure
 - `tools/` - Internal development tools
 
 Development Workflow
+
 - Use `pnpm dev` to start development mode for all packages
 - Use `pnpm build` to build all packages
 - Use `pnpm test` to run unit tests across all packages
@@ -39,6 +44,7 @@ Development Workflow
 - Changesets for version management and release automation
 
 Framework-Specific Packages
+
 - `@clerk/nextjs` - Next.js App Router and Pages Router support
 - `@clerk/clerk-react` - React hooks and components
 - `@clerk/vue` - Vue.js composables and components
@@ -50,6 +56,7 @@ Framework-Specific Packages
 - `@clerk/expo` - React Native/Expo SDK
 
 Testing Architecture
+
 - Unit tests with Jest and Vitest
 - Integration tests with Playwright
 - Component testing with React Testing Library
@@ -58,6 +65,7 @@ Testing Architecture
 - Separate test configurations per framework
 
 Build System
+
 - Turbo for monorepo orchestration and caching
 - tsup for TypeScript compilation and bundling
 - ESLint with custom configurations for different package types
@@ -66,26 +74,32 @@ Build System
 - Type checking with TypeScript and publint
 
 Environment Configuration
-- Supports multiple Clerk environment variables (CLERK_*, NEXT_PUBLIC_CLERK_*, etc.)
+
+- Supports multiple Clerk environment variables (CLERK*\*, NEXT_PUBLIC_CLERK*\*, etc.)
 - Development, staging, and production configurations
 - Verdaccio for local npm registry testing
 - Docker support for integration testing
 - CI/CD with GitHub Actions
 
 Localization Support
+
 - `packages/localizations/` contains translations for 30+ languages
 - Modular localization system allowing partial imports
 - Support for RTL languages
 - Framework-agnostic translation utilities
 
 Package Interdependency Rules
+
 - `@clerk/shared` is a common dependency for most packages
-- `@clerk/types` provides TypeScript definitions used across packages
+- `@clerk/shared/types` provides TypeScript definitions used across packages
+  - `@clerk/types` is an alias for `@clerk/shared/types`, but its usage is deprecated. Prefer using `@clerk/shared/types`.
+  - If a TypeScript error comes from a type imported from `@clerk/shared/types`, run `turbo build --filter=@clerk/shared --filter=@clerk/types` to make sure the latest version of the packages are being used.
 - `@clerk/backend` is independent and used for server-side operations
 - Framework packages depend on `@clerk/clerk-js` for core functionality
 - Integration packages build upon framework-specific packages
 
 Release Management
+
 - Automated releases with Changesets
 - Semantic versioning across all packages
 - Canary and snapshot releases for testing

.cursor/rules/monorepo.mdc

@@ -98,20 +98,50 @@ function getRelativeLinkReplacements() {
 function getCatchAllReplacements() {
   return [
     {
-      pattern: /\(setActiveParams\)/g,
-      replace: '([setActiveParams](/docs/reference/javascript/types/set-active-params))',
+      pattern: /(?<![\[\w`])`Appearance`\\<`Theme`\\>/g,
+      replace: '[`Appearance<Theme>`](/docs/guides/customizing-clerk/appearance-prop/overview)',
+    },
+    {
+      pattern: /\(CreateOrganizationParams\)/g,
+      replace: '([CreateOrganizationParams](#create-organization-params))',
     },
     {
       pattern: /`LoadedClerk`/g,
       replace: '[Clerk](/docs/reference/javascript/clerk)',
     },
     {
-      pattern: /\(CreateOrganizationParams\)/g,
-      replace: '([CreateOrganizationParams](#create-organization-params))',
+      pattern: /(?<![\[\w`])`?LocalizationResource`?(?![\]\w`])/g,
+      replace: '[`LocalizationResource`](/docs/guides/customizing-clerk/localization)',
+    },
+    {
+      // SessionResource appears in plain text, with an array next to it, with backticks, etc.
+      // e.g. `SessionResource[]`
+      pattern: /(?<![`[\]])\bSessionResource(\[\])?\b(?![\]\)`])/g,
+      replace: '[`SessionResource`](/docs/reference/javascript/session)$1',
+    },
+    {
+      pattern: /(?<![\[\w`])`?SessionStatusClaim`?(?![\]\w`])/g,
+      replace: '[`SessionStatusClaim`](/docs/reference/javascript/types/session-status)',
     },
     {
-      pattern: /\| `SignInResource` \|/,
-      replace: '| [SignInResource](/docs/reference/javascript/sign-in) |',
+      pattern: /(?<![`[\]])\bSetActiveParams\b(?![\]\(])/g,
+      replace: '[SetActiveParams](/docs/reference/javascript/types/set-active-params)',
+    },
+    {
+      pattern: /(?<![\[\w`])`?SignInResource`?(?![\]\w`])/g,
+      replace: '[`SignInResource`](/docs/reference/javascript/sign-in)',
+    },
+    {
+      pattern: /(?<![\[\w`])`?SignedInSessionResource`?(?![\]\w`])/g,
+      replace: '[`SignedInSessionResource`](/docs/reference/javascript/session)',
+    },
+    {
+      pattern: /(?<![\[\w`])`?SignUpResource`?(?![\]\w`])/g,
+      replace: '[`SignUpResource`](/docs/reference/javascript/sign-up)',
+    },
+    {
+      pattern: /(?<![\[\w`])`?OrganizationResource`?(?![\]\w`])/g,
+      replace: '[`OrganizationResource`](/docs/reference/javascript/organization)',
     },
     {
       pattern: /`OrganizationPrivateMetadata`/g,
@@ -142,6 +172,10 @@ function getCatchAllReplacements() {
       replace:
         '[`OrganizationMembershipPublicMetadata`](/docs/reference/javascript/types/metadata#organization-membership-public-metadata)',
     },
+    {
+      pattern: /(?<![\[\w`])`?UserResource`?(?![\]\w`])/g,
+      replace: '[`UserResource`](/docs/reference/javascript/user)',
+    },
     {
       /**
        * By default, `@deprecated` is output with `**Deprecated**`. We want to add a full stop to it.

.typedoc/custom-plugin.mjs

@@ -200,7 +200,7 @@ export const createUserService = (clerkClient: ClerkClient) => {
 
       const apiKey = await clerkClient.apiKeys.create({
         subject: userId,
-        name: `Integration Test - ${userId}`,
+        name: `Integration Test - ${faker.string.uuid()}`,
         secondsUntilExpiration: TWENTY_MINUTES,
       });