mirror of
https://github.com/dualshock-tools/dualshock-tools.github.io.git
synced 2026-03-01 11:19:54 +03:00
137 lines
3.8 KiB
Markdown
137 lines
3.8 KiB
Markdown
# Development Guide
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
PORT=8444 npm run serve:https
|
|
```
|
|
|
|
### Build Errors
|
|
|
|
Clean and rebuild:
|
|
|
|
```bash
|
|
npm run clean
|
|
npm run build
|
|
```
|
|
|
|
### SSL Certificate Issues
|
|
|
|
The certificates are pre-generated. If you need new ones:
|
|
|
|
```bash
|
|
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
|