Problem
The following footguns are documented in adopter memory but cause silent runtime misbehavior with no compiler error:
- Bare function ref in event handler —
@click="toggleLike"does nothing; only@click="toggleLike()"works - View-level
<script client>— silently dropped; only components get scopes - Store value imports — value imports from outside
resources/stores/get silently stripped from store bundles signal()call-syntax inside:for— falls back to a path that leaves the loop var as a signal function → comparisons silently always return the same branchx-classarray mixing static + conditional — breakstransform/translate-x-*utilities- Bare browser globals shadowed by store signals —
location.searchresolves to the search store'slocationsignal, throws, kills the rest of<script client> - Backticks in HTML comments inside
.stx— leak into merged setup function and flip JS parser into template-literal mode - Backticks inside
//line comments (in.tsfiles) — Bun parser chokes silently - stx directives inside HTML comments —
@push/@include/etc. get substituted at the comment location, busting page structure @includecan't forward:forloop var into a partial with<script client>— loop var hits scope boundarywindow.stx._rpunset on hard reload — dynamic route components must parselocation.pathnameinstead<template>tags in stx — SSG bug strips parent trees- Web Components (hyphenated tags) in stx templates — hyphenated tags are stx component refs
Every one of these is a place where the code looks correct but does nothing or does the wrong thing. The framework knows these are footguns (they're either in docs or in adopter memory notes). The linter should catch them at write time.
Proposed: @stacksjs/eslint-config-stx-strict
ESLint preset with one rule per footgun:
| Rule ID | Catches |
|---|---|
stx/no-bare-function-ref-in-event | @click="toggleLike" without parens |
stx/no-view-level-script-client | <script client> at the top level of a view file |
stx/store-value-imports-must-be-local | Imports from non-resources/stores/ paths in store files |
stx/no-signal-call-in-for-iteration-var | signal() call inside :for body |
stx/x-class-array-no-static-strings | x-class="[cond ? '...' : '', 'static']" |
stx/use-window-prefixed-globals | Bare location / history / localStorage in scopes with stores |
stx/no-backticks-in-html-comments | Backticks inside <!-- --> blocks in .stx |
stx/no-backticks-in-line-comments | Backticks inside // comments in .ts |
stx/no-stx-directives-in-html-comments | @push / @include inside <!-- --> |
stx/no-for-loop-var-in-include | @include('x', { v: loopVar }) where the partial has <script client> |
stx/no-template-tag-in-stx | <template> outside known-safe directive use |
stx/no-web-components-in-templates | hyphenated lowercase tags that aren't stx components |
Adopters opt in via:
{ "extends": ["@stacksjs/eslint-config-stx-strict"] }Or the strict preset becomes the default in create-stacks-app so new projects get it from day 1.
Prior art
@vue/eslint-config-typescript+ Vue official rules — catches Vue-specific footgunseslint-plugin-react— catches React footguns (missing keys, exhaustive deps, etc.)@typescript-eslint— catches TS-specific footgunseslint-plugin-svelte— Svelte equivalent
Every framework has its strict-mode lint preset. Stacks documents the footguns but doesn't ship the lint rules.
Impact
- Bug-class elimination: every documented footgun becomes a build-time error.
- Onboarding: new adopters can't accidentally write the broken pattern.
- Code review: reviewer doesn't have to remember the 13 footguns.
Phasing
- Phase 1: Top 5 most-hit rules (bare function ref, view-level script client, store value imports, signal call in :for, backticks in HTML comments)
- Phase 2: Remaining 8 rules
- Phase 3: Auto-fix where safe (
stx/no-bare-function-ref-in-eventcan auto-add parens)
Happy to PR Phase 1 — the rules are essentially "grep + AST check," each is ~50 LOC.