doc: update doc

Valerioageno · Mar 3, 2024 · 65237ee · 65237ee
1 parent d1ad00b
commit 65237ee
Show file tree

Hide file tree

Showing 3 changed files with 108 additions and 9 deletions.
diff --git 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 (<a href="https://github.com/denoland/rusty_v8" target="_blank">rusty_v8</a>) 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 <a href="https://github.com/Valerioageno/reactix" target="_blank">here</a> 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, "<!doctype html><html>...</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, "<!doctype html><html>...</html>".to_string());
 }
 ```
 
+## Example with actix-web
+
+> Examples with different web frameworks are available in the <a href="https://github.com/Valerioageno/ssr-rs/blob/main/examples" target="_blank">examples</a> 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<Ssr<'static, 'static>> = 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
@@ -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
@@ -5,9 +5,9 @@
 //!
 //! It use an embedded version of the v8 javascript engine (<a href="https://github.com/denoland/rusty_v8" target="_blank">rusty_v8</a>) 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  <a href="https://github.com/Valerioageno/reactix" target="_blank">here</a> 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, "<!doctype html><html>...</html>".to_string());
 //! }
 //!```
-
+//!
+//! # Example with actix-web
+//!
+//! > Examples with different web frameworks are available in the <a href="https://github.com/Valerioageno/ssr-rs/blob/main/examples" target="_blank">examples</a> 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<Ssr<'static, 'static>> = 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;