From 5effcdb5ff87d14c15501fa3b91837e19b043ddc Mon Sep 17 00:00:00 2001 From: Valerio Ageno Date: Sun, 3 Mar 2024 18:20:50 +0100 Subject: [PATCH] doc: update doc --- README.md | 61 +++++++++++++++++++++++++++++++++++++++++++---- examples/actix.rs | 2 +- src/lib.rs | 54 ++++++++++++++++++++++++++++++++++++++--- 3 files changed, 108 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 2cf9173..f45b393 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ The project aims to enable server side rendering on rust servers in the simplest It use an embedded version of the v8 javascript engine (rusty_v8) to parse and evaluate a built bundle file and return a string with the rendered html. -Currently it works with Webpack bundler v5.65.0; check it out here a full project who use this crate. +Currently it works with Webpack bundler v5.65.0. ## Getting started @@ -32,9 +32,9 @@ fn main() { let source = read_to_string("./path/to/build.js").unwrap(); - let mut js = Ssr::new(&source, "entryPoint"); + let mut js = Ssr::new(&source, "entryPoint").unwrap(); - let html = js.render_to_string(None); + let html = js.render_to_string(None).unwrap(); assert_eq!(html, "...".to_string()); } @@ -60,14 +60,65 @@ fn main() { let source = read_to_string("./path/to/build.js").unwrap(); - let mut js = Ssr::new(&source, "entryPoint"); + let mut js = Ssr::new(&source, "entryPoint").unwrap(); - let html = js.render_to_string(Some(&props)); + let html = js.render_to_string(Some(&props)).unwrap(); assert_eq!(html, "...".to_string()); } ``` +## Example with actix-web + +> Examples with different web frameworks are available in the examples folder. + +Even though the V8 engine allows accessing the same `isolate` from different threads that is forbidden by this crate for two reasons: + +1. rusty_v8 library have not implemented yet the V8 Locker API. Accessing Ssr struct from a different thread will make the V8 engine to panic. +2. Rendering HTML does not need shared state across threads. + +For this reason parallel computation is a better choice. Following actix-web setup: + +```rust +use actix_web::{get, http::StatusCode, App, HttpResponse, HttpServer}; +use std::cell::RefCell; +use std::fs::read_to_string; + +use ssr_rs::Ssr; + +thread_local! { + static SSR: RefCell> = RefCell::new( + Ssr::from( + read_to_string("./client/dist/ssr/index.js").unwrap(), + "SSR" + ).unwrap() + ) +} + +#[actix_web::main] +async fn main() -> std::io::Result<()> { + + Ssr::create_platform(); + + HttpServer::new(|| { + App::new() + .service(index) + }) + .bind("127.0.0.1:8080")? + .run() + .await +} + +#[get("/")] +async fn index() -> HttpResponse { + let result = SSR.with(|ssr| ssr.borrow_mut().render_to_string(None).unwrap()); + + HttpResponse::build(StatusCode::OK) + .content_type("text/html; charset=utf-8") + .body(result) +} +``` + ## Contributing Any helps or suggestions will be appreciated. diff --git a/examples/actix.rs b/examples/actix.rs index 32aa0ef..e83a31b 100644 --- a/examples/actix.rs +++ b/examples/actix.rs @@ -39,7 +39,7 @@ async fn index() -> HttpResponse { let start = Instant::now(); let result = SSR.with(|ssr| ssr.borrow_mut().render_to_string(None).unwrap()); println!("Elapsed: {:?}", start.elapsed()); - // This is a benchmark example. Please refer to examples/shared_ssr.rs for a better solution. + HttpResponse::build(StatusCode::OK) .content_type("text/html; charset=utf-8") .body(result) diff --git a/src/lib.rs b/src/lib.rs index c23a69a..6d637f5 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -5,9 +5,9 @@ //! //! It use an embedded version of the v8 javascript engine (rusty_v8) to parse and evaluate a built bundle file and return a string with the rendered html. //! -//! Currently it works with Webpack bundler v4.44.2; check it out here a full project who use this crate. +//! Currently it works with Webpack bundler v4.44.2. //! -//! # Gettin started +//! # Getting started //! ```toml //! [dependencies] //! ssr_rs = "0.3.0" @@ -63,7 +63,55 @@ //! assert_eq!(html, "...".to_string()); //! } //!``` - +//! +//! # Example with actix-web +//! +//! > Examples with different web frameworks are available in the examples folder. +//! +//! Even though the V8 engine allows accessing the same `isolate` from different threads that is forbidden by this crate for two reasons: +//! 1. rusty_v8 library have not implemented yet the V8 Locker API. Accessing Ssr struct from a different thread will make the V8 engine to panic. +//! 2. Rendering HTML does not need shared state across threads. +//! +//! For this reason parallel computation is a better choice. Following actix-web setup: +//! +//! ```rust +//! use actix_web::{get, http::StatusCode, App, HttpResponse, HttpServer}; +//! use std::cell::RefCell; +//! use std::fs::read_to_string; +//! +// !use ssr_rs::Ssr; +//! +//! thread_local! { +//! static SSR: RefCell> = RefCell::new( +//! Ssr::from( +//! read_to_string("./client/dist/ssr/index.js").unwrap(), +//! "SSR" +//! ).unwrap() +//! ) +//!} +//! +//! #[actix_web::main] +//!async fn main() -> std::io::Result<()> { +//! Ssr::create_platform(); +//! +//! HttpServer::new(|| { +//! App::new() +//! .service(index) +//! }) +//! .bind("127.0.0.1:8080")? +//! .run() +//! .await +//! } +//! +//! #[get("/")] +//! async fn index() -> HttpResponse { +//! let result = SSR.with(|ssr| ssr.borrow_mut().render_to_string(None).unwrap()); +//! +//! HttpResponse::build(StatusCode::OK) +//! .content_type("text/html; charset=utf-8") +//! .body(result) +//! } +//!``` mod ssr; pub use ssr::Ssr;