useRouter is not available in extension components

[mantis-toboggan-md]

Setup

• Rancher version: 2.14.1 (prime)
• Rancher UI Extensions: see description
• Browser type & version: ff

Describe the bug
Extension components using the composition api appear unable to access useRouter() -- it always returns undefined. Composition components are able to use this.$router as expected. This bug is not reproducible when running extensions locally; they must be built and loaded into the dashboard

To Reproduce
This issue was noticed during virtual clusters ui development. I've created a small test extension to reproduce it here: https://github.com/mantis-toboggan-md/simple-extension

The extension adds edit pages for limitRange and resourceQuota resources.

The limitrange page uses the composition api and calls useRouter() to get a url and render it on the page. This results in a console error and no url is rendered.

The resourceQuota edit component uses the options api and calls this.$router to get a url and render it on the page. This works as expected.

Expected Result
Extensions should be able to use useRouter()

Screenshots

Additional context
Possibly related to #10543

[github-actions]

🎯 Agentic Issue Triage

Summary: Extension components using Vue Composition API's useRouter() receive undefined when the extension is built and loaded into the dashboard. The Options API this.$router works fine in the same context, pointing to a Vue instance/provide-injection mismatch specific to the built extension context.

🔍 Root Cause Analysis

In Vue 3 (and Vue 2.7 backport), useRouter() works by calling inject(routerKey) using a symbol defined inside vue-router. This symbol must be the exact same reference used when the router was provided to the app.

When an extension is built separately and bundled (e.e. as a UMD/IIFE), it likely bundles its own copy of vue-router. The routerKey symbol in the extension's copy of vue-router is different from the routerKey in the dashboard's copy. So inject(routerKey) finds nothing → useRouter() returns undefined.

this.$router works because it reads directly from the Vue instance property chain (set globally via Vue.use(VueRouter)), not from the provide/inject symbol system.

The related issue #10543 (now closed) addressed a similar ESM vs UMD mismatch for defineComponent. The same class of problem appears here for the composition API router composables.

🐛 Reproduction Steps

1. Clone the test extension: https://github.com/mantis-toboggan-md/simple-extension
2. Build the extension: yarn build-pkg <extension-name>
3. Load the built extension into a running Rancher 2.14.1 instance
4. Navigate to the limitRange edit page (which uses useRouter())
5. Observe the console error and missing URL
6. Compare with the resourceQuota edit page (which uses this.$router) — it works correctly

Not reproducible locally because local dev mode shares the same webpack/module graph, so the same vue-router instance is used everywhere.

🛠 Debugging Strategies

1. Check bundled dependencies: In the built extension's output JS, check if vue-router is being bundled inline or marked as an external. If bundled, the routerKey symbol will be a different reference than the one in the dashboard.

2. Inspect externals config: In the extension's build config (vue.config.js or webpack config), ensure vue-router is in the externals list alongside vue. It should be provided by the host dashboard, not bundled.

3. Verify the router symbol: Add a temporary debug log in the extension:

   import { getCurrentInstance } from 'vue';
   const instance = getCurrentInstance();
   console.log('$router from instance:', instance?.proxy?.$router);
   console.log('useRouter result:', useRouter());

4. Check app.provide: In shell/initialize/app-extended.js, the router is injected as this.$router via the Vue plugin system. For Vue 3 composition API compat, the router also needs to be provided via app.provide(routerKey, router). Verify this is happening.

💡 Suggested Fix Directions

Option A — Mark vue-router as external in extension builds:
Ensure the extension build configuration externalizes vue-router so it re-uses the dashboard's instance. This is likely the correct fix — similar to how vue itself is externalized.

Option B — Expose useRouter as a re-export from @shell:
The dashboard could export a wrapper useRouter from @shell/composables that reads from the instance's $router, bypassing the symbol mismatch:

// `@shell/composables`/router.ts
import { getCurrentInstance } from 'vue';
export function useRouter() {
  return getCurrentInstance()?.proxy?.$router;
}

Extensions would then import from @shell/composables/router instead of vue-router directly.

Option C — Re-provide the router with the extension's vue-router symbol:
When loading an extension, detect and reconcile the router symbol. More complex and brittle.

Option A is the most robust long-term fix.

📋 Suggested Sub-Tasks

• Confirm that vue-router is NOT externalized in the extension build config
• Add vue-router to the extension build externals (alongside vue)
• Test that useRouter(), useRoute(), and other vue-router composables work in built extensions
• Add a note to the extension development documentation about not bundling vue-router
• Consider whether @shell should provide safe re-exports of composition API router utilities

📚 Relevant Resources

• [Vue Router — Composition API]((router.vuejs.org/redacted)
• [Vue 2.7 API Exposure Notes (ESM vs UMD)]((v2.vuejs.org/redacted)
• Related closed issue #10543 — ESM/UMD mismatch for defineComponent
• [Extension build configuration docs]((extensions.rancher.io/redacted)

Generated by Agentic Triage for issue #17718 · ● 462.9K · ◷

[rak-phillip]

I have some evidence that the instance of vue-router accessed via an extension is different from that of what is provided by shell. 77099bc demonstrates exposing createRouter to the window as an identity to be used for comparison between shell and an extension. After introducing this change in my environment, I performed the same comparison in the example extension. After confirming that the window object contains the probe, I produced the following result:

[shell] createRouter === window.__createRouterProbe: true [create.vue:5:1](webpack://test-router/node_modules/@rancher/shell/pages/c/_cluster/_product/_resource/create.vue)
[extension] createRouter === window.__createRouterProbe: false [limitrange.vue:5:1](webpack://test-router/pkg/test-router/edit/limitrange.vue)

[github-actions]

🤖 Issue grooming questions

Thanks for the detailed report and the test extension to reproduce the issue! The problem statement, technical context, and reproduction steps are clear. To complete grooming, the following is needed:

1. Missing: Acceptance Criteria

Please add a concrete, testable checklist defining what "fixed" looks like. For example:

• Extension components using the Composition API can call useRouter() and receive a valid router instance (not undefined) when loaded as a built/deployed extension.
• useRouter() behaviour in extensions matches the behaviour when running extensions locally in development.

2. Missing: Error details / stack trace

Could you share any relevant error messages from the browser console when useRouter() returns undefined? For example, the "console error" mentioned in the description — the full error text or stack trace would help pinpoint the root cause.

This comment was generated automatically to help gather the information needed to groom this issue.

Generated by Daily Issue Grooming · ● 544.8K · ◷

[github-actions]

🤖 Issue grooming questions

The issue has been reviewed again. The problem description, reproduction steps (including the test extension), and technical context remain clear. The two items previously requested are still not present in the issue body:

1. Still missing: Acceptance Criteria

Please add a concrete, testable checklist defining what "fixed" looks like. For example:

• Extension components using the Composition API can call useRouter() and receive a valid router instance (not undefined) when loaded as a built/deployed extension.
• useRouter() behaviour in built extensions matches the behaviour when running extensions locally in development mode.

2. Still missing: Error details

The description mentions "a console error" when useRouter() returns undefined. Could you paste the full error message or stack trace from the browser console? This will help confirm the root cause and scope the fix.

This comment was generated automatically to help gather the information needed to groom this issue.

Generated by Daily Issue Grooming · ● 310.5K · ◷