humid 0.0.1 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 331e268f4bfc9f9b46e4246a9fb1af56245616bedecfb13a9b220040fca74636
-  data.tar.gz: 87631778cddbd5511202a0a3aaaa54fb6827b8aee8bdae29f80297ee6764cd55
+  metadata.gz: a783b726d5542a0abfc94fc1918aad0212c13ac7b6db8b8efd90c5452a222b2e
+  data.tar.gz: b9c3719ace7b00d210c992b48f9c4ee02010e81d19c30aa47e8bf6fdd9e9373b
 SHA512:
-  metadata.gz: 5161834e3f6b0a8d6cb9e991965df392491e204373c0ec54773cf114f8c489be88f435a5d6ba90c226dc6a698ea053ca3ccaf64581cb01399272057ecb600990
-  data.tar.gz: a545a0ffb5c7f1dfdf333bb960566a28fb355fd3dfc60ede7ed88f3210f507ca21e7b389138c07b2a773903110df66b7e60df844a57815c0a87fb624a15ee44c
+  metadata.gz: d29027f962022c6f8d5aeaf09c11730d572a32f8936e025fc04c3490921ac51468f6567e99f29aeb090a344150fa5edce2bbe14e83c18bfe9afc62e89fb34a87
+  data.tar.gz: 9ceb09c4bebef88f71f3b9c229c9317526a1d5cd5100dce4a270aad383334401a14baa7e108417170c5c3cad122523e9539733404d4c9a3cdf6f7bb8c2ec5dbf

data/README.md

@@ -1,11 +1,12 @@
 # Humid
-
-Humid is a lightweight helper that leans on [mini_racer] and [webpacker] to
-generate Server Side Rendered (SSR) pages from your javascript application.
-
 [![Build
 Status](https://circleci.com/gh/thoughtbot/humid.svg?style=shield)](https://circleci.com/gh/thoughtbot/humid)
 
+Humid is a lightweight wrapper around [mini_racer] and [webpacker] used to
+generate Server Side Rendered (SSR) pages from your javascript application.
+While it was built for React, it can work with any JS function that returns a
+HTML string.
+
 ## Caution
 
 This project is in its early phases of development. Its interface,
@@ -33,30 +34,51 @@ Add an initializer to configure
 
 ```ruby
 Humid.configure do |config|
-  # name of your webpacker pack. Defaults to "server_rendering.js"
-  config.server_rendering_source = "server_rendering.js"
-
-  # name of your webpacker pack source map. Defaults to `nil`
-  config.server_rendering_source_map = "server_rendering.js.map"
-
-  # The logger instance. Defaults to `Logger.new(STDOUT)`
+  # Name of your webpacker pack file located in `app/javascript/packs/`. You
+  # should use a separate pack from your `application.js`.
+  #
+  # Defaults to "server_rendering.js"
+  config.server_rendering_pack = "server_rendering.js"
+
+  # Name of your webpacker pack source map.
+  #
+  # Defaults to `false`
+  config.use_source_map = true
+
+  # 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
+  #
+  # Defaults to true.
+  config.raise_render_errors = Rails.env.development? || Rails.env.test?
+
+  # The logger instance.
   # `console.log` and friends (`warn`, `error`) are delegated to
   # the respective logger levels on the ruby side.
+  #
+  # Defaults to `Logger.new(STDOUT)`
   config.logger = Rails.logger
 
-  # context_options. Options passed to mini_racer. Defaults to
-  # config.context_options = {
-  #   timeout: 1000,
-  #   ensure_gc_after_idle: 2000
-  # }
+  # Options passed to mini_racer.
+  #
+  # Defaults to empty `{}`.
+  config.context_options = {
+    timeout: 1000,
+    ensure_gc_after_idle: 2000
+  }
 end
 
-# If using puma in single mode
-# Humid.create_context
+# Common development options
+if Rails.env.development? || Rails.env.test?
+  # Use single_threaded mode for Spring and other forked envs.
+  MiniRacer::Platform.set_flags! :single_threaded
+
+  # If you're using Puma in single mode:
+  Humid.create_context
+end
 ```
 
 If you'd like support for source map support, you will need to
-1. Ensure `config.server_rendering_source_map` has a value
+1. Ensure `config.use_source_map` is set to `true`
 2. Add the following to your `server_rendering.js` pack.
 
 ```javascript
@@ -72,6 +94,8 @@ require("source-map-support").install({
 
 ## The mini_racer environment.
 
+### Functions not available
+
 The following functions are **not** available in the mini_racer environment
 
 - `setTimeout`
@@ -86,11 +110,59 @@ The following functions are **not** available in the mini_racer environment
 `console.log` and friends (`info`, `error`, `warn`) are delegated to the
 respective methods on the configured logger.
 
-### Webpacker
+## Usage
+
+Pass your HTML render function to `setHumidRenderer`
+
+```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}/>
+  )
+})
+```
+
+And finally call `render` from ERB.
+
+```ruby
+<%= Humid.render(initial_state) %>
+```
+
+Instrumentation is included:
+
+```
+Completed 200 OK in 14ms (Views: 0.2ms | Humid SSR: 11.0ms | ActiveRecord: 2.7ms)
+```
+
+### Puma
+
+`mini_racer` is thread safe, but not fork safe. To use with web servers that
+employ forking, use `Humid.create_context` only on forked processes.
+
+```ruby
+# Puma
+on_worker_boot do
+  Humid.create_context
+end
+
+on_worker_shutdown do
+  Humid.dispose
+end
+```
+
+### 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.
 
 ```diff
+ // config/webpack/production.js
+ // config/webpack/development.js
+ // config/webpack/test.js
+
  process.env.NODE_ENV = process.env.NODE_ENV || 'development'
 
  const environment = require('./environment')
@@ -117,39 +189,32 @@ not detect the `mini_racer` environment.
 +module.exports = [ssrConfig, webConfig]
 ```
 
-## Usage
-
-Pass your HTML render function to `setHumidRenderer`
-
-```javascript
-setHumidRenderer((json) => {
-  const initialState = JSON.parse(json)
-  return ReactDOMServer.renderToString(
-    <Application initialPage={initialState}/>
-  )
-})
-```
+## Writing universal code
+[Vue has an amazing resource][vue_ssr] on how to write universal code. Below
+are a few highlights that are important to keep in mind.
 
-And finally call `render` from ERB.
+### State
 
-```ruby
-<%= Humid.render(initial_state) %>
-```
+Humid uses a single context across multiple request. To avoid state pollution, we
+provide a factory function to `setHumidRenderer` that builds a new app instance on
+every call.
 
-### Puma
+This provides better isolation, but as it is still a shared context, polluting
+`global` is still possible. Be careful of modifying `global` in your code.
 
-`mini_racer` is thread safe, but not fork safe. To use with web servers that
-employ forking, use `Humid.create_context` only on forked processes.
+### Polyfills
 
-```ruby
-# Puma
-on_worker_boot do
-  Humid.create_context
-end
+Polyfills will fail when using in the `mini_racer` environment because of missing
+browser APIs. Account for this by moving the `require` to `componentDidMount`
+in your component.
 
-on_worker_shutdown do
-  Humid.dispose
-end
+```
+componentDidMount() {
+  const dialogPolyfill = require('dialog-polyfill').default
+  dialogPolyfill.registerDialog(this.dialog.current)
+  this.dialog.current.open = this.props.open
+  this.dialog.current.showModal()
+}
 ```
 
 ## Contributing
@@ -177,3 +242,4 @@ See [our other projects][community] or
 [hire]: https://thoughtbot.com?utm_source=github
 [mini_racer]: https://github.com/rubyjs/mini_racer
 [webpacker]: https://github.com/rails/webpacker
+[vue_ssr]: https://ssr.vuejs.org/

data/lib/humid.rb

@@ -11,12 +11,24 @@ module Humid
   extend self
   include ActiveSupport::Configurable
 
-  config_accessor :server_rendering_file do
+  class RenderError < StandardError
+  end
+
+  class FileNotFound < StandardError
+  end
+
+  @@context = nil
+
+  config_accessor :server_rendering_pack do
     "server_rendering.js"
   end
 
-  config_accessor :server_rendering_source_map do
-    nil
+  config_accessor :use_source_map do
+    false
+  end
+
+  config_accessor :raise_render_errors do
+    true
   end
 
   config_accessor :logger do
@@ -24,10 +36,7 @@ module Humid
   end
 
   config_accessor :context_options do
-    {
-      timeout: 1000,
-      ensure_gc_after_idle: 2000
-    }
+    {}
   end
 
   def remove_functions
@@ -54,16 +63,30 @@ module Humid
     JS
   end
 
-  def context
-    if @@context && Webpacker.env.development? && Webpacker.compiler.stale?
+  def handle_stale_files
+    if Webpacker.compiler.stale?
       Webpacker.compiler.compile
+    end
+
+    public_path = Webpacker.config.public_path
+    server_rendering_pack = config.server_rendering_pack
+    source_path = public_path.join(Webpacker.manifest.lookup(server_rendering_pack)[1..-1])
+    filename = File.basename(source_path.to_s)
+
+    if @@current_filename != filename
       dispose
       create_context
-    else
-      @@context
     end
   end
 
+  def context
+    if @@context && Webpacker.env.development?
+      handle_stale_files
+    end
+
+    @@context
+  end
+
   def dispose
     if @@context
       @@context.dispose
@@ -84,21 +107,39 @@ module Humid
     ctx.eval(js)
 
     public_path = Webpacker.config.public_path
-    asset_path = public_path.join(Webpacker.manifest.lookup(config.server_rendering_file)[1..-1])
-    filename = File.basename(asset_path.to_s)
-    ctx.eval(File.read(asset_path), filename: filename)
 
-    if config.server_rendering_source_map
-      map_path = public_path.join(Webpacker.manifest.lookup(config.server_rendering_source_map)[1..-1])
+    webpack_source_file = Webpacker.manifest.lookup(config.server_rendering_pack)
+    if webpack_source_file.nil?
+      raise FileNotFound.new("Humid could not find a built pack for #{config.server_rendering_pack}")
+    end
+
+    if config.use_source_map
+      webpack_source_map = Webpacker.manifest.lookup("#{config.server_rendering_pack}.map")
+      map_path = public_path.join(webpack_source_map[1..-1])
       ctx.attach("readSourceMap", proc { File.read(map_path) })
     end
 
+    source_path = public_path.join(webpack_source_file[1..-1])
+    filename = File.basename(source_path.to_s)
+    @@current_filename = filename
+    ctx.eval(File.read(source_path), filename: filename)
+
     @@context = ctx
   end
 
   def render(*args)
     ActiveSupport::Notifications.instrument("render.humid") do
-      @@context.call("__renderer", *args)
+      context.call("__renderer", *args)
+    rescue MiniRacer::RuntimeError => e
+      message = ([e.message] + e.backtrace.filter {|x| x.starts_with? "JavaScript"}).join("\n")
+      render_error = Humid::RenderError.new(message)
+
+      if config.raise_render_errors
+        raise render_error
+      else
+        config.logger.error(render_error.inspect)
+        ""
+      end
     end
   end
 end

data/lib/humid/version.rb

@@ -1,3 +1,3 @@
 module Humid
-  VERSION = "0.0.1".freeze
+  VERSION = "0.0.5".freeze
 end

data/spec/log_subscriber_spec.rb

@@ -45,7 +45,7 @@ RSpec.describe Humid::LogSubscriber do
   end
 
   it "is attached" do
-    allow(Humid.config).to receive("server_rendering_file") { "simple.js" }
+    allow(Humid.config).to receive("server_rendering_pack") { "simple.js" }
     Humid.create_context
     expect(Humid::LogSubscriber.runtime).to eql(0)
     Humid.render

data/spec/render_spec.rb

@@ -14,14 +14,24 @@ RSpec.describe "Humid" do
     end
 
     it "creates a context with initial js" do
-      allow(Humid.config).to receive("server_rendering_file") { "simple.js" }
+      allow(Humid.config).to receive("server_rendering_pack") { "simple.js" }
       Humid.create_context
 
       expect(Humid.context).to be_kind_of(MiniRacer::Context)
     end
 
+    context "When the file can not be found" do
+      it "raises" do
+        allow(Humid.config).to receive("server_rendering_pack") { "does_not_exist.js" }
+
+        expect {
+          Humid.create_context
+        }.to raise_error(Humid::FileNotFound, "Humid could not find a built pack for does_not_exist.js")
+      end
+    end
+
     it "does not have timeouts, immediates, and intervals" do
-      allow(Humid.config).to receive("server_rendering_file") { "simple.js" }
+      allow(Humid.config).to receive("server_rendering_pack") { "simple.js" }
 
       Humid.create_context
 
@@ -43,7 +53,7 @@ RSpec.describe "Humid" do
     end
 
     it "proxies to Rails logger" do
-      allow(Humid.config).to receive("server_rendering_file") { "simple.js" }
+      allow(Humid.config).to receive("server_rendering_pack") { "simple.js" }
       Humid.create_context
       expect(Humid.logger).to receive(:info).with("hello")
 
@@ -53,7 +63,7 @@ RSpec.describe "Humid" do
 
   describe "context" do
     it "returns the created context" do
-      allow(Humid.config).to receive("server_rendering_file") { "simple.js" }
+      allow(Humid.config).to receive("server_rendering_pack") { "simple.js" }
 
       Humid.create_context
 
@@ -64,7 +74,7 @@ RSpec.describe "Humid" do
       it "does not recompile the JS" do
         allow(Webpacker).to receive_message_chain("env.development?") { false }
         allow(Webpacker).to receive_message_chain("compiler.stale?") { true }
-        allow(Humid.config).to receive("server_rendering_file") { "simple.js" }
+        allow(Humid.config).to receive("server_rendering_pack") { "simple.js" }
 
         Humid.create_context
         prev_context = Humid.context
@@ -79,37 +89,61 @@ RSpec.describe "Humid" do
       end
     end
 
-    context "when the js is stale and env is development" do
-      it "compiles the JS" do
+    context "when the env is development" do
+      it "compiles the JS when stale" do
         allow(Webpacker).to receive_message_chain("env.development?") { true }
         allow(Webpacker).to receive_message_chain("compiler.stale?") { true }
         allow(Webpacker).to receive_message_chain("compiler.compile")
-        allow(Humid.config).to receive("server_rendering_file") { "simple.js" }
+        allow(Humid.config).to receive("server_rendering_pack") { "simple.js" }
 
         Humid.create_context
         prev_context = Humid.context
         expect(prev_context).to be_kind_of(MiniRacer::Context)
 
         allow(Webpacker).to receive_message_chain("compiler.stale?") { true }
+        # This simulates a changing file
+        allow(Humid.config).to receive("server_rendering_pack") { "simple_changed.js" }
+
+        next_context = Humid.context
+
+        expect(prev_context).to_not eql(next_context)
+        expect(next_context).to be_kind_of(MiniRacer::Context)
+      end
+
+      it "creates a new context when webpack-devserver already handled JS staleness" do
+        allow(Webpacker).to receive_message_chain("env.development?") { true }
+        allow(Webpacker).to receive_message_chain("compiler.stale?") { true }
+        allow(Webpacker).to receive_message_chain("compiler.compile")
+        allow(Humid.config).to receive("server_rendering_pack") { "simple.js" }
+
+        Humid.create_context
+        prev_context = Humid.context
+        expect(Humid.render).to eql("hello")
+        expect(prev_context).to be_kind_of(MiniRacer::Context)
+
+        allow(Webpacker).to receive_message_chain("compiler.stale?") { false }
+        # This simulates a changing file
+        allow(Humid.config).to receive("server_rendering_pack") { "simple_changed.js" }
 
         next_context = Humid.context
 
         expect(prev_context).to_not eql(next_context)
         expect(next_context).to be_kind_of(MiniRacer::Context)
+        expect(Humid.render).to eql("hello changed")
       end
     end
   end
 
   describe "render" do
     it "returns a js output" do
-      allow(Humid.config).to receive("server_rendering_file") { "simple.js" }
+      allow(Humid.config).to receive("server_rendering_pack") { "simple.js" }
       Humid.create_context
 
       expect(Humid.render).to eql("hello")
     end
 
     it "applys args to the func" do
-      allow(Humid.config).to receive("server_rendering_file") { "args.js" }
+      allow(Humid.config).to receive("server_rendering_pack") { "args.js" }
       Humid.create_context
 
       args = ["a", 1, 2, [], {}]
@@ -118,22 +152,37 @@ RSpec.describe "Humid" do
     end
 
     it "can use source maps to see errors" do
-      allow(Humid.config).to receive("server_rendering_file") { "reporting.js" }
-      allow(Humid.config).to receive("server_rendering_source_map") {
-        "reporting.js.map"
-      }
+      allow(Humid.config).to receive("server_rendering_pack") { "reporting.js" }
+      allow(Humid.config).to receive("use_source_map") { true }
 
       Humid.create_context
 
       expect {
         Humid.render
       }.to raise_error { |error|
-        expect(error).to be_a(MiniRacer::RuntimeError)
-        expect(error.message).to eql("Error: ^^ Look! These stack traces map to the actual source code :)")
-        expect(error.backtrace[0]).to eql("JavaScript at throwSomeError (/webpack:/app/javascript/packs/components/error-causing-component.js:2:1)")
-        expect(error.backtrace[1]).to eql("JavaScript at ErrorCausingComponent (/webpack:/app/javascript/packs/components/error-causing-component.js:8:1)")
-        expect(error.backtrace[2]).to eql("JavaScript at /webpack:/app/javascript/packs/reporting.js:18:1")
+        expect(error).to be_a(Humid::RenderError)
+        message = <<~MSG
+          Error: ^^ Look! These stack traces map to the actual source code :)
+          JavaScript at throwSomeError (/webpack:/app/javascript/packs/components/error-causing-component.js:2:1)
+          JavaScript at ErrorCausingComponent (/webpack:/app/javascript/packs/components/error-causing-component.js:8:1)
+          JavaScript at /webpack:/app/javascript/packs/reporting.js:18:1
+        MSG
+
+        expect(error.message).to eql message.strip
       }
     end
+
+    it "siliences render errors to the log" do
+      allow(Humid.config).to receive("server_rendering_pack") { "reporting.js" }
+      allow(Humid.config).to receive("raise_render_errors") { false }
+      allow(Humid.config).to receive("use_source_map") { true }
+
+      Humid.create_context
+
+      expect(Humid.logger).to receive(:error)
+      output = Humid.render
+
+      expect(output).to eql("")
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: humid
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.5
 platform: ruby
 authors:
 - Johny Ho
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-07-10 00:00:00.000000000 Z
+date: 2021-07-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: webpacker
@@ -44,14 +44,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '6.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '6.0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -100,14 +100,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '6.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '6.0'
 description: Javascript SSR rendering for Rails
 email: jho406@gmail.com
 executables: []