Proposal: compile client code from real Rust to JavaScript instead of runtime expressions (working spike + benchmarks)

[GoldStrikeArch]

The limits of runtime expressions

I like how much $() expressions do with so little machinery. After building a few non-trivial apps I keep running into two limits and adding another operator will not fix either one.

First, $() accepts one syn::Expr which Topcoat transliterates into a JavaScript string. It does not support match, for, if statements, structs, enums, arrays, ?, assignment, or even && and ||. The expression language has one numeric type and integers fail compilation. Today client code cannot express anything that needs a loop or data structure (eg something like a filterable list, grid or state machine).

Second, the Rust and browser implementations can disagree without a compiler error. Each operation available inside $() has two implementations: one in the Rust surrogate types and one in the TypeScript browser surrogates. The compiler checks that the Rust expression typechecks against the surrogate mirror but it never compares that behavior with the browser implementation. When the two implementations differ, the same $() expression evaluates differently on the server and in the browser. The tracker contains five examples:

• String comparison in reactive expressions disagrees between server and client #236
• f64 text rendering differs between server and client #237
• trim() strips U+FEFF in the browser but not on the server #238
• Define and test Unicode semantics for shared String methods #125
• Capturing a tuple in a runtime expression throws at hydration #254, caused by the deserializer's missing array case. It remains open but there is a fix in fix(runtime): hydrate a tuple captured by a runtime expression #255.

The individual fixes address each reported bug, but every new operation adds another place where the implementations can disagree.

State also reaches the client as a one-time JSON snapshot. Signals are the only live handles. The handwritten browser runtime scans the DOM once, so HTML inserted or replaced outside the runtime loses its bindings. Third-party JavaScript still requires a script tag and globals.

What I built

I built a spike around a rustc codegen backend. It compiles monomorphized MIR to readable JavaScript for the dom-expressions runtime used by SolidJS. The design follows SolidStart's server and client split, with Rust as the language. Topcoat still runs the server with hyper, view!, and SSR, while client components become Rust functions compiled to JavaScript. The backend emits JavaScript rather than WASM and the users do not need node in their toolchain and the serving path has no bundler.

Today the backend compiles structs, enums, tuples, arrays, slices, closures, dyn and vtables, drop glue, generics, and recursion. It also implements per-width integer semantics with BigInt for i64, u64, and i128, Box, Vec, String, format!, Rc, and Arc, iterators and sorting, async fn and .await and panics with #[track_caller] locations.

The backend builds core and alloc into its sysroot and uses no surrogate types. For unsupported constructs such as byte punning, threads, and std, it uses the reachability-gated error model from rust-gpu. A construct fails the build only when reachable from user code and the diagnostic includes the call chain.

In the spike, view! macro has a third emitter that produces dom-expressions calls. The browser uses solid-js 1.9.14, shipped as one 9.1 KB gzip bundle. The server emitter and compiled client allocate identical hydration keys. A jsdom parity test enforces this by asserting node identity.

#[island] produces one chunk per island and hydrates it lazily. #[procedure] calls procedures from compiled code over a typed serde wire. #[js_extern] declares foreign JavaScript with checked shapes and emits .d.ts declarations.

Debug information supplies names in the generated JavaScript. The code generator uses an expression queue and destination passing to avoid temporary-heavy output, and source maps let DevTools step through the original Rust. One compiled function looks like this:

function area(r) {
  return Math.imul(r.w, r.h) | 0;
}

Live demos

The live demos compile their islands from Rust and contain no handwritten JavaScript. The demo source is public.

• The island showcase runs Game of Life, falling sand on a canvas, and Minesweeper with recursive flood fill. The current expression language cannot express these programs.
• The benchmark demo runs the js-framework-benchmark app as an island.

Benchmarks

I ran the full upstream js-framework-benchmark suite locally across six implementations. Every reference implementation matched its published results. The full tables and methodology include the committed versions and pins. The run is reproducible with bench/setup.sh && bench/run.sh.

implementation	geomean vs vanillajs keyed	transferred, Brotli	first paint
vanillajs keyed	1.00	2.5 KB	53.7 ms
vanillajs non-keyed	0.85	2.4 KB	58.3 ms
topcoat-vanilla, compiled Rust and direct DOM	0.98	9.8 KB	81.6 ms
solid keyed	1.15	4.5 KB	58.9 ms
leptos keyed, WASM	1.16	48.8 KB	241.1 ms
topcoat-island, idiomatic view!	2.76	21.2 KB	47.9 ms

In this run, topcoat-vanilla scores 0.98 against keyed Vanilla JS at 1.00, compared with 1.15 for Solid and 1.16 for Leptos. It transfers 9.8 KB, about one fifth of Leptos's 48.8 KB, and its 81.6 ms first paint is about one third of Leptos's 241.1 ms.

The server-rendered topcoat-island records the fastest first paint at 47.9 ms. The linked benchmark report attributes its 2.76 geomean to the unkeyed list model's cost on partial update, select, and swap. A counter-only page transfers about 14 KB gzip in total, including the shared runtime.

What changes compared with $()

• Client code can use loops, match, structs, enums, collections, recursion, and async in the browser. The showcase demonstrates each category.
• rustc typechecks client code against core, and the backend emits Rust semantics. There is no TypeScript surrogate implementation to drift from the Rust implementation.
• #[js_extern] checks foreign JavaScript shapes and emits .d.ts declarations. #[repr(C)] structs cross the boundary as plain objects without a converter layer.
• Hydration uses solid-js instead of the one-shot DOM scan. Per-island chunks transfer code only for the islands on a page.
• Generated JavaScript keeps names from debug information, and its source maps point back to the original Rust.
• The compiled path is additive. It leaves the existing runtime and $() path unchanged.

Limitations

• The backend currently pins one rustc nightly, following the rust-gpu maintenance model. I have not investigated whether that constraint can be relaxed.
• npm package resolution is not implemented. Only single-file ESM or vendored libraries work. Closures cannot yet cross #[js_extern], so addEventListener cases use a small handwritten bootstrap. The benchmark's bootstrap is 22 lines.
• Only panic=abort works. Unwinding does not.
• The architecture rules out byte punning across representations. The affected cases include f64 through serde, TypeId, and SIMD. Threads and std itself are also out.

Questions

1. Would Topcoat consider compiled Rust to JavaScript for client code?
2. Would solid-js be acceptable as the target runtime? I chose it because its signals match Topcoat's model and I could turn its hydration contract into an executable test suite.
3. The spike currently coexists with $(). Should both remain long term, or should they converge?
4. What would the distribution model need before a serious upstreaming conversation? Would that require prebuilt backends per release channel, a toolchain-pinning UX, or something else?

The branch, compiler contract, and benchmark results are public:

• Spike branch
• Compiler contract covering the value model, heap, templates, and FFI
• Benchmark tables

[AmeinEskinder]

Four of the five issues in your bug-class list are mine, so let me add the part the tracker doesn't show: how each was actually found. I think that bears on the argument more than the count does.

One correction first — #254 has a fix open at #255. The issue is open; the fix isn't merged. I'd rather that read accurately than more damningly than it deserves.

#236 and #238 were found by reading the two implementations side by side. That's the honest case for "a careful reviewer catches these."

#237 is the one I'd point at. It reported four divergences, and fixing them was routine. But building a differential harness against rustc turned up a fifth nobody had seen: when two equally short digit strings are exactly equidistant from the value, ECMAScript resolves the tie to the even final digit and Rust resolves it away from zero, so 1690060720831323.25 renders …323.3 on the server and …323.2 in the browser. Three mismatches in the first 20,027 random doubles. It is invisible to reading — the reporter missed it, I missed it, and it only surfaced against a 300,016-value comparison with real Display output.

#254 I found by hunting the class rather than by hitting it: diffing the surrogate method sets between the two sides looking for asymmetries. tuple.rs exists on the Rust side with no tuple.ts; the grammar compiles pair.0 to pair[0]; hydrateSurrogate has no array case. One deliberate pass produced a live one.

The strongest evidence I can offer, though, is a mitigation I wrote rather than a bug I found. #270 adds a Decimal with independent comparators in both languages, and I pinned them together with a shared comparison table asserted on both sides — precisely because I did not trust two implementations of one algorithm to stay in sync across a release. That is a design property being papered over, and I am the one who wrote the paper.

Two honest counterweights. Each instance was cheap to fix, and parity tests now exist for the methods involved, so the standing exposure is new vocabulary rather than the current surface. And I should disclose that I have open PRs in the layer this proposal would replace (#255, #269, #270, #271), so I am not a neutral party on whether it should be replaced.

Whether four in a week is a rate that justifies a change this size is a judgement I don't think a contributor should make on your behalf. But the diagnosis matches what I found from the inside.

[GoldStrikeArch]

@AmeinEskinder

Thank you! This is a better account of the bug class than my summary, from the person who actually did the fixing. I've updated the issue so #254 reads with "fix open at #255".

And I should disclose that I have open PRs in the layer this proposal would replace (#255, #269, #270, #271), so I am not a neutral party on whether it should be replaced.

To be clear on the scope of this issue: the whole spike is additive and nothing here proposes replacing current work. The demos exist to establish what a real compiler path makes possible so maintainers can judge the direction. Whether and how it lands is a separate discussion and unlikely to happen "fast" (if it will happen at all 😅 ) as first of all the whole spike was just a research, the compiler is real, it works but I only tested a subset of possible "common programs" you can make. There are likely a lot of edge cases missed and so on. It can be a "separate track" within this repo, so it can replace $() expressions at some point or run side-by-side (again, depends on how maintainers would take it, maybe they will say "thanks, but no" which is also a valid answer)

[EbaraKoji]

I think the codegen backend should be implemented as a separate crate rather than directly as part of Topcoat.

I agree with the general direction proposed here. The current runtime expression approach has inherent limitations: as client-side event handlers become more complex, supporting additional Rust expressions and control flow becomes increasingly difficult, and subtle semantic differences between Rust and JavaScript can also become a source of bugs. Using a rustc codegen backend has a significant advantage in that it can leverage Rust's existing compiler infrastructure and operate on MIR rather than requiring Topcoat to incrementally reimplement Rust semantics.

At the same time, a rustc codegen backend is a relatively low-level and potentially very complex component, involving MIR, Rust type/layout semantics, pointer representation, control flow, and the differences between Rust and JavaScript semantics. Therefore, I think it deserves to be developed and reviewed as an independent compiler component rather than being tightly coupled to Topcoat.

In particular, Rust → JS differential testing should be a core part of its development: representative Rust programs should be executed natively and as generated JavaScript, with their behavior compared to detect subtle semantic mismatches. This is fundamentally different from Topcoat's SSR, hydration, or UI-level tests.

Therefore, I would suggest keeping the codegen backend as an independent crate with its own implementation, tests, and CI, and having Topcoat depend on it. This would allow the backend to be developed incrementally with rigorous testing and review, while keeping the promising rustc codegen approach itself independent from Topcoat's application-level implementation.

[GoldStrikeArch]

@EbaraKoji

Yes, I think this is a good direction overall (to move out into a separate create and have a tiny "bridge" in the topcoat itself). The current implementation is already generic enough to be extracted. Initially I thought that it can just live in the repo itself, just as a separate internal crate, with it's own testing infra and so on. The reason is that right now only topcoat is a potential user but on the other hand if it would be a completely separate crate maybe someone else would use it 🤔

I would like to hear the thoughts of the maintainers whether they are even interested in that in the first place

In particular, Rust → JS differential testing should be a core part of its development: representative Rust programs should be executed natively and as generated JavaScript, with their behavior compared to detect subtle semantic mismatches.

In theory it could also live in this "internal crate" and not "pollute" the top level infra. Right now there are a lot of tests and I stole some of them from Melange/js_of_ocaml and other projects like that "LanguageX-to-JS-compiler" (like dart2js, scala.js and so on)

[pikaju]

Hey @GoldStrikeArch, sorry for the late response. I missed this issue for some reason, maybe I confused it with a different one. First of all, this is a very cool idea, thank you for trying it out. I must admit, on first glance I don't understand the full scope of this or how it works exactly. Does this rerun the entire island in the browser, including the view! macro and everything? Or just the $(...)? How do they coexist?

I should maybe explain how Topcoat got to the point where it is now. The reason we made a server rendering framework is because we felt that Leptos/Dioxus are already very strong solutions for the WASM client rendering space. However, having a separate build target and maintaining the browser/server split isn't for everyone, so we wanted to try what it would look like to instead have the server be the authority at all times, with only minimal JS to swap out HTML. We looked at Datastar for inspiration, and they have a simple expression language (well, JavaScript...) to handle small pieces of logic in the browser, while having the server still do most of the work. This is what $(...) was supposed to be. Not a feature complete language, but the bare minimum to swap out a class here and there, set a signal or two, call a procedure, thats it. Cross-compiling Rust to JavaScript in the macro was an attempt to keep everything type-checked and rusty. I know that the current system is very flawed. In my opinion we shipped it prematurely. But, I also believe it has a lot of untapped potential still. Some arguments for it: It 1) needs no build step, 2) needs no separate compilation target, 3) needs no code splitting or bundle management, 4) has (granted currently fragile) type checking, 5) can run on the server trivially.

Looking at this now, I am worried that it introduces the same WASM headache that we wanted to avoid in the first place. To be clear, I might be misunderstanding this, and so forgive me if I'm coming to the wrong conclusions here. Please correct me if I am wrong. From my view, it seems that if the goal is to have client-side Rust, we should've taken the Leptos route from the beginning. I wanted to see how far we can get with a server-side signal system and a live-wirey setup that is currently being prototyped. The version of Topcoat that is currently released is not powerful enough, I am definitely aware of that.

I am still very open to these ideas though! Let's keep discussing it.

[GoldStrikeArch]

@pikaju

Here are some clarifications about the whole spike + the demo:

I must admit, on first glance I don't understand the full scope of this or how it works exactly. Does this rerun the entire island in the browser, including the view! macro and everything? Or just the $(...)?

So, I created a new attribute #[island] in Topcoat and it kinda behaves like Astro/Solid-start from the JS ecosystem. It compiles twice during build time (the "server version" and the "client/browser version" and the "client version" is a JavaScript, not WASM) then the server emits it's HTML during the initial render then the "hydration" happens and then after that phase the island can manipulate the DOM via compiled JavaScript from the view! body. Basically this allows us to create "any UI" similar to what Astro/Solid-start are doing. So, suppose you have this code:

#[island]
pub async fn counter(start: f64) -> Result {
    view! {
        signal count = start;
        <p>"count " $(count.get())</p>
        <button @click=$(|_e| count.set(count.get() + 1.0))>"+1"</button>
    }
}

• The server compiles this to an ordinary #[component]. It renders the HTML exactly as Topcoat does today, plus hydration keys wrapped in a <topcoat-island> element.
• The client crate compiles the same view! body (under cfg(topcoat_client)) to a small JS module that knows how to find the nodes the server already emitted and attach the $() holes to them. Hydration itself makes zero DOM mutations (and the click on the counter obviously makes one).

So $() keeps exactly the same role as today: it marks the small reactive bits. What changes is who compiles its body as right now instead of a syn::Expr transliterated to a JS string and checked against surrogate types, it is Rust compiled by rustc against the real core/alloc via our custom "rust to JS" compiler.

And that means that now you can use match, Vec, Arc/Rc, format!, Box and things like that but here are limitations, like no threads, SIMD and some other things.

How do they coexist?

Outside of #[island] nothing changed in the Topcoat, so the $()/view! will behave as today in other places

Looking at this now, I am worried that it introduces the same WASM headache that we wanted to avoid in the first place. To be clear, I might be misunderstanding this, and so forgive me if I'm coming to the wrong conclusions here. Please correct me if I am wrong. From my view, it seems that if the goal is to have client-side Rust, we should've taken the Leptos route from the beginning.

So, here is the table that summarizes the differences:

	$() today	compiled islands
no build step	yes	yes and no -> a second rustc pass in build.rs, but nothing outside cargo (no Node, npm, bundler, wasm-bindgen, etc)
no separate target	yes	roughly yes -> same source file, same rustc. The split is one attribute on one function
no code splitting / bundle management	yes	yes: the compiler emits one chunk per island plus a shared chunk and the import map, lazy-loaded on visibility
type checking	fragile	rustc against real core/alloc
runs on the server	yes	yes: that's the server half as it is the SSR component

There is a burden in the toolchain though -> the "rust to js" compiler links rustc's internal crates via rustc_private and is pinned to one exact nightly version (the same thing as rust-gpu and cranelift are doing). The island code is ordinary Rust and only the "compiler backend" is pinned. Distribution (prebuilt backends per nightly version, bump cadence, etc) is unsolved right now. So this is why I kinda agrees with @EbaraKoji that maybe the compiler itself can be separate crate altogether and Topcoat will just depend on the "bridge" to it or maybe it can stay as internal "subcrate" in this repo but with it's own toolchain/CI/tests and so on

Where we are different from Leptos/Dioxus:

• we output JS instead of WASM and IMO it is better (the emitted code is readable JS, source maps step back into the Rust in DevTools, there is no binary to fetch and instantiate and no bindgen glue). The view! macro in the #[island] also outputs the dom-expressions compatible code, so in theory you can also use solid-js inside the island or vise-versa. The interop with some third party JS on the page is also easier to achieve as there are no "WASM bridges"
• the JS output is minimalistic and ships around 9KB gzipped "shared runtime" plus about 1 KB per island. For example, in the js-framework-benchmark app Leptos ships 48.8 KB(brotli) and first-paints at 241ms the Topcoat island version of the same app ships 21.2KB and paints at 48ms because the server already rendered the page.
• although Leptos did introduce the #[island] macro in their own not that long ago IIRC, so we might not be that different :D

The real gains for the Topcoat if you go that road:

• you now can create applications which are server rendered as before but with a much richer UI and "latency sensitive UI" (what I mean here are some applications where you want immediate feedback without going round-trips over the network): canvas, some dashboards, interactive pieces like custom dropdowns, etc. Those things today would need hand written JS to work properly, now it can be a pure Rust
• the $() doesn't need a second implementation and can contain "almost any idiomatic Rust code"
• third party JS through #[js_extern] (also created during this research) with checked shapes and .d.ts type output instead of globals

[gbj]

I just wanted to offer a thought, as I see Leptos has been mentioned here a couple of times as a comparison point.

Bigger-Picture Framing Point

I think the proposal is conflating two orthogonal topics here: 1) Rust compile targets for the web and 2) framework design

• Rust compile targets for the web: traditionally this has been to WASM for two reasons: a) higher performance on certain kinds of tasks, and b) it's a good compile target for Rust. Note that "certain tasks" in (a) does not include most application programming; the use of WASM as a target for application programming compared to JS frameworks achieves no performance benefit. So let's ignore that part and say that WASM has, to date, been the only way to compile Rust to run in the browser, but has not other inherent virtue. So, this method of compiling normal Rust to normal JS is really cool! It's very possible that this is a good (or even better?) target for compiling Rust application code (as opposed to computationally-intensive code) for the browser, for any framework. Really interesting stuff and worth continuing to explore.
• framework design: the decision point here is between "isomorphic" approaches (same code runs on server/client: Leptos, Dioxus, React/Next, Vue/Nuxt, Svelte/SvelteKit, Sold, etc.) and "server-driven + DSL" (the world of HTMX, Alpine, Datastar, current Topcoat).

You could divide this into quadrants... "Compiles Rust to WASM or JS?" and "isomorphic or DSL?" Current Leptos/Dioxus are WASM/isomorphic, current Topcoat is JS/DSL. The proposal here shifts Topcoat from the JS/DSL quadrant to the JS/isomorphic quadrant.

I think that's the design decision to be made. I don't have an opinion on which path Topcoat should take, I just thought it might be a helpful clarification.

Nits and notes on the comments above

Just for the sake of clarifying anything that seemed off to me.

topcoat-island, idiomatic view! [geomean on js-framework-benchmark] 2.76

To anyone who's not familiar with this benchmark, 2.76 is a really high score (i.e., really, really slow). I assume it's because there's not a good keyed list implementation being used here? That's most of what the benchmark measures. Whether this is a useful benchmark or not is debatable, but I think it's worth noting that this puts it in the slowest 3% of results.

The server-rendered topcoat-island records the fastest first paint at 47.9 ms.
...
Leptos ships 48.8 KB(brotli) and first-paints at 241ms the Topcoat island version of the same app ships 21.2KB and paints at 48ms because the server already rendered the page.

This sounds like you're comparing apples (server-rendered Topcoat) to oranges (client-rendered everything else) and saying that first paint is faster for server rendering. This is true; server rendering gives a faster first paint, which is why all the frameworks you're comparing to support it. Unless I'm mis-reading and you did have Leptos server-rendering here?

although Leptos did introduce the #[island] macro in their own not that long ago IIRC

3 years ago :-) Hard to believe... time flies!