Merge pull request #15559 from agentbellnorm/provide-embedded-app-bundle

[TechDocs] Allow user to provide embedded app bundle and specify port

.changeset/dry-camels-scream.md

@@ -0,0 +1,5 @@
+---
+'@techdocs/cli': minor
+---
+
+Add `--preview-app-bundle-path` and `--preview-app-port` options to the `serve` command enabling previewing with apps other than the provided one

docs/features/techdocs/cli.md

@@ -70,6 +70,11 @@ a Backstage app server on port 3000. The Backstage app has a custom TechDocs API
 implementation, which uses the MkDocs preview server as a proxy to fetch the
 generated documentation files and assets.
 
+Backstage instances might differ from the provided preview app in appearance and
+behavior. To preview documentation with a different app, use
+`--preview-app-bundle-path` with a path to the bundle of the app to use instead.
+Typically, a `dist` or `build` directory.
+
 NOTE: When using a custom `techdocs` docker image, make sure the entry point is
 also `ENTRYPOINT ["mkdocs"]` or override with `--docker-entrypoint`.
 
@@ -81,14 +86,17 @@ Usage: techdocs-cli serve [options]
 Serve a documentation project locally in a Backstage app-like environment
 
 Options:
-  -i, --docker-image <DOCKER_IMAGE>        The mkdocs docker container to use (default: "spotify/techdocs")
-  --docker-entrypoint <DOCKER_ENTRYPOINT>  Override the image entrypoint
-  --docker-option <DOCKER_OPTION...>       Extra options to pass to the docker run command, e.g. "--add-host=internal.host:192.168.11.12"
-                                           (can be added multiple times).
-  --no-docker                              Do not use Docker, use MkDocs executable in current user environment.
-  --mkdocs-port <PORT>                     Port for MkDocs server to use (default: "8000")
-  -v --verbose                             Enable verbose output. (default: false)
-  -h, --help                               display help for command
+  -i, --docker-image <DOCKER_IMAGE>           The mkdocs docker container to use (default: "spotify/techdocs")
+  --docker-entrypoint <DOCKER_ENTRYPOINT>     Override the image entrypoint
+  --docker-option <DOCKER_OPTION...>          Extra options to pass to the docker run command, e.g. "--add-host=internal.host:192.168.11.12"
+                                              (can be added multiple times).
+  --no-docker                                 Do not use Docker, use MkDocs executable in current user environment.
+  --mkdocs-port <PORT>                        Port for MkDocs server to use (default: "8000")
+  --preview-app-bundle-path <PATH_TO_BUNDLE>  Preview documentation using a web app other than the included one.
+  --preview-app-port <PORT>                   Port where the preview will be served.
+                                              Can only be used with "--preview-app-bundle-path". (default: "3000")
+  -v --verbose                                Enable verbose output. (default: false)
+  -h, --help                                  display help for command
 ```
 
 ### Generate TechDocs site from a documentation project

packages/techdocs-cli/cli-report.md

@@ -100,6 +100,8 @@ Options:
   --no-docker
   --mkdocs-port <PORT>
   -v --verbose
+  --preview-app-bundle-path <PATH_TO_BUNDLE>
+  --preview-app-port <PORT>
   -h, --help
 ```
 

packages/techdocs-cli/src/commands/index.ts

@@ -18,6 +18,7 @@ import { Command } from 'commander';
 import { TechdocsGenerator } from '@backstage/plugin-techdocs-node';
 
 const defaultDockerImage = TechdocsGenerator.defaultDockerImage;
+const defaultPreviewAppPort = '3000';
 
 export function registerCommands(program: Command) {
   program
@@ -251,6 +252,25 @@ export function registerCommands(program: Command) {
     )
     .option('--mkdocs-port <PORT>', 'Port for MkDocs server to use', '8000')
     .option('-v --verbose', 'Enable verbose output.', false)
+    .option(
+      '--preview-app-bundle-path <PATH_TO_BUNDLE>',
+      'Preview documentation using another web app',
+    )
+    .option(
+      '--preview-app-port <PORT>',
+      'Port for the preview app to be served on',
+      defaultPreviewAppPort,
+    )
+    .hook('preAction', command => {
+      if (
+        command.opts().previewAppPort !== defaultPreviewAppPort &&
+        !command.opts().previewAppBundlePath
+      ) {
+        command.error(
+          '--preview-app-port can only be used together with --preview-app-bundle-path',
+        );
+      }
+    })
     .action(lazy(() => import('./serve/serve').then(m => m.default)));
 }
 

packages/techdocs-cli/src/commands/serve/serve.ts

@@ -42,6 +42,10 @@ function findPreviewBundlePath(): string {
   }
 }
 
+function getPreviewAppPath(opts: OptionValues): string {
+  return opts.previewAppBundlePath ?? findPreviewBundlePath();
+}
+
 export default async function serve(opts: OptionValues) {
   const logger = createLogger({ verbose: opts.verbose });
 
@@ -52,10 +56,6 @@ export default async function serve(opts: OptionValues) {
     ? true
     : false;
 
-  // TODO: Backstage app port should also be configurable as a CLI option. However, since we bundle
-  // a backstage app, we define app.baseUrl in the app-config.yaml.
-  // Hence, it is complicated to make this configurable.
-  const backstagePort = 3000;
   const backstageBackendPort = 7007;
 
   const mkdocsDockerAddr = `http://0.0.0.0:${opts.mkdocsPort}`;
@@ -115,9 +115,10 @@ export default async function serve(opts: OptionValues) {
     );
   }
 
-  const port = isDevMode ? backstageBackendPort : backstagePort;
+  const port = isDevMode ? backstageBackendPort : opts.previewAppPort;
+  const previewAppPath = getPreviewAppPath(opts);
   const httpServer = new HTTPServer(
-    findPreviewBundlePath(),
+    previewAppPath,
     port,
     opts.mkdocsPort,
     opts.verbose,