ReviewOS

stacks/stx

directives: consolidate or hard-document the @if / v-if / :if family distinction

#1743
Closed glennmichael123 opened this 22 days ago · 1 comment
22 days ago

Problem

stx ships three if families:

FormRuns atReactive?Else supportExample
@if (cond) ... @else ... @endifSSRNoYes (@elseif, @else, @endif)Blade-style block
v-if="cond" on elementCompiles at build to @ifNoYes (v-else-if, v-else)Vue-style sugar for the above
:if="cond" / x-if="cond" on elementRuntime via bindIf / bindIfChainYes (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>
@endif

Three 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-if as reactive (Vue habit) — it's actually compiled to server-side @if

Proposed direction

Three options, ranked by impact:

Rename the build-time family to make their lifecycle obvious:

TodayProposedLifecycle
@if (cond) ... @endif@if (cond) ... @endif (unchanged)SSR
v-if="cond"@v-if="cond" or <vif> blockSSR (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-conditionals lint rule that errors on a file that uses two of the three families
  • Add stx/explicit-conditional-comment lint 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)
22 days ago

Shipped the documentation half of Option C (the lowest-risk phase) in bc8cacf:

  • docs/guide/prefix-convention.md — new "Conditionals: three lifecycles (@if vs v-if vs :if)" section with:
    • the lifecycle table — @if = server/once, v-if = compiles to @if (verified in vue-template.ts, not reactive), :if/x-if = client/reactive via bindIf/bindIfChain
    • the "three adjacent lines, three lifecycles" trap rendered explicitly
    • the two gotchas you personally hit: $user (server scope) vs user (client signal scope) is not decoration, and the signal call/bare nuance inside :if (bare name works via the unwrap proxy; call syntax works via the #1733 retry pass)
    • a clarification that @ is overloaded: a statement @if(...) is a server directive, an attribute @click="…" is a client event listener
  • docs/guide/directives.md + docs/features/directives.md — callouts on the @if sections cross-linking to the lifecycle table, so adopters who land on the directive reference get routed to the distinction.
  • CLAUDE.md — compact three-if-families table so codegen/agent work picks the right family.

Deliberately not done (kept open if you want it):

  • The opt-in lint rules from Option C (stx/no-mixed-conditionals, stx/explicit-conditional-comment) — that's a pickier-rule build, separate from docs.
  • Options A/B (visual rename / soft-deprecation) — breaking changes for a future major; the docs above are the non-breaking mitigation in the meantime.

Closing the documentation deliverable. Happy to reopen / spin a focused issue for the lint rule if you want that next.

Sign in to comment on this issue.