Compiler

Compile errors are CompileErrors thrown by compile() (and so by the Vite plugin, which prints the file, line, column, code and a code frame). error.diagnostic holds code, message, severity, start, end, line and column; error.frame is the printed excerpt.

import { compile, CompileError } from "@shadow-js/compiler";

/** The diagnostic code `compile` throws for `source`, or `undefined` when it compiles. */
export function codeOf(source: string, generate: "dom" | "ssr" = "dom"): string | undefined {
  try {
    compile(source, { filename: "example.tsx", generate });
    return undefined;
  } catch (error) {
    if (error instanceof CompileError) return error.diagnostic.code;
    throw error;
  }
}

PARSE_ERROR#

The source is not valid TypeScript/JSX; the message is the parser's. The error carries the position and a code frame. Parser-level errors such as an empty attribute expression (class={}) surface as PARSE_ERROR.

CHILDREN_CONFLICT#

A component call has both a children prop and JSX children. Fix: use one of them.

CHILDREN_ATTRIBUTE#

A DOM element has a children="..." attribute. Write the content between the tags.

STRING_EVENT_HANDLER#

An on... attribute received a string, as in HTML (onClick="go()"). Strings are never evaluated, so the compiler refuses them in both the dom and ssr targets. Fix: pass a function.

UNKNOWN_NAMESPACE#

A dynamic attribute uses a namespace prefix the compiler does not know. The known ones are on:, oncapture:, use:, prop:, attr:, bool:, class:, style: and xlink:. Fix: use one of them, or a plain attribute name.

RAW_TEXT_CLOSE#

Static text inside <style> or <script> contains the closing tag (</style, </script), which would end the element early and let the rest be parsed as markup. Fix: move the content out of JSX (a stylesheet file, useHead).

VOID_CHILDREN#

A void element (br, input, img, hr, meta, link, ...) has children. Fix: remove them.

NAMESPACED_TAG#

A tag name with a namespace (<svg:rect />) is not supported. Write the element name without a prefix; SVG and MathML contexts are detected from the parent.

SPREAD_CHILD#

JSX spread children ({...items}) are not supported. Wrap the array in an ordinary expression: {items}.

JSX_TOO_DEEP#

One JSX tree is nested more than 400 levels below its root element. The lowering is recursive, so the depth is bounded. Fix: split the tree into components or build it from data.

INVALID_HTML_NESTING#

The markup would be re-arranged by the HTML parser, which would make the template differ from your JSX: <div> inside <p>, a <div> or text directly inside <table>, and similar. The error names the pair. Fix: use the valid structure (<tbody><tr><td> inside <table>, <span> inside <p>).

INNER_HTML_CHILDREN#

Server target only: an element has both an innerHTML attribute and JSX children. innerHTML replaces the children, so the combination is ambiguous. Fix: use one.

Defensive compiler codes#

These five codes are defensive checks in the lowering and code generation passes. The parser rejects the corresponding source first (an empty {} attribute value is reported as PARSE_ERROR), so valid TSX never reaches them. If you see one, it is a compiler bug: report the source that produced it.

Each has its own heading so a link to the code works:

EMPTY_ATTRIBUTE_EXPRESSION#

An attribute (on:, use:, prop: and the other code namespaces) has an empty expression. In practice the parser reports PARSE_ERROR ("JSX attributes must only be assigned a non-empty 'expression'") before the compiler sees it.

BAD_TAG#

A malformed element or member-expression tag name (<a.b> with a missing part).

BAD_ATTRIBUTE#

A malformed or unsupported attribute name, or an unsupported attribute value node.

BAD_CHILD#

A JSX child node of a kind the compiler does not know.

INTERNAL#

An invariant of the code generator failed (a fragment survived lowering, a dynamic attribute without an element reference). Always a compiler bug.