Merge pull request #24673 from backstage/techdocs-make-builder-config-optional

Techdocs: make builder config optional

.changeset/metal-years-rhyme.md

@@ -0,0 +1,6 @@
+---
+'@backstage/plugin-techdocs-backend': patch
+'@backstage/plugin-techdocs': patch
+---
+
+The `techdocs.builder` config is now optional and it will default to `local`.

packages/techdocs-cli-embedded-app/src/apis.ts

@@ -72,7 +72,7 @@ class TechDocsDevStorageApi implements TechDocsStorageApi {
   }
 
   async getBuilder() {
-    return this.configApi.getString('techdocs.builder');
+    return this.configApi.getOptionalString('techdocs.builder') || 'local';
   }
 
   async getEntityDocs(_entityId: CompoundEntityRef, path: string) {

plugins/techdocs-backend/config.d.ts

@@ -24,7 +24,7 @@ export interface Config {
      * Documentation building process depends on the builder attr
      * @visibility frontend
      */
-    builder: 'local' | 'external';
+    builder?: 'local' | 'external';
 
     /**
      * Techdocs generator information

plugins/techdocs-backend/src/service/DefaultDocsBuildStrategy.test.ts

@@ -17,12 +17,6 @@
 import { DefaultDocsBuildStrategy } from './DefaultDocsBuildStrategy';
 import { ConfigReader } from '@backstage/config';
 
-const MockedConfigReader = ConfigReader as jest.MockedClass<
-  typeof ConfigReader
->;
-
-jest.mock('@backstage/config');
-
 describe('DefaultDocsBuildStrategy', () => {
   const entity = {
     apiVersion: 'backstage.io/v1alpha1',
@@ -33,32 +27,40 @@ describe('DefaultDocsBuildStrategy', () => {
     },
   };
 
-  const config = new ConfigReader({});
-
-  beforeEach(() => {
-    jest.resetAllMocks();
-  });
-
   describe('shouldBuild', () => {
-    it('should return true when techdocs.build is set to local', async () => {
-      const defaultDocsBuildStrategy =
-        DefaultDocsBuildStrategy.fromConfig(config);
-
-      MockedConfigReader.prototype.getString.mockReturnValue('local');
+    it('should return true when techdocs.builder is set to local', async () => {
+      const defaultDocsBuildStrategy = DefaultDocsBuildStrategy.fromConfig(
+        new ConfigReader({
+          techdocs: {
+            builder: 'local',
+          },
+        }),
+      );
 
       const result = await defaultDocsBuildStrategy.shouldBuild({ entity });
 
       expect(result).toBe(true);
     });
 
-    it('should return false when techdocs.build is set to external', async () => {
-      const defaultDocsBuildStrategy =
-        DefaultDocsBuildStrategy.fromConfig(config);
-
-      MockedConfigReader.prototype.getString.mockReturnValue('external');
+    it('should return true when techdocs.builder is not set', async () => {
+      const defaultDocsBuildStrategy = DefaultDocsBuildStrategy.fromConfig(
+        new ConfigReader({ techdocs: {} }),
+      );
 
       const result = await defaultDocsBuildStrategy.shouldBuild({ entity });
+      expect(result).toBe(true);
+    });
 
+    it('should return false when techdocs.builder is set to external', async () => {
+      const defaultDocsBuildStrategy = DefaultDocsBuildStrategy.fromConfig(
+        new ConfigReader({
+          techdocs: {
+            builder: 'external',
+          },
+        }),
+      );
+
+      const result = await defaultDocsBuildStrategy.shouldBuild({ entity });
       expect(result).toBe(false);
     });
   });

plugins/techdocs-backend/src/service/DefaultDocsBuildStrategy.ts

@@ -29,6 +29,8 @@ export class DefaultDocsBuildStrategy implements DocsBuildStrategy {
   }
 
   async shouldBuild(_: { entity: Entity }): Promise<boolean> {
-    return this.config.getString('techdocs.builder') === 'local';
+    return [undefined, 'local'].includes(
+      this.config.getOptionalString('techdocs.builder'),
+    );
   }
 }

plugins/techdocs/config.d.ts

@@ -24,7 +24,7 @@ export interface Config {
      * Documentation building process depends on the builder attr
      * @visibility frontend
      */
-    builder: 'local' | 'external';
+    builder?: 'local' | 'external';
 
     /**
      * Allows fallback to case-sensitive triplets in case of migration issues.

plugins/techdocs/src/client.ts

@@ -151,7 +151,7 @@ export class TechDocsStorageClient implements TechDocsStorageApi {
   }
 
   async getBuilder(): Promise<string> {
-    return this.configApi.getString('techdocs.builder');
+    return this.configApi.getOptionalString('techdocs.builder') || 'local';
   }
 
   /**

plugins/techdocs/src/reader/components/TechDocsNotFound.tsx

@@ -39,7 +39,7 @@ export const TechDocsNotFound = ({ errorMessage }: Props) => {
   }, [analyticsApi, entityRef, location]);
 
   let additionalInfo = '';
-  if (techdocsBuilder !== 'local') {
+  if (![undefined, 'local'].includes(techdocsBuilder)) {
     additionalInfo =
       "Note that techdocs.builder is not set to 'local' in your config, which means this Backstage app will not " +
       "generate docs if they are not found. Make sure the project's docs are generated and published by some external " +