5. No required environment variables for basic usage. The CLI accepts --port, --host, --errors, and --dynamic flags at runtime.

Public API

createInstance

import { createInstance } from '@stoplight/prism-http';
import type {
  IHttpConfig,
  IHttpProxyConfig,
  PrismHttpComponents,
  PickRequired,
} from '@stoplight/prism-http';

function createInstance(
  defaultConfig: IHttpConfig | IHttpProxyConfig,
  components: PickRequired<Partial<PrismHttpComponents>, 'logger'>
): PrismInstance; // IPrism<IHttpOperation, IHttpRequest, IHttpResponse, IHttpConfig>

Use createInstance to embed a fully configured Prism HTTP instance inside Node.js code. Pass a defaultConfig that controls mocking vs. forwarding behaviour and supply at minimum a logger (pino Logger). All other components (router, validator, mocker, forwarder) are defaulted automatically.

getHttpOperationsFromSpec

import { getHttpOperationsFromSpec } from '@stoplight/prism-http';

function getHttpOperationsFromSpec(
  specFilePathOrObject: string | Record<string, unknown>
): Promise<IHttpOperation[]>;

Loads an OpenAPI v2/v3 specification from a file path or an already-parsed object and returns the array of IHttpOperation objects that Prism uses internally for routing and mocking. Use this whenever you need to pre-parse a spec before passing it to a Prism instance or for static analysis.

createAndCallPrismInstanceWithSpec

import { createAndCallPrismInstanceWithSpec, PrismOkResult, PrismErrorResult } from '@stoplight/prism-http';

function createAndCallPrismInstanceWithSpec(
  spec: string | Record<string, unknown>,
  config: IHttpConfig,
  request: IHttpRequest
): Promise<PrismOkResult | PrismErrorResult>;

A convenience function that combines spec loading, instance creation, and a single HTTP request dispatch. Ideal for one-shot test assertions without managing instance lifecycle.

Working examples

Scenario - Embed a mock server in a Jest test

Start a Prism mock instance directly in-process against a local spec file, fire a request, and assert the mocked response without spawning a child process.

import pino from 'pino';
import { createInstance, getHttpOperationsFromSpec } from '@stoplight/prism-http';

async function runMockRequest() {
  const logger = pino({ level: 'silent' });
  const operations = await getHttpOperationsFromSpec('./openapi.yaml');

  const instance = createInstance(
    { isProxy: false, mock: { dynamic: false } },
    { logger }
  );

  await instance.load(operations);

  const response = await instance.process({
    method: 'get',
    url: { path: '/pets', query: {} },
    headers: { accept: 'application/json' },
  });

  console.log(response.status);   // e.g. 200
  console.log(response.body);     // mocked body from spec
}

runMockRequest();

Scenario - Validation proxy forwarding to a real backend

Wire Prism as a validation proxy that checks outbound requests and inbound responses against an OpenAPI spec, forwarding to an upstream server.

import pino from 'pino';
import { createInstance, getHttpOperationsFromSpec } from '@stoplight/prism-http';
import type { IHttpProxyConfig } from '@stoplight/prism-http';

async function runProxyRequest() {
  const logger = pino({ level: 'warn' });
  const operations = await getHttpOperationsFromSpec('./openapi.yaml');

  const config: IHttpProxyConfig = {
    isProxy: true,
    upstream: new URL('https://petstore.swagger.io/v2'),
    mock: { dynamic: false },
    validateRequest: true,
    validateResponse: true,
  };

  const instance = createInstance(config, { logger });
  await instance.load(operations);

  const response = await instance.process({
    method: 'post',
    url: { path: '/pets', query: {} },
    headers: { 'content-type': 'application/json' },
    body: { name: 'Fido' },
  });

  console.log(response.status, response.body);
}

runProxyRequest();

Scenario - Parse a spec and inspect operations statically

Use getHttpOperationsFromSpec as a standalone utility to list all routes defined in a spec without starting any server.

import { getHttpOperationsFromSpec } from '@stoplight/prism-http';

async function listRoutes(specPath: string) {
  const operations = await getHttpOperationsFromSpec(specPath);

  for (const op of operations) {
    console.log(`${op.method.toUpperCase()} ${op.path}`);
    if (op.responses.length) {
      console.log(
        '  responses:',
        op.responses.map(r => r.code).join(', ')
      );
    }
  }
}

listRoutes('./openapi.yaml');

File walkthrough

• cli/ - Defines the prism CLI binary. src/index.ts bootstraps yargs; src/commands/mock.ts and src/commands/proxy.ts implement the two subcommands; src/util/createServer.ts wires the HTTP server.
• core/ - Package-agnostic interfaces and the factory function that assembles any Prism instance from pluggable components (router, mocker, forwarder, validators). src/types.ts defines IPrismComponents, IPrismInput, IPrismDiagnostic.
• http/ - Full HTTP implementation. src/index.ts exports createInstance; src/mocker/ handles response selection and generation; src/forwarder/ implements proxying via node-fetch; src/router/ matches incoming requests to operations; src/validator/ validates inputs and outputs.
• http-server/ - Thin layer (Fastify or raw http) that binds a Prism instance to a TCP port, used by the CLI.
• tsconfig.build.json - Shared production TypeScript config; excludes test files.
• tsconfig.json - Dev TypeScript config with project references across all packages.

Common pitfalls and fixes

• Node.js version < 18.20.1: Prism uses built-in fetch-adjacent APIs and fails silently on older runtimes. Pin engines.node to >=18.20.1 in your package.json.
• ESM / CJS mismatch with fp-ts: Prism imports from fp-ts/function, fp-ts/Either, etc. (v2 tree-shakeable paths). If bundlers resolve the ESM build incorrectly, add "moduleResolution": "node16" or keep CJS output.
• @stoplight/types version mismatch: IHttpOperation, IHttpHeaderParam, and related types must come from the same @stoplight/types version used internally. Duplicate installs cause assignability errors. Use npm dedupe.
• pino logger required: Passing console as the logger will throw at runtime. Always construct a real pino logger (pino({ level: 'silent' }) for tests).
• Spec path resolution: getHttpOperationsFromSpec resolves relative paths from process.cwd(), not from the calling file. Pass path.resolve(__dirname, './spec.yaml') explicitly.
• dynamic: true increases latency: The dynamic payload generator runs JSON Schema faker on every request. In CI keep dynamic: false for deterministic snapshots.

Vibe-coding prompt template

I have dropped the Stoplight Prism source into `vendor/prism/` in my project.
The integration guide is in `vendor/prism/USAGE.md`.
The upstream package is `@stoplight/prism-http` (stoplightio_prism).

Please help me integrate Prism into my existing Express/TypeScript project step-by-step:

1. Read `vendor/prism/USAGE.md` fully before writing any code.
2. Add the required tsconfig path aliases so `@stoplight/prism-core` and
   `@stoplight/prism-http` resolve to `vendor/prism/core/src` and
   `vendor/prism/http/src` respectively.
3. Install all runtime dependencies listed in the "Required dependencies" section.
4. Create a `src/mockServer.ts` module that:
   - Calls `getHttpOperationsFromSpec` with my local `openapi.yaml`
   - Calls `createInstance` with `{ isProxy: false, mock: { dynamic: false } }`
   - Exports a `processRequest(req)` helper that delegates to `instance.process`
5. Wire `src/mockServer.ts` into my existing Express app as middleware on `/mock/*`.
6. Add a Jest test that imports `createAndCallPrismInstanceWithSpec` and
   asserts a 200 response for a known GET route.

Only use symbols that appear in `vendor/prism/USAGE.md`. Do not install the
npm package; use the local source exclusively.

License and credit

The source is licensed under the Apache 2.0 license (see source/cli/LICENSE, source/core/LICENSE, source/http/LICENSE). Original project: Stoplight Prism by Stoplight, Inc.

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.