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.

完整安装指南与集成提示词将在购买后解锁。