Getting Started

Set up your development environment and start contributing to MQTT Explorer

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:

Development Mode

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:

Development Mode

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

Command	Description
yarn dev	Start Electron app in development mode
yarn dev:server	Start browser mode with hot reload
yarn dev:app	Run only the frontend dev server
yarn dev:electron	Run only Electron (after building)

Building

Command	Description
yarn build	Build desktop application
yarn build:server	Build browser mode for production
yarn start	Start built Electron app
yarn start:server	Start built Node.js server

Testing

Command	Description
yarn test	Run all unit tests
yarn test:app	Run frontend tests
yarn test:backend	Run backend tests
yarn test:ui	Run 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 (Recommended)

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

• Issues: github.com/thomasnordquist/mqtt-explorer/issues
• Discussions: GitHub Discussions
• Documentation: mqtt-explorer.com

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