From ab96bb770f57e8d7e84375047d9a9e1ed49105f4 Mon Sep 17 00:00:00 2001
From: Camila Belo <camilaibs@gmail.com>
Date: Wed, 24 Sep 2025 09:57:46 +0200
Subject: [PATCH] feat: add package start entry dir option

Signed-off-by: Camila Belo <camilaibs@gmail.com>
---
 .changeset/modern-pugs-appear.md              | 21 +++++++++++++++++++
 docs/tooling/cli/03-commands.md               | 11 +++++-----
 .../build/commands/package/start/command.ts   |  1 +
 .../commands/package/start/startPackage.ts    |  3 ++-
 packages/cli/src/modules/build/index.ts       |  4 ++++
 5 files changed, 34 insertions(+), 6 deletions(-)
 create mode 100644 .changeset/modern-pugs-appear.md

diff --git a/.changeset/modern-pugs-appear.md b/.changeset/modern-pugs-appear.md
new file mode 100644
index 0000000000..c9b9f56e89
--- /dev/null
+++ b/.changeset/modern-pugs-appear.md
@@ -0,0 +1,21 @@
+---
+'@backstage/cli': patch
+---
+
+Added a new `--entry-dir` option to the `package start` command, which allows you to specify a custom entry directory for development applications. This is particularly useful when maintaining separate dev apps for different versions of your plugin (e.g., stable and alpha).
+
+**Example usage:**
+
+Consider the following plugin dev folder structure:
+
+```
+dev/
+  index.tsx
+  alpha/
+    index.ts
+```
+
+- The default `yarn package start` command uses the `dev/` folder as the entry point and executes `dev/index.tsx`
+- Running `yarn package start --entry-dir dev/alpha` will instead use `dev/alpha/` as the entry point and execute `dev/alpha/index.ts`
+
+This enables you to maintain multiple development environments within a single plugin package.
diff --git a/docs/tooling/cli/03-commands.md b/docs/tooling/cli/03-commands.md
index d176278655..da8a9650f1 100644
--- a/docs/tooling/cli/03-commands.md
+++ b/docs/tooling/cli/03-commands.md
@@ -177,11 +177,12 @@ Usage: backstage-cli package start [options]
 Start a package for local development
 
 Options:
-  --config <path>  Config files to load instead of app-config.yaml (default: [])
-  --role <name>    Run the command with an explicit package role
-  --check          Enable type checking and linting if available
-  --inspect        Enable debugger in Node.js environments
-  --inspect-brk    Enable debugger in Node.js environments, breaking before code starts
+  --config <path>     Config files to load instead of app-config.yaml (default: [])
+  --role <name>      Run the command with an explicit package role
+  --check            Enable type checking and linting if available
+  --inspect          Enable debugger in Node.js environments
+  --inspect-brk      Enable debugger in Node.js environments, breaking before code starts
+  --entry-dir <path> Path to the directory containing the entry point file
 ```
 
 ## package build
diff --git a/packages/cli/src/modules/build/commands/package/start/command.ts b/packages/cli/src/modules/build/commands/package/start/command.ts
index 05fc668356..4a65953f76 100644
--- a/packages/cli/src/modules/build/commands/package/start/command.ts
+++ b/packages/cli/src/modules/build/commands/package/start/command.ts
@@ -23,6 +23,7 @@ import { paths } from '../../../../../lib/paths';
 export async function command(opts: OptionValues): Promise<void> {
   await startPackage({
     role: await findRoleFromCommand(opts),
+    entryDir: opts.entryDir,
     targetDir: paths.targetDir,
     configPaths: opts.config as string[],
     checksEnabled: Boolean(opts.check),
diff --git a/packages/cli/src/modules/build/commands/package/start/startPackage.ts b/packages/cli/src/modules/build/commands/package/start/startPackage.ts
index 10f705ba4d..bac7bee68f 100644
--- a/packages/cli/src/modules/build/commands/package/start/startPackage.ts
+++ b/packages/cli/src/modules/build/commands/package/start/startPackage.ts
@@ -20,6 +20,7 @@ import { startFrontend } from './startFrontend';
 
 export async function startPackage(options: {
   role: PackageRole;
+  entryDir: string;
   targetDir: string;
   configPaths: string[];
   checksEnabled: boolean;
@@ -45,8 +46,8 @@ export async function startPackage(options: {
     case 'frontend-plugin':
     case 'frontend-plugin-module':
       return startFrontend({
-        entry: 'dev/index',
         ...options,
+        entry: `${options.entryDir ?? 'dev'}/index`,
       });
     case 'frontend-dynamic-container' as PackageRole: // experimental
       return startFrontend({
diff --git a/packages/cli/src/modules/build/index.ts b/packages/cli/src/modules/build/index.ts
index fd31a6c782..552a35a316 100644
--- a/packages/cli/src/modules/build/index.ts
+++ b/packages/cli/src/modules/build/index.ts
@@ -137,6 +137,10 @@ export const buildPlugin = createCliPlugin({
             '--link <path>',
             'Link an external workspace for module resolution',
           )
+          .option(
+            '--entry-dir <path>',
+            'Path to the directory containing the entry point file',
+          )
           .action(lazy(() => import('./commands/package/start'), 'command'));
 
         await defaultCommand.parseAsync(args, { from: 'user' });