Merge pull request #10150 from backstage/freben/plugin-head

make the backend plugin ts files consistent

docs/auth/google/gcp-iap-auth.md

@@ -45,17 +45,14 @@ Add a `providerFactories` entry to the router in
 ```ts
 import { createGcpIapProvider } from '@backstage/plugin-auth-backend';
 
-export default async function createPlugin({
-  logger,
-  database,
-  config,
-  discovery,
-}: PluginEnvironment): Promise<Router> {
+export default async function createPlugin(
+  env: PluginEnvironment,
+): Promise<Router> {
   return await createRouter({
-    logger,
-    config,
-    database,
-    discovery,
+    logger: env.logger,
+    config: env.config,
+    database: env.database,
+    discovery: env.discovery,
     providerFactories: {
       'gcp-iap': createGcpIapProvider({
         // Replace the auth handler if you want to customize the returned user

docs/auth/identity-resolver.md

@@ -29,9 +29,9 @@ sign-in resolvers and set them for any of the Authentication providers inside
 ```ts
 import { DEFAULT_NAMESPACE, stringifyEntityRef } from '@backstage/catalog-model';
 
-export default async function createPlugin({
-  ...
-}: PluginEnvironment): Promise<Router> {
+export default async function createPlugin(
+  env: PluginEnvironment,
+): Promise<Router> {
   return await createRouter({
     ...
     providerFactories: {
@@ -105,13 +105,13 @@ matching `google.com/email` annotation.
 
 It can be enabled like this
 
-```tsx
+```ts
 // File: packages/backend/src/plugins/auth.ts
 import { googleEmailSignInResolver, createGoogleProvider } from '@backstage/plugin-auth-backend';
 
-export default async function createPlugin({
-  ...
-}: PluginEnvironment): Promise<Router> {
+export default async function createPlugin(
+  env: PluginEnvironment,
+): Promise<Router> {
   return await createRouter({
     ...
     providerFactories: {
@@ -130,9 +130,9 @@ can do this using the `CatalogIdentityClient` provided as context to Sign-In
 resolvers:
 
 ```ts
-export default async function createPlugin({
-  ...
-}: PluginEnvironment): Promise<Router> {
+export default async function createPlugin(
+  env: PluginEnvironment,
+): Promise<Router> {
   return await createRouter({
     ...
     providerFactories: {
@@ -174,11 +174,11 @@ display name and profile picture.
 This is also the place where you can do authorization and validation of the user
 and throw errors if the user should not be allowed access in Backstage.
 
-```tsx
+```ts
 // File: packages/backend/src/plugins/auth.ts
-export default async function createPlugin({
-  ...
-}: PluginEnvironment): Promise<Router> {
+export default async function createPlugin(
+  env: PluginEnvironment,
+): Promise<Router> {
   return await createRouter({
     ...
     providerFactories: {

docs/features/kubernetes/installation.md

@@ -60,15 +60,15 @@ add the following:
 ```typescript
 // In packages/backend/src/plugins/kubernetes.ts
 import { KubernetesBuilder } from '@backstage/plugin-kubernetes-backend';
+import { Router } from 'express';
 import { PluginEnvironment } from '../types';
 
-export default async function createPlugin({
-  logger,
-  config,
-}: PluginEnvironment) {
+export default async function createPlugin(
+  env: PluginEnvironment,
+): Promise<Router> {
   const { router } = await KubernetesBuilder.createBuilder({
-    logger,
-    config,
+    logger: env.logger,
+    config: env.config,
   }).build();
   return router;
 }

docs/features/search/getting-started.md

@@ -150,20 +150,24 @@ import {
 } from '@backstage/plugin-search-backend-node';
 import { PluginEnvironment } from '../types';
 import { DefaultCatalogCollator } from '@backstage/plugin-catalog-backend';
+import { Router } from 'express';
 
-export default async function createPlugin({
-  logger,
-  discovery,
-  tokenManager,
-}: PluginEnvironment) {
-  const searchEngine = new LunrSearchEngine({ logger });
-  const indexBuilder = new IndexBuilder({ logger, searchEngine });
+export default async function createPlugin(
+  env: PluginEnvironment,
+): Promise<Router> {
+  const searchEngine = new LunrSearchEngine({
+    logger: env.logger,
+  });
+  const indexBuilder = new IndexBuilder({
+    logger: env.logger,
+    searchEngine,
+  });
 
   indexBuilder.addCollator({
     defaultRefreshIntervalSeconds: 600,
     collator: new DefaultCatalogCollator({
-      discovery,
-      tokenManager,
+      discovery: env.discovery,
+      tokenManager: env.tokenManager,
     }),
   });
 
@@ -174,7 +178,7 @@ export default async function createPlugin({
 
   return await createRouter({
     engine: indexBuilder.getSearchEngine(),
-    logger,
+    logger: env.logger,
   });
 }
 ```
@@ -285,13 +289,13 @@ which are responsible for providing documents
 number of collators with the `IndexBuilder` like this:
 
 ```typescript
-const indexBuilder = new IndexBuilder({ logger, searchEngine });
+const indexBuilder = new IndexBuilder({ logger: env.logger, searchEngine });
 
 indexBuilder.addCollator({
   defaultRefreshIntervalSeconds: 600,
   collator: new DefaultCatalogCollator({
-    discovery,
-    tokenManager,
+    discovery: env.discovery,
+    tokenManager: env.tokenManager,
   }),
 });
 
@@ -311,8 +315,8 @@ its `defaultRefreshIntervalSeconds` value, like this:
 indexBuilder.addCollator({
   defaultRefreshIntervalSeconds: 600,
   collator: new DefaultCatalogCollator({
-    discovery,
-    tokenManager,
+    discovery: env.discovery,
+    tokenManager: env.tokenManager,
   }),
 });
 ```

docs/features/search/how-to-guides.md

@@ -72,10 +72,10 @@ import { DefaultTechDocsCollatorFactory } from '@backstage/plugin-techdocs-backe
 ```typescript
 indexBuilder.addCollator({
   defaultRefreshIntervalSeconds: 600,
-  factory: DefaultTechDocsCollatorFactory.fromConfig(config, {
-    discovery,
-    logger,
-    tokenManager,
+  factory: DefaultTechDocsCollatorFactory.fromConfig(env.config, {
+    discovery: env.discovery,
+    logger: env.logger,
+    tokenManager: env.tokenManager,
   }),
 });
 ```
@@ -120,9 +120,9 @@ provided by `@backstage/plugin-catalog-backend` offers some configuration too!
 
 indexBuilder.addCollator({
   defaultRefreshIntervalSeconds: 600,
-  collator: DefaultCatalogCollator.fromConfig(config, {
-    discovery,
-    tokenManager,
+  collator: DefaultCatalogCollator.fromConfig(env.config, {
+    discovery: env.discovery,
+    tokenManager: env.tokenManager,
 +   filter: {
 +      kind: ['API', 'Component', 'Domain', 'Group', 'System', 'User'],
 +   },
@@ -167,18 +167,22 @@ provided by existing plugins, the migration process is fairly straightforward:
    +import { DefaultCatalogCollatorFactory } from '@backstage/plugin-catalog-backend';
    +import { DefaultTechDocsCollatorFactory } from '@backstage/plugin-techdocs-backend';
    // ...
-     const indexBuilder = new IndexBuilder({ logger, searchEngine });
+     const indexBuilder = new IndexBuilder({ logger: env.logger, searchEngine });
      indexBuilder.addCollator({
        defaultRefreshIntervalSeconds: 600,
-   -    collator: DefaultCatalogCollator.fromConfig(config, { discovery }),
-   +    factory: DefaultCatalogCollatorFactory.fromConfig(config, { discovery }),
+   -    collator: DefaultCatalogCollator.fromConfig(env.config, {
+          discovery: env.discovery,
+        }),
+   +    factory: DefaultCatalogCollatorFactory.fromConfig(env.config, {
+          discovery: env.discovery,
+        }),
      });
      indexBuilder.addCollator({
        defaultRefreshIntervalSeconds: 600,
-   -    collator: DefaultTechDocsCollator.fromConfig(config, {
-   +    factory: DefaultTechDocsCollatorFactory.fromConfig(config, {
-         discovery,
-         logger,
+   -     collator: DefaultTechDocsCollator.fromConfig(env.config, {
+   +     factory: DefaultTechDocsCollatorFactory.fromConfig(env.config, {
+           discovery: env.discovery,
+           logger: env.logger,
        }),
      });
    ```

docs/features/search/search-engines.md

@@ -17,7 +17,7 @@ provided search engines by using the exposed setter to set the modified query
 translator into the instance.
 
 ```typescript
-const searchEngine = new LunrSearchEngine({ logger });
+const searchEngine = new LunrSearchEngine({ logger: env.logger });
 searchEngine.setTranslator(new MyNewAndBetterQueryTranslator());
 ```
 
@@ -30,8 +30,8 @@ Lunr can be instantiated like this:
 
 ```typescript
 // app/backend/src/plugins/search.ts
-const searchEngine = new LunrSearchEngine({ logger });
-const indexBuilder = new IndexBuilder({ logger, searchEngine });
+const searchEngine = new LunrSearchEngine({ logger: env.logger });
+const indexBuilder = new IndexBuilder({ logger: env.logger, searchEngine });
 ```
 
 ## Postgres
@@ -58,9 +58,9 @@ configured and make the following changes to your backend:
 // In packages/backend/src/plugins/search.ts
 
 // Initialize a connection to a search engine.
-const searchEngine = (await PgSearchEngine.supported(database))
-  ? await PgSearchEngine.from({ database })
-  : new LunrSearchEngine({ logger });
+const searchEngine = (await PgSearchEngine.supported(env.database))
+  ? await PgSearchEngine.from({ database: env.database })
+  : new LunrSearchEngine({ logger: env.logger });
 ```
 
 ## ElasticSearch
@@ -74,10 +74,10 @@ Similarly to Lunr above, ElasticSearch can be set up like this:
 ```typescript
 // app/backend/src/plugins/search.ts
 const searchEngine = await ElasticSearchSearchEngine.initialize({
-  logger,
-  config,
+  logger: env.logger,
+  config: env.config,
 });
-const indexBuilder = new IndexBuilder({ logger, searchEngine });
+const indexBuilder = new IndexBuilder({ logger: env.logger, searchEngine });
 ```
 
 For the engine to be available, your backend package needs a dependency into

docs/features/software-catalog/descriptor-format.md

@@ -64,7 +64,7 @@ spec:
 
 This is the same entity as returned in JSON from the software catalog API:
 
-```js
+```json
 {
   "apiVersion": "backstage.io/v1alpha1",
   "kind": "Component",
@@ -79,11 +79,13 @@ This is the same entity as returned in JSON from the software catalog API:
     "labels": {
       "example.com/custom": "custom_label_value"
     },
-    "links": [{
-      "url": "https://admin.example-org.com",
-      "title": "Admin Dashboard",
-      "icon": "dashboard"
-    }],
+    "links": [
+      {
+        "url": "https://admin.example-org.com",
+        "title": "Admin Dashboard",
+        "icon": "dashboard"
+      }
+    ],
     "tags": ["java"],
     "name": "artist-web",
     "uid": "2152f463-549d-4d8d-a94d-ce2b7676c6e2"

docs/features/software-templates/writing-custom-actions.md

@@ -108,11 +108,11 @@ should have something similar to the below in
 ```ts
 return await createRouter({
   containerRunner,
-  logger,
-  config,
-  database,
   catalogClient,
-  reader,
+  logger: env.logger,
+  config: env.config,
+  database: env.database,
+  reader: env.reader,
 });
 ```
 
@@ -123,25 +123,25 @@ will set the available actions that the scaffolder has access to.
 import { createBuiltinActions } from '@backstage/plugin-scaffolder-backend';
 import { ScmIntegrations } from '@backstage/integration';
 
-const integrations = ScmIntegrations.fromConfig(config);
+const integrations = ScmIntegrations.fromConfig(env.config);
 
 const builtInActions = createBuiltinActions({
   containerRunner,
   integrations,
-  config,
   catalogClient,
-  reader,
+  config: env.config,
+  reader: env.reader,
 });
 
 const actions = [...builtInActions, createNewFileAction()];
 return await createRouter({
   containerRunner,
-  logger,
-  config,
-  database,
   catalogClient,
-  reader,
   actions,
+  logger: env.logger,
+  config: env.config,
+  database: env.database,
+  reader: env.reader,
 });
 ```
 

docs/features/techdocs/getting-started.md

@@ -81,18 +81,16 @@ import {
   Publisher,
 } from '@backstage/plugin-techdocs-backend';
 import Docker from 'dockerode';
+import { Router } from 'express';
 import { PluginEnvironment } from '../types';
 
-export default async function createPlugin({
-  logger,
-  config,
-  discovery,
-  reader,
-}: PluginEnvironment) {
+export default async function createPlugin(
+  env: PluginEnvironment,
+): Promise<Router> {
   // Preparers are responsible for fetching source files for documentation.
-  const preparers = await Preparers.fromConfig(config, {
-    logger,
-    reader,
+  const preparers = await Preparers.fromConfig(env.config, {
+    logger: env.logger,
+    reader: env.reader,
   });
 
   // Docker client (conditionally) used by the generators, based on techdocs.generators config.
@@ -100,17 +98,17 @@ export default async function createPlugin({
   const containerRunner = new DockerContainerRunner({ dockerClient });
 
   // Generators are used for generating documentation sites.
-  const generators = await Generators.fromConfig(config, {
-    logger,
+  const generators = await Generators.fromConfig(env.config, {
+    logger: env.logger,
     containerRunner,
   });
 
   // Publisher is used for
   // 1. Publishing generated files to storage
   // 2. Fetching files from storage and passing them to TechDocs frontend.
-  const publisher = await Publisher.fromConfig(config, {
-    logger,
-    discovery,
+  const publisher = await Publisher.fromConfig(env.config, {
+    logger: env.logger,
+    discovery: env.discovery,
   });
 
   // checks if the publisher is working and logs the result
@@ -120,9 +118,9 @@ export default async function createPlugin({
     preparers,
     generators,
     publisher,
-    logger,
-    config,
-    discovery,
+    logger: env.logger,
+    config: env.config,
+    discovery: env.discovery,
   });
 }
 ```

docs/integrations/github/discovery.md

@@ -42,16 +42,16 @@ And then add the processors to your catalog builder:
    env: PluginEnvironment,
  ): Promise<Router> {
    const builder = await CatalogBuilder.create(env);
-+  const integrations = ScmIntegrations.fromConfig(config);
++  const integrations = ScmIntegrations.fromConfig(env.config);
 +  const githubCredentialsProvider =
 +    DefaultGithubCredentialsProvider.fromIntegrations(integrations);
 +  builder.addProcessor(
-+    GithubDiscoveryProcessor.fromConfig(config, {
-+      logger,
++    GithubDiscoveryProcessor.fromConfig(env.config, {
++      logger: env.logger,
 +      githubCredentialsProvider,
 +    }),
-+    GithubOrgReaderProcessor.fromConfig(config, {
-+      logger,
++    GithubOrgReaderProcessor.fromConfig(env.config, {
++      logger: env.logger,
 +      githubCredentialsProvider,
 +    }),
 +  );

docs/integrations/github/org.md

@@ -69,6 +69,6 @@ import { GithubOrgReaderProcessor } from '@backstage/plugin-catalog-backend';
 
 builder.replaceProcessors(
   // ... other processor replacements
-  GithubOrgReaderProcessor.fromConfig(config, { logger }),
+  GithubOrgReaderProcessor.fromConfig(env.config, { logger: env.logger }),
 );
 ```

docs/plugins/backend-plugin.md

@@ -76,9 +76,12 @@ following to it
 
 ```ts
 import { createRouter } from '@internal/plugin-carmen-backend';
+import { Router } from 'express';
 import { PluginEnvironment } from '../types';
 
-export default async function createPlugin(env: PluginEnvironment) {
+export default async function createPlugin(
+  env: PluginEnvironment,
+): Promise<Router> {
   // Here is where you will add all of the required initialization code that
   // your backend plugin needs to be able to start!
 
@@ -124,7 +127,9 @@ function, there is a `database` field. You can use that to get a
 
 ```ts
 // in packages/backend/src/plugins/carmen.ts
-export default async function createPlugin(env: PluginEnvironment) {
+export default async function createPlugin(
+  env: PluginEnvironment,
+): Promise<Router> {
   const db: Knex<any, unknown[]> = await env.database.getClient();
 
   // You will then pass this client into your actual plugin implementation

docs/plugins/testing.md

@@ -192,7 +192,7 @@ returns a result or displays an error or console message, like so:
 
 **`StringUtil ellipsis`**
 
-```js
+```ts
 export function ellipsis(text, maxLength, midCharIx = 0, ellipsis = '...') {
   // Do something blackbox. We should not care about the internals,
   // only inputs and outputs.
@@ -210,7 +210,7 @@ There are four things to test for in a utility function:
 
 > Handle Invalid Input (handle thrown errors):
 
-```js
+```ts
 it('Throws an error on improper arguments', () => {
   expect(() => {
     ellipsis();
@@ -220,7 +220,7 @@ it('Throws an error on improper arguments', () => {
 
 > Verify default input arguments:
 
-```js
+```ts
 it('Works with defaults', () => {
   expect(ellipsis('Hello world', 3)).toBe('Hel...');
   expect(ellipsis('', 3)).toBe('');
@@ -233,7 +233,7 @@ it('Works with defaults', () => {
 
 This is especially true for edge cases!
 
-```js
+```ts
 it('Works with midCharIx', () => {
   expect(ellipsis('Hello world', 3, 6)).toBe('...o w...');
   expect(ellipsis('', 3, 6)).toBe('');
@@ -265,7 +265,7 @@ For example:
 
 **`./MyApi.js`**
 
-```js
+```ts
 export {
   fetchSomethingFromServer: () => {
     // Live production call to a URI. Must be avoided during testing!
@@ -276,7 +276,7 @@ export {
 
 **`./__mocks__/MyApi.js`**
 
-```js
+```ts
 export {
   fetchSomethingFromServer: () => {
     // Simulate a production call, but avoid jest and just use a promise
@@ -287,7 +287,7 @@ export {
 
 **`./MyApi.test.js`**
 
-```js
+```ts
 /* eslint-disable import/first */
 
 jest.mock('./MyApi'); // Instruct Jest to swap all future imports of './MyApi.js' to './__mocks__/MyApi.js'

docs/plugins/url-reader.md

@@ -44,7 +44,7 @@ import { URLReaders } from '@backstage/backend-common';
 
 function makeCreateEnv(config: Config) {
   // ....
-  const reader = UrlReaders.default({ logger, config });
+  const reader = UrlReaders.default({ logger: root, config });
   //
 }
 ```