Hotwire Marten: Less JavaScript, More Interactivity

Recently I came across a statement that a developer went back to Ruby on Rails from the Crystal ecosystem. The reason: missing Hotwire support. And honestly, I get it!

I'm a huge fan of the Hotwire utilities - you can write normal server code without too many frontend dependencies. In fact, Turbo brings SPA feeling out of the box!

I've been developing apps with Marten for a while. And all of them have had Hotwire built in. I've built a turbo extension for it quite a while ago, but the experience was never the same as with Rails. So I very much understand the statement to go back to Rails. Everything works out of the box!

Well, how should anyone know that there's already effort to bring better Hotwire support to the Crystal ecosystem, if nobody writes about it? So here it is! In this post I'll walk you through building a task app with Marten using the full Hotwire stack — Turbo Frames, Turbo Streams, and Stimulus. And beyond what's already available in marten-turbo, I'm currently working on importmap and Stimulus integration support, which is coming along nicely. I want to show you where things stand today.

Initializing the task app

Let's start by setting up a normal Marten project:

marten new project turbo_tasks

Hotwire integration? None 😩 But don't worry — it's relatively simple to add, and once it's set up, the tooling will feel quite natural.

Let's add marten-turbo and marten-stimulus. The latter will pull in marten-importmap as a transitive dependency:

dependencies:
  marten_stimulus:
    github: treagod/marten-stimulus
  marten_turbo:
    github: treagod/marten-turbo

Run shards install and we're halfway there.

We need to require the new dependencies and register the Marten apps:

# src/project.cr
require "marten_stimulus"
require "marten_turbo"

# src/cli.cr
require "marten/cli"
require "marten_stimulus/cli"  # also loads marten_importmap/cli

config.installed_apps = [
  MartenImportmap::App,
  MartenStimulus::App,
  MartenTurbo::App,
]

And just like that, Marten has Hotwire support! It recognizes Turbo tags, provides Turbo helpers, and adds CLI commands for importmap and Stimulus.

1. Initialize Importmap

Run:

marten importmap init

This generates:

config/initializers/importmap.cr
config/initializers/importmap_pins.cr
src/assets/application.js

2. Pin Hotwire dependencies

Now pin the required packages:

marten importmap pin @hotwired/turbo
marten importmap pin @hotwired/stimulus

3. Boot Turbo and Stimulus

Update src/assets/application.js:

import "@hotwired/turbo"
import { Application } from "@hotwired/stimulus"
import { eagerLoadControllersFrom } from "stimulus-loading"

const Stimulus = Application.start()
eagerLoadControllersFrom("controllers", Stimulus)

The stimulus-loading import is pinned automatically by MartenStimulus::App — no manual setup needed. It reads your importmap at runtime and registers any controllers it finds under the controllers/ prefix.

You'll also need to tell the importmap where your controllers live. In config/initializers/importmap.cr:

Marten.configure do |config|
  config.importmap.draw do
    pin "application", "application.js"
    # Add this line
    pin_all_from "src/assets/controllers", under: "controllers"
  end
end

Finally, add {% importmap %} to the <head> section of your base template. This renders the importmap JSON and the necessary preloads.

With that, the boring part is done. Let's build something.

Task App

Let's build something really innovative: a Task App. An app where you can create a task and mark it as complete once done. Never seen that before 🤞.

Well it's small enough to showcase the basics of this setup.

We'll create a task model, let Marten generate the migrations and create a turbo-augmented CRUD interface.

The model is kept fairly slim in order to not overload this post:

class Task < Marten::Model
  field :id, :big_int, primary_key: true, auto: true
  field :title, :string, max_size: 255
  field :completed, :bool, default: false
end

And run

turbo_tasks$ marten genmigrations
Generating migrations for app 'main':
  › Creating [src/migrations/202604270947501_create_main_task_table.cr]... DONE
      ○ Create main_task table
turbo_tasks$ # Migrate
turbo_tasks$ marten migrate
Running migrations:
  › Applying main_202604270947501_create_main_task_table... DONE

Create src/handlers/tasks/list_handler.cr and src/templates/tasks/list.html:

class Tasks::ListHandler < Marten::Handlers::RecordList
  model ::Task
  template_name "tasks/list.html"
end

{% extend "base.html" %}

{% block title %}Tasks{% endblock %}

{% block content %}
  <h1>Tasks</h1>
  <ul>
    {% for task in records %}
      <li>{{ task.title }}</li>
    {% endfor %}
  </ul>
{% endblock %}

Some more tweaking:

path "/", Tasks::ListHandler, name: "home" to your config/routes.cr
Add {% importmap %} right before </head> inside src/templates/base.html
spin up the server with marten s, and navigate to http://127.0.0.1:8000/.

Nothing fancy yet — just a list of zero tasks. But open your dev-tools and check the network tab: Turbo and Stimulus are already loaded without touching any further JavaScript beyond the initialization 😮‍💨.

From here on, we'll keep the setup intentionally small so the Turbo behavior stays visible.

Turbo enters the room

Let's add some basic Turbo functionality to see if it really works. We need a create handler, a schema, and a template:

class Tasks::CreateHandler < Marten::Handlers::RecordCreate
  model ::Task
  template_name "tasks/create.html"
  schema TaskSchema
  success_route_name "home"
end

class TaskSchema < Marten::Schema
  field :title, :string
  field :completed, :bool, required: false
end

{% extend "base.html" %}
{% block title %}Create Task{% endblock %}
{% block content %}
  <h1>Create Task</h1>
  <turbo-frame id="new_task">
    <form action="{% url 'tasks_create' %}" method="post">
      {% csrf_input %}
      <label for="{{ schema.title.id }}">Title:</label>
      <input type="text" id="{{ schema.title.id }}" name="{{ schema.title.id }}" required>
      <button type="submit">Create</button>
    </form>
  </turbo-frame>
{% endblock %}

Add path "/tasks/create", Tasks::CreateHandler, name: "tasks_create" to your config/routes.cr.

Now update the list template to have a link to the new create page:

{% extend "base.html" %}

{% block title %}Tasks{% endblock %}

{% block content %}
  <h1>Tasks</h1>
  <a href="{% url 'tasks_create' %}" data-turbo-frame="new_task">Create task</a>
  <turbo-frame id="new_task"></turbo-frame>
  <ul>
    {% for task in records %}
      <li>{{ task.title }}</li>
    {% else %}
      <li>No tasks found. <a href="{% url 'tasks_create' %}">Create your first one</a></li>
    {% endfor %}
  </ul>
{% endblock %}

Notice what's happening here: the "Create task" link has data-turbo-frame="new_task", which tells Turbo to fetch the create page and only extract the matching <turbo-frame id="new_task"> from the response. It swaps that frame into the empty <turbo-frame> on the list page — no full page reload, no custom JavaScript. Nothing new to seasoned Hotwire devs, but it's still worth mentioning!

Click the link and the form just appears inline. Submit it and you're back to the list with your new task. That's the SPA feeling Turbo gives you for free.

That's enough for the first part. In the next one, I'll go further into Turbo and how to use it to not replace the whole page of the task list when updating a task!

推荐订阅源

DEV Community