Getting started

Updated Oct 14, 2026

Pack the checkout and install its archive in an existing, empty Bun consumer project outside this checkout. Set SIMULACAT_CORE_CHECKOUT to the absolute path of this repository and SIMULACAT_CORE_CONSUMER to the absolute path of the consumer directory:

cd "$SIMULACAT_CORE_CHECKOUT"
bun install --frozen-lockfile
bun pm pack --filename "$SIMULACAT_CORE_CONSUMER/simulacat-core.tgz"
cd "$SIMULACAT_CORE_CONSUMER"
bun add ./simulacat-core.tgz

Packing runs the package's prepack script, which generates and builds the published files before Bun creates the archive. The consumer therefore resolves the package's built exports as a normal installation does.

Create simulation.ts with a small, explicit fixture:

import {simulation, type InitialState} from 'simulacat-core';

const initialState: InitialState = {
  users: [{login: 'octocat', organizations: ['acme']}],
  organizations: [{login: 'acme'}],
  repositories: [{owner: 'acme', name: 'awesome-repo'}],
  branches: [{owner: 'acme', repo: 'awesome-repo', name: 'main'}],
  blobs: []
};

const app = simulation({initialState});
const server = await app.listen(Number(process.env['PORT'] ?? 3300));
process.once('SIGINT', () => {void server.ensureClose();});
process.once('SIGTERM', () => {void server.ensureClose();});
console.log(`Listening on http://127.0.0.1:${server.port}`);

Start the simulator:

bun simulation.ts

Point a GitHub client at BASE_URL, which defaults to http://localhost:3300. A repository lookup reads the seeded store:

BASE_URL="${BASE_URL:-http://localhost:3300}"
curl -fsS "$BASE_URL/repos/acme/awesome-repo" -w '\n'
curl -fsS -H 'x-simulacat-actor: user:octocat' "$BASE_URL/user" -w '\n'

The first response describes acme/awesome-repo; the second selects the seeded octocat user. Stop the server with Ctrl+C when the session is finished.

For a checkout of this repository, run bun install and make build before starting node bin/start.cjs. The CLI uses port 3300 by default; set PORT to choose another port. The library example above supplies its own fixtures.