velt/jsx

API reference

Server-side rendering of TSX to HTML. It is the default JSX provider: a .tsx module compiles its JSX to calls into velt/jsx/jsx-runtime and sees its types as JSX.Element, JSX.IntrinsicElements, …, and this module renders the result. For a walkthrough, read the guide.

import { renderToString, renderToStream, raw, Element } from "velt/jsx";

Exports

Fragment<>children</>: the children's markup, nothing around it.rawhtml inserted as it is, without escaping: the only way to emit markup from a string.renderToStringThe HTML of el, after awaiting its async components.renderToStringSyncThe HTML of el when it has no async component (no await needed).renderToStreamThe HTML of el as a streamed Response body (like React's renderToReadableStream): new Response(renderToStream(el), ...).ElementA rendered or partly rendered JSX node (see the module comment).RenderErrorThrown while rendering when a component threw or an async component rejected.ChildWhat may appear as a child: text is escaped, numbers render like ${n}, true, false and null render nothing, and an array renders its elements in order.AttrValueWhat an intrinsic attribute may hold: true renders the bare name, false and null omit the attribute, numbers render like ${n}, a Style renders its declarations.StyleAn inline style object: CSS properties in camelCase (fontSize) or custom ones (--accent) with their values (std/jsx/style.vlt renders it as React does).TextA dynamic text child that a precompiled template folds into its strings (jsxEscape).IntrinsicElementsTag name → attribute type, for every element of the HTML standard, of SVG 2 and of MathML Core.ElementChildrenAttributeComponents receive their JSX children in the children field of their props.

function

Fragment

#std/jsx/factory.vlt:50

Re-exported from velt/jsx/factory

function Fragment(children: Child[], key: string | null): Element

<>children</>: the children's markup, nothing around it.

function

raw

#std/jsx/factory.vlt:157

Re-exported from velt/jsx/factory

function raw(html: string): Element

html inserted as it is, without escaping: the only way to emit markup from a string. Never pass it text from users.

functionasync

renderToString

#std/jsx/render.vlt:19

Re-exported from velt/jsx/render

async function renderToString(
  el: Element,
): Promise<string> throws RenderError

The HTML of el, after awaiting its async components. Throws the RenderError of the first (in document order) component that threw or rejected.

function

renderToStringSync

#std/jsx/render.vlt:43

Re-exported from velt/jsx/render

function renderToStringSync(el: Element): string throws RenderError

The HTML of el when it has no async component (no await needed). Throws the RenderError of the first component that threw, or one saying the tree has an async component.

function

renderToStream

#std/jsx/render.vlt:76

Re-exported from velt/jsx/render

function renderToStream(el: Element): BodyStream

The HTML of el as a streamed Response body (like React's renderToReadableStream): new Response(renderToStream(el), ...). The markup above each pending async component is sent before the component is awaited, so it reaches the client while the component loads. Once the client has gone away, rendering stops. A component that throws cuts the response off (its RenderError is printed to stderr).

class

Element

#std/jsx/node.vlt:47

Re-exported from velt/jsx/node

A rendered or partly rendered JSX node (see the module comment). Its fields are std/jsx's internals (render.vlt and factory.vlt use them): read the markup with renderToString, as a template node keeps it in tree and its html is "".

Parameter ofrenderToStringrenderToStringSyncrenderToStreamvelt/jsx/jsx-runtimejsxComponentjsxAsyncComponentjsxTemplateReturned byFragmentrawvelt/jsx/jsx-runtimejsxjsxComponentjsxAsyncComponentFragmentjsxTemplatejsxTemplateStringUsed byChildvelt/jsx/jsx-runtimeChild

html: string

Markup rendered so far: everything when rest is null. Unused ("") in a template node.

tree: Tree | null = null

A template node's strings and child nodes (null for a node of one string, almost all).

rest: Deferred | null = null

What follows html when the node contains an async component or a component that threw.

constructor(html: string)No doc comment yet

get isComplete(): bool

True when the node is rendered completely (no async or failed component inside): its markup is html, or tree in a template node.

class

RenderError

#std/jsx/errors.vlt:10

Re-exported from velt/jsx/errors

class RenderError extends Error

Thrown while rendering when a component threw or an async component rejected. Element is not generic, so the component's own error type cannot travel through the tree: its value is formatted like ${e} into message, and component names the component ("<module path>#<Name>"). Also thrown by renderToStringSync for a tree that still has a pending async component (component is then "").

Thrown byrenderToStringrenderToStringSync

component: stringNo doc comment yet

constructor(component: string, message: string)No doc comment yet

type

Child

#std/jsx/node.vlt:40

Re-exported from velt/jsx/node

type Child = Element | Element[] | string | i64 | f64 | bool | null

What may appear as a child: text is escaped, numbers render like ${n}, true, false and null render nothing, and an array renders its elements in order.

Parameter ofFragmentvelt/jsx/jsx-runtimejsxFragmentUsed byElementChildrenAttributevelt/jsx/jsx-runtimeElementChildrenAttribute

type

AttrValue

#std/jsx/node.vlt:31

Re-exported from velt/jsx/node

type AttrValue = string | i64 | f64 | bool | Style | null

What an intrinsic attribute may hold: true renders the bare name, false and null omit the attribute, numbers render like ${n}, a Style renders its declarations.

Parameter ofvelt/jsx/jsx-runtimejsxjsxAttr

type

Style

#std/jsx/node.vlt:25

Re-exported from velt/jsx/node

type Style = Record<string, string | f64>

An inline style object: CSS properties in camelCase (fontSize) or custom ones (--accent) with their values (std/jsx/style.vlt renders it as React does).

Used byAttrValuevelt/jsx/attrsHtmlAttrsMathAttrsSvgAttrsvelt/jsx/jsx-runtimeAttrValue

type

Text

#std/jsx/node.vlt:34

Re-exported from velt/jsx/node

type Text = string | i64 | f64 | bool | null

A dynamic text child that a precompiled template folds into its strings (jsxEscape).

Parameter ofvelt/jsx/jsx-runtimejsxEscape

type

IntrinsicElements

#std/jsx/intrinsic.vlt:104

Re-exported from velt/jsx/intrinsic

type IntrinsicElements = { a: AnchorAttrs & SvgAttrs; abbr: HtmlAttrs; address: HtmlAttrs; area: AreaAttrs; article: HtmlAttrs; aside: HtmlAttrs; audio: AudioAttrs; b: HtmlAttrs; base: BaseAttrs; bdi: HtmlAttrs; bdo: HtmlAttrs; blockquote: QuoteAttrs; body: HtmlAttrs; br: HtmlAttrs; button: ButtonAttrs; canvas: CanvasAttrs; caption: HtmlAttrs; cite: HtmlAttrs; code: HtmlAttrs; col: ColAttrs; colgroup: ColAttrs; data: DataAttrs; datalist: HtmlAttrs; dd: HtmlAttrs; del: EditAttrs; details: DetailsAttrs; dfn: HtmlAttrs; dialog: DialogAttrs; div: HtmlAttrs; dl: HtmlAttrs; dt: HtmlAttrs; em: HtmlAttrs; embed: EmbedAttrs; fieldset: FieldsetAttrs; figcaption: HtmlAttrs; figure: HtmlAttrs; footer: HtmlAttrs; form: FormAttrs; h1: HtmlAttrs; h2: HtmlAttrs; h3: HtmlAttrs; h4: HtmlAttrs; h5: HtmlAttrs; h6: HtmlAttrs; head: HtmlAttrs; header: HtmlAttrs; hgroup: HtmlAttrs; hr: HtmlAttrs; html: HtmlAttrs; i: HtmlAttrs; iframe: IframeAttrs; img: ImgAttrs; input: InputAttrs; ins: EditAttrs; kbd: HtmlAttrs; label: LabelAttrs; legend: HtmlAttrs; li: LiAttrs; link: LinkAttrs; main: HtmlAttrs; map: MapAttrs; mark: HtmlAttrs; menu: HtmlAttrs; meta: MetaAttrs; meter: MeterAttrs; nav: HtmlAttrs; noscript: HtmlAttrs; object: ObjectAttrs; ol: OlAttrs; optgroup: OptgroupAttrs; option: OptionAttrs; output: OutputAttrs; p: HtmlAttrs; picture: HtmlAttrs; pre: HtmlAttrs; progress: ProgressAttrs; q: QuoteAttrs; rp: HtmlAttrs; rt: HtmlAttrs; ruby: HtmlAttrs; s: HtmlAttrs; samp: HtmlAttrs; script: ScriptAttrs & SvgScriptAttrs; search: HtmlAttrs; section: HtmlAttrs; select: SelectAttrs; slot: SlotAttrs; small: HtmlAttrs; source: SourceAttrs; span: HtmlAttrs; strong: HtmlAttrs; style: StyleAttrs; sub: HtmlAttrs; summary: HtmlAttrs; sup: HtmlAttrs; table: HtmlAttrs; tbody: HtmlAttrs; td: TdAttrs; template: TemplateAttrs; textarea: TextareaAttrs; tfoot: HtmlAttrs; th: ThAttrs; thead: HtmlAttrs; time: TimeAttrs; title: HtmlAttrs; tr: HtmlAttrs; track: TrackAttrs; u: HtmlAttrs; ul: HtmlAttrs; var: HtmlAttrs; video: VideoAttrs; wbr: HtmlAttrs; animate: AnimationAttrs; animateMotion: AnimationAttrs; animateTransform: AnimationAttrs; circle: CircleAttrs; clipPath: ClipPathAttrs; defs: SvgAttrs; desc: SvgAttrs; discard: AnimationAttrs; ellipse: EllipseAttrs; feBlend: FilterPrimitiveAttrs; feColorMatrix: FilterPrimitiveAttrs; feComponentTransfer: FilterPrimitiveAttrs; feComposite: FilterPrimitiveAttrs; feConvolveMatrix: FilterPrimitiveAttrs; feDiffuseLighting: FilterPrimitiveAttrs; feDisplacementMap: FilterPrimitiveAttrs; feDistantLight: FilterPrimitiveAttrs; feDropShadow: FilterPrimitiveAttrs; feFlood: FilterPrimitiveAttrs; feFuncA: FilterPrimitiveAttrs; feFuncB: FilterPrimitiveAttrs; feFuncG: FilterPrimitiveAttrs; feFuncR: FilterPrimitiveAttrs; feGaussianBlur: FilterPrimitiveAttrs; feImage: FilterPrimitiveAttrs; feMerge: FilterPrimitiveAttrs; feMergeNode: FilterPrimitiveAttrs; feMorphology: FilterPrimitiveAttrs; feOffset: FilterPrimitiveAttrs; fePointLight: FilterPrimitiveAttrs; feSpecularLighting: FilterPrimitiveAttrs; feSpotLight: FilterPrimitiveAttrs; feTile: FilterPrimitiveAttrs; feTurbulence: FilterPrimitiveAttrs; filter: FilterAttrs; foreignObject: ForeignObjectAttrs; g: SvgAttrs; image: SvgImageAttrs; line: LineAttrs; linearGradient: LinearGradientAttrs; marker: MarkerAttrs; mask: MaskAttrs; metadata: SvgAttrs; mpath: MpathAttrs; path: PathAttrs; pattern: PatternAttrs; polygon: PolyAttrs; polyline: PolyAttrs; radialGradient: RadialGradientAttrs; rect: RectAttrs; set: AnimationAttrs; stop: StopAttrs; svg: SvgRootAttrs; switch: SvgAttrs; symbol: SymbolAttrs; text: TextContentAttrs; textPath: TextPathAttrs; tspan: TextContentAttrs; use: UseAttrs; view: ViewAttrs; annotation: AnnotationAttrs; maction: MactionAttrs; math: MathRootAttrs; merror: MathAttrs; mfrac: MfracAttrs; mi: MathAttrs; mmultiscripts: MathAttrs; mn: MathAttrs; mo: MoAttrs; mover: MunderoverAttrs; mpadded: MpaddedAttrs; mphantom: MathAttrs; mprescripts: MathAttrs; mroot: MathAttrs; mrow: MathAttrs; ms: MathAttrs; mspace: MspaceAttrs; msqrt: MathAttrs; mstyle: MathAttrs; msub: MathAttrs; msubsup: MathAttrs; msup: MathAttrs; mtable: MathAttrs; mtd: MtdAttrs; mtext: MathAttrs; mtr: MathAttrs; munder: MunderoverAttrs; munderover: MunderoverAttrs; none: MathAttrs; semantics: MathAttrs }

Tag name → attribute type, for every element of the HTML standard, of SVG 2 and of MathML Core. a, script, style and title exist in HTML and SVG and take HTML's attributes (a and script also SVG's).

type

ElementChildrenAttribute

#std/jsx/intrinsic.vlt:314

Re-exported from velt/jsx/intrinsic

type ElementChildrenAttribute = { children: Child }

Components receive their JSX children in the children field of their props.