chore(coder plugin): make template names optional

packages/app/src/components/catalog/EntityPage.tsx

@@ -137,8 +137,8 @@ const coderAppConfig: CoderAppConfig = {
   },
 
   workspaces: {
-    templateName: 'devcontainers',
-    mode: 'manual',
+    defaultTemplateName: 'devcontainers',
+    defaultMode: 'manual',
     repoUrlParamKeys: ['custom_repo', 'repo_url'],
     params: {
       repo: 'custom',

plugins/backstage-plugin-coder/README.md

@@ -28,22 +28,23 @@ the Dev Container.
    yarn --cwd packages/app add @coder/backstage-plugin-coder
    ```
 
-1. Add the proxy key to your `app-config.yaml`:
+2. Add the proxy key to your `app-config.yaml`:
 
    ```yaml
    proxy:
      endpoints:
        '/coder':
-         # Replace with your Coder deployment access URL and a trailing /
+         # Replace with your Coder deployment access URL (add a trailing slash)
          target: 'https://coder.example.com/'
+
          changeOrigin: true
-         allowedMethods: ['GET']
+         allowedMethods: ['GET'] # Additional methods will be supported soon!
          allowedHeaders: ['Authorization', 'Coder-Session-Token']
          headers:
            X-Custom-Source: backstage
    ```
 
-1. Add the `CoderProvider` to the application:
+3. Add the `CoderProvider` to the application:
 
    ```tsx
    // In packages/app/src/App.tsx
@@ -58,14 +59,16 @@ the Dev Container.
      },
 
      // Set the default template (and parameters) for
-     // catalog items. This can be overridden in the
-     // catalog-info.yaml for specific items.
+     // catalog items. Individual properties can be overridden
+     // by a repo's catalog-info.yaml file
      workspaces: {
-       templateName: 'devcontainers',
-       mode: 'manual',
-       // This parameter is used to filter Coder workspaces
-       // by a repo URL parameter.
+       defaultTemplateName: 'devcontainers',
+       defaultMode: 'manual',
+
+       // This property defines which parameters in your Coder
+       // workspace templates are used to store repository links
        repoUrlParamKeys: ['custom_repo', 'repo_url'],
+
        params: {
          repo: 'custom',
          region: 'eu-helsinki',
@@ -88,7 +91,7 @@ the Dev Container.
 
    **Note:** You can also wrap a single page or component with `CoderProvider` if you only need Coder in a specific part of your app. See our [API reference](./docs/README.md) (particularly the section on [the `CoderProvider` component](./docs/components.md#coderprovider)) for more details.
 
-1. Add the `CoderWorkspacesCard` card to the entity page in your app:
+4. Add the `CoderWorkspacesCard` card to the entity page in your app:
 
    ```tsx
    // In packages/app/src/components/catalog/EntityPage.tsx
@@ -101,6 +104,33 @@ the Dev Container.
    </Grid>;
    ```
 
+### `app-config.yaml` files
+
+In addition to the above, you can define additional properties on your specific repo's `catalog-info.yaml` file.
+
+Example:
+
+```yaml
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: python-project
+spec:
+  type: other
+  lifecycle: unknown
+  owner: pms
+
+  # Properties for the Coder plugin are placed here
+  coder:
+    templateName: 'devcontainers'
+    mode: 'auto'
+    params:
+      repo: 'custom'
+      region: 'us-pittsburgh'
+```
+
+You can find more information about what properties are available (and how they're applied) in our [`catalog-info.yaml` file documentation](./docs/catalog-info.md).
+
 ## Roadmap
 
 This plugin is in active development. The following features are planned:

plugins/backstage-plugin-coder/dev/DevPage.tsx

@@ -24,8 +24,8 @@ const appConfig: CoderAppConfig = {
   },
 
   workspaces: {
-    templateName: 'devcontainers',
-    mode: 'manual',
+    defaultTemplateName: 'devcontainers',
+    defaultMode: 'manual',
     repoUrlParamKeys: ['custom_repo', 'repo_url'],
     params: {
       repo: 'custom',

plugins/backstage-plugin-coder/docs/catalog-info.md

@@ -0,0 +1,59 @@
+# `catalog-info.yaml` files
+
+This file provides documentation for all properties that the Coder plugin recognizes from Backstage's [`catalog-info.yaml` files](https://backstage.io/docs/features/software-catalog/descriptor-format/).
+
+## Example file
+
+```yaml
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: python-project
+spec:
+  type: other
+  lifecycle: unknown
+  owner: pms
+
+  # Properties for the Coder plugin are placed here
+  coder:
+    templateName: 'devcontainers'
+    mode: 'auto'
+    params:
+      repo: 'custom'
+      region: 'us-pittsburgh'
+```
+
+All config properties are placed under the `spec.coder` property.
+
+## Where these properties are used
+
+At present, there are two main areas where these values are used:
+
+- [`CoderWorkspacesCard`](./components.md#coderworkspacescard) (and all sub-components)
+- [`useCoderWorkspacesConfig`](./hooks.md#usecoderworkspacesconfig)
+
+## Property listing
+
+### `templateName`
+
+**Type:** Optional `string`
+
+This defines the name of the Coder template you would like to use when creating new workspaces from Backstage.
+
+**Note:** This value has overlap with the `defaultTemplateName` property defined in [`CoderAppConfig`](types.md#coderappconfig). In the event that both values are present, the YAML file's `templateName` property will always be used instead.
+
+### `templateName`
+
+**Type:** Optional union of `manual` or `auto`
+
+This defines the workspace creation mode that will be embedded as a URL parameter in any outgoing links to make new workspaces in your Coder deployment. (e.g.,`useCoderWorkspacesConfig`'s `creationUrl` property)
+
+**Note:** This value has overlap with the `defaultMode` property defined in [`CoderAppConfig`](types.md#coderappconfig). In the event that both values are present, the YAML file's `mode` property will always be used instead.
+
+### `params`
+
+**Type:** Optional JSON object of string values (equivalent to TypeScript's `Record<string, string | undefined>`)
+
+This allows you to define additional Coder workspace parameter values that should be passed along to any outgoing URLs for making new workspaces in your Coder deployment. These values are fully dynamic, and unfortunately, cannot have much type safety.
+
+**Note:** The properties from the `params` property are automatically merged with the properties defined via `CoderAppConfig`'s `params` property. In the event of any key conflicts, the params from `catalog-info.yaml` will always win.