WebviewUtil

WebviewUtil provides Ruby bindings for webview/webview, a small cross-platform library for building native desktop windows backed by a webview.

The gem exposes a compact WebviewUtil::Window wrapper around the native webview lifecycle: create a window, navigate it to a page, bind Ruby callbacks for JavaScript, evaluate JavaScript, and run the native event loop.

WebviewUtil continues Marco Concetto Rudilosso's earlier webview_ruby gem under the rbutils namespace with the WebviewUtil::Window API.

The API is still evolving and should be considered unstable until version 1.0.

Installation

Add this line to your application's Gemfile:

gem "webview_util"

And then execute:

bundle install

If you want the gem installed directly:

gem install webview_util

Usage

require "webview_util"

window = WebviewUtil::Window.new(
  title: "Example",
  width: 480,
  height: 360,
  debug: false
)

window.navigate("https://example.com")
window.run

Window#run blocks until the native window closes and destroys the webview before returning.

JavaScript Integration

Bind a Ruby block so page JavaScript can call it by name:

window = WebviewUtil::Window.new(title: "Bridge Example")

window.bind("exampleFunc") do |first, second|
  puts "called from JavaScript with #{first.inspect} and #{second.inspect}"
end

window.navigate("data:text/html,<script>exampleFunc('hello', 'ruby')</script>")
window.run

Run JavaScript from Ruby:

window.eval("console.log('Called from Ruby')")

Inject JavaScript before page scripts run:

window.init("console.log('running before page scripts')")

Close the window programmatically:

window.terminate

API

  • WebviewUtil::Window.new(title:, width:, height:, debug:) creates a native webview window.
  • Window#navigate(url) loads a URL or supported webview URI.
  • Window#run enters the native event loop and destroys the webview on exit.
  • Window#terminate requests event-loop termination.
  • Window#eval(js) evaluates JavaScript asynchronously in the current page.
  • Window#init(js) injects JavaScript before page scripts execute.
  • Window#bind(name, &block) exposes a Ruby block as a JavaScript function and passes parsed JSON arguments to the block.

Native Dependencies

Webview uses platform webview components: Cocoa/WebKit on macOS, WebKitGTK on Linux, and WebView2 on Windows. Native headers and libraries must be available when the extension is compiled.

Development

After checking out the repo, install dependencies:

bundle install

Run the default checks:

bundle exec rake

The default Rake task compiles the native extension, runs the test task, and runs RuboCop.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/rbutils/webview_util.

License

The gem is available as open source under the terms of the MIT License.