permafrost-dev
vue-ray
vue-ray
Debug Vue code with Ray to fix problems faster
Install this package in any Vue 3 project to send messages to the Ray app.
Installation
Install with npm:
npm install vue-rayor bun:
bun add vue-rayInstalling
When using in a Vue 3 project, you may optionally install the plugin globally in your main.js or app.js file. This is primarily useful if you want to cusomize the connection settings for the package.
import { RayPlugin } from 'vue-ray';
import { createApp } from 'vue';
import App from './App.vue';
const app = createApp(App);
app.use(RayPlugin, {
port: 23500,
host: 'localhost',
interceptErrors: true,
nodeRaySettings: {
interceptConsoleLog: true,
},
});Installation options
| Name | Type | Default | Description |
|---|---|---|---|
host |
string |
localhost |
host to connect to the Ray app on |
scheme |
string |
http |
URI scheme to use to connect to host |
interceptErrors |
boolean |
false |
send Vue errors to Ray |
port |
number |
23517 |
port to connect to the Ray app on |
nodeRaySettings |
object |
{} |
pass additional settings for node-ray (reference) |
Usage
To access the ray() function, import raySetup() from the vue-ray library:
<script setup>
import { raySetup } from 'vue-ray'
const ray = raySetup(); // `ray` is a ref, so you must use `ray.value` within the script tags
</script>The raySetup() function accepts an optional options object, defined as:
interface RaySetupOptions {
connection?: {
host?: string;
port?: number;
}
lifecycleEvents?: {
beforeCreate?: boolean;
beforeMount?: boolean;
created?: boolean;
mounted?: boolean;
unmounted?: boolean;
updated?: boolean;
all?: boolean;
}
}The lifecycleEvents object can be used to enable or disable sending of the component's lifecycle events to Ray. Use the all property to enable all lifecycle events.
The following example will send the created and mounted events to Ray for the component:
<script setup>
import { raySetup } from 'vue-ray'
const ray = raySetup({
lifecycleEvents: {
created: true,
mounted: true,
},
});
</script>The connection object can be used to specify the host and port to connect to the Ray app. The default values are localhost and 23517, respectively.
Sending data to Ray
Once you have called raySetup(), you may use the ray function in the Vue SFC as normal (see node-ray) to send data to Ray:
<template>
<div>
<button @click="ray('Hello from Vue!')">Send message to Ray</button>
<button @click="() => ray().html('<strong>hello with html!</strong>')">Send html message to Ray</button>
</div>
</template>See the node-ray reference for a complete list of available methods.
Vue-specific methods
| Name | Description |
|---|---|
ray().data() |
show the component data |
ray().props() |
show the component props |
ray().element(refName: string) |
render the HTML of an element with a ref of refName |
ray().track(name: string) |
display changes to a component's data variable (best used when not using script setup) |
ray().untrack(name: string) |
stop displaying changes to a component's data variable |
ray().watch(name: string, ref: Ref) |
watch a ref's value and send changes to Ray (best used in script setup) |
ray().unwatch(name: string) |
stop watching a ref's value and stop sending changes to Ray |
Watching refs
When using the script setup syntax, you can use the ray().watch(name, ref) method to watch a ref's value and send changes to Ray. Here's an example SFC using the script setup syntax:
<script setup>
import { ref } from 'vue';
import { raySetup } from 'vue-ray';
const one = ref(100);
const two = ref(22);
const ray = raySetup().value;
ray().watch('one', one);
ray().watch('two', two);
</script>
<template>
<div>
<div>{{ one }}</div>
<div>{{ two }}</div>
<button @click="one += 3">Increment one</button>
<button @click="two += 3">Increment two</button>
</div>
</template>Tracking component data
When not using the script setup syntax, you can use the ray().track(name) method to track changes to a component's data variable. Here's an example SFC:
<script>
import { raySetup } from 'vue-ray';
let ray;
export default {
props: ['title'],
data() {
return {
one: 100,
two: 22,
};
},
created() {
// must call raySetup() in the created() lifecycle hook so it can access the current component
ray = raySetup().value;
ray().track('one');
},
methods: {
sendToRay() {
ray().element('div1');
},
increment() {
this.one += 3;
this.two += 5;
}
}
};
</script>
<template>
<div class="flex-col border-r border-gray-200 bg-white overflow-y-auto w-100">
<div ref="div1" class="w-full flex flex-wrap">
<div ref="div1a" class="w-4/12 inline-flex">{{ one }}</div>
<div ref="div1b" class="w-4/12 inline-flex">{{ two }}</divr>
</div>
<div class="about">
<h1>{{ title }}</h1>
<a @click="sendToRay()">send ref to ray</a><br>
<a @click="increment()">increment data var</a><br>
</div>
</div>
</template>When either tracking data or watching a ref, you will notice that the entry in Ray updates in real-time as the data changes, instead of creating a new entry each time the >data changes.
Intercepting errors
Use the interceptErrors option to intercept errors and send them to Ray:
app.use(RayPlugin, { interceptErrors: true });Development setup
npm install
npm run testDevelopment Builds
npm run build:devThis will build the package in development mode, and writes to the dist-temp directory.
Production Builds
npm run build:distThis will build the package in production mode, and writes to the dist directory.
Code Coverage Details
Testing
vue-ray uses Vitest for unit tests. To run the test suite, run the following command:
npm run test...or run with coverage:
npm run test:coverageChangelog
Please see CHANGELOG for more information on what has changed recently.
Contributing
Please see CONTRIBUTING for details.
Security Vulnerabilities
Please review our security policy on how to report security vulnerabilities.
Credits
License
The MIT License (MIT). Please see License File for more information.