humid 0.7.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4c7f343b4b1518296d59917fb37ce2f8a60ee6b1a57b71f3fd378ce2ad55a4d4
-  data.tar.gz: e11384d2812e0de2cb7e676fa237957d44fbe63cf788e73adf997c9a14b2015e
+  metadata.gz: 4dace2fdf5d12412e01d86b520b5d77fd3fd04dd207b2815d93d0473283fa6a8
+  data.tar.gz: d8c40b486faa9f905c04c3d31c4eabd0cd304d0ad98d1666b1d76ad2aae32e0c
 SHA512:
-  metadata.gz: d5ca07bdd2c64b97f51c45dd14de734ab37e608704414a494461cce0645a10d4fcfb3c1e414152066c16b9be3f98c2f55fdcb6cd1cb6e3e7464e3ebb64e7ed8f
-  data.tar.gz: 52923317087b7439e80c347022acc55e102435367f3f0d54d52079f9e40129271aae60cba245bfe4d5d4352441988abd30882429f04d817e2528c029564a8cc3
+  metadata.gz: afc89db87f4b324b01b08a1f907ae74fd88a420b8c275095b9e7e44b8cf21e711b31dc18dbc0b021d85d8debca4e50986be1a16a2b43eec2a27ad1de6cc668c2
+  data.tar.gz: 1564ce03048d337b38891607afbbc360e47e5898601cb78a984ce4a003aafe1b3ff95dc6dc0a3faa70a6b6703446b11d7ddb86185250ad68e36e65401bf3dcb8

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
 
@@ -69,10 +78,18 @@ Humid.configure do |config|
   #
   # Defaults to `nil`
   config.logger = Rails.env.local? ? Rails.logger : nil
+
+  # Path to a JavaScript file to eval into the MiniRacer context
+  # before the application bundle. Use this to provide globals that
+  # bare V8 doesn't have (TextEncoder, URL, MessageChannel, etc.).
+  #
+  # Optional. Defaults to nil (no prepend).
+  # config.prepend = Rails.root.join("path/to/shim.js")
 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
   MINI_RACER_SSR = { context: MiniRacer::Context.new(timeout: 1000, ensure_gc_after_idle: 2000) }
 
@@ -161,9 +178,6 @@ MINI_RACER_SSR = { context: ctx }
 > [!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.
-
 ### Call `Humid.render`
 
 And finally call `render` from ERB.
@@ -221,17 +235,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
@@ -260,31 +276,45 @@ moving the `require` to `useEffect` in your component.
   }, [])
 ```
 
-## Polyfills
+## MiniRacer Shim
 
-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)
-to get around these issues.
+MiniRacer runs bare V8 — no browser APIs, no Node APIs. React SSR and
+libraries like `whatwg-url` expect globals that don't exist. Humid ships
+a pre-built shim in [`shim/dist/shim.js`](./shim/) that provides:
 
-## Testing
+- **TextEncoder / TextDecoder** — real implementation from `text-encoding`
+  (not stubs — `whatwg-url` needs them to actually encode strings)
+- **URL / URLSearchParams** — from `whatwg-url`
+- **MessageChannel** — stub (React's scheduler references it)
+- **navigator** — stub with `language: 'en-us'`
+- **source-map-support** — rewrites JS stack traces using source maps,
+  so Humid errors show original filenames and line numbers
+  (`app/views/posts/show.html.tsx:42`) instead of bundled positions
+  (`server_rendering.js:12345`)
 
-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:
+Use it with the `prepend` config option:
 
 ```ruby
-ActiveSupport.on_load(:action_dispatch_integration_test) do
-  parallelize_setup do
-    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_SSR[:context].dispose
-  end
+Humid.configure do |config|
+  config.prepend = Rails.root.join("path/to/shim.js")
 end
 ```
 
+The shim is eval'd into the MiniRacer context before your SSR bundle,
+so all globals are available when your code initializes.
+
+To rebuild the shim (e.g., after updating dependencies):
+
+```sh
+cd shim
+npm install
+npm run build
+# outputs shim/dist/shim.js
+```
+
+See the [shim README](./shim/README.md) for details on the two-stage
+build process.
+
 ## Telemetry
 
 The `MiniRacer::Context` gives you access to V8 heap statistics for monitoring
@@ -321,13 +351,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.
 
@@ -350,4 +381,4 @@ We are [available for hire][hire].
 
 [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.7.0".freeze
+  VERSION = "1.1.0".freeze
 end

data/lib/humid.rb

@@ -44,6 +44,11 @@ module Humid
       ctx.attach("console.warn", proc { |*args| logger.warn(fmt.call(:warn, *args)) })
     end
 
+    prepend_path = effective_config.prepend
+    if prepend_path
+      ctx.eval(File.read(prepend_path))
+    end
+
     js = remove_functions + renderer
     ctx.eval(js)
 

metadata

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