Problem
stx ships three if families:
| Form | Runs at | Reactive? | Else support | Example |
|---|---|---|---|---|
@if (cond) ... @else ... @endif | SSR | No | Yes (@elseif, @else, @endif) | Blade-style block |
v-if="cond" on element | Compiles at build to @if | No | Yes (v-else-if, v-else) | Vue-style sugar for the above |
:if="cond" / x-if="cond" on element | Runtime via bindIf / bindIfChain | Yes (signals) | Yes since #1734 (:else-if, :else) | Reactive directive |
Three different things called if. They look identical at a glance:
@if($user)
<span v-if="user.isAdmin">admin</span>
<span :if="loading">loading</span>
@endifThree different lifecycles in adjacent lines. No editor surface telling you which is which. Adopters get caught.
Symptoms I personally hit:
- Tried to use
:if="isAuthenticated"(bare ref) thinking it'd be reactive — it was reactive but the bare ref had a subtle gotcha (worked accidentally; see #1733) - Confused
@if($user)(server, $ prefix) with:if="user"(client, no $) — was treating $-prefix as decoration - Treated
v-ifas reactive (Vue habit) — it's actually compiled to server-side@if
Proposed direction
Three options, ranked by impact:
Option A (recommended): make the three look distinctly different
Rename the build-time family to make their lifecycle obvious:
| Today | Proposed | Lifecycle |
|---|---|---|
@if (cond) ... @endif | @if (cond) ... @endif (unchanged) | SSR |
v-if="cond" | @v-if="cond" or <vif> block | SSR (still compiles to @if) |
:if="cond" / x-if="cond" | :if / x-if (unchanged) | Runtime reactive |
The @ prefix becomes "SSR/build-time directive." The : and x- prefixes become "client-side reactive directive." Visually distinct at a glance.
Option B: deprecate one
Pick a single "build-time conditional" syntax (recommend @if since it's Blade-canonical and existing adopters know it), deprecate v-if over a major version. Adopters writing Vue-style migrate to @if. Reduces the surface to two: server @if, client :if.
Option C: hard documentation pass + lint rules
Keep the three syntaxes but ship explicit documentation + an opt-in linter rule:
- Add a "Directive Lifecycle" page to the docs with the table above
- Add
stx/no-mixed-conditionalslint rule that errors on a file that uses two of the three families - Add
stx/explicit-conditional-commentlint rule that requires a<!-- :if (reactive) -->comment before each conditional
This is the lowest-cost option but doesn't fix the fundamental UI of "they look the same."
Recommendation
Option A. The visual prefix distinction is what every other framework has done (Vue's v- prefix means "compiler directive," React's {} means "JSX expression escape," etc.). Stacks shipping three indistinguishable conditional families is a footgun adopters notice in week 1.
Impact
- Onboarding: adopters stop conflating the three.
- Debugging: when you read an unfamiliar component, you can tell at a glance whether a conditional is reactive or compile-time.
- Migration: Vue refugees feel at home because
@v-if(or whatever syntax) signals "this is the Vue-style compile directive."
Phasing
- Phase 1: Documentation + linter rules (Option C — lowest risk)
- Phase 2: Soft-deprecate one of the three (Option B)
- Phase 3: Hard rename for next major (Option A)