Public API

MockServer (commons-server)

import { MockServer } from '@mockoon/commons-server';

class MockServer {
  constructor(
    environment: Environment,
    options?: { enableRandomLatency?: boolean }
  );
  start(): void;
  stop(): Promise<void>;
}

The core server class. Instantiate with a Mockoon Environment object (built via generateEnvironment or loaded from a JSON file), call start() to bind the HTTP listener, and stop() to tear it down. Use this whenever you need an in-process mock server.

generateEnvironment (commons)

import { generateEnvironment } from '@mockoon/commons';

function generateEnvironment(): Environment;

Returns a fully-typed Environment object with sensible defaults (port 3000, empty routes array, UUID-assigned uuid). Use it as the starting point before pushing custom routes via addRoute or similar mutators.

migrate (commons)

import { migrate } from '@mockoon/commons';

function migrate(environment: Environment): Environment;

Applies all pending schema migrations to an Environment loaded from an older Mockoon data file. Always call this before passing a user-supplied JSON file to MockServer to avoid runtime validation errors caused by stale schemas.

run (cli)

import { run } from '@oclif/core';

// Re-exported by cli/src/index.ts

Invokes the Mockoon CLI programmatically. Pass process.argv or a custom argv array. Use this if you want to spin up a mock from the command line inside a Node.js script or test setup without spawning a child process.

Working examples

Scenario - In-process mock server for integration tests

Start a Mockoon mock server inside a Jest/Vitest test suite without any CLI or file system overhead.

import { generateEnvironment, migrate } from '@mockoon/commons';
import { MockServer } from '@mockoon/commons-server';

async function startMockServer(): Promise<MockServer> {
  const env = generateEnvironment();
  env.port = 3100;
  env.name = 'test-mock';

  // Add a simple GET /ping route
  env.routes.push({
    uuid: 'route-uuid-001',
    type: 'http',
    method: 'get',
    endpoint: 'ping',
    responses: [
      {
        uuid: 'response-uuid-001',
        statusCode: 200,
        label: 'OK',
        headers: [{ key: 'Content-Type', value: 'application/json' }],
        body: '{"status":"ok"}',
        rules: [],
        rulesOperator: 'OR',
        disableTemplating: false,
        fallbackTo404: false,
        default: true,
        crudKey: 'id'
      }
    ],
    enabled: true,
    responseMode: null
  } as any);

  const migratedEnv = migrate(env);
  const server = new MockServer(migratedEnv);
  server.start();
  return server;
}

// In your test
const server = await startMockServer();
// ... run tests against http://localhost:3100
await server.stop();

Scenario - Migrate a legacy Mockoon environment file

Load an environment from disk that was created with an older Mockoon version and update it before use.

import * as fs from 'fs';
import { migrate, Environment } from '@mockoon/commons';
import { MockServer } from '@mockoon/commons-server';

function loadAndMigrate(filePath: string): Environment {
  const raw = fs.readFileSync(filePath, 'utf-8');
  const env: Environment = JSON.parse(raw);
  return migrate(env);
}

const env = loadAndMigrate('./mocks/my-api.json');
const server = new MockServer(env);
server.start();
console.log(`Mock server running on port ${env.port}`);

Scenario - Use cloud models for sync payload typing

Type-check a sync payload received from Mockoon Cloud using the exported model interfaces.

import type { SyncModel, TeamModel, UserModel } from '@mockoon/cloud';

function handleSyncPayload(payload: unknown): void {
  const sync = payload as SyncModel;
  const user: UserModel = sync.user;
  const team: TeamModel = sync.team;

  console.log(`Syncing as ${user.email} in team ${team.name}`);
}

File walkthrough

• source/app/ - Electron shell plus Angular renderer; contains main.ts that bootstraps Firebase auth and the Angular app. Not intended for programmatic import.
• source/app/build-configs/ - electron-builder config files for Windows, macOS, and Linux packaging targets.
• source/app/build-res/ - Application icons and Windows Appx tile assets.
• source/app/scripts/ - One-off maintenance scripts (AUR version bump, test migration helpers, macOS notarization).
• source/cli/src/index.ts - Single re-export of run from @oclif/core; the CLI package entry point.
• source/cloud/src/index.ts - Barrel export of all cloud-side TypeScript models (sync, deploy, plans, teams, templates, user).
• source/commons/src/index.ts - Barrel export of the entire shared library: constants, enums, migrations, OpenAPI converter, schema builder, and all data models.
• source/commons-server/src/index.ts - Barrel export of the server runtime: MockServer, Faker helpers, logger, template parser, event listeners, and server utilities.
• source/serverless/ - Adapter package that wraps MockServer for use as a cloud function handler (AWS Lambda, GCP, Firebase).

Common pitfalls and fixes

• Stale environment JSON crashes the server: always call migrate(env) before passing any file-loaded environment to MockServer; older files lack required fields.
• Port collision in parallel tests: set a unique env.port per test worker; Mockoon does not auto-assign free ports.
• ESM/CJS interop with @oclif/core: the CLI package targets CommonJS; if your project uses "type": "module" in package.json, import cli/src/index.ts via createRequire or set "module": "CommonJS" in the consuming tsconfig.
• Faker version mismatch: commons-server relies on @faker-js/faker v8+; installing v7 causes runtime failures due to renamed locale APIs.
• Desktop app imports bleed into server builds: source/app/src/ imports Angular and Electron globals (window.api); never import from app/ in a Node.js server context - restrict imports to commons, commons-server, cloud, and serverless.
• TypeScript strict null errors on route responses: Environment.routes[].responses requires all fields including crudKey and rulesOperator; use generateEnvironment + spread rather than hand-rolling objects.

Vibe-coding prompt template

I have a local copy of the Mockoon monorepo source at `vendor/mockoon/` (from the
upstream package `@mockoon/mockoon`). I also have `USAGE.md` in the project root
describing the real exports and setup.

Please help me integrate Mockoon into my Node.js/TypeScript project step by step:

1. Read `USAGE.md` for the exact import paths, real exported symbols, and tsconfig
   path aliases needed.
2. Update `tsconfig.json` with the path mappings for `@mockoon/commons`,
   `@mockoon/commons-server`, and any other sub-packages I need.
3. Create a `src/mock-server.ts` module that uses `generateEnvironment`, `migrate`,
   and `MockServer` from the source to start a configurable in-process mock server.
4. Add a helper that loads an existing Mockoon `.json` environment file from disk,
   migrates it, and starts the server.
5. Wire the mock server into my existing Express app's test setup so it starts
   before tests and stops after.
6. Flag any ESM/CJS conflicts or peer dependency issues found in `USAGE.md` as
   inline TODO comments.

Only use symbols documented in `USAGE.md`. Do not invent new exports.

License and credit

Mockoon is released under the MIT License (see source/app/LICENSE.md and individual package LICENSE files). Upstream repository: https://github.com/mockoon/mockoon. NPM package: @mockoon/mockoon.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.