Repository navigation
Releases
2.0.0
fiorejs 2 gives every tag an immutable builder, renames the data object keys to attrs and on, rewrites live children to keep their place between comment markers, and replaces the plugin hook with a live-value protocol. It is a major release: check "Breaking changes" and the upgrade table before upgrading. @fiorejs/signals 2.0.0 and @fiorejs/jsx 2.0.0 follow this release and require it.
Breaking changes
- Data object keys:
attributesis nowattrs, andeventis nowon. element(name, data)is nowelement(name)(data):element(name)returns the tag function for any name.- Plugins are removed, and so is
use(). A value is live when it has a method underSymbol.for('fiorejs.live'), exported asLIVE; fiorejs callsvalue[LIVE](apply, context)for props, attributes and children. Signals from@fiorejs/signals2.0.0 carry this method. - A plain function is never a live value. In props, attributes, children and JSX alike, a function is a callback or plain content. Derived values are written with
computedfrom@fiorejs/signals. - Live children sit between two empty comments when they have siblings, so the comments show in
childNodesandinnerHTML(not inchildren,textContentor CSS selectors). A live child that is the only child of its element fills the element without comments. - Children arrays are flattened at any depth, so
[title, items.map(row)]works. Earlier versions flattened one level. - A plain object that carries
[LIVE]is live, also as the only argument of a tag.
Added
- Builders: every tag has
props(map),attrs(map),on(map),with(modifier),also(fn)andcreate(children). Builders never change, so a builder is a reusable template.propsandattrscombine across calls (later keys win);onadds listeners. HTMLModifierandSVGModifiertype a reusable modifier that works on every tag of its namespace and keeps the tag's element type.LIVE, and theLiveValue,LiveandBindContexttypes, for writing your own live values.- A live value under an inline handler prop binds, so
props: { onclick: handlerSignal }swaps the handler. Inline handler attributes such asonclickare still never set.
Improved
- Live children keep their nodes between two markers and read the DOM between them on every update, instead of tracking their nodes in a separate list. Updates keep working after
Node.normalize(), after browser page translation replaces a text node, and for a live child inside a fragment that becomes another live child's value. A list update steps over unchanged rows at both ends and moves only the rows that are out of order, withmoveBeforewhere the browser has it. Measured in Chrome 157 with the published packages (fiorejs and@fiorejs/signals, 1.2.0 and 1.0.0 against 2.0.0): creating 10,000 rows with a live text child is about 1.6 times faster, appending one row to a 10,000-row list takes about 2.0 ms instead of 3.2 ms, and updating 10,000 live texts is 10 to 20% faster. The first render of a 10,000-row list and replacing all of its rows are about 20% slower (about 1 to 2 ms). - A cyclic children array renders its other items instead of running out of memory, and very deep arrays do not overflow the stack.
- Types:
Childrenaccepts nested arrays and live values among siblings, and the deprecated MathMLais typed without a cast.
Upgrading from 1.x
| 1.x | 2.0 |
|---|---|
div({ attributes: { … } }) |
div({ attrs: { … } }) or div.attrs({ … }).create() |
div({ event: { click } }) |
div({ on: { click } }) or div.on({ click }).create() |
element('div', data) |
element('div')(data) |
use(plugin) |
a [LIVE] method on the value |
div(() => count.get() * 2) |
div(count.computed((n) => n * 2)) with @fiorejs/signals 2.0.0 |
The README's "Upgrading from 1.x" section has the details, and the documentation site describes the 2.0 API.
@fiorejs/signals 2.0.0
@fiorejs/signals 2 rebuilds signals as classes with a list and condition API, binds to fiorejs through the live-value protocol instead of a plugin, and forbids writes inside a computed. It requires fiorejs 2.0.0. Check "Breaking changes" before upgrading.
Breaking changes
- A bare function is no longer live.
div(() => count.get() * 2)shows the function's text; writediv(count.computed((n) => n * 2))ordiv(computed(() => …)). Functions insideclassListentries, aresourcesource andeffectstill work. eachis removed.each(todos, row)becomestodos.map(row), andeach(todos, row, (t) => t.id)becomestodos.for((t) => t.id).map(row).- A
computedcannot set a signal.set,updateormutatefrom a computed's run throws; derive the value instead, or set it in an effect or an event handler. - Methods must be called on the signal. Signals are classes now, so a detached
const { set } = countno longer works. - No plugin registration. Importing the package has no side effect, and
pluginis no longer exported. Signals carry fiorejs's[LIVE]method. Reactive<T>is a plain value or a signal;read()still accepts a function.
Added
signal.map(render)renders a list and keeps the rows of items it has seen;signal.for(key).map(render)keys the rows byitem.keyor by whatkeyreturns. Rows are kept per binding, and a row may render a fragment.signal.if(then).else(otherwise)shows one of two branches by the signal's truthiness. Only the shown branch is built, it is rebuilt only when the truthiness flips, and what it built stops when it switches.signal.computed(fn)derives a value from one signal, andsignal.with(fn)passes the signal to a reusable step.map,forandifare typed, andmapandforaccept only signals of arrays.
Improved
- Less memory and faster creation:
State,ComputedandResourceshare their methods through a class. In Node 26, creating 100,000state()takes 4.4 ms instead of 20.4 ms and uses 200 B per signal instead of 536 B. - A computed owns what its run creates. Bindings and effects created by a computed child stop before it recalculates and when it loses its readers, so content switched by a computed does not leak.
- A change made during a computed's run is not lost. If an effect inside a computed changes one of its inputs, the readers still get the current value.
classListreturns a computed value.- A binding is filed once under a fixed anchor, so a live child keeps pausing and resuming correctly when its nodes are moved, for example out of a JSX fragment.
Install with npm install fiorejs @fiorejs/signals. The README covers usage, lists, conditions and the known limits.
@fiorejs/jsx 2.0.0
@fiorejs/jsx 2 builds on fiorejs 2.0.0 and its live-value protocol. JSX syntax is unchanged. It requires fiorejs 2.0.0.
Changes
- Data object: the runtime now produces
{ props, attrs, on, children }and callselement(type)(data)from fiorejs 2. - Live values instead of plugins: a prop or child is live when it is a live value, such as a signal or computed from
@fiorejs/signals2.0.0. A function is never live:class={() => …}passes the function itself, so writeclass={computed(() => …)}. On a custom element, a function prop is therefore always a callback. - Children: the runtime passes children to fiorejs, which flattens nested arrays at any depth, so
{items.map(...)}next to other children works as before. - Fragments: a lone live child inside
<>…</>keeps updating after the fragment is inserted. - Custom elements: an object value, which includes every live value, goes to the property of that name, as the README explains.
Install with npm install fiorejs @fiorejs/jsx and set jsxImportSource to @fiorejs/jsx; the README has the setup.
@fiorejs/create 2.0.0
@fiorejs/create 2 scaffolds apps on fiore 2: fiorejs, @fiorejs/jsx and @fiorejs/signals 2.0.0. The command line options are unchanged.
Changes
- Dependencies: generated apps install
fiorejs,@fiorejs/jsxand@fiorejs/signalsat^2.0.0. - Templates use the 2.0 API: builders (
li.props({ ... }).create(...)) in the DOM templates, and in the signals templatestodos.for((todo) => todo.id).map(TodoItem)for the list,todo.done.computed(...)andleft.computed(...)for derived text and classes, andclassListfor conditional classes. A function is never a live value in fiore 2, so no template uses a bare getter. - No-build template: the import map points at the installed 2.0 packages in
node_modules, sonpm installis the only step before opening the page.
Run it with npm create @fiorejs@latest. Every combination of template, JSX, signals, linter and formatter was installed, type-checked, built, linted and format-checked against the 2.0 packages before this release.
1.2.0
This release fixes how props, attributes and children are applied, and adds an experimental plugin hook that the upcoming @fiorejs/signals and @fiorejs/jsx packages build on. Some fixes change behaviour; check the list under "Behaviour changes" before upgrading.
Behaviour changes
- Attribute values are passed through.
0and''are now set; 1.1.5 skipped every falsy value.nullandundefinedremove the attribute.falseremoves it too, except foraria-*,data-*and enumerated attributes such asdraggable, where it is written as"false". - Inline handler attributes are ignored. An attribute that is a real event handler of the element, such as
onclickin any case, is never set, so no handler string is run. Other names that start withon, such asonline, are set. Useeventfor listeners. - Children are kept when none are given. An element created without
childrenkeeps thetextContentorinnerHTMLset throughprops; 1.1.5 cleared it. null,undefined,trueandfalsechildren are skipped, souser.isAdmin && badge()works. Numbers are accepted as children.value,selectedIndexandcheckedare assigned after the attributes and children, soselect({ props: { value: 'M' }, children: [...] })selects the option.- Nested props merge only plain objects and their own keys.
undefinedleaves a property unchanged, and__proto__,constructorandprototypeare ignored. - MathML elements are created in the MathML namespace; 1.1.5 used the SVG namespace. The MathML
aelement is deprecated, because TypeScript and MathML Core do not define it. - Types: the SVG attribute map no longer accepts arbitrary keys, and
valueanddefaultValueare typed asstring | number | null | undefinedinstead ofany.
Added
- Experimental plugin hook.
use(plugin)registers a plugin by name that can bind live values to props, attributes and children. The API may change in a later release. fiorejs warns when it is loaded twice, because plugins registered on one copy do not reach the other. - Lists of more than 10,000 children are inserted in chunks instead of one spread call.
@fiorejs/signals 1.0.0
First release of @fiorejs/signals: signals for fiorejs that bind state to a property, attribute or child, so only that spot in the DOM updates when the state changes. Nothing re-renders and nothing is diffed. Importing the package registers it with fiorejs; it needs fiorejs 1.2.0 or later.
state,computed,effect,untrack,readandisSignalfor reactive state.resource(fetcher)andresource(source, fetcher)for loading data, withloadinganderrorsignals,refetch()andmutate(), and anAbortSignalthat cancels a load that is no longer needed.each(items, render, key)renders keyed lists and moves existing nodes instead of recreating them.- An effect whose run throws is reported with
reportErrorand stopped; other effects keep running.
Install with npm install fiorejs @fiorejs/signals. The README covers usage and the known limits.
@fiorejs/jsx 1.0.0
First release of @fiorejs/jsx: a JSX runtime for fiorejs. HTML and SVG written as JSX become real DOM nodes, created once, with no virtual DOM and no re-rendering. It needs fiorejs 1.2.0 or later.
- Props go to properties, attributes or listeners by name:
on+ event name becomes a listener (onClickandonclickboth listen toclick),styleobjects set style properties, andnullremoves an attribute. - Function components, fragments and async components; an async component shows a placeholder comment until it resolves.
- Signals and getters from a plugin such as
@fiorejs/signalswork as live props and children. - Typed per element: props, attributes and event handlers are checked against the element they are written on.
Install with npm install fiorejs @fiorejs/jsx and set jsxImportSource to @fiorejs/jsx. The README lists how each prop is applied.
@fiorejs/create 1.0.0
First release of @fiorejs/create. npm create @fiorejs creates a fiorejs app and asks for the build tool (Vite or none), the language (TypeScript or JavaScript), JSX, signals, a linter (ESLint, Oxlint or none) and a formatter (Prettier, oxfmt or none). Every question also has a flag, so it runs without prompts in scripts.
The generated apps use fiorejs 1.2, @fiorejs/jsx 1.0 and @fiorejs/signals 1.0. See the README for the flags.
1.1.5
Fix event and module resolution types Type imports in lib/types now carry the .d.ts extension, so props, attributes and children are checked under node16 and nodenext. Listeners use the element's own event map, type currentTarget as the element, and accept hyphenated custom event names as CustomEvent. generate-types pins TypeScript 5.9.