Revamp local dev to support websocket server for UI #1479

camden11 · 2025-05-05T21:30:40Z

Description and Context

This revamps the local dev flow for unified apps to make it more flexible and modular. Since I've walked everyone through (and left inline comments to explain) I won't go into too much detail here, but the primary purpose of this PR is to separate the many responsibilities of the old LocalDevManagerV2 into discrete classes.

While this makes a lot of code changes, the actual UX of running hs project dev should not change. Appreciate any help with testing to confirm that's true!

TODO

This sets things up to work with the Local Dev Websocket Server, which will be implemented in a separate PR.
I also plan on updating LocalDevState to be immutable but going to do that in a separate PR as well (this is safe for now since the dev servers don't interact directly with LocalDevState

Who to Notify

@brandenrodgers @joe-yeager @kemmerle

camden11 · 2025-05-06T16:19:36Z

commands/project/dev/unifiedFlow.ts

+    }
+  });
+
+  handleExit(({ isSIGHUP }) => localDevProcess.stop(!isSIGHUP));


LocalDevProcess represents the current local dev session (similar to the old LocalDevManager). Everything that interacts with the LocalDevProcess now lives outside of it and uses public methods to make necessary changes to the process.

This includes

Watcher

Keypress listener

In the future, the websocket server

I'd add a note with that explanation directly into the code.

camden11 · 2025-05-06T16:21:17Z

lib/projects/localDev/AppDevModeInterface.ts

@@ -0,0 +1,193 @@
+import { fetchAppInstallationData } from '@hubspot/local-dev-lib/api/localDevAuth';


This is a wrapper around the UIEDevModeInterface and includes all app-specific logic that previously lived in LocalDevManager. This lets us keep LocalDevProcess component agnostic

camden11 · 2025-05-06T16:24:47Z

lib/projects/localDev/DevServerManagerV2.ts

+  localDevState: LocalDevState;
+  logger: LocalDevLogger;
+};
+


DevServerManager is no longer a singleton. It now has access to the LocalDevState from the currently running process, and in the future, can pass that directly to dev servers

camden11 · 2025-05-06T16:26:58Z

lib/projects/localDev/DevServerManagerV2.ts

    await Promise.all(this.devServers.map(devServer => callback(devServer)));
  }

-  async setup({


These lifecycle methods don't need to accept arguments anymore, since they use the LocalDevState

camden11 · 2025-05-06T16:30:37Z

lib/projects/localDev/LocalDevLogger.ts

+class LocalDevLogger {
+  private state: LocalDevState;
+  private mostRecentUploadWarning: string | null;
+  private uploadWarnings: string[];


This class handles all logging related to LocalDevProcess. It exists primarily to keep the more complex logging logic out of LocalDevProcess but can also be passed to dev servers to give them control over logs related to the process (see below)

camden11 · 2025-05-06T16:32:07Z

lib/projects/localDev/LocalDevLogger.ts

+    }
+  }
+
+  addUploadWarning(warning: string): void {


This allows dev servers to add specific upload warnings that the logger will then log whenever the upload warning appears. Currently used when apps in a project have production installs, but in the future, other dev servers could also add messages here. For now, it lets us keep the LocalDevLogger component agnostic

camden11 · 2025-05-06T16:32:51Z

lib/projects/localDev/LocalDevManagerV2.ts

@@ -1,557 +0,0 @@
-import path from 'path';


Broken up into LocalDevProcess, LocalDevLogger, LocalDevWatcher, and AppDevModeInterface

camden11 · 2025-05-06T16:35:04Z

lib/projects/localDev/LocalDevProcess.ts

+  env: Environment;
+};
+
+class LocalDevProcess {


This class has two primary purposes:

Store LocalDevState and pass it to other objects that need access to it (namely the dev servers and logger)

Expose methods that allow interaction with the local dev process by external sources

camden11 · 2025-05-06T16:35:42Z

lib/projects/localDev/LocalDevProcess.ts

+    initialProjectNodes,
+    env,
+  }: LocalDevProcessConstructorOptions) {
+    this.state = {


It could make sense for LocalDevState to be its own class in the future, especially if dev servers will be mutating it. For now, I think this object will suffice

I think it might be a good idea to make the object immutable so that the other dev servers can't change it. We would want to be the source of truth for this information and probably wouldn't want it to change.

camden11 · 2025-05-06T16:37:18Z

lib/projects/localDev/LocalDevProcess.ts

+      intermediateRepresentation.intermediateNodesIndexedByUid;
+  }
+}
+


In later PRs, will add more methods that allow the LocalDevUIWebsocketServer to interact with the LocalDevProcess (for example, an upload method)

camden11 · 2025-05-06T16:37:55Z

lib/projects/localDev/LocalDevUIWebsocketServer.ts

+
+const LOG_PREFIX = '[LocalDevUIWebsocketServer] ';
+
+class LocalDevUIWebsocketServer {


This is still WIP - started working on it before I realized that the rest of the work in this PR was necessary. But figured it made sense to keep it in here and add to it in following PRs

camden11 · 2025-05-06T16:38:39Z

lib/projects/localDev/LocalDevWatcher.ts

+  unlinkDir: 'unlinkDir',
+};
+
+class LocalDevWatcher {


This is a good example of how external sources can interact with the LocalDevProcess

joe-yeager · 2025-05-06T16:49:44Z

lib/projects/localDev/LocalDevUIWebsocketServer.ts

+    const portData = await requestPorts([{ instanceId: SERVER_INSTANCE_ID }]);
+    const port = portData[SERVER_INSTANCE_ID];
+
+    this._server = new WebSocketServer({ port });


If we want, we can attach this WebSocketServer to the express server that we already use for the port manager. This would limit the number of ports we use on the users machine and allow us to have a reliable fixed port.

https://github.com/websockets/ws?tab=readme-ov-file#external-https-server

kemmerle · 2025-05-06T19:41:09Z

lib/constants.ts

  UNIFIED_APPS: 'Developers:UnifiedApps:PrivateBeta',
 } as const;
+
+export const LOCAL_DEV_UI_WEBSOCKET_MESSAGE_TYPES = {


Remember to remove these constants, as well.

kemmerle · 2025-05-06T19:54:38Z

lib/projects/localDev/LocalDevLogger.ts

+
+    // Avoid logging the warning to the console if it is currently the most
+    // recently logged warning. We do not want to spam the console with the same message.
+    if (warning !== this.mostRecentUploadWarning) {


We repeat this condition twice--wrap it in a function to DRY the code up a bit?

kemmerle · 2025-05-06T20:00:15Z

lib/projects/localDev/LocalDevLogger.ts

+    }
+  }
+
+  fileChangeError(e: unknown): void {


You could replace the next four functions with a single function like this:

private handleError( e: unknown, translationFn: (message: string) => string ): void { if (this.state.debug) { logger.error(e); } uiLogger.error(translationFn(e instanceof Error ? e.message : '')); }

kemmerle

I only had minor comments. Overall, I think this is a major improvement for local dev--the modular code is much easier to understand now. Ping me when you're finished making changes and I can give it a final

One other little comment: You might want to rename the PR given that the websocket work has been removed.

joe-yeager · 2025-05-06T20:28:11Z

lib/projects/localDev/LocalDevLogger.ts

+
+    // Avoid logging the warning to the console if it is currently the most
+    // recently logged warning. We do not want to spam the console with the same message.
+    if (warning !== this.mostRecentUploadWarning) {


Should we empty the this.uploadWarnings array when we log? Otherwise it will keep logging the same errors every time a new error is added and this method is called

Yeah good question. It's set up so it won't log exactly the same error twice but if there's a second one added it'll go off.... idk, I could see going either way with this, it could be annoying but it could also help prevent people from missing important errors.

If the hypothetical future dev serves work the way the apps dev server does, these messages will be added on startup and only logged once when files are changed, so it wouldn't be a problem then. Maybe makes sense to cross that bridge when we get there

joe-yeager · 2025-05-06T20:29:44Z

lib/projects/localDev/LocalDevLogger.ts

+  }
+
+  addUploadWarning(warning: string): void {
+    this.uploadWarnings.push(warning);


Maybe this can be a set so we can de-dupe the warnings

joe-yeager · 2025-05-06T20:32:15Z

lib/projects/localDev/LocalDevLogger.ts

+    langFunction: (message: string) => string
+  ): void {
+    if (this.state.debug) {
+      logger.error(e);


Should this be logger.debug?

Previously, LocalDevManagerV2 was using this pattern with using logger.error, I assume to make errors more visible when in debug mode. I decided to stick with that pattern

joe-yeager · 2025-05-06T20:34:13Z

lib/projects/localDev/LocalDevLogger.ts

+
+    uiLogger.log('');
+    uiLogger.log(
+      chalk.hex(UI_COLORS.SORBET)(


Nit: Could we move the color logic in the lang code?

joe-yeager · 2025-05-06T20:34:40Z

lib/projects/localDev/LocalDevLogger.ts

+      uiLink(
+        lib.LocalDevManager.learnMoreLocalDevServer,
+        'https://developers.hubspot.com/docs/platform/project-cli-commands#start-a-local-development-server'
+      )


Nit: We could move the uiLink in the lang file

joe-yeager · 2025-05-06T20:35:08Z

lib/projects/localDev/LocalDevLogger.ts

+      uiLink(
+        lib.LocalDevManager.viewProjectLink,
+        getProjectDetailUrl(
+          this.state.projectConfig.name,
+          this.state.targetProjectAccountId
+        ) || ''


Nit: We could move the uiLink into the lang file

brandenrodgers · 2025-05-12T17:43:47Z

lang/en.ts

    noComponents: 'There are no components in this project.',
    betaMessage: 'HubSpot projects local development',
-    learnMoreLocalDevServer: 'Learn more about the projects local dev server',
+    learnMoreLocalDevServer: uiLink(


Are these translations in the en.lyaml file too? Would it make sense to remove them as a part of this, or should we wait and do that later once everything is ported?

I've been operating under the assumption that we'd just delete the entire file at the end, so haven't been removing things from it. I don't think there's really any need to, especially since its easy to look up what we haven't ported to the new system by searching for i18n(

brandenrodgers

I tested out a handful of different edge cases and this seems to work the same as the existing setup 🎉

camden11 added 7 commits April 28, 2025 17:20

Local dev UI WIP

9096dfe

Merge branch 'main' into local-dev-ui-server-poc

50d6ee5

Local dev UI server POC

a9d2bbe

Revamp local dev WIP

415e1f3

Add AppDevModeInterface

998b57a

Functional local dev flow

6a6d2ff

Generate new IR on file change

6638562

camden11 commented May 6, 2025

View reviewed changes

make methods private

1336d0a

joe-yeager reviewed May 6, 2025

View reviewed changes

camden11 added 3 commits May 6, 2025 15:28

Copy fix

3c3c6b3

Rm websocket server

3aa1e68

remove ws

e813163

camden11 changed the title ~~WIP: Revamp local dev to support websocket server for UI~~ Revamp local dev to support websocket server for UI May 6, 2025

kemmerle reviewed May 6, 2025

View reviewed changes

camden11 marked this pull request as ready for review May 6, 2025 19:41

camden11 requested a review from brandenrodgers as a code owner May 6, 2025 19:41

remove other websocket things

7eeb2b4

camden11 requested a review from joe-yeager May 6, 2025 19:44

camden11 requested a review from kemmerle May 6, 2025 19:44

kemmerle reviewed May 6, 2025

View reviewed changes

Clean up local dev logger error handlers

01fe00f

joe-yeager reviewed May 6, 2025

View reviewed changes

camden11 added 3 commits May 12, 2025 11:27

Merge branch 'main' into local-dev-ui-server-poc

392ffd8

Clean up

2963cde

fix type errors

610f4f0

camden11 requested review from joe-yeager and kemmerle May 12, 2025 15:52

brandenrodgers reviewed May 12, 2025

View reviewed changes

brandenrodgers approved these changes May 12, 2025

View reviewed changes

camden11 merged commit 022a8de into main May 12, 2025
1 check passed

camden11 deleted the local-dev-ui-server-poc branch May 12, 2025 18:27

		@@ -0,0 +1,193 @@
		import { fetchAppInstallationData } from '@hubspot/local-dev-lib/api/localDevAuth';


		const LOG_PREFIX = '[LocalDevUIWebsocketServer] ';

		class LocalDevUIWebsocketServer {

Revamp local dev to support websocket server for UI #1479

Revamp local dev to support websocket server for UI #1479

Uh oh!

Conversation

camden11 commented May 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description and Context

TODO

Who to Notify

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kemmerle left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

camden11 May 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

brandenrodgers left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

camden11 commented May 5, 2025 •

edited

Loading

kemmerle left a comment •

edited

Loading

camden11 May 6, 2025 •

edited

Loading