{"id":21466545,"url":"https://github.com/permafrost-dev/vue-ray","last_synced_at":"2025-04-04T12:06:26.913Z","repository":{"id":37082007,"uuid":"337207954","full_name":"permafrost-dev/vue-ray","owner":"permafrost-dev","description":"Debug your Vue 3 code with Ray to fix problems faster","archived":false,"fork":false,"pushed_at":"2024-10-02T16:53:53.000Z","size":365,"stargazers_count":85,"open_issues_count":5,"forks_count":5,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-28T11:08:34.511Z","etag":null,"topics":["debugging","npm-package","ray-app","vue","vue-plugin","vue2","vue3","vuejs"],"latest_commit_sha":null,"homepage":"https://permafrost.dev/open-source","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/permafrost-dev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"permafrost-dev","custom":"https://permafrost.dev/open-source"}},"created_at":"2021-02-08T20:59:18.000Z","updated_at":"2024-12-30T02:21:59.000Z","dependencies_parsed_at":"2024-12-20T22:11:58.436Z","dependency_job_id":"26382b55-34cb-4bf7-be66-57be619cc637","html_url":"https://github.com/permafrost-dev/vue-ray","commit_stats":{"total_commits":295,"total_committers":4,"mean_commits":73.75,"dds":"0.19999999999999996","last_synced_commit":"cc00c9760aa6ad69208931de2dcc52796134aaf5"},"previous_names":[],"tags_count":35,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/permafrost-dev%2Fvue-ray","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/permafrost-dev%2Fvue-ray/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/permafrost-dev%2Fvue-ray/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/permafrost-dev%2Fvue-ray/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/permafrost-dev","download_url":"https://codeload.github.com/permafrost-dev/vue-ray/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247174415,"owners_count":20896078,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["debugging","npm-package","ray-app","vue","vue-plugin","vue2","vue3","vuejs"],"created_at":"2024-11-23T08:14:25.856Z","updated_at":"2025-04-04T12:06:26.886Z","avatar_url":"https://github.com/permafrost-dev.png","language":"TypeScript","funding_links":["https://github.com/sponsors/permafrost-dev","https://permafrost.dev/open-source"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://static.permafrost.dev/images/vue-ray/vue-ray-logo.png\" alt=\"vue-ray\" height=\"200\" style=\"block\"\u003e\n    \u003cbr\u003e\u003cbr\u003e\n    \u003ccode style=\"font-size:3.0rem;\"\u003e\u003cstrong\u003evue-ray\u003c/strong\u003e\u003c/code\u003e\n    \u003cbr\u003e\u003cbr\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://shields.io/npm/v/vue-ray\" alt=\"npm version\"\u003e \u003cimg src=\"https://shields.io/npm/dt/vue-ray\" alt=\"npm downloads\"\u003e \u003cimg src=\"https://shields.io/github/license/permafrost-dev/vue-ray\" alt=\"license\"\u003e \u003cimg src=\"https://github.com/permafrost-dev/vue-ray/workflows/Run%20Tests/badge.svg?branch=main\" alt=\"test status\"\u003e \n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n        \u003cimg alt=\"tech debt\" src=\"https://img.shields.io/codeclimate/tech-debt/permafrost-dev/node-ray?label=tech%20debt\u0026logo=codeclimate\u0026style=flat-square\"\u003e\n    \u003cimg src=\"https://api.codeclimate.com/v1/badges/2673d256c0590b4c91d9/maintainability\" /\u003e\n        \u003cimg src=\"https://codecov.io/gh/permafrost-dev/vue-ray/branch/main/graph/badge.svg?token=YW2BTKSNEO\"/\u003e\n\u003c/p\u003e\n\n# vue-ray\n\n## Debug Vue code with Ray to fix problems faster\n\nInstall this package in any Vue 3 project to send messages to the [Ray app](https://myray.app).\n\n## Installation\n\nInstall with npm:\n\n```bash\nnpm install vue-ray\n```\n\nor bun:\n\n```bash\nbun add vue-ray\n```\n\n### Installing\n\nWhen using in a Vue 3 project, you may optionally install the plugin globally in your `main.js` or `app.js` file. This is primarily useful if you want to cusomize the connection settings for the package.\n\n```js\nimport { RayPlugin } from 'vue-ray';\nimport { createApp } from 'vue';\nimport App from './App.vue';\n\nconst app = createApp(App);\n\napp.use(RayPlugin, { \n    port: 23500,\n    host: 'localhost',\n    interceptErrors: true,\n    nodeRaySettings: { \n        interceptConsoleLog: true,\n    },\n});\n```\n\n### Installation options\n\n| Name                  | Type       | Default     | Description                                                    |\n| --------------------- | ---------- | ----------- | -------------------------------------------------------------- |\n| `host`                | `string`   | `localhost` | host to connect to the Ray app on                              |\n| `scheme`              | `string`   | `http`      | URI scheme to use to connect to host                           |\n| `interceptErrors`     | `boolean`  | `false`     | send Vue errors to Ray                                         |\n| `port`                | `number`   | `23517`     | port to connect to the Ray app on                              |\n| `nodeRaySettings`     | `object`   | `{}`        | pass additional settings for `node-ray` _[(reference)](https://github.com/permafrots-dev/node-ray#configuration)_ |\n\n## Usage\n\nTo access the `ray()` function, import `raySetup()` from the `vue-ray` library:\n\n```html\n\u003cscript setup\u003e\nimport { raySetup } from 'vue-ray'\nconst ray = raySetup(); // `ray` is a ref, so you must use `ray.value` within the script tags\n\u003c/script\u003e\n```\n\nThe `raySetup()` function accepts an optional `options` object, defined as:\n\n```typescript\ninterface RaySetupOptions {\n    connection?: {\n        host?: string;\n        port?: number;\n    }\n    lifecycleEvents?: {\n        beforeCreate?: boolean;\n        beforeMount?: boolean;\n        created?: boolean;\n        mounted?: boolean;\n        unmounted?: boolean;\n        updated?: boolean;\n        all?: boolean;\n    }\n}\n```\n\nThe `lifecycleEvents` object can be used to enable or disable sending of the component's lifecycle events to Ray. Use the `all` property to enable all lifecycle events.\n\nThe following example will send the `created` and `mounted` events to Ray for the component:\n\n```html\n\u003cscript setup\u003e\nimport { raySetup } from 'vue-ray'\nconst ray = raySetup({\n    lifecycleEvents: {\n        created: true,\n        mounted: true,\n    },\n});\n\u003c/script\u003e\n```\n\nThe `connection` object can be used to specify the host and port to connect to the Ray app. The default values are `localhost` and `23517`, respectively.\n\n### Sending data to Ray\n\nOnce you have called `raySetup()`, you may use the `ray` function in the Vue SFC as normal _(see node-ray)_ to send data to Ray:\n\n```html\n\u003ctemplate\u003e\n    \u003cdiv\u003e\n        \u003cbutton @click=\"ray('Hello from Vue!')\"\u003eSend message to Ray\u003c/button\u003e\n        \u003cbutton @click=\"() =\u003e ray().html('\u003cstrong\u003ehello with html!\u003c/strong\u003e')\"\u003eSend html message to Ray\u003c/button\u003e\n    \u003c/div\u003e\n\u003c/template\u003e\n```\n\nSee the [node-ray reference](https://github.com/permafrost-dev/node-ray#reference) for a complete list of available methods.\n\n## Vue-specific methods\n\n| Name                        | Description                                            |\n| --------------------------- | ------------------------------------------------------ |\n| `ray().data()`                    | show the component data                                |\n| `ray().props()`                   | show the component props                               |\n| `ray().element(refName: string)`  | render the HTML of an element with a ref of `refName` |\n| `ray().track(name: string)`       | display changes to a component's data variable _(best used when not using script setup)_ |\n| `ray().untrack(name: string)`     | stop displaying changes to a component's data variable |\n| `ray().watch(name: string, ref: Ref)`  | watch a ref's value and send changes to Ray _(best used in script setup)_ |\n| `ray().unwatch(name: string)`     | stop watching a ref's value and stop sending changes to Ray |\n\n## Watching refs\n\nWhen using the `script setup` syntax, you can use the `ray().watch(name, ref)` method to watch a ref's value and send changes to Ray. Here's an example SFC using the `script setup` syntax:\n\n```html\n\u003cscript setup\u003e\nimport { ref } from 'vue';\nimport { raySetup } from 'vue-ray';\n\nconst one = ref(100);\nconst two = ref(22);\nconst ray = raySetup().value;\n\nray().watch('one', one);\nray().watch('two', two);\n\u003c/script\u003e\n\n\u003ctemplate\u003e\n    \u003cdiv\u003e\n        \u003cdiv\u003e{{ one }}\u003c/div\u003e\n        \u003cdiv\u003e{{ two }}\u003c/div\u003e\n        \u003cbutton @click=\"one += 3\"\u003eIncrement one\u003c/button\u003e\n        \u003cbutton @click=\"two += 3\"\u003eIncrement two\u003c/button\u003e\n    \u003c/div\u003e\n\u003c/template\u003e\n```\n\n## Tracking component data\n\nWhen not using the `script setup` syntax, you can use the `ray().track(name)` method to track changes to a component's data variable. Here's an example SFC:\n\n```html\n\u003cscript\u003e\nimport { raySetup } from 'vue-ray';\nlet ray;\n\nexport default {\n    props: ['title'],\n    data() {\n        return {\n            one: 100,\n            two: 22,\n        };\n    },\n    created() {\n        // must call raySetup() in the created() lifecycle hook so it can access the current component\n        ray = raySetup().value;\n        ray().track('one');\n    },\n    methods: {\n        sendToRay() {\n            ray().element('div1');\n        },\n        increment() {\n            this.one += 3;\n            this.two += 5;\n        }\n    }\n};\n\u003c/script\u003e\n\n\u003ctemplate\u003e\n    \u003cdiv class=\"flex-col border-r border-gray-200 bg-white overflow-y-auto w-100\"\u003e\n        \u003cdiv ref=\"div1\" class=\"w-full flex flex-wrap\"\u003e\n            \u003cdiv ref=\"div1a\" class=\"w-4/12 inline-flex\"\u003e{{ one }}\u003c/div\u003e\n            \u003cdiv ref=\"div1b\" class=\"w-4/12 inline-flex\"\u003e{{ two }}\u003c/divr\u003e\n        \u003c/div\u003e\n        \u003cdiv class=\"about\"\u003e\n            \u003ch1\u003e{{ title }}\u003c/h1\u003e\n            \u003ca @click=\"sendToRay()\"\u003esend ref to ray\u003c/a\u003e\u003cbr\u003e\n            \u003ca @click=\"increment()\"\u003eincrement data var\u003c/a\u003e\u003cbr\u003e\n        \u003c/div\u003e\n    \u003c/div\u003e\n\u003c/template\u003e\n```\n\n\u003e When either tracking data or watching a ref, you will notice that the entry in Ray updates in real-time\n\u003e as the data changes, instead of creating a new entry each time the \u003edata changes. \n\n## Intercepting errors\n\nUse the `interceptErrors` option to intercept errors and send them to Ray:\n\n```js\napp.use(RayPlugin, { interceptErrors: true });\n```\n\n## Development setup\n\n```bash\nnpm install\nnpm run test\n```\n\n## Development Builds\n\n```bash\nnpm run build:dev\n```\n\nThis will build the package in development mode, and writes to the `dist-temp` directory.\n\n## Production Builds\n\n```bash\nnpm run build:dist\n```\n\nThis will build the package in production mode, and writes to the `dist` directory.\n\n## Code Coverage Details\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://codecov.io/gh/permafrost-dev/vue-ray/branch/main/graphs/commits.svg\" height=\"100\" alt=\"codecov graph\" /\u003e\n    \u003cbr\u003e\n    \u003cimg src=\"https://codecov.io/gh/permafrost-dev/vue-ray/branch/main/graphs/sunburst.svg\" height=\"210\" alt=\"codecov graph\" /\u003e\n\u003c/p\u003e\n\n## Testing\n\n`vue-ray` uses Vitest for unit tests. To run the test suite, run the following command:\n\n```bash\nnpm run test\n```\n\n...or run with coverage:\n\n```bash\nnpm run test:coverage\n```\n\n---\n\n## Changelog\n\nPlease see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.\n\n## Contributing\n\nPlease see [CONTRIBUTING](.github/CONTRIBUTING.md) for details.\n\n## Security Vulnerabilities\n\nPlease review [our security policy](../../security/policy) on how to report security vulnerabilities.\n\n## Credits\n\n- [Patrick Organ](https://github.com/patinthehat)\n- [All Contributors](../../contributors)\n\n## License\n\nThe MIT License (MIT). Please see [License File](LICENSE) for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpermafrost-dev%2Fvue-ray","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpermafrost-dev%2Fvue-ray","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpermafrost-dev%2Fvue-ray/lists"}