Add --port to ng serve commands (#9113)

annajowang · web-flow · commit e175bb6689ab · 2025-09-12T20:53:49.000Z
diff --git a/src/emulator/apphosting/developmentServer.ts b/src/emulator/apphosting/developmentServer.ts
@@ -32,9 +32,10 @@ export async function detectPackageManager(rootdir: string): Promise<PackageMana
   throw new FirebaseError("Unsupported package manager");
 }
 
-export async function detectStartCommand(rootDir: string) {
+export async function detectPackageManagerStartCommand(rootDir: string) {
   try {
     const packageManager = await detectPackageManager(rootDir);
+    // TODO: This is not ideal for angular apps which don't usually have a dev script.
     return `${packageManager} run dev`;
   } catch (e) {
     throw new FirebaseError(
diff --git a/src/emulator/apphosting/serve.spec.ts b/src/emulator/apphosting/serve.spec.ts
@@ -17,7 +17,7 @@ describe("serve", () => {
   let checkListenableStub: sinon.SinonStub;
   let wrapSpawnStub: sinon.SinonStub;
   let spawnWithCommandStringStub: sinon.SinonStub;
-  let detectStartCommandStub: sinon.SinonStub;
+  let detectPackageManagerStartCommandStub: sinon.SinonStub;
   let configsStub: sinon.SinonStubbedInstance<typeof configsImport>;
   let resolveProjectPathStub: sinon.SinonStub;
   let listRunningWithInfoStub: sinon.SinonStub;
@@ -28,22 +28,22 @@ describe("serve", () => {
     checkListenableStub = sinon.stub(portUtils, "checkListenable");
     wrapSpawnStub = sinon.stub(spawn, "wrapSpawn");
     spawnWithCommandStringStub = sinon.stub(spawn, "spawnWithCommandString");
-    detectStartCommandStub = sinon.stub(utils, "detectStartCommand");
+    detectPackageManagerStartCommandStub = sinon.stub(utils, "detectPackageManagerStartCommand");
     configsStub = sinon.stub(configsImport);
     resolveProjectPathStub = sinon.stub(projectPathImport, "resolveProjectPath");
 
     listRunningWithInfoStub = sinon.stub(emulatorRegistry.EmulatorRegistry, "listRunningWithInfo");
     setEnvVarsForEmulatorsStub = sinon.stub(emulatorEnvs, "setEnvVarsForEmulators");
 
     resolveProjectPathStub.returns("");
-    detectStartCommandStub.returns("npm run dev");
+    detectPackageManagerStartCommandStub.returns("npm run dev");
 
     accessSecretVersionStub = sinon.stub(secrets, "accessSecretVersion");
   });
 
   afterEach(() => {
     wrapSpawnStub.restore();
-    detectStartCommandStub.restore();
+    detectPackageManagerStartCommandStub.restore();
     checkListenableStub.restore();
     sinon.verifyAndRestore();
   });
@@ -83,6 +83,30 @@ describe("serve", () => {
       expect(spawnWithCommandStringStub.getCall(0).args[0]).to.eq(startCommand);
     });
 
+    it("should append --port if an ng serve command is detected", async () => {
+      const startCommand = "ng serve --verbose";
+      checkListenableStub.onFirstCall().returns(true);
+      configsStub.getLocalAppHostingConfiguration.resolves(AppHostingYamlConfig.empty());
+
+      await serve.start({ startCommand });
+
+      expect(spawnWithCommandStringStub).to.be.called;
+      expect(spawnWithCommandStringStub.getCall(0).args[0]).to.eq(startCommand + " --port 5002");
+    });
+
+    it("should reject the custom command if a port is specified", async () => {
+      const startCommand = "ng serve --port 5004";
+      checkListenableStub.onFirstCall().returns(true);
+      configsStub.getLocalAppHostingConfiguration.resolves(AppHostingYamlConfig.empty());
+
+      await expect(serve.start({ startCommand })).to.be.rejectedWith(
+        FirebaseError,
+        /Specifying a port in the start command is not supported by the apphosting emulator/,
+      );
+
+      expect(spawnWithCommandStringStub).to.not.be.called;
+    });
+
     it("Should pass plaintext environment variables", async () => {
       const yaml = AppHostingYamlConfig.empty();
       yaml.env["FOO"] = { value: "BAR" };
diff --git a/src/emulator/apphosting/serve.ts b/src/emulator/apphosting/serve.ts
@@ -6,7 +6,7 @@
 import { isIPv4 } from "net";
 import * as clc from "colorette";
 import { checkListenable } from "../portUtils";
-import { detectPackageManager, detectStartCommand } from "./developmentServer";
+import { detectPackageManager, detectPackageManagerStartCommand } from "./developmentServer";
 import { DEFAULT_HOST, DEFAULT_PORTS } from "../constants";
 import { spawnWithCommandString } from "../../init/spawn";
 import { logger } from "./developmentServer";
@@ -33,32 +33,6 @@ interface StartOptions {
   rootDirectory?: string;
 }
 
-/**
- * Spins up a project locally by running the project's dev command.
- *
- * Assumptions:
- *  - Dev server runs on "localhost" when the package manager's dev command is
- *    run
- *  - Dev server will respect the PORT environment variable
- */
-export async function start(options?: StartOptions): Promise<{ hostname: string; port: number }> {
-  const hostname = DEFAULT_HOST;
-  let port = options?.port ?? DEFAULT_PORTS.apphosting;
-  while (!(await availablePort(hostname, port))) {
-    port += 1;
-  }
-
-  await serve(
-    options?.projectId,
-    options?.backendId,
-    port,
-    options?.startCommand,
-    options?.rootDirectory,
-  );
-
-  return { hostname, port };
-}
-
 // Matches a fully qualified secret or version name, e.g.
 // projects/my-project/secrets/my-secret/versions/1
 // projects/my-project/secrets/my-secret/versions/latest
@@ -111,22 +85,58 @@ async function loadSecret(project: string | undefined, name: string): Promise<st
 }
 
 /**
- * Runs the development server in a child process.
+ * Spins up a project locally by running the project's dev command.
+ *
+ * Assumptions:
+ *  - Dev server runs on "localhost" when the package manager's dev command is
+ *    run
+ *  - Dev server will respect the PORT environment variable
+ *    - This is not the case for Angular. When an `ng serve`
+ *       custom command is detected, we add --port <PORT> instead.
  */
-async function serve(
-  projectId: string | undefined,
-  backendId: string | undefined,
-  port: number,
-  startCommand?: string,
-  backendRelativeDir?: string,
-): Promise<void> {
-  backendRelativeDir = backendRelativeDir ?? "./";
+export async function start(options?: StartOptions): Promise<{ hostname: string; port: number }> {
+  const hostname = DEFAULT_HOST;
+  let port = options?.port ?? DEFAULT_PORTS.apphosting;
+  while (!(await availablePort(hostname, port))) {
+    port += 1;
+  }
+
+  const backendRoot = resolveProjectPath({}, options?.rootDirectory ?? "./");
+
+  let startCommand;
+  if (options?.startCommand) {
+    startCommand = options?.startCommand;
+    // Angular and nextjs CLIs allow for specifying port options but the emulator is setting and
+    // specifying specific ports rather than use framework defaults or w/e the user has set, so we
+    // need to reject such custom commands.
+    // NOTE: this is not robust, a command could be a wrapper around another command and we cannot
+    // detect --port there.
+    if (startCommand.includes("--port") || startCommand.includes(" -p ")) {
+      throw new FirebaseError(
+        "Specifying a port in the start command is not supported by the apphosting emulator",
+      );
+    }
+    // Angular does not respect the NodeJS.ProcessEnv.PORT set below. Port needs to be
+    // set directly in the CLI.
+    if (startCommand.includes("ng serve")) {
+      startCommand += ` --port ${port}`;
+    }
+    logger.logLabeled(
+      "BULLET",
+      Emulators.APPHOSTING,
+      `running custom start command: '${startCommand}'`,
+    );
+  } else {
+    // TODO: port may be specified in an underlying command. But we will need to parse the package.json
+    // file to be sure.
+    startCommand = await detectPackageManagerStartCommand(backendRoot);
+    logger.logLabeled("BULLET", Emulators.APPHOSTING, `starting app with: '${startCommand}'`);
+  }
 
-  const backendRoot = resolveProjectPath({}, backendRelativeDir);
   const apphostingLocalConfig = await getLocalAppHostingConfiguration(backendRoot);
   const resolveEnv = Object.entries(apphostingLocalConfig.env).map(async ([key, value]) => [
     key,
-    value.value ? value.value : await loadSecret(projectId, value.secret!),
+    value.value ? value.value : await loadSecret(options?.projectId, value.secret!),
   ]);
 
   const environmentVariablesToInject: NodeJS.ProcessEnv = {
@@ -135,8 +145,8 @@ async function serve(
     ...Object.fromEntries(await Promise.all(resolveEnv)),
     FIREBASE_APP_HOSTING: "1",
     X_GOOGLE_TARGET_PLATFORM: "fah",
-    GCLOUD_PROJECT: projectId,
-    PROJECT_ID: projectId,
+    GCLOUD_PROJECT: options?.projectId,
+    PROJECT_ID: options?.projectId,
     PORT: port.toString(),
   };
 
@@ -145,7 +155,7 @@ async function serve(
     // TODO(jamesdaniels) look into pnpm support for autoinit
     logLabeledWarning("apphosting", `Firebase JS SDK autoinit does not currently support PNPM.`);
   } else {
-    const webappConfig = await getBackendAppConfig(projectId, backendId);
+    const webappConfig = await getBackendAppConfig(options?.projectId, options?.backendId);
     if (webappConfig) {
       environmentVariablesToInject["FIREBASE_WEBAPP_CONFIG"] ||= JSON.stringify(webappConfig);
       environmentVariablesToInject["FIREBASE_CONFIG"] ||= JSON.stringify({
@@ -157,31 +167,14 @@ async function serve(
     await tripFirebasePostinstall(backendRoot, environmentVariablesToInject);
   }
 
-  if (startCommand) {
-    logger.logLabeled(
-      "BULLET",
-      Emulators.APPHOSTING,
-      `running custom start command: '${startCommand}'`,
-    );
-
-    // NOTE: Development server should not block main emulator process.
-    spawnWithCommandString(startCommand, backendRoot, environmentVariablesToInject)
-      .catch((err) => {
-        logger.logLabeled("ERROR", Emulators.APPHOSTING, `failed to start Dev Server: ${err}`);
-      })
-      .then(() => logger.logLabeled("BULLET", Emulators.APPHOSTING, `Dev Server stopped`));
-    return;
-  }
-
-  const detectedStartCommand = await detectStartCommand(backendRoot);
-  logger.logLabeled("BULLET", Emulators.APPHOSTING, `starting app with: '${detectedStartCommand}'`);
-
   // NOTE: Development server should not block main emulator process.
-  spawnWithCommandString(detectedStartCommand, backendRoot, environmentVariablesToInject)
+  spawnWithCommandString(startCommand, backendRoot, environmentVariablesToInject)
     .catch((err) => {
       logger.logLabeled("ERROR", Emulators.APPHOSTING, `failed to start Dev Server: ${err}`);
     })
     .then(() => logger.logLabeled("BULLET", Emulators.APPHOSTING, `Dev Server stopped`));
+
+  return { hostname, port };
 }
 
 function availablePort(host: string, port: number): Promise<boolean> {
diff --git a/src/emulator/initEmulators.ts b/src/emulator/initEmulators.ts
@@ -3,7 +3,7 @@
 import * as clc from "colorette";
 import { join } from "path";
 import { input, confirm } from "../prompt";
-import { detectStartCommand } from "./apphosting/developmentServer";
+import { detectPackageManagerStartCommand } from "./apphosting/developmentServer";
 import { EmulatorLogger } from "./emulatorLogger";
 import { Emulators } from "./types";
 import { Env, maybeGenerateEmulatorYaml } from "../apphosting/config";
@@ -29,7 +29,7 @@ export const AdditionalInitFns: AdditionalInitFnsType = {
 
     const backendRoot = join(cwd, backendRelativeDir);
     try {
-      const startCommand = await detectStartCommand(backendRoot);
+      const startCommand = await detectPackageManagerStartCommand(backendRoot);
       additionalConfigs.set("startCommand", startCommand);
     } catch (e) {
       logger.log(
