Building

Build Variants

World Monitor supports 4 build variants from a single codebase:

Variant	Environment Variable	Production URL	Focus
Full	`VITE_VARIANT=full`	worldmonitor.app	Geopolitics, military, conflicts
Tech	`VITE_VARIANT=tech`	tech.worldmonitor.app	AI/ML, startups, cloud
Finance	`VITE_VARIANT=finance`	finance.worldmonitor.app	Markets, trading, central banks
Happy	`VITE_VARIANT=happy`	happy.worldmonitor.app	Good news, positive trends

Each variant:

Loads curated data layers and RSS feeds
Uses variant-specific branding and metadata
Shares the same codebase and build pipeline

Web Builds (Production)

Build All Variants

npm run build

Each build command:

Runs TypeScript type checking (tsc)
Bundles assets with Vite
Generates Brotli-compressed files (.br)
Creates a service worker for PWA features
Outputs to dist/

Build Output

dist/
├── index.html                    # Main entry point
├── settings.html                 # Settings window (desktop)
├── live-channels.html            # Live video grid
├── assets/
│   ├── index-[hash].js          # Main bundle
│   ├── index-[hash].css         # Styles
│   ├── deck-stack-[hash].js     # deck.gl + luma.gl
│   ├── maplibre-[hash].js       # MapLibre GL JS
│   ├── transformers-[hash].js   # Transformers.js ML
│   ├── onnxruntime-[hash].js    # ONNX Runtime Web
│   ├── locale-fr-[hash].js      # French translations
│   └── ...                      # Other chunks
├── favico/                       # Favicon variants
├── sw.js                         # Service worker
└── manifest.webmanifest          # PWA manifest

Preview Production Build

npm run preview

Starts a local server at http://localhost:4173 serving the production build.

Build Configuration

Vite configuration (vite.config.ts):

Chunk splitting — Large dependencies are split into separate chunks:
- deck-stack — deck.gl, luma.gl, loaders.gl, math.gl, h3-js
- maplibre — MapLibre GL JS
- transformers — Transformers.js
- onnxruntime — ONNX Runtime Web
- d3 — D3.js
- i18n — i18next
- sentry — Error tracking
- locale-{lang} — Lazy-loaded translations
Brotli pre-compression — All .js, .css, .html, .svg, .json, .wasm files > 1KB are pre-compressed with Brotli (.br extension)
Service worker — PWA features with offline map tile caching

Desktop Builds (Tauri)

Prerequisites

Install Rust toolchain:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Install platform-specific dependencies:

macOS
Windows
Linux

xcode-select --install

sudo apt install libwebkit2gtk-4.1-dev \
  build-essential \
  curl \
  wget \
  file \
  libssl-dev \
  libayatana-appindicator3-dev \
  librsvg2-dev

Build Desktop App

npm run desktop:build:full

Each command:

Syncs version from package.json to Tauri config
Sets VITE_VARIANT and VITE_DESKTOP_RUNTIME=1
Builds the sidecar sebuf gateway
Builds the Tauri app with Rust

Build Output

macOS
Windows
Linux

src-tauri/target/release/bundle/
├── dmg/
│   └── World Monitor_2.5.21_aarch64.dmg    # Apple Silicon
│   └── World Monitor_2.5.21_x64.dmg        # Intel
└── macos/
    └── World Monitor.app                    # Unsigned app bundle

src-tauri/target/release/bundle/
├── msi/
│   └── World Monitor_2.5.21_x64_en-US.msi  # MSI installer
└── nsis/
    └── World Monitor_2.5.21_x64-setup.exe  # NSIS installer

src-tauri/target/release/bundle/
├── appimage/
│   └── world-monitor_2.5.21_amd64.AppImage
└── deb/
    └── world-monitor_2.5.21_amd64.deb

Package and Sign (Release)

For distributable releases with code signing:

npm run desktop:package:macos:full:sign -- \
  --cert "Developer ID Application: Your Name" \
  --team-id TEAMID123

The packaging script (scripts/desktop-package.mjs):

Builds the Tauri app
Signs the app bundle/installer
Notarizes (macOS only)
Creates a distributable package

Type Checking

Check Frontend

npm run typecheck

Runs tsc --noEmit on the main TypeScript configuration.

Check API Handlers

npm run typecheck:api

Runs tsc --noEmit -p tsconfig.api.json on server-side code.

Check Everything

npm run typecheck:all

Runs both frontend and API type checks.

Build Optimizations

Chunk Size Limits

The build is configured to warn for chunks larger than 1200 KB:

// vite.config.ts
build: {
  chunkSizeWarningLimit: 1200,
}

This is intentionally higher than Vite’s default (500 KB) because geospatial libraries (MapLibre, deck.gl) produce large bundles even when split.

Manual Chunk Splitting

// vite.config.ts
output: {
  manualChunks(id) {
    if (id.includes('/@deck.gl/')) return 'deck-stack';
    if (id.includes('/maplibre-gl/')) return 'maplibre';
    // ...
  },
}

This ensures:

Heavy dependencies are loaded on-demand
Browser can cache stable libraries separately
Initial page load is faster

Tree Shaking

Unused exports are automatically removed during build:

// vite.config.ts
build: {
  rollupOptions: {
    output: {
      manualChunks: /* ... */,
    },
  },
}

Brotli Compression

The brotliPrecompressPlugin generates .br files for all static assets:

assets/index-abc123.js       → 450 KB
assets/index-abc123.js.br    → 120 KB (73% smaller)

Vercel/Cloudflare automatically serve .br files when the client sends Accept-Encoding: br.

Environment Variables

Build-Time Variables

These are embedded into the JavaScript bundle at build time:

Variable	Purpose	Example
`VITE_VARIANT`	Build variant	`full`, `tech`, `finance`, `happy`
`VITE_DESKTOP_RUNTIME`	Enable desktop features	`1`
`VITE_SENTRY_DSN`	Error tracking	`https://...`
`VITE_POSTHOG_KEY`	Product analytics	`phc_...`
`VITE_MAP_INTERACTION_MODE`	Map controls	`3d` or `flat`

Runtime Variables (Server-Only)

These are available only in Vercel/serverless functions:

Variable	Purpose
`GROQ_API_KEY`	AI summarization (Groq)
`OPENROUTER_API_KEY`	AI summarization (OpenRouter)
`UPSTASH_REDIS_REST_URL`	Cache backend
`UPSTASH_REDIS_REST_TOKEN`	Cache authentication
`FINNHUB_API_KEY`	Stock quotes
`EIA_API_KEY`	Energy data
`ACLED_ACCESS_TOKEN`	Conflict data
`WINGBITS_API_KEY`	Aircraft enrichment

See .env.example for the complete list.

CI/CD Integration

Vercel Deployment

Production builds are deployed automatically on push to main:

# vercel.json
{
  "buildCommand": "npm run build:full",
  "outputDirectory": "dist",
  "framework": "vite"
}

Variants are deployed to separate domains:

worldmonitor.app — Full variant
tech.worldmonitor.app — Tech variant
finance.worldmonitor.app — Finance variant
happy.worldmonitor.app — Happy variant

GitHub Actions

Desktop builds are automated via GitHub Actions:

# .github/workflows/release.yml
name: Release Desktop Builds
on:
  push:
    tags:
      - 'v*'

jobs:
  build-macos:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run desktop:build:full
      - run: npm run desktop:package:macos:full:sign

Troubleshooting

Build fails with 'buf: command not found'

Install buf CLI:

make install-buf

Type errors in generated code

Regenerate proto code:

make clean
make generate

Desktop build fails with Rust errors

Update Rust toolchain:

rustup update stable

Bundle size too large

Check which dependencies are bloating the bundle:

npx vite-bundle-visualizer

Service worker not updating

Clear service worker cache:

# In DevTools Console:
navigator.serviceWorker.getRegistrations().then(registrations => {
  registrations.forEach(r => r.unregister());
});

Get Started

Core Features

Data & Intelligence

Variants

Configuration

Development

Deployment

Build Variants

Web Builds (Production)

Build All Variants

Build Output

Preview Production Build

Build Configuration

Desktop Builds (Tauri)

Prerequisites

Build Desktop App

Build Output

Package and Sign (Release)

Type Checking

Check Frontend

Check API Handlers

Check Everything

Build Optimizations

Chunk Size Limits

Manual Chunk Splitting

Tree Shaking

Brotli Compression

Environment Variables

Build-Time Variables

Runtime Variables (Server-Only)

CI/CD Integration

Vercel Deployment

GitHub Actions

Troubleshooting

Next Steps

Testing

Deployment

Build docs developers (and LLMs) love

Get Started

Core Features

Data & Intelligence

Variants

Configuration

Development

Deployment

​Build Variants

​Web Builds (Production)

​Build All Variants

​Build Output

​Preview Production Build

​Build Configuration

​Desktop Builds (Tauri)

​Prerequisites

​Build Desktop App

​Build Output

​Package and Sign (Release)

​Type Checking

​Check Frontend

​Check API Handlers

​Check Everything

​Build Optimizations

​Chunk Size Limits

​Manual Chunk Splitting

​Tree Shaking

​Brotli Compression

​Environment Variables

​Build-Time Variables

​Runtime Variables (Server-Only)

​CI/CD Integration

​Vercel Deployment

​GitHub Actions

​Troubleshooting

​Next Steps

Testing

Deployment

Build docs developers (and LLMs) love

Build Variants

Web Builds (Production)

Build All Variants

Build Output

Preview Production Build

Build Configuration

Desktop Builds (Tauri)

Prerequisites

Build Desktop App

Build Output

Package and Sign (Release)

Type Checking

Check Frontend

Check API Handlers

Check Everything

Build Optimizations

Chunk Size Limits

Manual Chunk Splitting

Tree Shaking

Brotli Compression

Environment Variables

Build-Time Variables

Runtime Variables (Server-Only)

CI/CD Integration

Vercel Deployment

GitHub Actions

Troubleshooting

Next Steps