Problem
stx components today use an untyped $props.X bag in <script server>:
<script server>
export const src = $props.src || ''
export const alt = $props.alt || ''
export const fallback = $props.fallback || '/images/default.svg'
export const className = $props.className || ''
</script>Problems:
- No call-site validation.
<SafeImage src={someBoolean} />compiles.<SafeImage src="x" srx="typo" />compiles. Wrong types reach<img src=...>and the browser silently renders an empty image or garbage. - No discoverability. The list of accepted props lives in
<script server>body; the caller has to read the component source. There's no editor surface for "what props does<Notification>take?" - No autocomplete. Typing
<SafeImagein an editor gets you nothing. Vue'sdefineProps<{ src: string }>()gives you autocomplete on every prop name + type validation on every value. - Defaults are stringly.
$props.src || ''collapses0,false,null,''into the fallback. For a numeric prop likecount={0}, the default-coalesce silently swaps it for the fallback. - No required vs optional distinction. Every prop is treated as optional with
|| default. No way to express "this prop is required and must be a number ≥ 0."
The first three are DX gaps. The last two are correctness gaps.
Proposed API
Mirror Vue 3 SFC's defineProps shape so adopters from Vue land transfer immediately:
<script server>
interface Props {
src: string // required
alt?: string // optional
fallback?: string // optional with default
fallbackClassName?: string
className?: string
}
const props = defineProps<Props>({
fallback: '/images/safe-image-default.svg',
alt: '',
})
</script>
<img
src="{{ props.src }}"
alt="{{ props.alt }}"
class="{{ props.className }}"
data-fallback="{{ props.fallback }}"
...
/>Build-time SFC compilation:
- Generates a JSON schema describing prop shape at component file path
- Emits
.d.tsfile alongside the component so editors can autocomplete callsites - Validates at call site:
<SafeImage src={123} />becomes a TS error, not silent runtime garbage
Runtime SSR:
props.srcaccesses the validated value (with default applied for optional props)- Type assertions still hold (
srcisstring, narrowed)
Sibling APIs (paired)
// Events typed similarly
interface Emits {
(e: 'close'): void
(e: 'submit', payload: { value: string }): void
}
const emit = defineEmits<Emits>()
emit('submit', { value: 'hi' }) // typed
emit('subm', ...) // TS error
// Slots typed
interface Slots {
default: () => unknown
header?: (props: { title: string }) => unknown
}
const slots = defineSlots<Slots>()Prior art
- Vue 3 SFC —
defineProps<T>()is the de-facto standard - React —
interface Props {}; function Comp(props: Props)— same TS-validated shape - Svelte 5 runes —
let { src, alt = '' } = $props()with TS inference - Solid —
(props: Props) => JSXwith full inference - Qwik —
component$((props: Props) => ...)
Every modern framework has typed props. stx is the only one that doesn't.
Impact
- Authoring DX: high. Adding a new component goes from "read another component's source to discover convention" to "let the compiler tell me what's required."
- Call-site safety: high. Wrong-shape calls become TS errors.
- Migration ergonomics from Vue/React: huge. The bigger lift for an adopter from Vue land today is "wait, where's
defineProps?"
Phasing
- Phase 1: Compile-time validation of
defineProps<T>()shape — generates.d.tsfor the component, no runtime change - Phase 2: Call-site type-check (the JSX-equivalent
<SafeImage src={...} />validates against the generated.d.ts) - Phase 3:
defineEmits<T>()+defineSlots<T>()for the full contract surface - Phase 4:
defineExpose<T>()for ref-accessed methods (already partially supported via current shape)
Happy to PR Phase 1.