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.crconfig/initializers/importmap_pins.crsrc/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 yourconfig/routes.cr - Add
{% importmap %}right before</head>insidesrc/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!
