Skip to main content

​
Overview

MQTT Explorer supports two deployment modes: the traditional Electron desktop application and a modern browser-based mode. This guide covers building both modes from source.

​
Prerequisites

1

Install Node.js

MQTT Explorer requires Node.js 20 or higher:
node --version  # Should be >= 20
2

Install Yarn package manager

npm install -g yarn
3

Clone the repository

git clone https://github.com/thomasnordquist/MQTT-Explorer.git
cd MQTT-Explorer
4

Install dependencies

yarn
This automatically installs dependencies for both the root project and the app subdirectory.

​
Building Desktop Application (Electron)

The Electron build creates a native desktop application for Windows, macOS, and Linux.

​
Development Build

For active development with hot reload: 
yarn dev
This runs two processes in parallel:
  • dev:app - Webpack dev server with hot module replacement
  • dev:electron - Electron process that loads the app
The development build automatically recompiles TypeScript and reloads the app when you make changes.

​
Production Build

Build optimized production assets: 
yarn build
This command:
  1. Compiles TypeScript in the root project (tsc)
  2. Builds the React app with production optimizations (cd app && yarn run build)

​
Running the Built Application

After building, launch the Electron app: 
yarn start

​
Building Browser Mode

The browser mode runs as a Node.js web server, making MQTT Explorer accessible through any modern browser.

​
Development Build

Launch with hot reload: 
yarn dev:server
This runs:
  • dev:server:app - Webpack dev server on port 8080
  • dev:server:backend - Node.js Express server on port 3000
Browser mode requires authentication. Set MQTT_EXPLORER_USERNAME and MQTT_EXPLORER_PASSWORD environment variables.

​
Production Build

Build for production deployment: 
yarn build:server
This command:
  1. Compiles TypeScript (npx tsc)
  2. Bundles the app with Webpack in production mode (cd app && npx webpack --config webpack.browser.config.mjs --mode production)

​
Running the Server

Start the production server: 
yarn start:server
Or with custom configuration: 
MQTT_EXPLORER_USERNAME=admin \
MQTT_EXPLORER_PASSWORD=secure_password \
PORT=3000 \
yarn start:server
Access the application at http://localhost:3000.

​
Build Output Structure

​
Electron Build

dist/
├── src/           # Compiled Electron main process
├── app/           # Built React application
└── scripts/       # Build and packaging scripts

​
Browser Build

dist/
├── src/           # Compiled server code
├── app/
│   └── bundle/    # Webpack bundled application
│       ├── index.html
│       └── main.js

​
Build Scripts Reference

# Full development environment with hot reload
yarn dev

# Run only the app dev server
yarn dev:app

# Run only Electron in development mode
yarn dev:electron

​
Platform-Specific Considerations

​
Linux

On Linux, the application runs with --no-sandbox flag for AppImage compatibility.
The afterPack.ts script wraps the binary: 
// Creates mqtt-explorer wrapper that adds --no-sandbox
#!/bin/bash
"${BASH_SOURCE%/*}"/mqtt-explorer.bin "$@" --no-sandbox

​
macOS

macOS builds require code signing for distribution. See Notarization for details.
macOS builds use hardened runtime and require entitlements:
  • res/entitlements.mac.plist - Main app entitlements
  • res/entitlements.mac.inherit.plist - Child process entitlements
  • res/entitlements.mas.plist - Mac App Store entitlements

​
Windows

No special build considerations. The application builds cleanly on Windows with the standard toolchain.

​
Docker Build (Browser Mode)

Build a containerized version of browser mode: 
# Build local image
docker build -f Dockerfile.browser -t mqtt-explorer:local .

# Build for specific platform (e.g., Raspberry Pi)
docker buildx build --platform linux/arm64 \
  -f Dockerfile.browser \
  -t mqtt-explorer:local-arm64 .

# Run the container
docker run -d \
  -p 3000:3000 \
  -e MQTT_EXPLORER_USERNAME=admin \
  -e MQTT_EXPLORER_PASSWORD=secure_password \
  -v mqtt-explorer-data:/app/data \
  mqtt-explorer:local
Supported platforms:
  • linux/amd64 (x86-64)
  • linux/arm64 (Raspberry Pi 3/4/5, Apple Silicon)
  • linux/arm/v7 (Raspberry Pi 2/3)

​
Troubleshooting

​
Build Fails with TypeScript Errors

Ensure you’re using a compatible TypeScript version: 
yarn list typescript
# Should match version in package.json (5.9.3)

​
Electron Build Fails

  1. Clear build artifacts: 
    rm -rf dist build node_modules app/node_modules
yarn
yarn build
  2. Check Node.js version: 
    node --version  # Must be >= 20

​
Browser Mode Server Won’t Start

  1. Check if port 3000 is in use: 
    lsof -i :3000  # Linux/macOS
netstat -ano | findstr :3000  # Windows
  2. Verify build output exists: 
    ls -la dist/app/bundle/

​
Missing Dependencies

Reinstall with frozen lockfile: 
yarn install --frozen-lockfile

​
Next Steps

Packaging

Create distributable packages for all platforms

Releases

Learn the release workflow and version management

Build docs developers (and LLMs) love

Get started for freeTalk to us