xray-grpc

library0.3.1jsnpmunverified

GRPC client for Xray, providing typed gRPC bindings for Xray-core management APIs. Current stable version is 0.3.1. This package wraps Xray's gRPC services (HandlerService, StatsService, etc.) with TypeScript definitions, enabling programmatic control of Xray proxies, routing, and statistics. It is a lightweight, type-safe alternative to manual protobuf usage or CLI-based config management. The library is actively maintained with a focus on compatibility with Xray-core's gRPC interface. Release cadence is irregular, tied to upstream Xray changes. It differentiates itself by being the only dedicated npm package for Xray gRPC with TypeScript support.

devops

npm install xray-grpc

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · XRAY-GRPC

xray-grpc

devopsjavascriptv0.3.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

HandlerServiceClient

✓ import { HandlerServiceClient } from 'xray-grpc'

✗ const { HandlerServiceClient } = require('xray-grpc')

Library is ESM-only; CommonJS require will fail as of v0.3.1

StatsServiceClient

✓ import { StatsServiceClient } from 'xray-grpc'

✗ import StatsServiceClient from 'xray-grpc'

Not a default export; named import required

xray-grpc

✓ import xray from 'xray-grpc'

Module object exposes all services as properties (e.g., xray.HandlerServiceClient)

GrpcService

✓ import type { GrpcService } from 'xray-grpc'

✗ import { GrpcService } from 'xray-grpc'

GrpcService is a type-only export; use `import type` at runtime to avoid errors

Creates a gRPC client, constructs an AddInbound request with VMess configuration, and sends it to Xray.

import { HandlerServiceClient } from 'xray-grpc'; import * as grpc from '@grpc/grpc-js'; const client = new HandlerServiceClient( 'localhost:8080', grpc.credentials.createInsecure() ); const request = { inboundTag: 'my-inbound', add: { tag: 'my-outbound', protocol: 'vmess', settings: { vnext: [{ address: 'example.com', port: 443, users: [{ id: 'uuid', security: 'auto' }] }] } } }; client.addInbound(request, (error, response) => { if (error) console.error(error); else console.log('Inbound added:', response); });

Debug

Known issues

breakingIn v0.3.0, the import paths changed from nested subpaths (e.g., 'xray-grpc/handler') to a single main export. Code using deep imports will break.

fix

Replace 'import { X } from 'xray-grpc/handler'' with 'import { HandlerServiceClient } from 'xray-grpc''.

affects: <0.3.0

gotchaThe package does not provide a default export. Attempting `import xray from 'xray-grpc'` yields `undefined` at runtime.

fix

Use named exports: `import { HandlerServiceClient } from 'xray-grpc'` or import namespace: `import * as xray from 'xray-grpc'`.

affects: >=0.3.0

deprecatedThe `protoRoot` configuration option was deprecated in v0.3.0. Setting it no longer has any effect and may cause a warning.

fix

Remove `protoRoot` from client options. Proto loading is now automatic.

affects: >=0.3.0

gotchaTypeScript users: Many exported symbols are purely types (e.g., `GrpcService`, `StatsRequest`). Using them as runtime values will cause a ReferenceError.

fix

Use `import type { GrpcService } from 'xray-grpc'` for type-only imports.

affects: >=0.3.0

Errors

Common errors & fixes

Error: Cannot find module 'xray-grpc'

Package not installed or import path incorrect (e.g., using subpath that was removed).

fix

Install the package: `npm install xray-grpc`. Then use correct import: `import { HandlerServiceClient } from 'xray-grpc'`.

TypeError: xray.HandlerServiceClient is not a constructor

Using default import (`import xray from 'xray-grpc'`) which is `undefined`.

fix

Use named import: `import { HandlerServiceClient } from 'xray-grpc'`.

Error: 12 UNIMPLEMENTED: unknown service xray.app.proxyman.command.HandlerService

Xray server does not support the requested service (version mismatch).

fix

Ensure Xray server version matches the gRPC definitions. Update Xray or use a compatible xray-grpc version.

Upgrade

Version history

0.3.1latest on npm

Audit

Dependencies

@grpc/grpc-jsrequiredRequired for gRPC client functionality

@grpc/proto-loaderoptionalUsed to load Xray protobuf definitions

Agent activity

18 hits · last 30 days

node

Resources

githubhttps://github.com/talrasha007/xray-grpc-node ↗

packagexray-grpc ↗

homepagehttps://github.com/talrasha007/xray-grpc-node#readme ↗