139 lines
3.9 KiB
Markdown
139 lines
3.9 KiB
Markdown
# Dashboard Build System
|
|
|
|
This document explains how to keep the Flutter web dashboard in sync with the server's static files.
|
|
|
|
## Overview
|
|
|
|
The XP Nix server serves static files from `xp_server/lib/src/web/static/` directory. The Flutter dashboard is a separate project in `xp_dashboard/` that needs to be built for web and copied to the static directory.
|
|
|
|
## Build Methods
|
|
|
|
### Method 1: Using the Server Command (Recommended)
|
|
|
|
When the server is running, you can use the interactive `build` command:
|
|
|
|
1. Start the server:
|
|
```bash
|
|
cd xp_server
|
|
dart run bin/xp_nix.dart
|
|
```
|
|
|
|
2. Type `build` in the server console and press Enter:
|
|
```
|
|
build
|
|
```
|
|
|
|
The server will:
|
|
- Check if Flutter is available
|
|
- Build the Flutter dashboard with `flutter build web --release`
|
|
- Copy all files from `xp_dashboard/build/web/` to `xp_server/lib/src/web/static/`
|
|
- Provide feedback on the build status
|
|
|
|
### Method 2: Using the Shell Script
|
|
|
|
For building outside of the running server, use the provided shell script:
|
|
|
|
```bash
|
|
./build_dashboard.sh
|
|
```
|
|
|
|
This script:
|
|
- Checks for Flutter availability
|
|
- Builds the Flutter dashboard
|
|
- Clears old static files
|
|
- Copies new files to the static directory
|
|
|
|
## Build Process Details
|
|
|
|
### What Gets Built
|
|
|
|
The Flutter build process creates:
|
|
- `index.html` - Main HTML file
|
|
- `main.dart.js` - Compiled Dart code
|
|
- `flutter.js`, `flutter_bootstrap.js` - Flutter runtime
|
|
- `flutter_service_worker.js` - Service worker for PWA features
|
|
- `assets/` - Flutter assets and fonts
|
|
- `canvaskit/` - CanvasKit rendering engine
|
|
- `icons/` - App icons
|
|
- `manifest.json` - Web app manifest
|
|
- Other supporting files
|
|
|
|
### File Synchronization
|
|
|
|
The build process:
|
|
1. **Clears** the existing `xp_server/lib/src/web/static/` directory
|
|
2. **Copies** all files from `xp_dashboard/build/web/` to the static directory
|
|
3. **Preserves** the directory structure including subdirectories
|
|
|
|
## Development Workflow
|
|
|
|
### When to Rebuild
|
|
|
|
Rebuild the dashboard when you:
|
|
- Make changes to Flutter widgets in `xp_dashboard/lib/`
|
|
- Update dependencies in `xp_dashboard/pubspec.yaml`
|
|
- Modify theme or styling
|
|
- Add new features to the dashboard
|
|
|
|
### Typical Workflow
|
|
|
|
1. Make changes to the Flutter dashboard code
|
|
2. Test locally if needed: `cd xp_dashboard && flutter run -d web-server`
|
|
3. Build and deploy: Use either the server `build` command or `./build_dashboard.sh`
|
|
4. Refresh your browser to see the changes
|
|
|
|
## Troubleshooting
|
|
|
|
### Flutter Not Found
|
|
```
|
|
❌ Flutter is not available in the system PATH
|
|
```
|
|
**Solution**: Ensure Flutter is installed and added to your PATH.
|
|
|
|
### Build Failed
|
|
```
|
|
❌ Flutter build failed
|
|
```
|
|
**Solution**: Check the error output, usually related to:
|
|
- Dart compilation errors
|
|
- Missing dependencies (`flutter pub get`)
|
|
- Invalid Flutter code
|
|
|
|
### Files Not Copied
|
|
```
|
|
❌ Build output directory not found
|
|
```
|
|
**Solution**: The Flutter build didn't complete successfully. Check the build output for errors.
|
|
|
|
## File Structure
|
|
|
|
```
|
|
xp_nix/
|
|
├── xp_dashboard/ # Flutter dashboard source
|
|
│ ├── lib/ # Flutter source code
|
|
│ ├── web/ # Web-specific files
|
|
│ └── build/web/ # Build output (generated)
|
|
├── xp_server/
|
|
│ ├── lib/src/web/static/ # Static files served by server
|
|
│ └── lib/src/build/ # Build system code
|
|
├── build_dashboard.sh # Standalone build script
|
|
└── BUILD_DASHBOARD.md # This documentation
|
|
```
|
|
|
|
## Advanced Usage
|
|
|
|
### Custom Build Options
|
|
|
|
To modify build options, edit the Flutter build command in:
|
|
- `xp_server/lib/src/build/dashboard_builder.dart` (for server command)
|
|
- `build_dashboard.sh` (for shell script)
|
|
|
|
Current build command: `flutter build web --release`
|
|
|
|
### Development vs Production
|
|
|
|
- **Development**: Use `flutter build web` (debug mode, faster builds)
|
|
- **Production**: Use `flutter build web --release` (optimized, smaller files)
|
|
|
|
The current setup uses `--release` for optimal performance.
|