{"id":15916,"library":"vue-ray","title":"Vue Ray Debugger","description":"vue-ray is a utility designed for debugging Vue 3 applications by sending debugging information to the desktop Ray app. Currently at version 2.0.3, the package maintains an active release cadence, with notable updates including a major rewrite in v2.0.1. This rewrite transitioned the package to an ESM-first architecture and removed support for Vue 2 and Node.js versions below 18. It offers two primary integration methods: a global `RayPlugin` for application-wide configuration and a `raySetup()` composable for `<script setup>` contexts. The package's key differentiator is its seamless integration with the commercial Ray debugging application, providing a dedicated GUI for inspecting data, component lifecycle events, and errors, offering a richer debugging experience than traditional `console.log` methods.","status":"active","version":"2.0.3","language":"javascript","source_language":"en","source_url":"https://github.com/permafrost-dev/vue-ray","tags":["javascript","vue","ray","debug","typescript","permafrost","spatie"],"install":[{"cmd":"npm install vue-ray","lang":"bash","label":"npm"},{"cmd":"yarn add vue-ray","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-ray","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core dependency for sending data to the Ray app; vue-ray wraps and configures it internally.","package":"node-ray","optional":false}],"imports":[{"note":"Used for global plugin installation in `main.ts` or `app.ts`. Since v2.0.1, vue-ray is ESM-first, so CommonJS `require()` is not supported. Also, it's a named export.","wrong":"const { RayPlugin } = require('vue-ray');","symbol":"RayPlugin","correct":"import { RayPlugin } from 'vue-ray';"},{"note":"Used within Vue's `<script setup>` components to obtain the `ray` debugging instance. ESM-only since v2.0.1.","wrong":"const { raySetup } = require('vue-ray');","symbol":"raySetup","correct":"import { raySetup } from 'vue-ray';"},{"note":"The `ray` instance is returned as a Vue `Ref` from `raySetup()`. You must access its `.value` property to call the actual `ray()` function.","wrong":"import { ray } from 'vue-ray'; ray().log('message');","symbol":"ray().log","correct":"const ray = raySetup(); ray.value().log('message');"}],"quickstart":{"code":"import { createApp, ref, onMounted } from 'vue';\nimport App from './App.vue';\nimport { RayPlugin, raySetup } from 'vue-ray';\n\n// main.ts or main.js\nconst app = createApp(App);\n\napp.use(RayPlugin, {\n    port: 23517, // Default Ray app port\n    host: 'localhost',\n    interceptErrors: true, // Send Vue errors to Ray\n    nodeRaySettings: {\n        interceptConsoleLog: true // Also send console.log messages to Ray\n    }\n});\n\napp.mount('#app');\n\n// src/components/MyComponent.vue (using <script setup>)\n<template>\n  <div>\n    <h1>{{ msg }}</h1>\n    <button @click=\"triggerRay\">Send to Ray</button>\n  </div>\n</template>\n\n<script setup lang=\"ts\">\nconst msg = ref('Hello Vue Ray!');\nconst ray = raySetup({\n    lifecycleEvents: {\n        created: true, // Send 'created' event to Ray\n        mounted: true  // Send 'mounted' event to Ray\n    }\n});\n\nonMounted(() => {\n    // Access the ray function via ray.value()\n    ray.value().log('MyComponent mounted!').data({ message: msg.value });\n});\n\nfunction triggerRay() {\n    ray.value().html('<i>Button clicked from component!</i>').label('interaction');\n    try {\n        // Simulate an error\n        throw new Error('Example error from component!');\n    } catch (e: any) {\n        // If interceptErrors is true in plugin, this will go to Ray automatically\n        // You can also manually send it:\n        ray.value().exception(e);\n    }\n}\n</script>\n","lang":"typescript","description":"This quickstart demonstrates both global `RayPlugin` installation for app-wide settings and component-level `raySetup()` usage in a `<script setup>` component to send data, lifecycle events, and interactive messages to the Ray desktop debugger."},"warnings":[{"fix":"Migrate your application to Vue 3 or use `vue-ray` v1.x for Vue 2 projects.","message":"Vue 2 support was dropped in `vue-ray` v2.x. This package is now exclusively for Vue 3 applications.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Update your Node.js environment to version 18 or newer.","message":"`vue-ray` v2.x requires Node.js version 18 or higher. Projects running on older Node.js versions will encounter errors.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Use ES Module `import` syntax (`import { ... } from 'vue-ray';`). Ensure your project's build configuration correctly handles ESM modules.","message":"`vue-ray` v2.x is now an ESM-first package. Direct `require()` statements for CommonJS environments will fail.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Always call `ray.value().<method>()` instead of `ray().<method>()`.","message":"When using `raySetup()` in `<script setup>`, the returned `ray` variable is a Vue `Ref`. You must access its `.value` property to call the actual `ray()` debugging function.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Upgrade to `vue-ray` v2.0.3 or higher to ensure `RayPlugin` is correctly exported and available.","message":"The `RayPlugin` export was missing in `vue-ray` versions 2.0.1 and 2.0.2, preventing global plugin installation.","severity":"gotcha","affected_versions":">=2.0.1 <2.0.3"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Upgrade `vue-ray` to version 2.0.3 or newer to resolve the missing export.","cause":"Attempting to use `RayPlugin` in a project with `vue-ray` v2.0.1 or v2.0.2, where the export was temporarily broken.","error":"TypeError: (0 , vue_ray__WEBPACK_IMPORTED_MODULE_2__.RayPlugin) is not a function"},{"fix":"Switch to ES Module `import` syntax: `import { RayPlugin } from 'vue-ray';`.","cause":"Using CommonJS `require()` syntax to import `vue-ray` v2.x, which is an ESM-first package.","error":"Error: require() of ES Module ... vue-ray/dist/index.mjs not supported."},{"fix":"Remember that `raySetup()` returns a Vue `Ref`. Access the debugging function via `ray.value()`, e.g., `ray.value().log('message')`.","cause":"Attempting to call the `ray` instance directly after getting it from `raySetup()` without accessing its `.value` property.","error":"TypeError: ray is not a function"}],"ecosystem":"npm"}