humid 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1b62f6d6c3c7ffac0ba1c609965742a6a09dafebe0ebb9fc05cbae3c9200299e
-  data.tar.gz: 56557384d6768ada9b8fa9e9403720b5e75f03a579e39483892afcb631cb04a4
+  metadata.gz: 4c7f343b4b1518296d59917fb37ce2f8a60ee6b1a57b71f3fd378ce2ad55a4d4
+  data.tar.gz: e11384d2812e0de2cb7e676fa237957d44fbe63cf788e73adf997c9a14b2015e
 SHA512:
-  metadata.gz: 4465a746beab25d302782cc71b8a70cd7fe827dc6ce3058e6720056c121bb86357733a9d31a7c266ceee6a53f938b174fec1eef111dbc634aa6699ffccb30ac9
-  data.tar.gz: c5d8a1c61b84b49a14a78c7d198af09871bbdf9cebc8c9bbd1d4b32c2cdd95ac7de2bad06214f80ec12a8507158b8bb95a592eff313e51e454dcd768e5a2cdc1
+  metadata.gz: d5ca07bdd2c64b97f51c45dd14de734ab37e608704414a494461cce0645a10d4fcfb3c1e414152066c16b9be3f98c2f55fdcb6cd1cb6e3e7464e3ebb64e7ed8f
+  data.tar.gz: 52923317087b7439e80c347022acc55e102435367f3f0d54d52079f9e40129271aae60cba245bfe4d5d4352441988abd30882429f04d817e2528c029564a8cc3

data/README.md

@@ -43,25 +43,25 @@ Add an initializer to configure the default options for `Humid.render`. These
 are overridable on `Humid.render`.
 
 ```ruby
-# app/initializers/humid.rb
+# config/initializers/humid.rb
 
 Humid.configure do |config|
   # Path to your build file located in `app/assets/builds/`. You should use a
   # separate build apart from your `application.js`.
   #
   # Required
-  config.application_path = Rails.root.join('app', 'assets', 'builds', 'server_rendering.js')
+  config.application_path = Rails.root.join("app/assets/builds/server_rendering.js")
 
   # Path to your source map file
   #
   # Optional
-  config.source_map_path = Rails.root.join('app', 'assets', 'builds', 'server_rendering.js.map')
+  config.source_map_path = Rails.root.join("app/assets/builds/server_rendering.js.map")
 
   # Raise errors if JS rendering failed. If false, the error will be
-  # logged out to Rails log and Humid.render will return an empty string
+  # logged and Humid.render will return an empty string.
   #
   # Defaults to true.
-  config.raise_render_errors = Rails.env.development? || Rails.env.test?
+  config.raise_render_errors = Rails.env.local?
 
   # The logger instance.
   # `console.log` and friends (`warn`, `error`) are delegated to
@@ -71,105 +71,105 @@ Humid.configure do |config|
   config.logger = Rails.env.local? ? Rails.logger : nil
 end
 
-# if Rails.env.local?
-#   # Use single_threaded mode for Spring and other forked envs.
-#   MiniRacer::Platform.set_flags! :single_threaded
-#   ctx = MiniRacer::Context.new(timeout: 100, ensure_gc_after_idle: 2000)
-#   MINI_RACER_CONTEXT = Humid.prepare(ctx)
-# end
+if Rails.env.local?
+  # Use single_threaded mode for Spring and other forked envs.
+  MiniRacer::Platform.set_flags! :single_threaded
+  MINI_RACER_SSR = { context: MiniRacer::Context.new(timeout: 1000, ensure_gc_after_idle: 2000) }
+
+  # Reload the context when the SSR bundle changes
+  ssr_checker = ActiveSupport::FileUpdateChecker.new([Humid.config.application_path.to_s]) do
+    MINI_RACER_SSR[:context].dispose
+    MINI_RACER_SSR[:context] = MiniRacer::Context.new(timeout: 1000, ensure_gc_after_idle: 2000)
+  end
+
+  Rails.application.reloaders << ssr_checker
+  Rails.application.reloader.to_run do
+    ssr_checker.execute_if_updated
+  end
+end
 ```
 
 ## Usage
 
+### Set a renderer
 
-### Create the MiniRacer Context.
+In your entry file, e.g, `server_rendering.js` (specified in
+`config.application_path`), pass your HTML render function to
+`setHumidRenderer`. There is no need to require the function, its included in
+the environment.
 
-On local development or test environments, uncomment the below.
+```javascript
+// Set a factory function that will create a new instance of our app
+// for each request.
+setHumidRenderer((json) => {
+  const initialState = JSON.parse(json)
 
-```ruby
-if Rails.env.local?
-  # Use single_threaded mode for Spring and other forked envs.
-  MiniRacer::Platform.set_flags! :single_threaded
-  ctx = MiniRacer::Context.new(timeout: 100, ensure_gc_after_idle: 2000)
-  MINI_RACER_CONTEXT = Humid.prepare(ctx)
-end
+  return ReactDOMServer.renderToString(
+    <Application initialPage={initialState}/>
+  )
+})
 ```
 
+If you'd like support for source map support, you will need to add the following
+to the same file and set `config.source_map_path` like the configuration above.
+
+```javascript
+require("source-map-support").install({
+  retrieveSourceMap: filename => {
+    return {
+      url: filename,
+      map: readSourceMap(filename)
+    };
+  }
+});
+```
+
+### Your webserver
+
 On production, keep in mind that `mini_racer` is **thread safe, but not fork
-safe**. When using with web servers that employ forking, create a
-`MINI_RACER_CONTEXT` with options of your choosing **on worker boot. There
-should be no context created on the master process.**
+safe**. When using with web servers that employ forking, create the context
+on worker boot. **There should be no context created on the master process.**
 
 For example with puma:
 
 ```ruby
 # config/puma.rb
 on_worker_boot do
-  ctx = MiniRacer::Context.new(timeout: 100, ensure_gc_after_idle: 2000)
-  MINI_RACER_CONTEXT = Humid.prepare(ctx)
+  ctx = MiniRacer::Context.new(timeout: 1000, ensure_gc_after_idle: 2000)
+  MINI_RACER_SSR = { context: Humid.prepare(ctx) }
 end
 
 on_worker_shutdown do
-  MINI_RACER_CONTEXT.dispose
+  MINI_RACER_SSR[:context].dispose
 end
 ```
 
-### Prepare the context with `Humid.prepare`
-
-`Humid.prepare` will prepare the context's environment by [removing
-functions](#functions-not-available), delegate `console.log` and friends to
-your logger, load the SSR js bundle, and add the render function.
+`Humid.prepare` will prepare the context's
+[environment](#the-mini_racer-environment).
 
 You can also override config options per-context:
 
 ```ruby
-MINI_RACER_CONTEXT = Humid.prepare(
+ctx = Humid.prepare(
   MiniRacer::Context.new(timeout: 1000),
   application_path: Rails.root.join("other_bundle.js"),
   logger: nil
 )
+MINI_RACER_SSR = { context: ctx }
 ```
 
-If you'd like support for source map support, you will need to
-
-1. Add the following to your entry file, e.g, `server_rendering.js`.
-2. set `config.source_map_path`.
-
-```javascript
-require("source-map-support").install({
-  retrieveSourceMap: filename => {
-    return {
-      url: filename,
-      map: readSourceMap(filename)
-    };
-  }
-});
-```
+> [!NOTE]
+> If you pass a context that was already prepared, `prepare` will noop and return the context back to you.
 
 See the [sample server_rendering.tsx](./sample/server_rendering.tsx) to see how
 it is integrated.
 
-### Add a renderer and call `Humid.render`
-
-In your entry file, e.g, `server_rendering.js`, pass your HTML render function
-to `setHumidRenderer`. There is no need to require the function.
-
-```javascript
-// Set a factory function that will create a new instance of our app
-// for each request.
-setHumidRenderer((json) => {
-  const initialState = JSON.parse(json)
-
-  return ReactDOMServer.renderToString(
-    <Application initialPage={initialState}/>
-  )
-})
-```
+### Call `Humid.render`
 
 And finally call `render` from ERB.
 
 ```ruby
-<%= Humid.render(MINI_RACER_CONTEXT, json).html_safe %>
+<%= Humid.render(MINI_RACER_SSR[:context], json).html_safe %>
 ```
 
 Instrumentation is included:
@@ -178,7 +178,7 @@ Instrumentation is included:
 Completed 200 OK in 14ms (Views: 0.2ms | Humid SSR: 11.0ms | ActiveRecord: 2.7ms)
 ```
 
-## The prepared `mini_racer` environment.
+## The `mini_racer` environment
 
 ### Functions not available
 
@@ -268,23 +268,19 @@ to get around these issues.
 
 ## Testing
 
-When running in test environments that also forks, you may need to set up new mini_racer
-contexts for each parallel worker. For example:
+The snippet When running in test environments that fork (e.g., parallel tests), each
+worker needs its own context since MiniRacer is not fork-safe. Using
+`MINI_RACER_SSR` as a hash makes this straightforward:
 
 ```ruby
 ActiveSupport.on_load(:action_dispatch_integration_test) do
-  include ActionView::Helpers::TranslationHelper
-  include Devise::Test::IntegrationHelpers
-
   parallelize_setup do
-    MINI_RACER_CONTEXT.dispose if defined?(MINI_RACER_CONTEXT)
-    ctx = MiniRacer::Context.new(timeout: 1000, ensure_gc_after_idle: 2000)
-    Object.send(:remove_const, :MINI_RACER_CONTEXT) if defined?(MINI_RACER_CONTEXT)
-    Object.const_set(:MINI_RACER_CONTEXT, Humid.prepare(ctx))
+    MINI_RACER_SSR[:context].dispose
+    MINI_RACER_SSR[:context] = MiniRacer::Context.new(timeout: 1000, ensure_gc_after_idle: 2000)
   end
 
   parallelize_teardown do
-    MINI_RACER_CONTEXT.dispose if defined?(MINI_RACER_CONTEXT)
+    MINI_RACER_SSR[:context].dispose
   end
 end
 ```
@@ -295,7 +291,7 @@ The `MiniRacer::Context` gives you access to V8 heap statistics for monitoring
 memory usage over time.
 
 ```ruby
-MINI_RACER_CONTEXT.heap_stats
+MINI_RACER_SSR[:context].heap_stats
 # {:total_heap_size=>3100672,
 #  :total_heap_size_executable=>4194304,
 #  :total_physical_size=>1280640,
@@ -314,7 +310,7 @@ render_histogram = meter.create_histogram("humid.render.duration", unit: "ms", d
 heap_gauge = meter.create_gauge("humid.heap.used_bytes", unit: "By", description: "V8 heap used bytes")
 
 ActiveSupport::Notifications.subscribe("render.humid") do |event|
-  stats = MINI_RACER_CONTEXT.heap_stats
+  stats = MINI_RACER_SSR[:context].heap_stats
   attributes = { "worker.pid" => Process.pid.to_s }
 
   render_histogram.record(event.duration, attributes: attributes)
@@ -350,7 +346,6 @@ We are [available for hire][hire].
 [community]: https://thoughtbot.com/community?utm_source=github
 [hire]: https://thoughtbot.com/hire-us?utm_source=github
 
-
 <!-- END /templates/footer.md -->
 
 [mini_racer]: https://github.com/rubyjs/mini_racer

data/lib/humid/version.rb

@@ -1,3 +1,3 @@
 module Humid
-  VERSION = "0.5.0".freeze
+  VERSION = "0.7.0".freeze
 end

data/lib/humid.rb

@@ -13,6 +13,9 @@ module Humid
   class FileNotFound < StandardError
   end
 
+  class NotPrepared < StandardError
+  end
+
   mattr_accessor :config
 
   self.config = ActiveSupport::OrderedOptions.new.merge({
@@ -27,6 +30,8 @@ module Humid
   end
 
   def prepare(ctx, options = {})
+    return ctx if ctx.respond_to?(:humid_prepared?) && ctx.humid_prepared?
+
     effective_config = config.merge(options)
     logger = effective_config.logger
     log_formatter = effective_config.log_formatter
@@ -39,9 +44,7 @@ module Humid
       ctx.attach("console.warn", proc { |*args| logger.warn(fmt.call(:warn, *args)) })
     end
 
-    js = ""
-    js << remove_functions
-    js << renderer
+    js = remove_functions + renderer
     ctx.eval(js)
 
     source_path = effective_config.application_path
@@ -54,10 +57,17 @@ module Humid
     filename = File.basename(source_path.to_s)
     ctx.eval(File.read(source_path), filename: filename)
 
+    def ctx.humid_prepared?
+      true
+    end
+
     ctx
   end
 
   def render(ctx, *args)
+    is_prepared = ctx.respond_to?(:humid_prepared?) && ctx.humid_prepared?
+    raise Humid::NotPrepared, "Context was not prepared with Humid.prepare" unless is_prepared
+
     ActiveSupport::Notifications.instrument("render.humid") do
       ctx.call("__renderer", *args)
     rescue MiniRacer::RuntimeError => e

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: humid
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Johny Ho
@@ -37,7 +37,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '8.0'
-description: Javascript SSR rendering for Rails
+description: Javascript Server Side Rendering (SSR) for Rails
 email: jho406@gmail.com
 executables: []
 extensions: []
@@ -68,5 +68,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
-summary: Javascript SSR rendering for Rails
+summary: Javascript Server Side Rendering (SSR) for Rails
 test_files: []