Mocklane

Generate, edit, and serve mock HTTP responses with browser-local AI.

Mocklane turns a pasted data model and a plain-language request into a structured JSON HTTP response. Its CLI opens the browser workspace, serves generated mocks from a local API, and can proxy every unmatched request to an existing backend.

Features

• Generates complete HTTP response objects from models and prompts
• Runs generation locally with Transformers.js, WebLLM, or native browser AI
• Accepts TypeScript, Python/Pydantic, Go, Java, Prisma, SQL, OpenAPI/JSON schemas, and example JSON
• Validates edited output before saving it
• Copies and downloads generated JSON
• Serves mocks from localhost:4000
• Proxies unmatched requests to an optional upstream API
• Handles mock CORS headers and preflight requests
• Stores models in the browser cache after the first download
• Keeps mock data in memory and binds its servers to the local machine

Requirements

• Node.js 20 or newer
• A modern browser with WebGPU for Transformers.js and WebLLM
• Enough browser storage and memory for the selected local model
• pnpm 9 when installing from GitHub source

Native Browser AI is shown only when the browser exposes the LanguageModel API. The first Transformers.js or WebLLM load downloads model assets; later loads can reuse the browser cache.

Installation

Choose either npm or the GitHub source repository. Both launch the same mocklane CLI.

Option 1: npm

Run Mocklane once with npx:

npx @mocklane/core

Or install the package globally and run the installed mocklane command:

npm install --global @mocklane/core
mocklane

Option 2: GitHub

Clone the source, install dependencies, and launch the locally built CLI:

git clone https://github.com/aasispaudel/Mocklane.git
cd Mocklane
pnpm install
pnpm mocklane:build

Quick Start

Mocklane starts two local servers and opens the browser workspace automatically:

Mocklane UI:      http://localhost:4001
Mock API proxy:   http://localhost:4000
Upstream server:  none (standalone mode)

If the default ports are busy, Mocklane automatically tries the next local pair, such as 4002/4003, then 4004/4005.

In the browser:

1. Select an AI provider and model.
2. Load the model when the provider requires it.
3. Paste or edit the data structure under Model / Structure.
4. Describe the endpoint and response under Prompt.
5. Select Generate.
6. Review or edit the generated HTTP JSON.
7. Enter the endpoint path and select Mock API.

Call the active mock from any local client:

curl http://localhost:4000/api/products

Select Unmock API to remove it, or press Ctrl+C in the terminal to stop Mocklane.

Generated Response Format

Mocklane generates a JSON object containing the complete HTTP response definition:

{
  "method": "GET",
  "path": "/api/products",
  "status": 200,
  "headers": {
    "content-type": "application/json"
  },
  "body": [
    {
      "id": "1",
      "name": "Example product"
    }
  ]
}

The local mock server returns the value of body with the configured status and headers. Before registering the mock, the endpoint path can be changed in the field below the JSON output.

AI Providers

Transformers.js

The default provider uses WebGPU through Transformers.js. Available models are:

• onnx-community/Qwen3-0.6B-ONNX using q4f16
• onnx-community/gemma-3-1b-it-ONNX-GQA using q4

Mocklane displays model download progress and identifies whether the model is loading for the first time or from the browser cache.

WebLLM

WebLLM uses:

Qwen2.5-0.5B-Instruct-q4f16_1-MLC

The model runs through WebGPU and must be loaded before generation.

Native Browser AI

When the browser provides window.LanguageModel or the legacy window.ai.languageModel, Mocklane can generate with the browser's native Gemini Nano runtime. Availability and model download behavior are controlled by the browser.

Mocklane does not send prompts to a hosted inference API. Model files may be downloaded from their model providers during initial setup, but response generation happens in the browser.

Editing Output

The output toolbar supports:

• Edit: opens the generated response in the JSON editor
• Save: parses and formats the edited JSON
• Cancel: discards the current edits
• Copy: copies the response to the clipboard
• Download: saves the response as a .json file

Invalid JSON cannot be saved. Mocklane displays the parser error in the editor so the response can be corrected without losing the draft.

Standalone Mock Server

Standalone mode is the default:

npx @mocklane/core

Registered routes return their configured mock responses. Unmatched routes return 404:

{
  "error": "No Mocklane mock matches this route.",
  "method": "GET",
  "path": "/api/unknown"
}

Mocks are matched by HTTP method and exact pathname. Query strings do not affect matching. Mock state is kept in memory and is cleared when the CLI exits.

Proxy Mode

Use proxy mode when an application already has a backend and only selected routes should be mocked:

npx @mocklane/core --target http://localhost:8000

Point the application at http://localhost:4000 instead of the upstream server:

Application -> localhost:4000 -> Mocklane -> localhost:8000

• A matching method and pathname returns the registered mock.
• An unmatched request is forwarded to the upstream server.
• Request methods, headers, bodies, and query strings are forwarded.
• Upstream status codes, headers, and response bodies are passed back to the client.

For example, with only GET /api/products mocked:

curl http://localhost:4000/api/products
curl http://localhost:4000/api/users

The first request uses the mock. The second request is forwarded to http://localhost:8000/api/users.

CLI Reference

Usage:
  mocklane [options]

Options:
  --target <url>       Optional upstream API URL for unmatched routes
  --proxy-port <port>  Mock/proxy port (default: 4000)
  --ui-port <port>     Mocklane UI port (default: 4001)
  -h, --help           Show CLI help

Custom ports

npx @mocklane/core --proxy-port 5000 --ui-port 5001

Proxy with custom ports

npx @mocklane/core \
  --target http://localhost:8000 \
  --proxy-port 5000 \
  --ui-port 5001

The proxy and UI ports must be different. Both servers bind to 127.0.0.1 and are not exposed to the local network. When custom ports are provided, Mocklane uses those exact ports.

Local Control API

The browser workspace registers mocks through a control API on the UI port.

Health

curl http://localhost:4001/__mocklane/health

{
  "ready": true,
  "proxyPort": 4000,
  "mocks": 0
}

List mocks

curl http://localhost:4001/__mocklane/mocks

Register a mock

Save a response definition as response.json, then run:

curl --request PUT \
  --header "content-type: application/json" \
  --data @response.json \
  http://localhost:4001/__mocklane/mocks

Remove a mock

curl --request DELETE \
  --header "content-type: application/json" \
  --data @response.json \
  http://localhost:4001/__mocklane/mocks

Control API request bodies are limited to 10 MB. A response definition must contain a method, a path beginning with /, an HTTP status from 100 to 599, and a headers object.

CORS Behavior

Mock responses include access-control-allow-origin: * unless the response already defines that header. An OPTIONS request containing access-control-request-method receives a 204 preflight response when Mocklane has a matching mock for that method and pathname.

Development

Clone the repository and install dependencies:

git clone https://github.com/aasispaudel/Mocklane.git
cd Mocklane
pnpm install

Start the React Router development server:

pnpm dev

The development UI runs at http://localhost:3010.

Run the source CLI

Build the browser UI before starting the TypeScript CLI:

pnpm build
pnpm mocklane

Run the compiled CLI and rebuild everything first:

pnpm mocklane:build

Validation

pnpm typecheck
pnpm test:cli
pnpm build:package

• typecheck generates React Router types and runs TypeScript validation.
• test:cli verifies UI serving, mock registration, standalone 404 responses, CORS preflight handling, and upstream proxying.
• build:package creates the production browser bundle and compiled CLI.

Architecture

app/
  components/                 Shared interface components
  routes/home.tsx             Main generator workspace
  styles/app.css              Application styles
cli/
  index.ts                    CLI entry point and argument parsing
  server.ts                   UI server, mock server, and upstream proxy
  mockRegistry.ts             In-memory method/path registry
  server.test.ts              CLI integration tests
src/
  ai/localModel.ts            WebLLM provider
  ai/transformersModel.ts     Transformers.js provider
  ai/nativeBrowserModel.ts    Native LanguageModel provider
  core/browserApiMock.ts      Browser-to-CLI mock registration
  core/generateMockResponse.ts Provider orchestration
  core/intent.ts              Input structure detection
  core/jsonUtils.ts           JSON extraction and formatting
  types/mockApi.ts            HTTP response types

The CLI serves the built SPA on the UI port and the mock/proxy server on the proxy port. The browser performs AI generation, then sends validated response definitions to the CLI control API. No Node.js AI runtime is required.

Operational Notes

• Local models can produce imperfect data. Review generated responses before using them in tests or demonstrations.
• Very large responses depend on model context limits, available GPU memory, and browser stability.
• Transformers.js and WebLLM are unavailable when WebGPU is unavailable.
• Native Browser AI depends on an experimental browser API and may not be present.
• Mocks are not persisted between CLI sessions.
• Mock matching is exact and does not interpret path parameters or wildcard routes.
• The proxy forwards credentials and authorization headers supplied by the client; use trusted upstream targets.

Contributing

Issues and pull requests are welcome at github.com/aasispaudel/Mocklane.

Before opening a pull request, run:

pnpm typecheck
pnpm test:cli
pnpm build:package

License

Mocklane is released under the MIT License.