https://github.com/permafrost-dev/react-ray
Official React integration for the Ray app.
https://github.com/permafrost-dev/react-ray
ray-app react react-hooks spatie
Last synced: 3 months ago
JSON representation
Official React integration for the Ray app.
- Host: GitHub
- URL: https://github.com/permafrost-dev/react-ray
- Owner: permafrost-dev
- License: mit
- Created: 2023-03-02T01:38:00.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-10-21T20:53:18.000Z (12 months ago)
- Last Synced: 2024-10-31T18:37:51.288Z (12 months ago)
- Topics: ray-app, react, react-hooks, spatie
- Language: JavaScript
- Homepage:
- Size: 222 KB
- Stars: 11
- Watchers: 2
- Forks: 1
- Open Issues: 5
-
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
# react-ray
The official React integration for the [Ray app](https://myray.app) by [Spatie](https://github.com/spatie/ray).
## Installation
You can install the package via npm:
```bash
npm install react-ray
```
## Usage
`react-ray` supports React 16+ and provides several hooks:
- `useRay` - send data to the Ray app whenever it updates.
- `useRayWithElement` - send the contents of an element ref to the Ray app, optionally updating the item in place when its dependencies change.
- `useRayInstance` - access the Ray instance directly.
### `useRay()`
To send data to Ray whenever it updates, use the `useRay` hook along with the `type` option to specify the type of data you are sending. The `boolean` `replace` option can be used to update the Ray item in place when its dependencies change. The default value for `replace` is `false`.
Valid types are `image`, `json`, `html`, `text`, or `xml`. See the [`node-ray` documentation](https://github.com/permafrost-dev/node-ray) for more information on these types.
```js
import { useRay } from 'react-ray';
import { useEffect, useState } from 'react';
const MyComponent = () => {
const [count, setCount] = useState(0);
useRay(count, { type: 'text', replace: true });
return (
setCount(count + 1)}>
Click me
);
};
```
### `useRayWithElement()`
To send the contents of a ref to the Ray app in a sequential manner (each dependency change sends a new item), set the `replace` option to `false`:
```js
import { useRayWithElement } from 'react-ray';
import { useRef, useState } from 'react';
const MyComponent = () => {
const [count, setCount] = useState(0);
const countRef = useRef(null);
useRayWithElement(countRef, [count], { replace: false });
return (
{count}
setCount(count + 1)}>
Click me
);
};
```
To update the Ray item in place that was sent with the contents of a ref when its dependencies change, set the `replace` option to true or omit it:
```js
import { useRayWithElement } from 'react-ray';
import { useRef, useState } from 'react';
const MyComponent = () => {
const [count, setCount] = useState(0);
const countRef = useRef(null);
useRayWithElement(countRef, [count], { replace: true });
// or
// useRayWithElement(countRef, [count]);
return (
{count}
setCount(count + 1)}>
Click me
);
};
```
### `useRayInstance()`
To access the Ray instance directly, use the `useRayInstance` hook:
```js
import { useRayInstance } from 'react-ray';
const MyComponent = () => {
const ray = useRayInstance();
ray('hello world');
return (
ray('hello world')}>
Click me
);
};
```
## Setup
```bash
npm install
npm run dev
```
## Testing
`react-ray` uses Jest for unit tests. To run the test suite:
`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)
- [Sam Apostel](https://github.com/sam-apostel)
- [All Contributors](../../contributors)
## License
The MIT License (MIT). Please see [License File](LICENSE) for more information.