2121</p >
2222
2323# node-ray
24+
2425### The official Node/JS & TypeScript integration for Ray - Understand and fix bugs faster.
2526
2627The package can be installed in any NodeJS, ES6+, or TypeScript application to send data to the [ Ray app] ( https://myray.app ) .
@@ -41,13 +42,18 @@ or bun:
4142bun add node-ray
4243```
4344
45+ ## Requirements
46+
47+ - Node.js >= 20.19
48+ - ESM-only (CommonJS is no longer supported; use v2.x for ` require ` support)
49+
4450## Available environments
4551
46- ` node-ray ` offers several options to allow you to use it in either NodeJS, Web-based TypeScript or Javascript projects, and browser environments.
52+ ` node-ray ` offers several options to allow you to use it in either NodeJS, Web-based TypeScript or JavaScript projects, and browser environments.
4753
48- > If you're using NextJs/React, take a look at [ permafrost-dev/react-ray] ( https://github.com/permafrost-dev/react-ray ) .
49- >
50- > If you're using Vue, check out [ permafrost-dev/vue-ray] ( https://github.com/permafrost-dev/vue-ray ) .
54+ > If you're using NextJs/React, take a look at [ permafrost-dev/react-ray] ( https://github.com/permafrost-dev/react-ray ) .
55+ >
56+ > If you're using Vue, check out [ permafrost-dev/vue-ray] ( https://github.com/permafrost-dev/vue-ray ) .
5157
5258### NodeJS
5359
@@ -56,20 +62,16 @@ When using in a NodeJS environment (the default), import the package as you woul
5662``` js
5763// es module import:
5864import { ray } from ' node-ray'
59-
60- // commonjs import:
61- const ray = require (' node-ray' ray ;
6265```
6366
67+ ` node-ray ` is ESM-only. CommonJS ` require ` is not supported.
68+
6469### Browser bundle
6570
6671When bundling scripts for use in a Browser environment _ (i.e., using webpack or vite)_ , import the ` /web ` export:
6772
6873``` js
6974import { ray } from ' node-ray/web'
70-
71- // or a commonjs import:
72- const { ray } = require (' node-ray/web'
7375```
7476
7577### Browser standalone
@@ -104,7 +106,7 @@ As of version `2.0.0`, you no longer need to manually initialize the global `ray
104106To use ` node-ray ` with Laravel Mix, include the following in ` resources/js/bootstrap.js ` :
105107
106108``` js
107- const { ray } = require ( ' node-ray/web' ) ;
109+ import { ray } from ' node-ray/web'
108110
109111window .ray = ray;
110112```
@@ -130,9 +132,6 @@ Most of the API from the [original PHP package](https://github.com/spatie/ray) i
130132``` js
131133// es module import:
132134import { ray } from ' node-ray'
133-
134- // commonjs import:
135- const { ray } = require (' node-ray'
136135```
137136
138137To modify the host or port:
@@ -175,7 +174,7 @@ ray().xml('<one>11</one>'); // previous call disabled sending data, XML not sent
175174
176175_ Note: This section only applies when using ` node-ray ` in the NodeJS environment, NOT a browser environment._
177176
178- ` node-ray ` will search for ` ray.config.js ` , which should be in the project's root directory.
177+ ` node-ray ` will search for ` ray.config.js ` , which should be in the project's root directory. The config file is ESM and should use ` export default ` .
179178
180179Using a configuration file is optional, and the package will use the default settings if no configuration file is specified.
181180
@@ -184,7 +183,7 @@ _Example:_
184183``` js
185184// ray.config.js
186185
187- module . exports = {
186+ export default {
188187 enable: true ,
189188 host: ' localhost'
190189 port: 23517 ,
@@ -279,60 +278,60 @@ See [using the package](docs/usage.md).
279278
280279## Reference
281280
282- | Call | Description |
283- | --- | --- |
284- | ` ray(variable) ` | Display a string, array or object |
285- | ` ray(var1, var2, …) ` | Ray accepts multiple arguments |
286- | ` ray().blue() ` | Output in color. Use ` green ` , ` orange ` , ` red ` , ` blue ` ,` purple ` or ` gray ` |
287- | ` ray().caller() ` | ** Asynchronous.** Show the calling class and method |
288- | ` ray().chain(callback) ` | Chain multiple Ray payloads and send them all at once. ` callback: (ray: Ray) => void ` |
289- | ` ray().clearScreen() ` | Clear current screen |
290- | ` ray().clearAll() ` | Clear current and all previous screens |
291- | ` ray().className(obj) ` | Display the classname for an object |
292- | ` ray().confetti() ` | Display Confetti in Ray |
293- | ` ray().count(name) ` | Count how many times a piece of code is called, with optional name |
294- | ` ray().date(date, format) ` | Display a formatted date, the timezone, and its timestamp |
295- | ` ray().die() ` | Halt code execution - NodeJS only |
296- | ` ray().disable() ` | Disable sending stuff to Ray |
297- | ` ray().disabled() ` | Check if Ray is disabled |
298- | ` ray().enable() ` | Enable sending stuff to Ray |
299- | ` ray().enabled() ` | Check if Ray is enabled |
300- | ` ray().error(err) ` | Display information about an Error/Exception |
301- | ` ray().event(name, data) ` | Display information about an event with optional data |
302- | ` ray().exception(err) ` | ** Asynchronous.** Display extended information and stack trace for an Error/Exception |
303- | ` ray().file(filename) ` | ** NodeJS only.** Display contents of a file |
304- | ` ray().hide() ` | Display something in Ray and make it collapse immediately |
305- | ` ray().hideApp() ` | Programmatically hide the Ray app window |
306- | ` ray().html(string) ` | Send HTML to Ray |
307- | ` ray().htmlMarkup(string) ` | Display syntax-highlighted HTML code in Ray |
308- | ` ray().if(true, callback) ` | Conditionally show things based on a truthy value or callable, optionally calling the callback with a ` ray ` argument |
309- | ` ray().image(url) ` | Display an image in Ray |
310- | ` ray().interceptor() ` | Access ConsoleInterceptor; call ` .enable() ` to show ` console.log() ` calls in Ray |
311- | ` ray().json([…]) ` | Send JSON to Ray |
312- | ` ray().label(string) ` | Add a text label to the payload |
313- | ` ray().limit(N) ` | ** Asynchronous.** Limit the number of payloads that can be sent to Ray to N; used for debugging within loops |
314- | ` ray().macro(name, callable) ` | Add a custom method to the Ray class. make sure not to use an arrow function if returning ` this ` |
315- | ` ray().measure(callable) ` | Measure the performance of a callback function |
316- | ` ray().measure() ` | Begin measuring the overall time and elapsed time since previous ` measure() ` call |
317- | ` ray().newScreen() ` | Start a new screen |
318- | ` ray().newScreen('title') ` | Start a new named screen |
319- | ` ray().nodeinfo() ` | ** NodeJS only.** Display statistics about node, such as the v8 version and memory usage |
320- | ` ray().notify(message) ` | Display a notification |
321- | ` ray().once(arg1, …) ` | ** Asynchronous.** Only send a payload once when in a loop |
322- | ` ray().pass(variable) ` | Display something in Ray and return the value instead of a Ray instance |
323- | ` ray().pause() ` | Pause code execution within your code; must be called using ` await ` |
324- | ` ray().projectName(name) ` | Change the active project name |
325- | ` ray().remove() ` | Remove an item from Ray |
326- | ` ray().screenColor(color) ` | Changes the screen color to the specified color |
327- | ` ray().separator() ` | Display a separator |
328- | ` ray().showApp() ` | Programmatically show the Ray app window |
329- | ` ray().small() ` | Output text smaller or bigger. Use ` large ` or ` small ` |
330- | ` ray().stopTime(name) ` | Removes a named stopwatch if specified, otherwise removes all stopwatches |
331- | ` ray().table(…) ` | Display an array or an object formatted as a table; Objects and arrays are pretty-printed |
332- | ` ray().text(string) ` | Display raw text in Ray while preserving whitespace formatting |
333- | ` ray().toJson(variable) ` | Convert a variable using ` JSON.stringify() ` and display the result |
334- | ` ray().trace() ` | Display a stack trace |
335- | ` ray().xml(string) ` | Send XML to Ray |
281+ | Call | Description |
282+ | ----------------------------- | ----------------------------------------------------------------------------------------------------------------- --- |
283+ | ` ray(variable) ` | Display a string, array or object |
284+ | ` ray(var1, var2, …) ` | Ray accepts multiple arguments |
285+ | ` ray().blue() ` | Output in color. Use ` green ` , ` orange ` , ` red ` , ` blue ` ,` purple ` or ` gray ` |
286+ | ` ray().caller() ` | ** Asynchronous.** Show the calling class and method |
287+ | ` ray().chain(callback) ` | Chain multiple Ray payloads and send them all at once. ` callback: (ray: Ray) => void ` |
288+ | ` ray().clearScreen() ` | Clear current screen |
289+ | ` ray().clearAll() ` | Clear current and all previous screens |
290+ | ` ray().className(obj) ` | Display the classname for an object |
291+ | ` ray().confetti() ` | Display Confetti in Ray |
292+ | ` ray().count(name) ` | Count how many times a piece of code is called, with optional name |
293+ | ` ray().date(date, format) ` | Display a formatted date, the timezone, and its timestamp |
294+ | ` ray().die() ` | Halt code execution - NodeJS only |
295+ | ` ray().disable() ` | Disable sending stuff to Ray |
296+ | ` ray().disabled() ` | Check if Ray is disabled |
297+ | ` ray().enable() ` | Enable sending stuff to Ray |
298+ | ` ray().enabled() ` | Check if Ray is enabled |
299+ | ` ray().error(err) ` | Display information about an Error/Exception |
300+ | ` ray().event(name, data) ` | Display information about an event with optional data |
301+ | ` ray().exception(err) ` | ** Asynchronous.** Display extended information and stack trace for an Error/Exception |
302+ | ` ray().file(filename) ` | ** NodeJS only.** Display contents of a file |
303+ | ` ray().hide() ` | Display something in Ray and make it collapse immediately |
304+ | ` ray().hideApp() ` | Programmatically hide the Ray app window |
305+ | ` ray().html(string) ` | Send HTML to Ray |
306+ | ` ray().htmlMarkup(string) ` | Display syntax-highlighted HTML code in Ray |
307+ | ` ray().if(true, callback) ` | Conditionally show things based on a truthy value or callable, optionally calling the callback with a ` ray ` argument |
308+ | ` ray().image(url) ` | Display an image in Ray |
309+ | ` ray().interceptor() ` | Access ConsoleInterceptor; call ` .enable() ` to show ` console.log() ` calls in Ray |
310+ | ` ray().json([…]) ` | Send JSON to Ray |
311+ | ` ray().label(string) ` | Add a text label to the payload |
312+ | ` ray().limit(N) ` | ** Asynchronous.** Limit the number of payloads that can be sent to Ray to N; used for debugging within loops |
313+ | ` ray().macro(name, callable) ` | Add a custom method to the Ray class. make sure not to use an arrow function if returning ` this ` |
314+ | ` ray().measure(callable) ` | Measure the performance of a callback function |
315+ | ` ray().measure() ` | Begin measuring the overall time and elapsed time since previous ` measure() ` call |
316+ | ` ray().newScreen() ` | Start a new screen |
317+ | ` ray().newScreen('title') ` | Start a new named screen |
318+ | ` ray().nodeinfo() ` | ** NodeJS only.** Display statistics about node, such as the v8 version and memory usage |
319+ | ` ray().notify(message) ` | Display a notification |
320+ | ` ray().once(arg1, …) ` | ** Asynchronous.** Only send a payload once when in a loop |
321+ | ` ray().pass(variable) ` | Display something in Ray and return the value instead of a Ray instance |
322+ | ` ray().pause() ` | Pause code execution within your code; must be called using ` await ` |
323+ | ` ray().projectName(name) ` | Change the active project name |
324+ | ` ray().remove() ` | Remove an item from Ray |
325+ | ` ray().screenColor(color) ` | Changes the screen color to the specified color |
326+ | ` ray().separator() ` | Display a separator |
327+ | ` ray().showApp() ` | Programmatically show the Ray app window |
328+ | ` ray().small() ` | Output text smaller or bigger. Use ` large ` or ` small ` |
329+ | ` ray().stopTime(name) ` | Removes a named stopwatch if specified, otherwise removes all stopwatches |
330+ | ` ray().table(…) ` | Display an array or an object formatted as a table; Objects and arrays are pretty-printed |
331+ | ` ray().text(string) ` | Display raw text in Ray while preserving whitespace formatting |
332+ | ` ray().toJson(variable) ` | Convert a variable using ` JSON.stringify() ` and display the result |
333+ | ` ray().trace() ` | Display a stack trace |
334+ | ` ray().xml(string) ` | Send XML to Ray |
336335
337336## FAQ
338337
0 commit comments