The @stacksjs/components README leads its ## Usage section with the verbose @component('Foo', {...}) Blade-style directive form, but the actual example files in the same package (and other consumer code) use the much cleaner JSX-tag form. New users following the README write code like:
@component('Dialog', { open: isOpen, onClose: close })
@component('DialogBackdrop')
@component('DialogPanel', { className: 'max-w-md' })
@component('DialogTitle')
Confirm delete
@endcomponent
@endcomponent
@endcomponent…when the actual idiomatic stx form is:
<Dialog :open="isOpen" :onClose="close">
<DialogBackdrop />
<DialogPanel className="max-w-md">
<DialogTitle>Confirm delete</DialogTitle>
</DialogPanel>
</Dialog>Where the inconsistency lives
| File | Form used |
|---|---|
packages/components/README.md § Usage / Basic Example | @component(...) directive |
packages/components/src/ui/dialog/README.md § Usage | @component(...) directive |
packages/components/examples/button-examples.stx | JSX tags (<Button variant="primary">) |
packages/components/examples/input-examples.stx | JSX tags |
packages/components/examples/demo.stx | mostly @component(...) directive (mixed) |
A reader hitting the README first reasonably concludes the directive form is the API. They write 30 lines of @component(...) boilerplate before discovering the example files do it differently.
Suggested change
Make the JSX-tag form the canonical example throughout, with @component(...) mentioned once as a Blade-compat alternative. Concretely:
- Rewrite
packages/components/README.md"Basic Example" and per-component snippets to use JSX tags - Rewrite
src/ui/*/README.md(35 component readmes) the same way — biggest mechanical lift, but each is short - Pick one form for
examples/demo.stx(probably JSX) and stop mixing within a single file - Add a one-liner near the top: "Both
<Foo>and@component('Foo', {...})work; the JSX form is preferred."
Why this matters
It's a subtle thing but it shapes the first impression of the library. The verbose form has a higher visual cost per usage and obscures simple things — a five-line modal becomes 15 lines of nested directives. New apps end up with a lot more code than they need.
I'm not asking to remove the directive form (it's a valid Blade-compat path), just to lead with the cleaner one.
Context
Hit while migrating an app to use @stacksjs/components. Came in expecting the JSX shape (matches <StxLink>, <Icon>, custom auto-discovered components, the rest of the stx ecosystem); got told by the README to write Blade directives; later found the real example files using JSX tags; spent a beat wondering if the JSX form was actually supported or just an experiment.