learningcircuit--local-deep-research/docs/FRONTEND_BUILD_SYSTEM.md

Frontend Build System Guide

Overview

Local Deep Research uses a modern frontend build system with npm for package management and Vite for bundling. This ensures all JavaScript libraries and CSS frameworks are served locally without any external CDN dependencies.

Quick Start

Development Mode

1. Install dependencies (first time only):

   npm install
   

2. Start the Flask server:

   cd src
   python -m local_deep_research.web.app
   

3. Start Vite dev server (in a separate terminal):

   npm run dev
   

   Vite will start on http://localhost:5173 with Hot Module Replacement (HMR) for instant updates.

Production Mode

1. Build production assets:

   npm run build
   

   This creates optimized bundles in src/local_deep_research/web/static/dist/

2. Start Flask normally:

   cd src
   python -m local_deep_research.web.app
   

   Flask will automatically serve the built assets from the dist/ folder.

Architecture

Why No CDNs?

• Security: All code is audited and served from your server
• Privacy: No user data leaks to third-party CDNs
• Reliability: Works offline, no dependency on external services
• Performance: Assets are optimized and cached locally
• Compliance: Important for enterprise/government deployments

Technology Stack

• npm: Package manager for JavaScript dependencies
• Vite: Fast build tool with instant HMR in development
• Flask: Python web framework serving the application

Dependencies

All frontend dependencies are managed in package.json:

Library	Purpose	License
@fortawesome/fontawesome-free	Icons throughout the UI	Font Awesome Free
bootstrap	CSS framework for some pages	MIT
bootstrap-icons	Additional icons	MIT
chart.js	Analytics charts	MIT
highlight.js	Code syntax highlighting	BSD-3-Clause
marked	Markdown rendering	MIT
socket.io-client	Real-time updates	MIT
jspdf & html2canvas	PDF export	MIT

File Structure

.
├── package.json                 # npm dependencies and scripts
├── vite.config.js              # Vite configuration
├── node_modules/               # Downloaded packages (git-ignored)
└── src/local_deep_research/web/
    ├── static/
    │   ├── dist/              # Production build output (git-ignored)
    │   │   ├── css/           # Bundled CSS
    │   │   ├── fonts/         # Font files (Font Awesome, Bootstrap Icons)
    │   │   └── js/            # Bundled JavaScript
    │   ├── js/
    │   │   ├── app.js         # Main entry point importing all dependencies
    │   │   └── ...            # Other application JavaScript
    │   └── css/
    │       └── styles.css     # Application styles
    ├── templates/
    │   └── base.html          # Uses Vite helper for asset loading
    └── utils/
        └── vite_helper.py     # Flask-Vite integration

Common Tasks

Update Dependencies

# Update all packages to latest versions
npm update

# Check for security vulnerabilities
npm audit

# Auto-fix vulnerabilities (if possible)
npm audit fix

# Rebuild after updates
npm run build

Add a New Library

1. Install the package:

   npm install library-name
   

2. Import in src/local_deep_research/web/static/js/app.js:

   import 'library-name/dist/library.css';  // If it has CSS
   import Library from 'library-name';      // Import JS
   
   // Make available globally if needed
   window.Library = Library;
   

3. Rebuild:

   npm run build
   

Debug Build Issues

# Clean install (removes node_modules and reinstalls)
rm -rf node_modules package-lock.json
npm install

# Verbose build output
npm run build -- --debug

# Check what's included in the bundle
npm run build -- --sourcemap

Security

Automated Checks

• Pre-commit Hook: .pre-commit-hooks/check-external-resources.py prevents CDN references
• GitHub Dependabot: Enable it to get automated PRs for security updates
• npm audit: Run in CI/CD pipeline to catch vulnerabilities

Manual Security Audit

# Check for known vulnerabilities
npm audit

# See dependency tree
npm list

# Check outdated packages
npm outdated

Troubleshooting

Icons Not Showing

Problem: Font Awesome or Bootstrap icons appear as squares

Solution:

1. Ensure fonts were built: Check src/local_deep_research/web/static/dist/fonts/
2. Rebuild if missing: npm run build
3. Clear browser cache: Ctrl+F5 (or Cmd+Shift+R on Mac)

JavaScript Not Loading

Problem: Libraries like marked or Chart.js not working

Solution:

1. Check browser console for errors
2. Verify npm packages installed: npm install
3. Rebuild assets: npm run build
4. Check Flask is serving from dist: Look for .vite/manifest.json

Vite Dev Server Issues

Problem: HMR not working or connection refused

Solution:

1. Ensure Vite is running: npm run dev
2. Check port 5173 is free: lsof -i :5173
3. Verify Flask debug mode is on for development

Build Errors

Problem: npm run build fails

Solution:

1. Check Node.js version: node --version (should be 16+ or 18+)
2. Clear cache and reinstall:

   rm -rf node_modules package-lock.json
   npm cache clean --force
   npm install
   

3. Check for conflicting global packages: npm list -g --depth=0

Development Tips

Using Vite Dev Server

When developing, Vite provides:

• Instant updates: Changes appear immediately without page refresh
• Better errors: Build errors shown in browser
• Fast startup: No bundling needed during development

Production Optimization

Vite automatically:

• Minifies JavaScript and CSS
• Tree-shakes unused code
• Splits code into chunks
• Generates sourcemaps for debugging
• Optimizes images and fonts
• Creates cache-busting hashes

Flask Integration

The ViteHelper class (src/local_deep_research/web/utils/vite_helper.py) handles:

• Loading from Vite dev server in development
• Loading built assets in production
• Fallback if build hasn't run yet

CI/CD Integration

Add to your CI pipeline:

# Example GitHub Actions
- name: Setup Node.js
  uses: actions/setup-node@v3
  with:
    node-version: '24'
    cache: 'npm'

- name: Install dependencies
  run: npm ci

- name: Security audit
  run: npm audit --audit-level=high

- name: Build assets
  run: npm run build

- name: Check for external resources
  run: python .pre-commit-hooks/check-external-resources.py

Migration from CDNs

If you're updating from an older version that used CDNs:

1. Pull latest changes
2. Install npm dependencies: npm install
3. Build assets: npm run build
4. Clear browser cache: CDN resources may be cached
5. Test thoroughly: Ensure all features work offline

Contributing

When adding frontend features:

1. No external resources: All assets must be in npm packages
2. Update package.json: Add new dependencies properly
3. Import in app.js: Ensure libraries are imported
4. Test the build: Run npm run build before committing
5. Document changes: Update this guide if needed

Support

• Build issues: Check Node.js version and reinstall packages
• Runtime issues: Check browser console and Flask logs
• Security concerns: Run npm audit and update packages
• Performance: Vite automatically optimizes; check bundle size with npm run build

---

Last updated: August 2024 Vite version: 5.x npm version: 10.x