@videntia/review-stack

Multi-slot Docker dev stack — bring up an isolated web + api + db per PR with hot reload, deterministic port allocation, and one-command teardown.

Built on top of docker compose. Runtime-agnostic — works under bun, pnpm, npm.

Why

Reviewing PRs locally means spinning up a fresh DB + API + web instance per branch without colliding ports. review-stack does port math + project naming + lifecycle commands so you don't.

Install

# bun
bun add -d @videntia/review-stack

# pnpm
pnpm add -D @videntia/review-stack

# npm
npm i -D @videntia/review-stack

Or one-shot:

bunx @videntia/review-stack up
pnpm dlx @videntia/review-stack up
npx @videntia/review-stack up

Quickstart

# 1. scaffold config + a runnable sample compose
review-stack init --sample --prefix myapp-review

# 2. start (uses current PR number from `gh pr view`, else fallback)
review-stack up

# 3. inspect
review-stack ps
review-stack logs --service api --follow

# 4. teardown
review-stack down            # keep volumes
review-stack down --volumes  # drop volumes
review-stack reset           # nuke + restart

Port allocation

web = base + (slot % modulus) * stride
api = web + 1
db  = web + 2

Defaults: base=10000, stride=10, modulus=5554. Slot = PR number, or fallbacks.main on main, fallbacks.noPr otherwise.

| PR | web | api | db | |-------|-------|-------|-------| | 7 | 10070 | 10071 | 10072 | | 230 | 12300 | 12301 | 12302 | | 1234 | 22340 | 22341 | 22342 |

Config (review.config.json)

{
  "projectPrefix": "myapp-review",
  "composeFile": "docker-compose.review.yml",
  "services": { "web": "web", "api": "api", "db": "db" },
  "ports": { "base": 10000, "stride": 10, "modulus": 5554 },
  "fallbacks": { "main": 80, "noPr": 90 },
  "hooks": {
    "migrate": "pnpm --filter @workspace/api db:migrate",
    "seed": "pnpm --filter @workspace/api db:seed"
  }
}

Env vars exposed to your compose file and hooks:

• REVIEW_SLOT — PR/slot number
• REVIEW_WEB_PORT, REVIEW_API_PORT, REVIEW_DB_PORT — computed host ports
• COMPOSE_PROJECT_NAME — <prefix>-<slot> (set automatically)

Commands

| Command | Purpose | |---------|---------| | init [--sample] [--prefix] | Write review.config.json (and optional sample compose) | | up [--slot N] [--pull] | Build + start + run hooks.migrate + hooks.seed | | down [--volumes] | Stop containers; -v also drops volumes | | reset | down -v then up | | ps | docker compose ps for the active stack | | logs [--service api] [--follow] | Tail logs | | migrate | Run hooks.migrate | | seed | Run hooks.seed |

Slot resolution order: --slot → REVIEW_SLOT env → gh pr view → fallback.

License

MIT