Skip to content

permafrost-dev/vue-ray

Repository files navigation

vue-ray

vue-ray

npm version npm downloads license test status

vue-ray

Debug Vue code with Ray to fix problems faster

Install this package in any Vue 2 or Vue 3 project to send messages to the Ray app. It also includes a Vuex plugin to monitor changes to the Vuex state.

Installation

Install with npm:

npm install vue-ray

or yarn:

yarn add vue-ray

Installing in Vue 3

When using in a Vue 3.x project (the default), import the package:

import { createApp } from 'vue';
import App from './App.vue';

// as an es module import:
import { RayPlugin } from 'vue-ray';

// or as a commonjs import:
const { RayPlugin } = require('vue-ray');

const app = createApp(App);

app.use(RayPlugin, { 
    interceptErrors: true,
    port: 23500,
    showComponentEvents: ['created', 'mounted'],
    nodeRaySettings: { 
        interceptConsoleLog: true,
    },
});

Installing in Vue 2

When using in a Vue 2.x project, import the 'vue2' variant:

const Vue = require('vue');

// as an es module import:
import { RayPlugin } from 'vue-ray/vue2';

// or as a commonjs import:
const { RayPlugin } = require('vue-ray/vue2');

Vue.use(RayPlugin, { 
    interceptErrors: true,
    host: '127.0.0.1',
    showComponentEvents: ['mounted'],
    nodeRaySettings: {
        interceptConsoleLog: false,
    },
});

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
showComponentEvents string[] [] display component events in Ray, see below for possible values
nodeRaySettings object {} pass additional settings for node-ray (reference)

Component events

Component lifecycle events can be sent to Ray using the showComponentEvents plugin option (array).

Use any of the following values with this option:

  • before-create
  • before-mount
  • created
  • mounted
  • unmounted
  • updated

Usage

Once the plugin is installed, you may access the ray() method on this as this.$ray().

See the node-ray reference for a complete list of available methods.

Vue-specific methods

Name Description
this.$ray().data() show the component data
this.$ray().props() show the component props
this.$ray().ref(name) show the innerHTML of a named ref
this.$ray().track(name) display changes to a component's data variable
this.$ray().untrack(name) stop displaying changes to a component's data variable

Tracking component data

Changes to any component's data variables can be tracked and displayed in real-time using the track(name) method.

<script>
export default {
    props: ['title'],
    data() {
        return {
            one: 100,
            two: 22,
        };
    },
    created() {
        this.$ray().data();
        this.$ray().track('one');
    },
    mounted() {
        setInterval(() => {
            this.one += 3;
        }, 4000);
    },
};
</script>

Example Component

<template>
    <div class="flex-col border-r border-gray-200 bg-white overflow-y-auto w-100">
        <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 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>
</template>

<script>
export default {
    props: ['title'],
    data() {
        return {
            one: 100,
            two: 22,
        };
    },
    created() {
        this.$ray().data();
        this.$ray().track('one');
    },
    methods: {
        sendToRay() {
            this.$ray().ref('div1');
        },
        increment() {
            this.one += 3;
        }
    }
};
</script>

Intercepting errors (Vue 3)

Use the interceptErrors option to intercept errors and send them to Ray:

app.use(RayPlugin, { interceptErrors: true });

Intercepting errors (Vue 2)

Use the interceptErrors option to intercept errors and send them to Ray:

Vue.use(RayPlugin, { interceptErrors: true });

Using the Vuex plugin

In either a Vue 2.x or 3.x project, use the vue-ray vuex plugin - it can track the vuex state, log mutations, and log actions.

To use it, import the RayVuexPlugin function from vue-ray, and pass the result of the function to the plugins property on your Vuex store:

// ...

import { RayVuexPlugin } from 'vue-ray'; // for both vue 2 and vue 3

// ...

const storeObj = {
    state: {
        one: 11,
        two: 22,
    },
    mutations: {
        incrementOne(state) {
            state.one += 1;
        },
        incrementTwo(state) {
            state.two += 2;
        },
    },
    actions: {},
    modules: {},
    plugins: [
        RayVuexPlugin({ 
            trackState: true,
            logMutations: true,
            trackingOptions: {
                propNames: ['on*'],
            }
        }),
    ],
};

// Vue 3:
export default createStore(storeObj);

// Vue 2:
export default new Vuex.Store(storeObj);

Vuex plugin options

Name Type Description
trackState boolean track the data in the store's state
logMutations boolean log all fired mutations to Ray
logActions boolean log all fired actions to Ray
loggedMutationColor string send logged mutations with the specified Ray color
loggedActionColor string send logged actions with the specified Ray color
trackingOptions object see "tracking options" section for more info

Valid color names are blue, gray, green, orange, purple, red, and none.

Tracking options

The trackingOptions definition is as follows:

trackingOptions?: {
    moduleNames?: string[];
    propNames?: string[];
};

The propNames is an array of wildcard patterns that will match stored data property names when tracking store state; for example, a value of ['f*'] would match store data properties named foo and fab but not dog.

The moduleNames is also an array of wildcard patterns but will match module names and module data property names, such as ['mymod.*'], which would match all properties in the mymod store.

The default value is ['*'], meaning all modules and properties match.

Development setup

  • npm install
  • npm run test
  • npm run build:all

Code Coverage Details

codecov graph
codecov graph

Testing

vue-ray uses Jest for unit tests. To run the test suite:

npm run test


Changelog

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.