Rails Integration

Matestack apps and pages are connected to Rails through controllers and controller actions. HTTP requests are handled through classic Rails routing and responded through Rails controller actions. Just let the controller action render Matestack page instead of a Rails view at the end. Optionally you can use apps on controller or action level in order to wrap the page with a layout written in pure Ruby.

JavaScript Setup

Matestack's JavaScript needs to be integrated into your Rails application in order to use the reactive, JavaScript driven features. You can use Webpacker (recommended) or Rails assets pipeline to do this.


Add 'matestack-ui-core' to your package.json by running:

$ yarn add https://github.com/matestack/matestack-ui-core#v1.3.2
$ yarn install

This adds the npm package that provides the JavaScript corresponding to the matestack-ui-core ruby gem. Make sure that the npm package version matches the gem version. To find out what gem version you are using, you may use bundle info matestack-ui-core.

Next, import 'matestack-ui-core' in your app/javascript/packs/application.js

import MatestackUiCore from 'matestack-ui-core'

and compile the JavaScript code with webpack:

$ bin/webpack --watch

When you update the matestack-ui-core gem, make sure to update the npm package as well.

Asset Pipeline

If you are using the asset pipeline, you don't need to install the separate npm package. All required JavaScript libraries are provided by the matestack-ui-core gem.

Require 'matestack-ui-core' in your app/assets/javascript/application.js

//= require matestack-ui-core

We recommend to (remove/deactivate)(https://stackoverflow.com/a/38649595) turbolinks, as there is no reason to use it alongside matestack-ui-core and there might appear some strange side effects. If you encounter strange page-transition/form-submit/action-submit behavior and have turbolinks activated, try to deactivate it first.

Rails layouts still required

Even if a Matestack app defines the layout of the UI, you need a classic Rails layout in order to get things running:

For Example, your app/views/layouts/shop_layout.html.erb should look like this:

<!DOCTYPE html>
<title>My Shop</title>
<%= csrf_meta_tags %>
<%= csp_meta_tag %>
<%= stylesheet_link_tag 'application', media: 'all' %>
<!-- if you are using webpacker: -->
<%= javascript_pack_tag 'application' %>
<!-- if you are using the asset pipeline: -->
<%= javascript_include_tag 'application' %>
<div id="matestack-ui">
<!-- Matestack apps and pages will be yielded here! -->
<%= yield %>

You need to add the ID "matestack-ui" to some part of your application layout (or any layout you use). Don't apply the "matestack-ui" id to the body tag.

Rails controllers referencing Matestack apps and pages


class ShopController < ApplicationController
# if not already included
include Matestack::Ui::Core::ApplicationHelper
# if custom components are used
include Components::Registry
layout "shop_layout" # if it shouldn't be the default application layout
matestack_app Shop::App # apps are optional!
def home
render Shop::Pages::Home
def product_detail
render Shop::Pages::Product::Detail

and something like this in place:


class Shop::App < Matestack::Ui::App
def response
heading text: 'Matestack Shop'


class Shop::Pages::Home < Matestack::Ui::Page
def response
heading size: 2, text: 'A few products you may like'
Product.limit(5).each do |product|
paragraph text: product.name
small text: product.price


class Shop::Pages::Products::Detail < Matestack::Ui::Page
def prepare
@product = Product.find(params[:id])
def response
heading size: 2, text: @product.name
paragraph text: product.description

Rails routing as you're used to

Just use Rails routing as you're used to. No additional setup required!

Rails.application.routes.draw do
get '/home', to: 'shop#home'
get '/product_details/:id', to: 'shop#product_details'