ferrovue

Vue single-file components compiled to Rust render functions. A Rust server renders a component's HTML with no JavaScript runtime, and the browser hydrates that HTML with the same .vue file.

• No Node on the server. The compiler runs at build time; the server is your Rust binary, and a render is a function call that writes into a String, 7.7 to 135 times faster than Vue's renderToString in the benchmarks (see Performance).
• Byte-identical to Vue. The generated Rust writes exactly the bytes Vue's renderToString writes for the same props, so Vue hydrates the page without a mismatch. Every supported construct is held to fixtures recorded from Vue.
• Exact or refused. What ferrovue cannot reproduce exactly is a compile error that names the file, line and construct. A component that compiles renders as Vue renders it.

ferrovue is at 0.8, before 1.0: a minor release may change the configuration, the generated code or the crates' API. The CHANGELOG says what changed, and the guide's upgrade pages (0.8 to 0.9, 0.7 to 0.8) say how to move a project.

 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.

Quick start

1. Install both halves

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

ferrovue needs Rust 1.89 or later (CI tests that and the latest stable). Generated code uses let-chains, so the crate that includes it needs edition 2024.

2. Configure

pnpm ferrovue init writes a starter ferrovue.config.json and components/Hello.vue. Or write the configuration at your project root yourself:

{
  "$schema": "https://cdn.jsdelivr.net/npm/ferrovue@0.8.0/schema.json",
  "components": "client/components",
  "out": "src/generated"
}

$schema points an editor at the configuration's JSON Schema, published with each version of the npm package, so VS Code and other JSON editors complete the keys, describe them on hover and flag a misspelt one. Name the version of ferrovue you use; ferrovue init writes it. ferrovue does not read $schema. Offline, the copy in the installed package works as well: "$schema": "./node_modules/ferrovue/schema.json".

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

pnpm ferrovue           # writes src/generated/{greeting.rs, mod.rs}
pnpm ferrovue --check   # in CI: exits 1 if the committed modules are stale
pnpm ferrovue --check --diff  # …and shows what differs, as `diff -u` does
pnpm ferrovue --check --format json  # errors as JSON, for an editor or CI annotations
pnpm ferrovue --watch   # regenerates when components or configs change

-c, --config <path> reads another configuration file. --watch regenerates on a change to what a run reads (the configuration, the components, stores, locale messages, pages or routes file, and the .ts files components import types from). A Vite project can use the plugin instead, which does the same in its dev server and before a build:

// vite.config.ts
import ferrovue from "ferrovue/vite";

export default { plugins: [ferrovue({ config: "config/ferrovue.json" })] };

root is the project root the configuration's paths are relative to (Vite's working directory by default), and config the configuration file in it, as --config takes it (ferrovue.config.json by default).

Every error carries a stable code, as error[FV1805]: components/Card.vue:4:17: …, documented in the error_codes guide. --format json writes the same errors as JSON with the exit status unchanged; the quick start has a VS Code problem matcher that puts them in the Problems panel.

#[rustfmt::skip]
mod generated;

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

// `new` takes the required props; each optional one has a setter.
let props = Props::new("Ada", 3).note("welcome back");

// 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();

// (`island()` exists for a component that renders from its props alone: the client rebuilds it from
// `data-props`. One that also takes slots, the route, stores, translations, teleports, provided
// values or the page head has `html()`, and the page's own app mounts it; see examples/fullstack.)

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

On the client, mountIslands(islands) from ferrovue, with islands from ferrovue/islands (written by the Vite plugin), hydrates every island on the page; see islands and hydration. 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.

The crate's features:

• router and i18n, both on by default: vue-router and vue-i18n. An application with neither routes nor translations can leave them out, and build neither ferrovue-router nor ferrovue-i18n: ferrovue = { version = "0.8", default-features = false }.

• axum and actix-web: Html is an IntoResponse or a Responder, so a handler responds with the component as text/html; charset=utf-8. into_html(props) and into_island(props) take the props by value, so a handler that builds them returns the page:

  async fn hello(Path(name): Path<String>) -> impl IntoResponse {
      greeting::into_html(greeting::Props::new(name, 0))
  }
  

• stream, which axum and actix-web turn on: HtmlStream, a page sent in the order its parts are ready.

• maud: ferrovue::Html implements maud::Render, so (greeting::html(&props)) goes straight into a maud::html! page.

• dioxus: {greeting::island(&props)} in a Dioxus 0.7 rsx! is the island element itself, with exactly the markup Vue hydrates inside it (examples/dioxus).

• ammonia: ferrovue::Sanitised, HTML cleaned by ammonia, for v-html. ferrovue::BasicHtml and ferrovue::InlineHtml are built in; the escaping guide describes all three.

The crate's feature flags list what each adds.

5. Diagnostics in your editor

ferrovue/volar is a plugin for Vue's language tools, which the Vue (Official) extension for VS Code and Vue support in other editors run. It compiles the project as you type and underlines what ferrovue refuses in the open component, with the error's code linked to its documentation. Name it in the tsconfig.json that includes your components, then run Vue: Restart Vue and TS servers:

{
  "include": ["components/**/*.vue", "components/**/*.ts"],
  "vueCompilerOptions": { "plugins": ["ferrovue/volar"] }
}

The quick start has the details; examples/fullstack/tsconfig.json enables it.

What a component may use

ferrovue compiles <script setup lang="ts"> components, and components with no script at all (an icon, a divider), which take no props. Props are declared by type, with defineProps<{ … }>(), an interface, or a type alias.

Anything else is refused at compile time, with an error that names the file, line and column, quotes the line and puts a caret under the construct. The errors_and_limits guide lists what is refused and why, and error_codes every code.

Guides

The crate's guide, ferrovue::guide on docs.rs, covers each topic in depth:

• Quick start and the generated code: what the compiler writes, and a component's Props, render, html and island
• Props: TypeScript types in Rust, dictionaries, shared types and constants
• Slots, scoped slots from Rust included
• Scoped styles: <style scoped> ids that match @vitejs/plugin-vue, v-bind() in <style>, CSS modules
• Routing, translating with vue-i18n, Pinia and provide and inject
• Teleports and the page head (useHead, useSeoMeta)
• Islands and hydration: islands, lazy hydration, a page hydrated whole, navigating between pages
• Streaming with holes, web frameworks (axum, actix-web) and Dioxus
• Numbers, strings and dates and prices: JavaScript's semantics in Rust
• Escaping and security
• Testing against Vue: your own components held to Vue with fixtures and two calls
• Errors and limits, with helpers, <ClientOnly> and Rust twins, and every error code
• Upgrading a project from 0.8 to 0.9 and from 0.7 to 0.8

examples/fullstack is a complete app to copy: an axum server, a Vite client, islands, Pinia, vue-router and streaming, with a test that it hydrates. CONTRIBUTING.md describes the repository and how to work on it.

Performance

Time to render one component to an HTML string: Vue's renderToString on Node, and the Rust that ferrovue generated from the same .vue file, given the same props. Each side checks its output against crates/ferrovue/benches/expected/<scenario>.html before anything is timed.

Mean times per render. Vue: tinybench's mean of one awaited renderToString(app), 5 s per scenario after a 1 s warm-up, the production build, each component with its SSR build's ssrRender, the app, Pinia and (for small) a vue-router at /users/me created outside the loop. ferrovue: criterion's mean point estimate (3 s warm-up, 100 samples) of a new String and one call of the generated render, release profile, the props, router and Route built outside the loop.

Measured on an AMD Ryzen 5 3600XT (6 cores / 12 threads, up to 3.8 GHz) with 62 GiB of RAM, running Linux 7.2.8-2-cachyos (CachyOS, x86_64), Node 26.10.0, Vue 3.5.43 and rustc 1.99.0, lightly loaded (a load average of about 1): treat the numbers as indicative. Most of Vue's time goes on component instances and their virtual nodes, of which tree has 255 and list one: per byte written, Vue renders list some fourteen times faster than tree, while ferrovue writes the two at a similar rate.

pnpm bench runs both halves (pnpm bench:rust, then pnpm bench:js), and pnpm bench:record rewrites benches/expected/*.html from Vue after a scenario changes. CI runs both in a short mode to check they build, run and agree on the HTML, and holds the instructions each scenario runs to within 5% of a committed baseline, and the time ferrovue and cargo build take on a project of 500 components to a budget; TESTING.md describes both.

Versions

Byte-identical output depends on Vue's own SSR compiler, so ferrovue compiles with an exact @vue/compiler-sfc (currently 3.5.44), and its conformance fixtures are recorded from one version of Vue and of each integration. Your project may use any later patch of the same minor:

A new minor of any of them (Vue 3.6, vue-router 5.5, …) needs a ferrovue release that re-records the fixtures from it. A weekly CI job re-records them from the newest patch each range allows and hydrates the committed HTML with it, so a patch that changes what Vue writes or hydrates is caught before it reaches you; a ferrovue patch follows when one does.

Deprecations

What ferrovue stops supporting is deprecated for at least one minor release and removed in the next major release. A deprecated crate item carries #[deprecated]; a deprecated configuration key warns with warning[FV1117] and a command-line option with warning[FV1118], naming the replacement, and the JSON Schema marks a deprecated key for editors. Each release's CHANGELOG lists what it deprecates under "Deprecated".

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.