feat: add package start entry dir option

Signed-off-by: Camila Belo <camilaibs@gmail.com>

.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.

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

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),

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({

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' });