Reference

Diagnostics

Every diagnostic the Unframework compiler reports, by its stable UF code, with what it means and how to fix it.

The compiler reports every problem it finds as a diagnostic, with a stable code such as UF3013. A code is never reused or renumbered. The compiler never copies code it has not analysed into an output, so anything it cannot lower to every target is a diagnostic, never a silent difference.

The CLI and the bundler plugin report codes too, for a config, a project or a build rather than one component, like UF7003 for an unknown target or UF7005 when the plugin can't tell your framework. Some of those have no place in a source to point at. They name the file they concern, like unframework.config.ts or your Vite config, at its start, and the message says what's wrong, naming a config's field by its JSON pointer.

A diagnostic has a severity, a message that names what was found, the place in the source, help, and, where the rewrite is mechanical, fixes. Only an error stops a component from compiling. A fix is safe when it can be applied without a review, and likely when it needs one. The compiler links each code to its section on this page.

This file has no key on its list item:

TagList.uf.tsx
// UF3013 missing-key: a list item without `key`; the likely fix keys it by its index.
export interface TagListProps {
  tags: string[];
}

export default function TagList({ tags }: TagListProps) {
  return (
    <ul>
      {tags.map((tag) => (
        <li>{tag}</li>
      ))}
    </ul>
  );
}

The compiler reports it, with a likely fix:

diagnostics.json
[
  {
    "code": "UF3013",
    "severity": "error",
    "message": "A list's element needs a `key`: the frameworks match each item's element across renders by it.",
    "file": "diagnostics/missing-key/TagList.uf.tsx",
    "start": {
      "line": 10,
      "column": 10,
      "offset": 254
    },
    "end": {
      "line": 10,
      "column": 12,
      "offset": 256
    },
    "help": "Key it by something unique and stable in the item: `key={item.id}`.",
    "fixes": [
      {
        "title": "Key the element by its index, `key={index}`",
        "confidence": "likely",
        "edits": [
          {
            "span": {
              "start": 238,
              "end": 238
            },
            "text": ", index"
          },
          {
            "span": {
              "start": 256,
              "end": 256
            },
            "text": " key={index}"
          }
        ]
      }
    ]
  }
]

Codes are grouped in bands:

BandCovers
UF1xxxSyntax and components
UF2xxxSetup and macros
UF3xxxJSX and cross-component usage
UF4xxxPortability (capabilities)
UF5xxxStyles
UF6xxxTypes
UF7xxxConfig and tooling
UF8xxxPlugins
UF9xxxInternal

Syntax and components

UF1001 syntax-error

Error. The file is not valid TSX.

The parser could not read the file as TSX. The message names the first problem it met.

Fix the syntax error. Any TypeScript editor shows the same error, because a .uf.tsx file is ordinary TSX.

A raw } or > in JSX text is a syntax error: write &#x7D; or &gt;, which every JSX implementation decodes (none decodes &rbrace;), or a string expression ({"}"}). The fix writes the reference where the file then parses. Where it would not, the } is more likely code after an element that is not closed.

UF1002 unsupported-syntax

Error. The compiler cannot lower this construct yet.

The construct is part of the source language, but this version of the compiler cannot lower it to every target yet. The compiler never copies code it has not analysed into an output, so it reports the construct instead.

Rewrite the code without the construct, or wait for the release that supports it. The message names the construct, and the milestone that lowers it where one does. Some constructs are outside the subset because one target cannot read them: Angular's template language has no block-bodied arrow functions, type assertions, hexadecimal numbers or \u{…} escapes, so template expressions keep to what every target reads alike. Where a mechanical rewrite exists (0x10 to 16, { return e; } to e), the fix applies it.

Setup code and handlers are script or class code on every target, which TypeScript checks: they may use those constructs, but not var, labels, for…in, classes, generators, this, function declarations and expressions inside other code (write an arrow function), or a type assertion on the target of a write of state or of a setup let, which the outputs respell (write the target bare). Where the React Compiler cannot compile code the subset admits (a throw in a try block, finally), React's output opts the component out of it. Their type annotations are copied as written, so a type query (typeof mode.value) names no prop, binding of the setup or authoring API, which the outputs respell or erase: write the type. A statement at the top level of a component's body that only does something (init();) belongs in onMounted or a function: the setup declares what the component holds. A watcher's deep, once and flush: "sync", and its stop handle, are not supported, and immediate: false, flush: "pre" and an empty options object, the defaults, are written as nothing, in a watcher's one canonical form: the fix removes them.

Some attributes wait for a target: a name a target's element types do not declare fails that target's type-check whatever its value (writingsuggestions, commandfor and dirname in React's; popover and closedby in Vue's, which are also the authoring types; ARIA 1.3's aria-description in Vue's and Svelte's), and a bound size or multiple on a <select>, or disabled on an <option> or <optgroup>, decides which option starts selected, which some clients settle before they bind it (form state, M3).

UF1101 no-component

Error. The file exports no component.

A .uf.tsx file holds components: exported PascalCase functions whose last statement returns JSX.

export default function Greeting() {
  return <p>Hello, world!</p>;
}

Export a component, or move framework-agnostic code to a plain .ts module.

UF1102 invalid-component

Error. A component must be a named PascalCase function that returns JSX.

A component is a function whose body is its setup, and whose last statement returns the JSX that is its template:

export default function Greeting() {
  return <p>Hello, world!</p>;
}

The compiler reports a component without a name (export default function () { … }), a generator, one whose last statement does not return JSX, and one that renders nothing (return <></>;).

A component returns an element or a fragment. A conditional or a list (return c ? <A /> : <B />;) belongs inside one: the fix wraps it in <>…</>, which renders the same.

A component is a function declaration. One written as a value, an arrow function or a function expression in a const (export const Card = (props: CardProps) => …), is reported, and still checked as the declaration it would be: the fix declares it as export function Card(props: CardProps) { return …; }, keeping its parameters and body.

It also reports an exported function that returns JSX, as a component does, under a name that is not PascalCase in ASCII letters and digits ([A-Z][A-Za-z0-9]*). JSX reads a tag that starts with a lower-case letter (<card>) as an HTML element, and every target names files after the component (Card.vue, and card.ts on Angular, whose selector is uf-card), so its name keeps to the characters every file system and target reads alike. The fix renames the function where its name is used nowhere else.

UF1103 invalid-export-name

Error. A component is exported under a name that is not an identifier.

Every target writes a component's exports as code, and consumers import a component by name to use it as a JSX tag, so its exported name must be an identifier.

export { Card as "my card" }; // rejected
export { Card as MyCard };     // accepted

UF1104 component-name-collision

Error. Two components would write one output file or Angular selector.

Each component compiles to a file named after it: Card.vue, and card.ts on Angular. Two components of one module whose names differ only in case, or an imported child whose output file is another component's, would write one file, since files whose names differ only in case overwrite each other on case-insensitive file systems (macOS and Windows). So would a shared .ts module named like a component's output file, such as badge.ts beside Badge.uf.tsx, or CardIcon.ts beside a component or a child CardIcon: each output tree holds a copy of the module beside the components, and an output imports a component's file by its name without the extension (./CardIcon), in kebab-case on Angular (./card-icon).

Angular also writes each child as a uf-<kebab> selector, and fills each slot through an attribute directive, such as ufCardTitle. A child whose selector is the component's own or another child's, and two filled slots whose directives share an attribute, would match twice.

Rename one of the components, one of the slots or the shared module.

UF1201 framework-import

Error. Components are framework-free.

A .uf.tsx component is compiled to every framework, so it cannot import one. The compiler writes each framework's code for you: hooks in React, refs in Vue, runes in Svelte, signals in Solid.

Write the component with the authoring API from @uxfront/unframework instead:

import { ref } from "@uxfront/unframework";

export default function Counter() {
  const count = ref(0);
  // …
}

UF1202 unresolved-import

Error. An imported module cannot be resolved.

A .uf.tsx file imports another one's components and injection keys by a relative specifier that ends in .uf.tsx. The compiler reads the imported module's public API through its resolver: the components it exports, their props, events, models and slots, and its keys. It reads a shared .ts module whose values a component imports, and every relative .ts module that one imports, through the resolver too: every output tree holds a copy of each. This import names a file the resolver cannot find, a name the file does not export, or a shared module that imports a file the resolver cannot find, or loads one it cannot follow (an import() of no string, import.meta.glob), or the compiler was called without a resolver.

import Field from "./Field.uf.tsx";       // the default export
import { Fields } from "./Fields.uf.tsx"; // a named export
import { sizes } from "./tokens.ts";      // a shared module's value

Check the path and the imported name. The Vite plugin passes a resolver; a direct call of compile() passes one as its resolve option.

UF1203 self-import

Error. A module does not import itself.

A component renders itself, or another component of its own module, by the name it is declared with (ADR-0053). An import of the module's own file would give it a second name.

// Countdown.uf.tsx
import Again from "./Countdown.uf.tsx"; // rejected
<Again from={from - 1} />               // rejected
<Countdown from={from - 1} />           // accepted

Remove the import, and render the component by its own name. The likely fix does both, unless the import binds something other than a component, or the module gives the name to something else.

UF1204 framework-in-shared-module

Error. A shared module imports a framework.

A component may read values and types from a relative .ts module, which the compiler copies into every output tree unchanged (ADR-0070). Every framework's output loads that copy, so it cannot import a framework, or @uxfront/unframework, whose authoring API exists only in .uf.tsx and .uf.ts files. This one does, itself or through another .ts module it imports. The diagnostic points at the component's import of the shared module, and the component is compiled for no target.

Keep a shared module to plain values, types and functions. Move logic that needs reactivity into a composable in a .uf.ts module, which the compiler compiles for each target.

UF1205 import-cycle

Error. Components import each other in a cycle.

A component edge is a value import of a component from another .uf.tsx module: the import a parent renders a child by (ADR-0071). These components import each other in a cycle of such edges, through two or more modules, so none of them can load before the others, and Angular cannot load them at all. The message names the files of the cycle, and the diagnostic points at the import that closes it.

An injection key, a type or a shared module imported back closes no cycle, so a consumer may import its key from the provider that renders it (UF2033).

Break the cycle: declare the components that render each other in one module. A component renders itself by its own name, without an import (UF1203).

Setup and macros

UF2001 invalid-props

Error. The props parameter is not in a form every target can declare.

A component takes its props as its only parameter, typed by an object type: either destructured, with optional static defaults, or as one object read as props.x.

export default function Badge({ label, tone = "info" }: BadgeProps) { … }
export function Plain(props: PlainProps) { return <p>{props.label}</p>; }

The compiler reports a parameter without a type annotation, a second parameter, a renamed, nested or computed property in the pattern, a member a props type declares twice, which TypeScript rejects too, a default on a required prop, a default on a prop whose type admits null (unless the default is null: Qwik applies a destructured default to null too), and, in the object form, a use of the object other than reading one of its members (props, props[key], props.x = …, (props).x) and a name starting with $$: Astro's compiled component declares $$props, $$result, $$slots and $$render where its output declares the object.

Destructure the props by their own names, declare each once, make a prop with a default optional, and read the object form only through its members.

UF2002 non-static-prop-default

Error. A prop's default must be a static value.

Vue hoists defineProps defaults out of the component and Angular reads an input's default before any input is set, so a default cannot read anything: not a prop, not a global, not a function's result.

A default is a string, number, boolean or null literal, a negated number, a template literal without expressions, or an array or object literal of those (identifier or string keys, no spreads).

({ page = 1, tags = ["new"] }: P)        // accepted
({ pageCount = Number.MAX_SAFE_INTEGER }: P) // rejected: reads a global

Write the value itself, or compute it in the template (pageCount ?? 10).

UF2003 reserved-prop-name

Error. A target reserves this name.

Every target declares each prop by its name and reads it in its templates, so a prop's name keeps to ASCII letters and digits (Angular's expression lexer reads no other letter), starting with a letter, and none a target gives a meaning of its own:

  • key, ref, children, class, style, slot, is, ref_for and ref_key, which React, Vue, Svelte or Astro read themselves and never pass to the component;
  • props, rawProps, constructor and Astro, which the outputs declare beside the props, and Fragment, which Astro's output imports to render <>;
  • JavaScript's reserved words, Angular's expression keywords (as, let, typeof, …) and the globals expressions may read (Math, String, …);
  • names of events (onClick): a component declares its events with defineEmits, and the outputs name their event props after them (ADR-0012); names starting with ng and a capital letter (ngIf), which Angular reserves for its directives, and names ending in $, which Qwik reads as a QRL.

The setup's bindings (its constants, lets, local functions, refs, models, slots, injected values and emit) are declared beside the props, as members of Angular's class among others, so their names keep to the same rules as a parameter's (UF3024), and are none of constructor, a name starting with ng and a capital letter, one starting with use and a capital letter or a digit (React's lint reads it as a hook, which a handler cannot call) and one ending in $; in the object form, none is a prop's name either. A parameter of a local function, a handler or a callback is an ASCII identifier too, since Angular's methods and template statements name it.

On Angular, each prop, model, event and exposed function is a member, an input or an output of one class, beside the lifecycle hooks (ngOnInit, ngOnChanges, …), each slot's query (titleTemplate) and the fallthrough class and style inputs. A model open is the input open and the output openChange, and an event named like a DOM event is the output uf<Name> (ufChange). So two of these names that meet are reported, as is a slot's directive, exported as CardTitle, that shares its name with a type, a key or a component the module exports.

The outputs also declare types named Props and CSSProperties, Angular's output imports its Component decorator, which is also a type, and reads TypeScript's Exclude, and Solid's output reads TypeScript's Partial, Record, Required and Pick, so a local type of any of these names is reported. Props is accepted as a component's own props type, when every component whose props reach it takes it as its props type: Astro's output declares a Props of its own for any other.

Rename the prop, the binding or the type.

UF2004 in-place-mutation

Error. State is replaced whole, never changed in place.

State is a ref whose value is replaced whole (ADR-0008): items.value = [...items.value, item]. No target's state is deep (Vue's output declares it with shallowRef), so a change in place (items.value.push(item)) re-renders none of them: their outputs would never see it.

So client code and getters change in place only a value no state shares: an object or an array they build themselves (a literal, new Map(), a copy written with a spread, or the new array slice, filter, map, concat, Array.from or Object.values returns, from state too), and what it holds where the code put a value it built there too (a literal's member written after its last spread, { ...x, tags: [...x.tags] }, or a container's members where every value the code writes into them is one, byKind[kind] = [] or byKind[kind] ??= []), but not what it shares with the value it copies; a deep copy (structuredClone(…), JSON.parse(…)) and all it holds; an element, the handler's event and a global (document.title); and a local, a setup let, a loop's variable, an array method's item or a reduce callback's accumulator (its initial value and what the callback returns) that only ever holds one of these, wherever the component's code writes it. A member assignment (a destructuring's and a loop's target too), delete, ++ or -- on a member, a method that changes its receiver (push, splice, sort, reverse, … and a Map's or a Set's set, add, delete and clear) and Object.assign and its kin are reported on anything else: a ref's value, a prop, a list's item, a constant the setup declares, a parameter, a member of a copy, or a name that may hold one of them. A module's top-level const changes in place only a value it builds itself, a literal, a new, a copy or a function's local that only ever holds one: a module's values are plain and read-only (ADR-0070).

tags.value.push("new");               // rejected
tags.value = [...tags.value, "new"];  // accepted
const copy = [...todos.value];
copy[0].done = true;                  // rejected: the copy shares the item with the ref
const open = todos.value.filter((todo) => !todo.done);
open.sort(byOrder);                   // accepted: `filter` returns a new array

Where the result is not used, the likely fix writes the new value whole: [...x.value, a], { ...x.value, key: v } for an object (never an array, a Map or a Set), toSorted, toReversed and toSpliced, x.value.slice(0, n) (or []) for an array's length, and for a destructuring assignment of a ref's members ([x.value[i], x.value[j]] = …) a copy that the assignment changes and that is then written whole.

UF2005 misplaced-reactive-call

Error. Macros and reactive APIs are called at the top level of the component.

Every target runs a component's setup once, and lowers each macro and reactive API where the setup calls it: a hook at the top of React's function, a rune in Svelte's script, a signal in Angular's class. So ref, computed, watch, watchEffect, onMounted, onUnmounted, defineEmits, useTemplateRef and useId are called at the top level of the component's body, as a statement or as a const's value: never inside a condition, a loop, a function, a handler or another API's callback, and never used as a value.

onMounted(() => {
  watch(open, () => report()); // rejected: a watcher created at every mount
});
watch(open, () => report());   // accepted

nextTick is a function, not a macro: client code (a handler, a watcher's callback, watchEffect, a lifecycle hook, or a function they call) calls it anywhere. The setup itself runs before the DOM exists, so it does not call nextTick.

UF2006 unbound-macro-result

Error. A macro's result is bound by a const.

ref, computed, useTemplateRef, useId and defineEmits return what the component holds: state, a derived value, a template ref, an id, the emit function. Each target declares it once, under the name a const at the top level of the component's body gives it, so a call whose result nothing binds, or that let or destructuring binds, has no counterpart.

defineEmits<{ close: [] }>();               // rejected
const emit = defineEmits<{ close: [] }>(); // accepted

The fix binds defineEmits's result as const emit, where the component names nothing emit already.

UF2007 setup-once-read

Warning. A setup const keeps the value it had when the setup ran.

The setup runs once per instance, so a const in it keeps its first value (plan §4.5): a const that reads a prop, a ref or a computed does not follow it when it changes. That is sometimes meant (a creation-time snapshot), and often a mistake.

const greeting = `Welcome, ${name}`;                  // keeps the first name
const greeting = computed(() => `Welcome, ${name}`);  // follows it

The likely fix makes it a computed, and reads it as greeting.value wherever it is read. ref(prop) seeds state from a prop on purpose, and is not reported.

UF2008 invalid-event-name

Error. An event's name is camelCase, apart from the props' names.

Every target spells an event its own way: React's, Solid's and Qwik's components take onLevelChange, Svelte's onlevelchange, Angular's an output levelChange (ADR-0012). So an event's name is camelCase in ASCII letters and digits, starting with a lower-case letter, and:

  • it does not start as an event prop does (onSave): a consumer would listen to onOnSave, and angular-eslint's no-output-on-prefix rejects it;
  • no two events differ only in case: Svelte lower-cases an event's prop;
  • no prop takes it: a prop is public on every target, and Angular declares a member for each; nor does a prop take its Svelte spelling (onchange for change). A binding of the setup may (function save() { emit("save"); }): it is the component's own, and Angular renames its class member (onSave), as the output keeps the event's name;
  • it is no keyword of Angular's template expressions (if, as, this, typeof, …), no global expressions may read (parseInt) and not constructor: Angular's template statements read the event's member by name (picked.emit(item)). Angular's lexer reads no other word as a keyword, so a JavaScript reserved word such as delete, new or default names an event.

The safe fix renames the event where its camelCase spelling is free (level-change to levelChange, onSave to save): its declaration and every emit of it.

UF2009 invalid-emits

Error. defineEmits takes one type argument: the events, as named tuples.

A component declares its events with one defineEmits call, whose one type argument lists them: an object type literal, or a local interface or type of one, whose members are the events, each typed by a named tuple of its payload. Every target reads the events from the type and declares a parameter for each member of a payload, so each member is named.

const emit = defineEmits<{ change: [value: number]; close: [] }>(); // accepted
const emit = defineEmits<{ (event: "change", value: number): void }>(); // rejected

The compiler reports Vue's call-signature form, runtime arguments (defineEmits(["change"])), a type argument that is no object type, an event that is not a named tuple ([number], a rest member, an optional event), a payload that names a member twice or puts a required member after an optional one, and a second defineEmits. A payload member's type is one props can have (strings, numbers, booleans, literals, null, undefined, arrays and local object types of them), since Vue declares an event's payload as it declares props.

UF2010 non-reactive-read

Error. A setup let or a template ref is read where values are tracked.

A template, a getter, an initial value, a watcher's source and watchEffect read values that the targets track, and render or run again when they change. A setup let is not reactive: a template that reads it would never update (React reads a useRef, which its lint rejects in render). A template ref is never a reactive dependency on every target (React's is a useRef).

let clicks = 0;
// …
<p>Clicked {clicks} times</p>  // rejected: hold it in a ref

Hold a value a template or an effect reads in a ref, and read an element from client code: onMounted, a handler, or watch(…, { flush: "post" }). A template or a getter that calls a function that reads one is UF2014; a watchEffect that does is reported here. What a watchEffect hands on to run later (a timer's callback, onCleanup's) runs untracked, and may read either: the handle of the timer it starts (onCleanup(() => clearInterval(timer))), or an element in a frame.

UF2011 invalid-write

Error. State is written in client code, as a statement of its own.

State is a ref, written through its value (count.value = 1, count.value += step, count.value++), and a setup let (timer = …) holds what no template reads. Only client code writes them: a handler, a watcher's callback, watchEffect, a lifecycle hook or a function they call. React, Solid and Angular write state through a setter, so a write is a statement of its own: the whole of an expression statement, or the whole expression body of a function whose value the framework drops (a handler, a watcher's callback, watchEffect, a lifecycle hook, an onCleanup callback). An arrow passed to another call writes in a block body, since a call such as map or then uses its value.

const flip = () => (on.value = !on.value);    // rejected: the function returns the write
const flip = () => { on.value = !on.value; }; // accepted
total.value = (count.value += 1);              // rejected: a write inside an expression
setTimeout(() => (copied.value = false), 2000); // rejected: write `() => { … }`

The fix gives a local function or an arrow whose expression body is a write a block body: a safe one where the call drops the arrow's value (a timer, forEach), a likely one elsewhere, where the code may need to return what the call uses. What a prop, a computed, a template ref, a constant, a local function, emit or a list's item holds is never written: copy a prop into a ref (const value = ref(initial)), and write the state a computed is computed from. A getter and an initial value are pure, and write nothing.

UF2012 conditional-return

Error. A component's body returns only at its end.

A component's body is its setup, which every target runs once, and its last statement returns the template. A return before it, conditional or not, would make the setup decide what renders, which no target's template can follow.

if (!message) return null; // rejected
return <p>{message}</p>;

Move the condition into the JSX: return <>{message && <p>{message}</p>}</>;.

UF2013 server-unsafe-effect

Error. An immediate watcher's callback is safe to run on the server.

Vue runs an immediate watcher's first callback during the setup, on the server too, and Angular and Qwik may: the server render must not depend on it, and must not fail. So the callback, every function in it (the onCleanup callbacks included) and the local functions they call write no state, read no template ref, read none of the browser's globals (every name lib.dom declares: document, window, localStorage, location, fetch, URL, IntersectionObserver, HTMLElement, requestAnimationFrame, …) nor the timers (setTimeout, setInterval, queueMicrotask and their clears), do not await, and call no nextTick. Emitting, reading state and props, console, performance and crypto are safe.

watch(() => query, (value) => { heading.value = value; }, { immediate: true }); // rejected
const heading = computed(() => `Results for ${query}`);                         // accepted

An immediate watcher with flush: "post" is reported too: its first callback runs before any DOM exists. Its onCleanup is called directly, before any await. Derive the value with computed, or write it from onMounted and a watcher without immediate.

UF2014 impure-function-call

Error. A template, a getter or an initial value calls only a pure local function.

Rendering, getters and initial values are pure: the targets run them when they decide to, on the server too. A template and an initial value call a local function only when it writes nothing, emits nothing, calls no nextTick, is not async, reads no template ref and no setup let, and reads only the globals they may (UF3020), itself and through the functions it calls. A function that reads the clock, chance or the locale is UF3019.

A getter (a computed's, a watcher's source) calls only a function that reads nothing but constants that read nothing themselves, and other such functions: Qwik hoists those, with their constants, out of the component, where a getter's closure can reach them.

function greet() { renders.value += 1; return `Hello, ${name}`; }
<h2>{greet()}</h2>  // rejected: rendering writes state

UF2015 conditional-effect-read

Error. watchEffect reads its reactive values unconditionally.

Vue's watchEffect tracks what each run reads, but React's effect and Qwik's track list an effect's dependencies statically: a value read only under a condition would be missed, or tracked when Vue's would not. So every read of a prop, a ref or a computed in a watchEffect lies in the straight-line start of its body: before the first if, loop, switch, catch, return, throw or await (that if's test, that switch's, return's or throw's value and that loop's head included: a for…of's iterable, a for's init and test, a while's test), into plain blocks and a try block up to its first call (its callee and arguments included: what follows runs only where that call does not throw), outside the right side of &&, ||, ??, ||=, &&= and ??= and the branches of ?:, after no ?. in its chain (a later key or argument included), outside a destructuring default, and outside any function inside it but one it hands on to run later: a function given to a timer, a promise's then, addEventListener, an observer or onCleanup, written in place or held in a local const only such calls are given, reads its values when it runs, which no target tracks. A local function it calls reads its reactive values the same way.

watchEffect(() => {
  const enabled = live.value;
  if (enabled) emit("search", query.value); // rejected: read under a condition
});

Read every value first, into locals, or watch explicit sources with watch. The same holds for a watcher's getter, and a computed a watcher's source reaches, whose value may be an object or an array: React compares those by identity, and recomputes them when any listed dependency changes.

UF2016 unknown-api

Error. The import is not part of unframework's API.

A component imports the authoring API by name from "@uxfront/unframework": ref, computed, watch, watchEffect, onMounted, onUnmounted, nextTick, defineEmits, defineModel, defineSlots, defineExpose, defineOptions, provide, inject, useTemplateRef and useId, and the package's types. The compiler recognises each API by the binding its import declares, and erases the import, so a namespace or a default import, an import that imports nothing, a value imported from a subpath (@uxfront/unframework/jsx-runtime holds types only) and a name the package does not export as an API mean nothing.

Vue's APIs that unframework writes another way are reported with their canonical form: reactive (state is a ref, replaced whole), toRefs (props are destructured in the signature), watchPostEffect (watch(…, { flush: "post" })) and others.

UF2017 invalid-emit

Error. An emit is a statement that names an event the component declares.

emit tells the component's parent that something happened. Each target writes every emit as a call of its own (a callback prop, an Angular output), and what that call returns differs (Qwik's is a promise). So an emit is a statement of its own, in client code, of an event defineEmits declares, named by a string, with as many arguments as the event's payload takes, none spread.

emit("change", count.value); // accepted
emit("changed");             // rejected: no such event
const saved = emit("save");  // rejected: an emit is a statement

emit itself is only called. A handler that is emit (onClick={emit}) is UF3029.

UF2018 early-dom-read

Error. A watcher that reads the DOM runs after it updates.

A watcher runs before the DOM updates, unless it says flush: "post": Vue's and Svelte's read the DOM as it was, React's and Solid's as it is now. So a watcher's callback that reads a template ref or the DOM through a global, itself or through the functions it calls, runs with flush: "post", after the DOM updates on every target. The globals that read what a render changes are document (but its title, cookie, visibility and listeners), window whole or through its document, layout and scroll (window.scrollY, window.innerWidth), getComputedStyle and getSelection. Storage, navigator, history, location, fetch, the timers and the observers read nothing a render changes: a watcher that persists a value (localStorage.setItem(…)) or writes the URL needs nothing.

watch(items, () => {
  emit("rendered", list.value?.childElementCount ?? 0); // rejected: Vue reads the old list
});
watch(items, () => { … }, { flush: "post" });           // accepted

The likely fix adds { flush: "post" }. watchEffect runs after the DOM updates on every target, and needs nothing. What a callback reads after await nextTick(), which every path to the read passes, reads the updated DOM on every target, and needs nothing either.

UF2019 erased-type-reference

Error. A copied annotation names an authoring type.

The compiler erases the import from "@uxfront/unframework", and copies the annotations of setup code and props into the outputs, where nothing declares Ref, OnCleanup or the package's other types: an output that copied one would not type-check.

watch(user, (value, previous, onCleanup: OnCleanup) => { … }); // rejected
watch(user, (value, previous, onCleanup) => { … });            // accepted

Leave the annotation out where TypeScript infers the type: the likely fix removes it from a callback's parameter and from a const with an initial value. Elsewhere, write the type itself.

UF2020 unwatchable-source

Error. A watcher watches a ref, a getter or an array of them.

A watcher's source says what it watches: a ref or a computed itself, a getter that reads what it watches, or an array of them. A prop's value, a ref's value (count.value) and a constant are values taken once, which nothing can watch; a template ref is never a reactive dependency on every target.

watch(page, (value) => …);       // rejected: a prop's value
watch(() => page, (value) => …); // accepted

The safe fixes watch a getter of a prop (() => page) and a ref itself (count.value to count).

UF2021 untyped-state

Error. State and a setup let have a type the outputs can declare.

React's useState, Solid's createSignal, Angular's signal and fields declare a value's type from what the source gives them. So ref() with neither a type argument nor an initial value holds undefined and nothing else to them, and a setup let without an annotation and without an initial value (or with only undefined or null) has no type at all. A setup let without an initial value holds undefined until code assigns it, and React's useRef and Qwik's useSignal declare it so: its annotation admits undefined, with a ! too.

const selected = ref();          // rejected
const selected = ref<string>();  // accepted
let timer;                       // rejected
let timer: ReturnType<typeof setTimeout>; // rejected
let timer: ReturnType<typeof setTimeout> | undefined; // accepted

State that may hold a function is reported too: React's setter calls a function it is given as an updater, and useState one as its initialiser. Keep the function in a local function, and in state what decides it.

UF2022 function-value

Error. A local function is called, or passed as a call's argument in client code.

The targets write a local function their own way: Angular as a method of its class, Qwik as a QRL. So code calls a local function; client code also passes one as a call's argument (setTimeout(tick, 100)), which Angular's output wraps. A template, a getter and an initial value only call one, and pass a function only as an arrow function written in the call (items.filter((item) => item.on)).

A watcher's, an effect's or a hook's callback, and a watcher's getter, are written in place:

onMounted(focusField);              // rejected
onMounted(() => focusField());      // accepted

The safe fix wraps a local function passed to onMounted, onUnmounted, watch or watchEffect by name in an arrow function that passes it the callback's arguments.

UF2023 read-before-declaration

Error. Code the setup runs reads only what is declared before it.

React's and Solid's outputs evaluate an initial value, a getter (useMemo, Solid's eager createMemo), a watcher's source and an immediate watcher's first callback where the source declares them, in order: one that reads a binding declared after it throws a ReferenceError there, while Vue's lazy computed hides it. So that code, and the local functions it calls, read and call only the props and the bindings declared before it.

const total = computed(() => net.value + tax.value); // rejected: `tax` comes next
const tax = computed(() => net.value * 0.2);

Declare what it reads first. A function declaration is hoisted, so code may call one declared after it, as long as what that function reads and calls is declared before the code; an arrow function in a const is not hoisted. Client code (handlers, callbacks, hooks) runs later, and may read any binding. A module computes its top-level consts in order too, as it loads, so a constant's value reads only the constants declared before it, itself or through the functions it calls; only a function's body, which runs once called, may read one declared after it.

UF2024 unsafe-local-call

Error. A local function that touches state is called directly, and never recursively.

Qwik's output makes a local function that touches state (reads or writes a binding, emits, reads a template ref) a QRL, whose calls it awaits. So client code calls such a function directly in the body of a handler, a callback, a hook or a local function, in an async arrow function, or in a callback that runs later (a timer's, a promise's then, onCleanup's), never inside an arrow function that runs at once and whose result counts (an array method's callback, a comparator). It passes the function only to a call that runs it later (setTimeout, addEventListener) or never runs it (removeEventListener, clearTimeout). A function that returns a promise (async, or annotated Promise<…>) may be called and passed anywhere: a QRL's call gives a promise of the same value, so await Promise.all(files.map(upload)) collects the same results. Local functions never call themselves, directly or through each other.

function markAllRead() {
  unread.value.forEach((subject) => markRead(subject)); // rejected
}

Call it from the body itself, or compute the new state at once and write it.

UF2025 non-canonical-call

Error. nextTick is called bare and awaited, never given a callback or used as a value.

await nextTick() is the one way to wait for the DOM to update (ADR-0007). Vue and Svelte also run a callback given to nextTick once the DOM has updated, but React's, Angular's and Qwik's outputs declare nextTick as a function that returns a promise and takes no callback, which would never run.

function copy() {
  done.value = true;
  nextTick(() => emit("copied")); // rejected
}
async function copy() {
  done.value = true;
  await nextTick();               // accepted
  emit("copied");
}

Make the function async, await nextTick(), and write the callback's code after it. The safe fix does so where the call is the last statement of a handler, an onMounted callback, a watcher's callback that is not immediate, or a local function nothing calls, and the callback is an arrow function without parameters. nextTick().then(…) stays: every target's nextTick returns a promise.

Each target writes its own call in place of nextTick(), so nextTick is also called bare: not passed or stored as a value (.then(nextTick), const wait = nextTick), which leaves no call to replace (write () => nextTick() where a function is passed), and not called through parentheses, an assertion or type arguments ((nextTick)()), which the safe fix writes bare.

UF2026 unsafe-teardown

Error. Teardown code reads no template ref, and does not wait.

The targets tear a component down in different orders. Vue empties a template ref while it removes the elements, before onUnmounted runs, and React detaches it before an effect's cleanup runs; Svelte, Angular and Qwik still hold the element there. So an onUnmounted callback, a watcher's or watchEffect's onCleanup callback, and the local functions they run (call, or pass to a call that runs them, now or later) read no template ref: what they would see depends on the target. A listener they remove (removeEventListener(type, onClick)) does not run there: it reads the element when its event fires, while the component is mounted.

An onUnmounted callback is not async, and calls no async local function: Vue drops an emit once the component is unmounted, and the other targets deliver it.

onUnmounted(() => {
  emit("closed", grid.value?.childElementCount ?? 0); // rejected
});

Read the element in the callback that sets up the work (onMounted, the watcher's callback) and keep it in a local or a setup let, which the teardown reads. Do the async work before the component unmounts.

UF2027 self-triggering-effect

Error. watchEffect writes no state it reads.

Vue ignores what an effect writes while it runs, so a watchEffect that writes a ref it reads runs once for each change. Svelte, Solid, Angular, Qwik and React track what the effect reads, and run it again after its own write, without end: Svelte and Solid throw, Angular stops its change detection, and Qwik's page freezes. Only what runs while the effect runs counts: its code up to an await, the same part of the local functions it runs at once, and the computed values it reads; count.value++ reads count as it writes it. A function it hands to a timer, then, addEventListener, an observer or onCleanup, written in place, held in a local const or named (setInterval(tick, 1000)), and what follows an await, run after it, which no target tracks.

watchEffect(() => {
  history.value = [...history.value, count.value]; // rejected
});
watch(count, (value) => {
  history.value = [...history.value, value];       // accepted
});

Watch the sources with watch, whose callback is untracked: it reads and writes what it needs.

UF2028 invalid-model

Error. defineModel takes a free name and static options.

const open = defineModel<boolean>("open", { default: false }) declares a model: a prop a parent may bind two ways with v-model:open. Every target names the prop and its update event after the model, so the name is a camelCase string literal, and the options, default and required, are static values, as a prop's default is. The name is also free: a component declares each model once, apart from its props, and from an event named openChange, whose callback (onOpenChange, and onOpenChange$ on Qwik) would be the model's too.

const open = defineModel<boolean>({ default: false });         // rejected
const open = defineModel<boolean>("open", { default: false }); // accepted

Name the model, and rename it where the name is taken. The safe fix names a nameless model "value".

UF2029 invalid-slots

Error. defineSlots declares optional slots, named apart from props, models and events.

const slots = defineSlots<{ default?(): Element; item?(props: { item: Item }): Element }>() declares the slots a parent may fill, in one call. Each member is optional, since a parent may leave any slot empty, and a method whose one parameter, if it has one, is a scoped slot's props. Each slot is declared once, with a camelCase name.

React, Solid, Qwik and Astro pass a slot as a prop, so a slot's name differs from every prop's and model's, and from an event's callback (onClose for close). React, Svelte and Solid pass the default slot as children, so no other slot takes that name.

Make each member an optional method, and rename a slot whose name is taken. The likely fix renames a children slot to content.

UF2030 invalid-expose

Error. defineExpose takes an object of the component's local functions.

defineExpose({ focus, clear }) lists what a parent may call through a ref on the component. Each target exposes functions in its own way (an imperative handle, a public method, a signal), so the argument is an object literal of the component's local functions, each in shorthand: no state, no computed value and no function written in place.

defineExpose({ focus, count });                      // rejected: `count` is a ref
defineExpose({ focus: () => input.value?.focus() }); // rejected
defineExpose({ focus, clear });                      // accepted

Declare each exposed function in the setup, and list it by name.

UF2031 invalid-options

Error. defineOptions takes a static { inheritAttrs: false }.

defineOptions({ inheritAttrs: false }) stops a parent's class and style from falling through to the component's root. It is the one option every target can honour, and the compiler must know it when the component compiles, so the argument is that object literal and nothing else.

Remove any other option, or the call where fallthrough should stay on.

UF2032 invalid-context

Error. provide and inject take an injection key, inject first.

provide(ThemeKey, theme) and const theme = inject(ThemeKey, fallback) share a value with every descendant. Each target turns the key into its own context (a React or Solid context, an Angular InjectionToken, a Qwik context id), so the first argument is an injection key, by its name, never a string, and the key types the call, which takes no type arguments. A component provides each key once. One that injects and provides a key reads its parent's value, as in Vue, so its inject comes before its provide.

A key of a Ref, a ComputedRef or a ModelRef, such as InjectionKey<Ref<number>>, shares the ref itself, which stays reactive where it is injected. So provide and inject's fallback take a binding of the setup by its name: a ref, a computed or a model for a Ref, a computed for a ComputedRef, and a model for a ModelRef. Its inject takes that fallback, which code reads where no ancestor provides the key.

provide(ThemeKey, theme);
const parent = inject(ThemeKey); // rejected: after its `provide`

Pass the key itself, move the inject before the provide, and give a ref's key a ref.

UF2033 invalid-injection-key

Error. An injection key is an exported InjectionKey Symbol of a .uf.tsx module.

Each target writes a key in its own form into the output of the module whose component provides it. So a key is an exported top-level const of a .uf.tsx module, declared alone, typed InjectionKey<T> with the type of what it provides, and initialised with Symbol and a string literal that describes it.

export const ThemeKey: InjectionKey<Theme> = Symbol("acme.theme");

Passing anything else to provide or inject, such as a string or a value imported from a shared .ts module, is UF2032: a key lives in the .uf.tsx module that provides it. Qwik uses the description as the context's id, so two keys with one description collide: give each key a namespaced description.

UF2034 context-write

Error. An injected value is read-only.

inject gives the value an ancestor provides. A write to it would change the provider's state behind its back on some targets and nothing on others, so code never writes an injected value, nor one of its members.

Provide a function beside the value, and call it to ask the provider to change its state.

UF2035 invalid-composable

Error. A composable is a named use* export that returns a shorthand object.

A .uf.ts module holds composables: named exports whose names start with use and an upper-case letter, each a setup under the rules of a component's, with no JSX (ADR-0069). Each parameter is annotated, and its type says how the body reads it: a value once, a getter (() => T) as it changes, and a callback from client code. The last statement returns a shorthand object of the state, derived values, functions and constants a caller may use.

import { ref } from "@uxfront/unframework";

export function useToggle(initial: boolean) {
  const on = ref(initial);
  function toggle() {
    on.value = !on.value;
  }
  return { on, toggle };
}

A composable cannot call useId, useTemplateRef, provide, inject, a define* macro or another composable, be a default export, or return anything but a shorthand object. Move what needs them into the component that calls the composable, and pass it in as an argument.

UF2036 composable-result-write

Error. A ref a composable returns is read-only to its caller.

A component reads a ref a composable returns through .value, and never writes it: on some targets the caller holds the value its render reads, apart from the composable's state, so a write would change one and not the other (ADR-0069).

Return a function from the composable that changes its state, and call it:

const { on, toggle } = useToggle(false);
on.value = true; // rejected
toggle();        // accepted

UF2037 invalid-directive

Error. A directive is a top-level const that defineDirective initialises.

A directive packages a behaviour an element takes (ADR-0099). It is declared once, at the top level of a module: const vName = defineDirective<T>({ … }), with a name that is v and an upper-case letter. A .uf.ts module exports it, and a component imports it by name. A component's own .uf.tsx module may declare one for its components alone.

import { defineDirective } from "@uxfront/unframework";

export const vAutofocus = defineDirective<boolean>({
  mounted(el, value) {
    if (value) el.focus();
  },
});

The type argument, the value's type, is required, and the object holds the hooks as methods: mounted(el, value), updated(el, value, oldValue) and unmounted(el), at least one of them, with parameters that take their types from the type arguments. The hooks run in the browser only, so they read their parameters, their own names, the browser's globals, the module's constants and the values it imports. They never call the authoring API or read a component's state. The names of Vue's own directives, like vShow, are reserved.

UF2038 nested-await

Error. An await in the setup is the whole value of a const.

An async component awaits at the top level of its setup, and only as the whole value of a const that declares one name (ADR-0101). Each target lowers that declaration its own way: Vue and Svelte await it in place, React and Solid run the awaits in a function of their own, Angular continues the setup after them and Qwik reads each through a derived value. An await inside a larger expression, a destructuring, a let, a bare statement, a block or a condition has no such form on every target.

const user = await loadUser(props.id);       // accepted
const { name } = await loadUser(props.id);   // rejected
const name = (await loadUser(props.id)).name; // rejected

Declare each awaited value with a const of its own, and read its members after it. An await inside a function the setup declares, such as a handler, is client code, and stays allowed.

UF2039 late-await

Error. The awaits open the setup, and read only props and module values.

An async component's awaits come first in its setup, before any state, constant, function, watcher, hook, provide, inject, useId, template ref, model or composable call, and an awaited expression reads only props, the module's values, globals and the values awaited before it (ADR-0101). React and Solid run the awaits in a function of their own, outside the component's render, and Qwik runs the body again up to each await, so the setup's other items are not there yet.

const user = await loadUser(props.id);
const team = await loadTeam(user.teamId); // accepted: it reads an earlier await
const visits = ref(user.visits);          // accepted: the items follow the awaits

Move the await above the other items, and compute what it needs from the props there. The macros defineEmits, defineSlots, defineExpose and defineOptions may sit anywhere, but an awaited expression never reads emit, a slot or a model.

JSX and cross-component usage

UF3001 unknown-element

Error. The element is not an HTML element.

Lower-case JSX tags are HTML elements, and the compiler emits them unchanged into every target. A tag that HTML does not define, an obsolete one (<center>, <marquee>) or one in the wrong case (<dIV>) would be read differently by each framework: Vue resolves it as a component, Angular rejects it, and the browser renders an unknown element.

Inside an <svg>, tags are SVG elements in SVG's own case (linearGradient, clipPath): an HTML element there, or an SVG element outside an <svg>, is reported too.

Use the HTML or SVG element; a misspelt case has a fix. Components are PascalCase (<Card>).

UF3002 reserved-element

Error. A component cannot render this element.

Some elements belong to the document or to a framework's template syntax, not to a component's markup:

  • <html>, <head> and <body> are the document's; the browser drops them inside one.
  • <title>, <meta>, <link> and <base> describe the document: React moves them into the <head>, and the other frameworks leave them in place.
  • <script> and <style> hold code the compiler cannot analyse; Vue and Angular drop them. A component's styles are a stylesheet it imports. This holds inside an <svg> too.
  • <template>, <slot>, <component>, <transition> and Angular's <ng-…> elements are template syntax in one framework or another.
  • SVG's animation elements (<animate>, <animateMotion>, <animateTransform>, <set> and <discard>) make the rendering depend on time, and <animate> and <set> can set any attribute, a javascript: href included.

UF3003 invalid-nesting

Error. The browser or a framework would repair this markup.

The HTML parser repairs some nesting: a <div> closes an open <p>, a <tr> directly in a <table> gets a <tbody>, text in a table moves out of it, and a void element such as <br> cannot hold children. Server-rendered HTML then becomes a different tree from the one a client renderer builds, and Svelte, Vue and React each report it. Svelte's compiler also drops whitespace on its own inside a <select> or a <datalist>.

The rules see through conditionals, lists and fragments: rows that a .map renders directly in a <table> get a <tbody> too. An expression renders text, so it cannot sit where text cannot (a table part, a <select>), and inside an <svg> only <text>, <tspan>, <textPath>, <title> and <desc> render text. Svelte drops whitespace-only text in SVG outside a <text>, so it is reported there too. SVG's <title> and <desc> hold text only: the HTML parser and Vue read an element inside them as HTML, and React as SVG.

The parser reads an <iframe>'s content as raw text, decoding no character reference and reading no comment, so text other than whitespace, an expression or a conditional there renders the servers' escapes and markers as text, which a client render does not. A browser never shows that content: remove it.

Write the markup the parser keeps: wrap rows in <tbody>, use a <div> where a paragraph would contain blocks, and put options on lines of their own.

UF3004 non-canonical-attribute

Error. The attribute is not written in its canonical form.

Each attribute has one way to be written (P3):

  • HTML names, in lower case: class, for, tabindex, not className, htmlFor or tabIndex.
  • A boolean attribute without a value: disabled, not disabled="" or disabled="disabled". Its presence turns it on: disabled="false" is still disabled.
  • A value for every other attribute: in JSX a bare attribute means the string "true", which is only meaningful for ARIA states, data-* and true/false attributes.
  • Numbers in canonical form (3, 0.5): some renderers set these attributes as DOM properties, which rewrites any other spelling.
  • No class rather than an empty one: Vue renders class="", the others leave it out. (Whitespace between class names needs no fix: the compiler writes one space.)
  • A literal as a literal: title="x", not title={"x"}; disabled, not disabled={true}; no attribute rather than {false}, {null} or {undefined}; class="a b", not class={["a", "b"]}; the attributes themselves, not a spread of an object literal.
  • Style keys in camel case (marginTop), as React's and Vue's style objects write them.
  • href, not SVG's old xlink:href.
  • key, in lower case, on a list's element: in JSX KEY is an attribute; and ref, in lower case.
  • A listener named as Vue names it, on and the DOM event's name: onKeydown and onDblclick, not React's onKeyDown or onDoubleClick, nor onclick in lower case.
  • No spread that renders nothing: of a type that declares no keys, or of a source that a condition around the spread shows is absent ({attrs ? null : <p {...attrs} />}).
  • An enumerated attribute's keyword in lower case (dir="rtl", not dir="RTL"), and the keyword HTML reads an empty value as (spellcheck="true", popover="auto", a <button>'s type="submit"): the targets' types take only those spellings.

The fix rewrites the attribute where the rewrite is mechanical.

UF3005 reserved-attribute

Error. The attribute belongs to a framework.

The attribute is syntax or data of one of the target frameworks, so that framework would not render it as an attribute:

  • Angular binds bind-*, on-*, bindon-*, ref-* and let-*, consumes i18n and reserves ng* names.
  • slot and is are template syntax in Svelte, Astro and Vue.
  • children, dangerouslySetInnerHTML, textContent and React's suppress… props are framework props, not attributes; write the content as JSX children.
  • data-hk, data-astro-*, data-v-*, data-qwik-* and data-uf-* are attributes that frameworks or the compiler add themselves, and ids starting with uf-id- are the ones the compiler generates.
  • xmlns, xmlns:*, xml:* and xlink:* (but xlink:href, which is href) are XML's: every target writes SVG's namespace itself, and the HTML parser and the clients disagree about namespaced attributes.

UF3006 unknown-attribute

Error. The attribute is not an attribute of this element.

Elements take HTML's attributes: the global ones (id, class, title, hidden, …), their own (href on <a>, alt on <img>), ARIA's role and aria-*, and data-*. SVG elements take SVG's attributes, in SVG's own case (viewBox, stroke-width). Frameworks treat other names inconsistently: Vue sets a name that matches a DOM property as that property, and React and Solid give some names meaning of their own.

Use the element's attribute, or a data-* attribute for your own data.

A listener (onClick) listens to an event an element receives: not one only the window receives (onHashchange), not one no target listens to alike (onSelectionchange), with one option suffix at most (Capture, Once or Passive), and Passive only on wheel, touchstart and touchmove, where it lets scrolling go on.

UF3007 duplicate-attribute

Error. The element has the same attribute twice.

Attribute names are case-insensitive in HTML, and className is class. With the same attribute twice, React keeps the last value, the HTML parser the first, and Vue and Svelte fail to compile. Keep one.

A spread sets every key its type declares, so a key that is also written on the element, or set by another spread, is set twice too. class is the exception: one spread's class merges with the element's own. A class name listed twice in one class is reported as well: Angular merges a static class with a bound one through the class list, which drops the repeat the other targets keep. The fix lists a static class's names once. So is a second key on a list's element: the list has one key.

UF3008 unportable-attribute-value

Error. The targets would render this attribute value differently.

Some values cannot be rendered the same way on every target, and some hold code or a document the compiler cannot analyse, which it never copies into an output:

  • javascript: URLs run code the compiler cannot analyse, and React blocks them. Event handlers are the way to run code.
  • srcdoc holds an HTML document, scripts included, which the frame runs as the page's own origin unless it is sandboxed. A data: URL that a frame loads (an <iframe>'s or an <embed>'s src, an <object>'s data) is a document too. Load the document from a URL, or write its markup in the component. data: images and media, and blob: URLs, hold no code the page runs, and are accepted.
  • An empty src, or an empty href outside <a>: React drops it and warns.
  • hidden="until-found": React renders hidden as a boolean.
  • A number out of range, or not a number, in a numeric attribute (rows, span, <li value>): renderers that set the DOM property rewrite or reject it.
  • A class name holding whitespace other than ASCII's (a no-break space): Angular splits class names there, and the other targets keep it in the name.
  • An attribute that React and Qwik type as a number (tabindex, colspan, aria-level) with a value that is not one: they write it as a number literal.
  • An ARIA value ARIA does not define (aria-hidden="yes", aria-live="loud"), or a role that is not one of ARIA's roles: assistive technology ignores it, and Svelte warns about it.
  • A value of an enumerated attribute that some target's types do not list (a <bdo>'s dir="auto", role="generic", autocomplete="bday", a <button>'s type="menu"): that target's output fails its type-check. The message lists the values every target takes.

UF3009 ambiguous-jsx-text

Error. JSX implementations read this text differently.

JSX does not define its text exactly, and its implementations disagree. Babel (which Vue's and Solid's JSX use) decodes character references first and then trims the lines, trimming only spaces and tabs. TypeScript, oxc and esbuild trim the raw lines first, also trimming Unicode whitespace such as a no-break space, and read U+2028 and U+2029 as line breaks. So &#32; at the end of a line, &#10;, a tab, or a raw no-break space next to a line break means one thing to some tools and another to the rest.

The compiler lowers text only where every implementation agrees. Write such characters as references (&nbsp;), write a space for a tab, and keep a significant space on the same line as the text it separates. Numeric references the implementations decode differently (&#+65;, a surrogate such as &#xD83D;, a number past U+10FFFF) are reported too, in attribute strings as well.

UF3010 unportable-character

Error. HTML would not keep this character.

Each target renders the component's markup on the server as HTML, and the browser parses it, so a static value must hold only characters the HTML parser keeps as they are:

  • a carriage return becomes a line feed (Svelte's compiler converts it too); in a file with CRLF line endings, a value written across lines holds one;
  • NUL (U+0000) is dropped from text and replaced in attribute values;
  • a lone UTF-16 surrogate cannot be encoded in UTF-8;
  • the control characters other than whitespace, and the noncharacters, are not allowed in an HTML document.

Remove the character. A carriage return from a line ending has a fix.

UF3011 html-only-reference

Warning. JSX does not decode this HTML character reference.

JSX decodes only the named character references of XHTML 1.0 (&amp;, &nbsp;, &copy;), and numeric ones (&#x2713;). The names HTML added later (&check;, &rbrace;, &NewLine;) stay as written: every target renders &check; as those seven characters, where an HTML or Vue template would show ✓.

Write the numeric reference for the character (the fix, where it changes nothing else), or &amp;check; for the text itself.

UF3012 jsx-outside-template

Error. JSX can only be in a component's template.

A component's template is the JSX its last statement returns, with the slot functions in it. The compiler lowers that tree to each target's template, and Vue's, Svelte's and Angular's templates are not JSX: they have no counterpart for JSX kept in a variable, returned from a helper, passed as a prop that is not a slot, or used as a value (an attribute's value, a function's argument, an array's element). JSX can be a child, a branch of a conditional child (c ? <A /> : <B />, c && <A />) or the element a .map child renders.

function renderIcon() {
  return <i class="icon" />; // rejected: a helper that returns JSX
}

Inline the JSX where it is used, move it into a slot function, or extract a component.

UF3013 missing-key

Error. A list's element needs a key.

A .map child renders one element per item, and the frameworks match the elements of two renders by their key. Without one, React warns and the targets disagree about which element an item keeps.

{items.map((item) => <li key={item.id}>{item.name}</li>)}

Key the element by something unique and stable in the item. The fix keys it by its index, which is unique but moves with the item: review it.

UF3014 misplaced-key

Error. A key belongs on the element a list renders.

key is not an attribute: it tells the frameworks which item of a list an element renders, and only the element a .map callback returns has one. Elsewhere React and Vue use it to remount an element and the others ignore it. A constant key on a list's element gives every item the same key.

The fix removes a misplaced key, and keys a list's element by its index.

UF3015 invalid-list

Error. A list is written source.map((item, index) => <element key={…}>…</element>).

A .map child lowers to each target's list: Vue's v-for, Svelte's {#each}, Angular's @for. Its callback is an arrow function with one or two plain parameters, the item and its index, that returns one element:

{users.map((user, index) => (
  <li key={user.id}>{index + 1}. {user.name}</li>
))}

Read an item's members as item.name rather than destructuring it (an entry of Object.entries as entry[0] and entry[1]), and wrap several elements in one. An item that renders or not is filtered out before mapping (users.filter((user) => user.active).map(…)); one that renders one element or another keeps one keyed element that holds the conditional (<li key={link.id}>{link.href ? <a …>…</a> : <span>…</span>}</li>).

UF3016 non-text-interpolation

Error. An expression child must render text.

An expression child renders its value as text. JSX renders true, false and arrays its own way, and the template targets render them as text ({{ true }} is "true" on Vue), so an expression child must be a string or a number, or null or undefined, which render nothing.

Turn the value into text: done ? "Done" : "Open" for a boolean, .join(", ") or .map(…) for an array, a member for an object. A literal {true} or {false} child renders nothing: remove it.

UF3017 dropped-line-feed

Error. The HTML parser drops a line feed at the start of this element.

The HTML parser drops a line feed that starts a <pre>, a <textarea> or a <listing>, and React's server renderer writes one more to keep it. Server-rendered HTML and a client render then disagree about the first line.

A text after a conditional or a list that can render nothing starts the element when it does: React's and Astro's servers then write nothing before it, so the parser drops its line feed, and the other targets write a comment, which keeps it.

Start the element's text with something other than a line feed.

UF3018 unportable-binding

Error. The targets render or type this bound value differently.

A bound value renders by the rules of where it is bound, and the targets agree only for some kinds of value:

  • a boolean attribute (disabled) takes a boolean; ARIA's true/false states (aria-hidden), draggable and spellcheck also take booleans, as "true" and "false";
  • an attribute some target's types restrict to a list of tokens (autocomplete, inputmode, role, aria-live, SVG's fill-rule) takes a string literal, or a union of them, that every target's types accept: the diagnostic lists them;
  • data-* and other attributes take strings and numbers: Qwik drops false there, React drops it on some, and the others write "false" (write String(value));
  • an attribute React and Qwik type as a number (tabindex, colspan) takes a number, and one some target's types declare as a string (title, id, aria-label, SVG's d) takes a string;
  • a class name takes a string, a style value a string, or a number where CSS needs no unit (opacity, line-height): React and Qwik add px to other numbers but 0, and Qwik also to SVG's stroke and opacity properties (stroke-width), which React leaves bare. A literal 0 is the value 0 on any property;
  • a list's source is an array, and its key a string or a number that reads the item or its index: a key that reads neither is the same for every item, which Vue and Svelte reject. It identifies the item within its own list, so it reads no variable of a list around it: Angular's track reads only its own item, $index and the component's members. A source that can be absent is defaulted, (items ?? []).map(…), which the fix writes for items?.map(…).

null and undefined leave the attribute or the declaration out everywhere, but for a value some targets set as a property (an <li>'s, a <meter>'s, an <option>'s: UF1002). Convert the value, or bind it where its kind renders alike.

UF3019 nondeterministic-render

Error. Rendering must not depend on time, chance or the machine.

A component renders on the server and again in the browser, and both renders must give the same markup (plan §4.5): rendering is a function of props, state and slots. Date, Intl, crypto, performance, globalThis and Math.random read the clock, chance or the machine, and toLocaleString, toLocaleDateString, toLocaleTimeString, toLocaleUpperCase, toLocaleLowerCase and localeCompare read the machine's locale.

The rule holds for what rendering reads too: a getter (a computed's, a watcher's source), an initial value (of a ref, a const, a let), which the setup runs on the server as well, and a local function a template, a getter or an initial value calls. Client code (a handler, a watcher's callback, a lifecycle hook) runs only in the browser, and may read them.

Pass the value in as a prop, computed where it is decided, or set it from client code.

UF3020 unresolved-reference

Error. The name is no prop, setup binding, list item or global code can read.

An expression in the template reads the component's props, the bindings its setup declares, the item and index of the lists around it, the parameters of the arrow functions in it, and a few pure globals: undefined, NaN, Infinity, Math, Number, String, Boolean, Array, Object, JSON, parseInt, parseFloat, isNaN, isFinite and the URI functions. The targets can reach nothing else: Angular's templates see only the component's members, and the outputs run where window may not exist.

Setup code reads more. A getter and an initial value also read Map, Set, WeakMap, WeakSet, Symbol, the error constructors and structuredClone; client code (a handler, a watcher's callback, watchEffect, a lifecycle hook) also reads every global lib.dom declares (document, localStorage, location, history, fetch, URL, URLSearchParams, FormData, AbortController, the observers, HTMLInputElement, KeyboardEvent, …), console, Promise, Date, Intl, performance and crypto, since it runs only in the browser, where every target runs it as written. It reads through window the members whose bare name reads like the component's own (name, status, top, length, event, open, close, focus, innerWidth, scrollY, the on… handlers, …), which a missing declaration or a typo would read silently: the likely fix writes window.innerWidth.

A module's top-level const reads the module's other constants, the values it imports from shared .ts modules and the globals a getter reads: the module computes it as it loads, on the server too.

Declare the value as a prop or in the setup, or check the name's spelling.

UF3021 impure-render-expression

Error. A template expression must not change anything.

Rendering is a pure function of props, state and slots (plan §4.5): a framework renders when it decides to, sometimes twice, and Svelte throws when a template expression changes state. So a template expression cannot assign, update or delete, use this, await, yield, void or the comma operator, define a function or a class, or call a method that changes its receiver: sort, reverse, splice, push, pop, shift, unshift, fill, copyWithin, and Object.assign and its kin.

Use the methods that return a new array: the fix writes toSorted, toReversed and toSpliced. An arrow function is a call's argument (items.filter((item) => item.on)).

The rule is the template's. A handler is no template expression: it runs on an event, and may write state and emit, as statements of their own (UF2011, UF2017).

UF3022 invalid-class-or-style

Error. The class or style is malformed.

A class and a style are lowered part by part, and every target writes the parts its own way, so each part must be one the targets read alike:

  • class and style objects have plain keys: no computed keys, spreads or methods;
  • a style string parses as CSS declarations, and a style sets something;
  • each property is one the browsers know (or a custom property, --gap): an unknown name is almost always a typo, which no browser applies and Solid's lint rejects;
  • a custom property's name is in lower case: Angular's compiler and its server renderer lowercase it, so var(--myGap) would not find --myGap there;
  • a style sets each property once, and never a shorthand beside one of its longhands (margin and marginTop), or a flow-relative property beside a physical one it can be (marginInlineStart and marginLeft): React's, Solid's and Qwik's style objects cannot keep the order that decides the result;
  • no !important, which React's style objects drop;
  • a static value reads the same to Angular's style parser, which knows no escapes or comments: a string holds no escaped quote of its own kind (put the other quote around it), the parentheses inside strings balance (write \28 for a lone one), and a comment holds no quote, parenthesis or ;.

Write each property once, with its final value.

UF3023 non-nullable-operand

Error. The operand of ?? or ?. is never null or undefined.

a ?? b and a?.b act only when a is null or undefined. When a can be neither where it is read, the operator does nothing, and Angular's compiler rejects it (NG8102, NG8107). a can be neither when its type excludes both, or when a condition around it rules them out as TypeScript narrows it: a test of a itself, through !, && and ||, a comparison with null, undefined or a value, typeof, a member read through ?., Array.isArray, or a discriminant of the union a belongs to:

{box.inner && <p title={box.inner?.title}>…</p>} // reported: write `box.inner.title`

Remove the operator, which the fix does, or make the prop optional if it can be absent.

Where the targets' checkers may read a apart, the compiler reports, as not supported yet (UF1002), a use that relies on a narrowing some of them do not see: a member, or a prop of the object form, a condition narrows outside a list's callback (Angular's loops keep the narrowing, the JSX targets' callbacks forget it); a prop an expression's own conditional narrows, used in an arrow function in it (Solid copies it with props.x, which the closure forgets); and a prop a list's key uses (Angular's track reads the input again). Testing the value, reading it through ?., giving it a value with ??, comparing it for equality and writing it into a string read alike everywhere. Where the compiler does not follow a test (an equality with a value that is no literal), Angular may narrow a and reject the operator, which is reported too. A destructured prop a conditional child narrows stays narrowed in its branch's lists and arrow functions on every target. Reading a member of a value a condition shows absent is reported as well.

A ref, a local function and a handler's event are never null or undefined either: count?.value and event?.key are reported, with the fix that writes ..

UF3024 shadowed-binding

Error. A parameter or a local shadows a name the outputs read, or is never read.

The targets rewrite the names a template expression reads: Solid reads a prop label as props.label, and Angular reads the template variable it declares for it, @let label = this.label();. A .map or arrow function parameter that has the name of a prop, of the object form's props parameter, of the item or index of a list around it, of a global an expression may read (String), the name props or rawProps, a name starting with $ (Angular's @for declares $index, $count and others), Fragment (Astro's output imports it to render <>) or a name starting with _ but _ itself (Vue's compiled render functions declare _ctx, _cache, __props and helpers such as _toDisplayString) would capture those rewrites or those names. A parameter named after one of Angular's expression keywords (as) cannot be read in its templates at all. Rename the parameter.

Setup code and handlers follow the same rule for their functions' parameters, and their consts, lets and catch parameters take no name of a prop, of the props parameter, of a binding of the setup (emit included), of a list variable around them, nor props or rawProps: the targets rewrite those names in the code (count.value to count(), a prop to props.label), and cannot rename a local.

An arrow function's parameter that nothing after it reads fails the outputs' lint (no-unused-vars). The fix removes it. (A list's unread index needs no fix: the targets leave it out.)

UF3025 unsupported-conditional

Error. A conditional child is written c ? <A /> : <B /> or c && <A />.

x || <B /> and x ?? <B /> render either the value of x or an element, which no template target can express as one conditional. Write the conditional with ?:: x ? x : <B /> for ||, and x != null ? x : <B /> for ??, which renders 0 and "" as ?? does.

{message ? message : <p>All good.</p>}
{count != null ? count : <p>None yet.</p>}

When x is a prop or a member of one that renders as text, the fix writes the conditional.

UF3026 ref-without-value

Error. A ref's value is read as .value.

A ref (ref, computed, useTemplateRef) holds its value in .value, which code reads and writes: count.value. Vue's templates unwrap a ref, so {count} renders its value there, but the other targets keep the value apart (React's count is the value, Solid's count(), Angular's this.count()), so the compiler reads count.value alone, as one name.

<output>{count}</output>       // rejected
<output>{count.value}</output> // accepted

The fix reads .value. A ref is passed whole only where an API takes it: a watcher's source (watch(count, …)) and a template ref's element (ref={input}). A ref has no member but value, and is never null or undefined (count?.value is UF3023).

UF3027 invalid-template-ref

Error. A template ref is attached by the ref of one element, outside lists.

useTemplateRef<T>() declares a template ref, and ref={input} on an element attaches it: once the element is mounted, client code reads it as input.value. A template ref holds one element, so exactly one element attaches it, outside every list: in a list, Vue fills it with an array of elements and the other targets with the last one.

const input = useTemplateRef<HTMLInputElement>();
// …
<input ref={input} />

The compiler reports a ref whose value is no template ref (a string, as Vue writes it, a callback, another binding), and a template ref attached twice, inside a list, or never.

UF3028 template-ref-use

Error. Client code never rebuilds a rendered element by hand.

Every framework renders its elements from state, so client code does not change a rendered element's structure or its text: textContent, innerHTML, innerText, outerHTML, outerText, append, appendChild, prepend, remove, removeChild, replaceChild, replaceChildren, replaceWith, insertBefore, insertAdjacentElement, insertAdjacentHTML, insertAdjacentText, before, after and normalize (eslint-plugin-svelte's no-dom-manipulating). Nor does it change the classes of an element whose class the template binds (classList.add(), className, setAttribute("class", …)), or the style of one whose style it binds (style.color, style.setProperty()): each framework patches what its template binds its own way, so Angular keeps a class it did not add and Qwik drops a style property it did not set. Bind the class or the style to state instead, or make the change on an element whose class or style the template leaves alone. A class, a style or an attribute the template does not bind is the code's own on every target (an autosizing textarea's style.height, setAttribute("aria-busy", …), dataset.x), and so is any attribute: each target compares a bound attribute with the value it last wrote, not with the DOM's.

A rendered element is a template ref's, the handler's event's currentTarget and target, and any node reached from one (parentElement, firstChild, querySelector(…), the items of querySelectorAll(…) and children, in a loop or an array method's callback), itself or through a local. An element of a template ref is judged by the elements the ref is attached to, a listener's event.currentTarget by the elements whose listeners run it (a function used as several listeners, or passed the event, by each of them), its event.target by those and what they hold, and any other by every element of the template. Other properties and methods (focus(), select(), scrollIntoView(), showModal(), scrollTop, an input's value, measurements) are fine, as is the document's own <body>.

UF3029 invalid-handler

Error. A handler is a local function's name or an arrow function.

A listener (onClick, onKeydown) runs a handler: the name of a function the setup declares (onClick={save}), which receives the event as its first parameter, or an arrow function written in place (onClick={(event) => …}), whose one parameter is the event. Every target calls either with the event, and Angular makes each a method of its class.

<button onClick={save}>Save</button>              // accepted
<button onClick={() => remove(item.id)}>×</button> // accepted
<button onClick={save()}>Save</button>            // rejected: runs while rendering
<button onClick="save()">Save</button>            // rejected: code in a string

The compiler reports a call, a string, a conditional, a member, a function expression, emit, and a function whose first parameter does not take the event's interface: one it extends, or a union of interfaces that holds one (event: MouseEvent | KeyboardEvent on a function a click and a key share, whose members are those of the interface both extend). A handler in a list that reads the list's item or index, and a handler that reads a value a condition around it narrows ({user && <button onClick={() => greet(user.name)}>…</button>}), is one call of a local function or of emit, with arguments Angular's template statements read (() => remove(item.id)): Angular passes the item, or the narrowed value, to its method there. Writing the value is no read: {open.value && <button onClick={() => (open.value = false)}>…</button>} needs no narrowing, though a compound assignment (+=), ++ and a member's write do read it. A handler's return value is discarded on every target.

UF3030 inaccessible-handler

Error. A handler is reachable with the keyboard and announced.

A listener on an element a keyboard user cannot reach, or a screen reader does not announce as interactive, leaves them without the action. Svelte's compiler warns about it, which fails its check, so the compiler reports it for every target, judged on the source's listeners as Svelte 5.57.1's accessibility rules judge them:

  • a11y_click_events_have_key_events: a click handler on a non-interactive element without a keydown, keyup or keypress handler;
  • a11y_no_static_element_interactions: a handler for a mouse, pointer, touch, key or drag event on an element with neither semantics nor a role (<div>, <span>);
  • a11y_no_noninteractive_element_interactions: a click, mouse button or key handler on a non-interactive element or role (<li>, <p>, role="listitem");
  • a11y_interactive_supports_focus: a handler on an element with an interactive role (role="button") that is not focusable (no tabindex);
  • a11y_mouse_events_have_key_events: mouseover without focus or focusin, mouseout without blur or focusout.

Put the handler on a <button> or a form control. An element hidden from assistive technology (aria-hidden="true") and one with role="presentation" or role="none" are not judged.

UF3031 ref-narrowing

Error. A ref's value, or a prop in code, is read into a local before its union is narrowed.

Solid and Angular read a ref's value through a call (query(), this.query()), and Angular every input (this.size()), which TypeScript never narrows. A narrowing to a value that is there survives the call: where code relies on a condition or an assignment before it showing a ref's value, a prop or a member of either present (if (selected.value) emit("select", selected.value), if (!draft.value.email) return;, selected.value = member;), the targets that read it through a call or a mirror assert it (selected()!). A narrowing to one kind of a union does not: a ref's value, a prop or a member of either that is one of several kinds (string | number, string[] | string, "a" | "b") or of several object shapes is used where a condition narrows it (typeof, Array.isArray, ===, a discriminant) only as a member every kind has, a test, an equality's operand, a string's part, or an argument a parameter takes whole. It is read into a local, returned, assigned, or put in a literal that goes to a call, only before such a condition, or where the written type of the local, the result or the target holds every kind.

The same holds for a prop read in a getter, an initial value or client code: React and Solid read a prop as a property (props.size), whose narrowing TypeScript forgets in a nested function. The template reads props as it always has.

if (typeof query.value === "string") emit("search", query.value.trim()); // rejected
const text = query.value; if (typeof text === "string") emit("search", text.trim()); // accepted
if (selected.value) emit("select", selected.value); // accepted

A conditional child still narrows its branch on every target: Solid passes it an accessor, and Angular reads it through @let (`{typeof value.value === "string" &&

{value.value.trim()}

UF3032 event-parameter-use

Error. A handler reads only the members every target's event has.

React passes a handler its synthetic event, which has only some of the DOM event's members: it lacks isComposing, composedPath, stopImmediatePropagation, offsetX and others, and Qwik passes currentTarget apart. So a handler's event is used only as event.member, read or called, for a member both the DOM's and React's event of that listener have (key, code, the modifier keys, button, clientX, currentTarget, target, preventDefault(), …), or passed whole to a local function's event parameter; never read through a computed member, destructured, stored or passed elsewhere.

if (event.key === "Enter" && !event.isComposing) send(); // rejected: React lacks it

Read what every target has, or listen natively from onMounted through a template ref.

UF3033 deferred-event-control

Error. preventDefault() and stopPropagation() run while the event is dispatched.

event.preventDefault() and event.stopPropagation() act only while the browser dispatches the event. A call after an await, or in a function the handler hands on (a timer's callback, a promise's continuation), runs once the browser has acted on the event, on every target: the form is submitted, the key typed, the click passed on. Every other call runs in place, under whatever test or switch case it is in, beside other statements or after a guard clause.

Qwik runs a handler after the event, and runs at once only the controls it can lift out of it (preventdefault:click, sync$): those its tests and guard clauses decide from the event alone. Where Qwik cannot, it reports conditional-event-control (UF4001) at the control.

async function subscribe(event: SubmitEvent) {
  event.preventDefault(); // accepted
  await save();
  event.preventDefault(); // rejected: the form is submitted by then
}

function onKeydown(event: KeyboardEvent) {
  if (event.key === "ArrowDown") {
    event.preventDefault(); // accepted
    move(1);
  }
  setTimeout(() => event.stopPropagation()); // rejected: the event is over by then
}

Call it before the first await, under the same test if it is conditional, and in the handler itself rather than in what it defers.

UF3034 passive-prevent-default

Error. A passive listener does not call preventDefault().

A passive listener (onWheelPassive, onTouchstartPassive, onTouchmovePassive) tells the browser that it never prevents the event's default, so the browser scrolls at once and ignores its preventDefault(). The call prevents nothing on any target, and Angular, which runs an element's listeners of one event in one listener, runs a passive one beside one that is not passive in a listener that is not passive, where the call would prevent. So what a passive listener runs, its handler and the local functions it passes its event to, calls no preventDefault().

<div onWheelPassive={(event) => { event.preventDefault(); zoom(event.deltaY); }} /> // rejected
<div onWheel={(event) => { event.preventDefault(); zoom(event.deltaY); }} />        // accepted

Remove the call, or make the listener not passive where it must prevent the default. The safe fix removes the call from a handler written in place, and the listener where the call is all it does.

UF3035 unknown-prop

Error. The component declares no such prop (layer 2).

A component element passes props by name, and the compiler reads the child's declarations through its resolver. An attribute that is no prop, model or slot of the child, nor class, style, key or ref, is rejected: no target passes an undeclared attribute through to the child's root.

<Field lable="Name" /> // rejected: did you mean `label`?

Pass a prop the child declares. The likely fix renames the attribute to the closest prop.

UF3036 unknown-event

Error. The component declares no such event (layer 2).

onX on a component listens to an event the child declares with defineEmits, and its handler receives the event's payload. No target passes a native listener through to the child's root, so an onX the child does not declare is rejected.

Listen to an event the child declares, or to the native event on an element inside the child. The likely fix renames the listener to the closest event.

UF3037 unknown-model

Error. The component declares no such model (layer 2).

v-model:open binds a model the child declares with defineModel. A name the child does not declare is rejected.

Bind a model the child declares. The likely fix renames the binding to the closest model.

UF3038 unknown-slot

Error. The component declares no such slot (layer 2).

A parent fills the child's default slot with its children, and the other slots with a slot object, {{ title: () => <h2>Profile</h2> }}. A key the child does not declare with defineSlots, or children given to a child with no default slot, is rejected.

Fill a slot the child declares. The likely fix renames the key to the closest slot.

UF3039 literal-outside-union

Error. The value is not one of the prop's literals (layer 2).

A prop typed by a union of literals, tone?: "info" | "warning", takes one of them. A literal outside the union is rejected where the parent writes it.

<Badge tone="warn" /> // rejected: did you mean "warning"?

Pass one of the prop's literals. The likely fix replaces the value with the closest one.

UF3040 invalid-slot-content

Error. A slot object holds arrow functions that return JSX.

A parent passes named and scoped slots in one object after the component's children: {{ title: () => <h2>Profile</h2>, item: ({ item }) => <li>{item.name}</li> }}. Each member is an arrow function that returns JSX, whose one parameter, if it has one, is the scoped slot's props, as a destructuring pattern or an identifier; or it is the parent's own slot, passed on ({{ title: slots.title }}).

Write each slot as an arrow function that returns JSX.

UF3041 invalid-slot-use

Error. A slot is rendered, tested or forwarded, and nothing else.

A component renders a slot as a child, {slots.title?.()} or {slots.item?.({ item })}, with fallback content after ??; tests whether the parent filled it with slots.title as a condition; and forwards it in a child's slot object, {{ title: slots.title }}. Each target writes each of these in its own form, so any other use of slots is rejected: storing a slot, calling it in setup code or passing slots itself.

Use one of the three forms.

UF3042 invalid-v-model

Error. v-model binds a ref's value to a form control or a named model.

v-model={text.value} binds a form control's state: the value of a text-like <input>, a <textarea> or a <select>, the checked state of a checkbox or a radio, or an array for a checkbox group or a <select multiple>. v-model:open={open.value} binds a model a component declares. The value is a ref's or a model's .value, and trim, lazy and number apply only to a control that holds text.

<Toggle v-model={open.value} />      // rejected: the model has no name
<Toggle v-model:open={open.value} /> // accepted

Bind a ref's value, name the model on a component, and drop a modifier the control cannot use. The safe fix names the model of a child that declares one.

UF3043 component-listener-option

Error. A component's event takes no listener option.

Capture, once and passive (onClickCapture) are options of a DOM listener. A component's event is no DOM event: the child calls the listener when it emits, so an option suffix on a component's listener means nothing.

Drop the suffix. The safe fix does.

UF3044 open-dynamic-component

Error. <component is> chooses from a statically known set.

<component is={nested.value ? "h3" : "h2"}> renders one of a set the compiler knows: a tag literal, a component by its name, a conditional whose leaves are all tags or all components, or a value typed as a union of tag literals, such as a prop or a ref. Angular and the typed targets write every candidate, so a value only the run time knows is rejected, as is a set that mixes tags and components.

Write the candidates out in a conditional, or type the value as a union of tag literals.

UF3045 dropped-fallthrough

Error. The component renders no class or style passed to it.

A parent's class and style on a component fall through to the child's root element, or pass on to its root component. A child that turns fallthrough off with defineOptions({ inheritAttrs: false }), or whose root is a fragment, a conditional or a list, has no root to take them, so passing them is rejected rather than dropped.

Style an element around the component, or give the child one root element or a prop for its class.

UF3046 invalid-component-ref

Error. A component ref holds what the component exposes.

ref={field} on a component holds what the child exposes with defineExpose, which client code calls: field.value?.focus(). The ref's type, useTemplateRef<FieldApi>(), is an object type of the exposed functions. A ref on a component that exposes nothing, or whose type names a member the component does not expose, is rejected.

Expose the function in the child, or remove it from the ref's type.

UF3047 unknown-component

Error. The tag names no component in scope.

A PascalCase tag names a component: one imported from a .uf.tsx module, one of the same module, or the component itself. Any other name is rejected.

Import the component, or correct the tag. The likely fix renames the tag to the closest component in scope.

UF3048 open-spread

Error. A spread's keys are the ones its type declares.

A spread renders exactly the keys its object's type declares, each as a bound attribute. Keys only the run time knows (an index signature, a type the compiler cannot see) cannot be rendered alike by every target, so such a spread is rejected.

Type the object with its keys, or bind each attribute on its own.

UF3049 reserved-spread-key

Error. A spread renders attributes: no listener, key, ref or children.

A spread renders attributes. Listeners, keys, refs and children each have a channel of their own, which every target writes in its own form, so an object whose type declares an onX, key, ref or children key cannot be spread.

Remove the key from the type, and pass the listener, key, ref or children on their own.

UF3050 undefined-model-binding

Error. A model that can be undefined is bound to a ref that cannot hold it.

A model with neither a default nor required: true can be undefined, since a parent may leave it unbound. React's output passes its changes with that type, through an onValueChange that takes string | undefined, and a setter of a string state does not type-check there. So a ref bound to it with v-model:value holds undefined too.

const value = defineModel<string>("value"); // in Field
const text = ref("");
<Field v-model:value={text.value} />; // rejected

Give the model a default or required: true, or let the ref hold undefined: ref<string | undefined>(…).

UF3051 raw-html

Warning. innerHTML renders markup that is not escaped.

innerHTML sets an element's content to the markup a string holds. The browser parses it as HTML, and no target escapes or sanitises it, so markup from a user or another site can run script in the page (cross-site scripting). Every target renders the markup as written.

<div innerHTML={article.body} />

Render only markup you trust, such as your own content, or markup a sanitiser such as DOMPurify has cleaned. Text is safer as children, <p>{comment}</p>, which every target escapes.

UF3052 raw-html-content

Error. innerHTML is the whole content of an element that holds content.

The markup innerHTML holds replaces the element's content, so it cannot be set beside children: React and Vue reject both, and the other targets render them differently. It also needs an element whose content is markup: a void element (<br>, <img>, <input>) holds no content, and the content of <textarea>, <title>, <option>, <script>, <style> and <iframe> is text.

Remove the children, or put the markup in an element of its own beside them:

<section>
  <h2>{title}</h2>
  <div innerHTML={body} />
</section>

UF3053 teleport-target

Error. <Teleport> needs to, a static CSS selector.

<Teleport to> mounts its content into the element to selects, once its component has mounted. Each target selects that element its own way, from the selector as written, so to is a string literal that selects something. A bound to, a template literal with expressions, an empty string or no to at all can't be read when the component compiles.

<Teleport to="body">
  <div class="toast">{message}</div>
</Teleport>

Write the selector as a string: to="body" or to="#overlays".

UF3054 teleport-content

Error. <Teleport> holds exactly one element.

The content of <Teleport> is one element, which may hold anything: text, components, conditionals and lists. Svelte, Angular and Qwik move that one node into to, and remove it when the component unmounts, so text, two elements, a component, a conditional, a list, a slot or <component is> can't be the content itself, and neither can nothing at all.

Wrap the content in an element, and put a condition around the <Teleport>, not inside it:

{open.value && (
  <Teleport to="body">
    <div class="dialog">
      <ConfirmDialog />
    </div>
  </Teleport>
)}

UF3055 unknown-directive

Error. v-name applies no directive the module declares or imports.

An element applies a directive by its name in kebab case: v-focus-trap applies vFocusTrap (ADR-0099). The module must declare that name at its top level with defineDirective, or import it from the .uf.ts module that exports it. A constant, a composable or a component of that name is no directive.

import { vFocusTrap } from "./focusTrap.uf.ts";

<div v-focus-trap={open.value}>…</div>

v-model is the one built-in directive. Arguments (v-name:arg) and modifiers (v-name_mod) are not supported yet.

UF3056 invalid-directive-use

Error. A directive takes an element and a value that changes only when it should.

A directive's hooks run on the element it is written on (ADR-0099). A component, a <Teleport>, a <Transition>, <component is> or a slot has no element of its own there, so a directive goes on an element inside it.

Every directive takes a value, and its updated hook runs after a render in which the value changed, as Object.is compares it. An object or array literal, a function written in place or a new is a fresh value at each render on some targets and the same one on others, so pass a state, a derived value, a prop, a setup function or a primitive instead:

const options = computed(() => ({ initial: first.value }));

<div v-focus-trap={options.value}>…</div>

UF3057 transition-child

Error. <Transition> holds one element, or one conditional of elements.

<Transition> runs its classes on the element it holds when that element enters or leaves (ADR-0100). So its child is exactly one element, or one conditional whose every branch is one element or nothing: cond && <p />, cond ? <p /> : <div /> or an else-if chain. Text, two nodes, a component, a slot, <component is>, a fragment or a list can't be that child, and neither can nothing at all. The element itself may hold anything.

Wrap a component in an element, and keep the condition inside the <Transition>:

<Transition name="fade">
  {open.value && (
    <div class="panel">
      <Details />
    </div>
  )}
</Transition>

UF3058 transition-prop

Error. <Transition>'s name and appear are literals.

Each target writes the transition's class names when the component compiles (ADR-0100), so name is a string literal that is not empty and holds no whitespace, and v when it is left out. appear is the bare attribute, or {true} or {false} written as literals. A bound name, a template literal with expressions, an empty name, one with whitespace, or a bound appear can't be read then.

<Transition name="fade" appear>
  <div class="toast">{message}</div>
</Transition>

To switch between two transitions, write two <Transition> elements in a conditional.

Portability (capabilities)

UF4001 unsupported-capability

Warning. A selected target cannot support a feature the component uses.

Each target declares, for every feature, whether it supports it natively, emulates it with an inline helper, or cannot support it. The component uses a feature that a selected target cannot support; the diagnostic points at its first use, and the message names the feature and the target's reason. For example, Astro renders on the server only, so event handlers are inert there.

A feature can also be a construct one framework renders differently from HTML and the other targets. Vue's client, for example, selects the first option of a single-selection list box (<select size="2"> without multiple), where HTML selects none, so Vue declares listbox unsupported, and the diagnostic points at the list box's size.

The severity comes from the target's capability matrix. With strict: true, portability warnings are errors. Remove the feature, or drop the target.

UF4002 sheet-order

Info. A selected target may cascade the component's sheets in another order.

Vue, React, Solid, Svelte and Astro load a component's scoped sheet as its module loads, in import order: a child's sheet before its parent's, and siblings by their imports. Angular and Qwik attach it when the component first renders: a parent's before its children's, and siblings in the order they render. Where two sheets' rules of equal specificity match one element, the later sheet wins, so the winner can differ on those two targets. That happens on a child's root, which carries its styled parent's attribute too, on content filled into a child's slot, and under :deep() and :global() (ADR-0063). The diagnostic points at the component's stylesheet import, on every target that cascades in render order.

Where one rule must win, give it a higher specificity than the other, or keep the two components' rules off the same element.

UF4003 component-host

Info. A selected target renders an element between a component and its child's root.

Angular renders each child component inside a host element, uf-<name>, styled display: contents, so it adds no box, and the page lays out as on the other targets. Selectors still see it. A parent's rule that reaches a child's root through a combinator (.list > .row, .a + .row, .a ~ .row) or a structural pseudo-class (:first-child, :last-child, :nth-child(), :only-child) matches the host's place, not the root's, so it may match differently there. A root Angular binds nothing on ({{ in an attribute) does not take the parent's scope attribute either. The diagnostic points at the first child component a styled component renders.

Match a child's root by its class or its attributes rather than by its place or its parent.

UF4004 generic-slot-props

Info. A selected target types a generic scoped slot's props by the type parameter's constraint.

A generic component's scoped slot passes props whose type names one of its type parameters, such as item: T in function List<T>(props: ListProps<T>). React, Vue, Svelte, Solid, Qwik and Astro type a consumer's fill by the type argument its props give. Angular infers a component's type parameter from its inputs alone, and a slot's directive cannot infer it, so the slot's context takes the parameter's constraint, unknown where it has none (ADR-0068). The component renders the same; only a consumer's type checking differs. The diagnostic points at the slot, or at a consumer's fill of it.

Give the type parameter a constraint that names what consumers read, or accept the looser type on Angular.

UF4005 composable-effect-order

Info. A selected target runs a composable's effects apart from the caller's.

A composable that runs code in the browser (a watcher, an effect or a lifecycle hook) runs it in its place among the caller's own on Vue, Svelte, Angular and Qwik, in source order. A composable is a custom hook on React, which runs a component's effects in its own order, and Solid queues a composable's watchers in its own module. On those two, code that relies on the order of the composable's effects and the caller's may see another (ADR-0069). The diagnostic points at the composable's call.

Make each effect depend on the state it reads, not on when another effect ran.

Styles

UF5001 shared-stylesheet

Error. A stylesheet is imported by a module that declares several components.

A sibling stylesheet (import "./Button.css") scopes the elements of one component: the compiler rewrites its selectors to match that component's scope attribute (ADR-0063). A module that declares several components gives the sheet no single owner, so it cannot tell whose elements the selectors mean.

Move each component that needs styles into a module of its own, with its own sheet, and import it where it is rendered.

UF5002 invalid-stylesheet

Error. A stylesheet is not valid CSS.

The compiler parses every imported stylesheet with lightningcss before it scopes it, and the parser reports an error. The message names it, and the diagnostic points at it in the sheet. A sheet that does not parse cannot be scoped, and the browsers would each recover from it differently. An at-rule lightningcss does not know (@apply, @custom-media) is reported too: the compiler cannot read its content, so its rules would reach the page unscoped.

Fix the CSS at the reported place. Remove an unknown at-rule, or compile it to plain CSS first.

UF5003 unsupported-stylesheet-language

Error. A stylesheet is written in a preprocessor's language.

A component imports a .scss, .sass, .less, .styl or .pcss file. The compiler scopes plain CSS only, because it reads the sheet itself with lightningcss and attaches the scoped result to every target, where no preprocessor runs.

Compile the sheet to a .css file first, and import that. Nesting, custom properties, @layer and @media are CSS, and need no preprocessor.

UF5004 unscopable-selector

Error. A selector cannot be scoped to the component.

The compiler scopes every rule of a component's sheet to the component's own elements. Some selectors cannot be scoped that way:

  • :root, html and body outside :global(), which match no element of the component;
  • :host, which only a shadow root has, and no target renders one;
  • an empty :deep(), :slotted() or :global(), or one used where it means nothing, such as :slotted() in a rule with nested rules, or beside a selector it would leave unscoped;
  • an empty :is() or :where(), which matches nothing;
  • a namespace prefix (svg|, *|), which the compiler does not scope;
  • a selector that tells an empty class or style from a missing one ([class=""], [style]), which the targets render differently (ADR-0044).

Wrap a page-level selector in :global(), or move it to a global stylesheet. Select the element without a namespace prefix, and by a class or a data-* attribute instead of an empty class or style. Select the component's root by a class instead of :host, and give a :deep() or :slotted() selector a rule of its own, at the top of the sheet.

UF5005 stylesheet-not-found

Error. An imported stylesheet does not exist.

A component imports a sibling stylesheet that the compiler cannot read: no file is at the path the specifier names, relative to the component's file.

Check the path and its case, which some file systems ignore and others do not, or create the file.

UF5006 unsupported-virtual-import

Error. A module that passes through is imported in a way the compiler cannot keep.

An import whose specifier starts with one of the passThrough prefixes (virtual: by default) names a module a bundler plugin registers, such as a styling engine's. Every output keeps it as written, and that plugin resolves it (plan §4.4). The compiler passes through two forms only: named imports called in a class (class={button({ size })}), and a side-effect import (import "virtual:theme.css"). A default, namespace or type-only import, or any other use of an imported name, would reach the targets unanalysed, and a name that nothing calls would reach every output as an unused import.

Import the module's class functions by name and call them in a class, or import the module for its effect alone.

Types

UF6001 unresolved-type

Error. A type cannot be resolved.

The compiler reads a component's props, events, models, slots and injection keys from their types (ADR-0067). It resolves a type the module declares, or one it imports from a relative .ts file, a .uf.tsx or .uf.ts module, or a package through its types and exports. This type names a declaration the type oracle cannot find: a name the module neither declares nor imports, a file that does not exist, or a package without types.

Check the name, the import's path, and that the package ships its types. Global types other than TypeScript's own library are not read: import the type instead.

UF6002 unsupported-type-construct

Error. The type oracle cannot evaluate this type.

The default type oracle reads types as written, without a type checker (ADR-0067). It resolves type literals, interfaces and aliases, extends chains, intersections, unions, literal unions, generic declarations, and Partial, Required, Pick, Omit and Readonly. Conditional and mapped types, infer, keyof, typeof and template-literal types need a type checker, so it reports them at their span rather than guess.

Write the type with the constructs above, or compile with the tsgo type oracle, @unframework.dev/type-oracle-tsgo, which resolves every construct through TypeScript.

UF6003 type-not-exported

Error. An output must import a type its module does not export.

Each output imports by name the types its props, events and slots name, from the module that declares them, rather than printing them again (ADR-0067). This type is declared in another module without export, so no output can import it.

Export the type from its module. The likely fix adds export to its declaration.

UF6004 props-not-object

Error. A props type is not an object type.

A component's props are the members of its props type: an object type literal, an interface, or an alias, an intersection, an extends chain or a utility type that resolves to one (ADR-0034, ADR-0067). This props type resolves to something else, such as a primitive, a union of object types, an array or a function, whose members the targets cannot declare as props.

Give the component one object type of props. Write alternatives as optional members, or as a member whose literal union says which applies.

UF6005 conflicting-members

Error. Two declarations give a prop different types.

A props type built from several declarations, by an intersection or an extends chain, declares one member twice, with types that differ, or optional in one and required in the other. The targets declare each prop once, with one type, so they cannot follow it (ADR-0067). The diagnostic points at the props annotation, and the message names the member and both declarations.

Declare the member once, or give both declarations the same type and optionality.

UF6006 generic-instantiation

Error. A generic component takes its type arguments from its props.

A generic component, function List<T>(props: ListProps<T>), infers its type arguments from the props its consumer passes, on every target (ADR-0068). Explicit type arguments on its tag (<List<string> items={names} />) have no form in several frameworks' templates, and a generic component cannot be a candidate of <component is>, whose props no one type argument types.

Remove the type arguments, and pass props whose types give T. Render a generic component by its own tag rather than through <component is>.

UF6007 directive-value-type

Error. A directive's value has another type than the directive takes.

A directive declared with defineDirective<T> takes a value of type T, and this value's type is not assignable to it: v-focus-trap={1} where vFocusTrap takes boolean. TypeScript does not type a dashed JSX attribute, so the editor accepts it, and some outputs would pass the wrong value to the directive's hooks.

Only the tsgo type oracle checks it (ADR-0109): typeOracle: "tsgo" in the configuration, or --type-oracle tsgo. The default oracle reads types as written and checks no value. The value is typed where it is written, narrowed by its branch, and with the directive's type as its context, as an assignment types it, so a template literal or a generic call is typed as the directive needs.

Pass a value of the type the directive takes, or change the type argument of its defineDirective.

Config and tooling

UF7001 config-not-loaded

Error. The configuration file could not be loaded.

Unframework could not import the configuration file (unframework.config.ts, .mts, .js or .mjs), or the file has no default export. The message names the file and says which.

Fix the file so Node can import it. Node loads a TypeScript configuration by stripping its types, so the file cannot use syntax that needs compiling, such as an enum or a parameter property: rewrite the file without that syntax. Then export the configuration as the file's default: export default defineConfig({ … }).

UF7002 config-invalid

Error. The configuration has the wrong shape.

A field in the configuration has the wrong type or form, or it isn't a field the configuration has. A package.targets entry that targets leaves out counts too. The message points at it by JSON Pointer.

Fix the field, or remove it. Write the configuration with defineConfig from @uxfront/unframework/config: its types let an editor flag a wrong field as you write it.

UF7003 unknown-target

Error. The configuration names an unknown target.

The configuration names a target that is not built in. Where a built-in name is close, the message suggests it.

Use one of the built-in names: react, vue, svelte, solid, angular, qwik or astro.

UF7004 target-options-invalid

Error. A target's options are not valid.

An entry in targetOptions holds options its target can't take: the target's schema rejects them, the schema throws on them, or the target has no schema, which means it declares no options and nothing would read them. The message gives the path of the option.

Fix the option, or remove it. A target that declares no options takes none, so remove them all, or leave its entry out.

UF7005 target-not-detected

Error. The bundler plugin could not detect a target.

The bundler plugin has no target option, and none of the plugins in the Vite configuration belongs to a framework it knows.

Add the framework's Vite plugin to the configuration, or pass target to the Unframework plugin.

UF7006 target-ambiguous

Error. The bundler plugin detected more than one target.

The bundler plugin has no target option, and the Vite configuration holds the plugins of two or more frameworks, so it cannot choose a target.

Pass target to the Unframework plugin.

UF7007 no-sources

Error. No source files were found.

The command found no .uf.tsx or .uf.ts file under srcDir, which is src by default.

Add a component there, or set srcDir in unframework.config.ts to the directory that holds your components.

UF7008 packager-missing

Error. A target's packager is not installed.

unframework build --package runs each target's packager, and it could not resolve this one. React and Solid use tsdown, Vue uses vite, @vitejs/plugin-vue and vue-tsc, Svelte uses @sveltejs/package, Angular uses ng-packagr, and Qwik uses vite and @qwik.dev/core, whose qwikVite() runs the build. Svelte and Qwik also need typescript, for their declarations. Unframework does not install them: it resolves them from package.resolveFrom, which is the project root by default.

Install the packager in the project, point package.resolveFrom at a directory that has it, or leave the target out of package.targets.

UF7009 packager-failed

Error. A target's packager failed.

unframework build --package ran a target's packager, and the packager failed.

Fix the problem the packager reports, or leave the target out of package.targets while you do.

UF7010 host-option-incompatible

Warning. A host framework option changes how whitespace renders.

Outputs assume the host framework's default whitespace handling, and two options that change it cannot be set per file: Vue's template.compilerOptions.whitespace and Astro's compressHTML. With Vue's "preserve", or an Astro compressHTML other than "jsx", a component can render different whitespace from the other targets.

Remove the option, or set Vue's to "condense" and Astro's to "jsx".

UF7011 example-with-props

Error. An example declares props.

unframework visual renders each *.example.uf.tsx file on every target with no props, so every target renders the same thing (ADR-0087). This example's component declares props, which no target is given.

Remove the props, and write the values the example shows into it, as the props of the components it renders. To show several states, render each one, or write an example for each.

UF7012 malformed-example-metadata

Warning. An example's metadata tag is malformed.

unframework preview reads the doc comment on an example's default export for its category, title and order (ADR-0110). One of these tags is malformed: @category or @title is empty, @category has an empty group, @order isn't a finite number, or a tag is given twice. The preview uses the value it derives instead: the category from the example's directory, the title from its file name, and no order.

Write a value after the tag, such as @category Components/Actions/Button, @title Colors or @order 2, give each tag once, or remove the tag. unframework visual doesn't read the comment, so its run is the same either way.

Plugins

UF8001 plugin-failed

Error. A compiler plugin failed.

A compiler plugin's ir or output hook threw, or returned something other than valid IR or a list of files. Valid IR has the schema's shape and keeps the invariants every target relies on (checkInvariants): component and export names every target can write, HTML every target renders alike, and no code or document the compiler cannot analyse. The message points at the first problems by JSON Pointer.

The compiler reports it instead of crashing, and leaves the plugin's step out: hooks receive a frozen module and frozen files, so a hook changes them by returning new ones, and a failed hook leaves nothing behind.

Fix the plugin, or remove it from the configuration.

Internal

UF9001 internal-error

Error. The compiler failed unexpectedly.

This is a bug in Unframework. Please open an issue with the file that triggered it: https://github.com/uxfront-com/unframework/issues/new/choose

UF9002 sourcemap-not-remapped

Error. A source map could not follow formatting.

The compiler maps each output before it formats it, then carries the map across by matching the non-whitespace characters on both sides. It counts only the characters of words, since the formatter removes punctuation and rewrites numbers. Fewer than 95% of those matched, or a markup file's code blocks or the markup around them changed in a way it can't follow, so it reports this instead of a wrong map.

The message says which. A file whose diff outgrows the compiler's bound is UF9003 instead.

This is a bug in Unframework. Please open an issue with the file that triggered it: https://github.com/uxfront-com/unframework/issues/new/choose

UF9003 sourcemap-skipped

Warning. A file ships without a source map.

The compiler carries each output's map through formatting with a diff, and that diff may hold 256 MB. Formatting changed this file too much to fit, so the compiler stopped and left the map out.

The file still works, only without a map: a stack frame in it shows the output's line, not the source's. To map it, write the code as the formatter prints it, like 1.5 for 1.50, so that formatting changes less. Or move a large table to a shared .ts module, which the compiler copies unchanged.

Copyright © 2026