provisioning/provisioning-outreach

Jesús Pérez 3666748bd9

outreach: clean-start baseline — public reach surface (constellation materialization)

2026-07-09 21:58:36 +01:00

9 KiB

Raw Blame History

Provisioning Poster Build System\n\nA modern, optimized build system for the Provisioning poster using Nushell scripts. This system provides development and production workflows with advanced optimization techniques.\n\n## 🎯 Features\n\n- 📦 Modular CSS: Split into focused modules (base, components, animations, patterns)\n- 🚀 Fast Development: File watching with auto-rebuild\n- ⚡ Production Optimization: CSS/HTML/SVG minification and compression\n- 🎨 SVG Management: Smart inlining vs external loading strategy\n- 📊 Performance Analysis: Detailed size and optimization reports\n- 🌐 Development Server: Built-in HTTP server with live reload\n- 🔧 Zero Dependencies: Pure Nushell implementation, no Node.js required\n\n## 📁 Project Structure\n\nplaintext\nposter/\n├── src/ # Source files (development)\n│ ├── index.html # Main HTML file\n│ ├── assets/\n│ │ ├── css/\n│ │ │ ├── main.css # Main CSS entry point\n│ │ │ ├── svg-data.css # SVG data URIs\n│ │ │ └── modules/ # Modular CSS files\n│ │ │ ├── base.css # Reset, typography, layout\n│ │ │ ├── components.css # UI components\n│ │ │ ├── animations.css # All animations\n│ │ │ └── patterns.css # Visual patterns\n│ │ └── svg/\n│ │ ├── symbols.svg # Animated symbols (inline)\n│ │ └── decorative-sprites.svg # Decorative patterns\n│ └── components/ # HTML partials (future)\n│\n├── dist/ # Built files (production)\n│ ├── index.html # Optimized HTML\n│ ├── assets/\n│ │ ├── css/\n│ │ │ └── main.min.css # Minified CSS\n│ │ └── svg/\n│ │ └── sprites.svg # Optimized SVG\n│ ├── .htaccess # Apache configuration\n│ ├── nginx.conf # Nginx configuration\n│ └── deploy.sh # Deployment script\n│\n├── scripts/ # Build scripts\n│ ├── build.nu # Main build script\n│ ├── dev.nu # Development workflow\n│ ├── prod.nu # Production workflow\n│ ├── optimize-css.nu # CSS optimization\n│ ├── optimize-svg.nu # SVG optimization\n│ ├── optimize-html.nu # HTML optimization\n│ └── utils.nu # Utility functions\n│\n└── config/\n └── build.config.nu # Build configuration\n\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- Nushell 0.105.2+ - Install Nushell\n\n### Development\n\n`bash\n# Start development server with file watching\nnu scripts/dev.nu --watch --port 3000\n\n# Quick development build only\nnu scripts/dev.nu build\n\n# Lint and validate source files\nnu scripts/dev.nu lint\n`\n\n### Production\n\n`bash\n# Full production build with optimization\nnu scripts/prod.nu\n\n# Production build with analysis and compression\nnu scripts/prod.nu full\n\n# Quick production build\nnu scripts/prod.nu quick\n`\n\n## 🛠️ Commands Reference\n\n### Development Commands\n\n| Command | Description |\n|---------|-------------|\n| `nu scripts/dev.nu` | Start dev server with file watching |\n| `nu scripts/dev.nu build` | Quick development build |\n| `nu scripts/dev.nu clean` | Clean development build |\n| `nu scripts/dev.nu analyze` | Build with file size analysis |\n| `nu scripts/dev.nu lint` | Lint and validate source files |\n| `nu scripts/dev.nu preview` | Preview production build locally |\n\n#### Development Options\n\n- `--port, -p <PORT>` - Development server port (default: 8080)\n- `--watch, -w` - Enable file watching for auto-rebuild\n- `--no-browser, -n` - Don't open browser automatically\n- `--verbose, -v` - Verbose output\n\n### Production Commands\n\n| Command | Description |\n|---------|-------------|\n| `nu scripts/prod.nu` | Full production build |\n| `nu scripts/prod.nu quick` | Quick production build |\n| `nu scripts/prod.nu full` | Full build with analysis and compression |\n| `nu scripts/prod.nu staging` | Build for staging environment |\n\n#### Production Options\n\n- `--analyze, -a` - Show detailed performance analysis\n- `--compress, -c` - Generate compressed versions (gzip)\n- `--verbose, -v` - Verbose output\n- `--output, -o <DIR>` - Custom output directory\n\n## ⚙️ Configuration\n\nEdit `config/build.config.nu` to customize build settings:\n\nnu\nexport const config = {\n # Directories\n src_dir: "src",\n dist_dir: "dist",\n\n # Critical CSS settings\n critical_css_modules: 2, # First N modules for critical CSS\n inline_css_max_size: 10240, # 10KB max for inline CSS\n\n # Optimization settings\n css_minify: true,\n html_minify: true,\n svg_optimize: true,\n svg_precision: 2,\n\n # Development server\n dev_port: 8080,\n dev_host: "localhost",\n\n # Performance thresholds\n inline_svg_max_size: 5120, # 5KB max for SVG inline\n\n # Output options\n verbose: true,\n show_file_sizes: true\n}\n\n\n## 🎯 Optimization Strategies\n\n### CSS Optimization\n\n1. Modular Architecture: CSS split into focused modules\n2. Critical CSS Inlining: Above-the-fold styles inlined in HTML\n3. Minification: Comments and whitespace removal\n4. Module Combination: External CSS combines non-critical modules\n\n### SVG Optimization\n\n1. Smart Inlining: Critical animated SVGs stay inline\n2. External Sprites: Decorative SVGs in external sprite files\n3. Data URI System: Small icons as CSS custom properties\n4. Size-based Strategy: Automatic inline vs external decisions\n\n### HTML Optimization\n\n1. Critical Resource Inlining: CSS and SVG above-the-fold\n2. Async Loading: Non-critical resources loaded asynchronously\n3. Meta Optimization: Performance and SEO meta tags\n4. Attribute Cleanup: Unnecessary attributes removed\n\n## 📊 Performance Results\n\nTypical optimization results:\n\n| Asset | Original | Optimized | Savings |\n|-------|----------|-----------|---------|\n| HTML | ~50KB | ~30KB | 40% |\n| CSS | ~40KB | ~25KB | 37% |\n| SVG | ~30KB | ~15KB | 50% |\n| Total | 120KB | 70KB | 42% |\n\nWith gzip compression:\n\n- Final size: ~18KB total\n- Load time: <1s on 3G networks\n\n## 🔧 Extending the Build System\n\n### Adding CSS Modules\n\n1. Create new module in `src/assets/css/modules/`\n2. Add to `css_modules` array in `config/build.config.nu`\n3. Import in `src/assets/css/main.css`\n\n### Custom Optimization\n\nAdd custom optimization functions to the respective scripts:\n\n- CSS: `scripts/optimize-css.nu`\n- SVG: `scripts/optimize-svg.nu`\n- HTML: `scripts/optimize-html.nu`\n\n### Development Workflow\n\nThe file watcher monitors:\n\n- `src/index.html`\n- `src/assets/css/modules/.css`\n- `src/assets/css/.css`\n- `src/assets/svg/*.svg`\n\nAuto-rebuild triggers on file changes during development.\n\n## 🚀 Deployment\n\n### Generated Deployment Files\n\nThe production build generates:\n\n- `.htaccess` - Apache server configuration\n- `nginx.conf` - Nginx server configuration\n- `deploy.sh` - Automated deployment script\n- `robots.txt` - SEO robots file\n\n### Deployment Options\n\n1. Manual: Copy `dist/` contents to web server\n2. Automated: Use generated `deploy.sh` script\n3. CI/CD: Integrate build commands in pipeline\n\n### Server Configuration\n\n#### Apache\n\nThe generated `.htaccess` enables:\n\n- Gzip compression\n- Cache headers\n- Security headers\n- MIME types\n\n#### Nginx\n\nThe generated `nginx.conf` includes:\n\n- Gzip compression\n- Cache rules\n- Security headers\n- Try files configuration\n\n## 🔍 Troubleshooting\n\n### Common Issues\n\n1. Build fails: Check Nushell version (0.105.2+ required)\n2. File watching not working: Ensure source files exist\n3. Server won't start: Check port availability\n4. Optimization too aggressive: Adjust config thresholds\n\n### Debug Commands\n\n`bash\n# Validate configuration\nnu scripts/build.nu --dev --verbose\n\n# Analyze file sizes\nnu scripts/dev.nu analyze\n\n# Check source file validity\nnu scripts/dev.nu lint\n\n# Test production build locally\nnu scripts/dev.nu preview\n`\n\n### Performance Issues\n\nIf builds are slow:\n\n1. Reduce `svg_precision` in config\n2. Disable verbose output\n3. Skip analysis during development\n4. Use `quick` commands for rapid iteration\n\n## 🤝 Contributing\n\nTo contribute to the build system:\n\n1. Follow Nushell best practices\n2. Add comprehensive error handling\n3. Include performance optimizations\n4. Document new features\n5. Test on multiple platforms\n\n## 📝 License\n\nThis build system is part of the Provisioning project and follows the same license terms.\n\n---\n\nBuilt with ❤️ using Nushell and optimized for modern web performance.