Hyperstack

Hyperstack is a Ruby-based DSL and modern web toolkit for building spectacular, interactive web applications fast!

• One language throughout the client and server. All Ruby code is compiled by Opal into JavaScript automatically.
• Webpacker and Yarn tooling for a modern, fast hot-reloader build environment with Ruby source maps.
• A well documented and stable Ruby DSL for wrapping React and ReactRouter as well as any JavaScript library or component. No need to learn JavaScript!
• Isomorphic Models with bi-directional data so you can access your models as if they were on the client.

This means you can write simple front-end code like this:

class GoodBooksToRead < HyperComponent
  render(UL) do
    Book.good_books.each do |book|
      LI { "Read #{book.name}" }
        .on(:click) { display book } if book.available?
    end
  end
end

In the code above, if the good_books scope changed (even on the server), the UI would update automatically. That's the magic of React and Isomorphic Models with bi-directional data at work!

Please see the website site for full documentation:

• hyperstack.org

You can be up and running in less than 5 minutes. Just follow the simple setup guide for to add Hyperstack to a new or existing Rails application:

• Setup and Installation docs

We now are issuing 1.0 release candidates weekly until all issues are either closed or moved to post 1.0 release status. Your opinion matters, plus take some time to up/down vote or comment on issues of interest.

Open issues includes enhancements, documentation, and discussion issues as well as few bugs.

The documentation WIP (work in progress) numbers are approx, as more sections may be added.

• Older Status Reports

Hyperstack is supported by a friendly, helpful community, both for users, and contributors. We welcome new people, please reach out and say hello.

• Join our Slack group
• After you have joined there is a shortcut at https://hyperstack.org/slack

Please ask technical questions on StackOverflow as the answers help people in the future. We use the hyperstack tag, but also add ruby-on-rails, ruby and react-js tags to get this project exposed to a broader community.

• Please ask questions here: https://hyperstack.org/question
• All the hyperstack tagged questions are here: https://hyperstack.org/questions

The browser-spec suites (hyper-model, hyper-operation, hyper-component, …) need a database and a Chrome instance. The easiest way to run them on a dev machine is against two throwaway Docker containers, driven by run-local-docker-specs.sh:

# whole suite for a gem (default: hyper-model)
./run-local-docker-specs.sh hyper-model

# a single batch or one example
./run-local-docker-specs.sh hyper-model spec/batch4
./run-local-docker-specs.sh hyper-model spec/batch4/scope_spec.rb:175

The script starts hs-postgres (Postgres 16, trust auth) and hs-chrome (selenium/standalone-chrome), both on the host network, then prepares the DB, precompiles the Opal bundle, and runs RSpec against the remote Chrome. It sets the flags that make this reliable: OPAL_PREFORK_DISABLE=1 (Opal 1.8's prefork build scheduler hangs in some sandboxes) and PRECOMPILED_ASSETS=1 (otherwise the on-the-fly debug pipeline recompiles per request and the first spec appears to hang for minutes).

Timezone: the server and the browser must share a timezone, or the column_type datetime specs fail by the offset (server time vs. browser-rendered time). The script pins both to TZ=Etc/UTC; override TZ only if you set it on the host and the Chrome container alike.

Every driver hyper-spec registers carries an HTTP read timeout, so a browser that stops answering fails the example in minutes instead of hanging until the OS gives up on the socket — which cost one CI job 42 minutes before a human cancelled it (#74). The default is 90s when PRECOMPILED_ASSETS is set and 300s when it is not, because the debug asset pipeline charges a cold Sprockets compile of the whole Opal bundle to the first visit. Override with HYPER_SPEC_READ_TIMEOUT / HYPER_SPEC_OPEN_TIMEOUT (seconds).

Under a debugger the browser is legitimately idle for as long as you sit on a breakpoint, so name a large value:

HYPER_SPEC_READ_TIMEOUT=86400 ./run-local-docker-specs.sh hyper-model spec/batch4/scope_spec.rb:175

Setting one to 0 means "impose nothing" and leaves whatever the installed selenium-webdriver defaults to — which is not a fixed answer, so it is not a way to ask for an unbounded wait: up to 4.46 there is no timeout at all, while 4.47 defaults to open 60 / read 120.

Tear the containers down with docker rm -f hs-postgres hs-chrome.

If you would like to help, please read the CONTRIBUTING file for suggestions.

Released under the MIT License. See the LICENSE file for further details.