Skip to content

DEVELOPMENT.md

Latest commit

 

History

History
136 lines (95 loc) · 3.83 KB

DEVELOPMENT.md

File metadata and controls

136 lines (95 loc) · 3.83 KB

Development Guide

Quick Start

# Install dependencies
npm install

# Start development with auto-reload
npm run dev:full

Open https://localhost:8443 in your browser (accept the SSL certificate warning).

Available Scripts

Script Description
npm run build Build for development (with source maps)
npm run build:prod Build for production (minified, optimized)
npm run clean Clean the dist directory
npm run serve:https Serve built app over HTTPS (required for WebHID)
npm run serve Serve built app over HTTP (WebHID won't work)
npm run start Build and serve over HTTPS
npm run dev:full Recommended: Build, watch, and serve with auto-reload
npm run watch Watch files and rebuild on changes

Development Workflow

For Active Development

npm run dev:full

This starts the complete development environment:

  • Builds the application
  • Watches for file changes
  • Serves over HTTPS at https://localhost:8443
  • Automatically rebuilds when you save files

For Testing Built Version

npm run start

This builds once and serves the result.

Important Notes

HTTPS Requirement

The WebHID API requires HTTPS. The development server uses self-signed certificates located at:

  • server.crt - SSL certificate
  • server.key - SSL private key

Browser Compatibility

  • Chrome/Edge: Full WebHID support ✅
  • Firefox: No WebHID support ❌
  • Safari: No WebHID support ❌

SSL Certificate Warning

When first accessing https://localhost:8443, your browser will show a security warning because we're using a self-signed certificate. This is normal for development - click "Advanced" and "Proceed to localhost" to continue.

File Structure

├── js/                 # Source JavaScript files
│   ├── core.js        # Main application entry point
│   ├── controllers/   # Controller-specific classes
│   └── modals/        # Modal dialog handlers
├── css/               # Source CSS files
├── templates/         # HTML template files
├── lang/              # Translation JSON files
├── assets/            # SVG assets
├── dist/              # Built application (auto-generated)
└── dev-server.js      # Custom development server

Build Process

The build system uses Gulp with the following steps:

  1. JavaScript: Bundled with Rollup, supports ES modules
  2. CSS: Concatenated and optionally minified
  3. HTML: Processed and optionally minified
  4. Assets: Copied to dist, SVGs can be inlined in production
  5. Languages: JSON files copied and optionally minified

Development vs Production

Feature Development Production
Source maps ✅ ❌
Minification ❌ ✅
Asset inlining ❌ ✅
File hashing ❌ ✅

Troubleshooting

Port Already in Use

If port 8443 is busy:

PORT=8444 npm run serve:https

Build Errors

Clean and rebuild:

npm run clean
npm run build

SSL Certificate Issues

The certificates are pre-generated. If you need new ones:

openssl req -x509 -newkey rsa:4096 -keyout server.key -out server.crt -days 365 -nodes -subj "/CN=localhost"

WebHID Not Working

  1. Make sure you're using HTTPS (npm run serve:https)
  2. Use Chrome or Edge browser
  3. Accept the SSL certificate warning
  4. Check browser console for errors