xp_nix/BUILD_DASHBOARD.md

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:

   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:

./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.