humid 0.6.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 961eafadcfe1132cdd132c096a28aba48155c740b224c3cbc32b4fd9731c10a6
-  data.tar.gz: 8a3635e896a4915c508a096c3b9f60e7d51265b39c6c448150fb89a627a3ab06
+  metadata.gz: f8a07ab8d934750bbdb01dc4596426d02edd7733d7bf87093b8ca36d5abbbb33
+  data.tar.gz: d3c9f28d92d637d8d4eb20e78676a0eacf09d7c922c0583448f3aacc1befe4fa
 SHA512:
-  metadata.gz: 7f9f13d45e1b4023cccdc88300c151024dbb08a5bcc73c24b1a81e089f1ad1d2a4ec1faea12feb81e13949e2c423a8e8a392d73bf45b547ecdcd20a6462b74b6
-  data.tar.gz: fba2e9ea74fdeab8a90f5503a0b34cf977ddb0006dcaf234ceff8b1d06548079461e0e5d17466cace1c68937b7fa290a5823ef0fe01352886b545b0fe87c9cc2
+  metadata.gz: 311cdf7125016802906bc28b7545c80c22e01709ebe679ead307f68783bab051a9e30bc634b777ce41802ad9d6564288305c593aee5da05a40e853b8a7ce31f2
+  data.tar.gz: 43777369d6c7b2525957d11117be0b1df56e960dbea0ca7be822ebb1b0d7c1e9af5f406fea47619d7f50829e203f610fb1074b1435b6ccce310453f1db04bf05

data/README.md

@@ -1,4 +1,9 @@
-# Humid
+<div align="center">
+  <img src="./images/svg/humid-icon.svg" alt="Humid" width="128" />
+  <h1>Humid</h1>
+  <p>A few helpers for Javascript server-side rendering on Rails with <a
+  href="https://github.com/rubyjs/mini_racer">mini_racer</a></p>
+</div>
 
 ![Build Status](https://github.com/thoughtbot/humid/actions/workflows/build.yml/badge.svg?branch=main)
 
@@ -12,16 +17,20 @@ returns an HTML string.
 
 ## Design
 
-Humid is designed for the common case where all data is gathered before
-rendering. Your application fetches everything needed, passes it as props, and
-Humid returns the rendered HTML in a single synchronous call. It does not
-support streaming or async data fetching during render.
+Humid is designed with 2 goals in mind:
 
-## Caution
+1. Its for the common case where all data is gathered before rendering. Your
+application fetches everything needed, passes it as props, and Humid returns
+the rendered HTML in a single synchronous call. It does not support streaming
+or async data fetching during render.
 
-This project is in its early phases of development. Its interface,
-behavior, and name are likely to change drastically before a major version
-release.
+2. Its a stepping stone for when you want to scale on the edge using
+[Cloudflare V8 isolates](https://developers.cloudflare.com/workers/reference/how-workers-works/)
+.`mini_racer` is a bare V8 environment, if your JS bundle works with
+`mini_racer`, it'll work on Cloudflare V8 isolates.
+
+> [!NOTE]
+> See the [sample](./sample/) for a complete working example.
 
 ## Installation
 
@@ -43,25 +52,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
@@ -72,10 +81,21 @@ Humid.configure do |config|
 end
 
 if Rails.env.local?
-  # Use single_threaded mode for Spring and other forked envs.
+  # Use single_threaded mode for dev and test environments.
+  # This will also work for mini_test parallel tests
   MiniRacer::Platform.set_flags! :single_threaded
-  ctx = MiniRacer::Context.new(timeout: 100, ensure_gc_after_idle: 2000)
-  MINI_RACER_CONTEXT = Humid.prepare(ctx)
+  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
 ```
 
@@ -117,22 +137,20 @@ require("source-map-support").install({
 ### 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
 ```
 
@@ -142,22 +160,23 @@ end
 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 }
 ```
 
-See the [sample server_rendering.tsx](./sample/server_rendering.tsx) to see how
-it is integrated.
+> [!NOTE]
+> If you pass a context that was already prepared, `prepare` will noop and return the context back to you.
 
 ### 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:
@@ -209,17 +228,19 @@ The default formatter returns `message` unchanged.
 
 ## Server-side libraries that detect node.js envs.
 
-You may need webpacker to create aliases for server friendly libraries that can
-not detect the `mini_racer` environment. For example, in `webpack.config.js`.
-
-```diff
-...
-  resolve: {
-    alias: {
-      'html-dom-parser': path.resolve(__dirname, '../../node_modules/html-dom-parser/lib/html-to-dom-server')
-    }
+Some libraries check for Node.js or browser globals to decide which code path
+to use. In `mini_racer`, neither environment is detected. You may need to
+configure your bundler to alias server-friendly versions. For example, in
+esbuild:
+
+```js
+// build_ssr.mjs
+await esbuild.build({
+  // ...
+  alias: {
+    'html-dom-parser': 'html-dom-parser/lib/html-to-dom-server'
   }
-...
+})
 ```
 
 ## Writing universal code
@@ -251,39 +272,16 @@ moving the `require` to `useEffect` in your component.
 ## Polyfills
 
 React SSR may import node.js dependencies that you need to polyfill for. See
-a sample esbuild [build script](./sample/bulid_ssr.js) and a [shim.js](./sample/shim.js)
+a sample esbuild [build script](./sample/build.mjs) and a [shim.js](./sample/shim.js)
 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:
-
-```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))
-  end
-
-  parallelize_teardown do
-    MINI_RACER_CONTEXT.dispose if defined?(MINI_RACER_CONTEXT)
-  end
-end
-```
-
 ## Telemetry
 
 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,
@@ -302,7 +300,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)
@@ -313,13 +311,14 @@ end
 A steadily climbing `used_heap_size` across requests indicates a memory leak in
 your JavaScript bundle.
 
+
 ## Contributing
 
 Please see [CONTRIBUTING.md](/CONTRIBUTING.md).
 
 ## License
 
-Humid is Copyright © 2021-2024 Johny Ho.
+Humid is Copyright © 2021-2026 Johny Ho.
 It is free software, and may be redistributed under the terms specified in the
 [LICENSE](/LICENSE.md) file.
 
@@ -338,9 +337,8 @@ 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
 [vue_ssr]: https://ssr.vuejs.org/
-[sample]: ./webpack.config.js
+[sample]: ./sample/

data/lib/humid/version.rb

@@ -1,3 +1,3 @@
 module Humid
-  VERSION = "0.6.0".freeze
+  VERSION = "1.0.0".freeze
 end

data/lib/humid.rb

@@ -30,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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: humid
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Johny Ho