cargo leptos 0.5.0
v0.5.0
on Rust Cargo

latest releases: 0.7.0-rc1, 0.7.0-rc0, 0.7.0-preview2...
13 months ago

v0.5.0

Goodbye, Scope

This long-awaited release changes the nature of the reactive system by removing the entire concept of explicit Scope and the ubiquitous cx variable.

The primary impetus behind this change is that it increases the correctness of the behavior of the reactive system, and fixes several persistent issues.

Click here for more details. In order to provide signals that implement `Copy` are are `'static` and are therefore easy to use with closures and event listeners in 100% safe Rust, Leptos allocates memory for signals, memos, and effects in an arena. This raises the question: When is it safe to deallocate/dispose of these signals?

From 0.0 to 0.4, Leptos allocated signals in a dedicated Scope, which was ubiquitous in APIs. This had several drawbacks

  1. Ergonomics: It was annoying additional boilerplate to pass around.
  2. Trait implementations: Needing an additional Scope argument on many functions prevented us from implementing many traits that could not take an additional argument on signals, like From, Serialize/Deserialize.
  3. Correctness: Two characteristics made this system somewhat broken
  • The Scope was stored in a variable that was passed around, meaning that the “wrong” scope could be passed into functions (most frequently Resource::read()). If, for example, a derived signal or memo read from a resource in the component body, and was called under a Suspense lower in the tree, the Scope used would be from the parent component, not the Suspense. This was just wrong, but involved wrapping the function in another closure to pass in the correct Scope.
  • It was relatively easy to create situations, that could leak memory unless child Scopes were manually created and disposed, or in which on_cleanup was never called. (See #802 and #918 for more background.)

The solution to this problem was to do what I should have been doing a year ago, and merge the memory allocation function of Scope into the reactive graph itself, which already handles reactive unsubscriptions and cleanup. JavaScript doesn’t deal with memory management, but SolidJS handles its onCleanup through a concept of reactive ownership; disposing of memory for our signals is really just a case of cleanup on an effect or memo rerunning.

Essentially, rather than being owned by a Scope every signal, effect, or memo is now owned by its parent effect or memo. (If it’s in an untrack, there’s no reactive observer but the reactive owner remains.) Every time an effect or memo reruns, it disposes of everything “beneath” it in the tree. This makes sense: for a signal to be owned by an effect/memo, it must have been created during the previous run, and will be recreated as needed during the next run, so this is the perfect time to dispose of it.

It also has the fairly large benefit of removing the need to pass cx or Scope variables around at all, and allowing the implementation of a bunch of different traits on the various signal types.

Now that we don't need an extra Scope argument to construct them, many of the signal types now implement Serialize/Deserialize directly, as well as From<T>. This should make it significantly easier to do things like "reactively serialize a nested data structure in a create_effect" — this removed literally dozens of lines of serialization/deserialization logic and a custom DTO from the todomvc example. Serializing a signal simply serializes its value, in a reactive way; deserializing into a signal creates a new signal containing that deserialized value.

Migration is fairly easy. 95% of apps will migrate completely by making the following string replacements:

  1. cx: Scope, => (empty string)
  2. cx: Scope => (empty string)
  3. cx, => (empty string)
  4. (cx) => ()
  5. |cx| => ||
  6. Scope, => (empty string)
  7. Scope => (empty string) as needed
  8. You may have some |_, _| that become |_| or |_| that become ||, particularly for the fallback props on <Show/> and <ErrorBoundary/>.

Basically, there is no longer a Scope type, and anything that used to take it can simply be deleted.

For the 5%: if you were doing tricky things like storing a Scope somewhere in a struct or variable and then reusing it, you should be able to achieve the same result by storing Owner::current() somewhere and then later using it in with_owner(owner, move || { /* ... */ }). If you have issues with this kind of migration, please let me know by opening an issue or discussion thread and we can work through the migration.

Islands

This release contains an initial, but very functional, implementation of the “islands architecture” for Leptos.

This adds an experimental-islands feature that opts you into a rendering mode that's different from the traditional server-rendered/client-hydrated model described here, in which the entire page requested is rendered to HTML on the server for the first request, and then runs on the client to hydrate this server-rendered HTML, and subsequent navigations take place by rendering pages in the browser.

The experimental- in experimental-islands means “parts of this API may need to change, and I won’t guarantee that its APIs won’t break during 0.5,” but I have no reasons to believe there are significant issues, and I have no planned API changes at present.

With this islands feature on, components are only rendered on the server, by default. Navigations follow the traditional/multi-page-app (MPA) style of navigating by fetching a new HTML page from the server. The name "islands" comes from the concept of the "islands architecture," in which you opt into small “islands” of interactivity in an “ocean” of server-rendered, non-interactive HTML.

This allows reducing the WASM binary size by a lot (say ~80% for a typical demo app), making the time-to-interactive for a page load much faster. It also allows you to treat most components as “server components” and use server-only APIs, because those plain components will never need to be rendered in the browser.

I still need to write some guide-style docs for the book, but I tried to put a pretty good amount of information in the PR, which you should read if you’re interested in this topic or in trying out islands.

There’s significant additional exploration that will take place in this direction. Expect a longer treatment in an upcoming updated roadmap posted as a pinned issue.

Additional Reading

Static Site Generation

This release includes some preliminary work on building static site rendering directly into the framework, mostly as part of leptos_router and the server integrations. Static site generation is built off of two key components, a new <StaticRoute /> component and the leptos_router::build_static_routes function.

StaticRoute defines a new static route. In order to be a static route, all parent routes must be static in order to ensure that complete URLs can be built as static pages. A “static route” means that a page can be rendered as a complete HTML page that is then cached and served on subsequent requests, rather than dynamically rendered, significantly reducing the server’s workload per request.

StaticRoute takes a path and view (like any Route) and a static_params prop. This is a function that returns a Future, which is used to provide a map of all the possible values for each route param. These static params are generated on the server. This means you can do something like call a #[server] function or access a database or the server filesystem. For example, if you have a /post/:id path, you might query the database for a list of all blog posts and use that to generate a set of possible params.

StaticRoute can be given an optional mode: StaticMode::Upfront (the default) or StaticMode::Incremental. Upfront means that all given routes will be generated when you call build_static_routes, and a 404 will be returned for any other pages. Incremental means that all the options you give in static_params will be generated up front, and additional pages will be generated when first requested and then cached.

Where our routes are defined, we can include a StaticRoute: 

view! {
	<Routes>
		<StaticRoute
			mode=StaticMode::Incremental
			path="/incr/:id"
			view=StaticIdView
			static_params=move || Box::pin(async move {
				let mut map = StaticParamsMap::default();
				map.insert("id".to_string(), vec![(1).to_string(), (2).to_string()]);
				map
			})
		/>
	</Routes>
}

In main.rs, we build the static routes for the site on server startup: 

let (routes, static_data_map) = generate_route_list_with_ssg(App);
build_static_routes(&conf.leptos_options, App, &routes, &static_data_map)
	.await
	.unwrap();

More to Come

There is additional work needed here as far as providing examples, and building out the story for things like invalidation (when to rebuild a page) and build hooks (when to build additional pages).

Other New Features in 0.5

attr: on components, and spreading attributes

Makes it much easier to pass some set of attributes to be given to a component (with attr: passed into a #[prop(attrs)] prop), and then to spread them onto an element with {..attrs} syntax. 

#[component]
pub fn App() -> impl IntoView {
    view! {
        <Input attr:value="hello" attr:label="foo" />
        <Input attr:type="number" attr:value="0" />
    }
}

#[component]
pub fn Input(
    #[prop(attrs)] attrs: Vec<(&'static str, Attribute)>,
) -> impl IntoView {
    view! {
        <input {..attrs} />
        <pre>{format!("{attrs2:#?}")}</pre>
    }
}

Generics on components in view

Newly added support for syntax that identifies a generic type for a component in the view 

#[component]
pub fn GenericComponent<S>(#[prop(optional)] ty: PhantomData<S>) -> impl IntoView {
    std::any::type_name::<S>()
}

#[component]
pub fn App() -> impl IntoView {
    view! {
        <GenericComponent<String>/>
        <GenericComponent<usize>/>
        <GenericComponent<i32>/>
    }
}

Callback types

This release includes a Callback type that makes it much easier to pass optional callbacks as component props, which was previously not possible with generically-typed callbacks. 

#[component]
fn MyComponent(
    #[prop(optional, into)] render_number: Option<Callback<(i32, i32), String>>,
) -> impl IntoView {
    render_number.map(|render_nummber| {
        view! {
            <div>
                // function call syntax works on nightly
                {render_number((42, 37))}
                // does the same thing
                {render_number.call((42, 37))}
            </div>
        }
    })
}

#[component]
pub fn App() -> impl IntoView {
    view! {
        <MyComponent render_number=|(x, y)| format!("x: {x} - y: {y}")/>
    }
}

with!() and update!() macros

Nested .with() calls are a pain. Now you can do 

let (first, _) = create_signal("Bob".to_string());
let (middle, _) = create_signal("J.".to_string());
let (last, _) = create_signal("Smith".to_string());
let name = move || with!(|first, middle, last| format!("{first} {middle} {last}"));

instead of 

let name = move || {
	first.with(|first| {
		middle.with(|middle| last.with(|last| format!("{first} {middle} {last}")))
	})
};

Rustier interfaces for signal types

This framework's origins as a Rust port of SolidJS mean we've inherited some functional-JS-isms. Combined with the need to pass cx everywhere prior to 0.5 this has tended to mean we've gone with create_ and so on rather than Rusty ::new(). This simply adds a few Rustier constructors like 

let count = RwSignal::new(0);
let double_count = Memo::new(move |_| count() * 2);

Optional #[server] Arguments

All arguments to #[server]are now optional: change default prefix to /api and default to generating a PascalCase type name from the function name 

// before
#[server(MyName, "/api")]
pub async fn my_name() /* ... */
// after
#[server]
pub async fn my_name /* ... */

JS Fetch API integration support

We have adapted the Axum integration to be usable when running inside JS-hosted WASM environments (Deno Deploy, Cloudflare Workers, etc.) This can be done by disabling default-features on axum and leptos_axum, using the axum-js-fetch library, and enabling the wasm feature on leptos_axum. 

leptos_axum = { version = "0.5", default-features = false, optional = true }
axum = { version = "0.6", default-features = false, optional = true }
axum-js-fetch = { version = "0.2", optional = true }
# ... 

[features]
default = ["csr"]
csr = ["leptos/csr", "leptos_meta/csr", "leptos_router/csr"]
hydrate = ["leptos/hydrate", "leptos_meta/hydrate", "leptos_router/hydrate"]
ssr = [
  "dep:axum",
  "dep:axum-js-fetch",
  "leptos_axum/wasm",
  # ...
]

There's a full Hackernews example in the repo that runs within Deno.

Feature Grab-Bag

  • Updated Resource APIs. Resources now follow the same API as other signals: .get() and .with() apply to the current value (which may be None). This means the old .with(), which was only called when the resource had resolved, is now .map(). There's also a new .and_then() method which can be called to deeply map over resources that return Result, like server functions. The goal of these methods is to reduce the amount of boilerplate mapping necessary with resources previously. Check out the Resource docs for more info.
  • create_effect now returns an Effect struct. This exists mostly so you can .dispose() it early if you need. (This may require adding some missing semicolons, as create_effect no longer returns ().)
  • create_effect’s first run is now scheduled on the next tick, using queueMicrotask. In other words, create_effect runs after your component returns a view, not immediately as the component runs. This removes most of the cases in which nesting request_animation_frame inside a create_effect had been necessary.
  • Support passing signals directly as attributes, classes, styles, and props on stable.
  • Many APIs that previously took impl Into<Cow<'static, str>> now take impl Into<Oco<'static, str>>. Oco (Owned Clones Once) is a new type designed to minimized the cost of cloning immutable string types, like the ones used in the View. Essentially this makes it cheaper to clone text nodes and attribute nodes within the renderer, without imposing an additional cost when you don't need to. This shouldn't require changes to your application in most cases of normal usage. (See #1480 for additional discussion.)

Minor Breaking Changes

leptos_axum::generate_route_list()

This function is no longer async. This means removing a single .await from main.rs in any Leptos-Axum app, but brings the API of the Axum (and Viz) integrations into line with the Actix one, and unlocks the use of this function in some non-async settings where it was desired.

<For/> prop view renamed children

The name of the function that renders each row of data to a view is now children rather than view. This means that the view can now be included inline, without needing to break out of the markup into another closure and view! macro invocation.

In other words, 

let (data, set_data) = create_signal(vec![0, 1, 2]);
view! {
    <For
        each=data
        key=|n| *n
        // stores the item in each row in a variable named `data`
        let:data
    >
        <p>{data}</p>
    </For>
}

is the same as 

let (data, set_data) = create_signal(vec![0, 1, 2]);
view! {
   <For
       each=data
       key=|n| *n
       children=|data| view! { <p>{data}</p> }
   />
}

which replaces 

let (data, set_data) = create_signal(vec![0, 1, 2]);
view! {
   <For
       each=data
       key=|n| *n
       view=|data| view! { <p>{data}</p> }
   />
}

use_navigate navigate function no longer returns a value

The navigate("path", options) call now uses request_animation_frame internally to delay a tick before navigating, which solves a few odd edge cases having to do with redirecting immediately and the timing of reactive system cleanups. This was a change that arose during 0.3 and 0.4 and is being made now to coincide with other breaking changes and a new version.

If you were relying on the Result<_, _> here and want access to it, let me know and we can bring back a version that has it. Otherwise, this shouldn't really require any changes to your app.

window_event_listener and friends now return a handle for removal

This one was just an API oversight originally, again taking advantage of the semver update. window_event_listener and its untyped version now return a WindowListenerHandle with a .remove() method that can be called explicitly to remove that event, for example in an on_cleanup. 

#[component]
fn TypingPage() -> impl IntoView {
    let handle = window_event_listener(ev::keypress, |ev| {
        /* do something */
    });
    on_cleanup(move || handle.remove());
}

Other Breaking Changes

  • use_context no longer works inside event listeners, inside spawn_local, etc. Use use_context inside the body of a component and move the context data into those other closures.
  • bind: has been renamed let:, which makes more sense for variable binding. (This applies to components like Await and now For, which take arguments in their children.)
  • Transition’s set_pending prop now applies #[prop(into)], which means it can take any signal setter. If you were doing something already like set_pending=something.into() the compiler will now get confused; just remove that .into().
  • create_effect’s first run is now scheduled on the next tick, using queueMicrotask. In other words, create_effect runs after your component returns a view, not immediately as the component runs. (Listing this as both a feature and a breaking change, as it is a behavior change!)
  • The log!, warn!, and error! macros have been moved into a separate logging module to avoid naming conflicts with the log and tracing crates. You can import them as use leptos::logging::*; if desired.
  • Signal traits now take an associated Value type rather than a generic (see #1578)
  • Changes to Resource APIs: the function formerly known as .with() is now .map(), and .read() is now .get() to match other signals.

What's Changed

New Contributors

Full Changelog: v0.4.9...v0.5.0

Check out latest releases or
releases around leptos 0.5.0

Don't miss a new leptos release

NewReleases is sending notifications on new releases.

Get notifications