@tsrx/core

@tsrx/core

TypeScript Render Extensions (TSRX) — the shared parser and compiler infrastructure that powers TypeScript UI frameworks.

@tsrx/core is framework-agnostic. It provides the parser, AST definitions, scope analysis, and code-generation utilities needed to target any framework runtime using TSRX syntax. Framework-specific packages—such as @tsrx/react, @tsrx/solid, and the external @tsrx/ripple—build on @tsrx/core to produce target-runtime output.

What is TSRX?

TSRX is an extension to TypeScript's syntax — in the same spirit that JSX is an extension to JavaScript. It adds a small set of orthogonal syntactic forms that are ergonomic for describing reactive UI, and leaves the semantics of those forms to the consuming framework.

A .tsrx file is a TypeScript module with TSRX enabled.

Installation

pnpm add @tsrx/core

Usage

import { analyzeTsrx, parseModule } from '@tsrx/core';

const ast = parseModule(source, 'App.tsrx');
const analysis = analyzeTsrx(ast, 'App.tsrx');

The parser produces an ESTree-compatible AST, augmented with the TSRX node types listed below. Framework compilers walk this AST to emit their own output.

Language docs

The TSRX website is the canonical source for language documentation:

• Getting Started — install TSRX for React, Preact, Solid, Vue, or Ripple and configure editor/AI tooling.
• Features — examples of function components, statement templates, control flow, scoped styles, and submodules.
• Specification — the current grammar and parser-level semantics.

Keeping the language reference on the website avoids duplicating the specification here and keeps package docs focused on the core parser API.

What @tsrx/core provides

• parseModule(source, filename, options?) — parse a TSRX module into an ESTree AST.
• analyzeTsrx(ast, filename, options?) — run target-neutral semantic validation before framework analysis or transformation. Pass collect: true, typeOnly: true, or to_ts: true to collect non-fatal diagnostics for editor/type-only output.
• Scope analysis — createScopes, Scope, ScopeRoot, binding tracking (import, prop, let, const, function, for_pattern, …).
• AST utilities — pattern walkers, identifier extraction, builders, location helpers, obfuscation helpers.
• CSS support — parseStyle, analyzeCss, renderStylesheets. CSS node offsets are relative to the style body; a sheet parsed with a body origin (every sheet parseModule produces) records sourceStart and a file-relative loc, and analyzeCss anchors its :global placement diagnostics on the selector with file-relative positions. Pass { errors, comments } to collect them instead of throwing.
• Scoped styles — analyzeTsrx resolves every <style> block. A standalone block is a child of an element or fragment and is scoped to its siblings: it styles the items beside it and everything below them, never the element that contains it, and the compiler adds a hash class to those elements so the block's selectors match only there. A block is an output node, so a block that is the lone output of a @{ … } or control-flow body is STYLE_STANDALONE_NEEDS_FRAGMENT. Raw CSS is TSRX template syntax, so a block with CSS in it outside every @{ … }/control-flow body is STYLE_STANDALONE_OUTSIDE_TEMPLATE; plain-TSX <style>{css}</style> is an ordinary element. Assigned blocks (const theme = <style>…</style>) are always themes (styleKind: 'theme') and keep every selector, and apply targets are resolved through real bindings, declared before use. Results ride on each block's metadata (styleKind, styleApplies, styleApplied) and on program.metadata.styles, and the analysis result exposes scopes. Target compilers use prepareStylesheetForRender(sheet, mode) with mode: 'scope' | 'theme' ('class-map' and a boolean are still accepted, and no mode prunes an assigned block) and createStyleClassMapFromStylesheet(sheet, options), whose object starts with $class and accepts { applied } for composed themes. Style diagnostics use the STYLE_*, CSS_GLOBAL_PLACEMENT, and CSS_IMPORT codes in DIAGNOSTIC_CODES.
• HTML helpers — isVoidElement, isBooleanAttribute, isDomProperty, validateNesting.
• Tag-name helpers — isSvgTagName(name) and isMathmlTagName(name) check case-sensitive membership in the tag-name sets used for ref types. These are namespace-independent checks: isSvgTagName includes names shared with HTML (a, title, script, and style), even though ref-type inference prefers HTML for those names when no SVG namespace is provided. Target compilers can use these checks when choosing safe lowering behavior without a known namespace.
• Event helpers — delegated-event utilities, event-name normalization.
• Source maps — convertSourceMapToMappings.
• Errors — TSRX_ERRORS and TS_ERRORS define each error @tsrx/core reports once, with its code: TSRX's own (DIAGNOSTIC_CODES), or TypeScript's for a mistake TypeScript also reports. An entry is { code, message }, or a function of the values its message takes that gives one (TS_ERRORS.MODIFIER_MUST_PRECEDE('export', 'abstract')). error(entry, filename, node, errors?, comments?) records an error in errors, or throws it; it also takes a message and a code.

See src/index.js for the full exported surface.

Non-goals

• @tsrx/core does not emit runtime code. Code generation lives in framework packages (e.g. @tsrx/ripple).
• @tsrx/core does not ship a runtime. There is no reactivity, rendering, or DOM code here.
• @tsrx/core does not lock consumers to a specific output format. Multiple compile targets can share the same parser and analysis.

License

MIT © Dominic Gannaway