Merge branch 'main' into ss/DOCS-10983

Author: SarahSoutoul

.changeset/afraid-papers-see.md

@@ -0,0 +1,7 @@
+---
+'@clerk/localizations': patch
+---
+
+Improve Korean (ko-KR) localization by translating missing strings
+
+- Translated undefined values to Korean

.changeset/fuzzy-keys-smell.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': patch
+---
+
+Build internal variants of all paginated hooks that use React Query instead of SWR.

.changeset/honest-pears-play.md

@@ -0,0 +1,7 @@
+---
+"@clerk/clerk-react": patch
+"@clerk/vue": patch
+"@clerk/astro": patch
+---
+
+Fixed missing API keys props within `<UserButton />`

.changeset/ripe-ants-carry.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

.changeset/ripe-banks-pay.md

@@ -191,7 +191,7 @@ jobs:
   unit-tests:
     needs: [check-permissions, build-packages]
     if: ${{ github.event_name != 'pull_request' || github.event.pull_request.draft == false }}
-    name: Unit Tests
+    name: Unit Tests (${{ matrix.node-version }}, ${{ matrix.filter-label }}${{ matrix.clerk-use-rq == 'true' && ', RQ' || '' }})
     permissions:
       contents: read
       actions: write # needed for actions/upload-artifact
@@ -205,11 +205,17 @@ jobs:
       TURBO_SUMMARIZE: false
 
     strategy:
-      fail-fast: true
+      fail-fast: false
       matrix:
         include:
           - node-version: 22
             test-filter: "**"
+            clerk-use-rq: "false"
+            filter-label: "**"
+          - node-version: 22
+            test-filter: "--filter=@clerk/shared --filter=@clerk/clerk-js"
+            clerk-use-rq: "true"
+            filter-label: "shared, clerk-js"
 
     steps:
       - name: Checkout Repo
@@ -229,22 +235,35 @@ jobs:
           turbo-team: ${{ vars.TURBO_TEAM }}
           turbo-token: ${{ secrets.TURBO_TOKEN }}
 
+      - name: Rebuild @clerk/shared with CLERK_USE_RQ=true
+        if: ${{ matrix.clerk-use-rq == 'true' }}
+        run: pnpm turbo build $TURBO_ARGS --filter=@clerk/shared --force
+        env:
+          CLERK_USE_RQ: true
+
+      - name: Rebuild dependent packages with CLERK_USE_RQ=true
+        if: ${{ matrix.clerk-use-rq == 'true' }}
+        run: pnpm turbo build $TURBO_ARGS --filter=@clerk/shared^... --force
+        env:
+          CLERK_USE_RQ: true
+
       - name: Run tests in packages
         run: |
           if [ "${{ matrix.test-filter }}" = "**" ]; then
-            echo "Running full test suite on Node ${{ matrix.node-version }}."
+            echo "Running full test suite on Node ${{ matrix.node-version }}"
             pnpm turbo test $TURBO_ARGS
           else
-            echo "Running LTS subset on Node ${{ matrix.node-version }}."
+            echo "Running tests: ${{ matrix.filter-label }}"
             pnpm turbo test $TURBO_ARGS ${{ matrix.test-filter }}
           fi
         env:
           NODE_VERSION: ${{ matrix.node-version }}
+          CLERK_USE_RQ: ${{ matrix.clerk-use-rq }}
 
       - name: Run Typedoc tests
         run: |
-          # Only run Typedoc tests for one matrix version
-          if [ "${{ matrix.node-version }}" == "22" ]; then
+          # Only run Typedoc tests for one matrix version and main test run
+          if [ "${{ matrix.node-version }}" == "22" ] && [ "${{ matrix.test-filter }}" = "**" ]; then
             pnpm test:typedoc
           fi
         env:
@@ -255,14 +274,14 @@ jobs:
         if: ${{ env.TURBO_SUMMARIZE == 'true' }}
         continue-on-error: true
         with:
-          name: turbo-summary-report-unit-${{ github.run_id }}-${{ github.run_attempt }}-node-${{ matrix.node-version }}
+          name: turbo-summary-report-unit-${{ github.run_id }}-${{ github.run_attempt }}-node-${{ matrix.node-version }}${{ matrix.clerk-use-rq == 'true' && '-rq' || '' }}
           path: .turbo/runs
           retention-days: 5
 
   integration-tests:
     needs: [check-permissions, build-packages]
     if: ${{ github.event_name != 'pull_request' || github.event.pull_request.draft == false }}
-    name: Integration Tests
+    name: Integration Tests (${{ matrix.test-name }}, ${{ matrix.test-project }}${{ matrix.next-version && format(', {0}', matrix.next-version) || '' }}${{ matrix.clerk-use-rq == 'true' && ', RQ' || '' }})
     permissions:
       contents: read
       actions: write # needed for actions/upload-artifact
@@ -291,18 +310,28 @@ jobs:
             'vue',
             'nuxt',
             'react-router',
-            'billing',
             'machine',
             'custom',
           ]
         test-project: ["chrome"]
         include:
+          - test-name: 'billing'
+            test-project: 'chrome'
+            clerk-use-rq: 'false'
+          - test-name: 'billing'
+            test-project: 'chrome'
+            clerk-use-rq: 'true'
           - test-name: 'nextjs'
             test-project: 'chrome'
             next-version: '14'
           - test-name: 'nextjs'
             test-project: 'chrome'
             next-version: '15'
+            clerk-use-rq: 'false'
+          - test-name: 'nextjs'
+            test-project: 'chrome'
+            next-version: '15'
+            clerk-use-rq: 'true'
           - test-name: 'nextjs'
             test-project: 'chrome'
             next-version: '16'
@@ -360,12 +389,24 @@ jobs:
           echo "affected=${AFFECTED}"
           echo "affected=${AFFECTED}" >> $GITHUB_OUTPUT
 
+      - name: Rebuild @clerk/shared with CLERK_USE_RQ=true
+        if: ${{ steps.task-status.outputs.affected == '1' && matrix.clerk-use-rq == 'true' }}
+        run: pnpm turbo build $TURBO_ARGS --filter=@clerk/shared --force
+        env:
+          CLERK_USE_RQ: true
+
+      - name: Rebuild dependent packages with CLERK_USE_RQ=true
+        if: ${{ steps.task-status.outputs.affected == '1' && matrix.clerk-use-rq == 'true' }}
+        run: pnpm turbo build $TURBO_ARGS --filter=@clerk/shared^... --force
+        env:
+          CLERK_USE_RQ: true
+
       - name: Verdaccio
         if: ${{ steps.task-status.outputs.affected == '1' }}
         uses: ./.github/actions/verdaccio
         with:
           publish-cmd: |
-            if [ "$(pnpm config get registry)" = "https://registry.npmjs.org/" ]; then echo 'Error: Using default registry' && exit 1; else pnpm turbo build $TURBO_ARGS --only && pnpm changeset publish --no-git-tag; fi
+            if [ "$(pnpm config get registry)" = "https://registry.npmjs.org/" ]; then echo 'Error: Using default registry' && exit 1; else CLERK_USE_RQ=${{ matrix.clerk-use-rq }} pnpm turbo build $TURBO_ARGS --only && pnpm changeset publish --no-git-tag; fi
 
       - name: Edit .npmrc [link-workspace-packages=false]
         run: sed -i -E 's/link-workspace-packages=(deep|true)/link-workspace-packages=false/' .npmrc
@@ -425,6 +466,7 @@ jobs:
           E2E_NEXTJS_VERSION: ${{ matrix.next-version }}
           E2E_PROJECT: ${{ matrix.test-project }}
           E2E_CLERK_ENCRYPTION_KEY: ${{ matrix.clerk-encryption-key }}
+          CLERK_USE_RQ: ${{ matrix.clerk-use-rq }}
           INTEGRATION_INSTANCE_KEYS: ${{ secrets.INTEGRATION_INSTANCE_KEYS }}
           MAILSAC_API_KEY: ${{ secrets.MAILSAC_API_KEY }}
           NODE_EXTRA_CA_CERTS: ${{ github.workspace }}/integration/certs/rootCA.pem
@@ -433,7 +475,7 @@ jobs:
         if: ${{ cancelled() || failure() }}
         uses: actions/upload-artifact@v4
         with:
-          name: playwright-traces-${{ github.run_id }}-${{ github.run_attempt }}-${{ matrix.test-name }}
+          name: playwright-traces-${{ github.run_id }}-${{ github.run_attempt }}-${{ matrix.test-name }}${{ matrix.next-version && format('-next{0}', matrix.next-version) || '' }}${{ matrix.clerk-use-rq == 'true' && '-rq' || '' }}
           path: integration/test-results
           retention-days: 1
 

.changeset/shaggy-numbers-attack.md

@@ -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,
       });