Building a web app using Rails 8 and Vue 3 with Vite

2026-06-08T00:00:00+00:00

Photo by Jonathan Perlin, 2022.

When it comes to frontend development, Rails 8 offers many great options.

There’s of course Hotwire: the new little-to-no-JavaScript frontend framework that leverages server-side rendering, WebSockets, and Stimulus to deliver rich, SPA-feeling web apps.

For serving static assets to web browsers, including JavaScript, Rails has the Asset Pipeline, which helps with fingerprinting, caching, and exposing assets.

By default, the Rails Asset Pipeline is configured to use Import Maps (with the importmap-rails gem), which allows easy delivery and loading of JavaScript as modules, without the need for bundling and/or transpiling. That means that your development environment and build pipeline do not need Node.js, Yarn, or any other package manager or bundler. Rails takes care of everything using standard HTML features supported by all major browsers.

Hotwire works beautifully with this setup.

Now, if you need bundling and transpiling, the Rails Asset Pipeline can be configured to do so too. Instead of importmap-rails, you’d be installing the jsbundling-rails gem. This way you can use bundlers like Bun, esbuild, Rollup.js and Webpack to process your JavaScript source code and emit bundles ready for the browser to run. CSS preprocessors like PostCSS and Dart Sass are also supported with the cssbundling-rails gem. In particular, this style is necessary when you need to integrate frontend frameworks like React or Svelte.

This used to be the case for Vue as well. However, the story is a bit different nowadays. In order to set up a Vue frontend for a Rails 8 app, it’s necessary to use Vite. The main reason is that with the advent of Vue 3, a lot of the ecosystem around Vue changed. The necessary plugins that implement support for Vue on bundlers like esbuild and Webpack have fallen behind. Vite, which is maintained by the developers of Vue, is the new recommended way to build and deliver modern Vue apps. Thankfully, there exists the vite_rails gem, which does the heavy lifting for us when it comes to integrating Vue with Rails.

In this article, we will see a recipe for how to set up a Rails 8 app with Vue via Vite.

The development environment

In order to build a Rails app, you of course need Ruby and the Rails gem. For the frontend part, you need Node.js and the package manager of your choice. We’ll just use npm here, but Yarn and pnpm work just as well.

For development, I like to use Development Containers with Visual Studio Code. With this, you can get a Docker container that’s optimized for development thathat allows you to hit the ground running.

In any case, if you want to follow along, make sure you have all these installed in your environment:

$ ruby -v
ruby 4.0.4 (2026-05-12 revision b89eb1bcbf) +PRISM [x86_64-linux]

$ rails -v
Rails 8.1.3

$ node -v
v24.15.0

$ npm -v
11.14.1

The code is also on GitHub, including the configuration of the devcontainer.

Creating a new Rails 8 project

To create the Rails project, we use a conventional CLI command:

rails new . -n rails8-vue3-vite -d postgresql --skip-hotwire --skip-javascript

Here, the interesting options are --skip-hotwire and --skip-javascript. We will be using Vue, so we tell Rails not to include support for Hotwire. Also, we will use Vite, which has its own conventions for handling JavaScript, so we use the --skip-javascript so that Rails doesn’t create its default JavaScript files.

We should also create a page that we can navigate to:

bundle exec rails g controller home index

After that, you should be able to run the app and navigate to the page we just created:

$ bin/rails server
=> Booting Puma
=> Rails 8.1.3 application starting in development 
=> Run `bin/rails server --help` for more startup options
Puma starting in single mode...
* Puma version: 8.0.1 ("Into the Arena")
* Ruby version: ruby 4.0.4 (2026-05-12 revision b89eb1bcbf) +PRISM [x86_64-linux]
*  Min threads: 3
*  Max threads: 3
*  Environment: development
*          PID: 45415
* Listening on http://127.0.0.1:3000
* Listening on http://[::1]:3000
Use Ctrl-C to stop

Setting up Vite

As I mentioned before, the vite_rails gem comes in really handy for integrating Vite with Rails. We install it with:

bundle add vite_rails

# ...

bundle exec vite install

With that, a few notable things should have happened in the project:

1: The gem should’ve been added to your Gemfile:

# ...
gem "vite_rails"

2: A package.json file should’ve been created with the necessary dependencies for Vite:

{
  "private": true,
  "type": "module",
  "devDependencies": {
    "vite": "^8.0.13",
    "vite-plugin-ruby": "^5.2.2"
  }
}

3: A pair of Vite config files should’ve been created, which configure Vite’s bundling process and its development and test servers:

// vite.config.ts
import { defineConfig } from 'vite'
import RubyPlugin from 'vite-plugin-ruby'

export default defineConfig({
  plugins: [
    RubyPlugin(),
  ],
})

// config/vite.json
{
  "all": {
    "sourceCodeDir": "app/frontend",
    "watchAdditionalPaths": []
  },
  "development": {
    "autoBuild": true,
    "skipProxy": true,
    "publicOutputDir": "vite-dev",
    "port": 3036
  },
  "test": {
    "autoBuild": true,
    "publicOutputDir": "vite-test",
    "port": 3037
  }
}

4: An app/frontend/entrypoints/application.js should’ve been created with some console.log calls that are useful for validating that things are working. This is called an “entry point”.

5: The following lines should’ve been added to your app/views/layouts/application.html.erb file:

<%= vite_client_tag %>
<%= vite_javascript_tag 'application' %>

vite_client_tag enables Hot Module Replacement, and vite_javascript_tag 'application' includes the bundle that Vite produces as a result of bundling application.js.

At this point, you can run the Vite development server and the Rails server in separate terminals:

$ bin/vite dev

  VITE v8.0.13  ready in 146 ms

  ➜  Local:   http://localhost:3036/vite-dev/
  ➜  press h + enter to show help

$ bin/rails server
# ...

You can now navigate to http://127.0.0.1:3000/home/index and see this:

If you’re using devcontainers, you may have to specify 127.0.0.1 as the host in the Vite dev server configuration in order to allow your browser to connect to it:

{
  "all": {
    "sourceCodeDir": "app/frontend",
    "watchAdditionalPaths": []
  },
  "development": {
    "autoBuild": true,
    "skipProxy": true,
    "publicOutputDir": "vite-dev",
+    "host": "127.0.0.1",
    "port": 3036
  },
  "test": {
    "autoBuild": true,
    "publicOutputDir": "vite-test",
+    "host": "127.0.0.1",
    "port": 3037
  }
}

Installing Vue

Finally, we can install Vue and the plugin that allows Vite to process *.vue files:

npm install vue

# ...

npm install @vitejs/plugin-vue

Then wire it up in the vite.config.ts:

import { defineConfig } from 'vite'
import RubyPlugin from 'vite-plugin-ruby'
+import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [
    RubyPlugin(),
+    vue()
  ],
})

With this, we’re all set. We can start developing Vue components. Here’s a quick example.

We can create a app/frontend/components/App.vue file with these contents:

<script>
export default {
  data() {
    return {
      message: 'Hello Rails, Vue and Vite!',
      count: 0
    }
  }
}
</script>

<template>
  <div>
    <h1>{{ message }}</h1>
  </div>

  <button @click="count++">Count is: {{ count }}</button>
</template>

<style scoped>
h1 {
  background: linear-gradient(to right, red, green, yellow);
  -webkit-background-clip: text;
  -webkit-text-fill-color: transparent;
  background-clip: text;
}

button {
  font-weight: bold;
}
</style>

And we can initialize the Vue app and mount the component we just created by adding this to app/frontend/entrypoints/application.js:

// ...

import { createApp } from 'vue'
import App from '../components/App.vue'

const app = createApp(App)
app.mount('#app')

And of course, we also have to add the mounting point in app/views/home/index.html.erb:

<!-- ... -->
<div id="app"></div>

The app now looks like this:

And that’s it! With Rails, Vue, Vite and a little elbow grease we can put together a beautiful monolithic app, powered by great frameworks that offer a stellar developer experience.

Running Ruby in Podman (When rbenv install Fails on Apple Silicon)

2026-01-12T00:00:00+00:00

I recently worked on a legacy Ruby backend app which hadn’t been changed for years. A Ruby development environment used to be provided by DevCamps for this site, but over the years we stopped using Ruby other than this small backend, so we also stopped using camps.

The frontend development now uses its own local dev server, so I decided to do the same for the backend by running the Unicorn server locally. I’m on a MacBook M2, so I should just be able to install rbenv using Homebrew. Easy, right?

Unfortunately not. I had a great deal of trouble getting any version of Ruby to run natively on my MacBook M2, so I eventually resorted to using Podman. You can skip to the end for my solution.

First try: native rbenv

The rbenv installation went just fine:

brew install rbenv ruby-build

And after adding eval "$(rbenv init -)" to my ~/.zshrc file, I tried to install the old version of Ruby:

rbenv install 2.4.10

However, this returned a BUILD FAILED message. Strangely, it also failed with a new version of Ruby (3.3.10). I tried debugging for a while before giving up — I figured this project isn’t worth multiple hours of getting a local Ruby installation to work (despite my obstinate attempts to do so).

Second try: mise

Several people on forums & blogs recommended using mise, a language-agnostic version manager. After installing it with Homebrew, I ran:

mise use --global ruby@2.4.10

This failed too! There was a good explanation, though: older Ruby versions don’t run on ARM processors. Of course, that makes sense. So I just needed to install a newer version from after Apple silicon was supported:

mise use --global ruby@3.3.10

However, this failed as well, just like rbenv:

mise ERROR Failed to install core:ruby@3.3.10:
   0: ~/Library/Caches/mise/ruby/ruby-build/bin/ruby-build exited with non-zero status: exit code 1

I’m sure there is a way to get Ruby running through a version manager on Apple silicon; I found several tutorials claiming you can just run these commands as normal and it’ll work. However, after spending longer than I’d like to admit, I was completely unable to do so despite trying many fixes found online.

This may be a unique problem on my machine, or I may be missing something. But the fact was, I’d waited through about a dozen failed Ruby installs (which take a long time!) and I just needed the app to work now. So I moved to a third option: run Ruby in a container.

Third try: Podman

Podman is a fully open-source containerization system which can run Dockerfiles and docker-compose.yml files. The app is a lightweight Sinatra backend with Unicorn as a server, and I just needed to add CloudFlare Turnstile to reduce bot traffic.

The app uses two main files: unicorn.rb (which holds the configuration for the Unicorn server) and config.ru (which defines and runs the Sinatra app). The command to start the app is pretty simple: bundle exec unicorn -c unicorn.rb config.ru. I also set up two files for the container: Containerfile and container-compose.yml.

Note: Podman does find files named Dockerfile and docker-compose.yml, but here I’m using Podman’s convention of Containerfile and container-compose.yml, which takes precedence if both are present in the folder.

To run this, I just needed to set up the environment in my Containerfile.

`Containerfile`

FROM ruby:2.4.10

WORKDIR /usr/src/app

COPY . .

RUN mkdir -p /var/log && \
 gem i bundler && \
 bundle install

EXPOSE 8080

CMD ["bundle", "exec", "unicorn", "-c", "unicorn.rb", "config.ru"]

It’s a pretty simple setup:

set the working directory
copy files from the source directory into the container
create the log directory defined in unicorn.rb
install bundler
install gems from Gemfile.lock
expose the port defined in unicorn.rb
define the server start command using a CMD instruction

`container-compose.yml`

services:
  backend:
    build:
        context: .
        dockerfile: Containerfile
    volumes:
        - .:/usr/src/app
    ports:
        - "8080:8080"

The volumes section means that changes on the host machine will be propogated to the container (and vice versa). This means you don’t need to rebuild the container when you change the app, instead you can use a change-watching Gem like rerun.

Note: You can run this without a compose file, the compose file just stores the volume & port information so you can run it more easily.
podman run -d --name mybackend -v .:/usr/src/app -p 8080:8080 <image_id>

Minimal `unicorn.rb` configuration file

listen "0.0.0.0:8080"
working_directory "/usr/src/app"

This is simple:

Use 0.0.0.0 to connect to the container’s network interface
Define our listening port
Set the working directory to the same value as in our Containerfile

Note: When we forward port 8080 to our Podman container, that traffic arrives on the container’s network interface, not on its internal loopback (localhost). If your app only listens on localhost, it’s essentially saying “I only accept connections from myself,” so the forwarded traffic gets rejected. By binding to 0.0.0.0, your app listens on all interfaces, which includes the one Podman uses to route external traffic into the container.

Simple `config.ru`

require 'sinatra'
get '/' do
  "Hello from Sinatra in Podman!\n"
end
run Sinatra::Application

This is also very simple:

After importing sinatra, define a GET route for the / location (so this will be accessed from localhost:8080/ on the host machine)

$ podman build .
$ podman run -p 8080:8080 <image-id>

This returned a successful response on my host machine:

$ curl localhost:8080
Hello from Sinatra in Podman!

When the app failed to run, it kept trying to restart until I moved a .env file into place and it worked. That shows that the volume is working correctly.

I’m not a Ruby expert, but with this setup I was able to convert the JavaScript code for Turnstile to Ruby and get it working!

Quick and Dirty Admin Pages with Rails scaffold_controller

2025-12-29T00:00:00+00:00

You’re building a Rails application, and you’ve reached that point where you or your team needs a simple way to manage data. You need an admin interface. You’ve heard of heavy-weight solutions like ActiveAdmin or Rails Admin, but they feel like overkill for adding a few new categories or moderating user posts. You don’t want to spend an afternoon configuring a gem. You need something now.

Luckily Rails has a built-in lightning-fast way to generate a fully functional admin CRUD interface for any existing model. Meet the often-overlooked scaffold_controller generator. It’s the secret weapon for building “quick and dirty” internal tools.

What Is scaffold_controller and Why Use It?

When you run rails generate scaffold Post, it creates everything: the model, migration, controller, and views. The scaffold_controller generator does only half of that, creating only the controller and views (as long as the model already exists).

This is perfect for creating a separate admin namespace because:

It’s Non-Destructive: Your existing, user-facing PostsController remains untouched
It’s Fast: One command gives you a complete set of CRUD actions and ERB views
It’s Simple: No new gems, dependencies, or complex configurations to learn

Let’s Build an Admin Interface for a Product Model

Imagine you have a Product model in your application. You have a ProductsController for your main site, but now you need an admin area to create, edit, and delete products.

Step 1: Create the Admin Namespace and Route

First, we’ll set up a routing namespace to keep our admin logic separate. This will put our URLs in this format: /admin/products

Open your config/routes.rb file and add:

# config/routes.rb
Rails.application.routes.draw do
  # ... existing routes ...

  namespace :admin do
    resources :products
  end
end

Running rails routes will now show new routes like admin_products_path, edit_admin_product_path, etc.

Step 2: Generate the Scaffold Controller

Now for the magic. In your terminal, run rails generate scaffold_controller Admin::Product

Important notes:

The namespace (Admin::) must match the one you used in your routes
The model name (Product) must be singular, just like with a regular scaffold

This one command generates several files:

Controller: app/controllers/admin/products_controller.rb
Views: A full set of ERB templates in app/views/admin/products/ (index.html.erb, show.html.erb, new.html.erb, edit.html.erb, _form.html.erb)

Step 3: Update the Generated Controller

The generated controller is a great start but it needs one crucial tweak. It doesn’t know about our namespace, so it will look for the Product model in the wrong place. The key change is ensuring every reference to the model is to Product, not Admin::Product.

Open products_controller.rb and change the class definition and any model references. Here’s a simplified example of what it should look like:

# app/controllers/admin/products_controller.rb
module Admin
  class ProductsController < ApplicationController
    before_action :set_product, only: [:show, :edit, :update, :destroy]

    # GET /admin/products
    def index
      @products = Product.all
    end

    # ... other actions ...

    private
      def set_product
        @product = Product.find(params[:id])
      end

      def product_params
        params.require(:product).permit(:name, :description, :price, :stock)
      end
  end
end

Step 4: Add a Link and Access Control

Your admin interface is now live at http://localhost:3000/admin/products. Before you deploy you must add some form of access control. This can be as simple as a basic HTTP authentication check in your Admin::ProductsController.

# app/controllers/admin/products_controller.rb
module Admin
  class ProductsController < ApplicationController
    http_basic_authenticate_with name: ENV['ADMIN_USER'], password: ENV['ADMIN_PASSWORD']

    # ... rest of the controller code ...
  end
end

It would also be good to add a link in your navigation for easy access:

<%= link_to "Admin Products", admin_products_path if Rails.env.development? %>

When Should You Use This Method?

Ideal for:

Internal tools, administrative, and support functions
Rapid prototyping
Simple CRUD needs where a full-blown admin gem is overkill

Not ideal for:

Customer-facing admin panels that need complex filtering, dashboards, or custom forms
Applications where you need fine-grained, role-based permissions

Conclusion

The scaffold_controller generator is a fantastic piece of Rails tooling that is often overlooked. It embodies the Rails philosophy of providing quick solutions for common problems. In just a few minutes you can have a functional, separate admin area for any model without the overhead of a new gem or the risk of breaking your public-facing code. So next time you need a simple data management interface, skip the gem research and let scaffold_controller do the heavy lifting for you.

Using ActiveSupport::ExecutionContext to improve Rails logging

2025-12-05T00:00:00+00:00

If you’ve ever tried to debug a complex user workflow in a modern Rails application, you know how difficult it can be. A single web request can spawn multiple background jobs, Turbo Stream updates, and a flurry of database queries. Answering the question “What was this user doing?” should be simple, but tracing the flow of events through a web of log files can be difficult and time consuming.

You can add custom log tags but that gets tedious and messy fast. Fortunately, Rails has a powerful, under-documented feature designed specifically to address this problem: ActiveSupport::ExecutionContext.

In this post, we’ll walk through what ExecutionContext is and how you can use it to add meaningful structure to your logs, making debugging a much more straightforward task.

The Problem: A Tangled Web of Logs

Imagine a user places an order on your site. The OrdersController#create action fires, which then enqueues a ReceiptJob and an InventoryUpdateJob. The controller also renders a Turbo Stream to update the UI. You have at least four separate units of work: the HTTP request and three background tasks.

Now, if the InventoryUpdateJob fails, your log might show an exception, but it won’t immediately tell you which user’s order triggered it. You’re left grepping for job IDs or tracing timestamps. ExecutionContext solves this problem by providing a shared context that is automatically shared across these different units of work.

How ExecutionContext Works

Think of ActiveSupport::ExecutionContext as a container for data that automatically gets passed along. When you store something in it during a web request, that data is bundled up and made available in any background jobs you start from that request without you having to manually send it.

It’s important to note that while ActiveSupport::ExecutionContext values are available within the same process (e.g., during the web request), they don’t automatically serialize and propagate to background jobs. For the context to be available in jobs, you’ll need to explicitly pass relevant values as job arguments. In our example, since we’re already passing the order object to both jobs, we can access order.user_id and order.id directly in the job. For contexts without such natural carriers consider extracting the relevant values and passing them explicitly as additional job arguments.

This is the magic that allows you to trace a chain of events.

A Practical Example: Tracing an Order

Let’s implement a solution for the ordering scenario. Our goal is to tag every log line related to this specific order with the user’s ID and the order ID.

First, we’ll set the context in an around_action in our ApplicationController:

# app/controllers/application_controller.rb
class ApplicationController < ActionController::Base
  around_action :set_execution_context

  private

  def set_execution_context
    # We only set the context if a user is logged in.
    if current_user
      ActiveSupport::ExecutionContext[:user_id] = current_user.id
      # We can also trace requests
      ActiveSupport::ExecutionContext[:request_id] = request.request_id
    end

    yield
  ensure
    # Ensure the context is cleared after the request is done.
    ActiveSupport::ExecutionContext.clear
  end
end

# app/controllers/orders_controller.rb
class OrdersController < ApplicationController
  def create
    @order = current_user.orders.create!(order_params)

    # Update the context with the real order_id
    ActiveSupport::ExecutionContext[:order_id] = @order.id

    ReceiptJob.perform_later(@order)
    InventoryUpdateJob.perform_later(@order)

    respond_to do |format|
      format.turbo_stream
    end
  end
end

Because we used perform_later, Active Job will automatically serialize our ExecutionContext (containing user_id and order_id) and make it available when the job runs.

Let’s look at the InventoryUpdateJob:

# app/jobs/inventory_update_job.rb
class InventoryUpdateJob < ApplicationJob
  def perform(order)
    logger.info "Updating inventory for order"

    # ... your business logic ...
  end
end

Making the Context Visible in Logs

Setting the context is only half the battle; we also need to see it in our logs. We can do this by customizing Rails’s log formatter.

Here’s a simple formatter that appends the execution context to every log line:

# config/initializers/log_formatting.rb
class ContextAwareFormatter < Logger::Formatter
  def call(severity, time, progname, msg)
    context = ActiveSupport::ExecutionContext.to_h

    tags = context.map { |key, value| "#{key}=#{value}" }.join(" ")
    tags = "[#{tags}] " unless tags.empty?

    "#{time.utc.iso8601(3)} #{severity} ##{Process.pid} #{tags}#{msg2str(msg)}\n"
  end
end

# Apply it to the Rails logger
Rails.logger.formatter = ContextAwareFormatter.new

With this in place, a log line from our InventoryUpdateJob might now look like this:

2025-12-01T15:33:01.123 INFO #123 [user_id=1001 order_id=998842] Updating inventory for order

If that job fails, the stack trace will be prefixed with the same [user_id=1001 order_id=998842] context. You can instantly see which user and order were affected.

Going Beyond: Tagging Database Queries

One of the most powerful applications is tagging database queries. This is incredibly useful for identifying expensive queries related to a specific user in a production environment.

You can subscribe to the SQL event and include the context in the log:

# config/initializers/log_formatting.rb
ActiveSupport::Notifications.subscribe("sql.active_record") do |event|
  context = ActiveSupport::ExecutionContext.to_h
  next if context.empty?

  payload = event.payload
  sql_with_context = "/* #{context.map { |k, v| "#{k}:#{v}" }.join(', ')} */ #{payload[:sql]}"

  Rails.logger.debug("SQL: #{sql_with_context}")
end

Here is what that log line would look like:

DEBUG -- : SQL: /* user_id:1001, order_id:998842 */ SELECT "orders".* FROM "orders" WHERE "orders"."user_id" = $1 LIMIT $2  [["user_id", 1001], ["LIMIT", 1]]

The SQL notification subscriber will fire on every database query which in production could introduce noticeable overhead. Consider wrapping this functionality in a Rails.env.development? check or using feature flags to control its activation. Be mindful of this trade-off when adding context to high-volume SQL logging.

A Stitch in Time Saves Nine

ActiveSupport::ExecutionContext is a robust solution to a common problem in modern, event-driven Rails applications. It provides a clean, built-in mechanism for propagating context, which leads to more debuggable and observable systems.

The next time you find yourself lost in a sea of log files, remember this tool. By adding a few lines of code to set the context and customizing your log formatter, you can transform a chaotic log file into a well-organized story of what your application is doing for each and every user.

Building Offline-Capable Rails Apps Using Service Workers and Turbo

2025-08-07T00:00:00+00:00

Users today expect web apps to continue working even when their internet connection is unstable or temporarily lost. Out of the box, Rails applications do not handle this well. In this blog post, we will walk through how to add offline support to a Rails app using Service Workers, Workbox, and Turbo. This approach gives users a smoother experience and better reliability when network conditions are not ideal.

This guide focuses on a real-world setup. You will learn how to cache pages and assets, handle Turbo form submissions offline, and provide a fallback UI when needed.

Why Offline Support Matters

Turbo makes Rails applications fast and responsive by replacing traditional client-side JavaScript with HTML over the wire. However, if the network drops out, those Turbo requests fail silently. Adding a Service Worker allows us to intercept those requests and provide a better experience.

Offline support improves performance, enhances user experience on mobile devices, and adds resilience in situations where network access is intermittent.

Creating a Manifest File

Start by adding a manifest file to your Rails app. This file lets the browser know your app supports offline behavior.

Create a file at app/assets/manifest.json with the following content:

{
  "name": "Offline Rails App",
  "short_name": "OfflineRails",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#222222"
}

Then, in your application layout, reference the manifest file:

<%= tag.link rel: "manifest", href: asset_path("manifest.json") %>

This enables progressive web app features and prepares your app for Service Worker support.

Creating the Service Worker

Rails does not ship with a Service Worker, so you need to create one. You can either output the compiled Service Worker file directly into the public folder or configure your JavaScript build system to handle it.

Here is a minimal Service Worker example using Workbox, saved as public/service-worker.js:

import { precacheAndRoute } from 'workbox-precaching'
import { registerRoute } from 'workbox-routing'
import { NetworkFirst, CacheFirst } from 'workbox-strategies'

precacheAndRoute(self.__WB_MANIFEST || [])

registerRoute(
  ({ request }) => request.mode === 'navigate',
  new NetworkFirst()
)

registerRoute(
  ({ request }) => ['style', 'script', 'image'].includes(request.destination),
  new CacheFirst()
)

This configuration tells the browser to try the network first for page navigation, but to fall back to cache if offline. Static assets such as stylesheets, scripts, and images are cached after the first visit.

Registering the Service Worker in Your Rails App

To register the Service Worker, add this code to your Rails JavaScript entry point. In Rails 7 with import maps or jsbundling, this is usually found in application.js or app/javascript/application.js:

if ('serviceWorker' in navigator) {
  window.addEventListener('load', () => {
    navigator.serviceWorker.register('/service-worker.js')
      .then(reg => console.log('Service worker registered', reg))
      .catch(err => console.error('Registration failed', err))
  })
}

Once registered, the browser begins managing network requests through the Service Worker.

Pre-Caching Essential Pages

To ensure key pages are available offline before a user visits them, you can pre-cache them during the install phase of the Service Worker.

Add the following to your Service Worker file:

self.addEventListener('install', event => {
  event.waitUntil(
    caches.open('static-pages-v1').then(cache => {
      return cache.addAll([
        '/',
        '/important_things',
        '/offline.html'
      ])
    })
  )
})

These pre-cached pages are useful for first-time offline users and can be extended as needed.

Handling Offline Turbo Form Submissions

Turbo uses fetch to submit forms. If the network is down, the request will fail and the user may not even notice. To improve this, you can intercept Turbo form submissions using Stimulus and queue them locally.

Here is an example Stimulus controller:

import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  connect() {
    this.element.addEventListener("turbo:submit-start", event => {
      if (!navigator.onLine) {
        event.preventDefault()
        const formData = new FormData(this.element)
        const payload = Object.fromEntries(formData)
        queueOfflineSubmission(payload)
        alert("You are offline. Your submission has been saved.")
      }
    })
  }
}

You will need to define queueOfflineSubmission to save the data to IndexedDB or localStorage. Later, you can sync the data when the connection is restored.

Adding an Offline Fallback Page

If a request fails because the user is offline and the response is not cached, it is helpful to show a fallback page.

Add this to your Service Worker:

self.addEventListener('fetch', event => {
  event.respondWith(
    fetch(event.request).catch(() => {
      return caches.match('/offline.html')
    })
  )
})

Place a simple offline.html file in the public folder. This helps users understand what happened instead of seeing a generic browser error.

Summary

Adding offline support to a Rails application is very achievable using Turbo, Service Workers, and a small amount of JavaScript. With this setup, your app can handle dropped connections without frustrating your users.

You now have a working foundation that includes:

A browser manifest and Service Worker registration
Cached pages and assets for offline use
Form submission queuing while offline
A fallback UI for missing network responses

Integrating Grape with Sidekiq for Asynchronous Processing in Rails

2025-08-04T00:00:00+00:00

When building an API in a Rails application using Grape, there is a natural tendency to handle all logic synchronously. For small applications or internal tools, that can work well. But for a growing SaaS platform or public-facing API, doing too much work in the request cycle leads to slower response times and can make your endpoints fragile.

This post walks through the process of integrating Grape with Sidekiq so that heavy tasks can be moved to background workers. The goal is to keep endpoints fast and resilient while offloading expensive processing.

Why asynchronous processing matters

Many common tasks in an API do not need to be done immediately. Examples include sending confirmation emails, syncing to a third-party service, exporting data, or generating reports. By sending these jobs to a background processor like Sidekiq, the API can respond quickly and let the user continue without waiting.

Separating these tasks also gives better observability and error handling. Sidekiq offers retries, job tracking, and simple ways to inspect queues out of the box.

Setting up Grape and Sidekiq

Assuming you already have a Rails application with Grape installed, the next step is to add Sidekiq and Redis. Redis is used to store the job queue.

Add the following to your Gemfile:

gem 'grape'
gem 'sidekiq'

Run bundle install and start Redis if it is not already running.

Next, configure Rails to use Sidekiq for background jobs by setting the queue adapter in config/application.rb:

config.active_job.queue_adapter = :sidekiq

You can also add a basic Sidekiq YAML config file to control queue priorities:

# config/sidekiq.yml
:queues:
  - default

Creating a Sidekiq worker

To use Sidekiq directly, create a new file in app/workers. For example, to send a welcome email:

class WelcomeEmailWorker
  include Sidekiq::Worker

  def perform(this_username)
    user = User.find_by(username: this_username)
    UserMailer.welcome(user).deliver_now
  end
end

This worker fetches a user and sends an email using a standard Rails mailer. The goal here is to keep logic focused and avoid branching inside the job.

Triggering a background job from a Grape endpoint

Now we connect the worker to a Grape endpoint. Here is an example of an endpoint that creates a user and queues a welcome email to be sent later:

# app/api/v1/users_api.rb
module V1
  class UsersAPI < Grape::API
    version 'v1', using: :path
    format :json

    resource :users do
      desc 'Create a user and queue welcome email'
      params do
        requires :email, type: String, desc: 'Users email'
        requires :name, type: String, desc: 'Users name'
        requires :username, type: String, desc: 'Users username'
      end
      post do
        user = User.create!(declared(params))

        # Enqueue welcome email
        WelcomeEmailJob.perform_later(user.username)

        status 201
        { id: user.id, email: user.email, name: user.name, username: user.username }
      end
    end
  end
end

Once the user is saved to the database, the perform_async method queues the job to be picked up by a running Sidekiq worker process.

This lets the API return a response right away instead of waiting for the email to be sent. In a production environment, this difference becomes more noticeable when there are many different parts to the request, or many requests to be triggered.

Running Sidekiq

To process jobs, Sidekiq must be running in a separate process from your Rails app server. In development, you can run it with:

bundle exec sidekiq

You should see logs indicating that the worker has started and is listening for jobs on the default queue.

Error handling and retries

Sidekiq includes built-in retry logic. You can configure the number of retries or disable them for specific jobs.

To log errors explicitly or report them to an external service, wrap your job logic in a begin-rescue block:

def perform(this_username)
  user = User.find_by(username: this_username)
  UserMailer.welcome(user).deliver_now
rescue => e
  Rails.logger.error("Welcome email failed: #{e.message}")
  raise e
end

Raising the error ensures that Sidekiq still sees the job as failed and can retry it if needed.

Conclusion

Integrating Grape with Sidekiq is a simple but effective way to improve performance and reliability in a Rails API. It lets you keep endpoint logic clean and offload work that does not need to be completed immediately.

This approach scales well for APIs that process uploads, send notifications, or interact with third-party services. It also aligns with the principle of keeping the request-response cycle short and predictable.

If you’re working with Grape in a growing Rails project, this is a natural next step.

Rebuilding a Modern App in Rails 7 Without JavaScript Frameworks

2025-05-13T00:00:00+00:00

In the realm of web development, the allure of JavaScript frameworks like React and Vue is undeniable. However, I recently embarked on a mission to rebuild a modern web application using Rails 7, Hotwire, and Turbo, deliberately avoiding any JavaScript frameworks. The outcome was a streamlined stack, improved performance, and a more maintainable codebase.

Why Consider a Framework-Free Approach in 2025?

The complexity introduced by modern JavaScript frameworks can sometimes overshadow their benefits. Managing dependencies, build tools, and the intricacies of client-side rendering often lead to increased development overhead. With the advancements in Rails 7, particularly the introduction of Hotwire and Turbo, it’s now feasible to build dynamic, responsive applications without the need for additional JavaScript frameworks.

The Application: A Simplified Project Management Tool

I had previously built an app that was esentially a simplified version of Trello. The app is a lightweight project management tool featuring:

Boards and cards
Drag-and-drop functionality
Real-time updates
Commenting system
User authentication and role management

Originally built with a React frontend and a Rails API backend, I decided to reconstruct it as a Rails 7 application, using Hotwire and Turbo for interactivity.

Advantages of Using Rails 7 with Hotwire and Turbo

Simplified stack: Eliminating the need for separate frontend frameworks reduced complexity and streamlined the development process.
Enhanced performance: Server-rendered HTML and Turbo’s partial page updates led to faster load times and a more responsive user experience.
Improved maintainability: A unified codebase made it easier to manage and scale the application over time.

Challenges Encountered

While the experience was largely positive, there were some hurdles:

Implementing drag-and-drop: Achieving this functionality required integrating a lightweight JavaScript library and connecting it with Stimulus controllers.
Real-time collaboration: Utilizing Turbo Streams and ActionCable facilitated real-time updates, but required careful handling to ensure consistency across clients.
File uploads: Managing file uploads and displaying progress indicators necessitated additional configuration and integration with Active Storage.

Successes Achieved

Despite the challenges, several aspects of the rebuild were notably successful:

Modal dialogs with turbo frames: Loading forms and content into modals became straightforward, enhancing user interaction without additional JavaScript.
Live updates with turbo streams: Real-time broadcasting of updates improved collaboration features and kept users informed without manual refreshes.
Interactive elements with stimulus: Implementing dynamic behaviors like toggles and dropdowns was efficient and required minimal JavaScript.

Comparison to the Previous React-Based Build

Feature	React Version	Hotwire Version
Build complexity	High (Webpack, Babel, etc.)	Low (No bundler required)
Developer onboarding	Steep learning curve	More accessible for full-stack devs
Performance	Fast post-hydration	Fast initial load with partial updates
Real-time capabilities	Requires state management libraries	Built-in with Turbo Streams
Maintenance overhead	Higher due to separate codebases	Lower with a unified codebase

Final Thoughts

Rebuilding the application using Rails 7 with Hotwire and Turbo proved to be a rewarding experience. The simplified stack, improved performance, and enhanced maintainability made it a compelling approach for developing modern web applications. While certain complex functionalities required additional effort, the overall benefits outweighed the challenges.

For developers seeking to build responsive and dynamic applications without the overhead of JavaScript frameworks, exploring the capabilities of Rails 7 with Hotwire and Turbo is a great option.

Migrating Rails 6 React to Rails 7 React

2023-06-26T00:00:00+00:00

CasePointer’s disease reporting portal is built on React and Rails 6, and it’s time for an upgrade to Rails 7. This blog post will cover the steps, benefits, and challenges of migrating from Rails 6 to Rails 7, and offer valuable insights into the world of Ruby on Rails.

With the recent release of Rails 7, there are many new features and improvements to explore. One of the biggest changes in Rails 7 is the retirement of Webpacker in favor of using the native webpack for bundling JavaScript.

For those who are not familiar, Webpacker is a Rails gem which is a wrapper around the webpack build system that provides a standard webpack configuration and reasonable defaults.

Steps for migrating Rails 6 React to Rails 7 React

To migrate a Rails 6 React application to Rails 7 React, follow these steps:

1. Update the Rails Gem in the Gemfile

In your application’s Gemfile, update the Rails gem version to Rails 7:

-gem "rails", "~> 6.1.4"
+gem "rails", "~> 7.0.0"

2. Upgrade Rails packages

Upgrade the Rails packages using Yarn:

yarn upgrade @rails/actioncable --latest
yarn upgrade @rails/activestorage --latest

3. Run the Rails update task

Run the following command to initiate the Rails update task:

bin/rails app:update

This task guides you file by file to integrate the new Rails 7 defaults. Refer to the Rails documentation for detailed information on this update task.

4. Remove Webpacker

Since Webpacker is no longer the default in Rails 7, follow these steps to remove it:

Remove the webpacker gem from your Gemfile:

-gem 'webpacker', '~> 4.0'

Remove the webpacker.yml file and any other files associated with webpacker.

Run bundle install to update the Gemfile.lock:

bundle install

5. Setting up Webpack

To set up Webpack for your Rails 7 React application, follow these steps:

Install webpack and other necessary libraries:

yarn install webpack webpack-cli @babel/core

Create a webpack.config.js file at the root of your application:

// webpack.config.js

const path = require("path");
const webpack = require("webpack");
// Add other necessary plugins and configurations

module.exports = {
  // Webpack configuration options
  output: {
    // Make sure to use the path of the rails asset pipeline
    path: path.join(__dirname, '/app/assets/builds'),
    // ...
  }
  module: {
    rules: [
      // Add CSS/SASS/SCSS rule with loaders
      {
        test: /\.(?:sa|sc|c)ss$/i,
        use: [MiniCssExtractPlugin.loader, 'css-loader', 'sass-loader'],
      },
      {
        test: /\.(png|jpe?g|gif|eot|woff2|woff|ttf|svg)$/i,
        use: 'file-loader',
      },
      {
        test: /\.(js|jsx)$/,
        exclude: /node_modules/,
        use: {
          loader: "babel-loader"
        }
      }
    ],
  },
  // ...
};

Add a .babelrc file for Babel configuration:

{
  "presets": ["@babel/preset-env", "@babel/preset-react"]
}

Update the scripts section in your package.json:

{
  "scripts": {
    "build": "webpack",
    "dev": "webpack --watch"
  }
}

6. Update Rails asset tags

In your application views, update the asset tags from stylesheet_pack_tag and javascript_pack_tag to stylesheet_link_tag and javascript_include_tag, respectively:

<%= stylesheet_link_tag 'application', media: 'all', 'data-turbolinks-track': 'reload' %>
<%= javascript_include_tag 'application', 'data-turbolinks-track': 'reload' %>

7. Start the dev server

Start the Rails development server with:

rails server

Then start the React development server with:

yarn run dev

By following these steps, we can take advantage of the new features and improvements in Rails 7 while continuing to leverage the power of React.

I wrote the same app twice, with Hotwire and Blazor Server — here’s what I learned

2023-05-27T00:00:00+00:00

There’s been a very interesting movement that has emerged recently in the world of frontend web development: a rise of little-to-no-JavaScript frontend frameworks.

The promise here is that we would be able to develop web applications with rich interactive capabilities without the need to write a whole lot of JavaScript. As such, these new approaches present themselves as alternatives to the likes of Vue, React, Angular, etc.

Two recent technologies that try to fulfill this promise come from two of the most prolific web application development frameworks of today: Blazor, built on .NET, and Hotwire, built on Ruby on Rails.

Now, I love my JS frameworks as much as the next guy, but these new technologies are intriguing. So I decided to build the same application twice, with Hotwire and with Blazor. I learned a few things along the way that I would like to share in this blog post.

Note that there is a table of contents at the end of this post.

What this article is

I want to present some of my findings when working with these two technologies. I also want to discuss how they work and how they feel. How they are similar and how they are different. How they take different routes to arrive at their ultimately similar destinations. Maybe offer some pros and cons.

This post assumes sufficient familiarity with C#, ASP.NET, Ruby, Ruby on Rails and the current state of the art of web development. I won’t assume any familiarity with either Blazor or Hotwire, but this is not a tutorial for either, so I won’t explain in detail how to fully build apps with these technologies.

So who am I writing this for? Essentially, for anybody who is curious about these technologies and is interested in understanding the big picture of what they are about, how they compare to each other, and building their next project with one of them. So, this article is intended to serve more as an introduction to both, a starting point for a conversation to help you make a decision on what’s best for you and your team.

Spoiler alert: Both are great and you can’t go wrong with either. It all comes down to your team’s preferences and past experience.

One final thing worth noting is that I’m focusing this article on “Blazor Server” specifically. I’ll be using the word “Blazor” moving forward, for short. Blazor as a framework has three variants: Blazor Server, Blazor WebAssembly and Blazor Hybrid. You can learn more about them here.

Most of the examples that I’ll use in this post come from a couple of demo apps that I built in order to get my feet wet with these technologies. You can find both of them in GitHub. Here’s the Blazor one and here’s the Hotwire one. You can study both the source code and the commit history, which I tried my best to keep neatly organized. They are both functionally identical, and based on this excellent Hotwire tutorial.

An overview of Blazor

When it comes to how they are designed and the developer experience they offer, these two are very different. Let’s go over some of the key details of Blazor and then we’ll do the same with Hotwire. With that, the differences between them will become apparent.

The first thing we have to understand about Blazor is that it is a component framework, very much like Vue or React. So, with Blazor, applications are broken up into composable modules called “Razor/Blazor components” that are essentially independent pieces of GUI bundled with their corresponding logic. Each component has three parts to it:

HTML-like markup that describes the layout and UI elements to be rendered,
C# logic that defines the behavior of the component, like what actions to take when users interact with GUI elements, and
CSS for styling the GUI elements.

For example here’s a simple a Blazor component that allows displaying, editing, and deleting a particular type of record called “Quote”. Don’t worry about the details too much; we’ll go over some of them next. For now, I just want us to get a sense of what Blazor components look like:

@using Microsoft.EntityFrameworkCore

@inject IDbContextFactory<QuoteEditorBlazor.Data.QuoteEditorContext> dbContextFactory

@if (isEditing)
{
    <QuoteEditorBlazor.Shared.Quotes.Edit
        QuoteToEdit="QuoteToShow"
        OnCancel="HideEditForm"
    />
}
else
{
    <div class="quote">
        <a href="quotes/@QuoteToShow.ID">@QuoteToShow.Name</a>
        <div class="quote__actions">
            <a class="btn btn--light" @onclick="DeleteQuote">Delete</a>
            <a class="btn btn--light" @onclick="ShowEditForm">Edit</a>
        </div>
    </div>
}

@code {
    [Parameter]
    public QuoteEditorBlazor.Models.Quote QuoteToShow { get; set; }

    [Parameter]
    public EventCallback OnQuoteDeleted { get; set; }

    bool isEditing = false;

    void ShowEditForm()
    {
        isEditing = true;
    }

    void HideEditForm()
    {
        isEditing = false;
    }

    void DeleteQuote()
    {
        using var context = dbContextFactory.CreateDbContext();
        context.Quotes.Remove(QuoteToShow);
        context.SaveChanges();
        OnQuoteDeleted.InvokeAsync();
    }
}

You can see that we have some C# in the file (enclosed in a @code block) with some event handlers and parameters. We also have some markup written with a mixture of HTML and C#. This markup has conditionals, wires up click event handlers, renders data from a given record, renders another component, etc. That markup is really just Razor, a templating language that has been widely used in ASP.NET for a good while now. And we also have some top-level statements like @using and @inject for including classes and objects that the component can use.

As far as CSS goes, here’s how it works: Suppose these are the contents of a file called Example.razor. The CSS for it would have to be defined in an Example.razor.css file sitting right next to it. Syntax-wise, this would just be a plain old CSS file. One cool thing to mention about it, though, is that the CSS within it is visible only to the component. So there’s no risk of conflicting rules between components.

If you’re familiar with modern frontend web development and have used frameworks like Vue or React, this should look very familiar to you. In fact, I would venture to say this is one of Blazor’s most attractive points. If you come from that background, and know .NET, it’s not that big of a leap to get into Blazor. The development experience is very similar as its design shares many concepts with modern JS frameworks; they operate under a very similar mental model.

Of course, C# is not JavaScript and .NET is not a browser. So there are many differences when it comes to the nitty-gritty mechanics of things. So a thorough understanding of the .NET framework and its libraries is also important for mastering Blazor. Which, depending on your team’s background, may be a point in favor or against.

How Blazor works under the hood

As you can probably gather from the previous discussion, Blazor takes control of the entire GUI of the application and puts up a firm layer of abstraction over traditional native web technologies. All notion of JavaScript or code executing on a browser environment is greatly de-emphasized. In fact, most of Blazor executes in the server.

Essentially, all the code that you actually write executes on the server side. When a user begins using the app, a two-way, persistent SignalR connection is established between the browser and server. Whenever the client requests a page, the server renders it and sends it through the connection to the client browser, where there’s a component that interprets and displays it. Likewise, whenever the user interacts with some UI element, like clicking a button or a link, the action is sent to the server via this SignalR connection for it to be processed. If changes to the GUI are necessary, the server calculates them and sends them back to the user’s browser, where they will be interpreted and used to re-render the screen with the new state.

Microsoft’s official documentation has an excellent diagram that helps explain the process:

So, even though there is client side code running and browser DOM being manipulated, this is all happening under the hood. The developer doesn’t need to be concerned with that and can just focus on authoring C# code, for the most part.

This approach has a few implications worth noting. One is that this means higher load on the server compared to more traditional web applications. This is mainly because there needs to be a connection always open between clients and the server, by design. Classic HTTP is purely stateless, and connections are typically opened and closed multiple times throughout a user’s session, as they interact with the web app. Not so for Blazor, where this SignalR connection (most likely via WebSockets) is always alive. So, for scalability concerns, we need to keep in mind that the more concurrent users our app has, the more resources the server will consume, even if the users are somewhat idle.

An abstraction over the request/response cycle

A key element of Blazor is that it abstracts developers from the classic HTTP request/response model. With Blazor, one seldom has to consider that aspect, as all interactions between client and server are managed via the framework itself through the persistent connection we discussed in the last couple of paragraphs. To the developer, there’s no real separation between the two. This is a big departure from classic MVC-like frameworks where things like endpoints, actions, and controllers are front and center. Such concepts are simply not in play on Blazor apps. The idea is to make them feel more like desktop apps: fully integrated, monolithic, simple packages of GUI and functionality.

This could become a double-edged sword as, in general, it is always important to have a clear understanding of the underlying technologies that support the application stack you’re working with. That is, the web is still there, even if you can’t see it. But as long as you’re cognizant of that, this approach can have great advantages too.

For example, thanks to this approach, there’s no need to employ the classic SPA pattern of developing applications in two halves: 1. a backend Web API for domain logic written in some backend programming language, and 2. a frontend application written in JavaScript that implements the user experience and communicates with the backend over HTTP.

Blazor attempts to offer a simpler solution from a developer’s perspective, where everything lives in the same execution environment so there’s no need for inter-process communication over HTTP. The example Blazor component from before demonstrates such a case. Notice how this link has an event handler registered to its click event:

<a @onclick="DeleteQuote">Delete</a>

That DeleteQuote event handler, simply defined as the method below, directly leverages the DbContext to issue the delete command to the underlying database:

void DeleteQuote()
{
    using var context = dbContextFactory.CreateDbContext();
    context.Quotes.Remove(QuoteToShow);
    context.SaveChanges();
}

Pretty simple.

However, this flexibility also requires great discipline from the development team. It falls upon us not to clutter the GUI code with all manner of extraneous things like database calls and domain or application logic that have nothing to do with user interface concerns. The traditional two-halves pattern for SPAs has this separation between domain and GUI logic baked in by necessity. Blazor allows us to break free from it, but that does not mean that the separation is not useful or even necessary. For a small example like this, this works just fine, but for larger applications, a more modularized design should be considered as well. Maybe the introduction of abstractions like repositories or domain services? At the end of the day, the core software design principles still need to be applied.

How Blazor supports common frontend framework features

Something else to consider, which I touched on before, is that Blazor is built on top of .NET. That means that a solid understanding of .NET concepts is all but a necessity in order to be effective with Blazor. Most of the features that are now traditional and expected in frontend JavaScript frameworks exist in Blazor, and they are implemented using age-old .NET concepts. If your team has solid .NET experience, this is a blessing. If not, then Blazor requires a larger investment, one that could be overwhelming depending on your time constraints.

Here are a few examples of how Blazor implements classic frontend framework features:

Handling DOM events

We already saw how event handlers work: they are defined as regular C# methods. The way they are registered to respond to events is via attributes in the GUI elements like @onclick or @onchange. All traditional DOM events are available. Like this:

<a @onclick="DeleteQuote">Delete</a>

Including other Blazor components

We also saw how to render components from within other components. All it takes is adding the component to the template as if it was any other GUI element/HTML tag. The tag itself is the name of the component, which sometimes needs to be fully qualified. We saw an example before:

<QuoteEditorBlazor.Shared.Quotes.Edit
    QuoteToEdit="QuoteToShow"
    OnCancel="HideEditForm"
/>

The fully qualified component name is QuoteEditorBlazor.Shared.Quotes.Edit in this case, and that’s how we reference it. If we were to include the namespace with an @using statement (like @using QuoteEditorBlazor.Shared.Quotes near the top of the file) then we would be able to invoke the component just by its name of Edit.

Passing parameters to components

That previous snippet also demonstrates how to pass parameters to components. In this case, we have two: QuoteToEdit which is an object, and OnCancel which is a custom event. As you can see, parameters are passed as if they were HTML element attributes. In the case of QuoteToEdit, we’re passing it QuoteToShow, which is a C# Property defined in the @code section of the component:

public QuoteEditorBlazor.Models.Quote QuoteToShow { get; set; }

In order for the receiving component to be able to accept the parameter, it needs to define a property itself of the same type, annotated with the Parameter attribute. In this case, the QuoteEditorBlazor.Shared.Quotes.Edit component defines it like this:

[Parameter]
public QuoteEditorBlazor.Models.Quote QuoteToEdit { get; set; }

Notice how the name of the property is the same name used for the “HTML attribute” that was used in markup to pass the parameter to the component:

QuoteToEdit="QuoteToShow"

In this case, the expected parameter is of type QuoteEditorBlazor.Models.Quote.

Defining, handling and triggering custom component events

The other parameter, which is a custom event, accepts a method. It looks like this in the receiving component:

[Parameter]
public EventCallback OnCancel { get; set; }

Again, this is a Property annotated with the Parameter Attribute. The only difference is that the type of this one is EventCallback. That’s what allows it to accept a method. Then, inside the receiving component, the event can be triggered with code like this:

OnCancel.InvokeAsync();

This will execute whatever method the parent component has registered as a handler for this custom event. In this case, that would be our HideEditForm method.

Handling component lifecycle events

Other than DOM and custom events, much like in other frontend frameworks, Blazor components also offer ways of hooking up to their own internal lifecycle events. OnInitialized is one of the most important ones, which runs when the component is first starting up. To hook into it and run some code when it happens, all a Blazor component has to do is implement it as a method override within its code section. Something like this:

protected override void OnInitialized()
{
    // Do something here.
}

There’s more to learn about component lifecycle and the official documentation does a good job in explaining it.

Templates

Like we discussed before, Blazor also offers a rich templating syntax via Razor, which is also a hallmark of modern frontend frameworks. We have conditional rendering, support for loops, interpolation of data, model binding, etc.

Routing

Routing is also included in Blazor and the way that it works is with the @page directive that’s used on top of components like this:

@page "/quotes"

Not all components will use these, only those that correspond to whole pages. Most components will be used as portions of pages and as such, would not include these. A @page statement like the above will make the component that includes it accessible via an URL like http://mydomain.com/quotes. In other words, at the root of the site.

These routes also support parameters, which can be defined like this:

@page "/quotes/{quoteId:int}"

A component with this directive will be accessible through URLs like http://mydomain.com/quotes/123. The code in the component can access the route parameter quoteId by defining it as a Property with the matching type, annotated with the Parameter attribute. Like this:

[Parameter]
public int QuoteId { get; set; }.

State management

Global application state management à la Vuex or Redux is also available in Blazor. The cool thing about how this is implemented in Blazor is that there is no need for any additional library or special components. A global app store can be a simple C# object that’s configured to have a lifetime that spans that of the user’s session. Here’s an example of a class that’s used to store global flash messages:

namespace QuoteEditorBlazor.AppState;

public class FlashStore
{
    public List<string> Messages { get; private set; } = new List<string>();

    public event Action? MessagesChanged;

    public async void AddMessage(string message)
    {
        Messages.Add(message);
        MessagesChanged?.Invoke();

        await Task.Delay(TimeSpan.FromSeconds(5));

        Messages.Remove(message);
        MessagesChanged?.Invoke();
    }
}

Like I said: a plain and simple C# class. It offers a method for displaying a message for a few seconds. It does this by storing the given message into an internal variable and then, after a little while, it gets removed. It also offers a MessagesChanged event that other components can subscribe to which is triggered as messages are added and removed.

The lifetime of the instance is controlled via its dependency injection configuration. In our Program.cs, it would be configured like this:

builder.Services.AddScoped<FlashStore>();

Like I mentioned before, Blazor apps establish a persistent connection for the user throughout their session. This means that the instance of the app that is running on the server is also persistent. So, if we add FlashStore as a scoped service, one single instance of it will also persist throughout the session. That’s why we can rely on its internal variables to store global application state.

You can learn more about state management in Blazor here.

Then, you could have a component that renders those messages that looks like this:

@using QuoteEditorBlazor.AppState

@inject FlashStore flashStore

@implements IDisposable

<div class="flash">
    @foreach (var message in flashStore.Messages)
    {
        <div class="flash__message">
            @message
        </div>
    }
</div>

@code {
    protected override void OnInitialized()
    {
        flashStore.MessagesChanged += StateHasChanged;
    }

    public void Dispose()
    {
        flashStore.MessagesChanged -= StateHasChanged;
    }
}

Very simple too. This Blazor component uses a loop to render all the messages. There are a couple of interesting things about this one. First, the component gets access to the instance of the FlashStore class via the @inject directive near the top of the file. That’s how the flashStore variable is made available for the component to use both in C# code and in the template.

The second interesting element is how this component registers its StateHasChanged method to the MessagesChanged event defined in FlashStore. As you recall, FlashStore will trigger MessagesChanged every time messages are added or removed. By registering StateHasChanged to that event, we make sure that the component re-renders every time the messages list changes; which in turn ensures that the most current messages are always rendered. Kind of a neat trick.

And as you might expect, any piece of code throughout the app can submit new messages to FlashStore by getting hold of the global instance via dependency injection and then calling:

flashStore.AddMessage("Here's a flash message!");

Interoperability with JavaScript

For all the nice abstractions that Blazor presents us with, the reality is that sometimes we actually do have to break through them. In the case of JavaScript, this happens when, for example, we need access to some native browser feature, or when we need to integrate with some library for some widget or other type of capability. In Blazor, this is certainly possible.

There are many details to consider when it comes to JavaScript interoperability in Blazor. Check out the official documentation to learn what all is possible. For our purposes here though, it’s enough to know that calls from .NET to JS and vice versa are supported.

The most basic example of calling JS code from .NET code looks like the following. If we have a JS function like this:

window.showMessagefromServer = (message) => {
    alert(`The server says: ${message}`);
    return "The client says thanks!";
};

Such a method can be invoked from a Blazor component like this:

string interopResult = await js.InvokeAsync<string>("showMessagefromServer", "Have a nice day!");

The Blazor component that runs this code would have to inject an instance of IJSRuntime into the js variable with a statement like @inject IJSRuntime js. A key thing to note is that the JavaScript method needs to be attached to the window object in order for it to be accessible.

Like I said, the other way around also works: JavaScript code is able to call .NET logic defined in a server-side Blazor component. Here’s a simple example for us to get an idea of how it feels. We can have a method that looks like this on a Blazor component:

[JSInvokable]
public static Task<string> getMessageFromServer()
{
    return Task.FromResult("Have a nice day!");
}

This method is public and static. It is also possible to invoke non-static instance methods, but the setup is a little more complicated, and this is enough for our purposes here. Other than that, as you can see, the method needs to be annotated with the JSInvokable attribute and return a type of Task.

Here’s some JavaScript that calls this method:

window.returnArrayAsync = () => {
    DotNet.invokeMethodAsync('{YOUR APP ASSEMBLY NAME}', 'getMessageFromServer')
        .then(data => {
            alert(`I asked the server and it says: ${data}`);
        });
};

There are a few noteworthy things here. First we have the DotNet.invokeMethodAsync function which Blazor makes available to us in JavaScript land. That’s what we use to invoke .NET server side code. Next, the function needs to be given the assembly name of our app as well as the name of the method to invoke within the Blazor component. This is the one that was annotated with JSInvokable. Finally, the function itself is asynchronous and thus returns a promise.

An overview of Hotwire

Hotwire makes a promise similar to Blazor’s. However, the way it goes about it couldn’t be more different.

Hotwire is much simpler and more minimalistic than Blazor. Whereas in Blazor we let the framework take total control of the GUI, just like we do with other popular frontend frameworks, Hotwire feels more like a natural evolution of traditional pre-JavaScript-heavy web development. We still have controllers and views, we still render pages on the server, and we still work in tandem with HTTP’s request/response model.

What Hotwire gives us, if we were to boil it down to a single sentence, is a way to refresh only portions of our pages as a result of user interactions. That is, we’re not forced to reload the entire page, as is the case with non-JavaScript web applications. For example, in Hotwire we have the ability to submit a form or click a link and, as a result of that, only update a particular message, picture, or section.

ASP.NET veterans will find this awfully familiar. That’s because all the way back in version 3.5, ASP.NET AJAX offered a very similar feature: partial page updates with the UpdatePanel component. Indeed, Hotwire presents a very similar concept; only greatly improved and modernized.

When it comes to actual coding, Hotwire’s footprint is minimal. It augments traditional Ruby on Rails controllers and views to produce the desired effect of page refreshes that are partial and targeted. Let’s walk through an example and you’ll see how we can start with a regular looking Rails app and then, through minor adjustments, we end up with a more richly interactive experience.

Imagine we are beginning to develop support for CRUDing a particular type of record called “Quote”, and we have these files:

### app/controllers/quotes_controller.rb
class QuotesController < ApplicationController
  def index
  end

  def new
    @quote = Quote.new
  end
end

<!-- app/views/quotes/index.html.erb -->
<main class="container">
  <div class="header">
    <h1>Quotes</h1>
    <%= link_to "New quote", new_quote_path %>
  </div>
</main>

<!-- app/views/quotes/new.html.erb -->
<main class="container">
  <%= link_to "Back to quotes", quotes_path %>

  <div class="header">
    <h1>New quote</h1>
  </div>

  <%= render "form", quote: @quote %>
</main>

<!-- app/views/quotes/_form.html.erb -->
<%= simple_form_for quote do |f| %>
  <% if quote.errors.any? %>
    <div class="error-message">
      <%= quote.errors.full_messages.to_sentence.capitalize %>
    </div>
  <% end %>

  <%= f.input :name %>
  <%= f.submit %>
<% end %>

This sample is using the simple_form gem, which you can learn more about here.

If you’re familiar with Rails, then you understand what’s happening here. We have a simple index page with a heading and a link to another page. That other page contains a form to create new Quote records. It also contains a link to go back to the index page.

Partial page updates with Turbo Frames

As they are right now, these files would produce a traditional web application user experience. When links are clicked, the whole screen will be reloaded to show the page that the clicked link points to. But what if we wanted, for example, to have the new record creation form appear out of nowhere within the same index page, without a full page reload? Here’s what that would look like with Hotwire:

 <!-- app/views/quotes/index.html.erb -->
 <main class="container">
   <div class="header">
     <h1>Quotes</h1>
     <%= link_to "New quote",
                 new_quote_path,
+                data: { turbo_frame: dom_id(Quote.new) } %>
   </div>

+  <%= turbo_frame_tag Quote.new %>
 </main>

 <!-- app/views/quotes/new.html.erb -->
 <main class="container">
   <%= link_to sanitize("&larr; Back to quotes"), quotes_path %>

   <div class="header">
     <h1>New quote</h1>
   </div>

+  <%= turbo_frame_tag Quote.new do %>
     <%= render "form", quote: @quote %>
+  <% end %>
 </main>

Remember that these examples are taken from a fully working application. Feel free to read through the source code to have a more complete understanding of the context within which these files exist.

And that’s really all it takes. Let’s go over it. With these changes, whenever a user clicks on the “New quote” link, instead of the browser triggering the usual GET request to then reload the screen and show the creation page, Hotwire’s frontend component captures the click event and makes the request itself via XHR. The server then receives this request normally and routes it to the new action in the quotes controller. All that action does is render the new.html.erb template and send that back to the client as a response.

When the Hotwire frontend component receives this, it notices that some of the response is enclosed in a turbo_frame_tag whose ID is that of an empty new Quote object. Now, because the link that the user clicked also had the ID of an empty new Quote object as its data-turbo_frame attribute, Hotwire looks for a turbo_frame_tag with the same ID in the page that’s currently being shown an replaces its contents with the contents from the similarly named turbo_frame_tag from the incoming response.

With that, you’ve seen in action some of the key elements that make Hotwire work. First of all we have the turbo_frame_tag helper, which produces a so-called “Turbo Frame”. Turbo Frames are the main building block that we use for partial page updates. Turbo Frames essentially say: “This section of the page is allowed to be dynamically updated without a full page refresh.” In an app that uses Hotwire, whenever you’re in a page that includes a Turbo Frame, if a request is made (whether it be navigation or form submission), and if the resulting response includes within it another Turbo Frame with the same ID, then Hotwire will notice the match and update the current page’s Turbo Frame with the contents of the Turbo Frame from the response.

Looking back at the code, you can see how we achieved this. We added an empty Turbo Frame on the index page, right below the link to the creation page. We also wrapped the form from the creation page in a similarly named Turbo Frame. Finally, we added the data-turbo_frame attribute to the link in the index page to tell Hotwire that it should kick in for this link and target that specific Turbo Frame. If the link was inside the Turbo Frame, we would not have to do this. Since it is outside, Hotwire needs the little hint that says: “Treat this link as if it was inside this Turbo Frame.”

I feel like this is at the same time a little awkward to wrap your head around and deceptively simple. When compared to Blazor, which builds upon tried and true concepts (as far as the developer experience goes at least), Hotwire almost seems alien, with a much more unusual style. But all in all, one can’t deny just how clean and simple all of this looks, in that “Rails magic” kind of way. And once it clicks, you can begin to see a world of possibilities opening up. The Hotwire developers managed to identify and extract a general design pattern of web application interactions, one that can be leveraged to produce a lot of varying rich interactive user experiences.

One neat aspect worth noting is that, if the user were to disable JavaScript, the app would still fully work. It would gracefully degrade. This is a direct consequence of Hotwire’s paradigm of adding minimal features on top of the existing traditional Rails programming model.

Imperative rendering with Turbo Streams

Let’s consider another example now. This time we’ll see another key component of Hotwire in action which is called Turbo Streams.

Turbo Streams helps solve the problem that emerges when the declarative style of pure Turbo Frames is not enough to obtain the fine grained control and behavior that we need. In these cases, the server needs to issue specific commands to the frontend on how to update the GUI. Via Turbo Streams, we can achieve just that. Coding-wise, these look like regular Rails view templates, albeit with some funky syntax thanks to the Turbo Stream helpers.

In our example, we’ll add a list of quotes in the index page, right below the link and the form. We’ll also complete our quote creation implementation so that we’re actually able to submit the form. As a result of that, we want the GUI to be updated so that the form goes away and the newly created quote is shown in the list. These last two are the things that we’ll use Turbo Streams for. Of course, these updates to the page will be done without a full page refresh.

Let’s start by adding a list of quotes on the index page.

In the controller, we query the database for all the quote records and store them in a variable that the view can later access.

 ### app/controllers/quotes_controller.rb
 class QuotesController < ApplicationController
   def index
+    @quotes = Quote.all
   end

   def new
     @quote = Quote.new
   end
 end

In the index view template, we render the collection of records.

 <!-- app/views/quotes/index.html.erb -->
 <main class="container">
   <div class="header">
     <h1>Quotes</h1>
     <%= link_to "New quote",
                 new_quote_path,
                 data: { turbo_frame: dom_id(Quote.new) } %>
   </div>

   <%= turbo_frame_tag Quote.new %>

+  <%= render @quotes %>
 </main>

Now we need to define a “_quote” partial view so that render statement we added on the index view can work automagically.

<!-- app/views/quotes/_quote.html.erb -->
<div class="quote">
  <%= quote.name %>
</div>

With this, the render @quotes statement will loop through all the records in @quotes and render this partial view for each on of them. This template is very simple. All it does is render the name of the quote.

Now let’s add an action that can accept quote creation form submissions:

 ### app/controllers/quotes_controller.rb
 class QuotesController < ApplicationController
   def index
     @quotes = Quote.all
   end

   def new
     @quote = Quote.new
   end
+
+  def create
+    @quote = Quote.new(quote_params)
+
+    if @quote.save
+      redirect_to quotes_path, notice: "Quote was successfully created."
+    else
+      render :new
+    end
+  end
+
+  def quote_params
+    params.require(:quote).permit(:name)
+  end
 end

A typical Rails recipe for a record creation endpoint. It takes the parameters coming from the request and uses them to create a new record via the Quote Active Record model. If successful, it redirects to the index page; if not, it renders the creation page again (via the new action). The new.html.erb view template has some logic to render error messages when they are present so those are going to show up when that page is rendered as a result of unsuccessful calls to this create endpoint.

At this point, we’re able to view all the quotes on record and create new ones. Now here are the changes to Hotwire-ify this scenario.

First we wrap the list of quotes with a Turbo Frame named “quotes”:

 <!-- app/views/quotes/index.html.erb -->
 <main class="container">
   <div class="header">
     <h1>Quotes</h1>
     <%= link_to "New quote",
                 new_quote_path,
                 data: { turbo_frame: dom_id(Quote.new) } %>
   </div>

   <%= turbo_frame_tag Quote.new %>

+  <%= turbo_frame_tag "quotes" do %>
     <%= render @quotes %>
+  <% end %>
 </main>

Next, we employ Turbo Streams. Like I said, Turbo Streams materialize themselves in code as if they were view templates. So, a new file is added that looks like this:

<!-- app/views/quotes/create.turbo_stream.erb -->
<%= turbo_stream.prepend "quotes", partial: "quotes/quote", locals: { quote: @quote } %>
<%= turbo_stream.update Quote.new, "" %>

It sort of looks like a couple of imperative statements, does it not? The first line instructs Hotwire to prepend, in the "quotes" Turbo Frame, a new render of the app/views/quotes/_quote.html.erb partial view, while passing it the @quote object as a parameter. The second line updates the Quote.new Turbo Frame to be empty. When we remember that the "quotes" Turbo Frame is the one that contains the list of records and the Quote.new Turbo Frame is the one that contains the new quote creation form, this starts to make sense. This Turbo Streams view is making the newly created quote appear in the list; and at the same time, it is making the form disappear. From a user’s perspective, this all takes place after submitting the creation form. So the user experience makes complete sense. All that with no full page refresh.

And finally, the controller action needs to make use of this new view template like so:

 ### app/controllers/quotes_controller.rb

 def create
   @quote = Quote.new(quote_params)

   if @quote.save
-    redirect_to quotes_path, notice: "Quote was successfully created."
+    respond_to do |format|
+      format.html { redirect_to quotes_path, notice: "Quote was successfully created." }
+      format.turbo_stream
+    end
   else
     render :new, status: :unprocessable_entity
   end
 end

This is yet another familiar Rails pattern. This is how we specify different response formats, whether it be HTML, JSON, XML. Now, thanks to Hotwire, we can also specify Turbo Streams. This is one of the great aspects about Hotwire: it seamlessly integrates with Rails’ existing features and concepts.

Anyway, in this case, we invoke format.turbo_stream within the block passed to respond_to and that makes it so the app/views/quotes/create.turbo_stream.erb view template is included in this action’s response. Hotwire’s frontend component sees this coming as part of the response and acts accordingly, updating the GUI how it’s been specified.

Adding JavaScript with Stimulus

The final piece of the Hotwire puzzle is Stimulus, which allows us to integrate JavaScript functionality in a neat way. Stimulus is a very simple JavaScript framework, it does not take control of the entire UI. In fact, it does not render any HTML at all. Stimulus essentially offers a nice way of wiring up JS behavior to existing markup. Let’s look at a quick example of how it could hypothetically be used for showing a confirmation popup before deleting a record.

The JavaScript logic lives inside so-called “Stimulus controllers”. For our example, it could look something like this:

// app/javascript/controllers/confirmations_controller.js
import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  confirm() {
    if (confirm("Are you sure you want to delete this record?")) {
      // Carry on with the operation...
    }
  }
}

And now, the idea is to wire up this code so that it runs when the hypothetical delete button is clicked. Here’s what that button could like:

<button
  data-controller="confirmations"
  data-action="click->confirmations#confirm"
>
  Delete
</button>

Pretty self-explanatory. We specify the name of the controller to use via the data-controller attribute. We also specify, via data-action, what method to invoke within that controller as a result of which DOM event, click in this case.

And that’s basically all it takes to sprinkle some JavaScript on Hotwire apps. Stimulus does offer a few more useful features, which you can read more about in the official documentation. But for us for now, it’s enough to know that it exists, and what’s the main idea behind it.

So as you can hopefully see, Hotwire is much smaller in scope to Blazor. And yet, it allows us to do just the same: highly interactive applications with little to no JavaScript. This ought to make a lot of Rails developers happy.

A final comparison

I was initially thinking about ending this blog post with a flowchart of sorts to explain the process of deciding which of these two technologies you should use. But really, the decision is very simple: If your team is comfortable with .NET, use Blazor. If your team is comfortable with Ruby on Rails, use Hotwire. It’s obvious, so I won’t claim to have made a great discovery here.

The only thing to add is that if your team is familiar with modern frontend web development framework concepts, you’ll be even better served by Blazor and you’ll hit the ground running. If not, then even for seasoned .NET people, there will be a decent learning curve, but not steep enough to be deterred. Moreover, if your team has no modern frontend development experience at all, then Hotwire is a godsend; thanks to its “augment classic backend-heavy web app development” style.

With that said, let’s close out with a summary of main aspects of both technologies and how they compare to each other.

Overall, Hotwire is much simpler than Blazor. While Blazor is a full-fledged GUI component framework, Hotwire’s approach is more like an augmentation of classic non-JavaScript web development patterns. That said, Hotwire’s style is more unusual than Blazor’s, so if your team is already familiar with modern frontend web development, Blazor can be a great fit.

While both frameworks try to offer enough functionality to allow the development of rich interactive experiences without the need to write any JavaScript, the reality is that sometimes JavaScript does need to be written. Both technologies offer ways to make this happen. And while both are perfectly workable, Blazor’s solution is a bit more clunky than Hotwire’s.

When it comes to classic web technologies like HTTP’s request/response cycle and the separation between server and client, Blazor’s style offers a big deviation from them. It greatly de-emphasizes them and presents instead a completely different programming model, one more akin to desktop application development. The concepts of request, response, client, and server seem to vanish. Not so for Hotwire, which builds upon these classic technologies in a way where they still need to be considered and are in fact in the spotlight. While Blazor attempts to do away with these, Hotwire embraces them.

In Blazor, client events are sent to the server, the server renders the DOM updates and sends them to the client for updates. This happens via the persistent SignalR/WebSockets connection.

Hotwire, on the other hand, intercepts client events and sends classic HTTP requests (via AJAX/XHR) to the server. The server then executes the requests and sends back the responses to the client which carries out the necessary operations, generally speaking, updating sections of the page that’s already being displayed.

That means that at the end of the day, both frameworks do the rendering on the server side and send the rendered markup over the wire to the clients. But in Blazor, the client and server have a persistent connection, while Hotwire’s connections come and go as normal HTTP requests and responses.

A neat aspect of Hotwire’s programming model is that it allows an incremental approach to web development where you can start developing the app like you would a traditional, non-reactive, non-JS app, then augment it with a little code to give it SPA capabilities.

And that’s all for now! I for one am glad to see these types of technologies emerge. While there are many teams out there that are already effective and productive with the current landscape of frontend web development, these two are very interesting and seem capable in their own right.

Besides, having alternatives is never a bad thing. Depending mainly on your previous experience, these could be a great fit for projects new and old. It’s great to know that both .NET and Rails include these types of offerings and that they work pretty well.

Implementing Basic HTTP Authentication in Rails

2023-01-26T00:00:00+00:00

Nowadays it’s rather unusual to deploy HTTP Basic Authentication in a production web application. However, the need came up recently from a client. In a nutshell, due to integration requirements with a third party system, we had to provide a web app which expected credentials supplied via Basic HTTP Auth and validated against an external web service.

Luckily for us, like a great many other things, this is very easy to implement with Ruby on Rails.

Setting up a new Rails project

If you want to work along with me, and you like Docker and VS Code, take a look at this blog post to learn about the easiest way to set up an environment for development with Ruby on Rails in a container.

If not, you can follow the official docs for installing Ruby.

Once you have your environment with Ruby ready, we can go ahead and create a new Rails project to demonstrate how to set up Basic HTTP Auth.

Creating the new project

First, install the rails gem:

$ gem install rails

Then, make sure you are located in the directory where you want to create the new project and do:

$ rails new . --minimal -O

--minimal is a new option to rails new added in version 6.1 that disables a lot of default features and gems. You can learn more about it here. -O excludes ActiveRecord from the project. We will not be using databases for this quick app so we don’t need it.

And finally, run the app:

$ bin/rails server

Open a browser and navigate to http://127.0.0.1:3000/ to see the classic Rails hello world screen:

Implementing Basic HTTP Auth

Now that we have a Rails app up and running, let’s actually add Basic HTTP auth to it.

First of all we need a page that we will secure:

$ bin/rails generate controller Pages home --no-helper

That’ll give us a “Pages” controller with a “home” action and its corresponding view.

Next, we replace the get 'pages/home' line in routes.rb with root 'pages#home'. That will make it so the root URL of our app points to the action created in the previous step.

Going back to the browser at http://127.0.0.1:3000/ you should see this now:

Now we can restrict access to this page with Basic HTTP Auth by adding this code to the “PagesController”:

 class PagesController < ApplicationController
+  before_action :authenticate_http_basic

   def home
   end

+  def authenticate_http_basic
+    return if authenticate_with_http_basic { |un, pw| do_authentication(un, pw) }
+
+    request_http_basic_authentication
+  end

+  def do_authentication(username, password)
+    username == "username" && password == "password"
+  end
 end

And that’s really all it takes. Try to navigate to http://127.0.0.1:3000/ in the browser and you’ll now encounter this:

Basic HTTP Auth in action! Hit cancel or input the wrong credentials and a “HTTP Basic: Access denied.” message will be shown; type in “username” and “password” and our beautiful homepage shows up.

Let’s now discuss the few lines of code that we added to the controller.

First is the authenticate_http_basic method which we’ve registered to the controller’s before_action callback. That means that before processing any of the controller’s actions (home being the only one), the method will be invoked and serve as a precondition for its execution.

In the method, the first thing we do is call authenticate_with_http_basic, which is how we tell Rails to authenticate the current request using Basic HTTP Auth. The block that we pass to the method is provided the username and password that the user typed in and is where we put any custom logic that we may have for validating the credentials.

authenticate_with_http_basic returns whatever the block returns. That’s why we have that return if ... guard clause as the first line of our authenticate_http_basic method. If the block returns truthy, the auth is deemed successful and the user is allowed in the page; if it returns falsy, execution continues and reaches the request_http_basic_authentication line; which prompts the authentication popup form that we saw earlier.

In our case, the custom logic that validates the credentials is very simple. It just calls a do_authentication method that checks the inputs against hardcoded values. But in the real world, this can be anything. For the client that I discussed at the beginning to this article, the requirement was to invoke an external web service to validate the provided credentials. You could also check the credentials against some database or file, etc.

Encapsulating the Basic HTTP Auth logic in a module

I also thought it’d be nice to encapsulate this in a module for easier reuse. That’s something that’s easy to accomplish thanks to Rails’ Concerns. For our little demo app, it’d look something like this:

Create a new app/controllers/concerns/http_basic_auth.rb file and add the following code:

# Provides the `authenticate_http_basic` method which can be used to
# authenticate requests using credentials provided via Basic HTTP Auth.
module HttpBasicAuth
  extend ActiveSupport::Concern

  included do
    def authenticate_http_basic
      return if authenticate_with_http_basic { |un, pw| do_authentication(un, pw) }

      request_http_basic_authentication
    end

    private

    def do_authentication(username, password)
      # TODO: Implement custom credentials validation logic.
      username == "username" && password == "password"
    end
  end
end

And in the controller that we want to restrict access to, all we need is this:

class PagesController < ApplicationController
  include HttpBasicAuth
  before_action :authenticate_http_basic

  def home
  end
end

If the entire app needs Basic HTTP Auth then adding this to the base ApplicationController might make more sense. If only some actions need to be behind the authentication, then the :only and :except modifiers can be used for finer grained control.

And that’s all for now! It may be surprising to some but sometimes even Basic HTTP Auth is necessary. For those cases, Rails has our backs.

Using Devise for Authentication in Rails Without Database Stored Accounts

2023-01-19T00:00:00+00:00

We can pretty much say that thanks to the venerable Devise gem, the authentication problem has been solved in Ruby on Rails. There are some instances however, when the requirements veer a little further away from convention and some customization needs to happen.

Such was the case of a recent project where we had to implement authentication and session management on a small web application that would serve as an API gateway into other system components. The interesting part was that there was no database to store accounts, and credentials would have to be validated against an external web service.

Luckily for us, the Devise gem is customizable enough to be able to fulfill this requirement via custom authentication strategies. With custom authentication strategies, one can implement completely bespoke authentication logic while still enjoying a lot of the features that Devise offers out of the box.

In this article, we’re going to walk through doing just that. Let’s get started.

To learn more about this capability of Devise, and how it relates to the underlying Warden concepts, here are some interesting sources:

Remote authentication with devise

Devise authentication strategies

Custom authentication methods with Devise

Warden strategies

Setting up a new Rails project

If you want to work along with me, and you like Docker and VS Code, take a look at this blog post to learn how to set up a containerized development environment for Ruby on Rails with minimal effort.

If not, you can follow the official docs for installing Ruby.

Either way, once you have your environment ready, we can go ahead and start setting up our new Rails project.

First, install the rails gem:

$ gem install rails

Then, make sure you are located in the directory where you want to create the new project and do:

$ rails new . --minimal

--minimal is an option to rails new added in version 6.1 that disables a lot of default features and gems. You can learn more about it here.

Installing Devise

Now, we need to add the Devise gem by adding this to your Gemfile:

gem "devise"

And then running the following to install it in the project:

$ bin/rails generate devise:install

Let’s also create a “home” page which we will point the app root route to. Run:

$ bin/rails generate controller Pages home --no-helper

That will create a new PagesController with a home action and its corresponding view.

Next, in the config/routes.rb file, replace the get 'pages/home' line created by the previous command with root "pages#home".

Also, like I said at the beginning, we won’t use a database for storing accounts or validating credentials. So, we can comment out this line on the Devise initializer at config/initializers/devise.rb:

Devise.setup do |config|
  # ...
  # ==> ORM configuration
  ## require 'devise/orm/active_record'
  # ...
end

Now we have a strong enough foundation to get started. Run bin/rails server and navigate to the URL that the Puma development server produced and you should see this:

Defining the User model

For Devise to work, it needs to be associated with a model class from our app that represents user accounts. Normally, this would be some ActiveRecord::Base derived class, like most conventional implementations. For us, though, this will not work because, like I said at the beginning, we don’t have a database. Neither accounts nor credentials will be stored locally, but rather in an external web service.

So what we do instead is define a class that looks enough like an ActiveRercord such that Devise can work with it. Thanks to Rails’ modularity, this is easy, as we only need to include a few modules into said class. Here’s what our User model class ends up looking like:

# app/models/user.rb
class User
  include ActiveModel::API
  include ActiveModel::Validations
  extend ActiveModel::Callbacks
  extend Devise::Models

  define_model_callbacks :validation

  attr_accessor :email, :password
end

As you can see, all we have done is include and extend various modules as well as define the validation callbacks. This will augment the class with the APIs necessary for Devise to be able to interact with it properly. We also define email and password fields which will be our credentials.

You can read more about ActiveModel::Callbacks and define_model_callbacks here.

Now that this class is available, in order to tell Devise that it needs to work with it, we add the following line to the config/routes.rb file:

 Rails.application.routes.draw do
   # ...
+  devise_for :users
 end

Implementing the custom authentication strategy

Now that Devise is hooked up, let’s finally implement the custom authentication strategy. For this we will take three steps:

Write a component that implements the authentication logic.
Write a component that implements the serialization logic.
Register the new strategy in the initializer and model class.

Let’s get started with step 1. Here’s what the class looks like:

# app/custom_auth/devise/strategies/custom_authenticatable.rb
# Based on https://gist.github.com/madtrick/3917079
module Devise
  module Strategies
    # The class needs to inherit from Devise::Strategies::Authenticatable which
    # implements most of the underlying logic for auth strategies in Devise.
    # You can read the code here:
    # https://github.com/heartcombo/devise/blob/main/lib/devise/strategies/authenticatable.rb
    class CustomAuthenticatable < Authenticatable
      # This is the method called by Warden to authenticate a user.
      # More info in https://github.com/wardencommunity/warden/wiki/Strategies#authenticate
      def authenticate!
        if credentials_valid?
          # Signals Warden that the authentication was successful.
          # Expects an instance of the model class that Devise is configured to work with.
          # This should be the user account that matches the provided credentials.
          success!(validated_user)
        else
          # Signals Warden that the authentication failed.
          fail!
        end
      end

      private

      # Returns a boolean indicating whether the provided credentials are valid.
      # This is where you can implement any bespoke logic to do so: Read a file,
      # call a service, validate a one-time-use token, etc.
      #
      # authentication_hash is provided by the base class and includes all the
      # fields included in the login form.
      def credentials_valid?
        authentication_hash[:email] == "test@email.com" && authentication_hash[:password] == "password"
      end

      def validated_user
        # mapping.to is a reference to the model class that Devise is configured
        # to use that represents user accounts. In this case, it's the User class.
        mapping.to.new(
          email: authentication_hash[:email],
          password: authentication_hash[:password]
        )
      end
    end
  end
end

Feel free to read through that code and the comments for some explanations on what each piece does. There are a few key points to go over.

First of all, the class needs to inherit from Devise::Strategies::Authenticatable. This is the base class that Devise provides for us to create custom authentication strategies. The most important method that we need to define is authenticate!. This method is invoked by the powers that be (i.e. Warden) to run the actual authentication logic. After calling it, Warden expects it to invoke either success! or fail!, depending on the authentication results, and the rest of the system will act accordingly. success! expects an instance of User being passed as an argument. This User instance represents the account that matches the given credentials.

The authenticate! method is where Devise and Warden give you the ability to fully customize how to authenticate the given credentials. I’ve chosen to implement a simple check against hardcoded values for our example here, but this can be anything. In my real world use case, I had to make a call to an external web service, but you could also check a file, validate a token with some algorithm, anything that’s possible with Ruby and Rails really.

The next step is to implement the logic to serialize and deserialize the instance of User that represents the logged-in account to and from the Rails session store. This is encapsulated in a very simple module that looks like this:

# app/custom_auth/devise/models/custom_authenticatable.rb
# Based on https://gist.github.com/madtrick/3916999
module Devise
  module Models
    module CustomAuthenticatable
      extend ActiveSupport::Concern

      module ClassMethods
        # Recreates a resource from session data.
        #
        # It takes as many params as elements in the array returned in
        # serialize_into_session.
        def serialize_from_session(email)
          new(email:)
        end

        # Returns an array with the data from the user that needs to be
        # serialized into the session.
        def serialize_into_session(user)
          [user.email]
        end
      end
    end
  end
end

And this one is very self-explanatory. There’s a serialize_into_session method that receives the User instance for the logged-in account and returns an array of the individual fields of it that we want Devise to include in the session data that persists across requests. And there’s also a serialize_from_session method that receives the fields from the serialized array as individual parameters and has to return a new User instance.

And finally, we need to register the new strategy and put it to work. We do that by adding these lines in the Devise initializer at config/initializers/devise.rb:

Devise.setup do |config|
  # ...
  config.warden do |manager|
    manager.strategies.add(:custom, Devise::Strategies::CustomAuthenticatable)
    manager.default_strategies(scope: :user).unshift(:custom)
  end

  Devise.add_module :custom_authenticatable, controller: :sessions, route: :session, strategy: :custom
  # ...
end

Here, we’ve registered our new custom authentication strategy with Warden and added it as a default. We’ve also declared a new Devise “module” (via the Devise.add_module method) that will use that strategy (as given by the strategy: parameter) and act as part of the sessions-related functionality (as given by the controller: and route: parameters). This means that, by adding this module to our User model class, Devise will render the routes necessary for session handling. Namely, sign_in and sign_out. Like this:

 $ bin/rails routes
              Prefix Verb   URI Pattern               Controller#Action
    new_user_session GET    /users/sign_in(.:format)  devise/sessions#new
        user_session POST   /users/sign_in(.:format)  devise/sessions#create
destroy_user_session DELETE /users/sign_out(.:format) devise/sessions#destroy

Now, all that’s left is adding the module to the User class at app/models/user.rb.

class User
  # ...
  devise :custom_authenticatable, authentication_keys: [:email, :password]
end

Note how we specify the authentication_keys to be email and password, the same fields that Devise::Strategies::CustomAuthenticatable uses to run the validation logic, and are defined as attributes in User. These can be anything really. The nice thing about using email and password in particular is that Devise’s default views and controllers already work with these fields, so no additional changes and configurations need to be done if we follow that convention.

With all this, we’re basically plugging some of our code right into the middle of Devise’s logic for authentication and leveraging the rest of the functionality provided by it, like automatic views and controllers and such. As we’ll see next.

Implementing session management

Now that we’ve laid out all the piping that we need, the rest of the work to add support for sessions to our little test app is actually just business as usual with Devise.

By adding the custom_authenticatable Devise module to the User class, and the devise_for :users line on the config/routes.rb file, the session management actions are already in. So all we have to do is add a few links to actually use them. Adding the following snippet on app/views/layouts/application.html.erb inside the <body> element will suffice:

<% if user_signed_in? %>
  <span>Hello <%= current_user.email %></span>
  <%= button_to "Log out", destroy_user_session_path, method: :delete %>
<% else %>
  <%= link_to "Log in", new_user_session_path %>
<% end %>

<p class="notice"><%= notice %></p>
<p class="alert"><%= alert %></p>

This should be very familiar if you’ve worked with Devise before. If not, there are more details here.

All this does is show a link to the log in page when there’s no user logged in; and a hello message along with a log out button when there is.

Run the app with bin/rails server, click the “Log in” link, and you’ll see Devise’s default log in page. Type in the hardcoded credentials from Devise::Strategies::CustomAuthenticatable and submit the form to see something like this:

We’ve just been redirected back to the root and are greeted and shown a result message courtesy of Devise.

And that’s it! We’ve developed a pretty simple custom authentication strategy for Devise that’s very straightforward. It does not use a database at all!

The important thing though, is that we can use this pattern to implement any number of more complex procedures. And we’ve done so in a way that does not lock us out of leveraging the rest of Devise’s out-of-the-box capabilities like automatic controllers and views.

Developing Rails Apps in a Dev Container with VS Code

2023-01-13T00:00:00+00:00

One of the great gifts from the advent of Docker and containers is the ability to get a good development environment up and running very quickly. Regardless of programming language or tech stack, there is probably an image in DockerHub or elsewhere that you can use to set up a container for development, either verbatim or as a basis for more complex setups.

Moreover, even if your development environment is complex, once you have containerized it, it’s easy to replicate for new team members.

VS Code, one of the most popular editors/IDEs today, with help from the Dev Containers extension, makes the task of setting up a container for software development easier than ever.

To demonstrate that, we’re going to walk through setting up such an environment for developing Ruby on Rails applications.

Setting up a Ruby Dev Container

As I alluded to before, all we need is Docker, VS Code, and the extension. Once you have those installed, we can easily create a new Docker container ready for Ruby on Rails development and have VS Code connect to it, resulting in a fully featured development environment.

Creating the configuration file

To get started, create a new directory and open it in VS Code with something like:

$ mkdir ruby-dev-container
$ cd ruby-dev-container
$ code .

Now, in VS Code, bring up the Command Palette with Ctrl + Shift + P. In it, run the “Dev Containers: Add Dev Container Configuration Files…” command. In the resulting menu, select “Show All Definitions…” option and look for Ruby.

From here on, the menu will ask you to select a version of Ruby and whether you want to include any additional features in the resulting development container. At the time of writing, 3.1 was the latest Ruby that appeared, so I selected that. Also, we don’t need any additional features, so I selected none.

There are many options here for different languages and tech stacks. For example, there’s Ruby, which we selected, but there are also ones that come out of the box with Sinatra, Rails, and even Postgres. Feel free to peruse! You can learn more about Dev Containers in the official site and on GitHub.

Anyway, after going through that menu and clicking the OK button, the extension will have produced a .devcontainer/devcontainer.json file with these contents:

{
	"name": "Ruby",
	// Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
	"image": "mcr.microsoft.com/devcontainers/ruby:0-3.1"

	// ...
}

Customizing the Dev Container

As you can see, this is a JSON file that specifies what the dev container will look like. The most important part is the image field which defines the image that the container will be running. In this case, it’s the “Ruby 3.1” image provided by the Microsoft Artifact Registry.

I like to add a few lines to this file to further configure the container. It ends up looking like this:

{
	"name": "Ruby",
	// Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
	"image": "mcr.microsoft.com/devcontainers/ruby:0-3.1",

	// Use 'forwardPorts' to make a list of ports inside the container available locally.
	"forwardPorts": [3000],

	// Configure tool-specific properties.
	"customizations": {
		// Configure properties specific to VS Code.
		"vscode": {
			// Add the IDs of extensions you want installed when the container is created.
			"extensions": [
				"rebornix.Ruby"
			]
		}
	}
}

"forwardPorts": [3000] makes the container’s port 3000 reachable from the local host machine’s browser. That means that whenever we do bin/rails server from inside the container, we will be able to navigate to the app from our browser.

The customizations section installs the Ruby VS Code extension in the container. This is surely optional but makes the development experience a little bit more fun. You can add any extensions you’d like here.

Running the Container

Now, to actually run and connect VS Code to a new container using the image and configs specified in the .devcontainer/devcontainer.json file; bring up the Command Palette again with Ctrl + Shift + P and run the “Dev Containers: Reopen in Container” command.

With that, VS Code will invoke Docker to download the image and create a new container based on it. It will also run and configure the container based on what’s specified in .devcontainer/devcontainer.json, and finally, connect to it.

When that’s done, you should be able to see the container running with docker ps.

That will take a while, but once it’s done, you’ll be able to open VS Code’s integrated terminal (with Ctrl + `), which will bring up a bash session in the container. From here, we can finally run all our usual Ruby and Rails commands to set up our project.

Feel free to explore the container’s environment. ruby -v for example will show that Ruby is ready to go in there.

Creating the new project

First, install the rails gem:

$ gem install rails

Then, create the new project:

$ rails new . --minimal

And finally, run the app:

$ bin/rails server

Open a browser and navigate to http://127.0.0.1:3000/ to see the classic Rails hello world screen:

And that’s all! I use Ruby on Rails on a daily basis, so that’s what I’ve chosen to demonstrate here. However, there are many more options of programming languages and technologies when it comes to Dev Containers. All of them share very similar setup processes.

And even if there isn’t an image optimized for development readily available in the Microsoft Artifact Registry, you can always author your own custom Dockerfile and use that for whatever use case you may have.

Updating Ruby on Rails

2023-01-12T00:00:00+00:00

Updating your app to the latest versions of the framework it was built on, and dependencies it uses, is an important part of the development process. It may seem like a waste to invest time and money into it, but it can bring as much value as a new feature.

One good thing about using a framework like Ruby on Rails is that security features are baked in. This saves development time as the developer doesn’t have to re-create the wheel for logins, permissions, authentication, etc. There are many users of the framework who work together to can catch and patch vulnerabilities. Unfortunately, this means if your app hasn’t been updated its weaknesses become more obvious. A black hat attacker has easy access to a list of past Rails vulnerabilities.

Have you ever been to a website that hasn’t been updated for a while and found that everything moves slower than you’re used to? As technology improves and functions are optimized application processing time can be reduced. Most releases come with a performance update that can help your application keep up with the best of them.

The gems your application uses also come out with updates to add new features and functionality. Usually these releases are made to work with the latest Rails versions. If you want to utilize them you’ll have to meet the minimum Rails version requirements.

Taking it step by step

When updating your Rails app, you can’t just jump to the latest version. Updating to the next major release one at a time is recommended. This allows you to fix bugs as you go rather than trying to figure out what change broke what code.

The full list of Rails releases can be found here.

Luckily you don’t have to go through each one of these releases. Releases including rc or beta (4.2.10.rc1, 6.0.0.beta1) can be skipped. Small releases can also be skipped, such as going from 6.0.0 to 6.0.1.

If you wanted to update from 4.0.0 to 7.0.4, I’d recommend this route:

4.0.0 → 4.1.0 → 4.2.0 → 5.0.0 → 5.1.0 → 5.2.0 → 6.0.0 → 6.1.0 → 7.0.0 → 7.0.4

Any of these updates can introduce bugs, but the biggest pain points will be the major version changes: 4 to 5, 5 to 6, etc.

Fixing bundle errors

After changing the Rails and Ruby versions in the Gemfile, run bundle update rails.

source 'http://rubygems.org'
ruby '2.7.0'

gem 'rails', '~> 7.0.0'

Some gems won’t be happy with the Rails update and will also need to be updated. Once this is done run bundle update rails again. If there are more errors, fix them. If it’s successful bundle install can then be run. This will ensure all the gems are properly installed.

Also make sure to start up your server and verify there’s no problems there.

No more errors — that means we’re done, right?

Well…

Manual testing

Even if your app builds correctly that doesn’t mean different parts of your app didn’t explode. Functions that worked in a previous version might have been deprecated in the newest version.

For example, I came across this error in a recent update:

The find_all_by_X function was no longer working. Thankfully Stack Overflow is there to help us understand what changes were made and how to fix them. This function was deprecated in Rails 4, so S.find_all_by_X_ID(x_ids) functions need to change to S.where(x_id: x_ids). Knowing this I was able to search the codebase for other find_all_by_ functions and change all of them.

For large Rails updates (5.2.0 → 6.0.0), a full test of the app will need to be done. All functionality and pages should be verified and fixes applied.

For smaller Rails updates (4.0.0 → 4.1.0), you can get away with a smaller test suite. You can stick to testing the big, commonly used features of the application. Of course, if you want to be thorough, a full test can also be done.

Sometimes a gem will no longer be supported by the developer and no update has been made to allow it to work with the latest version of Rails. We have two options on how to proceed:

Find a replacement gem to accomplish the same functionality. Every reference to the original gem will need to be updated and fully tested.
Fork off of the gem and add the fixes yourself. Developers tend to stick with the gems they know across multiple applications. Owning the gem can be good as this updated version can be used on multiple apps by you and others. You’ll need to update the Gemfile to point at this new repository.
```
gem 'dead_gem', git: 'https://github.com/githubUser/dead_gem'
```

Updating remaining gems

We’re in the home stretch now. Rails is now on the most recent version and everything in the app is working correctly.

The last recommended task is to update all gems to their latest versions. This will open up the gems’ latest features and make future Ruby on Rails updates easier.

Gems should be updated individually by running the command bundle update #GemName.

Rails developer job opening

2021-11-03T00:00:00+00:00

Photo by WOCinTech Chat, CC BY 2.0, cropped

We are seeking a full-time Ruby on Rails software developer based in the United States to work with us on our clients’ applications.

End Point Dev is an Internet technology consulting company based in New York City, with 50 employees serving many clients ranging from small family businesses to large corporations. The company is going strong after 26 years in business!

Even before the pandemic most of us worked remotely from home offices. We collaborate using SSH, Git, project tracking tools, Zulip chat, video conferencing, and of course email and phones.

What you will be doing:

Develop new web applications and support existing ones for our clients.
Work together with End Point Dev co-workers and our clients’ in-house staff.
Use your desktop operating system of choice: Linux, macOS, or Windows.
Enhance open source software and contribute back as opportunity arises.

You’ll need professional development experience with:

4+ years of development with Ruby on Rails
JavaScript frameworks and libraries such as Vue.js, React, Angular
Databases such as PostgreSQL, Redis, Solr, Elasticsearch, etc.
Security consciousness, such as under HIPAA for safe medical & PII data handling
Git version control
Automated testing
HTTP, REST APIs

You have these important work traits:

Strong verbal and written communication skills
An eye for detail
Tenacity in solving problems and focusing on customer needs
A feeling of ownership of your projects
Work both independently and as part of a team
A good remote work environment

For some of our clients you will need to submit to and pass a criminal background check.

What work here offers:

Collaboration with knowledgeable, friendly, helpful, and diligent co-workers around the world
Freedom from being tied to an office location
Flexible, sane work hours
Paid holidays and vacation
Health insurance subsidy and 401(k) retirement savings plan
Annual bonus opportunity

Get in touch with us:

~~Please email us an introduction to jobs@endpointdev.com to apply.~~ (This job has been filled.)

Include your location, a resume/CV, your Git repository or LinkedIn URLs, and whatever else may help us get to know you.

We look forward to hearing from you! Direct work seekers only, please—this role is not for agencies or subcontractors.

We are an equal opportunity employer and value diversity at our company. We do not discriminate on the basis of sex/gender, race, religion, color, national origin, sexual orientation, age, marital status, veteran status, or disability status.

Integrating the Estes Freight Shipping SOAP API as a Spree Shipping Calculator

2021-09-28T00:00:00+00:00

One of our clients with a Spree-based e-commerce site was interested in providing automated shipping quotes to their customers using their freight carrier Estes. After doing some research I found that Estes provided a variety of SOAP APIs and determined a method for extending Spree with custom shipping rate calculators. This presented an interesting challenge to me on several levels: most of my previous API integration experience was with REST, not SOAP APIs, and I had not previously worked on custom shipping calculators for Spree. Fortunately, the Estes SOAP API documentation and some code examples of other Spree shipping calculators were all I needed to create a successful integration of the freight shipping API for this client.

Estes API Documentation

The Estes Rate Quote Web Service API is the one that I relied on for being able to generate shipping quotes based on a combination of source address, destination address, and package weight. I found the developer documentation to be thorough and helpful, and was able to create working client code to send a request and receive a response relatively quickly. Many optional fields can be provided when making requests but I found that I only needed to use a small subset of these, as shown in the example code below.

The one aspect of the API that tripped me up a bit was their use of CN as the country code for Canada; Spree and most other codebases I have encountered use the international standard ISO 3166 country codes with CA for Canada, so I had to add a small workaround for that in my client code when requesting shipping quotes to Canadian addresses. Another limitation I encountered is that the API expected to receive only 5-digit US and 6-character Canadian postal codes, so I had to do a bit of manipulation in my shipping calculator to account for that.

Ruby SOAP Client

I researched Ruby SOAP clients and soon found Savon, the “Heavy metal SOAP client”, which proved to be very easy to integrate into my existing Rails/Spree application. I added the savon gem to my project’s Gemfile and I was quickly able to instantiate a Savon client and configure it using the WSDL provided by Estes. After that, most of the integration work involved crafting a valid XML payload for my request and then parsing the response.

Spree Shipping Calculators

The final piece of the puzzle was implementing the Savon client into a Spree shipping calculator class. This process allowed me to retrieve details about the current user’s order and then return the calculated shipping estimates within the context of the Spree checkout pages. Looking at existing shipping calculator code helped set me on the right path here; in the end, it was just a matter of defining a new class that inherited from the base Spree::ShippingCalculator class and then defining the #compute_package method expected by Spree for returning the shipping cost of a given package.

Code Example

# app/models/spree/calculator/shipping/estes_calculator.rb
module Spree::Calculator::Shipping
  # Custom freight shipping rate API integration
  class EstesCalculator < Spree::ShippingCalculator
    ESTES_API_URL = 'https://www.estes-express.com/tools/rating/ratequote/v4.0/services/RateQuoteService?wsdl'.freeze

    def self.description
      'Estes Freight'
    end

    def compute_package(package)
      country_code = package.order.ship_address.country.iso
      return 0 unless country_code.in?(['US', 'CA', 'MX'])

      client = Savon.client(
        filters: %i[user password account],
        log: true,
        log_level: :debug,
        logger: Logger.new(Rails.root.join('log', 'savon.log')),
        pretty_print_xml: true,
        wsdl: ESTES_API_URL
      )

      country_code = 'CN' if country_code == 'CA' # Estes uses CN for Canada
      postal_code = package.order.ship_address.zipcode

      postal_code =
        if country_code == 'CN'
          postal_code.delete(' ').first(6)
        else
          postal_code.first(5)
        end

      xml = <<~XML
        <soapenv:Envelope
            xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
            xmlns:rat="http://ws.estesexpress.com/ratequote"
            xmlns:rat1="http://ws.estesexpress.com/schema/2019/01/ratequote">
          <soapenv:Header>
            <rat:auth>
              <rat:user>#{ENV['ESTES_USER']}</rat:user>
              <rat:password>#{ENV['ESTES_PASSWORD']}</rat:password>
            </rat:auth>
          </soapenv:Header>
          <soapenv:Body>
            <rat1:rateRequest>
              <rat1:requestID>#{package.order.number}</rat1:requestID>
              <rat1:account>#{ENV['ESTES_ACCOUNT']}</rat1:account>
              <rat1:originPoint>
                <rat1:countryCode>US</rat1:countryCode>
                <rat1:postalCode>10001</rat1:postalCode>
              </rat1:originPoint>
              <rat1:destinationPoint>
                <rat1:countryCode>#{country_code}</rat1:countryCode>
                <rat1:postalCode>#{postal_code}</rat1:postalCode>
              </rat1:destinationPoint>
              <rat1:payor>S</rat1:payor>
              <rat1:terms>C</rat1:terms>
              <rat1:baseCommodities>
                <rat1:commodity>
                  <rat1:class>50</rat1:class>
                  <rat1:weight>#{package_weight(package)}</rat1:weight>
                </rat1:commodity>
              </rat1:baseCommodities>
            </rat1:rateRequest>
          </soapenv:Body>
        </soapenv:Envelope>
      XML

      response = client.call(:get_quote, xml: xml)
      quotes = response.body.dig(:rate_quote, :quote_info, :quote)

      if quotes.is_a?(Array)
        quotes.first.dig(:pricing, :total_price).to_f
      elsif quotes.is_a?(Hash)
        quotes.dig(:pricing, :total_price).to_f
      else
        0
      end
    rescue Savon::Error
      # Record shipping rate as 0 if an API error is caught, 0 amount will indicate need to show user an error message on the shipping rate page
      0
    end

    private

    def package_weight(package)
      weight = package.contents.sum { |content| content.line_item.weight }

      if weight < 5 # enforce minimum package weight
        5
      else
        weight.round
      end
    end
  end
end

Conclusion

I was pleased that I was able to quickly build a custom shipping calculator in Spree that used the Estes Rate Quote API to provide accurate shipping estimates for large freight packages. The high quality documentation of the Estes API and the Savon SOAP Client gem made for a pleasant development experience, and the client was happy to gain the new functionality for their Spree store.

Enumerated Types in Rails and PostgreSQL

2021-04-29T00:00:00+00:00

Photo by Jared Tarbell, used under CC BY 2.0, cropped from original.

Enumerated types are a useful programming tool when dealing with variables that have a predefined, limited set of potential values. An example of an enumerated type from Wikipedia is “the four suits in a deck of playing cards may be four enumerators named Club, Diamond, Heart, and Spade, belonging to an enumerated type named suit”.

I use enumerated types in my Rails applications most often for model attributes like “status” or “category”. Rails’ implementation of enumerated types in ActiveRecord::Enum provides a way to define sets of enumerated types and automatically makes some convenient methods available on models for working with enumerated attributes. The simple syntax does belie some potential pitfalls when it comes to longer-term maintenance of applications, however, and as I’ll describe later in this post, I would caution against using this basic 1-line syntax in most cases:

enum status: [:active, :archived]

The Rails implementation of enumerated types maps values to integers in database rows by default. This can be surprising the first time it is encountered, as a Rails developer looking to store status values like “active” or “archived” would typically create a string-based column. Instead, Rails looks for an numeric type column and stores the index of the selected enumerated value (0 for active, 1 for archived, etc.).

This exposes one of the first potential drawbacks of this minimalist enumerated type implementation: the stored integer values can be difficult to interpret outside the context of the Rails application. Although querying records in a Rails console will map the integer values back to their enumerated equivalents, other database clients are simply going to return the mapped integer values instead, leaving it up to the developer to look up what those 0 or 1 values are supposed to represent.

A larger problem that arises from defining an enum as an array of values is that the values are tied to the order of elements in an array. This means any change to the order or length of the array can have unwanted consequences on the mapped values.

# don't do this; the index of active is changed from 0 to 1, archived from 1 to 2
enum status: [:abandoned, :active, :archived]

At a minimum, I would recommend using this hash-based syntax for defining enumerated types with explicit integer mapping:

enum status: {
  active: 0,
  archived: 1
}

This provides the benefit of documenting which integers are mapped to which enumerated values, and also provides more flexibility for future adjustments. For example, a new status value can now be added to the enumerated type without disrupting any of the existing records:

enum status: {
  abandoned: 2,
  active: 0,
  archived: 1
}

For Rails applications with PostgreSQL databases, it’s possible to go one step further and get most of the best of both worlds: the efficiency of using predefined enumerated types while still maintaining the ability to store meaningful string values at the database level. This is made possible by combining Rails enums with PostgreSQL Enumerated Types.

This technique requires using a migration to first define a new enumerated type in the database, and then creating a column in the model’s table to use that PostgreSQL type:

class AddEnumeratedStatusToDevices < ActiveRecord::Migration[5.2]
  def up
    execute <<-SQL
      CREATE TYPE device_status AS ENUM ('abandoned', 'active', 'archived');
    SQL

    add_column :devices, :status, :device_status
    add_index :devices, :status
  end

  def down
    remove_index :devices, :status
    remove_column :devices, :status

    execute <<-SQL
      DROP TYPE device_status;
    SQL
  end
end

The corresponding model code to use this new enumerated type looks similar to before, but now the values are mapped to strings:

class Device < ApplicationRecord
  enum status: {
    abandoned: "abandoned",
    active: "active",
    archived: "archived"
  }
end

This combination of Rails and PostgreSQL enumerated types has become my preferred approach in most situations. One limitation to be aware of with this approach is that PostgreSQL enumerated types can be extended with ALTER TYPE, but existing values cannot be removed. There is a small bit of additional development overhead introduced with the need to manage the enumerated type at both the Rails and the PostgreSQL level, but I like having the option of querying records by the string values of attributes, and the use of a PostgreSQL enumerated type provides for more efficient database storage than simply using a string type column.

Job opening: Ruby on Rails & Vue.js developer

2021-02-24T00:00:00+00:00

Photo by WOCinTech Chat, CC BY 2.0, cropped

We are seeking a full-time software engineer specializing in Ruby on Rails and Vue.js to work with us on our clients’ applications.

End Point is an Internet technology consulting company based in New York City, founded 25 years ago! We have over 50 employees serving many clients ranging from small family businesses to large corporations.

Even before the pandemic most of us worked remotely from home offices. We collaborate using SSH, Git, project tracking tools, Zulip chat, video conferencing, and of course email and phones.

What you will be doing:

Develop new web applications and support existing ones for our clients
Consult with clients on software features and plans
Work together with End Point co-workers and our clients’ in-house staff
Use open source tools and contribute back as opportunity arises

What you bring:

Professional experience developing and supporting web applications in these technical areas:

3+ years of development with Ruby on Rails and front-end JavaScript
Frameworks and libraries such as Vue.js, React, Angular
Databases such as PostgreSQL, MySQL, Redis, Solr, Elasticsearch, etc.
Security consciousness
Git version control
Automated testing
HTTP, REST APIs

These work traits are just as important:

Strong verbal and written communication skills
An eye for detail
Tenacity in solving problems and focusing on customer needs
A feeling of ownership of your projects
Work both independently and as part of a team
Ability to pass a criminal background check when clients require
A good remote work environment and self-discipline

What work here offers:

Collaborate with knowledgeable, friendly, helpful, and diligent co-workers around the world
Flexible, sane work hours
Paid holidays and vacation
Annual bonus opportunity
Freedom from being tied to an office location
Use your desktop OS of choice: Linux, macOS, Windows
For U.S. employees: health insurance subsidy and 401(k) retirement savings plan

Get in touch with us:

~~Please email us an introduction to jobs@endpointdev.com to apply.~~ (This job has been filled.) Include your location, a resume/CV, your Git repository or LinkedIn URLs, and whatever else may help us get to know you.

We look forward to hearing from you! Direct work seekers only, please—this role is not for agencies or subcontractors.

Availity: An API for Health Insurance

2020-11-16T00:00:00+00:00

Photo by Sergio Santos, used under CC BY 2.0, cropped from original.

I have been working on a tele-therapy application for a client in the health care industry over the past few months and had the opportunity to do some interesting work in the area of health insurance coverages and claims.

I was tasked with creating an integration of the Availity API for insurance coverages which provides the ability to make requests for details about a patient’s health insurance coverage and returns responses containing information like the patient’s primary care doctor, their copay amounts, and their deductibles.

The ability to query this health insurance information from an API in an automated fashion helps streamline the process of billing clients by validating their health insurance details and also determining what a patient’s financial responsibility will be for their online therapy sessions. Availity provides information for over 11,000 insurance companies; a full list of supported payers is available on their site via a web interface and a downloadable CSV file.

Availity provides both REST and SOAP APIs in addition to a batch processing system that functions over SFTP. For the purposes of this article I will be focusing on the REST API which was the primary focus of my work for this project.

The developer documentation for the REST API was mostly self-serve; after signing up for an account on the Availity site I was able to rely on their publicly available documentation for all of the API details that I needed to start making requests.

Unfortunately, the development process for integrating the SOAP API was not nearly as smooth; the SOAP APIs link on Availity’s main developer portal page currently comes up blank, and I had to register a separate account in order to create a support request to obtain documentation on the SOAP API. Even with that documentation in hand, I found it difficult to determine things like the correct WSDL to use, and the process for generating X12 strings was much more complicated than making a more traditional REST request with a parameter hash. The large majority of payers supported by Availity are covered by the REST API, but there are some that are only supported by SOAP API requests and necessitate this more difficult process.

The application we were developing featured a Rails backend, so I used the Ruby rest-client gem when making requests to the Availity REST API.

The request payload was surprisingly small. Most payers only require this combination of patient/provider details when making a request:

Patient birth date
Payer ID (Assigned by Availity to the health insurance company in the payer list linked above)
Member ID (The patient’s membership ID with their insurer)
Provider NPI
Service type

Here is an excerpt of the API client code I created for making requests to the API:

module Availity
  class Client
    extend Limiter::Mixin

    # Rate limit API requests to 100 per second
    # https://developer.availity.com/partner/node/503
    limit_method :coverages, rate: 100, interval: 1

    BASE_URL = 'https://api.availity.com/availity/v1'

    # ...

    def coverages(payer_id:, member_id:, patient_birth_date:, patient_first_name:, patient_last_name:)
      url = "#{BASE_URL}/coverages"

      params = {
        payerID: payer_id,
        memberId: member_id,
        providerNpi: '123456789',
        patientBirthDate: patient_birth_date,
        patientFirstName: patient_first_name,
        patientLastName: patient_last_name,
        serviceType: '30'
      }

      headers = {
        Authorization: "Bearer #{token}",
        params: params
      }

      RestClient::Request.execute(
        method: :get,
        url: url,
        headers: headers,
        log: @log
      )
    end
  end
end

The insurance coverage API then returns a link to a fairly long JSON response with a variety of information on the patient’s health insurance plan. I added an additional class to parse that response for specific details such as name of primary care doctor, total and remaining deductibles for the year, copay amounts, etc.

In addition to this insurance coverage API, Availity provides various other API end points related to health care claims and costs that could be equally valuable to the development of applications in the health care industry.

COVID-19 Support for the Kansas Department of Health and Environment

2020-09-14T00:00:00+00:00

Kansas’s existing EpiTrax system

End Point has worked on Kansas’s disease surveillance systems since 2011. In 2018 we migrated them from their legacy TriSano application to the open source EpiTrax surveillance system created by Utah’s Department of Health. The new EpiTrax system had been in full production for about eight months when COVID-19 cases started to grow in the United States.

COVID-19: Help needed

In March 2020, the Director of Surveillance Systems at the Kansas Department of Health and Environment (KDHE) asked us at End Point to create a web-based portal where labs, hospitals, and ad-hoc testing locations could enter COVID-19 test data. While systems existed for gathering data from labs and hospitals, they needed a way to quickly gather data from the many new and atypical sites collecting COVID-19 test information.

Our approach

Since the portal was intended for people who were unfamiliar with the existing EpiTrax application, we were able to create a new design that was simple and direct, unconstrained by other applications. It required a self-registration function so users could access the system quickly and without administrative overhead, and users needed to understand how to use it without extensive training.

We at End Point agreed to create the portal and dashboard for test results reporters immediately, while planning for later development of additional administrative functions. We used Ruby on Rails and Vue.js to build the portal due to their usefulness for rapid development. The Vue.js front-end JavaScript framework allowed us to quickly put together the portal UI and integrate it with the Rails back-end web services.

Once approved, our team got to work setting up the environment, developing the portal application, and rigorously testing it.

Here are some screenshots of the application:

Portal home page

User registration page

Dashboard

Reporters’ entry screens

The portal was launched on April 30.

Contact tracers support

After the EpiTrax portal for COVID-19 was up and running, Kansas made urgent plans to hire 400 contact tracers. We updated the EpiTrax portal to accommodate this new type of user, showing contact tracers only the data they are authorized to view, while providing them the ability to make limited contact record updates and to create tasks. The project is ongoing, and eventually will be used for all diseases.

EpiTrax for Missouri

Late this Spring, after learning of Kansas’s use of the EpiTrax platform and the powerful capabilities that it provides to the Kansas public health system, the State of Missouri reached out to us at End Point to request their own EpiTrax implementation. End Point and Missouri quickly came to agreement, and since July we have been working together build out a full production EpiTrax surveillance system for them.

Contact us!

To discuss an EpiTrax project, contact us. Our expert team is ready to help you meet your requirements.

Shopify Admin API: Importing Products in Bulk

2020-05-04T00:00:00+00:00

Photo by Chris Young, used under CC BY-SA 2.0, cropped from original.

I recently worked on an interesting project for a store owner who was facing a daunting task: he had an inventory of hundreds of thousands of Magic: The Gathering (MTG) cards that he wanted to sell online through his Shopify store. The logistics of tracking down artwork and current market pricing for each card made it impossible to do manually.

My solution was to create a custom Rails application that retrieves inventory data from a combination of APIs and then automatically creates products for each card in Shopify. The resulting project turned what would have been a months- or years-long task into a bulk upload that only took a few hours to complete and allowed the store owner to immediately start selling his inventory online. The online store launch turned out to be even more important than initially expected due to current closures of physical stores.

Application Requirements

The main requirements for the Rails application were:

Retrieving product data for MTG cards by merging results from a combination of sources/APIs
Mapping card attributes and metadata into the format expected by the Shopify Admin API for creating Product records
Performing a bulk push of products to Shopify

There were some additional considerations like staying within rate limits for both the inventory data and Shopify APIs, but I will address those further in a follow-up post.

Retrieving Card Artwork and Pricing

I ended up using a combination of two APIs to retrieve MTG card data: MTGJSON for card details like the name of the card and the set it belonged to, and Scryfall for retrieving card images and current market pricing. It was relatively easy to combine the two because MTGJSON provided Scryfall IDs for all of its records, allowing me to merge results from the two APIs together.

Working With the Shopify Admin API in Ruby

The Shopify Admin API deals in terms of generic Product records with predefined attributes like title and product_type. The official shopify_api Ruby gem made it very easy to connect to my client’s Shopify store and create new products by creating Shopify::Product objects with a hash of attributes like so:

  attrs = {
    images: [{ src: scryfall_card.image_uris.large }],
    options: [
      {
        name: 'Card Type'
      },
      {
        name: 'Condition'
      }
    ],
    product_type: 'MTG Singles',
    tags: card.setCode,
    title: card.name,
    variants: [
      {
        inventory_management: 'shopify',
        inventory_quantity: 1,
        option1: 'Foil',
        option2: 'Like New',
        price: scryfall_card.prices.usd_foil
      }
    ]
  }

  Shopify::Product.new(attrs).save

The actual production code is a bit more complicated to account for outliers like cards with multiple “faces” and cards that come in both regular and foil variants, but the example above shows the basic shape of the attributes expected by the Shopify API.

Pushing 50,000 Products to Shopify

After I completed testing with individual products and confirmed the ability to take a specific card and turn it into a Shopify product with artwork and pricing pre-populated it was time to perform the full upload of all 50,000+ cards in the MTGJSON database. I decided to use Sidekiq and create jobs for each card upload so that I could rate limit the workers to stay within rate limits for both the Scryfall and Shopify APIs, and also have persistence that would allow me to pause/resume the queue or retry individual failed jobs.

The Sidekiq approach to queueing up all of the card uploads worked great; I was able to use the Sidekiq dashboard to monitor the queue of 50,000 jobs as it worked its way through each card, and was able to see the Shopify products being created on the store in real time. Once the inventory was in place in Shopify the store owner was able to start updating his inventory levels and make cards available for sale via the Shopify Admin.

Conclusion

A custom Ruby application using the Shopify API is a powerful solution for online storefronts that need to retrieve a large number of inventory data from external sources. I was pleased with how this project turned out; it was rewarding to create a custom application that leveraged several APIs and automated a task that would have been extremely repetitive, and probably impossibly time-consuming, to do manually. It was encouraging to do my first upload of a card and see it show up on the Shopify store with artwork, pricing, and card details pre-populated.

The development model used for this project could be applied to stores in a wide variety of markets. This project used external APIs to retrieve product information but that data source could easily be replaced with a spreadsheet, CSV file, or some other export file containing bulk information on products to be sold.

Capturing Outgoing Email With Mock SMTP Servers

2020-03-13T00:00:00+00:00

Photo by Seattleye, used under CC BY 2.0, cropped from original.

Sending automated email to users is a common requirement of most web applications and can take the form of things like password reset emails or order confirmation invoices.

It is important for developers working in development/staging environments to verify that an application is sending email correctly without actually delivering messages to users’ inboxes. If you were testing a background task that searches an e-commerce site for abandoned shopping carts and emails users to remind them that they have not completed a checkout, you would not want to run that in development and end up repeatedly emailing live user email addresses.

A mock SMTP server is useful for development and testing because it lets you configure the email settings of your development environment almost exactly the same as you would for outgoing SMTP email in your production site. The mock SMTP server will capture all of the outbound email and allow you to review it in a web interface instead of actually delivering it to users’ inboxes.

Mock SMTP Servers

There are a variety of standalone/free and hosted/commercial options for mock SMTP servers including:

MailHog (free)
MailSlurper (free)
MailCatcher (free)
Mailtrap (free for small solo projects/paid)
Mailosaur (paid)

The standalone/free options have been sufficient for the projects I have worked on. Some of the features offered by the hosted solutions like Mailtrap and Mailosaur may be appealing to larger development teams.

MailHog is my go-to mock SMTP server because it has a nice web interface and is extremely easy to install and configure for typical use. The standalone solutions that I have tried all work similarly; they listen for SMTP email on one port, and provide a web interface on a separate port for reviewing captured email.

Configuring a Rails Application to use MailHog

Installation and use of MailHog is very simple: download and run the mailhog executable to have it start listening for SMTP email on port 1025 and hosting a web interface on port 8025. Then edit the Rails development environment config file to send email using an SMTP server running on local port 1025:

# config/environments/development.rb
Rails.application.configure do
# …
  config.action_mailer.delivery_method = :smtp
  config.action_mailer.perform_deliveries = true
  config.action_mailer.smtp_settings = { address: 'localhost', port: 1025 }
# …
end

MailHog runs in the foreground and will display output as it receives outbound email. Opening a web browser to http://localhost:8025 shows MailHog’s web interface and allows you to view a list of the email that it has captured or click on an email to show its full details:

Conclusion

I have found MailHog to be helpful when developing a variety of different web applications, particularly ones that generate email for user notifications and confirmations. Thanks to its ease of installation and use, I would recommend it (or an equivalent mock SMTP solution) to any developer that needs to test outgoing email features in their web applications.

Rails Exception Notification and Logging

2019-10-31T00:00:00+00:00

Photo by Randen Pederson, used under CC BY-SA 2.0, cropped from original.

Exception handling is an important component of any Rails application that is intended to be deployed in a production environment.

If you have ever felt your heart sink because you received a screenshot of your Rails application with this dreaded “something went wrong” message from a customer or client, you know what I’m talking about:

Though developers strive to deploy projects that are free of bugs and never throw an exception, the reality is that people using your Rails applications do sometimes encounter errors. When that happens it’s better to have your application automatically notify you of the event, rather than finding out about it for the first time when someone calls or emails you.

Exception Notification

The Exception Notification gem is a stalwart of the Ruby/Rails ecosystem and the standard solution for configuring your Rails project to notify you when errors occur. I typically use the gem to deliver notifications to a development/hosting team via email, but it has a variety of built-in notifiers that can output to just about any location you would want: Slack, IRC, Amazon SNS, etc., plus an option to write custom webhooks for other services that are not supported by default.

Exception Notification is simple to install and configure, particularly for Rails applications where it can be installed as a Rails engine and configured via an initializer. The default config/initializers/exception_notification.rb initializer generated by the gem comes with an example of an email notifier:

# Email notifier sends notifications by email.
config.add_notifier :email, {
  email_prefix: '[ERROR] ',
  sender_address: %{"Notifier" <notifier@example.com>},
  exception_recipients: %w{exceptions@example.com}
}

along with examples of other configuration options for conditions to determine which errors should generate notifications and some examples of other notification providers.

Starting with just an email notifier might be enough for your needs, but it’s worth reading through the Exception Notification documentation to find out what other capabilities it has, including options for rate-limiting to prevent your inbox from being inundated by recurring errors.

ExceptionTrack

A related Rails-specific gem called ExceptionTrack adds another layer of exception tracking on top of Exception Notifier; it provides a mechanism for storing exceptions in your Rails application’s database, and provides a web interface (mounted as an engine inside your application) for reviewing them.

I tend to use a combination of ExceptionTrack and Exception Notifier in my projects, using ExceptionTrack and Exception Notifier in production environments but not configuring any Exception Notifier deliveries in development. It is easy to configure the gems differently in development and production thanks to Rails’ separate environment config files.

Generating database migration and config files with rails g exception_track:install will create the following initializer:

# config/initializers/exception-track.rb

# require 'exception_notification/sidekiq'

ExceptionTrack.configure do
  # environments for store Exception log in to database.
  # default: [:development, :production]
  # self.environments = %i(development production)
end

# ExceptionNotification.configure do |config|
#   config.ignored_exceptions += %w(ActionView::TemplateError
#                                   ActionController::InvalidAuthenticityToken
#                                   ActionController::BadRequest
#                                   ActionView::MissingTemplate
#                                   ActionController::UrlGenerationError
#                                   ActionController::UnknownFormat)
# end

ExceptionTrack’s configuration options are limited to mostly specifying which environments you want it to store exceptions for; by default it is enabled for both development and production.

After that it’s just a matter of running the database migration to create a table for storing ExceptionTrack’s data and then adding a new route to mount the web interface in your application, with something like:

# config/routes.rb

# ...
  mount ExceptionTrack::Engine => '/exceptions' if Rails.env.development?
# ...

If you want to make ExceptionTrack’s web interface available in production, it is advisable to protect the route behind authentication so that only users with admin-level access can view it. The Sidekiq gem’s documentation has some examples for protecting access to routes based on different authentication systems that can be easily adapted to work with ExceptionTrack’s routing.

Conclusion

Access to easily-installable tools for tracking and logging exceptions is a nice benefit for Rails developers, and Exception Notification / ExceptionTrack make a powerful combination for anyone interested in a self-serve solution that includes logging and the ability to send notifications to a wide variety of services.

Larger organizations and projects may benefit from a hosted service like Airbrake for error monitoring, but the solutions provided here can work well for many Ruby/Rails projects without the added expense of a managed third-party service.

Project On-ramping: Infrastructure and Codebase

2019-10-21T00:00:00+00:00

Photo by NASA via Unsplash

Living in the consulting world, we often jump into codebases and environments to get quickly up to speed to provide estimates or start fixing bugs right away. Here are some important landmarks I visit along my way to get up to speed on a new project.

Dev stack

First up, I learn as much as I can about the dev stack a codebase runs on. It used to be the case that LAMP (Linux, Apache, MySQL, PHP) was a pretty common setup in our world, but the number of dev tools and variety in stacks has expanded greatly over time. Many of my End Point clients are now running nginx on Linux, with Ruby on Rails and MySQL or PostgreSQL, but as a company we have both breadth and depth in web stack technologies (hover over the Expertise dropdown above).

Layered on top of the base infrastructure might be a JavaScript framework (e.g. React, Ember.js), and other abstractions to improve the dev process (e.g. Sass, Node.js). And layered on top of that further is the possibility of other services running on the server locally (e.g. search using Elasticsearch or Solr) and 3rd-party tools running on a server elsewhere (e.g. content delivery networks, monitoring, Stripe).

The web stack and 3rd-party tools can be so complex these days that there is a lot of ground to cover before jumping into the code.

Personnel infrastructure

Next up, I like to understand how our client works with the website and more about their limitations (time, technical, other). Especially in the consulting space where we are supporting existing developers, I think it’s important to exercise empathy over how they’ve gotten to the point they are at, and why they’ve reached out for additional development resources.

Does the client want a solution that enables them to make their own changes moving forward, i.e., a content management solution? Do they want to hand the project off entirely due to time limitations? Is there a hybrid solution that will enable them to make changes and defer to us as a resource for bigger decisions? Is the existing development staff who we should be best supporting and advising on decisions?

Are there dev instances?

After we have a high-level understanding of the dev stack and personnel involved, the next bridge we cross is to determine dev instance architecture (and how to get access to a dev instance!). It goes without saying (though I’m saying it anyways) that it’s a much lower risk to experiment and play around on a dev instance rather than a production server.

Here at End Point, we have our own in-house tool for spinning up dev instances (DevCamps), and we also work with clients who have their own setup for dev environments (e.g. Docker, AWS) that we can jump into.

Codebase: Where do I go?

I like to equate learning a new code base to moving to a new city. When you first arrive, you don’t know what you are looking at or where to go, but as you begin to make frequent trips to one location or another, you become familiar with those paths and you become most familiar with the paths that you take most often.

One of my first stops is the database. I review the tables and understand how the application models interface with them, as well as how they reference each other. Another stop (in the Rails world) is to visit config/routes.rb, which maps URLs and dispatches them to a Rails controller. This immediately informs me of the complexity of the application by the number of different URL requests it handles.

A third favorite stop upon gaining access to the codebase is the code history (hopefully there is one!), which can be telling about the organization as well as frequent code destinations visited.

Another place to visit is the (again, in the Rails space) Bundler Gemfile, which tells me how many (or how few) dependencies are included in a project.

While I don’t think it’s important to get into the nitty gritty of Rails models, controllers, or views at a first pass, my observations of the database, routing, Git history, and Gemfile can paint a picture of the complexity and dependencies of one project. Outside of the Rails space, many modern web frameworks have comparable code paradigm that I think are similarly revealing.

Digging deeper

From there, I look to client priorities for where to dig deeper into the code. I have found that in some cases in my consulting experience, the client priorities and convention use in codebase (e.g. with Ruby on Rails) overlaps nicely with my skill set and I’m able to jump right in to make changes, but other client work requires further research into third parties or historical context of the code and changes needed.

Campendium: A Responsive, Fancy Detail Page

2019-09-09T00:00:00+00:00

This week, I was very excited to deploy a project for Campendium, one of our long-time clients. As noted in my recent post on Campendium updates for the year, Campendium has thousands of listings of places to camp and provides a great infrastructure for the development of a rich community of travelers around North America.

For the past few months, I’ve been working on a significant update to Campendium’s campground detail page, the page template where in-depth information is provided for each of Campendium’s locations. This is equivalent to a product detail page on an ecommerce site.

The “guts” of the update included a new detail page design with expanded responsiveness, the introduction of 360° videos, and expanded user driven content in the form of Question & Answer (Q&A or QnA), reviews, notes, nightly rates, etc. Read on to find out more and see video examples of several of the features!

User Interface & Responsiveness Updates

One of the things the Campendium team and I are most proud of here is the responsiveness of the new design. In the case of traveling and camping, responsiveness is important since a large amount of traffic comes from mobile devices, relative to what you might see in other industries.

User images are shown as “hero images” and the user interface updates depending on the browser device and width, as shown in the following videos for Gilbert Ray Campground and Cayuga Lake State Park.

A preview of responsive behavior on the campground detail page with user submitted photos.

A second preview of responsive behavior on the campground detail page with embedded maps.

Another updated design usability tweak was a sticky navigation bar to navigation throughout the page, which can get especially long with user submitted content. See how the “Overview”, “Video”, etc. links become sticky as you scroll down on the page, and the current region coming into view of the page is underlined:

Navigation becomes fixed to the top of the browser as a user scrolls through the content.

Campendium uses Ruby on Rails as a backend, a bit of Bootstrap, and Sass and best practice responsive design is used throughout this updated user interface.

360° Videos

The Campendium team has been hard at work creating 360 degree videos of the various locations to provide significant value to their users. These videos are now embedded into the campground detail page. Video hosting is provided by YouTube and dropped into the Campendium campground HTML template.

A video in a video—a 360 degree video example.

I personally think these 360° videos are awesome, especially to those visual learners out there! You can learn so much from a video that can be hard to capture in user reviews.

Community Q&A

Another new feature with this deploy is the introduction of community driven Question & Answer. Users can submit questions about a campground, and users who have contributed to this campground are invited to respond (or they can opt-out site-wide to responding to questions). In addition to Q&A itself, user content can be “upvoted” (marked as Helpful) or flagged for an improved user content browsing experience.

All Q&A functionality is driven by JavaScript coupled with the Ruby on Rails backend.

Expansion of User Contributed Content and Features

Finally, this update includes expansion of user contributed content in addition to Q&A. This includes the ability for users to contribute notes, cell signal reports, and nightly rates. Reviews can now be filtered by user profile information and sorted by date or specific ranking. Reviews can also be searched by keywords and those keywords highlighted in the results. The following video demonstrates sorting and searching of reviews with highlighted keyword match:

Review searchability with highlighting and filterability.

All search functionality driven by JavaScript on the frontend, and a Ruby on Rails backend coupled with Sunspot and Solr.

Who Doesn’t Love Stats?

Just for the sake of sharing stats, from GitHub, this update included:

215 changed files
6,284 additions
3,924 deletions (removal / cleanup of unneeded JavaScript files)

Campendium v2019: A Summary of Recent Updates

2019-08-05T00:00:00+00:00

This year has brought a handful of exciting changes for Campendium, one of End Point’s long-time clients, by yours truly. Created by campers for campers, Campendium has thousands of listings of places to camp, from swanky RV parks to free remote destinations, vetted by a team of full-time travelers and reviewed by over 200,000 members. I thought I would take some time to summarize these recent updates.

Maps and Clustering

Campendium uses Mapbox for map rendering to display campgrounds and locations throughout North America. One of the new features added this year was clustering of campground locations, where campgrounds are grouped together and presented in a “cluster” with a size relative to how many campgrounds are in the cluster.

If a user is searching for campgrounds in a broad location, they can see where campgrounds might be more densely grouped by location. Once a user zooms in zoom in a couple of clicks, the campgrounds are no longer clustered and individual campgrounds locations can be seen. While working on this update, we spent a good amount of our time tweaking and troubleshooting the optimal clustering behavior to provide the most benefit to those searching for a campground. Mapbox GL JS works in parallel with ReactJS, and runs with a Ruby on Rails back-end.

Advanced Filtering

Another exciting was the introduction of advanced filtering in the search interface, presented in combination with map display. Users can filter campgrounds by category (e.g. Public Land, RV Parking, Parking, Dump Station), filter by price (with a slider), hookups, campground policy (e.g. age or pet restrictions), discounts, recreation, and facilities. All of this search filtering is driven by Sunspot, a Ruby on Rails gem for working with the popular Solr search engine. Results can be sorted by user provided reviews, price or distance from a specific GPS location. Here, much care was given to provide the best user interface for presenting this valuable functionality.

“Supporters Only” Features

Another recent update to Campendium includes functionality to offer user subscriptions. Registered users can sign up to support Campendium on a monthly or annual basis, and subscriptions are set to auto-renew at the end of their subscription period. This paid support hides advertisements throughout the site (advertisements are controlled by a third party), and advanced filtering on cell reception. There are plans to expand supporter features in the future. Ruby on Rails combined with StripeJS is used to manage subscription payments, and Ruby on Rails also serves as a backend for In-App Purchases of subscriptions from the App store.

Always Responsive and Latency-Aware

Because a large portion of the Campendium visitors are on the road, it’s important to have both a responsive design and to build for bandwidth limitations for users. Throughout the development of these new features, responsive and mobile friendly designs were implemented leveraging Sass, sometimes requiring help from the rest of the knowledgeable End Point team!

Many of the pages throughout the site are fully cached including the homepage, search result pages, and campground detail page, and cookies are used to indicate user status. In some cases, user submitted campground images are lazy-loaded to mitigate bandwidth limitations.

What’s Next?

While I didn’t go into much technical depth on these updates, I am happy that the updates represent a broad spectrum of full-stack development skills featuring nginx, Ruby on Rails, 3rd party integration including StripeJS, MapboxGL and IAP (Apple), a JavaScript framework with ReactJS, and working with Ruby gems to leverage other tools, for example, Solr (Sunspot) and Sass.

In the future, Campendium plans to continue using these tools to see a more interactive, social campground detail page, and has plans to expand outside of North America. You can visit Campendium here, or find them on Instagram here to follow their exciting announcements!

Building a web app using Rails 8 and Vue 3 with Vite

The development environment

Creating a new Rails 8 project

Setting up Vite

Installing Vue

Running Ruby in Podman (When rbenv install Fails on Apple Silicon)

First try: native rbenv

Second try: mise

Third try: Podman

Containerfile

container-compose.yml

Minimal unicorn.rb configuration file

Simple config.ru

Quick and Dirty Admin Pages with Rails scaffold_controller

What Is scaffold_controller and Why Use It?

Let’s Build an Admin Interface for a Product Model

Step 1: Create the Admin Namespace and Route

Step 2: Generate the Scaffold Controller

Step 3: Update the Generated Controller

Step 4: Add a Link and Access Control

When Should You Use This Method?

Conclusion

Using ActiveSupport::​ExecutionContext to improve Rails logging

The Problem: A Tangled Web of Logs

How ExecutionContext Works

A Practical Example: Tracing an Order

Making the Context Visible in Logs

Going Beyond: Tagging Database Queries

A Stitch in Time Saves Nine

Building Offline-Capable Rails Apps Using Service Workers and Turbo

Why Offline Support Matters

Creating a Manifest File

Creating the Service Worker

Registering the Service Worker in Your Rails App

Pre-Caching Essential Pages

Handling Offline Turbo Form Submissions

Adding an Offline Fallback Page

Summary

Integrating Grape with Sidekiq for Asynchronous Processing in Rails

Why asynchronous processing matters

Setting up Grape and Sidekiq

Creating a Sidekiq worker

Triggering a background job from a Grape endpoint

Running Sidekiq

Error handling and retries

Conclusion

Rebuilding a Modern App in Rails 7 Without JavaScript Frameworks

Why Consider a Framework-Free Approach in 2025?

The Application: A Simplified Project Management Tool

Advantages of Using Rails 7 with Hotwire and Turbo

Challenges Encountered

Successes Achieved

Comparison to the Previous React-Based Build

Final Thoughts

Migrating Rails 6 React to Rails 7 React

Steps for migrating Rails 6 React to Rails 7 React

1. Update the Rails Gem in the Gemfile

2. Upgrade Rails packages

3. Run the Rails update task

4. Remove Webpacker

5. Setting up Webpack

6. Update Rails asset tags

7. Start the dev server

I wrote the same app twice, with Hotwire and Blazor Server — here’s what I learned

What this article is

An overview of Blazor

How Blazor works under the hood

An abstraction over the request/response cycle

How Blazor supports common frontend framework features

Handling DOM events

Including other Blazor components

Passing parameters to components

Defining, handling and triggering custom component events

Handling component lifecycle events

Templates

Routing

State management

Interoperability with JavaScript

An overview of Hotwire

Partial page updates with Turbo Frames

`Containerfile`

`container-compose.yml`

Minimal `unicorn.rb` configuration file

Simple `config.ru`

Using ActiveSupport::ExecutionContext to improve Rails logging