@draganfilipovic/mocker

Mocker Server

Simple Node.js mock server with a beautiful GUI for managing API endpoints and responses. Perfect for development, testing, and prototyping.

Features

• 🎨 Beautiful GUI - Intuitive web interface for managing endpoints
• 🚀 Easy Setup - Start mocking APIs in seconds
• 📁 File-based Storage - All data stored in organized JSON files
• 🔄 Real-time Testing - Test endpoints directly from the GUI
• 📊 Status Code Management - Pre-configured dropdown with common HTTP status codes
• 🎯 Path-based Organization - Automatic folder structure based on API paths
• ✨ JSON Validation - Real-time validation with helpful error messages
• 🔒 Reserved Path Protection - Prevents conflicts with internal API routes
• 🌐 Dynamic Paths - Support for variable URL segments like /users/{id}/posts

Installation

Global Installation (Recommended)

npm install -g @draganfilipovic/mocker

Local Installation

npm install @draganfilipovic/mocker

Quick Start

Using the CLI

# Start the server (uses ./mocks directory by default)
mocker

# Or specify a custom directory
MOCKS_DIR=/path/to/your/mocks mocker

# Or set a custom port
PORT=8080 mocker

Using as a Module

const mocker = require('@draganfilipovic/mocker');

// Start the server programmatically
mocker.start({
  port: 3000,
  mocksDir: './custom-mocks'
});

Configuration

Command Line Options

mocker [options]

Options:
  -p, --port <number>     Port to run the server on (default: 3000)
  -d, --mocks-dir <path>  Directory to store mock data (default: ./mocks)
  -h, --help              Show help message

Environment Variables

# Set port and mocks directory
PORT=8080 MOCKS_DIR=./api-mocks mocker

Examples

# Default settings
mocker

# Custom port
mocker --port 8080
# or
PORT=8080 mocker

# Custom mocks directory
mocker --mocks-dir ./api-mocks
# or
MOCKS_DIR=./api-mocks mocker

# Both custom port and directory
mocker --port 8080 --mocks-dir ./api-mocks
# or
PORT=8080 MOCKS_DIR=./api-mocks mocker

Directory Structure

The server automatically creates the following structure:

your-project/
├── mocks/                    # Default mocks directory
│   └── endpoints/
│       ├── api/              # Static paths
│       │   └── users/
│       │       ├── get.200.Success.json
│       │       ├── get.404.Error.json
│       │       └── get.selected.json
│       └── users/             # Dynamic paths
│           └── __id__/        # {id} becomes __id__
│               └── posts/
│                   ├── get.200.Success.json
│                   └── get.selected.json
└── your-other-files...

API Endpoints

Mock API

• ALL /your-endpoint-path - Returns the selected mock response
• ALL /users/{id}/posts - Dynamic paths with variable segments

GUI Features

Endpoint Management

• Create endpoints with path and HTTP method
• Support for dynamic paths with {param} syntax
• Visual status indicators for each response
• Dynamic path indicators (🔄 icon and "Dynamic" badge)
• One-click endpoint testing
• Delete endpoints with confirmation

Response Management

• Add custom responses with JSON bodies
• Pre-configured status code dropdown (20 most common codes)
• Real-time JSON validation
• Select active response per endpoint
• Edit and delete responses

Testing

• Click endpoint URLs to open in new tab
• Built-in test button with response preview
• Real-time response display
• Dynamic path testing with example URLs
• Cache-busting headers prevent stale responses

File Format

Response Files

Files are named: {method}.{statusCode}.{name}.json

Example: get.200.Success.json

{
  "message": "User retrieved successfully",
  "data": {
    "id": 1,
    "name": "John Doe",
    "email": "[e-mail]"
  }
}

Selection Files

Files are named: {method}.selected.json

Example: get.selected.json

{
  "selectedResponseName": "Success"
}

Dynamic Paths

Create flexible mock endpoints that handle variable URL segments using {param} syntax.

Examples

Basic Dynamic Path:

/users/{id}

Matches: /users/123, /users/456, /users/abc

Multiple Parameters:

/users/{userId}/posts/{postId}

Matches: /users/123/posts/456, /users/john/posts/my-post

Real-world Example:

/users/auth/email-exists/{email}

Matches: /users/auth/email-exists/[e-mail]

How It Works

• Create Dynamic Endpoint: Enter path like /users/{id}/posts in the GUI
• Visual Indicators: Dynamic paths show 🔄 icon and "Dynamic" badge
• File Storage: {param} becomes __param__ in directory structure
• Path Matching: Server matches any value for {param} segments
• Same Response: All requests return the same mock response

Testing Dynamic Endpoints

In the GUI:

• Click "Test" button - automatically uses example values
• View both original pattern and example URL

With curl:

curl http://localhost:3000/users/123/posts
curl http://localhost:3000/users/456/posts

With JavaScript:

const response = await fetch('/users/123/posts');
const data = await response.json();

File Structure for Dynamic Paths

Path: /users/{id}/posts
Files: mocks/endpoints/users/__id__/posts/
  - get.200.Success.json
  - get.500.Error.json
  - get.selected.json

Development

Running from Source

git clone https://github.com/easingthemes/mocker.git
cd mocker
npm install
npm start

Building

npm run build

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• 🐛 Issues: GitHub Issues

Changelog

v1.1.0

• 🌐 Dynamic Paths - Support for variable URL segments like /users/{id}/posts
• 🔄 Visual Indicators - Dynamic path icons and badges in the GUI
• 🧪 Smart Testing - Automatic test value substitution for dynamic paths
• 🚫 Cache Prevention - No-cache headers prevent stale responses
• 📁 Enhanced File Structure - Automatic {param} to __param__ conversion

v1.0.0

• Initial release
• GUI for endpoint management
• File-based storage
• Real-time JSON validation
• Status code dropdown
• Path-based organization
• Reserved path protection

Made with ❤️ for developers who love clean, efficient mock servers.

(Actually made with Cursor AI)