MockForge Local ⚡

Production-Ready Desktop Mock REST API Suite
Build, configure, test, save, and run local mock REST APIs with a native desktop GUI or globally installable CLI.

🚀 Quick Start: How to Run

1. Launch the Native Desktop Window (Fastest)

Ensure dependencies and production assets are built:

# In the project directory:
npm start

This immediately opens the native Electron desktop application window. No browser is required.

2. Run Globally via NPM CLI

You can install MockForge globally so the mockforge and mockforge-local commands are available from any terminal or directory:

# Link the local package globally:
npm link

# Or install globally from local directory:
npm install -g .

Now you can launch the native desktop application from anywhere:

# Opens the native desktop application window:
mockforge

# Or use the alternate alias:
mockforge-local

3. CLI Command Options

MockForge supports CLI flags to configure ports, projects, or run without a window:

| Flag | Description | Example | | :--- | :--- | :--- | | -p, --port <number> | Set mock server listening port | mockforge --port 8080 | | --project <name> | Open specific project by name | mockforge --project "Storefront & Auth API" | | --open-last-project | Automatically reload last active project | mockforge --open-last-project | | --headless | Run mock server directly in the terminal (no GUI) | mockforge --headless --port 3000 | | -v, --version | Display installed version | mockforge --version | | -h, --help | Display CLI help menu | mockforge --help |

Headless Mode Example (Terminal Only)

mockforge --headless --port 4000

4. Development Mode (Live Reloading)

To develop with Vite hot module replacement (HMR):

Terminal 1 (Vite Dev Server):

npm run dev:renderer

Terminal 2 (Electron with Dev Flags):

npm run dev:electron

To re-build the production UI bundle:

npm run build

5. Automated Tests

Run the Vitest test suite covering unit schemas, template parsing, rule matching, in-memory stateful store, persistence, and real HTTP server integration:

npm test

🛠️ Key Features

• Native Electron Desktop App: Secure process architecture (contextIsolation: true, sandboxed IPC bridge).
• Interactive UI: Dark mode by default (gray-900 / 950 surfaces), comfortable light theme toggle, responsive layout.
• Dynamic Route Engine:
  • Full HTTP method support: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS.
  • Dynamic path parameters (e.g. /api/products/:id) and query parameters (?page=2).
  • Safe response templating ({{params.id}}, {{query.filter}}, {{body.field}}, {{timestamp}}, {{uuid}}, {{random.number(1,100)}}).
  • Conditional response rules (override status code and payload when query, header, or body conditions match).
  • Simulated latency delays (ms).
  • CORS and preflight OPTIONS handling.
• Built-in API Request Tester: Test mock endpoints directly inside the desktop window with headers, query parameters, payload editor, and copyable cURL commands.
• Real-Time Server Console: Live traffic inspection with sanitized authentication redaction (authorization tokens and secrets are redacted from logs).
• Simulated Stateful CRUD Store: Prototyping mode for in-memory resources (POST items, GET by ID, PUT/PATCH, and DELETE).
• Safe Persistence: Configuration stored in ~/.mockforge-local/data.json with atomic writes and automatic corrupted-file recovery.
• Import & Export: Export and import projects and environments as portable JSON files.

📦 Building Standalone Desktop Installers

To create standalone desktop distributions for Windows, macOS, or Linux using electron-builder:

# Package directory without creating installer:
npm run pack

# Build production installers (NSIS for Windows, DMG for macOS, AppImage for Linux):
npm run dist

📄 License

MIT © 2026 MockForge Team