ReviewOS

stacks/stx

stx dev rejects --pages but stx build accepts it (breaking change under a caret range)

#1781
Closed glennmichael123 opened this 14 days ago · 0 comments
14 days ago

Summary

stx build accepts --pages <dir>; stx dev rejects it as an unknown option and exits. The two sibling commands disagree about the same flag, so a script that works for one hard-fails for the other.

Repro

$ stx build --help
Options:
  --pages <dir>      Directory containing page templates (default: pages)
  --out <dir>        Output directory for generated files (default: dist)
  ...

$ stx dev --help
Usage:
  $ stx dev [file]
Options:
  --port <port>      Port to use for the dev server (default: 3000)
  ...
  (no --pages)

$ stx dev --pages pages
ClappError: Unknown option `--pages`
 isUsageError: true

So this package.json — written against a coherent API — is now half-broken:

"build": "stx build --pages pages --out dist --no-sitemap",   // ✅ works
"dev":   "stx dev --pages pages"                              // ❌ exits immediately

bun run dev is dead; bun run build is fine.

Why this is worth fixing rather than telling consumers to drop the flag

build has the right design and dev regressed away from it. Defaulting to pages/ is good; keeping --pages as an explicit override is what makes it usable. dev kept the default and deleted the override, which makes it strictly less capable:

  • dev is now CWD-dependent. It looks for pages/ in the current working directory and errors otherwise — it cannot be pointed elsewhere. build --pages is location-independent.
  • Inconsistent within one CLI. Same flag, same concept, different answer per subcommand.
  • Unknown options hard-error rather than warn. No deprecation window, no "--pages is now the default, ignoring".
  • It landed under a caret range. "@stacksjs/stx": "^0.2.73" resolves to 0.2.82, so a routine install silently removes a CLI flag — a breaking change in a non-major bump. Any consumer with dev --pages in package.json breaks on upgrade without touching their own code.

There's a real-world cost to the silence: in the repo where I hit this (stacksjs/ts-cloud, packages/ui — a 34-page management dashboard), bun run dev had been failing, so nobody was running the UI locally. Bugs that a single click-through would have caught sat unnoticed.

Also slightly misleading

When dev can't find the directory it prints:

Error: No 'pages' directory found in /path/to/cwd
Create a pages/ directory with .stx files to define your routes.
Example: pages/index.stx for the homepage.

That reads like you're scaffolding a new project. The common case is an existing project where you're simply one directory off, or passing the flag that used to work.

Suggested fix

  1. Re-add --pages <dir> to stx dev, defaulting to pages — matching stx build exactly. Smallest change, restores parity, un-breaks existing scripts.
  2. Failing that, accept-and-warn on --pages for a deprecation window instead of erroring.
  3. Independently worth considering: don't hard-error on unknown options for dev in general, and mention the CWD in the "no pages directory" message.

Happy to send a PR for (1).

Versions

stx 0.2.82, Bun 1.4.0-canary. Consumer: stacksjs/ts-cloud packages/ui.

Sign in to comment on this issue.