https://github.com/permafrost-dev/express-ray
Debug express.js server code with Ray to fix problems faster
https://github.com/permafrost-dev/express-ray
debugging express-js express-middleware expressjs middleware ray-app spatie typescript
Last synced: 3 months ago
JSON representation
Debug express.js server code with Ray to fix problems faster
- Host: GitHub
- URL: https://github.com/permafrost-dev/express-ray
- Owner: permafrost-dev
- License: mit
- Created: 2022-03-13T10:05:01.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2023-11-20T10:00:02.000Z (almost 2 years ago)
- Last Synced: 2024-05-01T11:30:36.944Z (over 1 year ago)
- Topics: debugging, express-js, express-middleware, expressjs, middleware, ray-app, spatie, typescript
- Language: JavaScript
- Homepage:
- Size: 192 KB
- Stars: 8
- Watchers: 2
- Forks: 1
- Open Issues: 8
-
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
# express-ray
Install this package in any Express.js project to provide an exceptional debugging experience using the [Ray app](https://myray.app) by [Spatie](https://spatie.be).
---
## Installation
Install this package with `npm`:
```bash
npm install express-ray
```
## Usage
### Plugin Installation
To install the `express-ray` plugin, call the `install` method provided by the `plugin` import:
```js
import { plugin as expressRayPlugin } from 'express-ray';
const app = express();
expressRayPlugin.install(app);
```
Once installed, access ray via the `app.$ray()` method. See the documentation for the [node-ray](https://github.com/permafrost-dev/node-ray) package for a list of available methods.
```js
app.get('/', (req, res) => {
app.$ray('sending "hello world" response');
res.send('hello world');
});
```
### Methods
The `app.$ray()` method provides additional helper methods specifically for express applications.
| Method | Description |
| ----------------------- | -------------------------------------------------------------- |
| `$ray().request(req)` | Sends information about the request object to Ray |
```js
app.get('/api/test', (req, res) => {
app.$ray().request(req);
res.send({ message: 'hello world' });
});
```
### Middleware
#### SendRequestToRay
Send details about each request to Ray with the `SendRequestToRay` middleware, optionally specifying configuration settings.
```ts
interface SendRequestToRayOptions {
methods?: HttpMethod[];
paths?: {
include?: string[];
ignore?: string[];
};
}
```
By default, all paths and http methods match and get sent to Ray. The `paths.include`, `paths.ignore`, and `methods` configuration settings support wildcards.
```js
import { middleware } from 'express-ray';
app.use(
middleware.SendRequestToRay({
methods: [HttpMethod.GET],
paths: { include: ['/api/*'], ignore: ['/api/ignored'] }
})
);
```
All configuration settings for this middleware are optional:
```js
app.use(middleware.SendRequestToRay());
```
#### SendErrorToRay
To send errors directly to Ray, use the `SendErrorToRay` middleware.
```js
import { middleware } from 'express-ray';
//
// register the middleware just before listen()
app.use(middleware.SendErrorToRay);
app.listen(port, () => {
console.log(`Listening on port ${port}`);
});
```
## Development Setup
```bash
npm install
npm run build:dev
```
## Testing
`express-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.