Skip to main content
Get up and running with MQTT Explorer development in minutes. This guide covers environment setup, running the application, and your first build.

​
Prerequisites

Before you begin, ensure you have:
  • Node.js >= 20
  • Yarn package manager
  • Git for version control
MQTT Explorer requires Node.js 20 or higher. Check your version with node --version.

​
Quick Start with GitHub Codespaces

The fastest way to start developing is with GitHub Codespaces, which includes a pre-configured environment with Node.js and an MQTT broker:
1

Open Codespaces

  1. Click the green “Code” button on the repository
  2. Select the “Codespaces” tab
  3. Click “Create codespace on [branch]”
2

Wait for Setup

The devcontainer will automatically install dependencies and start services. This takes 2-3 minutes.
3

Start Development

yarn dev:server
The development server will start with hot reload enabled.
The devcontainer includes a pre-configured MQTT broker at localhost:1883. See .devcontainer/README.md for details.

​
Local Development Setup

​
Initial Setup

1

Install Yarn

npm install -g yarn
2

Clone Repository

git clone https://github.com/thomasnordquist/mqtt-explorer.git
cd mqtt-explorer
3

Install Dependencies

yarn
This installs dependencies for all packages (root, app, and backend).

​
Development Modes

MQTT Explorer supports two development modes: Desktop (Electron) and Browser.

​
Desktop Application (Electron)

Develop the native desktop application with hot reload: 
yarn dev
This runs two processes in parallel:
  • App dev server - React frontend with hot reload
  • Electron process - Desktop window
The yarn dev command uses npm-run-all to run dev:app and dev:electron in parallel.

​
Browser Mode (Web Application)

Develop the web version served by Node.js: 
yarn dev:server
Open http://localhost:3000 in your browser. This runs:
  • Webpack dev server - React frontend with hot reload (port 3000)
  • Node.js backend - Express server with Socket.IO
Browser mode is ideal for testing mobile compatibility and developing without Electron overhead. See BROWSER_MODE.md for details.

​
Project Structure

mqtt-explorer/
├── app/              # React frontend (rendering logic)
│   ├── src/
│   │   ├── components/  # React components
│   │   ├── actions/     # Redux actions
│   │   ├── reducers/    # Redux reducers
│   │   ├── services/    # Business logic (LLM, decoders)
│   │   └── theme.ts     # Material-UI theme
│   └── package.json
├── backend/          # Data models and business logic
│   └── src/
│       ├── Model/       # MQTT topic tree, message handling
│       └── DataSource/  # Connection management
├── src/              # Electron bindings & server
│   ├── electron.ts      # Electron main process
│   └── server.ts        # Express server (browser mode)
├── package.json      # Root package (scripts, Electron config)
└── tsconfig.json     # TypeScript configuration
Key directories:
  • app/ - All UI and rendering logic
  • backend/ - Models, tests, connection management
  • src/ - Electron bindings and Node.js server
  • scripts/ - Build and release automation

​
Available Scripts

​
Development

CommandDescription
yarn devStart Electron app in development mode
yarn dev:serverStart browser mode with hot reload
yarn dev:appRun only the frontend dev server
yarn dev:electronRun only Electron (after building)

​
Building

CommandDescription
yarn buildBuild desktop application
yarn build:serverBuild browser mode for production
yarn startStart built Electron app
yarn start:serverStart built Node.js server

​
Testing

CommandDescription
yarn testRun all unit tests
yarn test:appRun frontend tests
yarn test:backendRun backend tests
yarn test:uiRun UI automation tests
See Testing for comprehensive test documentation.

​
First Build

Verify your setup by building the application:
1

Build TypeScript

yarn build
Compiles TypeScript and bundles the React app.
2

Verify Output

Check that build artifacts exist:
ls -la dist/     # TypeScript output
ls -la app/dist/ # Webpack bundles
3

Run Application

yarn start
The Electron window should open successfully.
Build failures? Check:
  • Node.js version (node --version >= 20)
  • Clean install: rm -rf node_modules && yarn
  • TypeScript errors: npx tsc --noEmit

​
Development Workflow

A typical development session:
1

Start Dev Server

yarn dev:server
Changes auto-reload in the browser.
2

Make Changes

Edit files in app/src/ for frontend changes or backend/src/ for model changes.
3

Test Changes

yarn test
Run tests to verify your changes.
4

Lint Code

yarn lint
Check for style and formatting issues.

​
Setting Up an MQTT Broker

For testing, you’ll need an MQTT broker. The easiest option: 
docker run -it -p 1883:1883 eclipse-mosquitto:latest
Connect to localhost:1883 in MQTT Explorer.
Public test brokers:
  • test.mosquitto.org:1883 (unencrypted)
  • mqtt.eclipseprojects.io:1883
Use for testing only - data is public!

​
Next Steps

Architecture

Understand the codebase structure and design patterns

Testing

Learn how to write and run tests

Styling

Follow Material-UI theming conventions

Contributing

Submit your first pull request

​
Troubleshooting

​
Port Already in Use

# Kill process on port 3000
lsof -ti:3000 | xargs kill -9

​
Dependencies Out of Sync

# Clean reinstall
rm -rf node_modules app/node_modules backend/node_modules
rm -f yarn.lock
yarn

​
TypeScript Errors

# Check for errors without building
npx tsc --noEmit

# Rebuild from scratch
rm -rf dist app/dist
yarn build

​
Electron Won’t Start

# Rebuild native modules
cd app && yarn add electron@latest
cd .. && yarn build

​
Getting Help

Ready to dive deeper? Continue to Architecture to understand the codebase structure.

Build docs developers (and LLMs) love

Get started for freeTalk to us