{"_id":"@arms/rum-browser-nuxt","_rev":"2-83168e2221dc8b8e438c984410d9f169","name":"@arms/rum-browser-nuxt","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@arms/rum-browser-nuxt","version":"0.1.0","keywords":["rum","real-user-monitoring","arms","nuxt","nuxt3","nuxt4","vue","vue-router","error-tracking","monitoring"],"author":{"name":"guangli.fj","email":"guangli.fj@alibaba-inc.com"},"license":"ISC","_id":"@arms/rum-browser-nuxt@0.1.0","maintainers":[{"name":"fengsir","email":"fengsir@live.com"},{"name":"yunjin4","email":"xiashujin.xsj@alibaba-inc.com"},{"name":"guangli.fj","email":"guangli.fj@alibaba-inc.com"},{"name":"yangling1996","email":"yl260087@alibaba-inc.com"},{"name":"yunyi-alibaba","email":"ly403664@alibaba-inc.com"},{"name":"alibaba_rum_harmony","email":"yanglanxin.ylx@alibaba-inc.com"}],"dist":{"shasum":"dce89265c946151bbd81ff01a28a67e2af188375","tarball":"https://registry.npmjs.org/@arms/rum-browser-nuxt/-/rum-browser-nuxt-0.1.0.tgz","fileCount":35,"integrity":"sha512-wOTR7vYFcE5YjxfJ6eq34fbb8NcgRuAVGY0Fo8GbEj/siJTsnbjDQ6S+GSWwySCF15tGRD2vSTFKEbu2G79BOQ==","signatures":[{"sig":"MEYCIQDvkFlRCkM+Rx2SjkVWbMO42ifck2EQxmxY9x6s5kq6tAIhAJ0YfomFxBeSvuQsylmvxKeKDXPxqbaAD8ybcDutl1h/","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":71186},"main":"lib/index.js","types":"es/index.d.ts","module":"es/index.js","exports":{".":{"types":"./es/index.d.ts","import":"./es/index.js","default":"./es/index.js","require":"./lib/index.js"},"./package.json":"./package.json"},"gitHead":"46c3211d4300953fe4e8490a6e5649d75dabc46f","scripts":{"test":"jest --config jest.config.js --no-watchman","build":"build-scripts build --skip-demo","prepublishOnly":"npm run build"},"_npmUser":{"name":"guangli.fj","email":"guangli.fj@alibaba-inc.com"},"_npmVersion":"10.9.8","description":"Nuxt plugin for @arms/rum-browser SDK (Nuxt 3/4 file-route view tracking + dual-channel error capture, zero nuxt/vue/vue-router imports)","directories":{},"sideEffects":false,"_nodeVersion":"22.22.3","browserslist":["last 2 Chrome versions","last 2 Safari versions","last 2 Firefox versions","last 2 Edge versions","iOS >= 14","Android >= 8"],"dependencies":{},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^4.9.4"},"peerDependencies":{"vue":"^3.5.0","nuxt":"3 || 4","vue-router":"^4.0.0 || ^5.0.0","@arms/rum-core":">=0.1.11","@arms/rum-browser":">=0.1.16"},"peerDependenciesMeta":{"vue":{"optional":true},"nuxt":{"optional":true},"vue-router":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/rum-browser-nuxt_0.1.0_1788266320719_0.42728521350991855","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@arms/rum-browser-nuxt","version":"0.1.1","description":"Nuxt plugin for @arms/rum-browser SDK (Nuxt 3/4 file-route view tracking + dual-channel error capture, zero nuxt/vue/vue-router imports)","author":{"name":"guangli.fj","email":"guangli.fj@alibaba-inc.com"},"license":"ISC","main":"lib/index.js","module":"es/index.js","types":"es/index.d.ts","exports":{".":{"types":"./es/index.d.ts","import":"./es/index.js","require":"./lib/index.js","default":"./es/index.js"},"./package.json":"./package.json"},"keywords":["rum","real-user-monitoring","arms","nuxt","nuxt3","nuxt4","vue","vue-router","error-tracking","monitoring"],"sideEffects":false,"publishConfig":{"access":"public"},"scripts":{"build":"build-scripts build --skip-demo","test":"jest --config jest.config.js --no-watchman","prepublishOnly":"npm run build"},"dependencies":{},"peerDependencies":{"@arms/rum-core":">=0.1.11","@arms/rum-browser":">=0.1.16","nuxt":"3 || 4","vue":"^3.5.0","vue-router":"^4.0.0 || ^5.0.0"},"peerDependenciesMeta":{"nuxt":{"optional":true},"vue":{"optional":true},"vue-router":{"optional":true}},"devDependencies":{"typescript":"^4.9.4"},"browserslist":["last 2 Chrome versions","last 2 Safari versions","last 2 Firefox versions","last 2 Edge versions","iOS >= 14","Android >= 8"],"_id":"@arms/rum-browser-nuxt@0.1.1","gitHead":"e4f9f22c4374aa577f7361ece27ecaf66f7ddff9","_nodeVersion":"22.22.3","_npmVersion":"10.9.8","dist":{"integrity":"sha512-AQPAYzdzu6jaeHAytLDTmS54vUrxX+L4QgSrwZDcwmpzWSC3KHfpO5H609oLrvaKQHDuCU6DpwGyTXK6Faiz8A==","shasum":"6e2dd7f7035d6baef0e7bf9bf4e23db28da09110","tarball":"https://registry.npmjs.org/@arms/rum-browser-nuxt/-/rum-browser-nuxt-0.1.1.tgz","fileCount":35,"unpackedSize":70608,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCICzfKvZJgOPJ2FE5wPZpE1MHvGNXfbo3bJFCffTxupzgAiEAoR9o3fwSNPvPKouajikgRX3xGvZBmlWbX2/QLe4MxlQ="}]},"_npmUser":{"name":"guangli.fj","email":"guangli.fj@alibaba-inc.com"},"directories":{},"maintainers":[{"name":"fengsir","email":"fengsir@live.com"},{"name":"yunjin4","email":"xiashujin.xsj@alibaba-inc.com"},{"name":"guangli.fj","email":"guangli.fj@alibaba-inc.com"},{"name":"yangling1996","email":"yl260087@alibaba-inc.com"},{"name":"yunyi-alibaba","email":"ly403664@alibaba-inc.com"},{"name":"alibaba_rum_harmony","email":"yanglanxin.ylx@alibaba-inc.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/rum-browser-nuxt_0.1.1_1788269539912_0.7435748279500216"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-01T12:38:40.460Z","modified":"2026-09-01T13:32:20.203Z","0.1.0":"2026-09-01T12:38:40.849Z","0.1.1":"2026-09-01T13:32:20.057Z"},"author":{"name":"guangli.fj","email":"guangli.fj@alibaba-inc.com"},"license":"ISC","keywords":["rum","real-user-monitoring","arms","nuxt","nuxt3","nuxt4","vue","vue-router","error-tracking","monitoring"],"description":"Nuxt plugin for @arms/rum-browser SDK (Nuxt 3/4 file-route view tracking + dual-channel error capture, zero nuxt/vue/vue-router imports)","maintainers":[{"name":"fengsir","email":"fengsir@live.com"},{"name":"yunjin4","email":"xiashujin.xsj@alibaba-inc.com"},{"name":"guangli.fj","email":"guangli.fj@alibaba-inc.com"},{"name":"yangling1996","email":"yl260087@alibaba-inc.com"},{"name":"yunyi-alibaba","email":"ly403664@alibaba-inc.com"},{"name":"alibaba_rum_harmony","email":"yanglanxin.ylx@alibaba-inc.com"}],"readme":"# @arms/rum-browser-nuxt\n\nNuxt 插件 for `@arms/rum-browser` RUM SDK —— 支持 **Nuxt 3 / Nuxt 4**（Vue 3.5+、vue-router v4 / v5）。\n\n能力范围：\n\n- **文件路由风格的视图追踪**：经 `router.afterEach` 驱动 `Shell.startView`（手动 view 模式），view.name 反向归一化为 Nuxt 文件路由风格（`/user/:id()` → `/user/[id]`），与 `pages/` 目录心智一致、聚合稳定\n- **Nuxt 双通道异常捕获**：链式包装 `vueApp.config.errorHandler`（保留原 handler）+ `nuxtApp.hook('app:error')`（Nuxt 启动 / SSR 传播错误），同一错误对象 WeakSet 去重只报一次，自动上报 `source: 'vue'` 的异常事件（`snapshots` 内携带 `framework: 'nuxt'`）\n- **手动错误上报**：`addNuxtError(error, context?)` 供 `onErrorCaptured` / 自定义 errorHandler 场景转发\n\n> 不含：组件性能监控、hydration 错误分级、Nuxt Module 形态、Nitro 服务端集成（均为非目标，见 docs-dev/browser-nuxt-spec.md）。\n\n## 安装\n\n本插件不独立工作 —— 需与主包 `@arms/rum-browser`（必需 peer dependency）同时安装，并完成主包初始化：\n\n```bash\nnpm install @arms/rum-browser @arms/rum-browser-nuxt\n```\n\n## 发布前置条件\n\n发布顺序（严格按序，前一步发版在 registry 生效后，再发布下一步）：\n\n1. **`@arms/rum-core@>=0.1.11`**：含 `Shell.startView` 与 `IConfiguration.trackViewsManually` 能力的发版（已在 npm registry 发布）\n2. **`@arms/rum-browser@>=0.1.16`**：含 PvCollector 手动模式防护（`trackViewsManually` 早退，避免双发 PV）的发版（已在 npm registry 发布）\n3. **`@arms/rum-browser-nuxt`**（本包）\n\n本包为独立实现（不依赖 `@arms/rum-browser-vue` / `@arms/rum-browser-react`，dependencies 为空），无兄弟包解锁约束；peerDependencies 下限与 registry 实际产物对齐，外部安装可正常解析。后续版本迭代仍需遵循上述发布顺序（依赖包发版在 registry 生效后，再发布本包）。仓库内开发期经 workspace 直链源码使用（无需等待发版），安装依赖请遵循仓库惯例使用 `yarn` 或 `scripts/bootstrap.sh`。\n\n## 快速开始\n\n在 Nuxt 项目中创建客户端插件文件（`.client.ts` 后缀保证仅在客户端执行）：\n\n```ts\n// plugins/arms-rum.client.ts\nimport ArmsRum from '@arms/rum-browser';\nimport { initNuxtPlugin } from '@arms/rum-browser-nuxt';\n\nexport default defineNuxtPlugin({\n name: 'arms-rum',\n // enforce: 'pre' 保证本插件先于其他插件执行，\n // 错误双通道可捕获后续插件的启动错误\n enforce: 'pre',\n setup() {\n ArmsRum.init({\n endpoint: 'https://your-endpoint',\n // pid: 'your-pid',\n });\n initNuxtPlugin(ArmsRum, {\n router: useRouter(), // 必填：驱动视图采集\n nuxtApp: useNuxtApp(), // 推荐：启用错误双通道\n });\n },\n});\n```\n\n> **时序说明**：`initNuxtPlugin` 不依赖 `armsRum.init()` 完成 —— 可在 init 前后任意时序同步调用，先后顺序可互换（反向时序经内部 pending 队列兜底，首屏 view 与排队错误不丢失）。`defineNuxtPlugin` / `useRouter` / `useNuxtApp` 均为 Nuxt 自动导入 —— 本包源码零 nuxt / vue / vue-router 导入（SSR-safe），router / nuxtApp 由用户在 `setup()` 中取好后传入。\n\n## 视图命名规则\n\nview.name 按 `to.matched` **尾向头**取第一个非空 `path`（最深匹配段即页面本身的模板），再反向归一化为 Nuxt 文件路由风格：\n\n| vue-router 路由模板（matched.path） | view.name（Nuxt 文件路由风格） | 对应 pages/ 目录 |\n| -------------------------------------- | ------------------------------ | ------------------------------ |\n| `/users` | `/users` | `pages/users.vue` |\n| `/user/:id()` | `/user/[id]` | `pages/user/[id].vue` |\n| `/blog/:slug?` | `/blog/[[slug]]` | `pages/blog/[[slug]].vue` |\n| `/:slug(.*)*` | `/[...slug]` | `pages/[...slug].vue` |\n| `/:pathMatch(.*)*` | `/[...pathMatch]` | `pages/[...pathMatch].vue` |\n| `/users-:group()-:id()` | `/users-[group]-[id]` | `pages/users-[group]-[id].vue` |\n| 嵌套路由（父 `''` + 子 `/user/:id()`） | `/user/[id]`（尾向头取最深段） | `pages/user/[id].vue` |\n\n静态路由原样保留；转义字符还原为字面量（`\\:` → `:`）。\n\n## 路由语义\n\n> **警告：`router` 必填 —— 传入后 view/PV 完全由 `afterEach` 驱动，主包自动 PV 被禁用**\n>\n> 插件在 `nuxtCollector.setup` 中注入 `trackViewsManually: true`：主包 PvCollector 跳过首屏 PV 与 history 拦截（避免双发），view 的创建、命名、计时**完全依赖** `router.afterEach` 驱动（内部调用 `shell.startView`）。\n\n导航语义（对齐 Nuxt 场景约定）：\n\n| 导航场景 | 是否开新视图 | 说明 |\n| ------------------------------------ | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |\n| 首次导航 / 首屏 | ✅ | `initial_load`；init 前触发经 pending 队列补发 |\n| 路径变化 | ✅ | `route_change`（ctx 已有 view 时；否则 `initial_load`） |\n| **query 变化**（path 与 hash 不变） | ❌ 跳过 | `/list?page=1` → `/list?page=2` 不算新视图 |\n| **hash 变化**（path 不变） | ❌ 去重 | `/doc#section-a` → `/doc#section-b` afterEach 放行但视图名不变，经 `Shell.startView` 同名去重后无新 view 事件（与 browser-vue 行为一致） |\n| 导航失败（afterEach 第三参 failure） | ❌ 跳过 | guard 拦截 / 取消等不算新视图 |\n| 同名重复导航 | ❌ 去重 | `Shell.startView` 内建同名去重 |\n\n## 异常捕获说明\n\n`nuxtApp` 传入时启用双通道自动接管：\n\n- **通道 1**：链式包装 `nuxtApp.vueApp.config.errorHandler` —— 先经 `addNuxtError` 上报，再调用你已有的 handler（保留 Nuxt 自带 `handleVueError` 驱动错误页的行为；无原 handler 时保持 Vue 默认的 `console.error` 可见性，不吞错）\n- **通道 2**：`nuxtApp.hook('app:error')` 捕获 Nuxt 启动 / SSR 传播错误（纯 Vue 场景不存在的 Nuxt 独有通道；插件 `enforce: 'pre'` 时可捕获后续插件启动错误）\n- **去重**：同一错误对象（引用相等）经双通道只报一次（WeakSet）；非 object 错误值无引用语义，不去重\n\n上报字段：\n\n```ts\n{\n event_type: 'exception',\n type: 'error',\n source: 'vue', // 复用家族 vue 错误存储/查询链路\n name: 'TypeError', // error.name（非 Error 值自动 normalize）\n message: \"Cannot read properties of undefined\",\n stack: '...',\n // 扩展信息收敛为单一 JSON 字符串字段（值为 undefined 的内部键不会出现）\n snapshots: JSON.stringify({\n handling: 'handled',\n framework: 'nuxt', // 本包标识，恒定携带\n component_stack: 'at \\nat ', // 当前组件在前，沿父链向上\n component_name: 'OrderList',\n lifecycle_hook: 'hook:mounted', // Vue errorHandler 的 info 参数\n }),\n times: 1,\n}\n```\n\n也可在 `onErrorCaptured` / 自定义 errorHandler 中手动上报（双通道已接管时无需重复调用）：\n\n```ts\nimport { addNuxtError } from '@arms/rum-browser-nuxt';\n\n// 组件内\nonErrorCaptured(function (err, instance, info) {\n addNuxtError(err, { lifecycle_hook: info });\n return false;\n});\n```\n\n## API\n\n### 主入口 `@arms/rum-browser-nuxt`（单入口，无子入口）\n\n| 导出 | 说明 |\n| ---------------------------------------------------------- | ---------------------------------------------------------------------------------- |\n| `initNuxtPlugin(shell: Shell, options: NuxtPluginOptions)` | 初始化插件（collector 注册 + 路由视图采集 + 条件启用错误双通道） |\n| `addNuxtError(error: unknown, context?: NuxtErrorContext)` | 手动上报 Nuxt 异常（`component_stack` / `component_name` / `lifecycle_hook` 可选） |\n| `type NuxtPluginOptions` / `NuxtErrorContext` 等 | 公共类型（duck typing，版本无关） |\n\n### `NuxtPluginOptions`\n\n`initNuxtPlugin(shell, options)` 的第二参数（源 `src/types/index.ts`）：\n\n| 字段 | 类型 | 必填 | 说明 |\n| --------- | ------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `router` | `AnyRouter` | 是 | vue-router 实例（v4 / v5 均可，`useRouter()` 取得，仅依赖 `afterEach` / `currentRoute` 最小接口）。驱动 view 生命周期（手动 view 模式：注入 `trackViewsManually` + 调用 `Shell.startView`） |\n| `nuxtApp` | `NuxtAppLike` | 否 | NuxtApp 实例（`useNuxtApp()` 取得）。提供时启用错误双通道自动接管；不提供时仅启用路由视图采集，错误可经 `addNuxtError` 手动上报 |\n\n### `NuxtErrorContext`\n\n`addNuxtError` 的第二参数（字段对齐 `@arms/rum-browser-vue` 的 `VueErrorContext`）：\n\n| 字段 | 类型 | 说明 |\n| ----------------- | -------- | ----------------------------------------------------------------------------------- |\n| `component_stack` | `string` | 组件链栈，如 `'at \\nat '`（当前组件在前） |\n| `component_name` | `string` | 出错组件名 |\n| `lifecycle_hook` | `string` | 生命周期钩子 / 错误来源信息（Vue errorHandler 的 `info` 参数，如 `'hook:mounted'`） |\n\n## 版本要求\n\n| 依赖 | 版本要求 | 说明 |\n| ------------------- | -------------------- | ------------------------------------------------------------------------------------------------ |\n| `@arms/rum-core` | `>=0.1.11` | 含 `Shell.startView` 与 `IConfiguration.trackViewsManually`（已发布） |\n| `@arms/rum-browser` | `>=0.1.16` | 含 PvCollector 手动模式防护（已发布） |\n| `nuxt` | `3（>=3.7）\\|\\| 4` | optional peer；3.7 起 `defineNuxtPlugin` 对象语法与 `enforce` 稳定 |\n| `vue` | `^3.5.0` | optional peer；本包经 `nuxtApp.vueApp.config.errorHandler` duck typing 访问，不直接依赖 vue 模块 |\n| `vue-router` | `^4.0.0 \\|\\| ^5.0.0` | optional peer；仅依赖 `afterEach` / `currentRoute` 最小接口 |\n\n> **版本口径说明**：peerDependencies 中 `nuxt` 声明为 `3 || 4`，实际支持基线为 Nuxt ≥3.7 —— 更早版本的 `defineNuxtPlugin` 对象语法与 `enforce` 不稳定。`vue` peer 为 `^3.5.0`，而 Nuxt 3.7-3.12 生态常配 vue 3.3 / 3.4 —— 三项框架 peer 均 optional（`peerDependenciesMeta` 标记），版本不满足仅产生安装告警、不阻塞安装（插件对框架实例 duck typing，实际兼容宽于声明口径）。\n\n### Nuxt 2 用户\n\nNuxt 2 / Vue 2 已 EOL（插件体系完全不同），本包不支持。请使用通用包 `@arms/rum-browser`（自动 PV + 全局异常采集，无 Nuxt 专属能力），或升级到 Nuxt 3 后接入本包。\n\n## 已知限制\n\n> 以下限制是当前 MVP 设计所固有的，后续版本计划改进。\n\n### 单实例约束\n\n插件为 collector 级单例（模块级状态持有 shell / ctx 引用）。重复调用 `initNuxtPlugin` 传入**另一个** rum 实例时会打印 `logger.warn` 并跳过重复注册、仅刷新 shell 引用 —— 最后一次绑定的实例生效。微前端多子应用各自持有独立 RUM 实例的场景暂不支持。\n\n### `source='vue'` 错误不受 `collectors.jsError` 采样管控\n\n本包上报的错误携带 `source: 'vue'`，browser SDK 的 `SessionProcessor` 采样键映射当前不覆盖 `'vue'`（与 browser-vue 包同款已知约束）——这些错误会绕过 `collectors.jsError` 采样配置。如需禁用，请使用 `collectors.exception`（设置为 `false`）。另外，core reporter 对 exception 按 `getErrorID(message + stack)` 聚合且 key 不含 source —— 同一错误被全局通道与插件双通道捕获时会聚合合并；自动通道错误可经 `filters.exception` 过滤以保留富上下文事件。\n\n### errorHandler 覆盖边界\n\n- **组件 `onErrorCaptured` 返回 `false`**：按 Vue 语义该错误被视为\"已处理\"并阻止传播，全局 `errorHandler` 不会触发 —— 插件捕获不到（Vue 框架行为）；需观测时请在 `onErrorCaptured` 中手动调用 `addNuxtError`；\n- **`warnHandler` 不覆盖**：Vue 运行时警告不进入 RUM 异常事件；\n- **`unhandledrejection`**：由主包 `@arms/rum-browser` 的 jsError 采集器覆盖，无需本插件处理；\n- **hydration mismatch 明细**：Vue errorHandler 不捕获（vuejs/core#13154），不做监控承诺。\n\n### 错误页为全新页面加载\n\nNuxt 渲染 `error.vue` 属全新页面加载，插件与会话上下文随之重置 —— 错误后首屏 view 重新计为 `initial_load`。\n\n### 无 `pages/` 目录的应用\n\n仅单 `app.vue` 的 Nuxt 应用没有路由实例，插件因缺少有效 `router` 整体禁用（`logger.error` 自监控上报），仅 `addNuxtError` 手动错误上报可用。\n\n### 错误去重窗口语义\n\n双通道去重按 app 生命周期（WeakSet 按错误对象引用）—— 同一 `Error` 实例二次抛出会被去重丢弃。\n\n### 初始化时序\n\n`initNuxtPlugin` 可在 `armsRum.init()` 前后任意时序同步调用。初始化完成之前调用 `addNuxtError` 时安全降级：插件未接入则 warn + skip（不抛错）；插件已接入但 init 未完成则排队，init 完成后自动补发。init 前触发的路由导航经 pending 队列兜底，collector setup 后自动补发首个 view（`loading_type: 'initial_load'`），首屏不丢失。\n\n## 兼容性\n\n| 环境 | 支持情况 | 说明 |\n| --------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Vite / webpack 5 等 | ✅ | 经 `exports` 字段解析单入口（types / import / require / default 四条件） |\n| SSR（Nuxt 服务端） | ✅ 安全 | 源码零 nuxt / vue / vue-router 导入、零顶层 `window` / `document` 访问（唯一 DOM 触点 `getCurrentUrl` 在函数内 try-catch 防护）；配合 `.client.ts` 后缀约定使用 |\n| CDN / `