v0.0.1: vite-plugin-httptape — record/replay HTTP for Vite dev servers

[tibtof]

Problem

A TS developer with a new Vite project wants httptape as their dev backend proxy — record once, replay deterministically, edit JSON fixtures by hand. Today the only path (in httptape/httptape's examples/ts-frontend-first) is docker-compose with three services, requires Docker, and lives outside vite.config.ts. Not competitive with Vite's native DX.

User story

As a TS developer with a Vite project, I want to add httptape() to my vite.config.ts plugins array so that during vite dev my API calls are transparently proxied through httptape — recorded on first hit, replayed from local JSON fixtures on subsequent runs, with secrets redacted before they hit disk.

Public API (the whole surface for v0.0.1)

```ts
import { defineConfig } from 'vite'
import httptape from 'vite-plugin-httptape'

export default defineConfig({
plugins: [
httptape({
upstream: 'https://api.example.com', // required when mode: 'proxy'
fixtures: './mocks', // default: './mocks'
sanitize: './sanitize.json', // default: undefined (no sanitization)
mode: 'proxy', // 'proxy' | 'serve' — default: 'proxy'
route: '/api', // Vite server.proxy key — default: '/api'
port: 0, // 0 = pick free port — default: 0
}),
],
})
```

That's the whole surface — six options, CORS hardcoded on, no DSL.

What the plugin does

1. On `vite dev` start: spawn the httptape binary with the right CLI flags as a child process. If `port: 0`, picks a free port first via `net.createServer().listen(0)`.
2. Wires `vite.config.server.proxy[route]` so requests forward to the local httptape port.
3. Pipes httptape's stdout/stderr through Vite's logger with a `[httptape]` prefix.
4. On `vite dev` stop (SIGINT, file-triggered restart, etc.): graceful shutdown of the httptape child (SIGTERM with 3s grace, then SIGKILL).
5. `mode: 'serve'` swaps `httptape proxy` for `httptape serve` (no upstream needed) — frontend-first dev when there's no backend yet.

Out of scope for v0.0.1

• Recording control (always records on miss in proxy mode; no per-route opt-out)
• Hot-reload of `sanitize.json` (Vite restart picks it up)
• `freeze: true` / replay-only mode (punted to v0.0.2)
• Multiple upstreams (one plugin instance, one upstream)
• Testcontainers-style usage from Vitest tests (separate package later)
• Next.js / Remix / webpack integrations (separate packages later)

Acceptance criteria

• `pnpm i -D vite-plugin-httptape` on macOS arm64, macOS x64, Linux x64, Linux arm64, Windows x64 installs and the correct platform binary lands in `node_modules`
• Adding the plugin to `vite.config.ts` with only `upstream` set works against a real public API (e.g. `https://api.github.com\`) — first request records, second replays from `./mocks/`
• `mode: 'serve'` works against a `./mocks/` directory of hand-written fixtures (no upstream reachable)
• `Ctrl-C` on `vite dev` cleanly stops both Vite and the httptape child (no orphan processes)
• `httptape` logs prefix correctly in Vite's terminal output
• `examples/ts-frontend-first` in `httptape/httptape` converted to use the plugin — docker-compose deleted, one-line config in `vite.config.ts`, all behavior preserved (separate PR after this lands)
• README with copy-pasteable quick-start (under 30 lines of config)

Validation gate

v0.0.1 is not published to npm until the converted `examples/ts-frontend-first` demo runs cleanly and the dev-server lifecycle is verified by hand. Same gating pattern as `httptape-jvm`.

Status

READY_FOR_DEV — see first comment for ADR-1 (architectural design).

[tibtof]

ADR-1: Architectural design for v0.0.1

Date: 2026-05-25
Status: Accepted

Repo and tooling

• Monorepo: `pnpm` workspaces. Vite's own choice; current TS plugin standard; Dependabot supports pnpm-lock.yaml.
• TypeScript: strict, ESM-only (Vite is ESM-only). Dual exports (ESM + .d.ts).
• Node target: Node 20 LTS minimum (Vite 6+ requires it).
• License: Apache 2.0 (matches httptape core).
• Tests: Vitest. Unit + one integration test that spawns a real binary against an in-process upstream.
• Lint/format: ESLint flat config + Prettier.
• CI: GitHub Actions — typecheck, lint, vitest on Node 20 + 22, ubuntu + macos + windows.

Package layout

```
httptape-js/
├── package.json # private root, pnpm workspaces
├── pnpm-workspace.yaml
├── tsconfig.base.json
├── .github/workflows/{ci,release}.yml
└── packages/
├── vite-plugin-httptape/ # the plugin
│ ├── src/
│ │ ├── index.ts # default export: httptape(options)
│ │ ├── options.ts # HttptapeOptions type + validation
│ │ ├── binary.ts # resolveBinary() — runtime require.resolve
│ │ ├── port.ts # pickFreePort() helper
│ │ ├── process.ts # spawn/lifecycle wrapper
│ │ └── log.ts # logger prefix piping
│ ├── test/
│ │ ├── options.test.ts
│ │ ├── port.test.ts
│ │ └── integration.test.ts # spawns binary against http.createServer upstream
│ ├── package.json
│ └── README.md
└── binary-{darwin-arm64,darwin-x64,linux-x64,linux-arm64,win32-x64}/
├── package.json # name: @httptape/binary--
├── bin/httptape # the binary (populated by release workflow)
└── README.md # one-line note: "Platform-specific binary for vite-plugin-httptape; do not install directly."
```

Binary distribution

• Five platform packages: `@httptape/binary-darwin-arm64`, `@httptape/binary-darwin-x64`, `@httptape/binary-linux-x64`, `@httptape/binary-linux-arm64`, `@httptape/binary-win32-x64`.
• Declared as optionalDependencies of `vite-plugin-httptape`. npm/pnpm install whichever match the current platform.
• Runtime resolution: `require.resolve('@httptape/binary-' + process.platform + '-' + process.arch + '/bin/httptape')`. If it fails, throw a friendly error with troubleshooting steps.
• Same pattern as `esbuild`, `@swc/core`, `sharp`.

Vite plugin shape

```ts
export default function httptape(options: HttptapeOptions): Plugin {
let child: ChildProcess | undefined
let port: number

return {
name: 'vite-plugin-httptape',
apply: 'serve', // dev only
async config() {
port = options.port || await pickFreePort()
return {
server: {
proxy: {
[options.route ?? '/api']: {
target: `http://localhost:\${port}\`,
changeOrigin: true,
rewrite: (path) => path.replace(new RegExp(`^${options.route ?? '/api'}`), ''),
},
},
},
}
},
configureServer(server) {
child = spawnHttptape(options, port, server.config.logger)
server.httpServer?.on('close', () => killGracefully(child))
},
}
}
```

Process lifecycle

• Use `child_process.spawn` (not `exec` — we need a handle to kill).
• `detached: false`, `stdio: ['ignore', 'pipe', 'pipe']`.
• On Vite close: SIGTERM, wait up to 3s, then SIGKILL. Handle ECHILD gracefully.
• Register a top-level `process.on('exit', ...)` cleanup as belt-and-suspenders against orphan processes.

Free-port helper

```ts
import { createServer } from 'net'

export function pickFreePort(): Promise {
return new Promise((resolve, reject) => {
const srv = createServer()
srv.unref()
srv.on('error', reject)
srv.listen(0, () => {
const { port } = srv.address() as AddressInfo
srv.close(() => resolve(port))
})
})
}
```

(Tiny TOCTOU race between close and binary spawn — accepted; mitigation is binary retry on bind failure, but for v0.0.1 we don't bother.)

Logging

Pipe child stdout/stderr line-by-line to `server.config.logger.info(`[httptape] ${line}`)` and `.error(...)` respectively. Use `readline` for line buffering.

Release pipeline (decided: automated from day 1)

• `httptape/httptape` `release.yml` gains a final step: `repository_dispatch` to `httptape/httptape-js` with event type `httptape-release` and the released version as payload. (Separate PR back in `httptape/httptape` — see issue tracker.)
• `httptape-js/.github/workflows/release.yml` listens for that dispatch, runs a matrix of 5 platforms, cross-compiles the Go binary (checks out `httptape/httptape` at the released tag), packages each as an npm tarball, `npm publish`-es all 5 binary packages, then `npm publish`-es `vite-plugin-httptape` last with matching version.
• Requires:
  • A PAT or GitHub App token with `repo` scope stored as `HTTPTAPE_JS_DISPATCH_TOKEN` in `httptape/httptape` secrets.
  • An `NPM_TOKEN` secret in `httptape-js` with publish rights on `@httptape/*` and `vite-plugin-httptape` scopes/names.
• npm scopes to claim: `@httptape` (already used in JVM ecosystem terminology; verify availability).

Scope of dev's first PR

In scope:

• Monorepo bones (`package.json`, `pnpm-workspace.yaml`, `tsconfig.base.json`, `.gitignore`, `.editorconfig`)
• `packages/vite-plugin-httptape` with the locked API surface, all 6 modules above, unit tests
• Stub platform packages (`packages/binary-*`) with placeholder `bin/httptape` files plus a `.gitkeep` so the layout exists pre-publish
• README in the plugin package with copy-pasteable quickstart
• Root README explaining the monorepo
• CI workflow: typecheck + lint + vitest on Node 20 + 22, ubuntu/macos/windows
• Integration test that spawns a real httptape binary from $PATH if available, skips gracefully if not (so CI doesn't break before the release workflow exists)

Out of scope (separate PRs):

• The `release.yml` cross-repo automation (next task)
• npm scope reservation + first publish (manual step after the gate)
• Migration of `httptape/httptape examples/ts-frontend-first` (separate PR in the other repo)

Test strategy

• `options.test.ts`: defaulting, validation (e.g., `mode: 'proxy'` requires `upstream`)
• `port.test.ts`: returns a port; multiple calls return distinct ports
• `integration.test.ts`: spawns `httptape serve` against a fixture dir, hits it via fetch, asserts the response. Skipped with `test.skipIf(!httptapeOnPath)` when no binary is available.

Consequences

• Plus: Single `pnpm add -D vite-plugin-httptape` + a 5-line config gives Vite-frictionless DX.
• Plus: Mirrors `httptape-jvm` topology — third repo with the same Build → validate → publish gate.
• Minus: Five platform binary packages is operational overhead (each needs its own npm package). esbuild lives with this; we will too.
• Minus: Cross-repo release dispatch couples `httptape` and `httptape-js` release pipelines. Manual fallback (locally run publish script) stays available if the dispatch ever breaks.

---

Status: READY_FOR_DEV — proceed with the scaffold per "Scope of dev's first PR" above.

[tibtof]

Status: READY_FOR_REVIEW
PR: #2

[tibtof]

Status: CHANGES_REQUESTED

PR #2 review found 2 bugs to fix before approval:

1. process.ts -- setTimeout in killGracefully needs .unref() to prevent 3-second hang on shutdown
2. index.ts -- route prefix passed to new RegExp() without escaping; replace with startsWith/slice

Scaffold structure, API surface, tests, CI, and package.json hygiene all verified against ADR-1.

[tibtof]

Status: APPROVED -- ready for human review

Both reviewer-requested fixes verified in commit 4a6d86f:

• timeout.unref() added correctly in process.ts
• Regex replaced with startsWith/slice in index.ts
• New tests cover regex-metacharacter edge cases

No regressions, no unrelated changes.

[tibtof]

Status: READY_FOR_REVIEW
PR: #3

This covers the receiver half of the cross-repo release pipeline (ADR-1). The dispatcher step in httptape/httptape's release.yml is a separate follow-up PR.

[tibtof]

Status: CHANGES_REQUESTED

PR #3 review found 1 blocking issue:

1. Missing build step: vite-plugin-httptape is published without running tsc first. The dist/ directory (declared in "files") will be empty/missing, producing a broken npm package. Fix: add pnpm --filter vite-plugin-httptape build step between Install dependencies and Publish vite-plugin-httptape.

All other aspects of the release workflow (triggers, tag resolution, cross-compilation, version-set, pnpm/Node setup, publish order, auth, permissions, documentation) verified correct against ADR-1.