chore(vue): Improve error message when Clerk plugin is not installed #6719

wobsoriano · 2025-09-05T17:38:57Z

Description

Checklist

pnpm test runs as expected.
pnpm build runs as expected.
(If applicable) JSDoc comments have been added or updated for any package exports
(If applicable) Documentation has been updated

Type of change

Summary by CodeRabbit

Bug Fixes
- Prevents runtime error when installing the Clerk Vue plugin without options.
- Provides clearer, scoped error messages when using Clerk Vue without the plugin installed, with a direct docs link.
Tests
- Added tests covering plugin-installed vs. not-installed scenarios.
Tooling
- Introduced a test setup file and updated test configuration for consistent environment variables.
Chores
- Added a changeset to publish a patch release for @clerk/vue.

changeset-bot · 2025-09-05T17:39:02Z

🦋 Changeset detected

Latest commit: d2d3155

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
@clerk/vue	Patch
@clerk/nuxt	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

vercel · 2025-09-05T17:39:04Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
clerk-js-sandbox	Ready	Preview	Comment	Sep 5, 2025 5:46pm

coderabbitai · 2025-09-05T17:39:05Z

Walkthrough

Adds a named-source parameter to useClerkContext with centralized error handling via errorThrower and updated docs link. Updates all callsites to pass their identifier. Makes plugin.install resilient to undefined options. Introduces a unit test for missing-plugin errors, plus Vitest setup/config. Adds a changeset for a patch release.

Changes

Cohort / File(s)	Summary
Clerk context hook update `packages/vue/src/composables/useClerkContext.ts`	Adds `source: string` parameter, integrates `errorThrower`, updates error message and docs URL; returns context or throws via errorThrower.
Callsite updates to pass source `packages/vue/src/composables/use*.ts`, `packages/vue/src/components/controlComponents.ts`	Replace `useClerkContext()` with `useClerkContext('<hook/component name>')` across Auth, Clerk, Organization, Session, SessionList, SignIn, SignUp, User, and RedirectToSignIn. No logic changes otherwise.
Plugin install hardening `packages/vue/src/plugin.ts`	Safely destructures `initialState` from possibly undefined options.
Tests and test setup `packages/vue/src/composables/__tests__/useClerkContext.test.ts`, `packages/vue/vitest.config.ts`, `packages/vue/vitest.setup.ts`	New test validates error when plugin not installed and success when installed; adds Vitest setup file preloading PACKAGE_NAME/PACKAGE_VERSION; references setup in config.
Changeset `.changeset/fuzzy-rivers-tell.md`	Adds patch release note for @clerk/vue highlighting improved error when plugin not installed.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  actor Dev as App Component
  participant Hook as useAuth/useUser/...
  participant Ctx as useClerkContext(source)
  participant Vue as Vue inject()
  participant Err as errorThrower

  Dev->>Hook: call composable
  Hook->>Ctx: useClerkContext("useAuth")
  Ctx->>Vue: inject(ClerkContextKey)
  alt Context found
    Vue-->>Ctx: ctx
    Ctx-->>Hook: ctx
    Hook-->>Dev: computed refs
  else Context missing
    Ctx->>Err: throw("@clerk/vue: useAuth can only be used when the Vue plugin is installed. ...")
    Err-->>Dev: Error thrown
  end

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

I nibbled through the context grass,
Named each path that I would pass.
If plugins hide, I thump—beware!
A clearer squeak of error air.
With tests to tuck me in at night,
I hop a patch—release in sight. 🐇✨

✨ Finishing Touches

📝 Generate Docstrings

🧪 Generate unit tests

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch rob/better-vue-nuxt-plugin-error-message

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

Review comments: Directly reply to a review comment made by CodeRabbit. Example:
- I pushed a fix in commit <commit_id>, please review it.
- Open a follow-up GitHub issue for this discussion.
Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query.
PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
- @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
- @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

CodeRabbit Commands (Invoked using PR/Issue comments)

Type @coderabbitai help to get the list of available commands.

Other keywords and placeholders

Add @coderabbitai ignore or @coderabbit ignore anywhere in the PR description to prevent this PR from being reviewed.
Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
Add @coderabbitai anywhere in the PR title to generate the title automatically.

Status, Documentation and Community

Visit our Status Page to check the current availability of CodeRabbit.
Visit our Documentation for detailed information on how to use CodeRabbit.
Join our Discord Community to get help, request features, and share feedback.
Follow us on X/Twitter for updates and announcements.

pkg-pr-new · 2025-09-05T17:42:09Z

Open in StackBlitz

@clerk/agent-toolkit

npm i https://pkg.pr.new/@clerk/agent-toolkit@6719

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@6719

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@6719

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@6719

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@6719

@clerk/dev-cli

npm i https://pkg.pr.new/@clerk/dev-cli@6719

@clerk/elements

npm i https://pkg.pr.new/@clerk/elements@6719

@clerk/clerk-expo

npm i https://pkg.pr.new/@clerk/clerk-expo@6719

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@6719

@clerk/express

npm i https://pkg.pr.new/@clerk/express@6719

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@6719

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@6719

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@6719

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@6719

@clerk/clerk-react

npm i https://pkg.pr.new/@clerk/clerk-react@6719

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@6719

@clerk/remix

npm i https://pkg.pr.new/@clerk/remix@6719

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@6719

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@6719

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@6719

@clerk/themes

npm i https://pkg.pr.new/@clerk/themes@6719

@clerk/types

npm i https://pkg.pr.new/@clerk/types@6719

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@6719

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@6719

commit: d2d3155

coderabbitai

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

packages/vue/src/plugin.ts (1)
41-57: Fix unsafe access when pluginOptions is undefined

You guard initialState with pluginOptions || {}, but still read pluginOptions.sdkMetadata, which will throw if pluginOptions is undefined. Merge with a default and use optional chaining.

Apply:
-    const { initialState } = pluginOptions || {};
+    const { initialState } = pluginOptions ?? {};

     const options = {
-      ...pluginOptions,
-      sdkMetadata: pluginOptions.sdkMetadata || SDK_METADATA,
+      ...(pluginOptions ?? {}),
+      sdkMetadata: pluginOptions?.sdkMetadata ?? SDK_METADATA,
     } as LoadClerkJsScriptOptions;

🧹 Nitpick comments (4)

packages/vue/src/composables/useSignIn.ts (1)
33-39: De-duplicate the hook name string

Use a single SOURCE constant for both telemetry and error provenance to prevent drift.

Apply:
 export const useSignIn: UseSignIn = () => {
-  const { clerk, clientCtx } = useClerkContext('useSignIn');
+  const SOURCE = 'useSignIn' as const;
+  const { clerk, clientCtx } = useClerkContext(SOURCE);

   const unwatch = watch(clerk, value => {
     if (value) {
-      value.telemetry?.record(eventMethodCalled('useSignIn'));
+      value.telemetry?.record(eventMethodCalled(SOURCE));
       unwatch();
     }
   });
packages/vue/src/composables/useUser.ts (1)
35-47: Optional: avoid hardcoded hook name

Mirror the useSignIn pattern with a SOURCE constant to avoid copy-paste mistakes across files.
 export const useUser: UseUser = () => {
-  const { userCtx } = useClerkContext('useUser');
+  const SOURCE = 'useUser' as const;
+  const { userCtx } = useClerkContext(SOURCE);
packages/vue/src/composables/__tests__/useClerkContext.test.ts (2)
9-23: Solid negative-path coverage; minor resilience tweak

Test is precise and hides Vue’s inject warning. Consider building the expected prefix from PACKAGE_NAME to avoid hardcoding '@clerk/vue'.
-    expect(() => render(Component)).toThrow(
-      '@clerk/vue: useAuth can only be used when the Vue plugin is installed. Learn more: https://clerk.com/docs/references/vue/clerk-plugin',
-    );
+    const prefix = `${globalThis.PACKAGE_NAME}: `;
+    expect(() => render(Component)).toThrow(
+      `${prefix}useAuth can only be used when the Vue plugin is installed. Learn more: https://clerk.com/docs/references/vue/clerk-plugin`,
+    );
25-45: Prevent accidental network/script loads during tests

When installing the real plugin, plugin.ts may attempt to load ClerkJS in JSDOM. Mock the browser loader to a resolved promise to keep tests hermetic.

Add near the top of this test file (before imports that use the plugin), or in a dedicated test setup:
vi.mock('../../utils/loadClerkJsScript', () => ({
  loadClerkJsScript: () => Promise.resolve(),
}));
vi.mock('../../utils/inBrowser', () => ({
  inBrowser: () => false, // or true if you prefer, since load is mocked anyway
}));
Alternatively, add afterEach(() => vi.restoreAllMocks()) to the suite to ensure mocks/spies are reset.

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

💡 Knowledge Base configuration:

MCP integration is disabled by default for public repositories
Jira integration is disabled by default for public repositories
Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 4a5bd7a and 5b75dde.

📒 Files selected for processing (15)

.changeset/fuzzy-rivers-tell.md (1 hunks)
packages/vue/src/components/controlComponents.ts (1 hunks)
packages/vue/src/composables/__tests__/useClerkContext.test.ts (1 hunks)
packages/vue/src/composables/useAuth.ts (1 hunks)
packages/vue/src/composables/useClerk.ts (1 hunks)
packages/vue/src/composables/useClerkContext.ts (1 hunks)
packages/vue/src/composables/useOrganization.ts (1 hunks)
packages/vue/src/composables/useSession.ts (1 hunks)
packages/vue/src/composables/useSessionList.ts (1 hunks)
packages/vue/src/composables/useSignIn.ts (1 hunks)
packages/vue/src/composables/useSignUp.ts (1 hunks)
packages/vue/src/composables/useUser.ts (1 hunks)
packages/vue/src/plugin.ts (1 hunks)
packages/vue/vitest.config.ts (1 hunks)
packages/vue/vitest.setup.ts (1 hunks)

🧰 Additional context used

📓 Path-based instructions (9)

**/*.{js,jsx,ts,tsx}