"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 whatthis.targetsincluded
Debuggingundefinedmethod 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 moreundefinedtarget 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!
SOCIAL SHARE CARD GENERATOR