rails-8-setup

---
name: rails-8-setup
description: Creates new Rails 8.1+ applications with full Claude Code integration. Includes Tidewave MCP for runtime Rails integration, Hotwire Club MCP for Hotwire knowledge, and Chrome DevTools for browser automation. Use when asked to "create a new Rails app", "set up a Rails project", or "scaffold a new Rails application".
license: MIT
---

# Rails 8.1+ Project Setup Skill

This skill creates fully configured Rails 8.1+ applications with modern tooling and comprehensive Claude Code integration.

## Quick Start

The setup script can be run directly:

```bash
./scripts/setup.sh my_app_name
```

Or interactively (will prompt for app name):

```bash
./scripts/setup.sh
```

## What Gets Installed

### Core Stack

| Component | Technology |
|-----------|------------|
| Ruby | 3.3.x or 3.4.x |
| Rails | 8.1+ |
| Database | PostgreSQL |
| Testing | Minitest |
| Frontend | Hotwire (Turbo + Stimulus), Tailwind CSS, Importmaps |
| Background Jobs | Solid Queue |
| Caching | Solid Cache |
| WebSockets | Solid Cable |
| Deployment | Kamal |

### MCP Servers (Project-level)

| Server | Purpose | Requirement |
|--------|---------|-------------|
| Tidewave | Runtime Rails integration | Rails server running |
| Hotwire Club | Hotwire/Turbo/Stimulus knowledge | Always available |

### MCP Servers (Plugin-level)

| Server | Purpose |
|--------|---------|
| Chrome DevTools | Browser automation and debugging |
| Context7 | Documentation lookup |

## Browser Automation Guidelines

When working with Rails applications that have Tidewave running:

### Use Tidewave for:
- Running Ruby code (`project_eval`)
- Database queries (`execute_sql_query`)
- Checking logs (`get_logs`)
- Finding source locations (`get_source_location`)
- Getting documentation (`get_docs`)

### Use Chrome DevTools for:
- Taking screenshots
- Performance profiling
- Console error checking
- Network request analysis
- Visual UI testing
- Core Web Vitals analysis

**Do NOT use Chrome DevTools for tasks that Tidewave can accomplish directly.**

## Prerequisites

1. **Ruby 3.3+** installed via rbenv, rvm, or asdf
2. **Rails 8.1+**: `gem install rails`
3. **PostgreSQL** installed and running
4. **Claude Code** with this plugin installed

## Files Created

```
my_app/
├── .claude/
│   ├── settings.json       # Shared settings (commit this)
│   └── settings.local.json # Local overrides (gitignored)
├── .mcp.json               # MCP server configuration
├── CLAUDE_TOOLS.md         # Comprehensive documentation
└── ... (standard Rails 8.1+ app)
```

## Post-Setup Workflow

1. Start the Rails server:
   ```bash
   cd my_app && bin/rails server
   ```

2. Open Claude Code in another terminal:
   ```bash
   cd my_app && claude
   ```

3. Start building with natural language:
   - "What models does this app have?"
   - "Show me the routes"
   - "Create a User model with email and name"

## Notes

- Tidewave MCP only works when the Rails server is running on port 3000
- Hotwire Club MCP works independently with its built-in SQLite database
- Chrome DevTools is provided by the plugin (not project-level)
- The setup auto-configures permissions for fast development (no prompts)