alpinejs-ray

    1.4.0 • Public • Published

    alpinejs-ray

    alpinejs-ray

    npm version license test status
    npm downloads jsdelivr downloads

    alpinejs-ray

    Debug your Alpine.js code with Ray to fix problems faster

    This package can be installed into any project using alpine.js to send messages to the Ray app.

    screenshot

    Installation via CDN

    The preferred way to use this package is to load it via a CDN. You'll need to load the axios library as well:

    <script src="https://cdn.jsdelivr.net/npm/axios@latest"></script>
    <script src="https://cdn.jsdelivr.net/npm/alpinejs-ray@latest/dist/standalone.min.js"></script>

    Installation with package bundlers

    Install with npm:

    npm install alpinejs-ray

    or yarn:

    yarn add alpinejs-ray

    Importing the plugin

    Although not the recommended way, you can import package normally, along with node-ray/web, alpinejs and axios:

    import { Ray, ray } from 'node-ray/web';
    import Alpine from 'alpinejs';
    import AlpineRayPlugin from 'alpinejs-ray';
    
    window.ray = ray;
    window.Ray = Ray;
    window.axios = require('axios');
    window.axios.defaults.headers.common['X-Requested-With'] = 'XMLHttpRequest';
    
    window.Alpine = Alpine;
    window.AlpineRayPlugin = AlpineRayPlugin;
    window.AlpineRayPlugin.init();
    window.AlpineRayPlugin.start();

    To help reduce this large amount of boilerplate code, you can use the bootstrap helper function:

    import Alpine from 'alpinejs';
    import { bootstrapImports } from 'alpinejs-ray';
    
    const AlpineRayPlugin = bootstrapImports(Alpine);
    AlpineRayPlugin.start();

    Configuration options

    To configure alpinejs-ray, you must create an alpineRayConfig property on the window object before loading alpinejs-ray:

    <script>
        window.alpineRayConfig = {
            logComponentsInit: true,
        };
    </script>
    
    <!-- load axios and alpinejs-ray scripts here -->
    Name Type Default Description
    logComponentsInit boolean false Send info on component initializations to Ray
    logCustomEvents boolean false Send info on custom events to Ray (events with hyphenated names)

    Usage

    Once the plugin is installed, you may access the $ray() method within your components.

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

    Example Components

    <button @click="$ray('hello from alpine')">Send to Ray</button>
    <div x-data="onClickData()" x-init="init()">
        <div x-show="show">Hi There Ray!</div>
    
        <button x-on:click="toggle()">Show/Hide (Ray)</button>
    </div>
    
    <script>        
    function onClickData() {
        return {
            init() {
                this.$ray().html('<strong>init on-click-ray data</strong>');
            },
            toggle() {
                this.show = !this.show;
                this.$ray('toggled show value to ' + (this.show ? 'true' : 'false'));
            },
            show: false,
        };
    }
    </script>

    Displaying errors

    Errors can be automatically sent to Ray. The portion of the code that caused the error is highlighted.

    screenshot

    Tracking Spruce Data Stores

    Spruce data store are automatically tracked if Spruce is installed. Consider the following:

    window.Spruce.store('mydata', {
        showing: false,
        toggle() {
            this.showing = !this.showing;
            ray().html('<strong>[spruce]</strong> showing = ' + this.showing);
        }
    });
     
    setInterval( () => {
        window.Spruce.stores.mydata.showing = !window.Spruce.stores.mydata.showing;
    }, 3000);

    Data tracking example (note that the values change in place):

    data tracking

    Watching Spruce store properties

    To watch a Spruce store property and display changes in Ray, use the $ray().spruce().watch('store.propName') method:

    <div x-data="componentData()" x-init="init()">
        <div x-show="$store.mydata.showing">Hi There Ray!</div>
        <button x-on:click="toggle()">Show/Hide (Ray)</button>
    </div>
    
    <script>      
    window.Spruce.store('mydata', {
        showing: false,
    });
      
    function componentData() {
        return {
            init() {
                // changes to mydata.showing will be displayed in Ray
                this.$ray().spruce().watch('mydata.showing');
            },
            toggle() {
                this.$store.mydata.showing = !this.$store.mydata.showing;
            },
        };
    }
    </script>

    Development setup

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

    Testing

    alpinejs-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.

    Install

    npm i alpinejs-ray

    DownloadsWeekly Downloads

    9

    Version

    1.4.0

    License

    MIT

    Unpacked Size

    562 kB

    Total Files

    8

    Last publish

    Collaborators

    • avatar