# @simulacrum/foundation-simulator

> Base simulator to build simulators for integration testing.

Latest version **0.8.0** (published 2026-06-16) · MIT license · 0 weekly downloads

## Install

```sh
npm install @simulacrum/foundation-simulator
pnpm add @simulacrum/foundation-simulator
yarn add @simulacrum/foundation-simulator
bun add @simulacrum/foundation-simulator
```

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.8.0 |
| Published | 2026-06-16 |
| First published | 2024-06-05 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM |
| Dependencies | 8 |
| Unpacked size | 79 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 117 |
| Author | Frontside Engineering |
| Maintainers | frontsidejack |
| Keywords | emulation, integration testing, mock, mocking, simulation |

## Links

- npm: https://www.npmjs.com/package/@simulacrum/foundation-simulator
- Repository: https://github.com/thefrontside/simulacrum
- Homepage: https://github.com/thefrontside/simulacrum#readme
- Issues: https://github.com/thefrontside/simulacrum/issues
- npm.io page: https://npm.io/package/@simulacrum/foundation-simulator

## Dependencies (8)

- [cors](https://npm.io/package/cors.md) ^2.8.6
- [defu](https://npm.io/package/defu.md) ^6.1.7
- [fdir](https://npm.io/package/fdir.md) ^6.5.0
- [starfx](https://npm.io/package/starfx.md) ^0.16.1
- [express](https://npm.io/package/express.md) ^5.2.1
- [ajv-formats](https://npm.io/package/ajv-formats.md) ^3.0.1
- [openapi-backend](https://npm.io/package/openapi-backend.md) ^5.17.0
- [http-proxy-middleware](https://npm.io/package/http-proxy-middleware.md) ^3.0.5

## Alternatives

- [duck](https://npm.io/package/duck.md) — 4.2M weekly downloads
- [ava](https://npm.io/package/ava.md) — 560.2K weekly downloads
- [storybook-addon-module-mock](https://npm.io/package/storybook-addon-module-mock.md) — 71.7K weekly downloads
- [vest](https://npm.io/package/vest.md) — 50.1K weekly downloads
- [@ethereum-waffle/mock-contract](https://npm.io/package/@ethereum-waffle/mock-contract.md) — 40.0K weekly downloads

## Recent versions

- 0.8.0 (latest) — 2026-06-16
- 0.1.0-foundation-simulator-route-list.ab1c616 (preview) — 2024-08-13
- 0.7.0 — 2026-06-10
- 0.6.1 — 2026-02-18
- 0.6.0 — 2025-10-15
- 0.5.1 — 2025-09-26
- 0.5.0 — 2025-09-09
- 0.4.1 — 2025-05-05
- 0.4.0 — 2025-03-27
- 0.3.1 — 2025-02-20
- 0.3.0 — 2025-02-04
- 0.2.1 — 2025-01-17
- 0.2.0 — 2024-09-16
- 0.1.0-foundation-simulator-route-list.dcbcfa5 — 2024-08-12
- 0.1.0-foundation-simulator-route-list.a78a0ea — 2024-07-22
- … 13 more at https://npm.io/package/@simulacrum/foundation-simulator/versions

## README

# `@simulacrum/foundation-simulator`

This simulator gives some base level functionality which is likely to be used in every simulator. It is built with the expectation to be extended and meet your needs for any custom simulators as well. If you need assistance in building a simulator for your needs, please reach out to [Frontside for this or any other consulting services](https://frontside.com/).

Use this base with an OpenAPI specification or other API contract enforcement mechanisms to quickly wire up test data that feels real. Implement APIs that feel real _including_ the handling features such as webhooks, WebSockets, GraphQL, and/or Authentication/Authorization. See the other simulators in these repos as additional examples on how you may implement a simulator.

## Quick Start

Get started with some JSON file, and incrementally build up as needs arise. Start with:

```shell
npm install -D @simulacrum/foundation-simulator
```

Then drop this in a file, e.g. `start.js`:

```js
import { startFoundationSimulationServer } from "@simulacrum/foundation-simulator";

await startFoundationSimulationServer({
  port: 9090,
  serveJsonFiles: `${import.meta.dirname}/jsonFiles`,
});
```

And then run it with Node, et. al.:

```shell
node ./start.js
```

> [!TIP]
> The `node` CLI now has a `--watch` or `--watch-path` arg. Want your simulator to automatically restart? Run it something like this `node --watch-path=./simulator ./simulator/start.js` (adjust for your folder paths).

Want to write in TypeScript? We recommend using `tsx` and running by:

```shell
node --import tsx ./start.ts
```

## Extending The Simulator Data

This is a base simulator which wires together a few libraries to create a foundation where we may incrementally improve and make the simulating an endpoint more dynamic. It uses the following libraries which you may also refer to their docs as required.

- [express](https://expressjs.com/) for API route handling
- [openapi-backend](https://openapistack.co/docs/openapi-backend/intro/) to bootstrap and ensure the supplied OpenAPI specification's contract
- [starfx](https://starfx.bower.sh/) for handling the simulation state and side-effects (such as firing off webhooks and inter-simulation communication)
  - [effection](https://frontside.com/effection) used internally in starfx to handle events, side-effects and communication through structured concurrency

The foundation simulator includes a base route at `localhost:<port>` which notes all of the routes and a simple log of requests.

See the `./example` and `./tests` folders for integrated examples along with the API reference below. Additionally, other simulators within the monorepo and `@simulacrum` namespace are being built atop this foundation.

## API Reference

### `port`

Pass a port number that may be used instead of the default, `9000`.

### `serveJsonFiles`

This takes a path pointing to a directory of JSON files. It is the quickest method to get started and will establish routes for each JSON file based on the directory and filename. The primary use case and API method is `GET` requests.

### `openapi`

If the API that is being simulated maintains an OpenAPI 3.0 specification, the simulator can use that to define routes, provide mock data (contained within the specification), validate payloads and responses, and establish handlers for custom route handling.

### `extendRouter`

For custom routes and responses, this API uses `express` directly. It supports any API method that `express` supports: `GET`, `POST`, `DELETE`, etc.

### `extendStore`

To further customize the data and in-memory, immutable store, this API supports extending the internal `immer` store. This API relies on `starfx` heavily, and those docs may also serve as an appropriate reference.

The `openpi` and `extendRouter` APIs both include the `simulationStore` passed in as an arguement to provide an in-memory, mutable store.

### `delayResponses`

This API wraps each API and allows configuration to delay a response. The improves the "real" feel of the simulator that your frontend may load and react more closely to the deployed state.

We have implemented the following in simulators to set a default, but dynamically increase the delay in for testing specific cases.

```js
import { createFoundationSimulationServer } from "@simulacrum/foundation-simulator";

const slowResponse = process.env?.SLOW_RESPONSE
  ? process.env.SLOW_RESPONSE === "true"
    ? 800
    : parseInt(process.env.SLOW_RESPONSE, 10)
  : 0;

export const simulation = createFoundationSimulationServer({
  port: 9999,
  delayResponses: {
    minimum: 50 + slowResponse,
    maximum: 1000 + slowResponse * 5,
  },
});
```

---
_Source: https://npm.io/package/@simulacrum/foundation-simulator · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._