emirror-de/lewp-rs

Generate your HTML5 website technically optimized and always valid without losing the algorithmic comfort and flexibility.

---

❓ What is lewp?

Lewp is a server side website rendering framework that enables you to use the full algorithmic power of Rust for the creation of technically valid HTML5 websites.

Its approach differs from most of the popular frameworks currently available by not using templates, JSX or other custom syntax that mixes languages. This prevents your code from getting messy ending up in unmaintainable spaghetti.

By its unique identification approach of pages, components and resources, Lewp speeds up the development of your next website and makes it easier to maintain even when you did not touch your source code for a longer period of time.

Thanks to lewp's file hierarchy implementation, structuring your resources has never been easier. They even get compiled into the final binary, so you do not need to worry about missing resources on deployment any longer. Your components CSS and JavaScript is automatically isolated and integrated into your webpage, so no more tearing one's hair about the optimization of your <script> and <link> tags. You will find more simplifications and optimizations for your website creation while exploring lewp.

Generate your HTML5 website technically optimized and always valid without losing the algorithmic comfort and flexibility.

⚠ This crate is currently evolving. API breaking changes can happen anytime until v1.0.0. Compiler warnings are currently used as development reminders and will be removed as soon as possible.

This is the adjusted Rust implementation of the PHP version of lewp.

If you have questions, want to contribute or have any other type of request, your invited to create an issue.

🥅 Project goals

1. Simplfying the creation of web pages without mixing programming languages or putting logic into your HTML (like it is done in templates)

2. Creating modularized websites with truly isolated and reusable components/modules, eg. automatically namespaced CSS and JavaScript

3. Providing a default implementation of a folder hierarchy for easy resource management and possibility to share between different projects

4. Getting the best of both worlds, server side rendering and client side application logic

5. Minimization of page loading times (for example FCP and TTI)

6. No HTML boilerplate code

7. Applying SEO best practices already in development setup as much as possible

❗ lewp is not a webserver. It is a library that supports you in structuring your algorithms bringing them perfectly in line with your view, without letting your code get messy! It perfectly integrates with frameworks like rocket, actix-web or axum.

📦 Features

• No more template hell in your code base
• No more whitespace bugs in your website
• Technically optimized, always valid, minified, HTML5 code
• Component based development, truly isolated
• Archive definition with pre-defined paths for easy resource management
• Uses rust_embed under the hood so all your assets are always available
• Build the DOM completely in Rust

Quick start example

For more examples with comments have a look at the repositories examples.

use lewp::{
    component::{Component, ComponentId, ComponentModel},
    html::{
        api::{h1, text},
        Node,
    },
    page::{Page, PageId, PageModel},
    view::PageView,
};
struct HelloWorld {
    data: String,
}
impl HelloWorld {
    pub fn new() -> Self {
        Self {
            data: String::from("Hello World!"),
        }
    }
}
impl ComponentModel for HelloWorld {
    type Message = ();
    fn id(&self) -> ComponentId {
        "hello-world".into()
    }
    fn main(&mut self) {}
    fn view(&self) -> Option<Node> {
        Some(h1(vec![text(&self.data)]))
    }
}
struct HelloWorldPage;
impl PageModel for HelloWorldPage {
    fn id(&self) -> PageId {
        "hello-world-page".into()
    }
    fn main(&self, view: &mut PageView) {
        let mut comp = Component::from(HelloWorld::new());
        view.push(&mut comp);
    }
}
fn main() {
    simple_logger::init().unwrap();
    let page = Page::from(HelloWorldPage {});
    let executed_page = page.main();
    println!("{}", executed_page.render());
}

🚌 Planned feature list

• Option to split CSS up into "render critical" (will be inlined on rendering) and "non render critical" parts that will be inserted as <link>
• html5-picture support to be able to scale the images to predefined sizes for specific breakpoint optimization
• JavaScript minification
• Provide an API for localization (l10n)
• Async main method for PageModel and ComponentModel
• More to come, throw your ideas to the issues ... :-)

🤠 Contributing

Unless explicitly stated, any contribution intentionally submitted for inclusion in this project, as defined in the Apache-2.0 license, shall be dual licensed as below, without any additional terms or conditions.

Please have a look at CONTRIBUTING.md for guidelines and conventions.

⚖ License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT license (LICENSE-MIT)

at your option.

lewp-rs's Issues

Duplicated memory usage when using MemoryStorage with embedded storage

Motivation

The current implementation compiles all resources that are defined in a Storage into the binary. As a result, the resources are already present in memory.

Having a look at MemoryStorage<Css> the CSS files are processed and therefore loaded again into memory (but adjusted), resulting in a duplication of memory usage where the initial files are not used any longer.

Desired solution

There is currently no ideal solution for this. Implementing RustEmbed trait without embedding the files into the binary on release would solve this, with the drawback that you need to copy the storage folder on release.

Improve code quality by applying clippy hints

Motivation

At this early stage of the library, clippy hints have not been applied yet.

Desired solution

Remove all warnings that occur when running cargo clippy --all-features.

lewp-css README not up to date

The README in folder lewp-css is not up to date. The crate name on crates.io is lewp-css, not css-next.

Create an issue template for missing documentation

Motivation

Currently there are two issue templates available for bug reports and enhancement requests.

Desired solution

It would be nice to have an issue template for documentation, so that contributors have an easy way to point out missing spots or to suggest an enhancement.

Consider renaming `ComponentDetails` to `ResourceDetails`

Motivation

The ComponentDetails struct is a key struct for working with lewp and identifies any resource as well component. The naming could be misleading because most of the member have names with "resource" in it.

Desired solution

It should be considered to rename the ComponentDetails struct to ResourceDetails. This could be more descriptive to end users.

Consider to extend `ArchiveCache` by the usage of `cached` crate

Motivation

Currently the ArchiveCache struct implements a cache to hold the resources in memory until a restart of the app. It may be more efficient to use the cached crate for this.

Desired solution

A solution that makes use of the cached crate should be considered.

Move fh::Component and everything else necessary to resources module

Motivation

At the time of writing, the fh::Component trait is at the wrong place. It easily is being misunderstood what this trait is used for.

Desired solution

Move the trait to resources module and rename it to Resource. This is more precise about what this trait is useful for. The fh::ResourceType should be moved to resources as well.

In addition to that, the fh::ComponentType enum might be not necessary anymore.

Evaluate upgrading html5ever and subcrates

New versions of html5ever and its subcrates are released. Evaluate what needs to be done to upgrade these dependencies.

Consider the usage of yoshuawuyts/html

Motivation

At the moment, lewp-html powers the core HTML generation. To decrease required maintenance work it should be considered to change to https://github.com/yoshuawuyts/html

Add a global file hierarchy level

Motivation
Currently only two file hierarchy level exist, modules and pages. If resources need to be shared throughout a whole website, it would be required to either symlink or copy them from another page level. This creates massive overhead in disk space and a significant amount of work for the developer.

Desired solution
Introducing a global file hierarchy level that is automatically shared throughout all pages.

Code examples/public API

pub enum Level {
    Core,
    Module,
    Page,
    Global, // maybe another name would be more appropriate?
}

Remove all warnings during compilation

Expected behavior

On compilation, no warnings should be emitted by the compiler.

Actual behavior

The compiler emits warnings.

To Reproduce

cargo build --all-features

JavaScript per component isolation

Motivation

At the time of writing, JavaScript is not isolated for the components. The files are only combined, minified and added as type = "module" to the page.

Desired solution

The added JavaScript should be isolated per component, meaning that the module is executed in a separate scope like a self invoking function with a reference to the DOM node of the component. In addition to that, an API for standardizing the initialization process needs to be defined.

Refine contribution guidelines

To make it easier for newcomers to contribute, a contributing checklist or procedure to follow should be added.
This should include:

• All required cargo checks, incl. clippy, test, rustfmt
• The develop branch should be removed
• The main branch should be the default development branch

The structure should be renewed as well, to get a better overview when reading the first time.

Add documentation about the concept of `lewp`

Motivation

Currently there is only API documentation available. To present the full power of lewp more information is required about the internal details. It should also be used by contributors as a place to start from when preparing their contribution.

Desired solution

Create a detailed, separate documentation that tells about the concept of lewp and some of its internals that are not documented in the API documentation.

Replace LewpError struct by using anyhow crate

Motivation

The LewpError struct is currently extensively used.

Desired solution

This struct should be replaced by anyhow which enables a more generic usage.