Improve dev server with unified command and listhen integration

README.md

@@ -29,10 +29,60 @@ After that, you can make changes to the source code and run the following comman
 npm run build
 ```
 
-If you are developing the application locally and want to build the source code in watch mode, you can run the following command:
+### Development Server
+
+For local development, you have several options:
+
+#### Full Development Server (Recommended)
+Run everything with a single command that combines webpack build watching and HTTP server:
+
+```sh
+npm run dev:full
+```
+
+This will:
+- Start webpack in watch mode for automatic rebuilds
+- Start an HTTP server on http://localhost:8080 with CORS enabled
+- Display the auto-loader URL for Custom Checkout integration
+
+#### Development Server with HTTPS Tunnel
+For testing with live HTTPS websites, you can enable Cloudflare Tunnels:
 
 ```sh
+npm run dev:tunnel
+```
+
+This provides:
+- All features of `dev:full`
+- An HTTPS tunnel URL (e.g., `https://abc123.trycloudflare.com`)
+- Automatic tunnel URL display for easy Custom Checkout integration
+
+#### Manual Development (Legacy)
+If you prefer the traditional two-step approach:
+
+```sh
+# Terminal 1: Start webpack in watch mode
 npm run dev
+
+# Terminal 2: Start the HTTP server
+npm run dev:server
+```
+
+#### Environment Variables
+You can customize the development server behavior using environment variables:
+
+```sh
+# Enable tunnel mode
+DEV_SERVER_TUNNEL=true npm run dev:full
+
+# Change port
+DEV_SERVER_PORT=3000 npm run dev:full
+
+# Enable verbose logging
+DEV_SERVER_VERBOSE=true npm run dev:full
+
+# Custom cloudflared path
+CLOUDFLARED_PATH=/usr/local/bin/cloudflared npm run dev:tunnel
 ```
 
 If you want to create a prerelease (i.e.: `alpha`) for testing in the integration environment, you can run the following command:
@@ -61,13 +111,29 @@ npm run regenerate-har
 
 Follow [this guide](https://developer.bigcommerce.com/stencil-docs/customizing-checkout/installing-custom-checkouts) for instructions on how to fork and install this app as a Custom Checkout in your store.
 
-If you want to test your checkout implementation, you can run:
+### For Development Testing
+
+#### Using the Enhanced Development Server (Recommended)
+```sh
+# Local development with HTTP
+npm run dev:full
+# Then use: http://localhost:8080/auto-loader-dev.js
+
+# For HTTPS testing with live stores
+npm run dev:tunnel
+# The tunnel URL will be displayed (e.g., https://abc123.trycloudflare.com/auto-loader-dev.js)
+```
+
+#### Using the Legacy Method
+If you want to test your checkout implementation manually, you can run:
 ```sh
 npm run dev:server
 ```
 
 And enter the local URL for `auto-loader-dev.js` in Checkout Settings, e.g `http://127.0.0.1:8080/auto-loader-dev.js`
 
+**Note:** The HTTPS tunnel option is particularly useful when testing with live BigCommerce stores that require HTTPS connections.
+
 ## Release
 
 Everytime a PR is merged to the master branch, CircleCI will trigger a build automatically. However, it won't create a new Git release until it is approved by a person with write access to the repository. If you have write access, you can approve a release job by going to [CircleCI](https://circleci.com/gh/bigcommerce/workflows/checkout-js/tree/master) and look for the job you wish to approve. You can also navigate directly to the release job by clicking on the yellow dot next to the merged commit.

package.json

@@ -18,6 +18,8 @@
     "build:server": "http-server dist",
     "typecheck": "tsc --noEmit -p ./tsconfig.base.json",
     "dev": "npm-run-all nx:dev",
+    "dev:full": "node scripts/dev-server.js",
+    "dev:tunnel": "node scripts/dev-server.js --tunnel",
     "dev:vm": "WEBPACK_DONE='rsync -rvc --progress --delete --compress-level=9 build store.bcdev:/opt/bigcommerce_app/vagrant_code/vendor/bower_components/checkout-js/' npm run dev",
     "dev:server": "http-server build --cors",
     "e2e": "npm run build && npx playwright install && PORT=5005 MODE=REPLAY npx playwright test",
@@ -157,6 +159,7 @@
     "jest": "29.7.0",
     "jest-environment-jsdom": "29.7.0",
     "jest-junit": "^15.0.0",
+    "listhen": "^1.9.0",
     "mini-css-extract-plugin": "^2.6.0",
     "msw": "^1.3.2",
     "npm-run-all": "^4.1.5",

scripts/README.md

@@ -0,0 +1,68 @@
+# Development Server Enhancement
+
+This directory contains enhanced development server scripts that improve the BigCommerce Checkout JS development workflow using [listhen](https://github.com/unjs/listhen).
+
+## Scripts
+
+### dev-server.js
+Main development server script that combines webpack development build with HTTP server and optional tunneling via listhen.
+
+**Features:**
+- Unified command to start both webpack dev build and HTTP server
+- Optional HTTPS tunneling via listhen (powered by untun)
+- Automatic port selection and process management
+- Configurable via CLI arguments or environment variables
+- Verbose logging mode for debugging
+- Built-in static file serving with CORS support
+
+### test-dev-server.js
+Test script to verify the development server functionality.
+
+**Features:**
+- Automated testing of dev server startup
+- HTTP endpoint validation
+- Proper cleanup and error handling
+
+## Usage Examples
+
+```bash
+# Basic development server
+npm run dev:full
+
+# Development server with HTTPS tunnel
+npm run dev:tunnel
+
+# Custom port and verbose logging
+DEV_SERVER_PORT=3000 DEV_SERVER_VERBOSE=true npm run dev:full
+
+# Using the script directly
+node scripts/dev-server.js --help
+node scripts/dev-server.js --port 9000 --tunnel --verbose
+```
+
+## Environment Variables
+
+- `DEV_SERVER_TUNNEL`: Enable tunnel mode ('true'/'false')
+- `DEV_SERVER_PORT`: HTTP server port (default: 8080, auto-selected with listhen)
+- `DEV_SERVER_VERBOSE`: Enable verbose logging ('true'/'false')  
+- `DEV_SERVER_BUILD_DIR`: Build directory to serve (default: build)
+
+## Architecture
+
+The dev-server.js script manages:
+
+1. **Webpack Process**: Runs `npm run dev` for watch mode compilation
+2. **Listhen Server**: Elegant HTTP server with optional tunneling capabilities
+   - Static file serving for the build directory
+   - Automatic CORS headers
+   - SPA routing support (fallback to index.html)
+   - Optional HTTPS tunnel via untun/cloudflared
+
+All processes are managed with proper signal handling and cleanup on exit.
+
+## Benefits of Listhen Integration
+
+- **Automatic port selection**: No more port conflicts during development
+- **Built-in tunneling**: Simplified tunnel setup without manual cloudflared installation
+- **Better error handling**: Graceful fallbacks when tunneling is unavailable
+- **Modern architecture**: Based on unjs ecosystem with h3 and nitro foundation