# 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
```
| 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
```
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
```
```html
Hi There Ray!
```
## 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!
```
## 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.
