Skip to content

About

Comprehensive Claude Code plugin for Hotwire and Hotwire Native development

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Hotwire Toolkit

A comprehensive Claude Code plugin for Hotwire and Hotwire Native development. Build modern web applications with Turbo and Stimulus, and wrap them in native iOS/Android apps with Hotwire Native.

Features

🛠️ Commands

Execute common Hotwire development tasks:

  • /hotwire:init-turbo [rails|node|standalone] - Initialize a new Hotwire web project
  • /hotwire:init-native [ios|android|both] - Set up Hotwire Native for mobile
  • /hotwire:add-frame [file] [frame-name] [lazy|eager] - Add Turbo Frame to existing page
  • /hotwire:create-bridge [name] [ios|android|both] - Create Bridge Component for web-native communication

🤖 Agents

Specialized agents for analysis and conversion:

  • turbo-analyzer - Analyzes your codebase for Turbo optimization opportunities

    • Identifies full page reloads that should be Frames
    • Finds missing Turbo Streams for real-time updates
    • Suggests Stimulus controller opportunities
    • Provides prioritized optimization plan
  • native-converter - Helps convert web features to native

    • Identifies features that benefit from native implementation
    • Generates complete Bridge Component code (web + iOS + Android)
    • Provides testing instructions
    • Shows platform-specific considerations

📚 Skills

Expert knowledge automatically injected when you ask relevant questions:

  • hotwire-fundamentals - Core Hotwire, Turbo, and Stimulus concepts

    • Turbo Drive, Frames, and Streams
    • Stimulus controllers, targets, values, and actions
    • How they work together
    • Decision tree for when to use what
  • turbo-stimulus - Advanced patterns and best practices

    • Nested frames and pagination
    • Optimistic UI updates
    • Custom Turbo Stream actions
    • Stimulus outlets and composition
    • Debouncing and form validation
    • Performance optimization
  • hotwire-native - Mobile app development with iOS/Android

    • Path Configuration for URL routing
    • Bridge Components for native features
    • Native Screens when needed
    • Complete setup guides for iOS and Android
    • Common patterns and debugging

Installation

From GitHub

/plugin install github:yourusername/hotwire-toolkit

From Marketplace

/plugin marketplace add anthropics/claude-code
/plugin install hotwire-toolkit

Quick Start

Starting a New Hotwire Web Project

Rails:

/hotwire:init-turbo rails

Node/Express:

/hotwire:init-turbo node

Standalone HTML:

/hotwire:init-turbo standalone

Adding Turbo Frames

/hotwire:add-frame app/views/posts/show.html.erb comments-section lazy

This adds a lazy-loaded Turbo Frame to the specified file.

Analyzing Existing Code

"Analyze my app for Turbo optimization opportunities"

The turbo-analyzer agent will:

  1. Explore your codebase
  2. Identify optimization opportunities
  3. Provide prioritized recommendations
  4. Show before/after code examples

Adding Mobile Apps

iOS:

/hotwire:init-native ios

Android:

/hotwire:init-native android

Both:

/hotwire:init-native both

Creating Bridge Components

/hotwire:create-bridge camera both "Take photos and upload to posts"

Generates complete code for:

  • Stimulus controller (web)
  • Swift component (iOS)
  • Kotlin component (Android)
  • HTML usage example

Usage Examples

Example 1: Converting Full Page Reloads to Turbo Frames

Ask:

"I have a comments section that reloads the entire page when submitting.
How do I convert it to use Turbo Frames?"

Claude (with hotwire-fundamentals skill):

  • Explains Turbo Frames concept
  • Shows how to wrap the comments section
  • Demonstrates server-side response
  • Provides complete working example

Example 2: Adding Native Camera

Ask:

"Create a bridge component for photo upload using native camera"

Claude (with native-converter agent):

  • Generates Stimulus controller
  • Creates iOS Swift component
  • Creates Android Kotlin component
  • Shows HTML integration
  • Explains permission setup
  • Provides testing guide

Example 3: Optimistic UI

Ask:

"How do I make like buttons update instantly, even before server responds?"

Claude (with turbo-stimulus skill):

  • Explains optimistic UI pattern
  • Shows Stimulus controller with rollback
  • Demonstrates error handling
  • Provides accessibility considerations

Skills Auto-Triggering

Skills automatically activate when you ask related questions:

hotwire-fundamentals triggers on:

  • "what is turbo"
  • "how does stimulus work"
  • "turbo frames vs turbo streams"
  • "hotwire getting started"

turbo-stimulus triggers on:

  • "advanced turbo patterns"
  • "stimulus outlets"
  • "debouncing search"
  • "form validation with stimulus"
  • "optimistic UI"

hotwire-native triggers on:

  • "hotwire native setup"
  • "path configuration"
  • "bridge components"
  • "ios integration"
  • "android integration"

Just ask naturally - the relevant skill will be automatically loaded!

Project Structure

hotwire-toolkit/
├── .claude-plugin/
│   └── plugin.json              # Plugin metadata
├── commands/
│   ├── init-turbo.md            # Initialize Hotwire web project
│   ├── init-native.md           # Initialize mobile apps
│   ├── add-frame.md             # Add Turbo Frames
│   └── create-bridge.md         # Create Bridge Components
├── agents/
│   ├── turbo-analyzer.md        # Analyze for optimization
│   └── native-converter.md      # Convert features to native
├── skills/
│   ├── hotwire-fundamentals/
│   │   └── SKILL.md             # Core Hotwire concepts
│   ├── turbo-stimulus/
│   │   └── SKILL.md             # Advanced patterns
│   └── hotwire-native/
│       └── SKILL.md             # Mobile development
├── templates/                   # Code templates
└── README.md                    # This file

Common Workflows

1. Starting from Scratch

# Initialize web app
/hotwire:init-turbo rails

# Build features
# (Ask questions, skills guide you)

# Optimize
"Analyze my app for Turbo opportunities"

# Add mobile apps
/hotwire:init-native both

# Add native features
/hotwire:create-bridge haptics both

2. Enhancing Existing App

# Analyze first
"Analyze my app for Hotwire optimization opportunities"

# Implement suggestions
/hotwire:add-frame app/views/posts/index.html.erb posts-list

# Gradually add frames/streams
# ...

# When ready for mobile
/hotwire:init-native ios

3. Mobile-First

# Start with web
/hotwire:init-turbo rails

# Immediately set up mobile
/hotwire:init-native both

# Build features web-first, test on mobile
# Add native enhancements as needed
/hotwire:create-bridge camera both

Best Practices

  1. Start Web-First: Build your app with Hotwire web, then wrap in native
  2. Use Skills: Ask questions to get expert guidance
  3. Analyze Often: Run turbo-analyzer regularly to find optimization opportunities
  4. Progressive Enhancement: Add native features only where they add value
  5. Test on Devices: Always test mobile apps on real devices, not just simulators

Requirements

Web Development

  • Rails 7+ (for Rails projects) or Node.js 18+
  • Modern browser with JavaScript enabled

iOS Development

  • Xcode 14+
  • iOS 14+ target
  • Swift 5.7+
  • CocoaPods or Swift Package Manager

Android Development

  • Android Studio Arctic Fox+
  • Minimum SDK: API 26 (Android 8.0)
  • Kotlin 1.8+
  • Gradle 7.0+

Troubleshooting

"Frame not found" errors

Problem: Target page doesn't have matching turbo-frame.

Solution:

# In controller
if turbo_frame_request?
  render partial: "posts/post_frame"
else
  render :show
end

Mobile app can't connect to dev server

iOS Simulator:

  • Use http://localhost:3000
  • Check Info.plist allows HTTP for localhost

Android Emulator:

  • Use http://10.0.2.2:3000 (not localhost)
  • Check network_security_config.xml allows cleartext

Physical Devices:

  • Use machine's IP: http://192.168.1.XXX:3000
  • Ensure same WiFi network
  • Start Rails with: rails server -b 0.0.0.0

Bridge component not working

Check:

  1. Component registered in native code?
  2. Component names match (web/native)?
  3. Bridge available? (Test with isNativeApp check)
  4. Web fallback working?

Debug:

// Enable logging
connect() {
  console.log("Bridge component connected")
}

send(event, data, callback) {
  console.log("Sending:", event, data)
  super.send(event, data, callback)
}

Resources

Contributing

Contributions welcome! Please submit issues and pull requests to the GitHub repository.

License

MIT License - See LICENSE file for details.

Support

Version History

1.0.0 (Initial Release)

  • Commands: init-turbo, init-native, add-frame, create-bridge
  • Agents: turbo-analyzer, native-converter
  • Skills: hotwire-fundamentals, turbo-stimulus, hotwire-native
  • Complete iOS and Android setup guides
  • Bridge component templates
  • Optimization patterns

Built with ❤️ for the Hotwire community. Happy building!

About

Comprehensive Claude Code plugin for Hotwire and Hotwire Native development

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors