overengineeringstudio / overengineeringstudio/effect-utils

storybook.nix: --exact-port and --ci are contradictory, causing silent failures on port conflicts

Open
#307 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

area:nix area:storybook type:bug
Dominant language
TypeScript
Stars
82
Forks
2
Avg merge
1d 8h
Merged PRs (30d)
121

Description

Problem

storybook.nix passes both --ci and --exact-port to the storybook process, but these flags are contradictory for the port-conflict case:

  • --ci disables interactive prompts and makes storybook auto-select a free port when the requested one is taken
  • --exact-port prevents auto-selection and causes storybook to fail if the port is taken

The inline comment even describes the --ci defense-in-depth behavior, but --exact-port silently negates it:

# --ci disables interactive prompts (defense-in-depth: if the devenv-allocated port is
#   unexpectedly taken, storybook auto-selects a free port instead of hanging on a prompt)
# --exact-port prevents auto-opening browser tabs
${storybookBin} dev -p ${toString (getAllocatedPort pkg)} --host 0.0.0.0 --no-open --ci --exact-port

The result: if the devenv-allocated port is already occupied at runtime, the storybook process exits immediately with no useful error output — the process-compose log just shows storybook v10.2.1 and nothing else.

Root cause

ports.http.allocate allocates ports at Nix eval time to avoid conflicts within a devenv project (e.g. two storybooks in the same project). It has no visibility into ports occupied at runtime by other processes (other devenv projects, other tools, etc.).

So if two devenv projects both allocate port 6006, whichever starts second will silently fail.

How to reproduce

  1. Have two separate devenv projects that both configure storybook.nix with overlapping port numbers (e.g. both use 6006 as base port)
  2. Run devenv up in the first project — storybook starts fine on 6006
  3. Run devenv up in the second project — the storybook process exits immediately, showing only storybook v10.2.1 in process-compose

Expected behavior

Either:

  • Option A: Remove --exact-port so --ci can do its job — storybook auto-selects a free port and prints the actual URL in its startup banner
  • Option B: Document a port range convention per project so operators know to avoid overlapping allocations, and keep --exact-port for predictable URLs

Option A seems strictly better since it degrades gracefully and storybook's own startup output already shows the real URL.


Filed on behalf of @schickling

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start in storybook.nix at the Storybook dev command and review the --ci and --exact-port arguments alongside the inline comment. Reproduce the conflict with two devenv projects and inspect the process-compose output; done when a taken allocated port no longer causes a silent exit and the resulting URL or useful error is visible.

Written by the indexing model from the issue text.

Assessment

Domain
devops
Issue type
Bug
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.