mentalized.net

Announcing Flowbite Components for Rails

Sat, 21 Feb 2026 00:00:00 +0000

We‘re open sourcing our Flowbite component library, a set of view components, we’re using in Front Lobby, Skrift, and a bunch of other projects, both internal and external.

These days there’s no shortage of UI kits for Rails. It seems everybody is building their own design system and selling a component library on top of it. We aren’t that ambitious; we just want a gem we can include in all our projects and be off to the races, preferably open source so we don’t have to bother with private gems.

Enter flowbite-components: UI components for your Rails application, built on ViewComponent, Tailwind, and Flowbite, licensed under an MIT license, and ready to use today.

Forms

A major driver for building flowbite-components was input fields.

A complete input field isn’t just the input itself, but also its label, its error messages, and helper text. They have a bunch of states they can be in, like are there errors or is the control disabled, and they come in a multitude of types - all of which benefit from all of the above.

Rails’ form helpers provide some building blocks for this, but we wanted a fully fledged experience we could bring along across projects, and still be sure that both the user experience is great, and the developer experience isn’t restricted moving forward.

I think we’ve ended up on something that’s both flexible and expressive:

<% form_with model: @user do |form| %>
  <%= render Flowbite::InputField::Text.new(attribute: :name, form: form) %>
  <%= render Flowbite::InputField::Email.new(attribute: :email, form: form) %>
  <%= render Flowbite::Button.new(type: :submit, content: "Save") %>
<% end %>

And of course, if you don’t want to just use the defaults for a field, you have options for customizing each element of the input field:

  <%= render Flowbite::InputField::Text.new(
    attribute: :name,
    form: form,
    label: {content: "Full Name", class: "text-2xl"},
    hint: {content: "Enter your full name"}
  ) %>

Getting started

Flowbite Components is available now on RubyGems and GitHub, and the documentation is online.

Do check out the installation instructions, which unfortunately aren’t as simple as I’d like them to, at this point.

Why Flowbite?

There are many UI/design kits out there, so why Flowbite?

Flowbite has a bunch of things going for it.

It’s open source, MIT licensed, which means we can actually release this gem and not have it be a private gem just for us.
It comes with both dark and light mode, which pretty much is a must these days.
It has a bunch of premium pages and components, some of which are paid for, which makes me hopeful for its extensibility and longevity.
Importantly, it has a comprehensive set of well designed input components, with all the elements you need for a user-friendly CRUD interface.

Outside of that, I like the look and feel. Their semantic classes and easy themability just reinforces the choice.

It’s a work in progress

Today, we’re officially releasing v0.2. Why not v1? We’re still polishing and tweaking the API, so I am reluctant to commit to a v1 just yet.

Also, we’re really far behind the full set of components. I mean, we only have 9 so far, which doesn’t really warrant a v1.

The future

Will we ever support all the components that Flowbite has designed? I honestly doubt it. For now we’re extracting components from our existing application, and implementing new ones as we need them. If we never need a, say, KBD component, we’ll likely never see one.

That said, not all components need to live in a component library. KBD is a good example of this; it’s effectively a single div with a list of CSS class names. I am not sure exactly how much value is added by creating a Flowbite::KBD component for this.

Another thing I’d love to investigate is a form builder, perhaps similar to Simple Form. Being able to say

<% form_with model: @user, builder: Flowbite::Form do |f| %>
  <%= f.input :name %>
  <%= f.input :address %>
  <%= f.submit %>
<% end %>

and still get the full Flowbite experience would be pretty cool.

Announcing styr

Sat, 24 Jan 2026 00:00:00 +0000

Ever needed to run some maintenance task in your production environment? For me this always triggers a bunch of questions: What’s that hostname again? What user should I log in as? And where did we deploy the application?

We‘ve built styr to answer those questions and ease the pain.

With styr launching a Rails console in your production environment is as simple as

$ styr --target=production run bundle exec rails console
Running rails console on ⬢ redacted-production... up, run.9530
Loading production environment (Rails 7.2.1.2)
redacted(prod)>

And the best part is, if your application is reachable via SSH instead of being hosted on Heroku as above, launching a Rails console in your production environment is as simple as

$ styr --target=production run bundle exec rails console
Loading production environment (Rails 8.0.2.1)
redacted(prod)>

Getting started

Just follow the fairly simple installation and usage instructions at substancelab/styr. Basically:

Grab the code from GitHub.
Add the styr binary to your PATH.
Configure targets in your application.

You should now be able to see styr in all its glory:

$ styr
styr [options] [--target] task [task options]
        --help                       Show helpful information
        --target TARGET              Target to perform the task on

Available tasks:
  run       Run a command on a target
  targets   List configured targets
  tasks     List available tasks

How about one-off scripts?

In my last post here I talked about running one-off scripts on Heroku with Rails, and of course you can do this with styr:

$ cat hi.rb | styr --target=production run "rails runner -"

Legacy

Looking back at my posts, this has actually been an ongoing thing of mine, and in many ways styr is the spiritual successor to capistrano-remote - just simpler and better.

The future

While the current version provides the bare minimum, I’d love to be able to add application specific tasks. How about running styr --target=production rake db:migrate for example, or perhaps just styr --target=production console to launch a console regardless of your application stack.

I am also seeing something interesting in running tasks on multiple servers at once. Perhaps something like styr --target=worker,web,app-01,app-02 run df -h to see free disk space across multiple servers?

One-off scripts on Heroku with Rails

Thu, 16 Oct 2025 00:00:00 +0000

Every so often you have a small script that needs to be run on your staging or production server, but committing and deploying the script on its own is just too much of a hassle. Luckily Rails and Heroku has a great solution for this.

rails runner

If you have a script in your application that needs to run in the context of your Rails application, you can run it via rails runner.

For example, let’s say we have this very important script:

puts Rails.env

Running this with just ruby gives an error:

$ ruby hi.rb
hi.rb:1:in `<main>': uninitialized constant Rails (NameError)

puts Rails.env
     ^^^^^

This makes sense, since Rails isn’t loaded. That’s where rails runner steps up and ensures the full Rails environment is loaded:

$ rails runner hi.rb
development

Pretty helpful!

rails runner doesn’t only run scripts from disk, it also has a few other tricks up its sleeve. For example, you could pass the code directly:

$ rails runner "puts Rails.env"
development

or you can pipe the Ruby code to rails runner - note the little - at the end of the command there, that means read the script from stdin.

$ cat hi.rb | rails runner
development

heroku run

Heroku’s CLI has a function similar to rails runner, namely heroku run.

Usage: heroku run COMMAND

Example: heroku run bash

That allows you to run a one-off process inside a Heroku dyno. Say, if we needed to run migrations on Heroku we could do

$ heroku run rails db:migrate

Also pretty helpful!

heroku run rails runner

Let’s combine those! heroku run runs any process, what if that process was rails runner?

$ heroku run 'rails runner "puts Rails.env"'

We do have to be fairly vigilant about placing our quotation marks so the correct things are run by the correct processes. In the above everything in ' is run by heroku run, which in turn runs everything in " using rails runner.

heroku run rails runner with a pipe

But can we pipe a script to rails runner and have heroku run run it in a dyno? I am so glad you asked! Yes, we can. heroku run forwards stdin to the process being run, so we can do

$ echo "puts Rails.env" | heroku run "rails runner -"
Running rails runner - on ⬢ some-app... up, run.7413
puts Rails.env
production

Note how the script/stdin is echoed back to us, which gets annoying for longer scripts. To avoid this we could use the --no-tty flag:

$ echo "puts Rails.env" | heroku run --no-tty "rails runner -"
Running rails runner - on ⬢ some-app... up, run.9354
production

How to run one-off Rails application scripts on Heroku

This leads us to the natural conclusion of all the above. In order to run a one-off script in a Heroku dyno with your Rails application environment loaded without having to add it to git and deploy, you can run it like so:

$ cat hi.rb | heroku run --no-tty "rails runner -"
Running rails runner - on ⬢ some-app... up, run.1846
production

Very helpful indeed!

Styr might help you

If you find the above relevant or helpful, you might be interested in checking out styr instead, which makes the above even easier.

Don't use instance variables in partials

Wed, 17 Sep 2025 00:00:00 +0000

One of my favorite pet peeves is instance variables in partials. Unfortuntaly, I still encounter these in actual production code.

I get it, it happens. You have a view template that needs cleaning up:

# app/views/employees/show.html.erb
...
<% @meetings.each do |meeting| %>
  A bunch of code to render a meeting
<% end %>
...

Easy enough, just extract some parts of it into a partial:

# app/views/employees/show.html.erb
...
<%= render("meetings") %>
...

# app/views/employees/_meetings.html.erb
<% @meetings.each do |meeting| %>
  A bunch of code to render a meeting
<% end %>

Now you suddenly have an instance variable in the partial. No biggie, you think, it works perfectly fine and that instance variable is already defined.

Why is this bad?

You’ve just coupled the partial to - not just the view - but the controller action, which is where the instance variable is defined.

If you ever need to use that partial in a different context it’ll break. If you remove the @meetings variable from the action (which isn’t unlikely because it’s obviously not being used in the view, so why even create it?) it’ll break. Boom, NoMethodError: undefined method 'each' for nil.

Instead, use locals. Even better, use strict locals. Or perhaps even better, ViewComponents, but that’s out of scope for this article.

Locals

If we instead rely on a local variable in the partial, the error would’ve been undefined method or variable, meetings, which is much more direct understandable:

# app/views/employees/_meeting.html.erb
<% meetings.each do |meeting| %>
  A bunch of code to render a meeting
<% end %>

We can then use the partial like this:

<% render("meetings", :meetings => @meetings) %>

While this is a bit more typing up front, it makes it painfully obvious what data the partial needs.

Strict locals

To make it even more explicit what locals a partial needs, we can configure the partial to use strict locals. Effectively document the “method signature” for a partial:

<%# locals (meetings:) %>
<% meetings.each do |meeting| %>
  A bunch of code to render a meeting
<% end %>

If we then try to render the partial without passing the :meetings local we’d get a ArgumentError: missing local: :meetings - again, much more explicit, understandable and actionable.

Don’t take my word for it

If you need more arguments against using instance variables in partials, just listen to Andy Croll.

How to fix `ld: library not found for -lzstd` installing mysql2

Mon, 04 Aug 2025 00:00:00 +0000

I have a history of problems with installing the mysql2 gem, and this is just another chapter in that tale. If you receive a ld: library not found for -lzstd error when running bundler or otherwise attempt to install the mysql2 gem, this might be the solution.

What I experienced

I am using MacPorts and trying to install the mysql2 gem gave me the following error

$ gem install mysql2 -v 0.5.6
...
ld: library not found for -lzstd
clang: error: linker command failed with exit code 1 (use -v to see invocation)
make: *** [mysql2.bundle] Error 1

make failed, exit code 2
...

TLDR; the solution

What worked for me was telling ld that it can find the libzstd files in the MacPorts lib directory at /opt/local/lib:

$ gem install mysql2 -v 0.5.6 -- --with-ldflags="-L/opt/local/lib"

More details

The relevant part of the error message above is

ld: library not found for -lzstd

This happens when ld wants to include some library, given after -l (in this case libzstd), but can’t. However the library is installed as part of my MacPort installation:

$ ls -1 /opt/local/lib/libzstd*
/opt/local/lib/libzstd.1.5.7.dylib
/opt/local/lib/libzstd.1.dylib
/opt/local/lib/libzstd.a
/opt/local/lib/libzstd.dylib

Seeing that ld can’t an installed library probably means that ld is looking the wrong place - or at the very least, not looking in the right place. So let’s tell it to.

Investigating man ld leads us to the -L/--library-path= command line argument:

-Ldir: Add dir to the list of directories in which to search for libraries. Directories specified with -L are searched in the order they appear on the command line and before the default search path. In Xcode4 and later, there can be a space between the -L and directory.

So maybe telling ld where to find the libraries can help. However, we are not calling ld directly ourselves, but rather RubyGems is calling it for us as part of the installation process.

Luckily, we can forward arguments to the installation process:

$ gem install mysql2 -v 0.5.6 -- --with-ldflags="-L/opt/local/lib"
Building native extensions with: '--with-ldflags=-L/opt/local/lib'
This could take a while...
Successfully installed mysql2-0.5.6
1 gem installed

So basically, we’re telling gem to tell make to tell ld to use /opt/local/lib as the -L argument.

Extra credits

Unfortunately this is a one-time thing. The next time you have to install mysql2, it’ll fail again - there’s no persistence here.

We can, however, take advantage of bundler here. If you do

$ bundle config --local build.mysql2 "--with-ldflags=-L/opt/local/lib"

you tell bundler to tell gem to tell make to tell ld to use /opt/local/lib in all future installations of the mysql2 gem.

Designing the API for a ViewComponent Input Group

Tue, 29 Jul 2025 00:00:00 +0000

I’ve been working on a set of form input components based on the ViewComponent library. Unfortunately I’ve been having problems deciding on an API I like and this post is my attempt to think it through publicly.

The simple case

The simplest case for an input group is something like

<%= render(InputGroup.new(form, :name)) %>

which should render something like

<label for="user_name">Name</label>
<input id="user_name" name="user[name]">

That’s easy and straightforward to implement:

class InputGroup < ViewComponent::Base
  erb_template <<-ERB
    <%= @form.label(@attribute) %>
    <%= @form.text_field(@attribute) %>
  ERB

  def initialize(form, attribute)
    @attribute = attribute
    @form = form
  end
end

Specify the label text

Now, it’s fairly common to change the text of the label to something other than the default, ie to get something like:

<label for="user_name">Please enter your full name</label>
<input id="user_name" name="user[name]">

An API for this, which goes hand in hand with what View Component already provides is:

<%= render(InputGroup.new(form, :name).with_label_content("Please enter your full name)) %>

For this to work we need to implement a LabelComponent that uses the #content accessor:

class LabelComponent < ViewComponent::Base
  erb_template <<-ERB
    <%= @form.label(@attribute, content, **options) %>
  ERB

  def initialize(form, attribute, **options)
    @attribute = attribute
    @form = form
    @options = options
  end
end

and we need to use that component. Initially I thought I could use a component slot for this, but that doesn’t work since we have to pass extra options (ie @attribute and @form) to the label. Well, we could make it work, but that’d require the consumer to pass those arguments for us:

<%= render InputGroup.new(form, :name) do |component| %>
  <% component.with_label(form, :name) { "Please enter your full name" } %>
<% end %>

and that’s too repetitive and error prone. A better solution is to use a lambda slot, which is intended to work as “wrappers for another ViewComponent with specific default values”:

class InputGroup
  ...
  renders_one :label, ->(**args, &block) do
    arguments = {
      attribute: @attribute,
      form: @form
    }.merge(args)

    LabelComponent.new(**arguments, &block)
  end
  ...
end

With that in place, we get the expected output:

<label for="user_name">Please enter your full name</label>
<input id="user_name" name="user[name]">

So far, so good. However, while changing just the label text is a common usage case, it is also a simple case. There might be cases where the consumer wants to do crazy and do something entirely different for the label.

Replacing the entire label

I want the consumers of my component to be able to do whatever they want for their labels. Perhaps they want to not have a label, or add more details to their labels, or otherwise go nuts, I’m not judging:

<div>
  <label>Your username</label>
  <p>This will be used whenever you log in</p>
</div>
<input id="user_name" name="user[name]">

Using standard ViewComponent practices and slots that could look something like:

<%= render InputGroup.new do |component| %>
  <% component.with_label do %>
    <%= render(LabelWithDescription.new) %>
  <% end %>
<% end %>

Alas, this doesn’t work as hoped. The return value of the block passed to with_label is used as the content for the label slot, which means we’ll pass that content onto our LabelComponent, effectively rendering a LabelComponent with a LabelWithDescription inside it. That’s not what we want.

(Aside: This begs the question; what is the actual difference between with_label_content and with_label? 🤔)

Back to the drawing board…

The only way I know of where we can achieve that last part is by using a blank/anonymous slot definition:

class InputGroup
  ...
  renders_one :label
  ...
end

However, this means we need to find a new way to handle the simple case, since

<%= render(InputGroup.new(form, :name).with_label_content("Please enter your full name)) %>

is now also going to just render whatever we pass to #with_label_content, ie without the wrapping LabelComponent. Thankfully, ViewComponent 4.0 introduces #default_SLOT_NAME methods, which is used to return whatever should be in a slot when content isn’t provided.

This means we can do

class InputGroup
  def default_label
    LabelComponent.new(@form, @attribute)
  end
end

to handle the simple case where no content is provided for the slot. We still need to find a way to specify custom text for the label, though. Instead of using #with_label_content we should be able to pass it as an argument, ie something like:

<%= render(InputGroup.new(form, :name, label: {content: "Please enter your full name"})) %>

To handle that we need to change our initializer:

def initialize(form, attribute, label: {})
  @attribute = attribute
  @form = form
  @label = label
end

and our default_label method:

def default_label
  label_options = @label.dup

  # Extract the content argument
  label_content = label_options.delete(:content)

  # Build a component with the remaining arguments
  component = LabelComponent.new(form, attribute, **label_options)
  if label_content
    # Pass the content argument as the content of the component if it exists
    component.with_content(label_content)
  else
    # ... otherwise just use the default
    component
  end
end

With the above in place, we’re back in business. The following

<%= render(InputGroup.new(form, :name, label: {content: "Please enter your full name"})) %>

now renders

<label for="user_name">Please enter your full name</label>
<input id="user_name" name="user[name]">

just like we want it to and we get the default behavior using

<%= render(InputGroup.new(form, :name)) %>

and we can replace the entire component with any content we desire:

<%= render InputGroup.new(form, :name) do |component| %>
  <% component.with_label do %>
    <h1>Who are you</h1>
    <%= form.label(:name, "What's your name?") %>
  <% end %>
<% end %>

Bonus: Label attributes

The above way of doing things has a neat bonus; it makes it really easy for us to pass options to our label component. Say we want to add a CSS class to the label, this code

<%= render(InputGroup.new(form, :name, label: {class: "required"})) %>

should end up rendering

<label for="user_name" class="required">User name</label>
<input id="user_name" name="user[name]">

Lo and behold, it already does. Since we pass everything in the label argument onto LabelComponent we’ve already implemented this. What a nice bonus.

Conclusion

I think I am fairly happy with this API. It…

Gives us sensible defaults.
Allows us to easily override the most common default (ie label text).
Allows us to pass arguments to the label component to customize it.
Allows us to replace the label component entirely with something more fancy.
Paves a path forward where other slots can be customized in the same way, ie render(InputGroup.new(form, :name, input: {class: "w-100"})).

Driving View Transitions with Hotwired/Turbo

Sat, 19 Apr 2025 00:00:00 +0000

View transitions between pages has been a reality on the web for quite a while now (at least in the browsers that support it). It has also been possible to use them with Turbo, albeit somewhat cumbersome, but that’s changed. Turbo now has built-in support for the View Transitions API as of version 8+.

Opt in to view transitions in Turbo Drive

First of all, ensure you’re using a browser with View Transitions support, ie not Firefox, alas.

All we have to do to enable Turbos built-in support for view transitions is add a meta tag to our page(s):

<meta name="view-transition" content="same-origin">

… and that’s it! When you navigate between pages you now get the default crossfading transition.

Make it easier to see what’s going on

In the real world we don’t want the transitions to take more than a few hundred miliseconds, if that. Any longer and the app starts feeling slow and sluggish. Remember, the transition cannot start until the new page has been actually loaded, so the transition does indeed slow down the user.

However, for debugging it can be beneficial to slow the transitions down so we can actually see what’s happening. We can do that by target the view-transition pseudo elements and set their animation duration:

::view-transition-old(root),
::view-transition-new(root) {
  animation-duration: 5s;
}

Animate the outgoing page

The default crossfade is boring, though, let’s spice it up.

A great thing about the view transition animations is that they are just standard CSS animations. This means we can use pretty much all the tricks and timing functions, we’re used to. Let’s define an animation that moves an element left and fades it out:

@keyframes exit-left {
  0% {
    transform: translateX(0);
    opacity: 100%;
  }
  100% {
    transform: translateX(-100%);
    opacity: 0%;
  }
}
/* ... and apply it to the leaving page */
::view-transition-old(root) {
  animation-name: exit-left;
  animation-timing-function: ease-in;
}

By applying this animation to the ::view-transition-old element, we’ve made the existing page look like it disappears stage left, while the new page still crossfades in.

Animate the incoming page

Let’s change how to new page appears by adding a new animation that makes it appear to come in from the right:

@keyframes enter-left {
  0% {
    transform: translateX(100%);
    opacity: 0%;
  }
  100% {
    transform: translateX(0%);
    opacity: 100%;
  }
}
::view-transition-new(root) {
  animation-name: enter-left;
  animation-timing-function: ease-out;
}

This looks pretty neat, huh? Now, you can obviously play with timing functions and animations to your hearts content and creative ability.

Going directions

View transitions appear on all page changes – not just the ones triggered by Turbo Drive. This also means, that when we click the Back button, we go back to the previous page with a pretty transition. However, the animation is the same as when we navigate by clicking.

Since the page we navigate to by using the back page is seen by view transitions as a new page (even though it’s actually a page from the cache) it will be animated as a new transition and enter from the right, which looks unexpected.

Luckily, Turbo has our back here:

Turbo also adds a data-turbo-visit-direction attribute to the <html> element to indicate the direction of the transition. The attribute can have one of the following values:

forward in advance visits.

back in restoration visits.

This means we can modify our CSS selectors and change the animations based on what direction we’re going; forward when we’re moving forward in the history using links or the forward button, and back when using the back button.

Only slide forward

So let’s start by ensuring we only use our left-moving animations when we navigate forward:

html[data-turbo-visit-direction="forward"] {
  &::view-transition-new(root) {
    animation-name: enter-left;
    animation-timing-function: ease-out;
  }

  &::view-transition-old(root) {
    animation-name: exit-left;
    animation-timing-function: ease-in;
  }
}

Doing this and we get our fancy animation when we navigate forward, ie click on links, and the default crossfade when going back by using the back button.

Slide history pages in

We can improve the back animation, for example to have it go the other way of the forward animation. Let’s start by adding two animations going the other way, ie one that enters going right and one that exits going right:

@keyframes exit-right {
  0% {
    transform: translateX(0);
    opacity: 100%;
  }
  100% {
    transform: translateX(100%);
    opacity: 0%;
  }
}
@keyframes enter-right {
  0% {
    transform: translateX(-100%);
    opacity: 0%;
  }
  100% {
    transform: translateX(0%);
    opacity: 100%;
  }
}

We can then use those animations when the navigation direction is “back”:

html[data-turbo-visit-direction="back"] {
  &::view-transition-new(root) {
    animation-name: enter-right;
    animation-timing-function: ease-out;
  }

  &::view-transition-old(root) {
    animation-name: exit-right;
    animation-timing-function: ease-in;
  }
}

Animate just part of the page

Until now we’ve animated the entire page, which is a bit much. Let’s say we want our slide animations to apply only to the main content area of the page. In this case that area is wrapped in an article element. We can target that to give it a specific view transition identifier:

article {
  view-transition-name: article;
}

If we then change all our previous ::view-transition-new(root) selectors to ::view-transition-new(article) and the same for ::view-transition-old(root) , which becomes ::view-transition-old(article), we get an entirely different experience:

(I’ve also changed the animation duration here to more realistic values).

Active Record STI and eager loading

Fri, 24 Jan 2025 00:00:00 +0000

This week has been … interesting. Not because of obvious geopolitical events, but because a client application started throwing weird errors; background processes failed in ways that weren’t possible and otherwise reliable cronjobs just didn’t do what they were supposed to; no failures or anything, they just didn’t process the records they were meant to.

This particular application uses Single Table Inheritance (STI) for one of the tables and we introduced a new super class into the hierarchy at the beginning of the week. Everything worked great in development and in testing, but in production things started being off.

Turns out, STI was to blame - or rather, us not reading the manual…

Let me tell you a tale…

The application has an Event model, which has a few subclasses; ArtistEvent inherits from Event, while BookingEvent and OfferEvent inherits from ArtistEvent.

We need to send an email every so often for specific BookingEvents so we have a cron job set up for that, running a rake task that runs some method in a class. And for some reason, those mails didn’t go out.

Blame the code!

Looking at the code, everything appears fine. The relevant events are loaded from the database using something similar to ArtistEvent.ready_for_reminders and each model is then processed.

Blame the data!

Running the code in a rails console on the production server made it clear that there were indeed events ready for reminders, yet when the cron job ran it found exacly 0 events.

Blame the cron job!

The cron job in question uses a rake task to trigger the code, and after a bunch of debugging we concluded that things did not work when running the code via a rake task, but it did work when running the same code via rails runner. Wut?!

Blame rake!

One sneaky difference between using rake (even when loading the rails environment) and using rails runner is how they load your application: By default, in production environments Rake tasks do not eager load the application.

Blame eager loading!

Armed with this knowledge (which I didn’t know until now, and I have a fair amount of Rails experience, I’d say 👴🏻) we started looking closer at how Rails eager loads.

Lo and behold, we could reproduce the problem in development when setting config.eager_load = true:

With `eager_load=false`

ArtistEvent.limit(1).to_sql
#=> "SELECT \"events\".* FROM \"events\" WHERE \"events\".\"type\" IN ('ArtistEvent') LIMIT 1"

With `eager_load=true`

ArtistEvent.limit(1).to_sql
#=> "SELECT \"events\".* FROM \"events\" WHERE \"events\".\"type\" IN ('ArtistEvent', 'OfferEvent', 'BookingEvent') LIMIT 1"

In other words, when eager_load is set to false, our query exclusively loads models of type ArtistEvent, ie none. We want the subclasses of ArtistEvent to be loaded, which is what happens with eager_load = true.

RTFM

Apparently, Single Table Inheritance doesn’t play well with lazy loading classes: Active Record has to be aware of STI hierarchies to work correctly, but when lazy loading, classes are precisely loaded only on demand.

This means that when we do ArtistEvent.subclasses with eager_load = false the subclasses has yet to be loaded and therefore doesn’t exist yet!

> ArtistEvent.subclasses.map(&:name) # With eager_load=false
#=> []

“Thankfully” 🙄 this is a known and documented problem and I guess we should have read the manual on Autoloading and reloading constants, but we didn’t and the application has been running just fine for years…

Luckily a bunch of solutions are also well documented in the above guide, so if you ever run into problems with ActiveRecord STI not including all subclasses in type queries there is a way forward.

How to fix (some) UnknownError and InvalidArgumentError in Capybara

Wed, 14 Aug 2024 00:00:00 +0000

The other day, our headless system specs in a Ruby on Rails project started failing with a bunch of errors we hadn’t seen before. Mostly Selenium::WebDriver::Error::UnknownError: unknown error: failed to close window in 20 seconds but in some cases also Selenium::WebDriver::Error::InvalidArgumentError: invalid argument: 'handle' must be a string.

Usually random errors in browser tests can be fixed by upgrading selenium-webdriver, Chrome, chromedriver or any combination thereof, but not this time.

TLDR

If you’re seeing errors like unknown error: failed to close window in 20 seconds or invalid argument: 'handle' must be a string in your Selenium test suite running on Chrome you might need to add --disable-search-engine-choice-screen to the driver options.

Root cause

The culprit revealed itself when we tried running the test suite with an actually visible, non-headless Chrome:

Chrome, even when running headless, wants the user to pick their search engine preference. But since there is no user, or no way to see the dialog, it’ll just wait and time out after a while.

The solution

Luckily there is a commandline option to disable the dialog: --disable-search-engine-choice-screen. So to fix the issue we can add that to our other Capybara driver options:

Capybara::Selenium::Driver.new(
  app,
  :browser => :chrome,
  :options => Selenium::WebDriver::Chrome::Options.new(
    :args => [
      "--headless=new",
      "--disable-search-engine-choice-screen"
    ]
  )
)

SimpleLocalize on Rails

Wed, 24 Apr 2024 00:00:00 +0000

When your application spans across multiple countries and languages, managing your translations using Rails’ default locale files in git becomes too cumbersome. We recently moved a clients Rails app to SimpleLocalize to give translators and developers a better workflow around translations. This is how we did it.

The setup

Rails 6 using I18n with the default backend spanning 7 different languages.
Deployment to Linode servers via Hatchbox.
Circle CI runs tests and prepares deployments.

Install the CLI

We’re going to make use of SimpleLocalizes CLI tool to move translations around, so we start by installing that.

I am not a big fan of the curl | bash process outlined in their docs, especially not when it then asks for root access 😬, so I’ve opted for downloading the CLI from their releases page. But you do whatever fits you and your setup here, the important thing is that we get a simplelocalize command to run.

Configure CLI for Rails defaults

Having installed the CLI we can run

simplelocalize init

to generate a default config file in the directory, we’re in. Personally I prefer having config files stored in /config, so let’s move it elsewhere there and add it to git.

mv simplelocalize.yml config/
git add config/simplelocalize.yml

Do note that this means we have to add a -c option to all simplelocalize commands for it to pick up our config file.

Now feel free to customize your config file as you please. I’d recommend the following options, though, as they match what we’re used to in Rails:

uploadPath: ./config/locales/application.{lang}.yml
uploadFormat: yaml
uploadOptions:
  - 'MULTI_LANGUAGE'
  - 'REPLACE_TRANSLATION_IF_FOUND'

downloadPath: ./config/locales/application.{lang}.yml
downloadFormat: yaml
downloadOptions:
  - 'MULTI_LANGUAGE'
  - 'WRITE_NESTED'

Most of the CLI commands need to be authorized with --apiKey. The API key can be found in the ‘Integrations > Project credentials > API Key’.

You can keep your API key in the config file or you can provide it on the CLI whenever you call the CLI, that’s up to you. Keeping secret keys out of git is a good practice, though. Ultimately, storing the API key in an environment variable is probably the best approach.

Import your existing translations

After signing up for SimpleLocalize and creating a project for your application, you want to seed the project with all your existing translations. Head to the “Data” tab in SimpleLocalize and choose YAML file under Import translations.

To configure the import for the format used by I18n’s YAML files, use the following settings:

Multi-language file: Even though each file only contains a single language, the file is formatted like a multi-language file with the locale name as a root-level key.
Overwrite translations: Not strictly necessary, but if you end up importing more than once, it does come in handy.
Leave Namespace empty.

Now, upload each of your language files one by one (sidenote, being able to choose and upload multiple files at once here would be great).

Alternatively, you can use the CLI to perform the above process, assuming you’ve configured everything as described:

simplelocalize -c config/simplelocalize.yml upload --apiKey $API_KEY

Download translations to development

Now that SimpleLocalize is the ultimate source of truth for translations, we should remove them from our repository. You could still have them in git, and it would ease some things (like deployment). We have found, though, that the overall cost in terms of merge conflicts and confusion as to what translations are the most recent makes that solution untenable.

So…

git rm config/locales/*
touch config/locales/.gitkeep
echo config/locales >> .gitignore
git add config/locales/.gitkeep
git commit -m "Remove translation files"

Now, your up-to-date translations is no more than a

simplelocalize -c config/simplelocalize.yml download --apiKey $API_KEY

away.

Download translations during deployment

Now that we have removed our translations from the project, they’ll no longer be included when we run a deployment. Instead we’ll have to download the most recent translations from SimpleLocalize during deployment.

This application uses Hatchbox for deployments, so the following applies directly to that service. However, you should be able to replicate this using whatever hosting provider you use.

During the build phase (we use a Custom build script) we can download the translations from SimpleLocalize using the CLI - assuming it’s installed:

simplelocalize -c config/simplelocalize.yml download --apiKey $API_KEY

This is just like we do in development and you might consider wrapping this in a script that you can run whenever/wherever needed (we’ve got a script/translations/pull) that does exactly this.

During the pre-build phase we’ll make sure the CLI is installed on the build server. Your milage may vary, but we found that downloading a specific release

How you install the CLI on your build server is up to you, but you could do it via a script like the following:

wget --no-verbose https://github.com/simplelocalize/simplelocalize-cli/releases/download/2.6.0/simplelocalize-cli-linux
mv simplelocalize-cli-linux ~/bin/simplelocalize
chmod a+x ~/bin/simplelocalize

Download translations on CI

We use Circle as our CI server and we need the translations downloaded there as well in order to run tests and build the project assets.

Unfortunately we ran into issues with the most recent versions of the CLI. Because Circle is running older versions of Ubuntu we can’t run the newer CLI releases:

simplelocalize: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.33' not found (required by simplelocalize)
simplelocalize: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.34' not found (required by simplelocalize)

We ended up just installing a legacy version of the CLI (2.1.1), which works, and subsequently using it to download translations:

curl -s https://get.simplelocalize.io/2.1.1/install | bash
simplelocalize -c config/simplelocalize.yml download --apiKey $API_KEY

(on CI I am not too worried about the curl | bash pattern - should I be?)

Closing notes

Now all that is left is inviting your developers and translators to SimpleLocalize and start localizing.

mentalized.net

Announcing Flowbite Components for Rails

Forms

Getting started

Why Flowbite?

It’s a work in progress

The future

Announcing styr

Getting started

How about one-off scripts?

Legacy

The future

One-off scripts on Heroku with Rails

rails runner

heroku run

heroku run rails runner

heroku run rails runner with a pipe

How to run one-off Rails application scripts on Heroku

Styr might help you

Don't use instance variables in partials

Why is this bad?

Locals

Strict locals

Don’t take my word for it

How to fix ld: library not found for -lzstd installing mysql2

What I experienced

TLDR; the solution

More details

Extra credits

Designing the API for a ViewComponent Input Group

The simple case

Specify the label text

Replacing the entire label

Back to the drawing board…

Bonus: Label attributes

Conclusion

Driving View Transitions with Hotwired/Turbo

Opt in to view transitions in Turbo Drive

Make it easier to see what’s going on

Animate the outgoing page

Animate the incoming page

Going directions

Only slide forward

Slide history pages in

Animate just part of the page

Further reading

Active Record STI and eager loading

Let me tell you a tale…

Blame the code!

Blame the data!

Blame the cron job!

Blame rake!

Blame eager loading!

With eager_load=false

With eager_load=true

RTFM

How to fix (some) UnknownError and InvalidArgumentError in Capybara

TLDR

Root cause

The solution

SimpleLocalize on Rails

The setup

Install the CLI

Configure CLI for Rails defaults

Import your existing translations

Download translations to development

Download translations during deployment

Download translations on CI

Closing notes

How to fix `ld: library not found for -lzstd` installing mysql2

With `eager_load=false`

With `eager_load=true`