# Scaffolder Frontend

This is the React frontend for the default Backstage [software templates](https://backstage.io/docs/features/software-templates/).
This package supplies interfaces related to showing available templates in the
Backstage catalog and the workflow to create software using those templates.

## Installation

This `@backstage/plugin-scaffolder` package comes installed by default in any
Backstage application created with `npx @backstage/create-app`, so installation
is not usually required.

To check if you already have the package, look under
`packages/app/package.json`, in the `dependencies` block, for
`@backstage/plugin-scaffolder`. The instructions below walk through restoring
the plugin, if you previously removed it.

```bash
# From your Backstage root directory
yarn --cwd packages/app add @backstage/plugin-scaffolder
```

Once installed, the plugin is automatically available in your app through the default feature discovery. For more details and alternative installation methods, see [installing plugins](https://backstage.io/docs/frontend-system/building-apps/installing-plugins).

### Troubleshooting

If you encounter [issues with early closure of the `EventStream`](https://github.com/backstage/backstage/issues/5535)
used to auto-update logs during task execution, you can work around them by enabling
long polling. To do so, update your `packages/app/src/apis.ts` file to register a
`ScaffolderClient` with `useLongPollingLogs` set to `true`. By default, it is `false`.

```typescript
import {
  AnyApiFactory,
  createApiFactory,
  discoveryApiRef,
  fetchApiRef,
  identityApiRef,
} from '@backstage/core-plugin-api';
import { scmIntegrationsApiRef } from '@backstage/integration-react';
import {
  scaffolderApiRef,
  ScaffolderClient,
} from '@backstage/plugin-scaffolder';

export const apis: AnyApiFactory[] = [
  createApiFactory({
    api: scaffolderApiRef,
    deps: {
      discoveryApi: discoveryApiRef,
      identityApi: identityApiRef,
      scmIntegrationsApi: scmIntegrationsApiRef,
      fetchApi: fetchApiRef,
    },
    factory: ({ scmIntegrationsApi, discoveryApi, identityApi, fetchApi }) =>
      new ScaffolderClient({
        discoveryApi,
        identityApi,
        scmIntegrationsApi,
        fetchApi,
        useLongPollingLogs: true,
      }),
  }),
  // ... other factories
];
```

This replaces the default implementation of the `scaffolderApiRef`.

### Local development

When you develop a new template, action or new `<ScaffolderFieldExtensions/>`, then we recommend
to launch the plugin locally using the `createDevApp` of the `./dev/index.tsx` file for testing/Debugging purposes

To play with it, open a terminal and run the command: `yarn start` within the `./plugins/scaffolder` folder

**NOTE:** Don't forget to open a second terminal, start your Backstage backend there,
and configure the template locations that you want to test.

## Old Frontend System

If your Backstage app uses the old frontend system, you need to manually wire the plugin into your app as outlined in this section. If you are on the new frontend system, you can skip this.

### Add the plugin to your `packages/app`

Add the root page that the scaffolder plugin provides to your app. You can
choose any path for the route, but we recommend the following:

```diff
// packages/app/src/App.tsx
+import { ScaffolderPage } from '@backstage/plugin-scaffolder';


<FlatRoutes>
  <Route path="/catalog" element={<CatalogIndexPage />} />
  <Route path="/catalog/:namespace/:kind/:name" element={<CatalogEntityPage />}>
    {entityPage}
  </Route>
+  <Route path="/create" element={<ScaffolderPage />} />;
  ...
</FlatRoutes>
```

The scaffolder plugin also has one external route that needs to be bound for it
to function: the `registerComponent` route which should link to the page where
the user can register existing software component. In a typical setup, the
register component route will be linked to the `catalog-import` plugin's import
page:

```diff
// packages/app/src/App.tsx
+import { scaffolderPlugin } from '@backstage/plugin-scaffolder';
+import { catalogImportPlugin } from '@backstage/plugin-catalog-import';

const app = createApp({
  // ...
  bindRoutes({ bind }) {
+    bind(scaffolderPlugin.externalRoutes, {
+      registerComponent: catalogImportPlugin.routes.importPage,
+    });
  },
});
```

You may also want to add a link to the scaffolder page to your application
sidebar:

```diff
// packages/app/src/components/Root/Root.tsx
+import CreateComponentIcon from '@material-ui/icons/AddCircleOutline';

export const Root = ({ children }: PropsWithChildren<{}>) => (
  <SidebarPage>
    <Sidebar>
+      <SidebarItem icon={CreateComponentIcon} to="create" text="Create..." />;
      ...
    </Sidebar>
```

## Links

- [scaffolder-backend](https://github.com/backstage/backstage/tree/master/plugins/scaffolder-backend)
  provides the backend API for this frontend.