Registry / testing / backstage-grpc-playground

backstage-grpc-playground

library0.3.0jsnpmunverified

A Backstage frontend plugin that provides a gRPC playground interface, ported from BloomRPC. Current stable version is 0.3.0 (beta). It allows sending gRPC requests (unary, client streaming, server streaming) directly from Backstage entity pages or a dedicated route. Proto files are loaded from a backend plugin (backstage-grpc-playground-backend). Unlike BloomRPC, this plugin is web-based, integrates with Backstage's API documentation system, and generates markdown documentation via protoc-gen-doc. Does not support server reflection or gRPC-web. Requires Backstage ^1.5.0 and React 16/17.

testing devops

npm install backstage-grpc-playground

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · BACKSTAGE-GRPC-PLA

backstage-grpc-playground

testingjavascriptv0.3.0

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.

GrpcPlaygroundComponent

✓ import { GrpcPlaygroundComponent } from 'backstage-grpc-playground'

✗ const GrpcPlaygroundComponent = require('backstage-grpc-playground').GrpcPlaygroundComponent

ESM-only; named export used for API doc widget customization.

GrpcPlaygroundPage

✓ import { GrpcPlaygroundPage } from 'backstage-grpc-playground'

✗ import GrpcPlaygroundPage from 'backstage-grpc-playground'

Must use named import; no default export.

grpcPlaygroundPlugin

✓ import { grpcPlaygroundPlugin } from 'backstage-grpc-playground'

Optional: the Backstage plugin instance, rarely needed directly.

Shows how to add the gRPC playground as an API doc widget for grpc entities and as a standalone route.

// packages/app/src/apis.ts import { GrpcPlaygroundComponent } from 'backstage-grpc-playground'; import { createApiFactory, apiDocsConfigRef, defaultDefinitionWidgets } from '@backstage/plugin-api-docs'; import { AnyApiFactory } from '@backstage/core-plugin-api'; export const apis: AnyApiFactory[] = [ createApiFactory({ api: apiDocsConfigRef, deps: {}, factory: () => { const definitionWidgets = defaultDefinitionWidgets(); return { getApiDefinitionWidget: (apiEntity) => { if (apiEntity.spec.type === 'grpc') { return { type: 'grpc', title: 'gRPC Playground', component: GrpcPlaygroundComponent, }; } return definitionWidgets.find(d => d.type === apiEntity.spec.type); }, }; }, }), ]; // packages/app/src/App.tsx import { GrpcPlaygroundPage } from 'backstage-grpc-playground'; import { Route } from 'react-router-dom'; const routes = ( <Route path="/grpc-playground" element={<GrpcPlaygroundPage />} /> );

Debug

Known issues

gotchaRequires a separate backend plugin (backstage-grpc-playground-backend) to be installed and configured.

fix

Follow installation instructions at https://github.com/zalopay-oss/backstage-grpc-playground-backend

affects: >=0.1.0

gotchaDoes not support loading protos via server reflection; proto files must be stored on the backend filesystem.

fix

Place .proto files in the backend's proto directory (default packages/backend/proto).

affects: >=0.1.0

gotchagRPC-web is not supported. Only unary, client streaming, and server streaming (i.e., no bidirectional streaming).

fix

Use only unary, client streaming, or server streaming RPCs.

affects: >=0.1.0

gotchaNode.js 14 or 16 required; Node 18+ may cause issues.

fix

Use Node.js 14 or 16, or check for compatibility updates.

affects: >=0.1.0

deprecatedReact 17 support only; React 18 may not be fully compatible.

fix

Use React 16.13.1 or 17.0.0. For React 18, wait for an update.

affects: >=0.1.0

Errors

Common errors & fixes

Cannot find module 'backstage-grpc-playground' or its corresponding type declarations.

Missing dependency or incorrect import path.

fix

Run 'yarn --cwd packages/app add backstage-grpc-playground' from backstage root.

Failed to load proto file: no such file or directory

Proto file not placed in the backend's proto directory or wrong path in yaml definition.

fix

Ensure .proto files are in packages/backend/proto (or configured protoDir) and that the yaml file references them correctly.

gRPC Playground shows 'No API entity found'

The route /grpc-playground is not registered or the entity type is not 'grpc'.

fix

Add <Route path="/grpc-playground" element={<GrpcPlaygroundPage />} /> in App.tsx and ensure the API entity spec.type is 'grpc'.

Error: Unsupported method type: BIDIRECTIONAL_STREAMING

The RPC is bidirectional streaming, which is not supported.

fix

Only use unary, client streaming, or server streaming RPCs.

Upgrade

Version history

0.3.0latest on npm

Audit

Dependencies

reactrequiredPeer dependency: ^16.13.1 || ^17.0.0

Agent activity

26 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/zalopay-oss/backstage-grpc-playground ↗

packagebackstage-grpc-playground ↗

homepagehttps://github.com/zalopay-oss/backstage-grpc-playground ↗