Contributing to MeshMonitor

July 28, 2026 · View on GitHub

Thank you for your interest in contributing to MeshMonitor! This guide will help you get started with development and ensure your contributions meet our quality standards.

🚀 Getting Started

System Tests (End-to-End)

We also have a comprehensive system test suite that verifies the full deployment using Docker.

# Run the full system test suite (builds fresh Docker image)
./tests/system-tests.sh

# Run tests against your running dev environment (Fast!)
./tests/dev-test.sh

# Run tests against a specific Meshtastic node
TEST_NODE_IP=192.168.1.50 ./tests/system-tests.sh

Running Tests Locally

Before submitting a PR, ensure all tests pass:

# Run all tests
npm run test:run

# Run tests in watch mode during development
npm run test

# Run tests with coverage report
npm run test:coverage

# Run specific test files
npm run test:run src/services/database.test.ts

# Run tests with UI (great for debugging)
npm run test:ui

Test Categories

Unit Tests: Test individual functions and components
- Database operations (src/services/database.test.ts)
- React components (src/components/*.test.tsx)
- API endpoints (src/server/*.test.ts)
Type Checking: Ensure TypeScript types are correct
```
npm run typecheck
```
Linting: Follow our code style guidelines
```
npm run lint
```

Writing Tests

When adding new features, include appropriate tests:

// Example test structure
describe('YourFeature', () => {
  it('should handle normal cases', () => {
    // Test implementation
  });

  it('should handle edge cases', () => {
    // Test edge cases
  });

  it('should handle errors gracefully', () => {
    // Test error handling
  });
});

🔄 Pull Request Process

Before Submitting

Ensure all tests pass:

npm run test:run
npm run typecheck
npm run lint

Update documentation if you've changed APIs or added features
Test your changes with a real Meshtastic node if possible
Build the project to ensure it compiles:
```
npm run build
npm run build:server
```

PR Guidelines

Create a feature branch:

git checkout -b feature/your-feature-name
# or
git checkout -b fix/issue-description

refactor: Code refactoring
test: Test additions or changes
chore: Maintenance tasks

🤖 Automated Checks

Interface icons

Use the shared UiIcon component and a semantic registry name for app-owned interface icons. Do not hardcode emoji, checkmarks, arrows, stars, or similar Unicode glyphs in components or translated UI copy.
Use BrandIcon for supported brands. Brand SVG data comes from Simple Icons and must record its source and version; do not substitute a lookalike emoji.
User-authored content and protocol/domain data (for example messages, reactions, waypoint symbols, and script-selected emoji) remain data, not interface icons. Any new source-level exception needs an issue-referenced ESLint disable explaining why it is content rather than UI.
npm run lint:ci blocks new hardcoded UI glyphs. Existing violations are ratcheted while they are migrated to UiIcon.

Our CI/CD pipeline runs automatically on all PRs:

GitHub Actions Workflows

CI (ci.yml)
- Runs on every PR, whatever branch it targets
- Lint ratchet, type checking, and the full unit suite on Node 22 / 24 / 25 (against real PostgreSQL and MySQL service containers)
- Frontend, server, documentation, and Docker build validation
- Security scanning
A separate pr-tests.yml used to run alongside this one, but every job in it was a strict subset of a job here — it re-ran the same suite a fourth time on Node 24 and then re-ran parts of it again. Its one unique job, the VitePress documentation build, now lives in ci.yml.
Release Pipeline (release.yml)
- Runs on version tags
- Full test suite
- Multi-platform Docker builds
- Automated release notes

Status Checks

All PRs must pass these checks:

✅ All tests passing
✅ TypeScript compilation successful
✅ Linter warnings resolved (or documented)
✅ Docker build successful
✅ Security scan clean

📁 Project Structure

meshmonitor/
├── src/
│   ├── components/      # React components
│   ├── server/          # Express backend
│   ├── services/        # Shared services
│   └── test/           # Test utilities
├── docs/               # Documentation
│   └── architecture/   # System architecture docs
├── public/            # Static assets
├── .github/          # GitHub Actions workflows
└── tests/           # Additional test files

🐛 Reporting Issues

When reporting issues, please include:

Environment details:
- Node.js version
- Operating system
- Browser (for frontend issues)
- Meshtastic firmware version
Steps to reproduce
Expected vs actual behavior
Error messages and logs
Screenshots (if applicable)

💡 Feature Requests

We welcome feature requests! Please:

Check existing issues first
Describe the use case
Explain the expected behavior
Consider implementation complexity

🏗️ Development Tips

Hot Reloading

Both frontend and backend support hot reloading in development mode.

Database Development

# Reset database during development
rm data/meshmonitor.db
# The database will be recreated on next start

Docker Development

# Build and test Docker image locally
docker build -t meshmonitor:local .
docker run -p 8080:3001 meshmonitor:local

Debugging

Frontend debugging: Use React Developer Tools
Backend debugging: Use Node.js inspector
```
node --inspect dist/server/server.js
```
Test debugging: Use Vitest UI
```
npm run test:ui
```

📝 Code Style

We use ESLint and TypeScript for code quality:

Use TypeScript for all new code
Follow existing patterns in the codebase
Add types for all function parameters and returns
Use meaningful variable names
Add comments for complex logic
Keep functions small and focused

🙏 Thank You!

Your contributions make MeshMonitor better for everyone. We appreciate your time and effort in improving this project!

If you have questions, feel free to:

Open an issue for discussion
Ask in pull request comments
Refer to existing code for patterns

Happy coding! 🚀