Vue Ray Debugger

Common errors

• TypeError: (0 , vue_ray__WEBPACK_IMPORTED_MODULE_2__.RayPlugin) is not a function

  cause Attempting to use `RayPlugin` in a project with `vue-ray` v2.0.1 or v2.0.2, where the export was temporarily broken.
  fix Upgrade `vue-ray` to version 2.0.3 or newer to resolve the missing export.

• Error: require() of ES Module ... vue-ray/dist/index.mjs not supported.

  cause Using CommonJS `require()` syntax to import `vue-ray` v2.x, which is an ESM-first package.
  fix Switch to ES Module `import` syntax: `import { RayPlugin } from 'vue-ray';`.

• TypeError: ray is not a function

  cause Attempting to call the `ray` instance directly after getting it from `raySetup()` without accessing its `.value` property.
  fix Remember that `raySetup()` returns a Vue `Ref`. Access the debugging function via `ray.value()`, e.g., `ray.value().log('message')`.

Warnings

• breaking Vue 2 support was dropped in `vue-ray` v2.x. This package is now exclusively for Vue 3 applications.
  Fix: Migrate your application to Vue 3 or use `vue-ray` v1.x for Vue 2 projects.
• breaking `vue-ray` v2.x requires Node.js version 18 or higher. Projects running on older Node.js versions will encounter errors.
  Fix: Update your Node.js environment to version 18 or newer.
• breaking `vue-ray` v2.x is now an ESM-first package. Direct `require()` statements for CommonJS environments will fail.
  Fix: Use ES Module `import` syntax (`import { ... } from 'vue-ray';`). Ensure your project's build configuration correctly handles ESM modules.
• gotcha 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.
  Fix: Always call `ray.value().<method>()` instead of `ray().<method>()`.
• gotcha The `RayPlugin` export was missing in `vue-ray` versions 2.0.1 and 2.0.2, preventing global plugin installation.
  Fix: Upgrade to `vue-ray` v2.0.3 or higher to ensure `RayPlugin` is correctly exported and available.

Install

• npm install vue-ray npm
• yarn add vue-ray yarn
• pnpm add vue-ray pnpm

Imports

• RayPlugin
  wrong:

  const { RayPlugin } = require('vue-ray');

  correct:

  import { RayPlugin } from 'vue-ray';

  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.
• raySetup
  wrong:

  const { raySetup } = require('vue-ray');

  correct:

  import { raySetup } from 'vue-ray';

  Used within Vue's `<script setup>` components to obtain the `ray` debugging instance. ESM-only since v2.0.1.
• ray().log
  wrong:

  import { ray } from 'vue-ray'; ray().log('message');

  correct:

  const ray = raySetup(); ray.value().log('message');

  The `ray` instance is returned as a Vue `Ref` from `raySetup()`. You must access its `.value` property to call the actual `ray()` function.

Quickstart

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.

import { createApp, ref, onMounted } from 'vue';
import App from './App.vue';
import { RayPlugin, raySetup } from 'vue-ray';

// main.ts or main.js
const app = createApp(App);

app.use(RayPlugin, {
    port: 23517, // Default Ray app port
    host: 'localhost',
    interceptErrors: true, // Send Vue errors to Ray
    nodeRaySettings: {
        interceptConsoleLog: true // Also send console.log messages to Ray
    }
});

app.mount('#app');

// src/components/MyComponent.vue (using <script setup>)
<template>
  <div>
    <h1>{{ msg }}</h1>
    <button @click="triggerRay">Send to Ray</button>
  </div>
</template>

<script setup lang="ts">
const msg = ref('Hello Vue Ray!');
const ray = raySetup({
    lifecycleEvents: {
        created: true, // Send 'created' event to Ray
        mounted: true  // Send 'mounted' event to Ray
    }
});

onMounted(() => {
    // Access the ray function via ray.value()
    ray.value().log('MyComponent mounted!').data({ message: msg.value });
});

function triggerRay() {
    ray.value().html('<i>Button clicked from component!</i>').label('interaction');
    try {
        // Simulate an error
        throw new Error('Example error from component!');
    } catch (e: any) {
        // If interceptErrors is true in plugin, this will go to Ray automatically
        // You can also manually send it:
        ray.value().exception(e);
    }
}
</script>