@hubspot/ui-extensions-dev-server 0.10.1 → 1.0.0

package/README.md

@@ -1,7 +1,26 @@
-# UI Extensions – Dev Server
+# UI Extensions Dev Server
 
-Development server library to run your HubSpot UI Extensions.
+This package is a development server library for HubSpot UI Extensions. It provides a Vite and Express-powered server for local development of extensions, which is run via the HubSpot CLI. There is also a `remoteBuild` function, used by Artifactor to generate production builds of extensions.
 
-## Overview
-This package contains the library functions for running HubSpot UI extensions locally, as well as running a production build for debugging purposes.
+## Installation
 
+You can install the package directly to run the CLI command to execute the production build locally:
+
+```bash
+npm install @hubspot/ui-extensions-dev-server
+```
+
+However, most people will use this package indirectly via the [HubSpot cli](https://git.hubteam.com/HubSpot/hubspot-cli-private):
+
+```bash
+hs project dev
+```
+
+## Key Documentation
+
+- [Architectural Overview](./docs/uie-dev-server-overview.md)
+- [How to Contribute](./CONTRIBUTING.md)
+
+## Ownership and Issue Management
+
+We centerally manage issues in our [primary `ui-extensibility` repo](https://git.hubteam.com/hubspot/ui-extensibility/)

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { remoteBuild, buildSingleExtension } from './lib/build';
-import DevModeInterface, { DevModeInterfaceNonSingleton } from './lib/DevModeInterface';
-import DevModeUnifiedInterface, { DevModeUnifiedInterfaceNonSingleton } from './lib/DevModeUnifiedInterface';
+import { remoteBuild, buildSingleExtension } from './lib/build.ts';
+import DevModeInterface, { DevModeInterfaceNonSingleton } from './lib/DevModeInterface.ts';
+import DevModeUnifiedInterface, { DevModeUnifiedInterfaceNonSingleton } from './lib/DevModeUnifiedInterface.ts';
 export { remoteBuild, buildSingleExtension, DevModeInterface, DevModeInterfaceNonSingleton, DevModeUnifiedInterface, DevModeUnifiedInterfaceNonSingleton, };

package/dist/index.js

@@ -1,45 +1,4 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.DevModeUnifiedInterfaceNonSingleton = exports.DevModeUnifiedInterface = exports.DevModeInterfaceNonSingleton = exports.DevModeInterface = exports.buildSingleExtension = exports.remoteBuild = void 0;
-const build_1 = require("./lib/build");
-Object.defineProperty(exports, "remoteBuild", { enumerable: true, get: function () { return build_1.remoteBuild; } });
-Object.defineProperty(exports, "buildSingleExtension", { enumerable: true, get: function () { return build_1.buildSingleExtension; } });
-const DevModeInterface_1 = __importStar(require("./lib/DevModeInterface"));
-exports.DevModeInterface = DevModeInterface_1.default;
-Object.defineProperty(exports, "DevModeInterfaceNonSingleton", { enumerable: true, get: function () { return DevModeInterface_1.DevModeInterfaceNonSingleton; } });
-const DevModeUnifiedInterface_1 = __importStar(require("./lib/DevModeUnifiedInterface"));
-exports.DevModeUnifiedInterface = DevModeUnifiedInterface_1.default;
-Object.defineProperty(exports, "DevModeUnifiedInterfaceNonSingleton", { enumerable: true, get: function () { return DevModeUnifiedInterface_1.DevModeUnifiedInterfaceNonSingleton; } });
+import { remoteBuild, buildSingleExtension } from "./lib/build.js";
+import DevModeInterface, { DevModeInterfaceNonSingleton, } from "./lib/DevModeInterface.js";
+import DevModeUnifiedInterface, { DevModeUnifiedInterfaceNonSingleton, } from "./lib/DevModeUnifiedInterface.js";
+export { remoteBuild, buildSingleExtension, DevModeInterface, DevModeInterfaceNonSingleton, DevModeUnifiedInterface, DevModeUnifiedInterfaceNonSingleton, };

package/dist/lib/DevModeInterface.d.ts

@@ -1,5 +1,5 @@
-import { ProjectComponentMap, AppExtensionMapping, DevModeSetupArguments } from './types';
-import { DevModeParentInterface } from './DevModeParentInterface';
+import { ProjectComponentMap, AppExtensionMapping, DevModeSetupArguments } from './types.ts';
+import { DevModeParentInterface } from './DevModeParentInterface.ts';
 declare class DevModeInterface extends DevModeParentInterface {
     _generateAppExtensionMappings(components: ProjectComponentMap): AppExtensionMapping[];
     setup(args: DevModeSetupArguments): Promise<void>;

package/dist/lib/DevModeInterface.js

@@ -1,37 +1,23 @@
-"use strict";
-/* hs-eslint ignored failing-rules */
-/* eslint-disable hubspot-dev/no-unsupported-ts-syntax */
-var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.DevModeInterfaceNonSingleton = void 0;
-const constants_1 = require("./constants");
-const config_1 = require("./config");
-const DevModeParentInterface_1 = require("./DevModeParentInterface");
-class DevModeInterface extends DevModeParentInterface_1.DevModeParentInterface {
+import { SUPPORTED_APP_TYPES, PUBLIC_APP } from "./constants.js";
+import { loadExtensionConfig } from "./config.js";
+import { DevModeParentInterface } from "./DevModeParentInterface.js";
+class DevModeInterface extends DevModeParentInterface {
     _generateAppExtensionMappings(components) {
         // Loop over all of the app configs that are passed in
         const allComponentNames = Object.keys(components);
         return allComponentNames.reduce((appExtensionMappings, componentName) => {
             const component = components[componentName];
-            if (!constants_1.SUPPORTED_APP_TYPES.includes(component.type)) {
+            if (!SUPPORTED_APP_TYPES.includes(component.type)) {
                 return appExtensionMappings; // It's not a modern app, skip it
             }
             // Load all of the extension configs for a particular app.json file
-            const extensionsConfigForApp = (0, config_1.loadExtensionConfig)(component.config, component.path);
+            const extensionsConfigForApp = loadExtensionConfig(component.config, component.path);
             const extensionConfigKeys = Object.keys(extensionsConfigForApp);
             // Loop over the loaded extension configs and generate the list of choices to use to prompt the user for input
             extensionConfigKeys.forEach((extensionKey) => {
                 const extensionConfig = extensionsConfigForApp[extensionKey];
                 if (extensionConfig.appConfig) {
-                    extensionConfig.appConfig.isPublicApp = component.type === constants_1.PUBLIC_APP;
+                    extensionConfig.appConfig.isPublicApp = component.type === PUBLIC_APP;
                 }
                 appExtensionMappings.push({
                     name: `${componentName}/${extensionConfig.data.title}`,
@@ -41,12 +27,10 @@ class DevModeInterface extends DevModeParentInterface_1.DevModeParentInterface {
             return appExtensionMappings;
         }, []);
     }
-    setup(args) {
-        return __awaiter(this, void 0, void 0, function* () {
-            args.choices = this._generateAppExtensionMappings(args.components);
-            yield this.parentSetup(args);
-        });
+    async setup(args) {
+        args.choices = this._generateAppExtensionMappings(args.components);
+        await this.parentSetup(args);
     }
 }
-exports.DevModeInterfaceNonSingleton = DevModeInterface;
-exports.default = new DevModeInterface();
+export { DevModeInterface as DevModeInterfaceNonSingleton };
+export default new DevModeInterface();

package/dist/lib/DevModeParentInterface.d.ts

@@ -1,5 +1,5 @@
-import { PlatformVersion, ProjectConfig, Logger, ExtensionOutputConfig, ProjectComponentMap, AppExtensionMapping, DevModeStartArguments, DevModeSetupArguments, UnifiedProjectComponentMap, DevModeBaseSetupArguments } from './types';
-import { DevServerState } from './DevServerState';
+import { PlatformVersion, ProjectConfig, Logger, ExtensionOutputConfig, ProjectComponentMap, AppExtensionMapping, DevModeStartArguments, DevModeSetupArguments, UnifiedProjectComponentMap, DevModeBaseSetupArguments } from './types.ts';
+import { DevServerState } from './DevServerState.ts';
 export declare abstract class DevModeParentInterface {
     configs?: ExtensionOutputConfig[];
     devServerState?: DevServerState;

package/dist/lib/DevModeParentInterface.js

@@ -1,25 +1,10 @@
-"use strict";
-var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-};
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.DevModeParentInterface = void 0;
-const constants_1 = require("./constants");
-const dev_1 = require("./dev");
-const config_1 = require("./config");
-const constants_2 = require("./constants");
-const utils_1 = require("./utils");
-const DevServerState_1 = require("./DevServerState");
-const inquirer_1 = __importDefault(require("inquirer"));
+import { PLATFORM_VERSION } from "./constants.js";
+import { startDevMode } from "./dev.js";
+import { loadLocalConfig } from "./config.js";
+import { throwUnhandledPlatformVersionError } from "./utils.js";
+import { DevServerState } from "./DevServerState.js";
+import inquirer from 'inquirer';
+import { EXPRESS_DEFAULT_PORT, EXPRESS_SERVER_ID } from "./constants.js";
 const defaultLogger = {
     info: (...args) => {
         console.log(...args);
@@ -34,27 +19,32 @@ const defaultLogger = {
         console.error(...args);
     },
 };
-class DevModeParentInterface {
-    constructor() {
-        this.logger = defaultLogger;
-    }
+export class DevModeParentInterface {
+    configs;
+    devServerState;
+    onUploadRequired;
+    logger = defaultLogger;
+    urls;
+    isConfigured;
+    isRunning;
+    shutdown;
     _getPlatformVersion(projectConfig) {
-        const { platformVersion } = projectConfig !== null && projectConfig !== void 0 ? projectConfig : {};
+        const { platformVersion } = projectConfig ?? {};
         if (!platformVersion) {
-            return constants_1.PLATFORM_VERSION.V20231;
+            return PLATFORM_VERSION.V20231;
         }
         switch (platformVersion) {
-            case constants_1.PLATFORM_VERSION.V20231:
-                return constants_1.PLATFORM_VERSION.V20231;
-            case constants_1.PLATFORM_VERSION.V20232:
-                return constants_1.PLATFORM_VERSION.V20232;
-            case constants_1.PLATFORM_VERSION.V20251:
-                return constants_1.PLATFORM_VERSION.V20251;
-            case constants_1.PLATFORM_VERSION.V20252:
-            case constants_1.PLATFORM_VERSION.UNSTABLE:
-                return constants_1.PLATFORM_VERSION.V20252;
+            case PLATFORM_VERSION.V20231:
+                return PLATFORM_VERSION.V20231;
+            case PLATFORM_VERSION.V20232:
+                return PLATFORM_VERSION.V20232;
+            case PLATFORM_VERSION.V20251:
+                return PLATFORM_VERSION.V20251;
+            case PLATFORM_VERSION.V20252:
+            case PLATFORM_VERSION.UNSTABLE:
+                return PLATFORM_VERSION.V20252;
             default:
-                return (0, utils_1.throwUnhandledPlatformVersionError)(platformVersion);
+                return throwUnhandledPlatformVersionError(platformVersion);
         }
     }
     _reset() {
@@ -67,131 +57,125 @@ class DevModeParentInterface {
         this.isConfigured = false;
         this.isRunning = false;
     }
-    parentSetup(_a) {
-        return __awaiter(this, arguments, void 0, function* ({ onUploadRequired, logger, urls, setActiveApp, choices = [], }) {
-            var _b, _c, _d;
-            if (this.isConfigured) {
-                logger.debug('Dev server has already been configured, skipping');
-                return;
-            }
-            this.logger = logger;
-            this.onUploadRequired = onUploadRequired;
-            this.urls = urls;
-            if (choices.length === 0) {
-                throw new Error('No extensions to run');
-            }
-            else if (choices.length === 1) {
-                this.configs = [choices[0].value];
-            }
-            else {
-                const promptModule = inquirer_1.default.createPromptModule();
-                const answers = yield promptModule({
-                    type: 'checkbox',
-                    name: 'extensions',
-                    message: 'Which extension(s) would you like to run?',
-                    validate: (input) => {
-                        if (!input || input.length === 0) {
-                            return 'Select at least one extension to run';
-                        }
-                        const appNames = new Set(input.map((choice) => choice.data.appName));
-                        if (appNames.size > 1) {
-                            return 'Running multiple extensions is only supported for a single application';
-                        }
-                        return true;
-                    },
-                    choices,
-                });
-                this.configs = answers.extensions;
-            }
-            this.isConfigured = true;
-            if (typeof setActiveApp === 'function') {
-                yield setActiveApp((_d = (_c = (_b = this.configs) === null || _b === void 0 ? void 0 : _b[0]) === null || _c === void 0 ? void 0 : _c.appConfig) === null || _d === void 0 ? void 0 : _d.uid);
-            }
-        });
-    }
-    start(_a) {
-        return __awaiter(this, arguments, void 0, function* ({ requestPorts, accountId, projectConfig, }) {
-            var _b, _c, _d, _e;
-            this.logger.debug('Start function was invoked', {
-                accountId,
-                projectConfig,
-            });
-            if (this.isRunning) {
-                this.logger.debug('Dev server is already running, not starting again');
-                return;
-            }
-            let expressPort = constants_2.EXPRESS_DEFAULT_PORT;
-            let webSocketPort = constants_2.WEBSOCKET_DEFAULT_PORT;
-            if (requestPorts) {
-                try {
-                    const portData = yield requestPorts([
-                        { instanceId: constants_2.EXPRESS_SERVER_ID, port: constants_2.EXPRESS_DEFAULT_PORT },
-                        { instanceId: constants_2.VITE_DEV_SERVER_ID, port: constants_2.WEBSOCKET_DEFAULT_PORT },
-                    ]);
-                    expressPort = portData[constants_2.EXPRESS_SERVER_ID];
-                    webSocketPort = portData[constants_2.VITE_DEV_SERVER_ID];
-                }
-                catch (e) {
-                    if ((e === null || e === void 0 ? void 0 : e.status) === 409) {
-                        throw new Error('Another instance is already running. To proceed, please stop the existing server and try again.');
+    async parentSetup({ onUploadRequired, logger, urls, setActiveApp, choices = [], }) {
+        if (this.isConfigured) {
+            logger.debug('Dev server has already been configured, skipping');
+            return;
+        }
+        this.logger = logger;
+        this.onUploadRequired = onUploadRequired;
+        this.urls = urls;
+        if (choices.length === 0) {
+            throw new Error('No extensions to run');
+        }
+        else if (choices.length === 1) {
+            this.configs = [choices[0].value];
+        }
+        else {
+            const promptModule = inquirer.createPromptModule();
+            const answers = await promptModule({
+                type: 'checkbox',
+                name: 'extensions',
+                message: 'Which extension(s) would you like to run?',
+                validate: (selectedChoices) => {
+                    if (!selectedChoices || selectedChoices.length === 0) {
+                        return 'Select at least one extension to run';
                     }
-                    this.logger.debug('Call to port manager failed, using default ports');
-                }
-            }
-            const { proxy: localDevUrlMapping } = (0, config_1.loadLocalConfig)(((_c = (_b = this.configs) === null || _b === void 0 ? void 0 : _b[0]) === null || _c === void 0 ? void 0 : _c.path) || '', this.logger) || {};
-            try {
-                this.devServerState = new DevServerState_1.DevServerState({
-                    localDevUrlMapping,
-                    extensionConfigs: this.configs,
-                    accountId,
-                    platformVersion: this._getPlatformVersion(projectConfig),
-                    expressPort,
-                    webSocketPort,
-                    logger: this.logger,
-                    urls: this.urls,
-                    appConfig: (_e = (_d = this.configs) === null || _d === void 0 ? void 0 : _d[0]) === null || _e === void 0 ? void 0 : _e.appConfig,
-                });
-            }
-            catch (e) {
-                this.logger.debug('Error setting up DevServerState', e);
-                throw e;
-            }
+                    const configs = selectedChoices
+                        .map((choice) => choice.value)
+                        .filter((value) => {
+                        return (typeof value === 'object' && value !== null && 'data' in value);
+                    });
+                    if (configs.length !== selectedChoices.length) {
+                        return 'Invalid extension configuration';
+                    }
+                    const appNames = new Set(configs.map((config) => config.data.appName));
+                    if (appNames.size > 1) {
+                        return 'Running multiple extensions is only supported for a single application';
+                    }
+                    return true;
+                },
+                choices,
+            });
+            this.configs = answers.extensions;
+        }
+        this.isConfigured = true;
+        if (typeof setActiveApp === 'function') {
+            await setActiveApp(this.configs?.[0]?.appConfig?.uid);
+        }
+    }
+    async start({ requestPorts, accountId, projectConfig, }) {
+        this.logger.debug('Start function was invoked', {
+            accountId,
+            projectConfig,
+        });
+        if (this.isRunning) {
+            this.logger.debug('Dev server is already running, not starting again');
+            return;
+        }
+        let expressPort = EXPRESS_DEFAULT_PORT;
+        if (requestPorts) {
             try {
-                this.shutdown = yield (0, dev_1.startDevMode)(this.devServerState);
+                const portData = await requestPorts([
+                    { instanceId: EXPRESS_SERVER_ID, port: EXPRESS_DEFAULT_PORT },
+                ]);
+                expressPort = portData[EXPRESS_SERVER_ID];
             }
             catch (e) {
-                this.logger.debug('Error starting dev mode', e);
-                throw e;
+                if (e?.status === 409) {
+                    throw new Error('Another instance is already running. To proceed, please stop the existing server and try again.');
+                }
+                this.logger.debug('Call to port manager failed, using default ports');
             }
-            const { extensionsMetadata } = this.devServerState;
-            extensionsMetadata.forEach((metadata) => {
-                const { config: { data: { title, appName }, }, } = metadata;
-                this.logger.info(`Running extension '${title}' from app '${appName}'`);
+        }
+        const { proxy: localDevUrlMapping } = loadLocalConfig(this.configs?.[0]?.path || '', this.logger) || {};
+        try {
+            this.devServerState = new DevServerState({
+                localDevUrlMapping,
+                extensionConfigs: this.configs,
+                accountId,
+                platformVersion: this._getPlatformVersion(projectConfig),
+                expressPort,
+                logger: this.logger,
+                urls: this.urls,
+                appConfig: this.configs?.[0]?.appConfig,
             });
-            this.isRunning = true;
+        }
+        catch (e) {
+            this.logger.debug('Error setting up DevServerState', e);
+            throw e;
+        }
+        try {
+            this.shutdown = await startDevMode(this.devServerState);
+        }
+        catch (e) {
+            this.logger.debug('Error starting dev mode', e);
+            throw e;
+        }
+        const { extensionsMetadata } = this.devServerState;
+        extensionsMetadata.forEach((metadata) => {
+            const { config: { data: { title, appName }, }, } = metadata;
+            this.logger.info(`Running extension '${title}' from app '${appName}'`);
         });
+        this.isRunning = true;
     }
-    // The contract is for this to be async, so eslint can chill
+    // The contract is for this to be async, with the __event param. Eslint doesn't like it.
     // eslint-disable-next-line require-await
-    fileChange(filePath, __event) {
-        return __awaiter(this, void 0, void 0, function* () {
-            if (!this.devServerState || !this.devServerState.extensionsMetadata) {
-                return;
-            }
-            const relevantConfigFileChanged = this.devServerState.extensionsMetadata.some((metadata) => metadata.config.extensionConfigPath === filePath);
-            if (relevantConfigFileChanged && this.onUploadRequired) {
-                this.onUploadRequired();
-            }
-        });
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    async fileChange(filePath, __event) {
+        if (!this.devServerState || !this.devServerState.extensionsMetadata) {
+            return;
+        }
+        const relevantConfigFileChanged = this.devServerState.extensionsMetadata.some((metadata) => metadata.config.extensionConfigPath === filePath);
+        if (relevantConfigFileChanged && this.onUploadRequired) {
+            this.onUploadRequired();
+        }
     }
-    cleanup() {
-        return __awaiter(this, void 0, void 0, function* () {
-            if (this.shutdown) {
-                yield this.shutdown();
-            }
-            // Since the DevModeInterface is a singleton, we need to wipe out the state when we shutdown
-            this._reset();
-        });
+    async cleanup() {
+        if (this.shutdown) {
+            await this.shutdown();
+        }
+        // Since the DevModeInterface is a singleton, we need to wipe out the state when we shutdown
+        this._reset();
     }
 }
-exports.DevModeParentInterface = DevModeParentInterface;

package/dist/lib/DevModeUnifiedInterface.d.ts

@@ -1,5 +1,5 @@
-import { AppExtensionMapping, UnifiedProjectComponentMap, UnifiedDevModeSetupArguments, ProfileVariables } from './types';
-import { DevModeParentInterface } from './DevModeParentInterface';
+import { AppExtensionMapping, UnifiedProjectComponentMap, UnifiedDevModeSetupArguments, ProfileVariables } from './types.ts';
+import { DevModeParentInterface } from './DevModeParentInterface.ts';
 declare class DevModeUnifiedInterface extends DevModeParentInterface {
     _generateAppExtensionMappings(components: UnifiedProjectComponentMap, profileData?: ProfileVariables): AppExtensionMapping[];
     setup(args: UnifiedDevModeSetupArguments): Promise<void>;