{"id":15513450,"url":"https://github.com/permafrost-dev/alpinejs-ray","last_synced_at":"2025-08-20T14:32:22.583Z","repository":{"id":36980643,"uuid":"345003570","full_name":"permafrost-dev/alpinejs-ray","owner":"permafrost-dev","description":"Debug your Alpine.js code with Ray to fix problems faster","archived":false,"fork":false,"pushed_at":"2024-12-10T03:32:05.000Z","size":289,"stargazers_count":29,"open_issues_count":9,"forks_count":2,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-12-14T14:03:55.508Z","etag":null,"topics":["alpine","alpinejs","alpinejs-plugin","debugging","npm-package","ray","ray-app"],"latest_commit_sha":null,"homepage":"https://permafrost.dev/open-source","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/permafrost-dev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"permafrost-dev"}},"created_at":"2021-03-06T04:21:00.000Z","updated_at":"2024-12-06T03:54:57.000Z","dependencies_parsed_at":"2024-12-03T18:49:11.637Z","dependency_job_id":null,"html_url":"https://github.com/permafrost-dev/alpinejs-ray","commit_stats":{"total_commits":179,"total_committers":4,"mean_commits":44.75,"dds":"0.25698324022346364","last_synced_commit":"7d92d5b05b190dc0e70d6b5e5092785ff372527d"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/permafrost-dev%2Falpinejs-ray","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/permafrost-dev%2Falpinejs-ray/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/permafrost-dev%2Falpinejs-ray/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/permafrost-dev%2Falpinejs-ray/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/permafrost-dev","download_url":"https://codeload.github.com/permafrost-dev/alpinejs-ray/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230431103,"owners_count":18224655,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["alpine","alpinejs","alpinejs-plugin","debugging","npm-package","ray","ray-app"],"created_at":"2024-10-02T09:54:18.704Z","updated_at":"2024-12-19T12:11:03.991Z","avatar_url":"https://github.com/permafrost-dev.png","language":"TypeScript","funding_links":["https://github.com/sponsors/permafrost-dev"],"categories":["TypeScript"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://static.permafrost.dev/images/alpinejs-ray/alpinejs-ray-logo-600x300-transparent.png\" alt=\"alpinejs-ray\" height=\"200\" \n        style=\"display: block; height: 200px;\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://shields.io/npm/v/alpinejs-ray\" alt=\"npm version\"\u003e\n    \u003cimg src=\"https://shields.io/github/license/permafrost-dev/alpinejs-ray\" alt=\"license\"\u003e\n    \u003cimg src=\"https://github.com/permafrost-dev/alpinejs-ray/workflows/Run%20Tests/badge.svg?branch=main\" alt=\"test status\"\u003e\n    \u003cimg src=\"https://codecov.io/gh/permafrost-dev/alpinejs-ray/branch/main/graph/badge.svg?token=YW2BTKSNEO\"/\u003e\n    \u003cbr\u003e\n    \u003cimg src=\"https://shields.io/npm/dt/alpinejs-ray\" alt=\"npm downloads\"\u003e\n    \u003cimg src=\"https://data.jsdelivr.com/v1/package/npm/alpinejs-ray/badge?style=rounded\" alt=\"jsdelivr downloads\"\u003e\n\u003c/p\u003e\n\n# alpinejs-ray\n\n## Debug Alpine.js code with Ray to fix problems faster\n\nInstall this package into any project using [Alpine.js](https://github.com/alpinejs/alpine) to send messages to\nthe [Ray app](https://myray.app).\n\n\u003e Note: use version `^1.4` of this package for Alpine v2 and `^2.0` for Alpine v3.\n\n\u003c!-- ![screenshot](https://static.permafrost.dev/images/alpinejs-ray/screenshot-01.png) --\u003e\n\n## Installation\n\n### Installation via CDN (recommended)\n\nThe preferred way to use this package is to load it via CDN, which must be done _before_ loading Alpine.\n\nThe `axios` library must be loaded prior to loading `alpinejs-ray` and `Alpine`:\n\n```html\n\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/axios@latest/dist/axios.min.js\"\u003e\u003c/script\u003e\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/alpinejs-ray@2/dist/standalone.min.js\"\u003e\u003c/script\u003e\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/alpinejs@3/dist/cdn.min.js\" defer\u003e\n```\n\n### Installation via Module Import\n\nFirst, install `alpinejs-ray` with npm _(or your preferred package manager)_:\n\n```bash\nnpm install alpinejs-ray\n```\n\nAlthough not the recommended way, the package can be imported as an ESM module along with `alpinejs` and `axios`:\n\n```js \nimport Alpine from 'alpinejs';\nimport AlpineRayPlugin from 'alpinejs-ray';\n\nwindow.axios = require('axios');\nwindow.axios.defaults.headers.common['X-Requested-With'] = 'XMLHttpRequest';\n\nwindow.Alpine = Alpine;\n\nAlpine.plugin(AlpineRayPlugin);\nAlpine.start();\n```\n\n## Configuration\n\nTo configure `alpinejs-ray`, you must create an `alpineRayConfig` property on the `window` object before\nloading `alpinejs-ray`:\n\n```html\n\n\u003cscript\u003e\n    window.alpineRayConfig = {\n        interceptErrors: true,\n        logComponentsInit: true,\n        logCustomEvents: true,\n        logEvents: ['abc'],\n    };\n\u003c/script\u003e\n\n\u003c!-- load axios and alpinejs-ray --\u003e\n```\n\n| Name                | Type(s)          | Default | Description                                                |\n|---------------------|------------------|---------|------------------------------------------------------------|\n| `logComponentsInit` | `boolean`        | `false` | Send info on component initializations to Ray              |\n| `logErrors`         | `boolean`        | `false` | Send javascript errors to Ray instead of the console       |\n| `logEvents`         | `boolean, array` | `false` | Send specified custom events to Ray, or `false` to disable |\n\n## Usage\n\nAfter installing the plugin, access the `$ray()` magic method within your components:\n\n```html\n\n\u003cbutton @click=\"$ray().text('hello world')\"\u003eSay Hello\u003c/button\u003e\n```\n\nSee the [node-ray reference](https://github.com/permafrost-dev/node-ray#reference) for a complete list of available\nmethods.\n\n### Directives\n\nUse the `x-ray` directive within your HTML markup to easily send data to Ray. The value of the directive must be a valid\njavascript expression.\n\n```html\n\n\u003cdiv x-data\u003e\n    \u003c!-- sends 'hello world' and the value of the 'mystore.somevalue' Alpine store to Ray --\u003e\n    \u003cdiv x-ray=\"'hello world'\"\u003e\u003c/div\u003e\n    \u003cdiv x-ray=\"$store.mystore.somevalue\"\u003e\u003c/div\u003e\n\u003c/div\u003e\n```\n\nThe `x-ray` directive values are reactive; if the value changes, the new data will be sent to and displayed in Ray\nin-place.\nThe changed value will be momentarily highlighted in Ray to indicate that it was updated.\n\n## Example Components\n\n```html\n\n\u003cbutton @click=\"$ray('hello from alpine')\"\u003eSend to Ray\u003c/button\u003e\n```\n\n```html\n\n\u003cdiv x-data=\"onClickData()\"\u003e\n    \u003cdiv x-show=\"show\"\u003eHi There Ray!\u003c/div\u003e\n\n    \u003cbutton x-on:click=\"toggle()\"\u003eShow/Hide (Ray)\u003c/button\u003e\n\u003c/div\u003e\n\n\u003cscript\u003e\n    function onClickData() {\n        return {\n            init() {\n                this.$ray().html('\u003cstrong\u003einit on-click-ray data\u003c/strong\u003e');\n            },\n            toggle() {\n                this.show = !this.show;\n                this.$ray('toggled show value to ' + (this.show ? 'true' : 'false'));\n            },\n            show: false,\n        };\n    }\n\u003c/script\u003e\n```\n\n## Displaying errors\n\nErrors can be displayed in Ray automatically, with the portion of the code that caused the error highlighted.\n\n![screenshot](https://static.permafrost.dev/images/alpinejs-ray/error-display.png)\n\n## Tracking Data Stores\n\nAlpine stores can be automatically sent to Ray whenever the store data is mutated. Consider the following:\n\n```js\nwindow.Alpine.store('mydata', {\n    showing: false,\n});\n\nsetInterval(() =\u003e {\n    window.Alpine.store('mydata').showing = !window.Alpine.store('mydata').showing;\n}, 3000);\n```\n\nTo watch the store and display changes in Ray, use the `$ray().watchStore('name')` method:\n\n```html\n\n\u003cdiv x-data=\"componentData()\"\u003e\n    \u003cdiv x-show=\"$store.mydata.showing\"\u003eHi There Ray!\u003c/div\u003e\n    \u003cbutton x-on:click=\"toggle()\"\u003eShow/Hide (Ray)\u003c/button\u003e\n\u003c/div\u003e\n\n\u003cscript\u003e\n    window.Alpine.store('mydata', {\n        showing: false,\n    });\n\n    function componentData() {\n        return {\n            init() {\n                this.$ray().watchStore('mydata');\n            },\n            toggle() {\n                this.$store.mydata.showing = !this.$store.mydata.showing;\n            },\n        };\n    }\n\u003c/script\u003e\n```\n\n## Development Setup\n\nFor the development of `alpinejs-ray`, clone the repository and install dependencies via npm:\n\n```bash\nnpm install\n```\n\nFinally, build all library files; they will be output to the `dist` directory.\n\n```bash\nnpm run build:all\n```\n\n## Testing\n\n`alpinejs-ray` uses Jest for unit tests. To run the test suite:\n\n```bash\nnpm run test\n```\n\n## Changelog\n\nPlease see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.\n\n## Contributing\n\nPlease see [CONTRIBUTING](.github/CONTRIBUTING.md) for details.\n\n## Security Vulnerabilities\n\nPlease review [our security policy](../../security/policy) on how to report security vulnerabilities.\n\n## Credits\n\n- [Patrick Organ](https://github.com/patinthehat)\n- [All Contributors](../../contributors)\n\n## License\n\nThe MIT License (MIT). Please see [License File](LICENSE) for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpermafrost-dev%2Falpinejs-ray","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpermafrost-dev%2Falpinejs-ray","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpermafrost-dev%2Falpinejs-ray/lists"}