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: trueSo 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 immediatelybun 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:
devis now CWD-dependent. It looks forpages/in the current working directory and errors otherwise — it cannot be pointed elsewhere.build --pagesis 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 "
--pagesis now the default, ignoring". - It landed under a caret range.
"@stacksjs/stx": "^0.2.73"resolves to0.2.82, so a routine install silently removes a CLI flag — a breaking change in a non-major bump. Any consumer withdev --pagesin 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
- Re-add
--pages <dir>tostx dev, defaulting topages— matchingstx buildexactly. Smallest change, restores parity, un-breaks existing scripts. - Failing that, accept-and-warn on
--pagesfor a deprecation window instead of erroring. - Independently worth considering: don't hard-error on unknown options for
devin 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.