add --port flag to heft-storybook-plugin to set the storybook dev server port in serve mode (#5819)

Co-authored-by: Taylor Lodge <ubermouse@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: UberMouse

common/changes/@rushstack/heft-storybook-plugin/heft-storybook-plugin-port-flag_2026-06-05-15-54.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@rushstack/heft-storybook-plugin",
+      "comment": "Add `--port` flag to pass a specific dev server port through to the Storybook CLI in serve mode",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@rushstack/heft-storybook-plugin"
+}

heft-plugins/heft-storybook-plugin/heft-plugin.json

@@ -28,6 +28,12 @@
           "longName": "--no-open",
           "description": "Pass --no-open to the storybook CLI so it does not automatically open a browser window in serve mode.",
           "parameterKind": "flag"
+        },
+        {
+          "longName": "--port",
+          "description": "Pass --port to the storybook CLI to bind the dev server to a specific port in serve mode.",
+          "parameterKind": "string",
+          "argumentName": "PORT"
         }
       ]
     }

heft-plugins/heft-storybook-plugin/src/StorybookPlugin.ts

@@ -23,6 +23,7 @@ import type {
   IScopedLogger,
   IHeftTaskPlugin,
   CommandLineFlagParameter,
+  CommandLineStringParameter,
   IHeftTaskRunHookOptions
 } from '@rushstack/heft';
 import type {
@@ -191,6 +192,7 @@ interface IPrepareStorybookOptions extends IStorybookPluginOptions {
   isTestMode: boolean;
   isDocsMode: boolean;
   isNoOpenMode: boolean;
+  port: string | undefined;
 }
 
 const DEFAULT_STORYBOOK_VERSION: StorybookCliVersion = StorybookCliVersion.STORYBOOK7;
@@ -229,6 +231,7 @@ const STORYBOOK_FLAG_NAME: '--storybook' = '--storybook';
 const STORYBOOK_TEST_FLAG_NAME: '--storybook-test' = '--storybook-test';
 const DOCS_FLAG_NAME: '--docs' = '--docs';
 const NO_OPEN_FLAG_NAME: '--no-open' = '--no-open';
+const PORT_FLAG_NAME: '--port' = '--port';
 
 /** @public */
 export default class StorybookPlugin implements IHeftTaskPlugin<IStorybookPluginOptions> {
@@ -248,6 +251,8 @@ export default class StorybookPlugin implements IHeftTaskPlugin<IStorybookPlugin
     const docsParameter: CommandLineFlagParameter = taskSession.parameters.getFlagParameter(DOCS_FLAG_NAME);
     const noOpenParameter: CommandLineFlagParameter =
       taskSession.parameters.getFlagParameter(NO_OPEN_FLAG_NAME);
+    const portParameter: CommandLineStringParameter =
+      taskSession.parameters.getStringParameter(PORT_FLAG_NAME);
 
     const parseResult: IParsedPackageNameOrError = PackageName.tryParse(options.storykitPackageName);
     if (parseResult.error) {
@@ -312,6 +317,7 @@ export default class StorybookPlugin implements IHeftTaskPlugin<IStorybookPlugin
           isTestMode: storybookTestParameter.value,
           isDocsMode: docsParameter.value,
           isNoOpenMode: noOpenParameter.value,
+          port: portParameter.value,
           ...options
         });
         await this._runStorybookAsync(runStorybookOptions, options);
@@ -470,7 +476,7 @@ export default class StorybookPlugin implements IHeftTaskPlugin<IStorybookPlugin
     runStorybookOptions: IRunStorybookOptions,
     options: IStorybookPluginOptions
   ): Promise<void> {
-    const { logger, resolvedModulePath, verbose, isServeMode, isTestMode, isDocsMode, isNoOpenMode } =
+    const { logger, resolvedModulePath, verbose, isServeMode, isTestMode, isDocsMode, isNoOpenMode, port } =
       runStorybookOptions;
     let { workingDirectory, outputFolder } = runStorybookOptions;
     logger.terminal.writeLine('Running Storybook compilation');
@@ -522,6 +528,10 @@ export default class StorybookPlugin implements IHeftTaskPlugin<IStorybookPlugin
       storybookArgs.push('--no-open');
     }
 
+    if (isServeMode && port) {
+      storybookArgs.push('--port', port);
+    }
+
     const storybookEnv: NodeJS.ProcessEnv = {
       ...process.env,
       // Prevent corepack from prompting to pin a package manager version