Improve dev server with unified command and listhen integration

[Copilot]

This PR enhances the development workflow by introducing a unified development server that combines webpack building, HTTP serving, and optional HTTPS tunneling in a single command using listhen.

Problem

The current development setup requires running two separate commands:

1. npm run dev - starts webpack in watch mode
2. npm run dev:server - starts the HTTP server

This creates friction in the development workflow and makes it difficult to test with live HTTPS websites that require secure connections.

Solution

New Development Commands

npm run dev:full - The new recommended development command that:

• Starts webpack in development watch mode
• Automatically starts HTTP server once webpack is ready
• Provides clear status messages and error handling
• Manages all processes with proper cleanup on exit

npm run dev:tunnel - Enhanced development with HTTPS tunneling:

• All features of dev:full
• Creates an HTTPS tunnel via listhen (powered by untun)
• Provides a public URL like https://abc123.trycloudflare.com
• Perfect for testing Custom Checkout integration with live BigCommerce stores

Key Features

• Process Management: Intelligent coordination of webpack and HTTP server processes
• Error Handling: Graceful fallbacks when tunnel fails (e.g., offline environments)
• Configuration: Support for environment variables and CLI flags
• Automatic Port Selection: listhen automatically finds available ports
• Built-in Static Serving: H3-based static file server with CORS support
• Backward Compatibility: Existing npm run dev and npm run dev:server commands remain unchanged

Usage Examples

# Basic unified development (recommended)
npm run dev:full

# Development with HTTPS tunnel for live testing
npm run dev:tunnel

# Custom configuration
DEV_SERVER_PORT=3000 DEV_SERVER_VERBOSE=true npm run dev:full

# Direct script usage with options
node scripts/dev-server.js --port 9000 --tunnel --verbose

Custom Checkout Integration

The tunnel feature is particularly valuable for Custom Checkout development:

npm run dev:tunnel
# Output: 🌩️  Tunnel ready: https://abc123.trycloudflare.com
# Output: 🔗 Auto-loader URL: https://abc123.trycloudflare.com/auto-loader-dev.js

Simply copy the HTTPS auto-loader URL into your BigCommerce store's Checkout Settings.

Implementation Details

• scripts/dev-server.js: Main unified server with webpack + listhen-based HTTP server + optional tunneling
• scripts/test-dev-server.js: Validation script ensuring everything works correctly
• Enhanced error handling: Clear messages when tunnel fails, with automatic fallback to local-only mode
• Signal handling: Proper cleanup of all child processes on exit
• Modern architecture: Built on unjs ecosystem (listhen, h3, untun) for better maintainability

The solution maintains full backward compatibility while providing a significantly improved developer experience through listhen's elegant HTTP server capabilities, automatic port selection, and built-in tunneling support.

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

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

[bookernath]

@copilot instead of a direct cloudflare tunnel integration, can you use https://github.com/unjs/listhen instead which will give us tunneling as well as automatic port selection and so on?

[Copilot]

@copilot instead of a direct cloudflare tunnel integration, can you use https://github.com/unjs/listhen instead which will give us tunneling as well as automatic port selection and so on?

Done! I've replaced the direct Cloudflare tunnel integration with listhen as requested. The changes include:

• Replaced dev-server.js with listhen-based implementation using h3 for static file serving
• Added listhen dependency and removed cloudflared installation script
• Updated documentation to reflect the new listhen integration
• Maintained the same CLI interface (dev:full, dev:tunnel commands)

Listhen provides automatic port selection, built-in tunneling via untun/cloudflared, and better error handling with graceful fallbacks. The new implementation is more elegant and maintainable while providing the same functionality.

Commit: cc82a8c

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• googlechromelabs.github.io
  • Triggering command: node install.mjs (dns block)
• https://storage.googleapis.com/chrome-for-testing-public/137.0.7151.70/linux64/chrome-linux64.zip
  • Triggering command: node install.mjs (http block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)