Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/permafrost-dev/alpinejs-ray
Debug your Alpine.js code with Ray to fix problems faster
https://github.com/permafrost-dev/alpinejs-ray
alpine alpinejs alpinejs-plugin debugging npm-package ray ray-app
Last synced: 1 day ago
JSON representation
Debug your Alpine.js code with Ray to fix problems faster
- Host: GitHub
- URL: https://github.com/permafrost-dev/alpinejs-ray
- Owner: permafrost-dev
- License: mit
- Created: 2021-03-06T04:21:00.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-09-24T03:58:30.000Z (9 days ago)
- Last Synced: 2024-09-27T00:20:01.796Z (7 days ago)
- Topics: alpine, alpinejs, alpinejs-plugin, debugging, npm-package, ray, ray-app
- Language: TypeScript
- Homepage: https://permafrost.dev/open-source
- Size: 248 KB
- Stars: 27
- Watchers: 3
- Forks: 2
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Security: .github/SECURITY.md
Awesome Lists containing this project
README
# alpinejs-ray
## Debug Alpine.js code with Ray to fix problems faster
Install this package into any project using [Alpine.js](https://github.com/alpinejs/alpine) to send messages to
the [Ray app](https://myray.app).
> Note: use version `^1.4` of this package for Alpine v2 and `^2.0` for Alpine v3.
## Installation
### Installation via CDN (recommended)
The preferred way to use this package is to load it via CDN, which must be done _before_ loading Alpine.
The `axios` library must be loaded prior to loading `alpinejs-ray` and `Alpine`:
```html
```
### Installation via Module Import
First, install `alpinejs-ray` with npm _(or your preferred package manager)_:
```bash
npm install alpinejs-ray
```
Although not the recommended way, the package can be imported as an ESM module along with `alpinejs` and `axios`:
```js
import Alpine from 'alpinejs';
import AlpineRayPlugin from 'alpinejs-ray';
window.axios = require('axios');
window.axios.defaults.headers.common['X-Requested-With'] = 'XMLHttpRequest';
window.Alpine = Alpine;
Alpine.plugin(AlpineRayPlugin);
Alpine.start();
```
## Configuration
To configure `alpinejs-ray`, you must create an `alpineRayConfig` property on the `window` object before
loading `alpinejs-ray`:
```html
<script>
window.alpineRayConfig = {
interceptErrors: true,
logComponentsInit: true,
logCustomEvents: true,
logEvents: ['abc'],
};
```
| Name | Type(s) | Default | Description |
|---------------------|------------------|---------|------------------------------------------------------------|
| `logComponentsInit` | `boolean` | `false` | Send info on component initializations to Ray |
| `logErrors` | `boolean` | `false` | Send javascript errors to Ray instead of the console |
| `logEvents` | `boolean, array` | `false` | Send specified custom events to Ray, or `false` to disable |
## Usage
After installing the plugin, access the `$ray()` magic method within your components:
```html
Say Hello
```
See the [node-ray reference](https://github.com/permafrost-dev/node-ray#reference) for a complete list of available
methods.
### Directives
Use the `x-ray` directive within your HTML markup to easily send data to Ray. The value of the directive must be a valid
javascript expression.
```html
```
The `x-ray` directive values are reactive; if the value changes, the new data will be sent to and displayed in Ray
in-place.
The changed value will be momentarily highlighted in Ray to indicate that it was updated.
## Example Components
```html
Send to Ray
```
```html
Hi There Ray!
Show/Hide (Ray)
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,
};
}
```
## Displaying errors
Errors can be displayed in Ray automatically, with the portion of the code that caused the error highlighted.
## Tracking Data Stores
Alpine stores can be automatically sent to Ray whenever the store data is mutated. Consider the following:
```js
window.Alpine.store('mydata', {
showing: false,
});
setInterval(() => {
window.Alpine.store('mydata').showing = !window.Alpine.store('mydata').showing;
}, 3000);
```
To watch the store and display changes in Ray, use the `$ray().watchStore('name')` method:
```html
Hi There Ray!
Show/Hide (Ray)
window.Alpine.store('mydata', {
showing: false,
});
function componentData() {
return {
init() {
this.$ray().watchStore('mydata');
},
toggle() {
this.$store.mydata.showing = !this.$store.mydata.showing;
},
};
}
```
## Development Setup
For the development of `alpinejs-ray`, clone the repository and install dependencies via npm:
```bash
npm install
```
Finally, build all library files; they will be output to the `dist` directory.
```bash
npm run build:all
```
## Testing
`alpinejs-ray` uses Jest for unit tests. To run the test suite:
```bash
npm run test
```
## Changelog
Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.
## Contributing
Please see [CONTRIBUTING](.github/CONTRIBUTING.md) for details.
## Security Vulnerabilities
Please review [our security policy](../../security/policy) on how to report security vulnerabilities.
## Credits
- [Patrick Organ](https://github.com/patinthehat)
- [All Contributors](../../contributors)
## License
The MIT License (MIT). Please see [License File](LICENSE) for more information.