From 16f3429e1af48aec0606b6d6c3fd27d0a69e1c2e Mon Sep 17 00:00:00 2001
From: Dylan Staley <88163+dstaley@users.noreply.github.com>
Date: Mon, 10 Nov 2025 11:34:05 -0600
Subject: [PATCH] chore(repo): Update rules for types

---
 .changeset/wild-animals-call.md |  2 ++
 .cursor/rules/monorepo.mdc      | 22 ++++++++++++++++++----
 2 files changed, 20 insertions(+), 4 deletions(-)
 create mode 100644 .changeset/wild-animals-call.md

diff --git a/.changeset/wild-animals-call.md b/.changeset/wild-animals-call.md
new file mode 100644
index 00000000000..a845151cc84
--- /dev/null
+++ b/.changeset/wild-animals-call.md
@@ -0,0 +1,2 @@
+---
+---
diff --git a/.cursor/rules/monorepo.mdc b/.cursor/rules/monorepo.mdc
index 73a18af0942..e7b45bc0abd 100644
--- a/.cursor/rules/monorepo.mdc
+++ b/.cursor/rules/monorepo.mdc
@@ -1,11 +1,13 @@
 ---
-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
@@ -13,6 +15,7 @@ Repository Overview
 - 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