The problem wasn’t that the individual classes were particularly bad. Most of them were fine in isolation. The problem was that it was hard to know which service objects were being used by other service objects and it was hard to discern the impact that changing a service object had. It was safer to add a new service object and you had two choices: near the controller (the beginning of the chain) or the model (the end).

So the chains got longer. The service objects in the middle became a tangled web that nobody wanted to touch. The roles blurred until “service object” just meant “a class that does something, somewhere.”

I started thinking about what better boundaries and purpose would look like.

The service object problem

Service objects are just plain old Ruby objects. They can take anything, return anything, and call anything. There’s no constraint that tells you “this is my particular, exclusive job.” So when you’re staring at a chain of them, you have to read every one to understand what’s actually happening.

The lack of a clear role means they could do a bit of everything. Should this do validation? Is it some key business logic? Can I trust the inputs? Do I dare modify the data? Which models will this touch? The answer is usually “who knows?” which is how you end up with logic accreting at the edges — controllers and models — because at least you know what those are for.

Looking at the tests didn’t help. We believed in strong unit testing and mocking the boundaries. The test suite would tell you each link worked in isolation, but nothing about what the pipeline actually did end-to-end. You could have a green test suite and a broken feature.

The problem isn’t service objects per se. It’s the lack of clear roles and boundaries. What if each class had exactly one job, with explicit inputs, validation, and output?

Design philosophy

The idea behind ActionFigure is fully-articulated controller actions. When you open an action class, the full story is right there — what it accepts, how it validates, what it does, what it returns. You should be able to quickly see what it does without tracing through a chain of other objects.

Functional style. Actions are essentially functions. Clear inputs go in via keyword arguments, a render-ready hash comes out. No side-effecting instance state, no mutable shared context being passed down a chain.

Explicit over implicit. The shape and types of inputs are declared, not inferred. The response format can be chosen, not assumed. There’s no magic method resolution and no convention-based behavior — what you see is what you get.

Self-contained units. Each action is a complete, readable unit. No hidden state inherited from a base class, no relying on middleware you can’t see. Class-level state like params_schema and rules is intentionally not inherited by subclasses. Share behavior through plain Ruby — extract a method, call a service — not through deep class hierarchies.

Reusable across controllers. Because actions are decoupled from the controllers that call them, versioned controllers can share the same action class. V1::UsersController and V2::UsersController can both call Users::CreateAction.create. Versioning lives in the routing and controller layer where it belongs, not duplicated across business logic.

Introducing ActionFigure

Here’s what an action class looks like. This one creates a user and returns a JSON:API formatted response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

class Users::CreateAction
  include ActionFigure[:jsonapi]

  params_schema do
    required(:user).hash do
      required(:name).filled(:string)
      required(:email).filled(:string)
    end
  end

  def create(params:, company:)
    user = company.users.create(params[:user])
    return UnprocessableContent(errors: user.errors.messages) if user.errors.any?

    Created(resource: user.as_json(only: %i[id name email]))
  end
end

The params_schema block declares the shape and types of the input. The action method does the work. ActionFigure automatically detects #create as the entry point and generates a matching class method, so the controller calls Users::CreateAction.create. The response helpers — Created, UnprocessableContent — return render-ready hashes that go straight to render in the controller.

The controller becomes a one-liner:

1
2
3
4
5
6

class UsersController < ApplicationController
  def create
    render Users::CreateAction.create(params:, company: current_company)
  end
end

Extra keyword arguments like company: are passed through to #create as context. The action doesn’t know or care that it’s being called from a controller — you can test it with a plain method call.

The validation pipeline

In a typical Rails app the controller has params.require(:user).permit(:name, :email) — a whitelist that tells you which keys are allowed but nothing about their shape or types. You have to make those checks elsewhere.

ActionFigure replaces this with a two-layer pipeline that lives in one place.

Layer one: params_schema. This is where you declare the shape and types of the input. It makes both obvious at a glance:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

params_schema do
  required(:user).hash do
    optional(:title).filled(:string)
    required(:name).filled(string)
    optional(:email).filled(:string)
    optional(:guid).filled(:string)
    required(:address).hash do
      required(:street1).filled(:string)
      optional(:street2).filled(:string)
      required(:city).filled(:string)
      required(:state).filled(:string)
      required(:zipcode).filled(:string)
    end
  end
  optional(:referral_id).filled(:integar)
end

Compare that to params.require(:user).permit(:title, :name, :email, address: [:street1, :street2, :city, :state, :zipcode]). The permit call tells you the allowed keys, but not that title and street2 are optional while the rest are required, not that referral_id should be an integer, and there’s no clean way to express that referral_id is an optional sibling of the required user hash. With params_schema, the shape is obvious and the types are explicit.

Type coercion happens automatically — the string "25" that comes over HTTP becomes the integer 25. ActionFigure also accepts ActionController::Parameters directly. The schema acts as the whitelist, so there are no manual permit calls.

If the schema fails, the action method never runs. The action returns an UnprocessableContent response immediately.

Layer two: rules. This is where cross-field and contextual validation lives. Rules only run after the schema passes, so you can trust that the data is structurally valid:

1
2
3
4

rules do
  one_rule(:email, :guid, "provide either an email or a guid, but not both")
end

ActionFigure provides four cross-param rule helpers:

• one_rule — exactly one of the listed fields must be present
• all_rule — all or none of the listed fields must be present
• any_rule — at least one of the listed fields must be present
• exclusive_rule — at most one of the listed fields may be present

These are convenience helpers for common cases, but the rules block supports any custom validation that works with dry-validation — so you’re not limited to these four:

1
2
3
4
5
6
7
8
9
10

rules do
  rule(:email) do
    key.failure("is not a valid email") unless values[:email].include?("@")
  end

  rule(:email) do
    key.failure("is already taken") if User.exists?(email: values[:email])
  end
end

These run in the validation layer, before the action method. Invalid combinations never reach your business logic. When the action method runs, you can trust that the inputs are structurally valid and logically consistent.

You can also enable strict mode with whiny_extra_params in the configuration. By default, extra parameters are silently stripped. With strict mode, they trigger a validation failure:

1
2
3
4
5
6
7

ActionFigure.configure do |config|
  config.whiny_extra_params = Rails.env.development?
end

# Called with: { item_id: 1, quantity: 2, admin: true }
# Result: UnprocessableContent with { admin: ["is not allowed"] }

The throughline: instead of validation scattered across controller, model, and service objects, the entire input contract is in one place.

Pluggable response formatters

Action logic shouldn’t be coupled to a particular response envelope. ActionFigure separates the two: your action method uses response helpers like Ok and Created, and the formatter decides what shape the JSON takes.

The JSON:API formatter, for example, wraps resources in the standard { data: { type, id, attributes } } structure and formats errors with JSON pointers:

1
2
3
4
5
6
7
8

Created(resource: user.as_json(only: %i[id name email]))
# => {
#   json: {
#     data: { id: "1", name: "Tad", email: "tad@example.com" }
#   },
#   status: :created
# }

1
2
3
4
5
6
7
8
9
10
11
12

UnprocessableContent(errors: { name: ["is missing"] })
# => {
#   json: {
#     errors: [{
#       status: "422",
#       detail: "is missing",
#       source: { pointer: "/data/attributes/name" }
#     }]
#   },
#   status: :unprocessable_content
# }

ActionFigure ships with four formatters. Here’s how the same Ok(resource: { name: "Tad" }) call looks in each:

You select a formatter per-class with include ActionFigure[:jsonapi], or set a global default:

1
2
3
4

ActionFigure.configure do |config|
  config.format = :jsonapi
end

Every formatter provides nine response helpers that map to HTTP status codes:

You can also build your own. A custom formatter is a module that implements the eight required methods (Ok, Created, Accepted, UnprocessableContent, NotFound, Forbidden, Conflict, PaymentRequired) and registers itself:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

module MyFormatter
  include ActionFigure::Formatter

  def Ok(resource:, meta: nil)
    { json: { result: resource, ok: true }, status: :ok }
  end

  def Created(resource:, meta: nil)
    { json: { result: resource, ok: true }, status: :created }
  end

  def Accepted(resource: nil, meta: nil)
    { json: { ok: true }, status: :accepted }
  end

  def UnprocessableContent(errors:)
    { json: { errors: errors, ok: false }, status: :unprocessable_content }
  end

  def NotFound(errors:)
    { json: { errors: errors, ok: false }, status: :not_found }
  end

  def Forbidden(errors:)
    { json: { errors: errors, ok: false }, status: :forbidden }
  end

  def Conflict(errors:)
    { json: { errors: errors, ok: false }, status: :conflict }
  end

  def PaymentRequired(errors:)
    { json: { errors: errors, ok: false }, status: :payment_required }
  end
end

ActionFigure.configure do |config|
  config.register(my_format: MyFormatter)
  config.format = :my_format
end

Registration validates that your module implements all required methods at load time, so you find out immediately if you’ve missed one.

Under the hood

If you’re curious about how the pieces fit together, here’s what’s happening inside.

Automatic entry point discovery. ActionFigure uses a method_added hook to watch for public instance methods defined on the class. The first public method becomes the entry point and a matching class-level method is created automatically. So when you define def create(params:, company:), ActionFigure generates Users::CreateAction.create as the class method that runs the full validation pipeline before invoking your method.

If a class defines more than one public method, ActionFigure raises an IndeterminantEntryPointError — use the entry_point macro to disambiguate, or make the helper method private:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

class Orders::SearchAction
  include ActionFigure[:jsend]

  entry_point :search

  params_schema do
    optional(:order_id).filled(:string)
    optional(:tracking_number).filled(:string)
  end

  def search(params:, company:)
    orders = company.orders
    orders = orders.where(id: params[:order_id]) if params[:order_id]
    orders = orders.where(tracking_number: params[:tracking_number]) if params[:tracking_number]
    Ok(resource: orders.as_json(only: %i[id tracking_number status]))
  end

  def format_results(orders)
    # making this private would also resolve the ambiguity
    orders.as_json(only: %i[id tracking_number status])
  end
end

Dynamic module building. When you write include ActionFigure[:jsonapi], the [] method dynamically builds a module that mixes in two things: the validation pipeline (Core) and the chosen formatter. Here’s the actual code:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

def self.[](format = configuration.format)
  format_modules.compute_if_absent(format) { build_format_module(format, fetch(format)) }
end

def self.new_format_module(formatter)
  Module.new do
    def self.included(base)
      base.extend(ActionFigure::Core::ClassMethods)
      return unless defined?(ActiveSupport::Notifications) &&
                    ActionFigure.configuration.activesupport_notifications

      base.extend(ActionFigure::Core::Notifications)
    end

    include ActionFigure::Core
    include formatter
  end
end

This is why each action class gets a clean include — the dynamically built module brings in everything the action needs in one shot. Formatter selection happens at include time, so different actions in the same app can use different formatters.

Thread-safe caching. Format modules are cached in a Concurrent::Map, so each one is built exactly once and reused across threads. The compute_if_absent call guarantees thread safety without explicit locks — important for high-throughput Rails apps running on Puma.

1
2
3
4

def self.format_modules
  @format_modules ||= Concurrent::Map.new
end

No inheritance by design. Class-level state — params_schema, rules, and the detected entry point — is stored in class instance variables that are intentionally not inherited by subclasses. This is a deliberate choice. Each action is a flat, self-contained unit that you can read without wondering what a parent class set up. It prevents the kind of deep inheritance chains that made the original service object problem so hard to reason about.

Contract exposure. The underlying Dry::Validation::Contract is accessible via .contract:

1
2
3
4
5

contract = Users::CreateAction.contract
result = contract.call(user: { name: "Tad", email: "tad@example.com" })
result.success?  # => true
result.to_h      # => { user: { name: "Tad", email: "tad@example.com" } }

This is useful for form validation endpoints where you want to check params without running the full action, or for testing validation rules in isolation.

Testing

With ActionFigure, testing is straightforward. Actions are Ruby objects that receive named parameters and return hashes. You call the class method with the same arguments the controller would pass, and you assert on the result.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

require "action_figure/testing/minitest"

class Users::CreateActionTest < Minitest::Test
  include ActionFigure::Testing::Minitest

  def test_creates_a_user
    company = Company.create!(name: "Acme")

    result = Users::CreateAction.create(
      params: { user: { name: "Tad", email: "tad@example.com" } },
      company: company
    )

    assert_Created(result)
    assert_includes result[:json][:data].to_s, "Tad"
  end

  def test_rejects_missing_name
    company = Company.create!(name: "Acme")

    result = Users::CreateAction.create(
      params: { user: { email: "tad@example.com" } },
      company: company
    )

    assert_UnprocessableContent(result)
  end
end

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

require "action_figure/testing/rspec"

RSpec.describe Users::CreateAction do
  it "creates a user with valid parameters" do
    company = Company.create!(name: "Acme")

    result = Users::CreateAction.create(
      params: { user: { name: "Tad", email: "tad@example.com" } },
      company: company
    )

    expect(result).to be_Created
    expect(result[:json][:data]).to include("name" => "Tad")
  end

  it "rejects missing name" do
    company = Company.create!(name: "Acme")

    result = Users::CreateAction.create(
      params: { user: { email: "tad@example.com" } },
      company: company
    )

    expect(result).to be_UnprocessableContent
  end
end

The matchers — assert_Created, be_Created, assert_UnprocessableContent, be_UnprocessableContent, and so on — are provided for all nine response statuses. They check the :status key in the returned hash.

The test calls the action the same way the controller does. There’s nothing to mock.

ActiveSupport Notifications

ActionFigure has optional ActiveSupport::Notifications integration. When enabled, every action call emits a process.action_figure event with the action class name and response status:

1
2
3
4

ActionFigure.configure do |config|
  config.activesupport_notifications = true
end

1
2
3
4
5
6

ActiveSupport::Notifications.subscribe("process.action_figure") do |event|
  Rails.logger.info "#{event.payload[:action]} → #{event.payload[:status]} (#{event.duration}ms)"
end

# => "Users::CreateAction → created (12.3ms)"

You get logging, monitoring, and alerting hooks without coupling any of that into the action logic itself. The action doesn’t know it’s being observed.

File conventions

Actions aren’t generic service objects floating in app/services/ with vague names like UserManager or ProcessOrder. They follow a consistent naming convention: Resource::VerbAction. The -Action suffix tells you exactly what you’re looking at — a class that handles a single controller action with declared inputs and a structured response.

I have two recommended directory structures (that work with Rails autoloading):

1
2
3
4
5
6
7
8
9
10
11

app/actions/
  users/
    create_action.rb
    destroy_action.rb
    index_action.rb
    show_action.rb
    update_action.rb
  orders/
    search_action.rb
    cancel_action.rb

1
2
3
4
5
6
7
8
9
10
11
12
13

app/controllers/
  users_controller.rb
  users/
    create_action.rb
    destroy_action.rb
    index_action.rb
    show_action.rb
    update_action.rb
  orders_controller.rb
  orders/
    search_action.rb
    cancel_action.rb

The second option keeps actions right next to the controllers that call them. Either way, when you see Users::CreateAction you know it’s an action class that handles user creation for a controller — not a service object that might be called from anywhere.

Playing well with others

Because actions are plain Ruby objects that take keyword arguments and return hashes, they compose naturally with whatever gems you’re already using. No adapters, no special imports — just call the library and pass the result to a response helper.

Serialization. Use Blueprinter, Alba, Oj Serializers, or anything else that gives you a hash:

1
2
3
4
5
6
7

def create(params:, company:)
  user = company.users.create(params[:user])
  return UnprocessableContent(errors: user.errors.messages) if user.errors.any?

  Created(resource: UserBlueprint.render_as_hash(user))
end

Authorization. Pass current_user as context from the controller and check policies inside the action:

1
2
3
4
5
6
7
8
9
10

def destroy(params:, current_user:)
  user = User.find(params[:id])
  unless UserPolicy.new(current_user, user).destroy?
    return Forbidden(errors: { base: ["not authorized to delete this user"] })
  end

  user.destroy!
  NoContent()
end

Pagination. Paginate with Pagy, cursor pagination, or whatever you prefer — pass metadata through the meta: keyword:

1
2
3
4
5
6
7
8
9
10
11

class Users::IndexAction
  include ActionFigure[:jsend]
  include Pagy::Backend

  def index(request:, company:, **)
    pagy, users = pagy(:keyset, company.users.order(:name), request:)
    resource = UserSerializer.many(users)
    Ok(resource:, meta: { next: pagy.next })
  end
end

The pattern is always the same: context comes in as keyword arguments, the gem does its job, and the result goes out through a response helper.

Actions without a schema

Not every action needs parameter validation. Actions that omit params_schema skip the validation pipeline entirely — any params: passed through are delivered as-is. This is useful when validation is handled upstream (like OpenAPI middleware) or when the action simply doesn’t need params:

1
2
3
4
5
6
7
8

class HealthCheckAction
  include ActionFigure[:jsend]

  def check
    Ok(resource: { status: "healthy", time: Time.current })
  end
end

1
2
3
4
5
6

class HealthController < ApplicationController
  def show
    render HealthCheckAction.check
  end
end

Fully articulated

The 12-deep service object chains happened because there were no clear roles or boundaries. Nobody knew where they were in the chain, so the chains got longer.

ActionFigure is my answer to that. Each action owns its validation, its logic, and its response shape. One class, one job, fully self-contained. You open the file and you can see what it does and know that it is being used by a controller.

ActionFigure on GitHub →

However, many of the lettering practice sheets are locked behind email signups and they are fixed at a particular style. I realized that they aren’t that complicated and would be easy to generate.

So I built a Lettering Practice Page Generator.

It’s an interactive tool that lets you configure every aspect of a practice page, upload a letterform to trace, and download it as a PDF. No signup. No email. Just sliders and a download button.

Letterform upload

The headline feature: upload a PNG or SVG of any letterform and the generator will place it on your practice sheet. There are three modes:

• Reference — a full-opacity copy at the start of each row, so you have something to look at while you practice
• Tracing — ghosted copies tiled across the first row, so you can trace directly over them
• Both — reference on every row, plus tracing on the first

Once uploaded, you can fine-tune the placement with three sliders:

• Offset — shifts the letterform up or down, useful for letters with descenders like g or y that need to sit lower relative to the baseline
• Size — scales the letterform from 25% to 200% of the row height
• Spacing — controls the gap between tracing copies across the row

Guide lines

The generator has controls for the five horizontal guide lines that matter in lettering:

• Ascender — the top boundary for tall letters like b, d, h
• Cap height — where capital letters reach
• X-height — the height of lowercase letters like a, e, o
• Baseline — where letters sit
• Descender — how far below the baseline letters like g, p, y drop

Each line has a distinct color and style so you can tell them apart at a glance. The baseline is a solid dark line. The cap height is solid orange. The x-height is dotted blue. Ascender and descender lines are dashed gray.

Beyond the lines themselves, you can adjust:

• Slant angle — anywhere from -45° to +45° for scripts that require angled guides
• Slant spacing — how far apart the slant lines are
• Rows — how many line sets fit on the page
• Gap — vertical space between rows
• Margin — page margins

Everything updates in real time on a canvas preview, so you can see exactly what you’ll get before downloading.

The PDF

The download generates a letter-sized PDF with all of your settings preserved. The line weights, colors, dash patterns, and letterform placement match the preview exactly. Print it, grab a pen, and practice.

That’s it. No account, no email list, no watermarks. Just a tool that makes the practice sheets I wanted.

Try it out →

But Rubular, as of this post, is still using Ruby 2.5.9. I thought it would be interesting to have a more modern version. Also, since this is a statically generated blog I wanted to see if I could build something similar that runs entirely in the browser.

ruby.wasm

ruby.wasm is a build of CRuby compiled to WebAssembly. You can load it with a single script tag:

1
2

<script src="https://cdn.jsdelivr.net/npm/@ruby/4.0-wasm-wasi@2.8.1/dist/browser.script.iife.js"></script>

Once loaded, you can write Ruby directly in the page:

1
2
3
4
5

<script type="text/ruby">
  require "js"
  JS.global[:document].querySelector("#output")[:textContent] = "Hello from Ruby"
</script>

The js gem bridges Ruby and JavaScript. You can read DOM elements, set properties, and attach event listeners. The Ruby code runs in the browser with no server involved.

The regex engine

The core of the editor is a Ruby function that takes a pattern, flags, and test string, then returns structured match data as JSON:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

def run_regex(pattern_str, flags_str, test_str, sub_str)
  opts = 0
  opts |= Regexp::IGNORECASE if flags_str.include?("i")
  opts |= Regexp::MULTILINE if flags_str.include?("m")
  opts |= Regexp::EXTENDED if flags_str.include?("x")

  regex = Regexp.new(pattern_str, opts)

  matches = []
  offset = 0

  while (m = regex.match(test_str, offset))
    match_data = {
      full: m[0],
      index: m.begin(0),
      length: m[0].length,
      groups: []
    }

    (1...m.size).each do |i|
      group = {number: i, value: m[i]}
      if i - 1 < m.names.length && m.names[i - 1]
        group[:name] = m.names[i - 1]
      end
      match_data[:groups] << group
    end

    matches << match_data

    new_offset = m.end(0)
    new_offset += 1 if new_offset == offset
    break if new_offset > test_str.length
    offset = new_offset
  end

  {error: nil, matches: matches}.to_json
end

This is real Regexp. Not a JavaScript approximation. Ruby-specific features like \A, \z, \h, \K, \R, and \p{L} all work because it is the actual Ruby regex engine running in the browser.

Connecting Ruby to the DOM

The function is exposed to JavaScript through a Proc:

1
2
3
4

JS.global[:rubyRegex] = Proc.new { |pattern, flags, text, sub|
  run_regex(pattern.to_s, flags.to_s, text.to_s, sub.to_s)
}

On the JavaScript side, a thin layer reads the inputs, calls window.rubyRegex(), and renders the results. Match positions come back as indices, so building highlighted HTML is straightforward:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

function buildHighlightedHTML(text, matches) {
  let result = '';
  let lastIndex = 0;

  for (const match of matches) {
    const start = match.index;
    const end = start + match.length;
    result += escapeHTML(text.slice(lastIndex, start));
    result += '<mark>' + escapeHTML(match.full) + '</mark>';
    lastIndex = end;
  }

  result += escapeHTML(text.slice(lastIndex));
  return result;
}

Input events fire with a 100ms debounce, which keeps things responsive without overwhelming the WASM runtime.

The tool

The editor has a few features worth mentioning:

• Flag toggles for i (case insensitive), m (multiline), and x (extended mode)
• A gsub mode that shows the substitution result when toggled on
• Generated Ruby code with syntax highlighting, so you can copy the exact .scan or .gsub call into your project
• Permalinks that encode the regex, test string, and flags in the URL for sharing

The loading time for ruby.wasm is noticeable—a few seconds on first visit while the WASM binary downloads. After that, everything runs instantly.

Try it out →

RoboTalk Programming Language

RoboTalk is a stack-based language using postfix (Reverse Polish) notation. Instead of writing 5 + 3, you write 5 3 +. Values are pushed onto a stack, and operators consume values from the stack and push results back.

Basic Syntax

• Labels are defined with a colon, e.g Main:
• Comments start with # or are enclosed in { }
• Variables are read by name and written with a quote: aim reads the aim register, aim' writes to it
• Storing values uses the pattern: 90 aim' sto (stores 90 in aim)

The IF statement works like this: value1 value2 operator label IF. For example, range 0 > ShootEm if means “if range > 0, jump to ShootEm and save the return address.”

Variables (A-Z)

You have 26 general-purpose variables named A through Z. Read them by name, write to them with a quote suffix:

1
2
3

10 a' sto    # Store 10 in variable A
a 5 + b' sto # Store A + 5 in variable B

Note: X and Y are special—they return the robot’s coordinates and are read-only.

Robot State Registers

These registers let you read and control your robot:

Weapon Commands

Write to these registers to fire weapons:

The value you write determines the energy spent (and thus damage dealt): 15 fire' sto fires with 15 energy.

Hardware Configuration

When building a robot, you spend Hardware Points on various attributes and weapons. The total determines your robot’s class.

Most competitive play uses the 9-point “Mortal” class.

Processor Speed

This determines how many instructions your robot executes per chronon (game tick):

Bullet Types

Choose one (mutually exclusive):

Weapons

Each weapon costs 1 Hardware Point. Choosing the right weapons for your strategy is crucial.

Bullets (FIRE / BULLET)

Bullets are your primary weapon and don’t cost extra hardware points—they’re included with every robot. They travel at speed 12 and deal damage based on your bullet type (Explosive, Normal, or Rubber). Bullets are versatile and energy-efficient, making them the workhorse weapon for most robots. Use the BULLET' command when you have explosive bullets but want to fire a normal shot to avoid splash damage at close range.

• Damage: Depends on bullet type (Explosive: Energy × 2, Normal: Energy × 1, Rubber: Energy ÷ 2)
• Speed: 12
• Best for: General combat, consistent damage output

Missiles

Missiles are slow but devastating. They travel at only speed 5, making them easy to dodge at long range, but they deal double damage (Energy × 2). Missiles excel at close-range combat where the enemy has less time to react, or against stationary/predictable targets. The slow speed makes leading shots more difficult—you need to anticipate where the enemy will be much further in advance.

• Damage: Energy × 2
• Speed: 5
• Cost: 1 hardware point
• Best for: Close-range brawling, high-damage ambushes

Hellbores

Hellbores are unique because their speed equals the energy you put into them. Fire with 4 energy and it moves at speed 4; fire with 20 energy and it moves at speed 20. This makes them incredibly versatile—slow and powerful or fast and light. The tradeoff is you must fire between 4-20 energy per shot (no tiny plinks or massive blasts). Advanced robots use hellbores to vary their projectile timing and confuse enemies that try to dodge predictable shots.

• Damage: Energy × 1
• Speed: Equal to energy invested (4-20)
• Cost: 1 hardware point
• Best for: Unpredictable attacks, skilled players who can exploit variable timing

Lasers

Lasers hit instantly—no travel time, no leading required. Point at an enemy, fire, and they take damage immediately. The catch? They only deal 1/5 of the energy invested as damage, making them very energy-inefficient. Lasers also require line-of-sight to a living robot; you can’t fire into empty space. They’re ideal for finishing off weak enemies or for robots that struggle with leading shots.

• Damage: Energy ÷ 5
• Speed: Instant
• Cost: 1 hardware point
• Best for: Guaranteed hits, finishing blows, simple aiming logic

Stunners

Stunners don’t just damage enemies—they temporarily freeze them in place, stopping their program execution. This gives you time to line up follow-up shots or escape. The damage is low (Energy ÷ 4), so stunners work best as a tactical tool rather than a primary weapon. Stun an enemy, then blast them with missiles while they can’t dodge.

• Damage: Energy ÷ 4
• Speed: 14
• Cost: 1 hardware point
• Best for: Crowd control, setting up kills, disabling dangerous enemies

Mines

Mines are deployed at your current location and sit there until an enemy touches them. They’re defensive weapons—drop them while retreating or place them in areas enemies are likely to pass through. The damage formula (2 × (Energy - 5)) means you need at least 6 energy to deploy one, with 5 energy as overhead. Mines are great for area denial and punishing aggressive pursuers.

• Damage: 2 × (Energy - 5)
• Minimum energy: 6
• Cost: 1 hardware point
• Best for: Defense, area denial, punishing chasers

Drones

Drones are autonomous homing projectiles. Once launched, they track and chase the target robot for 100 chronons before expiring. They deal half damage (Energy ÷ 2) but don’t require you to aim—the drone does the work. Drones are excellent against evasive enemies and let your robot focus on dodging while the drone handles offense. The downside is their limited lifespan and reduced damage.

• Damage: Energy ÷ 2
• Lifespan: 100 chronons
• Cost: 1 hardware point
• Best for: Fire-and-forget attacks, fighting evasive enemies, multitasking

TacNukes (Tactical Nukes)

TacNukes explode at your current position, dealing area damage to nearby enemies. They’re suicide weapons in a sense—you need to get close to use them effectively, and you might catch yourself in the blast. They’re best used as a desperation move when you’re about to die anyway, or by robots designed around hit-and-run tactics.

• Damage: Energy × 1 (area effect)
• Cost: 1 hardware point
• Best for: Desperation attacks, close-range specialists, mutual destruction

MegaNukes

MegaNukes are larger, more powerful versions of TacNukes with a 20-unit blast radius and 1.5× damage multiplier. They’re the ultimate area denial weapon but share the same risks—you need to be close, and you might hurt yourself. Use them when surrounded or when you’ve cornered an enemy and want to ensure the kill.

• Damage: Energy × 1.5 (area effect)
• Blast radius: 20 units
• Cost: 1 hardware point
• Best for: Large area attacks, ensuring kills, last stands

Probes

Probes aren’t weapons—they’re sensors that reveal enemy information. When you have probes equipped, you can query a target robot’s stats: their remaining damage (health), current energy, shield level, ID, aim direction, and more. This intelligence lets you make smarter decisions: focus fire on wounded enemies, avoid well-shielded ones, or predict where they’re aiming.

• Damage: None (sensor only)
• Cost: 1 hardware point
• Best for: Intelligence gathering, target prioritization, advanced tactics

Probe Modes

When you have probes equipped, write a mode value to query enemy stats:

Game Mechanics

Movement

• Maximum speed: 20 in any direction
• Movement cost: 2 × speed in energy per chronon
• Reversing direction costs double (going from +4 to -4 costs 16 energy)
• Speed persists until changed
• Arena boundaries: 0-300 on both X and Y axes

Weapon Speeds

For leading your shots, you need to know projectile speeds:

Leading Shots

To hit a moving target, use the doppler register with arctan:

1
2
3

doppler -12 arctan aim + aim' sto  # Lead for bullets
10 fire' sto

The formula compensates for target movement based on the weapon’s speed.

Example Robot

Here’s a simple robot that demonstrates the basics:

1
2
3
4
5
6
7
8
9
10
11

# Simple robot that rotates and shoots

Main:
  range 0 > ShootEm if    # If we see a robot, shoot it
  aim 5 + aim' sto        # Otherwise, rotate turret 5 degrees
  Main jump               # Loop forever

ShootEm:
  10 fire' sto            # Fire with 10 energy
  return                  # Return to scanning

This robot continuously rotates its turret. When range returns a non-zero value (meaning there’s a robot in the line of fire), it jumps to ShootEm and fires.

A More Advanced Robot

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# Robot with movement and leading shots

Main:
  5 speedx' sto           # Start moving right

Scan:
  range 0 > Attack if     # Found a target?
  aim 7 + aim' sto        # Rotate turret
  Scan jump

Attack:
  doppler -12 arctan      # Calculate lead angle
  aim + aim' sto          # Adjust aim
  15 fire' sto            # Fire!

  # Dodge after shooting
  speedy chs speedy' sto  # Reverse vertical direction
  Scan jump

This robot moves while scanning, leads its shots using doppler compensation, and reverses direction after each shot to make itself harder to hit.

Tips for Writing Robots

1. Manage your energy: Don’t fire with more energy than you can spare. Running out of energy means you can’t move or shoot.
2. Keep moving: A stationary robot is an easy target. Even simple oscillating movement helps.
3. Lead your shots: Moving targets require aim compensation. The doppler register tells you how much to adjust.
4. Use interrupts: Set up interrupt handlers for collisions and low damage to react quickly to threats.
5. Know your class: A 9-point Mortal robot needs careful tradeoffs between firepower, speed, and survivability.
6. Test against variety: A robot that beats one opponent might lose to another. Test against different strategies.

I compiled this documentation with help from Claude reviewing the RoboWar source code.

Alpine and htmx take different approaches:

• Alpine is for client-side reactivity—state that lives in the browser
• htmx is for server interactions—fetching HTML from your backend

Both are better than Stimulus at what they do. And when you need both approaches? They work together to do a better job than Stimulus.

Let me show you with examples taken from the Stimulus documentation itself.

This is the example from the Stimulus homepage. You type a name, click a button, and see a greeting.

1
2
3
4
5
6

<div data-controller="hello">
  <input data-hello-target="name" type="text">
  <button data-action="click->hello#greet">Greet</button>
  <span data-hello-target="output"></span>
</div>

1
2
3
4
5
6
7
8
9
10

import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  static targets = [ "name", "output" ]

  greet() {
    this.outputTarget.textContent = `Hello, ${this.nameTarget.value}!`
  }
}

To understand what happens when you click the button, you have to:

1. Find the controller name in the HTML
2. Find the corresponding JavaScript file
3. Map the action syntax to a method
4. Understand the all of the naming conventions

Compare that to the Alpine version:

1
2
3
4
5
6

<div x-data="{ name: '' }">
  <input x-model="name" type="text">
  <button>Greet</button>
  <span x-text="name ? `Hello, ${name}!` : ''"></span>
</div>

No separate file. No imports. No target lookups. The behavior is right there in the HTML. I can easily put it directly here in this article:

This is the second example from the Stimulus handbook. It loads HTML from the server and optionally refreshes it on an interval.

1
2
3
4

<div data-controller="content-loader"
     data-content-loader-url-value="/messages.html"
     data-content-loader-refresh-interval-value="5000"></div>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  static values = { url: String, refreshInterval: Number }

  connect() {
    this.load()
    if (this.hasRefreshIntervalValue) {
      this.startRefreshing()
    }
  }

  disconnect() {
    this.stopRefreshing()
  }

  load() {
    fetch(this.urlValue)
      .then(response => response.text())
      .then(html => this.element.innerHTML = html)
  }

  startRefreshing() {
    this.refreshTimer = setInterval(() => {
      this.load()
    }, this.refreshIntervalValue)
  }

  stopRefreshing() {
    if (this.refreshTimer) {
      clearInterval(this.refreshTimer)
    }
  }
}

That’s 30+ lines of JavaScript to periodically fetch some HTML. You have to manage lifecycle hooks, timers, and cleanup.

Compare it to the htmx version:

1
2

<div hx-get="/messages.html" hx-trigger="load, every 5s"></div>

htmx handles the fetch, the interval, and the cleanup automatically.

Want navigation between different content sources?

1
2
3
4
5
6
7
8

<nav>
  <button hx-get="/demos/messages.html" hx-target="#content">Messages</button>
  <button hx-get="/demos/tasks.html" hx-target="#content">Comments</button>
</nav>
<div id="content">
  <p>Click a button to load content</p>
</div>

I can put the above code example directly in this article:

Sometimes you need both client-side state and server interaction. A modal dialog with a form is a classic example: showing/hiding the modal is client-side state, but the form submission goes to the server.

With Stimulus you’d need either one complex controller or two controllers that somehow communicate with each other (which Stimulus isn’t good at). You’d wire up the modal toggle, handle the form submission with fetch, parse the response, update the DOM, and close the modal on success.

I’m not going to code it up because it would be 80+ lines across multiple files and Stimulus sucks.

The Alpine with htmx example is around 15 lines of HTML:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

<div x-data="{ open: false }">
  <button @click="open = true">Subscribe</button>

  <div x-show="open" x-cloak class="modal-backdrop" @click.self="open = false">
    <div class="modal">
      <h2>Subscribe to Updates</h2>
      <form hx-post="/subscribe" hx-target="#result" @htmx:after-request="open = false">
        <input type="email" name="email" placeholder="you@example.com" required>
        <button type="submit">Subscribe</button>
      </form>
      <div id="result"></div>
      <button @click="open = false">Cancel</button>
    </div>
  </div>
</div>

Alpine handles the modal state. htmx handles the form submission. They communicate through the @htmx:after-request event—when htmx finishes, Alpine closes the modal.

No JavaScript files. No lifecycle management. No manual DOM manipulation.

Check it out:

(The form won't actually submit because this is a static blog, but the modal interaction works.)

Stimulus claims to be “a modest JavaScript framework for the HTML you already have.” But look at the examples:

1. The Stimulus HTML is littered with framework-specific attributes that point elsewhere
2. The behavior lives in separate files with their own conventions
3. Simple tasks require a lot of ceremony: controllers, targets, actions, values, and lifecycle hooks

Alpine and htmx actually deliver on the promise:

1. The behavior is visible in the HTML itself
2. You can understand what happens without opening another file
3. Simple tasks are simple

The best part? You don’t have to choose. Alpine handles client-side state. htmx handles server interactions. Use whichever one fits the problem or use them together.

The original plugin used the tubby gem to build HTML. Tubby is a nice little library, but it hasn’t been updated since January 2021 and I didn’t really need it. A heredoc works just as well and removes a dependency.

The original Tubby code:

1
2
3
4
5
6
7
8

Tubby.new do |tag|
  tag.figure(class: 'code-example') do
    tag.figcaption(title, class: 'title')
    tag.aside(@params[:comment]) if @params[:comment]
    tag.div(class: 'overflow') { tag.raw! source }
  end
end.to_s

Replaced with a simple heredoc:

1
2
3
4
5
6
7
8

<<~HTML
  <figure class="code-example">
    #{title_html}
    #{aside_html}
    <div class="overflow">#{source}</div>
  </figure>
HTML

I also discovered a bug in my lexer lookup. The original code used const_get with manual capitalization:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

formatter = Rouge::Formatters::HTMLTable.new(
  Rouge::Formatters::HTML.new,
  table_class: 'code',
  gutter_class: 'gutter',
  code_class: 'source ' + language
)
language = language.capitalize if language == language.downcase
lexer =
  begin
    Rouge::Lexers.const_get(language).new
  rescue NameError
    Rouge::Lexers::Markdown.new
  end

I was using const_get with a fallback which was fine, but Rouge::Lexer.find(language) is a much better approach.

1
2

lexer = Rouge::Lexer.find(language&.downcase) || Rouge::Lexers::PlainText.new

Rouge::Lexer.find handles aliases and returns nil if the language isn’t found, which is cleaner than rescuing a NameError.

The original code always rendered a <figcaption> even when no title was provided. Now, title and aside elements only render when they have content:

1
2
3
4
5
6
7
8
9
10

def title_html
  return '' if @params[:title].to_s.empty?
  %(<figcaption class="title">#{@params[:title]}</figcaption>)
end

def aside_html
  return '' if @params[:comment].to_s.empty?
  %(<aside>#{@params[:comment]}</aside>)
end

Here’s the refactored plugin:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53

# frozen_string_literal: true

require 'rouge'

class CodeBlock < Liquid::Block
  def initialize(_tag_name, params, _tokens)
    super
    @params = parse_params(params)
  end

  def render(_context)
    code = super
    language = @params[:language]

    <<~HTML
      <figure class="code-example">
        #{title_html}
        #{aside_html}
        <div class="overflow">#{highlight(code:, language:)}</div>
      </figure>
    HTML
  end

  private

  def highlight(code:, language:)
    lexer = Rouge::Lexer.find(language&.downcase) || Rouge::Lexers::PlainText.new
    formatter = Rouge::Formatters::HTMLTable.new(
      Rouge::Formatters::HTML.new,
      table_class: 'code',
      gutter_class: 'gutter',
      code_class: "source #{language}"
    )
    formatter.format(lexer.lex(code))
  end

  def title_html
    return '' if @params[:title].to_s.empty?
    %(<figcaption class="title">#{@params[:title]}</figcaption>)
  end

  def aside_html
    return '' if @params[:comment].to_s.empty?
    %(<aside>#{@params[:comment]}</aside>)
  end

  def parse_params(params)
    params.scan(Liquid::TagAttributes).to_h { |k, v| [k.to_sym, v.delete('"')] }
  end
end

Liquid::Template.register_tag('code', CodeBlock)

The changes:

1. Removed the tubby dependency—one less gem to worry about
2. Used Rouge::Lexer.find for better language lookup
3. Extracted highlight, title_html, and aside_html methods for readability
4. Empty elements no longer render
5. Simplified parse_params using Liquid::TagAttributes and .to_h
6. Changed the default language from 'markdown' to 'plaintext'

While I was at it, I noticed that inline code references were inconsistent with the code blocks in my blocks. When I mention Rouge::Lexer.find in a sentence, it should have the same syntax highlighting as it does in a code block—Rouge and Lexer as constants, find as a method name.

So I created a companion plugin for inline code:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

# frozen_string_literal: true

require 'rouge'

class InlineCode < Liquid::Block
  def initialize(_tag_name, params, _tokens)
    super
    @params = parse_params(params)
  end

  def render(_context)
    code = super.strip
    language = @params[:language]
    token = @params[:token]
    if token
      manual(code:, language:, token:)
    else
      auto(code:, language:)
    end
  end

  private

  def parse_params(params)
    params.scan(Liquid::TagAttributes).to_h { |k, v| [k.to_sym, v.delete('"')] }
  end

  def manual(code:, language:, token:)
    %(<code class="highlight #{language}"><span class="#{token}">#{code}</span></code>)
  end

  def auto(code:, language:)
    lexer = Rouge::Lexer.find(language) || Rouge::Lexers::PlainText.new
    formatter = Rouge::Formatters::HTML.new
    highlighted = formatter.format(lexer.lex(code))
    %(<code class="highlight #{language}">#{highlighted}</code>)
  end
end

Liquid::Template.register_tag('ic', InlineCode)

The usage is similar to the code block plugin:

1
2

{％ ic language: "ruby" ％}Rouge::Lexer.find{％ endic ％}

Sometimes Rouge doesn’t have enough context to identify a token correctly. For example, find on its own is identified as a local variable, not a method. The optional token parameter lets you override the styling:

1
2

{％ ic language: "ruby", token: "nf" ％}find{％ endic ％}

The syntax highlighting classes are shared between the block and inline plugins via a Sass mixin, so they stay in sync. Now when I reference a method like parse_params in the copy, it looks the same as it does in a code example.

I like Simulus’s proposition, but I don’t like the implementation. So let’s do it in a Ruby on Rails application with Vue instead (source code).

Even though Vue 3 was released in September 2020, Rails still doesn’t support it as an option for creating new applications, so we’ll have to create the app first and then configure it for Vue.

Next add vue, the vue loader (for webpack).

Now that Vue is installed, it needs some configuration. Edit the webpack configuration file:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

const { environment } = require('@rails/webpacker')
const { DefinePlugin } = require('webpack')
const { VueLoaderPlugin } = require('vue-loader')
const customConfig = {
  resolve: {
    alias: {
      vue: 'vue/dist/vue.esm-bundler.js' // Use the variation that allows Vue to use existing HTML (e.g. Rails views)
    }
  }
}

environment.config.merge(customConfig)

environment.plugins.prepend(
  'Define',
  new DefinePlugin({
    __VUE_OPTIONS_API__: false, // To use the Composition API exclusively (I like it, but this is optional)
    __VUE_PROD_DEVTOOLS__: false // Ensure development code tools stay out of production code
  })
)

environment.plugins.prepend(
  'VueLoaderPlugin',
  new VueLoaderPlugin()
)

environment.loaders.prepend('vue', {
  test: /\.vue$/,
  use: [{ loader: 'vue-loader' }]
})

module.exports = environment

Now that the Vue is configured let’s give it some HTML to work with

and edit the routes file to use it.

1
2
3
4
5
6

Rails.application.routes.draw do
  root 'widgets#index'

  resources :widgets
end

Suppose I want to ensure that people fill out the style name correctly. I could add a Rails validation that the name matches a certain regular expression (and I will later) but that means filling out the form, submitting it, and then discovering a problem. It would be nicer if I got a warning as I was filling the form out. A bit of JavaScript could be nice.

There are a lot of ways to set this up, but since it is a comparison to Stimulus let’s set it up in a Stimulus style. In Stimulus you give an element a specific data-controller attribute and it hooks code to the element. Let’s add a data-component (because Vue uses components) attribute to our HTML and then hook some Vue code to it.

Our Widget views share a common form, so let’s add it to the form partial:

1
2
3
4
5
6

<div data-component="Widget">
  <%= form_with(model: widget) do |form| %>
    ...
  <% end %>
</div>

Create the component:

1
2
3
4
5
6
7
8
9

const Widget = {
  name: 'Widget',
  setup() {
    return {}
  }
}

export default Widget

And add code to hook them together:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

// standard Rails stuff
import Rails from "@rails/ujs"
import Turbolinks from "turbolinks"
import * as ActiveStorage from "@rails/activestorage"
import "channels"

Rails.start()
Turbolinks.start()
ActiveStorage.start()

// Vue stuff here
import { createApp } from 'vue'

import Widget from '../components/Widget'
// I could import more components here

const components = { Widget } // An object to hold components

// Normally this would be done with 'DOMContentLoaded', but Turbolinks breaks that
document.addEventListener("turbolinks:load", () => {
  // Find everything with a data-component
  document.querySelectorAll('[data-component]').forEach((node) => {
    // mount the respective Vue component
    createApp(components[node.dataset.component]).mount(node)
  })
})

The plan is to run a check on a form field when it loses focus (onBlur), so let’s start with that. In our component let’s write a function that takes a parameter and logs it out with console.log.

1
2
3
4
5
6
7
8
9
10
11

const Widget = {
  name: 'Widget',
  setup() {
    const log = (message) => { console.log(message) }

    return { log }
  }
}

export default Widget

Update your HTML to use the new function:

1
2
3
4
5
6
7
8
9
10
11

<div data-component="Widget">
  <%= form_with(model: widget) do |form| %>
    ...
    <div class="field">
      <%= form.label :style %>
      <%= form.text_field :style, "@blur" => "log('it got blurry')" %>
    </div>
    ...
  <% end %>
</div>

If you start the server and start up the page, you should be able to click in the first text field, click out of the text field, and see the message in the browser’s console.

This is interesting, but not terribly useful. Let’s assume that widget styles start with “WX-“ and we want to check that in the component:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

const Widget = {
  name: 'Widget',
  setup() {
    const check = (name) => {
      if (/^WX-.+/.test(name)) {
        console.log('valid')
      } else {
        console.log('invalid')
      }
    }

    return { check }
  }
}

export default Widget

And hook the new code in:

1
2
3
4
5
6
7
8
9
10
11

<div data-component="Widget">
  <%= form_with(model: widget) do |form| %>
    ...
    <div class="field">
      <%= form.label :style %>
      <%= form.text_field :style, "@blur" => "check($event.target.value)" %>
    </div>
    ...
  <% end %>
</div>

When you try out the modified page you should see “valid” and “invalid” when you type different strings into the text field and remove focus.

This is nice, but users aren’t going to look in their web console for messages. Let’s output a message into the HTML. First we’ll create a Vue ref in our Widget:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

import { ref } from 'vue'

const Widget = {
  name: 'Widget',
  setup() {
    var errorMessage = ref(null)

    // ...

    return { errorMessage, check }
  }
}

export default Widget

And add a corresponding div to the HTML:

1
2
3
4
5
6
7
8
9
10
11
12

<div data-component="Widget">
  <%= form_with(model: widget) do |form| %>
    ...
    <div class="field">
      <%= form.label :style %>
      <%= form.text_field :style, "@blur" => "check($event.target.value)" %>
      <div ref="errorMessage" style="color: #C00"></div>
    </div>
    ...
  <% end %>
</div>

Which leads to the final version of the component:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

import { ref } from 'vue'

const Widget = {
  name: 'Widget',
  setup() {
    var errorMessage = ref(null)

    const check = (name) => {
      if (/^WX-.+/.test(name)) {
        errorMessage.value.textContent = ''
      } else {
        errorMessage.value.textContent = 'This style name is incorrect'
      }
    }

    return { errorMessage, check }
  }
}

export default Widget

And here is the complete, final version of the form partial:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

<div data-component="Widget">
  <%= form_with(model: widget) do |form| %>
    <% if widget.errors.any? %>
      <div id="error_explanation">
        <h2><%= pluralize(widget.errors.count, "error") %> prohibited this widget from being saved:</h2>

        <ul>
          <% widget.errors.each do |error| %>
            <li><%= error.full_message %></li>
          <% end %>
        </ul>
      </div>
    <% end %>

    <div class="field">
      <%= form.label :style %>
      <%= form.text_field :style, "@blur" => "check($event.target.value)" %>
      <div ref="errorMessage" style="color: #C00"></div>
    </div>

    <div class="field">
      <%= form.label :color %>
      <%= form.text_field :color %>
    </div>

    <div class="field">
      <%= form.label :runcible %>
      <%= form.check_box :runcible %>
    </div>

    <div class="actions">
      <%= form.submit %>
    </div>
  <% end %>
</div>

Final observations:

• I think this code is quite readable. You can look at the HTML and get a good sense of what the JavaScript will do. You can look at the JavaScript and get a good sense of what will happen in the HTML.
• I don’t have to reason about JavaScript to know what the resulting HTML is going to be.
• This is easy to backtrace. If you “view source” on this in a browser it is finding the corresponding partial in your Rails views and component in your JavaScript should be pretty easy.
• It is easy to see what is being passed to the JavaScript functions.
• I chose a naming scheme and setup that made sense to me, but there are a lot of different approaches that would work.
• Vue is a “progressive” framework. That means that you can add more techniques as needed. If you want to evolve this into a single page application you can. If you want to add child components to this component you can. If you want to start using single file components you can (I like this tutorial: https://dev.to/vannsl/vue3-on-rails-l9d).
• Because the components are just objects with functions, it would be easy to extract this into something reusable. Imagine turning the check function into a host of functions (e.g. matches, presence, numericality) similar to Rails validators that you can import from a useValidation composable.
• I didn’t touch on testing (maybe my next blog post), but Vue has a lot of documentation on testing, and utilities for the major testing frameworks. This example could be tested with Jest and mounting the component with Vue testing utilities. As I stated before, you could extract the code into a useValidation composable and test the functions, which is even more straightforward.

I switched jobs a few months ago. The team I joined is replacing an application that is a mixture of jQuery, Angular, React, Bootstrap, and Foundation. It uses the Rails asset pipeline together with Webpack. It is a mess. The JavaScript feels like a cancer that has spread everywhere.

For the new application we decided to use Stimulus. It is endorsed by the Rails team and its promise to be “a modest JavaScript framework for the HTML you already have” felt like a breath of fresh air.

However, after using Stimulus for a couple of months I realized that it wasn’t for me for a variety of reasons, including:

1. There is nothing in the Stimulus documentation about how to test it. I tried to work out some strategies on my own, but nothing was particularly satisfying.
2. There is not a lot of documentation in general. For example, it took me a fair amount of searching to discover that they use “--” in their naming for subdirectories. I don’t think it is in the documentation still.
3. Putting all of your state in the DOM is tricky. If you have anything that modifies the DOM (for example, we had something that toggled between an “edit” and “view” mode) you could clobber your state; taking state out of the DOM is one of early arguments for Backbone.
4. There is no easy way to coordinate or message between controllers, especially nested ones. One of React’s key features is that components can easily pass information to their child components.
5. Stimulus disconnects functions from their parameters. You call a function and then it has to search for the applicable data- attribute in the DOM.
6. Their naming scheme is cumbersome, e.g. data-controller="using-a--sub-directory" data-target="some--nested--target-has-a.function". Everything is location-in-your-code-file-structure based.
7. It was hard for me to get reusable pieces of code. Because nesting controllers seemed to make things complex, I stopped trying to make them work together and I just started making a controller per page.
8. It doesn’t try to work with the larger JavaScript ecosystem

A lot of my frustrations with Stimulus stem, I think, from my differences from how David Heinemeier Hansson works. I’ve listened to several of his interviews, including recent ones about his Hotwire approach. For example:

1. He doesn’t like JavaScript and tries to avoid it when he can.
2. He has a front-end team who can write custom code for him.
3. He is focused on Basecamp and Hey

In contrast:

1. I don’t love JavaScript, but I can appreciate its usefulness and I try to respect it for what it is.
2. I am a full-stack developer, which means I have to live with the JavaScript I write and I often need to use JavaScript libraries.
3. I work on products that don’t necessarily have the same needs as Basecamp or Hey

About the time I was hitting peak frustration with Stimulus, Vue released version 3. I’ve found that it addresses my frustrations well:

1. There are official testing libraries for Vue and with a lot of documentation.
2. Vue has the most and the most thorough documentation of any JavaScript framework I’ve seen.
3. Vue has several strategies for state management and you don’t have to put state in the DOM.
4. Vue has support for passing data between components as well as support for emitting and listening to events.
5. Vue makes it clear what parameters are being passed to functions.
6. Vue has a lot of naming guidelings, but what you name things is much more flexible.
7. Vue encourages code reuse through “composables” (very much like React’s hooks) and components.
8. Vue tries work with the JavaScript ecosystem.

The part of Vue that I like the best is that it is a “progressive” framework. That is, I can use it for “sprinkles” at one end or a full single page application at the other. I can write HTML first and then use it for “the HTML I already have.”

Here’s how I was able to get it working after a lot of trial and error and painful web searching (seriously, “Less” is a terrible name for a project).

First I started a new rails project.

Next I added the react-rails gem. This could have been done with a --webpack=react on creation, but I like to do things manually when I’m learning and it allowed me to switch to the latest webpacker at the same time.

1
2
3
4
5

...
gem 'webpacker', '~> 5.1', '>= 5.1.1' # <-- updated to latest (as of this writing)
gem 'react-rails', '~> 2.6', '>= 2.6.1' # <-- added
...

I used the setup scripts to configure it for my Rails app.

I added the JavaScript modules that I would need. I didn’t technically need to add webpack, but it was nice to stop some warnings.

Now that everything was installed, I needed to configure everything. I started by writing a configuration file for less-loader.

1
2
3
4
5
6
7
8
9
10
11
12
13
14

const getStyleRule = require('@rails/webpacker/package/utils/get_style_rule')

module.exports = getStyleRule(/\.less$/i, false, [
  {
    loader: 'less-loader',
    options: {
      sourceMap: true,
      lessOptions: {
        javascriptEnabled: true,
      }
    }
  }
])

I updated the webpack environment to use my loader configuration file.

1
2
3
4
5

const { environment } = require('@rails/webpacker')
const less = require('./loaders/less')
environment.loaders.append('style', less)
module.exports = environment

I edited webpacker’s configuration file to reflect these changes.

1
2
3
4
5
6

...
  extensions:
    ...
    - .less
    - .module.less

I edited Babel’s configuration to import the styles from Ant Design.

1
2
3
4
5
6
7
8
9
10
11
12

...
  return {
    ...
    plugins: [
      ...
      ],
      [
        "import", { "libraryName": "antd", "libraryDirectory": "es", "style": true }
      ]
    ].filter(Boolean)
  ...

I decided to create a component to ensure that everything was working properly.

I based it on the first examples from the Ant Design documents.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

import React from "react"
import { Button, DatePicker, Switch, TimePicker, version } from "antd";

const ComponentTest = (props) => {
  return (
    <React.Fragment>
      <h1>Ant Design version: {version}</h1>
      <div>
        <DatePicker />
        <Button type="primary" style={{ marginLeft: 8 }}>
          Primary Button
        </Button>
      </div>
      <div style={{ marginTop: 16 }}>
        <TimePicker size="large" />
        <Switch checkedChildren={ props.checked } unCheckedChildren={ props.unchecked } style={{ marginLeft: 8 }} />
      </div>
    </React.Fragment>
  )
}

export default ComponentTest

I created a view to try it out.

I made that view the default.

1
2
3
4

Rails.application.routes.draw do
  root 'welcome#index'
end

I edited the application layout to generate a stylesheet with stylesheet_pack_tag. This is for the styles from my JavaScript.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

<!DOCTYPE html>
<html>
  <head>
    <title>Nessman</title>
    <%= csrf_meta_tags %>
    <%= csp_meta_tag %>
    <%= stylesheet_pack_tag 'application', media: 'all', 'data-turbolinks-track': 'reload' %>
    <%= javascript_pack_tag 'application', 'data-turbolinks-track': 'reload' %>
    <%= stylesheet_link_tag 'application', media: 'all', 'data-turbolinks-track': 'reload' %>
  </head>

  <body>
    <%= yield %>
  </body>
</html>

I edited the view to render my new component.

1
2
3
4

<div style="width: 480px; margin: 10px auto;">
  <%= react_component('ComponentTest', { checked: 1, unchecked: 0 }) %>
</div>

It worked well, but I wanted to test one last thing. I edited my Less loader to modify a variable in the design, changing the primary color to a bright red. Any of the default variables can be changed.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

const getStyleRule = require('@rails/webpacker/package/utils/get_style_rule')
const overrides = { '@primary-color': '#F00' }

module.exports = getStyleRule(/\.less$/i, false, [
  {
    loader: 'less-loader',
    options: {
      sourceMap: true,
      lessOptions: {
        javascriptEnabled: true,
        modifyVars: overrides
      }
    }
  }
])

I put a working demo up on Heroku.

First, I want to thank Cameron Dutro for the scuttle.io website and the Arel Helpers gem. We decided to just write our own helpers rather than add a gem dependency to our codebase, but the gem was still helpful. I’m using this method a lot.

1
2
3
4
5
6
7
8
9
10

class ApplicationRecord < ActiveRecord::Base
  primary_abstract_class

  def self.[](column = nil)
    return arel_table if column.nil?

    arel_table[column]
  end
end

We have an extensive GraphQL API and these are the query parts I had to figure out.

1
2
3
4
5
6
7
8
9

  Foo.where(subquery.arel.exists)
  # example:
  Supplier.where(
    Product.select(:id).where(
      Product[:supplier_id].eq(Supplier[:id]).and(Product[:price].lt(20))
    ).arel.exists
  )
  # SELECT * FROM suppliers WHERE EXISTS(SELECT id FROM products WHERE products.supplier_id = suppliers.id AND products.price < 20)

1
2
3
4
5
6
7
8
9

  Foo.where(subquery.arel.exists.not)
  # example:
  Supplier.where(
    Product.select(:id).where(
      Product[:supplier_id].eq(Supplier[:id]).and(Product[:price].lt(20))
    ).arel.exists.not
  )
  # SELECT * FROM suppliers WHERE NOT EXISTS(SELECT id FROM products WHERE products.supplier_id = suppliers.id AND products.price < 20)

1
2
3
4
5

  Foo.where(bar: ['baz', 'qux'])
  # example:
  Client.where(zipcode: ['84720', '84113'])
  # SELECT * FROM clients WHERE zipcode IN ('84720', '84113')

1
2
3
4
5

  Foo.where.not(bar: ['baz', 'qux'])
  # example:
  Client.where.not(zipcode: ['84720', '84113'])
  # SELECT * FROM clients WHERE zipcode NOT IN ('84720', '84113')

1
2
3
4
5
6

  Foo.where(Foo[:bar].matches(baz))
  # example:
  search_string = 'Jo'
  Client.where(Client[:first_name].matches(search_string + '%'))
  # SELECT * FROM clients WHERE first_name LIKE 'Jo%'

1
2
3
4
5

  Foo.where(Foo[:bar].does_not_match(pattern))
  # example:
  Client.where(Client[:email].does_not_match('%@example.com'))
  # SELECT * FROM clients WHERE email NOT LIKE '%@example.com'

1
2
3
4
5

  Foo.where(Foo[:bar].matches(pattern, nil, true))
  # example:
  Client.where(Client[:name].matches('%smith%', nil, true))
  # SELECT * FROM clients WHERE name ILIKE '%smith%' (PostgreSQL)

1
2
3
4
5

  Foo.where(Foo[:bar].eq(nil))
  # example:
  Client.where(Client[:address].eq(nil))
  # SELECT * FROM clients WHERE address IS NULL

1
2
3
4
5

  Foo.where(Foo[:bar].not_eq(nil))
  # example:
  Client.where.not(Client[:address].eq(nil))
  # SELECT * FROM clients WHERE address IS NOT NULL

1
2
3

  Client.where(created_at: Date.yesterday..Date.tomorrow)
  # SELECT * FROM clients WHERE created_at BETWEEN '2020-01-07' AND '2020-01-09'

1
2
3
4
5

  Foo.where(Foo[:bar].eq('a').or(Foo[:baz].eq('b')))
  # example:
  Client.where(Client[:status].eq('active').or(Client[:vip].eq(true)))
  # SELECT * FROM clients WHERE status = 'active' OR vip = true

1
2
3
4
5
6
7
8

  Foo.where(Foo[:bar].gt(value))   # >
  Foo.where(Foo[:bar].gteq(value)) # >=
  Foo.where(Foo[:bar].lt(value))   # <
  Foo.where(Foo[:bar].lteq(value)) # <=
  # example:
  Product.where(Product[:price].gteq(100).and(Product[:price].lteq(500)))
  # SELECT * FROM products WHERE price >= 100 AND price <= 500

1
2
3
4
5
6

  Foo.order(Foo[:bar].asc)
  Foo.order(Foo[:bar].desc)
  # example:
  Client.order(Client[:created_at].desc, Client[:name].asc)
  # SELECT * FROM clients ORDER BY created_at DESC, name ASC

1
2
3
4
5
6
7
8
9
10
11

  Foo.joins(:bars) # simple association
  # custom join condition:
  Foo.joins(Foo.arel_table.join(Bar.arel_table).on(
    Foo[:bar_id].eq(Bar[:id])
  ).join_sources)
  # example:
  Client.joins(Client.arel_table.join(Order.arel_table).on(
    Client[:id].eq(Order[:client_id]).and(Order[:status].eq('active'))
  ).join_sources)
  # SELECT * FROM clients INNER JOIN orders ON clients.id = orders.client_id AND orders.status = 'active'

1
2
3
4
5
6
7
8
9
10
11

  Foo.left_joins(:bars) # simple association
  # custom join condition:
  Foo.joins(Foo.arel_table.join(Bar.arel_table, Arel::Nodes::OuterJoin).on(
    Foo[:bar_id].eq(Bar[:id])
  ).join_sources)
  # example:
  Client.joins(Client.arel_table.join(Order.arel_table, Arel::Nodes::OuterJoin).on(
    Client[:id].eq(Order[:client_id])
  ).join_sources).where(Order[:id].eq(nil))
  # SELECT * FROM clients LEFT OUTER JOIN orders ON clients.id = orders.client_id WHERE orders.id IS NULL

Thanks for reading!