11---
2- description:
3- globs:
2+ description:
3+ globs:
44alwaysApply: true
55---
6+
67Monorepo Architecture and Structure
78
89Repository Overview
10+
911- This is the official Clerk JavaScript SDK monorepo containing all Clerk authentication packages
1012- Clerk provides streamlined user experiences for sign up, sign in, and profile management
1113- All packages are published under the @clerk namespace on npm
1214- Uses pnpm as the package manager with Turbo for build orchestration
1315- Supports multiple JavaScript frameworks and environments
1416
1517Core Package Categories
18+
1619- **Core SDK**: `@clerk/clerk-js` - Core browser SDK with UI components
1720- **Framework Integrations**: Next.js, React, Vue, Astro, Nuxt, Remix, Express, Fastify
1821- **Platform Support**: Expo (React Native), Chrome Extension
@@ -23,6 +26,7 @@ Core Package Categories
2326- **Specialized**: `@clerk/agent-toolkit` - AI agent integration tools
2427
2528Directory Structure
29+
2630- `packages/` - All publishable packages
2731- `integration/` - End-to-end tests and integration templates
2832- `playground/` - Development and testing applications
@@ -31,6 +35,7 @@ Directory Structure
3135- `tools/` - Internal development tools
3236
3337Development Workflow
38+
3439- Use `pnpm dev` to start development mode for all packages
3540- Use `pnpm build` to build all packages
3641- Use `pnpm test` to run unit tests across all packages
@@ -39,8 +44,9 @@ Development Workflow
3944- Changesets for version management and release automation
4045
4146Framework-Specific Packages
47+
4248- `@clerk/nextjs` - Next.js App Router and Pages Router support
43- - `@clerk/clerk- react` - React hooks and components
49+ - `@clerk/react` - React hooks and components
4450- `@clerk/vue` - Vue.js composables and components
4551- `@clerk/astro` - Astro integration with SSR support
4652- `@clerk/nuxt` - Nuxt.js module
@@ -50,6 +56,7 @@ Framework-Specific Packages
5056- `@clerk/expo` - React Native/Expo SDK
5157
5258Testing Architecture
59+
5360- Unit tests with Jest and Vitest
5461- Integration tests with Playwright
5562- Component testing with React Testing Library
@@ -58,6 +65,7 @@ Testing Architecture
5865- Separate test configurations per framework
5966
6067Build System
68+
6169- Turbo for monorepo orchestration and caching
6270- tsup for TypeScript compilation and bundling
6371- ESLint with custom configurations for different package types
@@ -66,26 +74,30 @@ Build System
6674- Type checking with TypeScript and publint
6775
6876Environment Configuration
69- - Supports multiple Clerk environment variables (CLERK_*, NEXT_PUBLIC_CLERK_*, etc.)
77+
78+ - Supports multiple Clerk environment variables (CLERK*\*, NEXT_PUBLIC_CLERK*\*, etc.)
7079- Development, staging, and production configurations
7180- Verdaccio for local npm registry testing
7281- Docker support for integration testing
7382- CI/CD with GitHub Actions
7483
7584Localization Support
85+
7686- `packages/localizations/` contains translations for 30+ languages
7787- Modular localization system allowing partial imports
7888- Support for RTL languages
7989- Framework-agnostic translation utilities
8090
8191Package Interdependency Rules
92+
8293- `@clerk/shared` is a common dependency for most packages
8394- `@clerk/types` provides TypeScript definitions used across packages
8495- `@clerk/backend` is independent and used for server-side operations
8596- Framework packages depend on `@clerk/clerk-js` for core functionality
8697- Integration packages build upon framework-specific packages
8798
8899Release Management
100+
89101- Automated releases with Changesets
90102- Semantic versioning across all packages
91103- Canary and snapshot releases for testing
0 commit comments