Stimulus + TypeScript: A Love Story
“We resisted TypeScript in our Stimulus controllers—until it saved us from 50 runtime bugs in a week.”
Stimulus is brilliant for sprinkling interactivity without a JavaScript framework. But as our app grew, we found ourselves:
-
Guessing what
this.targetsincluded -
Debugging
undefinedmethod calls - Wasting hours on typos in event names
Then we added TypeScript—and everything changed.
Here’s how to make Stimulus and TypeScript work together like soulmates, not forced partners.
1. Why TypeScript? The Pain Points It Fixes
Problem 1: Magic Strings Everywhere
Before:
// What targets exist? Guess and check!
this.targets.find("submitButton") // Error? Maybe it's "submit-btn"?
After:
// Autocomplete and type-checking
this.targets.find("submitButton") // ✅ Compiler error if misspelled
Problem 2: Untyped Event Handlers
Before:
// Hope the event has `detail`!
handleSubmit(event) {
const data = event.detail.user // 💥 Runtime error if undefined
}
After:
interface CustomEventDetail {
user: { id: string }
}
handleSubmit(event: CustomEvent<CustomEventDetail>) {
const data = event.detail.user // ✅ Type-safe
}
2. The Setup (It’s Easier Than You Think)
Step 1: Install Dependencies
yarn add --dev typescript @types/stimulus @hotwired/stimulus
Step 2: Configure tsconfig.json
{
"compilerOptions": {
"target": "ES6",
"module": "ESNext",
"strict": true,
"moduleResolution": "node",
"esModuleInterop": true
}
}
Step 3: Write Typed Controllers
// app/javascript/controllers/search_controller.ts
import { Controller } from "@hotwired/stimulus"
export default class extends Controller {
static targets = ["input", "results"]
declare readonly inputTarget: HTMLInputElement
declare readonly resultsTarget: HTMLElement
search() {
// `this.inputTarget` is now typed as HTMLInputElement!
fetch(`/search?q=${this.inputTarget.value}`)
.then(r => r.json())
.then(data => {
this.resultsTarget.innerHTML = data.html
})
}
}
Key Wins:
-
No more
undefinedtarget errors - Autocomplete for DOM methods
- Compiler checks for event payloads
3. Advanced Patterns We Love
1. Typed Action Params
// In controller:
toggle({ params }: { params: { activeClass: string } }) {
this.element.classList.toggle(params.activeClass)
}
<!-- In HTML: -->
<button data-action="click->menu#toggle"
data-menu-active-class-param="is-open">
Toggle
</button>
2. Shared Types Across Frontend/Backend
// shared/types.ts
export interface User {
id: string
name: string
}
// In controller:
fetchUser(): Promise<User> {
return fetch("/current_user").then(r => r.json())
}
3. Type-Safe Global Events
// Custom event type
type CartUpdatedEvent = CustomEvent<{ items: number }>
// Dispatch with type safety
this.dispatch("cart:updated", { detail: { items: 3 } })
// Listen with type safety
window.addEventListener("cart:updated", (e: CartUpdatedEvent) => {
console.log(e.detail.items) // ✅ Number
})
4. The Tradeoffs
⚠️ Slightly slower initial setup
⚠️ Build step required (but Vite makes this painless)
⚠️ Team learning curve if new to TypeScript
But the payoff:
- 50% fewer runtime errors in our Stimulus code
- Faster onboarding (types document behavior)
- Confident refactors
5. Gradual Adoption Path
-
Start with one controller (
form_controller.ts) - Add types for new controllers only
- Convert old controllers as you touch them
“But We’re a Small Team!”
We were too. Start small:
- Add TypeScript to one controller
- Measure time saved on debugging
- Let the team lobby for more
Already using Stimulus + TypeScript? Share your pro tips below!
