node-ray

node-ray

Debug your NodeJS code with Ray to fix problems faster

This package can be installed in any NodeJS, ES6+, or TypeScript application to send messages to the Ray app.

Installation

Install with npm:

npm install node-ray

or yarn:

yarn add node-ray

Available environments

node-ray offers several variants to allow you to use it in either NodeJS or Browser environments.

NodeJS

When using in a NodeJS environment (the default), import the package as you would normally:

// es module import:
import { ray } from 'node-ray';

// commonjs import:
const ray = require('node-ray').ray;

Browser bundle

If you're bundling your scripts for use in a Browser environment (i.e. using webpack), import the /web variant:

// es module import:
import { ray } from 'node-ray/web';

// commonjs import:
const ray = require('node-ray/web').ray;

Browser standalone

If you'd like to use node-ray directly in a webpage, you may inject it via a CDN package. The standalone version is bundled with everything except the axios library.

    <script src="https://cdn.jsdelivr.net/npm/axios@latest"></script>
    <script src="https://cdn.jsdelivr.net/npm/node-ray@latest/dist/standalone.js"></script>

You may access the helper ray() method as Ray.ray().

Usage

The majority of the API from the original PHP package is supported. See the api reference for more information.

// es module import:
import { ray } from 'node-ray';

// commonjs import:
const ray = require('node-ray').ray;

ray('a string');

ray(['several', 'arguments'], 'can', {be: provided});

ray().table(['one two', {a: 100, b: 200, c: 300}, [9, 8, 7]).blue();

ray().html('<em>large text</em>').large().green();

ray().image('https://placekitten.com/200/300');

ray().clearAll();

ray().disable(); // disable sending data to Ray at runtime
ray().xml('<one>11</one>'); // disabled, data not sent to Ray

Configuration

Note: This section only applies if you are using node-ray in the NodeJS environment.

node-ray will search for ray.config.js. You should place this file in your project's root directory, similiar to the way ray.php is placed in the root directory when using spatie/ray.

This is optional and the package will use the default settings if no configuration file is found.

Example:

// ray.config.js

module.exports = {
    enable: true,
    host: 'localhost',
    port: 23517,
}

About

This package attempts to replicate the entire PHP API for Ray to provide a robust solution for debugging NodeJS projects.

How is this different from js-ray?

This is a more complete implementation written in typescript, and its primary use case is for NodeJS projects, although it can be used in Browser environments as well.

The codebase was translated to Typescript directly from the original PHP source code of spatie/ray.

As a result, node-ray supports the majority of features that exist in the original package; js-ray does not.

We did draw some inspiration for portions of the code from js-ray, however.

Using the package

See using the package.

Reference

Development setup

• npm install
• npm run build:all
• npm run test
• node build/test.js

Testing

node-ray uses Jest for unit tests. To run the test suite:

npm run test

To update the test snapshots:

npm run test -- -u

License

The MIT License (MIT). Please see License File for more information.