Improving documentation of @frontside/backstage-plugin-graphql

.changeset/yellow-houses-exercise.md

@@ -0,0 +1,5 @@
+---
+'@frontside/backstage-plugin-graphql': patch
+---
+
+Adding README for `@frontside/backstage-plugin-graphql`

plugins/graphql/README.md

@@ -1,9 +1,58 @@
-# graphql
+# @frontside/backstage-plugin-graphql
 
-Welcome to the plugin for Backstage that exposes a GraphQL API for data stored in the Backstage catalog.
+> **Status**
+> Alpha - this plugin is in early stages but it already includes many design features that came from our experience implementing GraphQL API for Backstage with our clients. You should expect the schema provided by this plugin to change because we're missing a number of important features.
+
+Backstage GraphQL Plugin adds a GraphQL API to a Backstage developer portal. The GraphQL API behaves like a gateway to provide a single API for a growing number of features provided by Backstage. 
+
+It includes the following features,
+
+1. Graph schema - easily query relationships between data in the catalog.
+2. Schema-based resolvers - add field resolvers using directives without requiring JavaScript.
+3. Modular schema definition - allows organizing related schema into [graphql-modules](https://www.graphql-modules.com/docs)
+4. Strives to support - [GraphQL Server Specification]
+
+Some key features are currently missing. These features may change the schema in backward-incompatible ways.
+
+1. [`Connection`](https://relay.dev/docs/guides/graphql-server-specification/#connections) based on [GraphQL Cursor Connections Specification](https://relay.dev/graphql/connections.htm).(see [#68](https://github.com/thefrontside/backstage/issues/68))
+2. `viewer` query for retrieving data for the current user. (see [#67](https://github.com/thefrontside/backstage/issues/67))
+
+We plan to add these over time. If you're interested in contributing to this plugin, feel free to message us in [`#graphql` channel in Backstage Discord](https://discord.gg/yXEYX2h7Ed).
 
 ## Getting started
 
-```
-yarn add @frontside/backstage-plugin-graphql
-```
+You can install the GraphQL Plugin using the same process that you would use to install other backend Backtstage plugins.
+
+1. Run `yarn add @frontside/backstage-plugin-graphql` in `packages/backend`
+2. Create `packages/backend/src/plugins/graphql.ts` file with the following content
+
+   ```ts
+    import { createRouter } from '@frontside/backstage-plugin-graphql';
+    import { Router } from 'express';
+    import { PluginEnvironment } from '../types';
+
+    export default async function createPlugin(
+      env: PluginEnvironment,
+    ): Promise<Router> {
+      return await createRouter({
+        logger: env.logger,
+        catalog: env.catalog,
+      });
+    }
+   ```
+
+3. Add plugin's router to your backend API router in `packages/backend/src/index.ts`
+
+  ```ts
+  // import the graphql plugin
+  import graphql from './plugins/graphql';
+
+  // create the graphql plugin environment
+  const graphqlEnv = useHotMemoize(module, () => createEnv('graphql'));
+
+  // add `/graphql` route to your apiRouter
+  apiRouter.use('/graphql', await graphql(graphqlEnv));
+  ```
+
+  See [packages/backend/src/index.ts](https://github.com/thefrontside/backstage/blob/main/packages/backend/src/index.ts) for an example.
+

plugins/graphql/package.json

@@ -68,7 +68,8 @@
   },
   "files": [
     "dist",
-    "src/app/modules/**/*.graphql"
+    "src/app/modules/**/*.graphql",
+    "README.md"
   ],
   "jest": {
     "testTimeout": 15000