# backstage-grpc-playground

> A frontend plugin for Backstage supporting gRPC playground

Latest version **0.3.0** (published 2022-08-29) · MIT license · 0 weekly downloads

## Install

```sh
npm install backstage-grpc-playground
pnpm add backstage-grpc-playground
yarn add backstage-grpc-playground
bun add backstage-grpc-playground
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.3.0 |
| Published | 2022-08-29 |
| First published | 2022-06-06 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 21 |
| Unpacked size | 401.2 KB |
| Known vulnerabilities | 0 (+12 in 2 direct dependencies) |
| Install scripts | no |
| GitHub stars | 39 |
| Author | Zalopay-OSS |
| Maintainers | fr0stf0x |
| Keywords | backstage, backstage plugin, gRPC, bloomrpc, gRPC playground, Zalopay |

## Links

- npm: https://www.npmjs.com/package/backstage-grpc-playground
- Repository: https://github.com/zalopay-oss/backstage-grpc-playground
- Issues: https://github.com/zalopay-oss/backstage-grpc-playground/issues
- npm.io page: https://npm.io/package/backstage-grpc-playground

## Dependencies (21)

- [antd](https://npm.io/package/antd.md) ^4.20.7
- [uuid](https://npm.io/package/uuid.md) ^8.3.2
- [brace](https://npm.io/package/brace.md) ^0.11.1
- [mousetrap](https://npm.io/package/mousetrap.md) ^1.6.5
- [react-ace](https://npm.io/package/react-ace.md) ^6.4.0
- [react-use](https://npm.io/package/react-use.md) ^17.2.4
- [lodash.get](https://npm.io/package/lodash.get.md) ^4.4.2
- [path-parse](https://npm.io/package/path-parse.md) ^1.0.7
- [protobufjs](https://npm.io/package/protobufjs.md) ^6.11.2
- [rehype-raw](https://npm.io/package/rehype-raw.md) ^6.1.1
- [remark-gfm](https://npm.io/package/remark-gfm.md) ^3.0.1
- [re-resizable](https://npm.io/package/re-resizable.md) ^4.11.0
- [react-markdown](https://npm.io/package/react-markdown.md) ^8.0.3
- [@ant-design/icons](https://npm.io/package/@ant-design/icons.md) ^4.7.0
- [browser-fs-access](https://npm.io/package/browser-fs-access.md) ^0.29.6
- [react-sortable-hoc](https://npm.io/package/react-sortable-hoc.md) ^2.0.0
- [github-markdown-css](https://npm.io/package/github-markdown-css.md) ^5.1.0
- [@backstage/core-plugin-api](https://npm.io/package/@backstage/core-plugin-api.md) ^1.0.5
- [@backstage/integration-react](https://npm.io/package/@backstage/integration-react.md) ^1.1.3
- [@microsoft/fetch-event-source](https://npm.io/package/@microsoft/fetch-event-source.md) ^2.0.1
- [@backstage/plugin-catalog-react](https://npm.io/package/@backstage/plugin-catalog-react.md) ^1.1.3

## Recent versions

- 0.3.0 (latest) — 2022-08-29
- 0.3.0-next.0 — 2022-08-29
- 0.2.0-next.0 — 2022-08-04
- 0.1.4 — 2022-07-26
- 0.1.4-next.1 — 2022-07-26
- 0.1.3-b — 2022-07-18
- 0.1.3 — 2022-07-15
- 0.1.2 — 2022-06-17
- 0.1.2-next.1 — 2022-06-15
- 0.1.2-next.0 — 2022-06-15
- 0.1.1 — 2022-06-06
- 0.1.0 — 2022-06-06

## README

# backstage-grpc-playground

![GitHub](https://img.shields.io/github/license/zalopay-oss/backstage-grpc-playground) ![Project Level](https://img.shields.io/badge/level-beta-yellowgreen) ![GitHub issues](https://img.shields.io/github/issues/zalopay-oss/backstage-grpc-playground) ![GitHub contributors](https://img.shields.io/github/contributors-anon/zalopay-oss/backstage-grpc-playground?color=blue)

<!-- TOC -->
- [**Overview**](#overview)
- [**Changelog**](#changelog)
- [**Requirements**](#requirements)
- [**Methods supported**](#methods-supported)
- [**Not supported**](#not-supported-yet)
- [**Install**](#install)
- [**Usage**](#usage)
- [**Compare to BloomRPC**](#compare-to-bloomrpc)
- [**Yaml file definition**](#yaml-file-definition)
- [**Examples**](#examples)
- [**Acknowledgements**](#acknowledgements)

## Overview

**backstage-grpc-playground** is a [backstage](https://backstage.io) plugin ported from [BloomRPC](https://github.com/bloomrpc/bloomrpc) which is an Electron application. We modified some of the original code to make this compatible with Backstage entity. See [Compare to BloomRPC](#compare-to-bloomrpc)

This repo contains React frontend plugin. For the backend plugin, please checkout [backstage-grpc-playground-backend](https://github.com/zalopay-oss/backstage-grpc-playground-backend.git)

## Changelog

View [Full changelog](CHANGELOG.md)

## Requirements

- Backstage ^1.5.0
- Node.JS 14 | 16

## Methods supported

- Unary
- Client streaming
- Server streaming

## Not supported (yet)

We are currently not supporting

- Load proto from reflection. [See issue](https://github.com/zalopay-oss/backstage-grpc-playground/issues/2)

## Install

Install backstage-grpc-playground for `packages/app`

E.g: In your backstage project root

```zsh
yarn --cwd packages/app add backstage-grpc-playground
```

## Usage

#### Customize ApiDoc to use **backstage-grpc-playground** for `grpc` type

```typescript
// packages/app/src/apis.ts
import { GrpcPlaygroundComponent } from 'backstage-grpc-playground';

// your code
// ...

export const apis: AnyApiFactory[] = [
  // other apis 
  // ...
  
  createApiFactory({
    api: apiDocsConfigRef,
    deps: {},
    factory: () => {
      // load the default widgets
      const definitionWidgets = defaultDefinitionWidgets();

      return {
        getApiDefinitionWidget: (apiEntity: ApiEntity) => {
          // custom rendering for grpc
          if (apiEntity.spec.type === 'grpc') {
            return {
              type: 'grpc',
              title: 'gRPC Playground',
              component: GrpcPlaygroundComponent
            }
          }
          
          // fallback to the defaults
          return definitionWidgets.find(d => d.type === apiEntity.spec.type);
        },
      };
    },
  }),
]
```

#### A path `/grpc-playground` in backstage application

```tsx
// packages/app/src/App.tsx
import { GrpcPlaygroundPage } from 'backstage-grpc-playground'

// your code
// ...

const routes = (
  <FlatRoutes>
    // other routes 
    // ...
    <Route path="/grpc-playground" element={<GrpcPlaygroundPage />} />
  </FlatRoutes>
);
```

Example importing API definition from Github [examples/yaml-definition/unary.yaml](https://github.com/zalopay-oss/backstage-grpc-playground/blob/main/examples/yaml-definition/unary.yaml)

![import API](examples/images/import_1.gif)

## Compare to BloomRPC

- Load proto files from [defined entity spec](#yaml-file-definition) (learn more at [examples](#examples)), creating clients and send gRPC requests at [backstage backend](https://github.com/zalopay-oss/backstage-grpc-playground-backend.git)
- Proto files are contained in backend (default /packages/backend/proto)
- Able to view document generated as markdown with protoc-gen-doc integrated in backend plugin. See [example](#examples)
- Removed "Import from server reflection" [See issue](https://github.com/zalopay-oss/backstage-grpc-playground/issues/2)
- Removed "Add import paths" button
- Removed "gRPC-web" switch
- Missing imports warning, allow user to upload folder
  - User upload a file "employee.proto" that imports "common.proto"
  ![missing import 1](examples/images/missing_import_1.gif)

  - User upload a file "account.proto" that imports some google-apis proto files. In this case user should import google folder
  ![missing import 2](examples/images/missing_import_2.gif)
- Support generating document file in https://github.com/zalopay-oss/backstage-grpc-playground-backend/pull/1
- Support proto library https://github.com/zalopay-oss/backstage-grpc-playground/issues/9, see [guide](examples/yaml-definition/libraries.yaml)

## Yaml file definition

See [yaml-definition](examples/yaml-definition/README.md)

## Examples

#### View document

See [example](https://github.com/zalopay-oss/backstage-grpc-playground/pull/4)

#### Unary

![call 1](examples/images/call_unary.gif)

See [example](examples/unary/README.md)

#### Stream

![call 1](examples/images/call_stream.gif)

See [example](examples/stream/README.md)

## Acknowledgements

- Thanks to [Backstage Team](https://github.com/backstage/backstage) for creating an incredible framework
- Thanks to the authors of the awesome [BloomRPC Application](https://github.com/bloomrpc/bloomrpc)
- Feel free to [submit new issues](https://github.com/zalopay-oss/backstage-grpc-playground/issues/new)

---
_Source: https://npm.io/package/backstage-grpc-playground · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._