@hubspot/ui-extensions-dev-server 0.0.1-prealpha.0 → 0.0.1-prealpha.3

package/README.md

@@ -1,15 +1,27 @@
 # ui-extensions-dev-server
-This package contains the build script for bundling and serving remote extensions locally.  It checks for a config file named `extension-config.json` in directory the dev server command is ran from.  This config file is optional, and the below example contains what the default values are.
-
-Example config file:
-
-```json
-{
-  "version": "1.0",
-  "extensions": {
-    "example-app": {
-      "file": "App.tsx"
-    }
-  }
-}
-```
+
+## Overview
+This package contains the cli for running HubSpot UI extensions locally, as well as running a production build for debugging purposes.
+
+### Help
+If for any reason you need help with the `ui-extensions-dev-server` you can access the help menu in a few ways:
+
+- `hs-ui-extensions-dev-server`
+- `hs-ui-extensions-dev-server -h`
+- `hs-ui-extensions-dev-server --help`
+
+### Local Development
+Prompts you which of your extensions you would like to run in local dev mode. Once you have made your selection, it sets up a watcher on the entry point file for that project as well as any child files.  Any changes to those files will trigger a local build which will bundle your code and output the bundle in a `dist/` directory inside of your current working directory.  To initiate local dev mode in the browser, you just need to navigate to the CRM where your the deployed version of your card lives.  The browser will detect that you have the dev server running, and make the connection on your behalf.
+
+| Action | Command |
+| - | - |
+| Standard Local Dev | `hs-ui-extensions-dev-server dev` |
+| Bypass Prompt | `hs-ui-extensions-dev-server dev --extension MyEntryPointFile.jsx` <br /> `hs-ui-extensions-dev-server dev -e MyEntryPointFile.jsx`|
+
+### Production Build
+This should not be required in the standard development workflow. It is there to aid debugging the output of an extension.  This command will run a build similar to what we will run when these extensions are uploaded.  The output will be written into a `dist/` directory in the current working directory.
+
+| Action | Command |
+| - | - |
+| Build All Extensions | `hs-ui-extensions-dev-server build` |
+| Build a single extension | `hs-ui-extensions-dev-server build --extension MyEntryPointFile.jsx` <br /> `hs-ui-extensions-dev-server build -e MyEntryPointFile.jsx`|

package/build.js

@@ -1,32 +1,43 @@
-/* eslint-disable hubspot-dev/no-async-await */
-/*global module*/
-'use es6';
-
 const { build } = require('vite');
 const { ROLLUP_OPTIONS } = require('./constants');
 
-async function buildExtensions(config, outputDir) {
+async function buildAllExtensions(config, outputDir) {
   const extensionKeys = Object.keys(config);
-
   for (let i = 0; i < extensionKeys.length; ++i) {
     const { data } = config[extensionKeys[i]];
-    await build({
-      build: {
-        lib: {
-          entry: data?.module?.file,
-          name: data.output,
-          formats: ['iife'],
-          fileName: () => data.output,
-        },
-        rollupOptions: ROLLUP_OPTIONS,
-        outDir: outputDir,
-        emptyOutDir: i === 0,
-        minify: false,
-      },
-    });
+
+    await buildSingleExtension(
+      data?.module.file,
+      data?.output,
+      outputDir,
+      i === 0
+    );
   }
 }
 
+async function buildSingleExtension(
+  file,
+  outputFileName,
+  outputDir,
+  emptyOutDir = true
+) {
+  await build({
+    build: {
+      lib: {
+        entry: file,
+        name: outputFileName,
+        formats: ['iife'],
+        fileName: () => outputFileName,
+      },
+      rollupOptions: ROLLUP_OPTIONS,
+      outDir: outputDir,
+      emptyOutDir,
+      minify: false,
+    },
+  });
+}
+
 module.exports = {
-  buildExtensions,
+  buildAllExtensions,
+  buildSingleExtension,
 };

package/cli.js

@@ -0,0 +1,65 @@
+const logger = require('./logger');
+const commandLineArgs = require('command-line-args');
+const commandLineUsage = require('command-line-usage');
+
+function parseArgs() {
+  const mainDefinitions = [{ name: 'command', defaultOption: true }];
+  const mainOptions = commandLineArgs(mainDefinitions, {
+    stopAtFirstUnknown: true,
+  });
+  const argv = mainOptions._unknown || [];
+  const DEV_MODE = mainOptions.command === 'dev';
+  const BUILD_MODE = mainOptions.command === 'build';
+
+  const optionDefinitions = [
+    { name: 'port', alias: 'p', type: Number },
+    { name: 'extension', alias: 'e', type: String },
+    { name: 'help', alias: 'h', type: Boolean },
+  ];
+
+  const options = commandLineArgs(
+    optionDefinitions,
+    DEV_MODE || BUILD_MODE ? { argv } : {}
+  );
+
+  return { DEV_MODE, BUILD_MODE, ...options };
+}
+
+function showHelp(OUTPUT_DIR) {
+  const sections = [
+    {
+      header: 'HubSpot UI Extensions Local Dev Server',
+      content: `Used for local development of HubSpot extensions.  Built assets can be found in the ${OUTPUT_DIR} directory`,
+    },
+    {
+      header: 'Available Commands',
+      content: [
+        { name: 'dev', summary: 'starts the local development server' },
+        { name: 'build', summary: 'runs a build of your extensions' },
+      ],
+    },
+    {
+      header: 'Options',
+      optionList: [
+        {
+          name: 'extension',
+          typeLabel: '{underline file}',
+          description:
+            'The extension entrypoint file build or start local development for',
+        },
+        {
+          name: 'help',
+          description: 'Print this usage guide.',
+        },
+      ],
+    },
+  ];
+  const usage = commandLineUsage(sections);
+  logger.info(usage);
+  process.exit(0);
+}
+
+module.exports = {
+  parseArgs,
+  showHelp,
+};

package/config.js

@@ -1,17 +1,14 @@
-/* eslint-disable hubspot-dev/no-async-await */
-/*global process, module */
-'use es6';
 const prompts = require('prompts');
 const logger = require('./logger');
 const path = require('path');
 const { MAIN_APP_CONFIG, PROJECT_CONFIG } = require('./constants');
 const { getUrlSafeFileName } = require('./utils');
 
-async function getExtensionConfig(configuration) {
-  if (process.env.EXTENSION && configuration[process.env.EXTENSION]) {
-    const { data } = configuration[process.env.EXTENSION];
+async function getExtensionConfig(configuration, extension) {
+  if (extension && configuration[extension]) {
+    const { data } = configuration[extension];
     return {
-      key: process.env.EXTENSION,
+      key: extension,
       name: data.title,
       file: data?.module?.file,
       output: data?.output,
@@ -82,21 +79,28 @@ function loadConfig() {
   }
 
   const outputConfig = {};
-  try {
-    mainAppConfig.extensions.crm.cards.forEach(card => {
-      const extensionsRemoved = card.file.replace('extensions/', '');
-      const cardConfig = require(path.join(process.cwd(), extensionsRemoved));
+
+  mainAppConfig.extensions.crm.cards.forEach(card => {
+    const extensionsRemoved = card.file.replace('extensions/', '');
+    const cardPath = path.join(process.cwd(), extensionsRemoved);
+    try {
+      const cardConfig = require(cardPath);
       const extensionFileName = cardConfig.data?.module?.file;
       outputConfig[extensionFileName] = cardConfig;
       outputConfig[extensionFileName].data.output = getUrlSafeFileName(
         cardConfig.data?.module?.file
       );
       outputConfig[extensionFileName].data.appName = projectConfig.name;
-    });
-  } catch (e) {
-    logger.error(e.message);
-    process.exit(1);
-  }
+    } catch (e) {
+      let errorMessage = e?.message;
+      if (e?.code === 'MODULE_NOT_FOUND') {
+        errorMessage = `Unable to load "${cardPath}" file. \nPlease make sure you are running the command from the src/app/extensions directory and that your card JSON config exists within it.`;
+      }
+
+      logger.error(errorMessage);
+      process.exit(1);
+    }
+  });
 
   return outputConfig;
 }

package/constants.js

@@ -1,9 +1,7 @@
-/*global module */
-'use es6';
-
 const VITE_DEFAULT_PORT = 5173;
 const MAIN_APP_CONFIG = 'app.json';
 const PROJECT_CONFIG = 'hsproject.json';
+const OUTPUT_DIR = 'dist';
 
 const ROLLUP_OPTIONS = {
   // Deps to exclude from the bundle
@@ -23,4 +21,5 @@ module.exports = {
   ROLLUP_OPTIONS,
   MAIN_APP_CONFIG,
   PROJECT_CONFIG,
+  OUTPUT_DIR,
 };

package/dev.js

@@ -1,6 +1,3 @@
-/* eslint-disable hubspot-dev/no-async-await */
-/*global module, process*/
-'use es6';
 const express = require('express');
 const chokidar = require('chokidar');
 const { WebSocketServer } = require('ws');
@@ -12,8 +9,8 @@ const fs = require('fs');
 const path = require('path');
 const { ROLLUP_OPTIONS } = require('./constants');
 
-async function _devBuild(config, outputDir) {
-  const extensionConfig = await getExtensionConfig(config);
+async function _devBuild(config, outputDir, extension) {
+  const extensionConfig = await getExtensionConfig(config, extension);
   build({
     build: {
       watch: {
@@ -121,8 +118,8 @@ function _startDevServer(outputDir, port, extensionConfig) {
   });
 }
 
-async function startDevMode(config, outputDir, port) {
-  const extensionConfig = await _devBuild(config, outputDir);
+async function startDevMode(config, outputDir, port, extension) {
+  const extensionConfig = await _devBuild(config, outputDir, extension);
   _startDevServer(outputDir, port, extensionConfig);
 }
 

package/logger.js

@@ -1,6 +1,3 @@
-/*global module*/
-'use es6';
-
 const { cyan, red, yellow, magenta } = require('console-log-colors');
 
 function info(message) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hubspot/ui-extensions-dev-server",
-  "version": "0.0.1-prealpha.0",
+  "version": "0.0.1-prealpha.3",
   "description": "",
   "main": "index.js",
   "scripts": {
@@ -9,9 +9,26 @@
   "publishConfig": {
     "access": "public"
   },
+  "files": [
+    "README.md",
+    "build.js",
+    "cli.js",
+    "config.js",
+    "constants.js",
+    "dev.js",
+    "logger.js",
+    "remoteBuild.js",
+    "run.js",
+    "utils.js",
+    "tests/runTests.js",
+    "tests/testBuild.js",
+    "tests/testDevServer.js"
+  ],
   "license": "MIT",
   "dependencies": {
     "chokidar": "^3.5.3",
+    "command-line-args": "^5.2.1",
+    "command-line-usage": "^7.0.1",
     "console-log-colors": "^0.4.0",
     "express": "^4.18.2",
     "process": "^0.11.10",
@@ -20,7 +37,13 @@
     "ws": "^8.12.1"
   },
   "bin": {
-    "hs-ui-extensions-dev-server": "run.js"
+    "hs-ui-extensions-dev-server": "run.js",
+    "hs-ui-extensions-remote-build": "remoteBuild.js"
   },
-  "gitHead": "eb6b25c4f33ce83c1727cdddb7024267f0b63a70"
+  "eslintConfig": {
+    "env": {
+      "node": true
+    }
+  },
+  "gitHead": "74dbffa7fe6e4ad7d5029897801c11dc5d5edae1"
 }

package/remoteBuild.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+const { OUTPUT_DIR } = require('./constants');
+const { getUrlSafeFileName } = require('./utils');
+const { buildSingleExtension } = require('./build');
+
+// Regular expressions to match files ending in ts, js, tsx, and jsx
+const entryPointRegex = new RegExp(/.*\.(ts|js)[x]?$/);
+
+let extension = process.argv[process.argv.length - 1];
+
+if (!entryPointRegex.test(extension)) {
+  throw new Error(
+    'The last argument should be the filename you wish to build.  Supported file extensions are [ts, tsx, js, jsx]'
+  );
+}
+
+// The incoming filename may be the full path the the file, so split the string
+// to remove any directory prefix up until the extensions directory
+extension = extension.split('extensions/').pop();
+
+buildSingleExtension(extension, getUrlSafeFileName(extension), OUTPUT_DIR);

package/run.js

@@ -1,21 +1,25 @@
 #!/usr/bin/env node
-/* eslint-disable hubspot-dev/no-async-await */
-/*global process*/
-'use es6';
 
 const { startDevMode } = require('./dev');
 const { loadConfig } = require('./config');
-const { buildExtensions } = require('./build');
-const { VITE_DEFAULT_PORT } = require('./constants');
+const { buildAllExtensions, buildSingleExtension } = require('./build');
+const { VITE_DEFAULT_PORT, OUTPUT_DIR } = require('./constants');
+const { parseArgs, showHelp } = require('./cli');
+const { getUrlSafeFileName } = require('./utils');
 
-const DEV_MODE = process.env.DEV_MODE || false;
-const OUTPUT_DIR = 'dist';
-const PORT = process.env.PORT || VITE_DEFAULT_PORT;
+const { DEV_MODE, BUILD_MODE, port, extension, help } = parseArgs();
+const PORT = port || VITE_DEFAULT_PORT;
 
-const config = loadConfig();
+if (help || !(DEV_MODE || BUILD_MODE)) {
+  showHelp(OUTPUT_DIR);
+}
 
 if (DEV_MODE) {
-  startDevMode(config, OUTPUT_DIR, PORT);
-} else {
-  buildExtensions(config, OUTPUT_DIR);
+  startDevMode(loadConfig(), OUTPUT_DIR, PORT, extension);
+} else if (BUILD_MODE) {
+  if (extension) {
+    buildSingleExtension(extension, getUrlSafeFileName(extension), OUTPUT_DIR);
+  } else {
+    buildAllExtensions(loadConfig(), OUTPUT_DIR);
+  }
 }

package/tests/runTests.js

@@ -1,6 +1,4 @@
 #!/usr/bin/env node
-/*global process */
-'use es6';
 
 const { testBuild } = require('./testBuild');
 const { testDevServer } = require('./testDevServer');

package/tests/testBuild.js

@@ -1,22 +1,15 @@
-/*global module, process */
-'use es6';
-
 const { execSync } = require('child_process');
 const fs = require('fs');
 const path = require('path');
 const assert = require('assert');
 
-function testBuild(logger) {
-  logger.info('Build Tests started 🤞');
-  execSync('hs-ui-extensions-dev-server');
+function _testHelper(command, outputDirFiles) {
+  execSync(command);
 
   // Make sure the files are getting generated in the dist dir
   const distDir = path.join(process.cwd(), 'dist');
   const filesInOutputDir = fs.readdirSync(distDir);
-  assert.deepStrictEqual(filesInOutputDir, [
-    'PhoneLines.js',
-    'ProgressBarApp.js',
-  ]);
+  assert.deepStrictEqual(filesInOutputDir, outputDirFiles);
 
   // Spot check the file contents to make sure they seem ok
   filesInOutputDir.forEach(file => {
@@ -35,8 +28,53 @@ function testBuild(logger) {
       );
     });
   });
+}
+
+function testDefaultBuildPath(logger) {
+  logger.warn('- Test default build path started 🤞');
+  _testHelper('hs-ui-extensions-dev-server build', [
+    'PhoneLines.js',
+    'ProgressBarApp.js',
+  ]);
+  logger.info('- Test default build path passed 🚀');
+}
+
+function testBuildWithExtensionFlag(logger) {
+  logger.warn('- Test build with flags started 🤞');
+  _testHelper(
+    'hs-ui-extensions-dev-server build --extension ProgressBarApp.tsx',
+    ['ProgressBarApp.js']
+  );
+  logger.info('- Test build with flags passed 🚀');
+}
+
+function testDefInfraBuildFileName(logger) {
+  logger.warn('- Test build with entrypoint as arg 🤞');
+  _testHelper('hs-ui-extensions-remote-build ProgressBarApp.tsx', [
+    'ProgressBarApp.js',
+  ]);
+  logger.info('- Test build with entrypoint as arg 🚀');
+}
+
+function testDevInfraBuildFileNameWithPathPrefix(logger) {
+  logger.warn('- Test build with config file as arg 🤞');
+  _testHelper(
+    'hs-ui-extensions-remote-build some/super/long/file/path/to/the/extensions/PhoneLines.tsx',
+    ['PhoneLines.js']
+  );
+  logger.info('- Test build with config file as arg 🚀');
+}
+
+function testBuild(logger) {
+  logger.warn('\nBuild Tests started - External Devs 🤞');
+  testDefaultBuildPath(logger);
+  testBuildWithExtensionFlag(logger);
+  logger.info('Build Tests passed - External Devs🚀');
 
-  logger.info('Build Tests passed 🚀');
+  logger.warn('\nBuild Tests started - Dev Infra 🤞');
+  testDefInfraBuildFileName(logger);
+  testDevInfraBuildFileNameWithPathPrefix(logger);
+  logger.info('Build Tests passed - Dev Infra 🚀');
 }
 
 module.exports = {

package/tests/testDevServer.js

@@ -1,6 +1,3 @@
-/*global module, process */
-'use es6';
-
 const { spawn } = require('child_process');
 const fs = require('fs');
 const path = require('path');
@@ -14,24 +11,32 @@ const testResults = {
   webSocketTestPassed: false,
 };
 
+const port = 5172;
+
 function testDevServer(logger, devServerProcess) {
-  logger.info('Dev Server Tests started 🤞');
+  logger.warn('\nDev Server Tests started 🤞');
 
   // We need to use spawn here because it will put the process into the background,
   // which is required because dev mode is a blocking process and we want to test that
   // the express server and websocket server are starting properly
-  devServerProcess = spawn('hs-ui-extensions-dev-server', {
-    env: { ...process.env, DEV_MODE: 'true', EXTENSION: 'PhoneLines.tsx' },
-  });
+  devServerProcess = spawn('hs-ui-extensions-dev-server', [
+    'dev',
+    '--extension',
+    'PhoneLines.tsx',
+    '--port',
+    `${port}`,
+  ]);
 
   devServerProcess.stdout.on('data', buffer => {
     const data = buffer.toString().toLowerCase();
     if (data.includes('built in')) {
-      testBuild(testResults);
+      testBuild(testResults, logger);
     }
-    if (data.includes('listening') && data.includes('localhost:5173')) {
-      testExpressServer(testResults);
-      testWebSocketServer(testResults);
+    if (data.includes('listening') && data.includes(`localhost:${port}`)) {
+      setTimeout(() => {
+        testExpressServer(testResults, logger);
+        testWebSocketServer(testResults, logger);
+      }, 1000);
     }
   });
 
@@ -74,7 +79,7 @@ function metConditions() {
 
 // Test that the files were built in the proper location and spot
 // check the contents of the files.
-function testBuild(results) {
+function testBuild(results, logger) {
   // // Make sure the files are getting generated in the dist dir
   const distDir = path.join(process.cwd(), 'dist');
   const filesInOutputDir = fs.readdirSync(distDir);
@@ -95,41 +100,44 @@ function testBuild(results) {
       `File ${filesInOutputDir[0]} contents should contain: "${stringToCheck}"`
     );
   });
+  logger.info('- Build succeeded 🚀');
   results.buildTestPassed = true;
 }
 
 // Test that the express server is running on the expected port
 // and that it is serving the files as expected.
-function testExpressServer(results) {
+function testExpressServer(results, logger) {
   http.get(
     {
       host: 'localhost',
-      port: 5173,
+      port,
       path: '/PhoneLines.js',
     },
     response => {
       if (response.statusCode !== 200) {
         throw Error('Error with express server');
       }
+      logger.info('- Express server connected and serving files 🚀');
       results.expressTestPassed = true;
     }
   );
 }
 
 // Test the the web socket server is running on the expected port and
-// that we are able to recieve messages from it.
-function testWebSocketServer(results) {
+// that we are able to receive messages from it.
+function testWebSocketServer(results, logger) {
   const fileContents = fs
     .readFileSync(path.join('dist', 'PhoneLines.js'))
     .toString('base64');
 
-  const ws = new WebSocket('ws://localhost:5173');
+  const ws = new WebSocket(`ws://localhost:${port}`);
   ws.on('message', messageBuffer => {
     const message = JSON.parse(messageBuffer.toString());
     assert(message.event === 'start' || message.event === 'update');
     assert(message.appName === 'example-app');
     assert.strictEqual(message.extension, 'Phone Lines');
     assert(message.callback, `data:text/javascript;base64,${fileContents}`);
+    logger.info('- WebSocket server connected and sending messages 🚀');
     results.webSocketTestPassed = true;
   });
 }

package/utils.js

@@ -1,6 +1,3 @@
-/*global module*/
-'use es6';
-
 function getUrlSafeFileName(filePath) {
   const fileName = filePath.split('/').pop();
   const fileNameWithJsExtension = fileName.replace(/\.ts[x]?$|\.jsx$/g, '.js');