ferrovue

Vue single-file components compiled to Rust render functions. With them, a Rust server renders a component's HTML with no JavaScript at run time, and the browser hydrates the result with the same .vue file.

 Button.vue ──(ferrovue compiler, Node)──▶ button.rs ──(your Rust server)──▶ HTML ──▶ Vue hydrates it

ferrovue doesn't interpret templates. It takes what @vue/compiler-sfc compiles a template to for server rendering (straight-line _push calls plus a few @vue/server-renderer helpers) and translates that small, closed vocabulary into Rust that writes the same bytes. Vue still decides element structure, attribute order, whitespace and fragment markers. If a single byte differed, the browser would report a hydration mismatch, so anything outside that vocabulary is a compile error that names the component and the construct. ferrovue never guesses.

The project has two halves:

Quick start

1. Install both halves

pnpm add -D ferrovue          # or npm / yarn
cargo add ferrovue serde --features serde/derive
cargo add --dev serde_json    # the generated conformance helper uses it under cfg(test)

ferrovue supports the latest stable Rust, currently 1.99. Generated code uses let-chains, so the crate that includes it needs edition 2024.

2. Configure

ferrovue.config.json at your project root:

{
  "components": "client/components",
  "out": "src/generated"
}

3. Write a component

<!-- client/components/Greeting.vue -->
<script setup lang="ts">
defineProps<{ name: string; unread: number; note?: string }>();
</script>

<template>
  <p class="greeting">Hello, {{ name }}!<b v-if="unread">{{ unread }} new</b><i v-if="note">{{ note }}</i></p>
</template>

4. Generate and render

npx ferrovue            # writes src/generated/{greeting.rs, mod.rs}
npx ferrovue --check    # in CI: exits 1 if the committed modules are stale

#[rustfmt::skip]
mod generated;

use generated::greeting::{self, Props};

let props = Props { name: "Ada".into(), unread: 3, note: None };

// The markup alone:
let html: String = greeting::html(&props).into_string();

// …or as an island the client hydrates: wrapped in
// <div data-island="Greeting" data-props="{…}">…</div>
let island = greeting::island(&props).into_string();

// …or straight into a buffer you already hold:
let mut page = String::from("<!doctype html><body>");
greeting::render(&mut page, &props);

With routes configured, the generated route_table::router() builds the router once. Resolve each request's location with router.at(path) and pass the result to the components that take a route.

With the maud feature, ferrovue::Html implements maud::Render, so (greeting::html(&props)) can go straight into a maud::html! page.

What a component may use

ferrovue compiles <script setup lang="ts"> components. Props are declared by type, with defineProps<{ … }>(), an interface, or a type alias.

Refused at compile time, each with an error that names the construct:

• <style scoped>, <style module>, and v-bind() in CSS
• <Teleport> and <component :is>
• <RouterLink custom>, slot props that are array literals, defaults in destructured slot props, and outlets of one slot that pass different props
• custom directives not listed in clientDirectives
• watchEffect, watch with immediate, onServerPrefetch, top-level await, and statements in setup that change state
• route.query and route.fullPath, and setup stores
• Pinia getters that read this or return a function
• / and fractions, ordering comparisons of strings
• null
• any method call without a Rust twin

An object prop handed to a child component is cloned. Its strings are Cows, so borrowed ones cost nothing to copy.

Scoped slots from Rust

A scoped slot's Slots field takes a closure that receives the props its outlet passes, as a generated …SlotProps struct borrowed for the render. The closure returns whether it wrote content; returning false shows the slot's fallback, as empty content does in Vue.

let row = |out: &mut String, p: &data_list::RowSlotProps<'_>| {
    ferrovue::escape_into(out, p.label);
    true
};
data_list::render(&mut page, &props, data_list::Slots { row: Some(&row), ..Default::default() });

Hydrating Pinia state

ferrovue::state_script_into(&mut page, "__pinia", &stores);   // a <script type="application/json">

import { hydrateState } from "ferrovue/client";
hydrateState(pinia); // before app.mount(): every store starts from what the server rendered

Streaming with holes

ferrovue::hole() is a slot whose content you write later. Render a layout with holes, split_holes the output, and stream the pieces with each hole's content between them, in whatever order the content is ready.

Versions

Byte-identical output depends on Vue's own SSR compiler, so the package pins vue, @vue/compiler-sfc and @vue/server-renderer to an exact version (currently 3.5.43). Upgrading Vue means re-running the conformance suite (see TESTING.md) and releasing a new ferrovue version.

Repository layout

crates/ferrovue/             the Rust runtime crate
  src/                       runtime + unit tests
  tests/conformance/         components, fixtures, recorded HTML, generated Rust
  tests/vectors/             string and router vectors shared with the TypeScript tests
  tests/properties.rs        property-based tests of the runtime
packages/ferrovue/           the compiler (npm package)
  src/compiler.ts            .vue → Rust
  src/cli.ts                 the `ferrovue` command
  src/client.ts              browser-side helpers
  src/testing.ts             utilities for a project's own conformance suite
  test/                      compiler, CLI, router, vector and conformance tests

Development

pnpm install
pnpm test          # compiler, CLI and the Vue half of the conformance suite
pnpm typecheck
cargo test --all-features

TESTING.md explains how the suite fits together and how to add a case.

Licence

Licensed under either of Apache License, Version 2.0 or MIT licence, at your option. Unless you explicitly state otherwise, any contribution you intentionally submit for inclusion in this work, as defined in the Apache-2.0 licence, is dual-licensed as above, without any additional terms or conditions.